MoFox 桥接适配器 fuilyha56-wq/dsh-for-mofox-ada

DSH Adapter

dshfind

dsh_adapter 让 Neo-MoFox 调用和管理本机 DeepSeek Harness。插件不会复刻 DSH 内部能力，而是完整保留 DSH 官方边界：任意一元 RPC、同源 HTTP、CLI 参数、 profile、长期进程、下行事件和 DSH_HOME 数据。

当前发布版本：1.0.1。

双版本协议支持

适配器内置两代 DSH Web 协议并自动探测（bridge.protocol_mode = "auto"）：

| | legacy（0.1.0-rc.x） | modern（0.1.2-alpha/rc） |
| RPC 路由 | POST /api/session.list（点分） | POST /api/session/list（斜杠） |
| payload | 扁平业务参数 | {"args": {...}} 具名参数包装 |
| 事件流 | /api/events.mux 与 /api/events.host | /api/remote.mux（$events 逻辑流） |
| 交互回传 | POST /api/respond | POST /api/$events/result |
| 认证 | 默认无 | 进程 token（?token= 换 dsh-auth Cookie） |

已实测互通版本：0.1.0-rc.6、0.1.2-alpha.2、0.1.2-alpha.5、0.1.2-rc.1 （npm 上不存在 0.1.2-alpha.1，alpha 系列自 alpha.2 起发布，协议同源）。
modern 服务需在 bridge.web_token 填入 dsh web 输出 URL 中 ?token= 的值；若由适配器自动启动 Web，token 会从进程输出中自动提取。

安装

仓库根目录提供 DSH bundle，可先将其登记到 DSH Web profile：

dsh plugin --profile web add github:fuilyha56-wq/dsh-for-mofox-ada

本地开发或已克隆仓库时：

dsh plugin --profile web add .

该 bundle 的作用是让 DSH profile 记录此集成包；它不在 DSH 的 Node/Cordis 进程中执行 Neo-MoFox 的 Python 代码。完整桥接运行时仍必须作为 Neo-MoFox 插件部署：将本目录放入 Neo-MoFox 的 plugins/，重启或重新加载 Neo-MoFox，然后确认 dsh_adapter:adapter:dsh_adapter 已注册。DSH Web 与 Neo-MoFox 可以运行在同一台主机，默认通过 http://127.0.0.1:18948 通信。

未发布到 npm 前，建议固定可信提交安装，例如：

dsh plugin --profile web add github:fuilyha56-wq/dsh-for-mofox-ada#COMMIT_SHA

DSH 使用 pnpm 安装 git 依赖；若它提示需要在 profile 的 pnpm-workspace.yaml 中授权 allowBuilds，仅在审阅并信任该固定提交后再授予权限。本包没有构建步骤或安装脚本。

组件

| 签名 | 用途 |
| dsh_adapter:service:dsh_adapter | 供其他插件调用全部桥接操作 |
| dsh_adapter:command:dsh | Owner 级 /dsh 管理命令 |
| dsh_adapter:adapter:dsh_adapter | 将每个 DSH Web session 映射为 Neo-MoFox 私聊流 |
| dsh_adapter:router:dsh_adapter | /api/dsh-adapter HTTP API |
| dsh_adapter:tool:dsh_query | LLM 只读查询 Tool |
| dsh_adapter:action:dsh_headless | LLM 委派任务给 DSH headless Agent |
| dsh_adapter:action:dsh_model_switch | LLM 按实时目录切换 DSH 会话模型 |
| dsh_adapter:action:dsh_preset_switch | LLM 切换空白 DSH 会话的 Agent preset 模式 |
| dsh_adapter:action:dsh_operate | LLM 完整 DSH 操作 Action |
| dsh_adapter:action:dsh_respond | LLM 在当前 DSH 私聊流中结构化回答问题或审批 |

启动与配置

当前机器已经全局安装 @deepseek-ai/dsh。默认配置使用 dsh 命令和 ~/.dsh，自动探测或启动 http://127.0.0.1:18948 的 Web profile。

Neo-MoFox 首次加载插件时会生成：

config/plugins/dsh_adapter/config.toml

完整配置项（含默认值）：

[bridge]
enabled = true # 是否启用 DSH 桥接
dsh_command = "dsh" # DSH 可执行命令或绝对路径
dsh_home = "~/.dsh" # DSH_HOME 数据目录
default_workspace = "." # DSH 默认工作目录
web_base_url = "http://127.0.0.1:18948" # DSH Web 根地址
protocol_mode = "auto" # 协议代际：auto / legacy / modern
web_token = "" # modern token（自动启动时自动提取）toml
adopt_external_web = true # 发现已运行 DSH Web 时是否接管
attach_manage_lifecycle = true # 接管进程的默认生命周期策略
auto_start_web = true # 探测失败时是否自动启动 Web
web_start_timeout_seconds = 30.0 # 等待 Web 就绪秒数
start_event_streams = true # 是否自动订阅事件流
default_timeout_seconds = 300.0 # CLI/HTTP 默认超时
max_timeout_seconds = 3600.0 # 外部可指定的最大超时
max_response_bytes = 8388608 # 单次响应最大字节数
process_output_bytes = 4194304 # 每进程输出缓冲上限
event_buffer_size = 2000 # 每条事件流缓冲上限
allow_arbitrary_data_paths = false # 是否允许读 DSH_HOME 之外的文件
allow_sensitive_data = false # 是否允许读凭据存储

