智慧协作体系（zhihui-xiezuo）

这是**「智慧协作体系」的第一个模块 —— DSH 会话桥**，后续会继续补充其它模块。

让外部 Agent 接入一个已经在运行的本机 DeepSeek Harness (DSH) Web 实例：列会话、只读核对、绑定会话、向指定会话投递任务，并取回该任务所属回合的最终回复。

提供 CLI 与 MCP（stdio） 双入口，Windows / macOS / Linux 可用。

这个包解决什么问题

你在浏览器里开着 dsh web，某个会话里有一场正在进行的对话。你想让另一个 Agent（Codex、Claude Desktop、Cursor、任何 MCP 客户端）把一条任务投进那个会话，并且拿到这一回合的回复。

DSH 官方没有提供这个能力：

• 官方 @deepseek-ai/dsh-acp 是 ACP 协议 + stdio，自己拉起一个全新的 DSH 进程，只能操作它自己创建/恢复的会话。它碰不到你网页上正开着的那个会话——那个会话由 dsh web 进程持有跨进程写锁，ACP 去 session/resume 会撞上 SessionAlreadyOwnedError。

• 官方没有任何 MCP 形式的会话控制服务端（packages/mcp/ 下只有 mcp-client 和 mcp-resources，方向都是「DSH 消费外部 MCP」，不是对外暴露）。

本包补的就是这个缺口：接入已运行实例、操作人正在看的那个会话、人在环。

两者不重叠，各自独占不同场景。

Related MCP server: pipe-opencode

安装

需要 Node.js ≥ 22。

npm install -g zhihui-xiezuo

或者从源码：

git clone https://github.com/chongming1994/zhihui-xiezuo.git && cd zhihui-xiezuo
npm install
npm link          # 可选，装出全局命令

安装后有两个可执行入口：

• zhihui-xiezuo —— 命令行

• zhihui-xiezuo-mcp —— MCP stdio 服务端

Windows 说明

npm install -g / npm link 会自动生成 .cmd shim，无需手动处理。也可以不装全局，直接用 node <包内路径>\bin\zhihui-xiezuo.js 调用。

快速开始

1. 拿到 DSH 的启动令牌

启动 dsh web 时终端会打印一个带 token 参数的 URL，把那个 token 复制出来。

2. 认证

# 交互式输入（不回显，不落命令行历史）
zhihui-xiezuo auth

# 或从受保护文件读取
zhihui-xiezuo auth --token-file ~/.config/dsh-token

凭据写入状态目录（见下），令牌本身不保存。DSH 重启后令牌会变，需要重新 auth。

3. 检查连接

zhihui-xiezuo check --json

只调 session/list，不激活任何会话。

4. 列会话、绑定、投递、取回复

zhihui-xiezuo sessions                       # 列会话摘要（不含聊天正文）
zhihui-xiezuo inspect <会话ID>                # 只读核对单个会话
zhihui-xiezuo bind <会话ID>                   # 显式绑定目标
zhihui-xiezuo send --file ./task.md          # 投递任务
zhihui-xiezuo wait <requestId> --timeout 600000   # 取回该回合回复

CLI 命令

完整选项与退出码见 zhihui-xiezuo --help。

退出码（给调用方用的稳定契约）：

0 成功   1 失败   2 用法错误   3 认证/信任失败   4 目标不存在
5 本地等待超时   6 关联不确定   7 提交结果未知

MCP 接入

MCP 服务端是 stdio 传输，暴露 10 个工具。

通用配置

{
  "mcpServers": {
    "zhihui-xiezuo": {
      "command": "node",
      "args": ["/绝对路径/zhihui-xiezuo/bin/zhihui-xiezuo-mcp.js"],
      "env": {
        "ZHIHUI_XIEZUO_URL": "http://127.0.0.1:3080"
      }
    }
  }
}

全局安装后也可以直接用命令名：

{
  "mcpServers": {
    "zhihui-xiezuo": {
      "command": "zhihui-xiezuo-mcp"
    }
  }
}

Windows 上如果用命令名，注意某些客户端不走 shell、找不到 .cmd；此时请写 "command": "node" + 绝对路径的 args。

工具清单

只读

写入（需要显式 confirm: true，否则直接拒绝、不执行）

长任务

写操作要求 confirm: true 是刻意的安全边界：本工具绝不推断「当前网页会话」，也绝不代替用户授权。

状态目录

可用环境变量覆盖，优先级：

--home 参数  →  ZHIHUI_XIEZUO_HOME  →  DSH_BRIDGE_HOME（旧变量，向后兼容）  →  平台默认

目录内含 config.json、credential.json（凭据）、requests/（请求账本）、workorders/、locks/。

安全边界

本工具在设计上刻意收紧，使用前请知悉：

• 仅本机环回：只接受 127.0.0.1 / localhost / ::1，非环回地址在发出任何网络请求之前就失败关闭。

• 不跟随重定向：所有 /api 调用与令牌交换都用 redirect: 'manual'，任何 3xx 一律显式拒绝，绝不把任务正文或凭据转发到别的地址。

• 只发显式绑定的会话：绝不推断「当前网页会话」。目标必须显式指定或已绑定。

• 不订阅审批通道：因此不可能自动批准任何请求。审批永远留给人。

• 不提供 cancel / steer / approve / 改队列 / 改模型 / 改 preset。

• 未知状态不自动重发：submission_unknown / result-unknown 只留账等人工核对，不重试。

• 不读密钥：凭据只存在状态目录的 credential.json，不打印、不写入任务正文。

已知限制

• 不能取消、不能批准：send 只支持 mode=queue，不提供 steer / cancel / approve。

• 需要有一个跑着的 dsh web：本包是纯 HTTP 客户端，不自己拉起 DSH。

• DSH 接口契约是 pre-stable：上游升级后需重新核对（check 会报告契约字段）。

• Windows 上不做自动 ACL 收紧：chmod 在 Windows 只能切只读位，本包不自动改 ACL。若要限制令牌文件访问，请自行执行：

  icacls "C:\path\to\dsh-token" /inheritance:r /grant:r "%USERNAME%:R"

  或直接用交互式 auth（令牌不落文件，最省事）。

开发

npm install
npm test          # 139 项测试

源码结构：

src/
  cli.js             命令行入口、参数解析、命令分派
  mcp-server.js      MCP stdio 服务端（10 个工具）
  rpc.js             DSH HTTP 客户端（环回校验、令牌交换、redirect 拒绝）
  mux.js             WebSocket 会话事件流
  associate.js       回合归属关联（requestId → turn → reply）
  store.js           请求账本、文件锁、状态单调前进
  config.js          状态目录、配置、凭据、原子写
  secret-input.js    令牌输入（POSIX mode 校验 / Windows ACL 校验）
  workorder.js       协作工作单状态机
  errors.js          稳定错误码与退出码
  redact.js          输出脱敏

许可

MIT