[router]
enabled = true
shared_token = ""
allow_remote_without_token = false

[llm]
expose_tools = true
expose_actions = true
max_result_characters = 30000

[interaction]
enabled = true
approval_policy = "ask"
progress_delivery = "aggregate"
progress_window_seconds = 2.0
max_event_text_characters = 12000
persist_pending_requests = true

进程生命周期管理

MoFox 与 DSH 进程的关系由两个配置项控制，全部写在 [bridge] 段：

adopt_external_web（发现已运行的 DSH Web 时怎么办）

启动时若 web_base_url 已有可用的 DSH Web（你自己开的，或上次遗留的）：

- true（默认）：接管它——纳入桥管理，/dsh processes 可见
- false：仅复用不接管——你自己开的 DSH 在 MoFox 关闭后继续运行

attach_manage_lifecycle（接管进程的默认生命周期策略）

所有「接管」动作（adopt_external_web 接管、孤儿接管、process_attach 操作）的默认策略：

- true（默认）：MoFox 关闭时随行终止（进程树强杀）——杜绝孤儿进程占用端口，适合「DSH 只是给 MoFox 用的」场景
- false：仅登记监控——MoFox 关闭后该进程继续运行，适合「DSH 是我自己开的， MoFox 只是借用」场景

process_attach 操作可用 manage_lifecycle 参数逐次覆盖这个默认值。

行为总结

| 场景 | 默认行为 |
| MoFox 自动拉起 DSH Web | MoFox 关闭时进程树强杀，端口释放 |
| 发现已运行的 DSH Web | 接管复用，关闭时随行终止 |
| 端口被孤儿占用 | 找到孤儿 PID 接管复用，关闭时回收 |
| 你自己开 DSH 且不想被关 | adopt_external_web = false，或 attach_manage_lifecycle = false |

手动操作

- 独立 PowerShell 窗口跑 DSH（便于观察/手动操作）： process_start 加 "new_console": true
- 接管任意外部 DSH 进程：process_attach（参数 process_id、pid，可选 manage_lifecycle）
- 解除接管但不终止：process_detach
- 立即终止一个进程（含整树）：process_stop

interaction.enabled = true 且 bridge.start_event_streams = true 时，原生 Adapter
负责先注册 Runtime listener、再按代际订阅下行事件流：legacy 订阅 /api/events.mux 与 /api/events.host 两条 WebSocket 流，modern 统一订阅 /api/remote.mux 的 $events 逻辑流。每个 DSH sessionId 都是一个
platform=dsh 的独立 Neo-MoFox 私聊流；关闭 interaction 不影响现有 CLI、RPC、Router
或 Service 能力。

聊天命令 text /dsh status /dsh sessions /dsh models /dsh models session-e8664bf4-1f7e-479e-bd6c-9a04ff87f3e1 /dsh model session-e8664bf4-1f7e-479e-bd6c-9a04ff87f3e1 deepseek-v4-flash high /dsh presets /dsh preset session-e8664bf4-1f7e-479e-bd6c-9a04ff87f3e1 "PTC 模式" /dsh headless "检查当前项目并运行测试" "E:\project" /dsh rpc host.describe "{}" /dsh rpc session.list "{}" /dsh cli "[\"--version\"]" /dsh exec process_start "" /dsh processes /dsh output web2 0 /dsh stop web2 /dsh events mux 0 /dsh data sessions /dsh pending /dsh pending session-e8664bf4-1f7e-479e-bd6c-9a04ff87f3e1 /dsh respond answer QUESTION_RPC_ID '[{"id":"language","selected":["Python"]}]' /dsh respond cancel QUESTION_RPC_ID /dsh respond approval APPROVAL_RPC_ID allow /dsh respond approval APPROVAL_RPC_ID reject

命令权限为 OWNER。带空格或 JSON 的参数必须整体加引号，解析规则与 Neo-MoFox 其他命令一致。

LLM 调用

- dsh_query：可用 session_list 查会话 ID，使用 model_list 查模型，使用 preset_list 查 Agent preset 模式，也可查询状态、输出、事件和数据。
- dsh_headless：让 DSH Agent 在指定工作目录完成任务，任务可能修改文件。
- dsh_model_switch：切换指定会话模型；provider 留空时按实时目录自动解析并校验推理等级。
- dsh_preset_switch：切换 blank=true 空白会话的模式；支持 preset ID 或显示名。
- dsh_operate：使用 operation 与 parameters_json 调用全部操作。
- dsh_respond：只处理当前 platform=dsh 私聊流的 pending 请求，不能跨 session 回答。answer 传入问题答案 JSON 数组，cancel 取消问题，approve/reject 回答审批。

例如切换到当前 DSH 原生提供的 DeepSeek-V4-Flash：

{
"session_id": "SESSION_ID",
"model": "deepseek-v4-flash",
"reasoning_effort": "high"
}

model_switch 会先调用 session.models 校验目录，并把显示名规范化为真实模型 ID；调用方不需要猜测 provider。成功的会话选择由 DSH 自身持久化为默认模型设置。

DSH 当前内置模式：

| ID | 显示名 | 用途 |
| standard | 标准模式 | 完整编码 Agent，包含编辑、Shell、检索、Skills、计划、目标和子代理 |
| code | PTC 模式 | 标准模式能力加 Code Mode SDK，由 TypeScript 程序组合多步操作 |
| minimal | 极简模式 | 仅提供持久 bash 与 str_replace_editor |
| cordis | 创造模式 | 创建和实验自定义 Agent preset |

DSH 只允许尚未开始对话的空白会话切换模式。模型应先调用 session_list，选择 blank=true 的会话，再调用 preset_list 和 dsh_preset_switch；非空白会话会由 DSH 返回 agent-preset-locked，适配器不会绕过这一安全约束。

HTTP API

Router 挂载在 /api/dsh-adapter：

| 方法 | 路径 | 用途 |
| GET | /operations | 列出统一操作 |
| GET | /status | 查询 DSH 与桥状态 |
| POST | /execute | 执行任意统一操作 |
| POST | /rpc | 调用任意 DSH RPC |
| POST | /headless | 执行 headless 任务 |

通用调用示例：

POST /api/dsh-adapter/execute
{
"operation": "rpc_call",
"parameters": {
"method": "session.list",
"payload": {}
}
}

未设置 shared_token 时仅允许环回请求。设置后，所有请求都必须携带：

X-DSH-Bridge-Token: <shared_token>

DSH Web 自身没有远程认证层。不要将 DSH Web 端口或本 Router 无保护地暴露到公网。

Service API

其他插件通过公开 Service API 获取实例：

from typing import Any, Protocol, cast

from src.app.plugin_system.api import service_api

class DshAdapterServiceProtocol(Protocol):
"""DSH Adapter Service 的最小公共形状。"""

async def execute(
self,
operation: str,
parameters: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""执行一个统一桥接操作。"""

async def switch_model(
self,
session_id: str,
model: str,
*,
reasoning_effort: str | None = None,
provider: str | None = None,
) -> dict[str, Any]:
"""切换指定 DSH 会话模型。"""

service = cast(
DshAdapterServiceProtocol,
service_api.get_service("dsh_adapter:service:dsh_adapter"),
)
result = await service.switch_model(
"SESSION_ID",
"deepseek-v4-flash",
reasoning_effort="high",
)

完整参数见 API.md。

DSH Web 会话交互

普通 DSH Web 会话可在执行过程中发出 question/requested 和 approval/requested。它们进入对应 session 的私聊流，普通文本不会被猜测为答案；只要该 session 有 pending 交互，普通 session.prompt 出站就会失败，必须使用 dsh_respond、Owner /dsh respond 命令或 Service API。

问题答案是对象数组，例如：

[
{"id": "language", "selected": ["Python"]},
{"id": "style", "selected": ["custom"], "custom": "保持 PEP 8"} ]

审批策略由 interaction.approval_policy 控制：

| 策略 | dsh_respond Bot | Owner 命令 | Service |
| ask | 仅可 reject | 可 allow 或 reject | 仅可 reject |
| autonomous | 可 approve 或 reject | 可 allow 或 reject | 可 allowed-once 或 rejected |
| reject | 新审批由 Adapter 自动 rejected | 仅可 reject | 仅可 rejected |

每次 allowed-once 都精确绑定当前 rpcId、approvalId 和 session，不能复用。只有 DSH 回执 {"accepted": true} 后 pending 才会消费；网络失败或其他拒绝会保留为可重试，reason="not-pending" 则标记为 stale。

数据与安全边界

- CLI 通道只能执行配置的 DSH 可执行文件，但参数、profile、patch、stdin 和环境变量可透传。
- 通用 HTTP 通道只能请求 web_base_url 的同源相对路径，不能转为任意 URL 请求器。
- 直接文件读取默认限制在 DSH_HOME，并拒绝 .credentials.yaml。
- allow_arbitrary_data_paths = true 可扩大直接文件读取范围。
- allow_sensitive_data = true 才允许读取 DSH 凭据存储；不要向 LLM 开启此项。
- 输出、响应、文件和事件缓冲均有配置上限，避免无界内存增长。
- respond 可回答 DSH 事件流发起的问题；调用方必须使用事件中的原始 rpcId。

验证

uv run pytest plugins/dsh_adapter/tests -q -p no:cacheprovider --no-cov