OrgX 工作账本 useorgx/orgx-deepseek-harness-plugin

面向 DeepSeek Harness 的 OrgX

@useorgx/deepseek-harness-plugin 把 OrgX MCP 工具加进 DeepSeek Harness 配置档，还能通过 Harness 无头模式运行一个绑定工作区的 OrgX 网关对等端。

这个包是开发者预览版。装上包只能证明包体存在，不能证明 OrgX 认证通过、网关准入成功、派发成功、部署完成或已用于生产。

用 OrgX 向导安装

受支持的用户流程是 OrgX 向导。它会检测兼容的 DeepSeek Harness 安装，把本包装进 headless 配置档，并在浏览器里完成 OrgX 配对：

npx @useorgx/wizard@latest setup

然后通过向导启动任务，让它在 DSH 启动前刷新 OAuth token：

npx @useorgx/wizard@latest deepseek "List the OrgX tools available in this workspace."

DSH 包在 MCP 连接或首次工具同步失败时会启动失败。不要把包存在当成 OrgX 工具面已通过认证的证明。

直接安装包体

DeepSeek Harness 锁定在 0.1.0-rc.6。进阶用户可以用 Node ^22.19.0 或 >=24.0.0 直接安装本包：

npm install --global @deepseek-ai/dsh@0.1.0-rc.6
export ORGX_MCP_ACCESS_TOKEN='your_orgx_oauth_access_token'
export DEEPSEEK_API_KEY='your_deepseek_key'
dsh plugin --profile headless add @useorgx/deepseek-harness-plugin@0.1.1
dsh --profile headless --dump-config
dsh --profile headless "List the OrgX tools available in this workspace."

做源码开发时，运行 npm pack --ignore-scripts，再用 file: URL 安装生成的 tarball。裸的本地链接给不了同样的干净安装保证。

本包内置了 @useorgx/orgx-gateway-sdk@0.1.0-alpha.9 提交 49f3cad612954c448878dc62d0f9c6bc87fa0f79 中那份 MIT 许可的 OrgX 网关对等端客户端，版本完全一致。DSH 在安装插件时会拦截 Git 及其他特殊子依赖，所以内置这份已审计的客户端，才能让全新配置档装得上。见 THIRD_PARTY_NOTICES.md。

包体挂载一个 @deepseek-ai/dsh-mcp-client 实例，名为 orgx。它通过 Streamable HTTP 连接 https://mcp.useorgx.com/mcp?profile=v2，并发送 Authorization: Bearer $ORGX_MCP_ACCESS_TOKEN。这个值必须是客户端托管的 OrgX OAuth 2.1 访问 token；oxk_ 网关密钥对托管 MCP 无效。设置 ORGX_MCP_URL 可改用其他 OrgX MCP 端点。OAuth token 缺失，或首次 MCP 连接与工具同步失败时，启动会失败。本预览版不跑浏览器 PKCE 流程，也不刷新 token；token 过期后请替换客户端托管的访问 token。

DeepSeek Harness 0.1.0-rc.6 只桥接 MCP 工具。本客户端用不了 MCP Resources 和 Prompts。非文本 MCP 块面向模型时也是有损投影，即使执行本地结果保留了它们的 JSON 块。

运行 OrgX 对等端

对等端把执行 cwd 设在 ORGX_WORKSPACE_ROOT 内；请求的仓库如果解析到该目录之外，会在 Harness 启动前失败。这是路径与变更边界，不是主机隔离。Harness 的 workspace-write 不限制同一用户的文件读取、进程可见性或网络访问，因此模型或工具可能看到其他主机数据，或通过网络发送数据。只有接受这一风险后，才设置 ORGX_DEEPSEEK_HOST_ACCESS_ACK=1；没有这项确认，启动和凭据就绪检查都会失败。

使用作用域限定为 gateway:drive 和 plugin:heartbeat 的 API key。OrgX gateway-key 响应会返回 installation_id；把这个稳定值连同 key 一起保存，每次启动时原样传入两者。

export ORGX_API_KEY='oxk_your_workspace_key'
export ORGX_MCP_ACCESS_TOKEN='your_orgx_oauth_access_token'
export DEEPSEEK_API_KEY='your_deepseek_key'
export ORGX_WORKSPACE_ID='your-workspace-uuid'
export ORGX_INSTALLATION_ID='install.your-stable-installation-id'
export ORGX_WORKSPACE_ROOT='/absolute/path/to/the/workspace'
export ORGX_DEEPSEEK_HOST_ACCESS_ACK='1'
dsh plugin --profile headless exec orgx-deepseek-harness-peer

这个预览版是非托管的 gateway protocol v1 peer。它不实现 candidate/canonical 激活与晋升生命周期。传入 ORGX_RUNNER_INSTANCE_ID、ORGX_ACTIVATION_ATTEMPT_ID 或 ORGX_RUNNER_ROLE 会让启动明确失败；这些字段永远不会出现在它的心跳或 socket URL 中。

打开 WebSocket 之前，peer 会先写一条 gateway 心跳，把传输就绪和调度就绪都标为 false。只有以下检查全部成功，它才宣告调度就绪：

- dsh --version 证明固定版本的运行时进程存活；
- 固定的官方 https://api.deepseek.com/user/balance 端点接受 DEEPSEEK_API_KEY，并报告 is_available: true，且不发起推理请求；以及
- 一次 MCP Streamable HTTP initialize 加 tools/list 交换接受 ORGX_MCP_ACCESS_TOKEN。

密钥存在、以及不带凭据的版本命令，永远不算通过认证。探测失败、凭据被拒或过期、证据缺失，一律保持 fail-closed。成功的证据缓存 45 秒；peer 每 15 秒刷新一次 gateway 在线状态，socket 关闭时尽力写一条离线心跳。

DSH 子进程拿到服务商 key 和单独限定作用域的 MCP 访问 token，但拿不到 gateway key。环境中的 DSH_ 控制项不会转发，只有 DSH_HOME 例外；子进程被强制为 workspace-write 权限，遥测被禁用，这样环境里的全权限或 OTLP 导出设置就无法覆盖这两项策略。这些设置仍然不能隔离主机读取、进程或网络访问。

可选的运行时设置：

- ORGX_BASE_URL 修改 OrgX gateway 基础 URL。
- ORGX_RECEIPT_OUTBOX_PATH 设置持久回执目录的绝对路径。默认在当前用户的 OrgX 状态目录下。
- ORGX_DEEPSEEK_HARNESS_BIN 修改可执行文件路径，默认是 dsh。
- ORGX_DEEPSEEK_HARNESS_PROFILE 把配置档从 headless 改掉。
- ORGX_DEEPSEEK_HARNESS_MODEL 启用打包好的模型补丁，作用于 deepseek-official 服务商。它改的是组合默认值；DSH 设置里已经保存的模型仍然可以优先。

Harness 无头模式的 stdout 只包含最终助手文本和退出码，没有 token 或成本核算。因此驱动的 wire 消息必须带上数值 tokens_used: 0 和 cost_estimate_cents: 0；这两个值在此来源都表示未知，不是免费。OrgX 把持久化的 DeepSeek 成本规范化为保守的调度估算，记录计量质量，并在预算上限中累计该估算。进程退出码为零时报告 outcome_kind: awaiting_review：进程结束了，但工作尚未被接受、合并、部署，也未经生产验证。

SDK 的 WebSocket 发送没有服务端确认，所以持久性由应用负责。在产出 task.started 之前，对端会原子写入一个启动前预留标记。如果写入失败，它会在 Harness 能拉起进程之前关闭内层迭代器，并尽力 POST 一条 blocked 回执。在产出每个启动后的 task.completed 帧之前，它会把精确的 v1 HTTP 回执原子写入 mode-0700 的 outbox，文件权限为 mode-0600，然后 POST 到幂等的 run-receipt 端点。两个文件都不写入任何 key 或 token。

只有 2xx 响应才会移除终态回执。如果 Harness 完成后最终持久化失败，对端会立即直接尝试绑定的 HTTP 回执，并且仍然产出原来的完成结果。2xx 会清除预留；如果 HTTP 也失败，完成结果留在内存重试队列中，其预留标记也保留。待处理回执会在启动、重连以及每 15 秒一次的心跳 tick 时重试。重启时若存在未解决的预留，会以修复消息失败关闭，而不是冒险重新执行。

固定版本的 SDK 无法持久恢复仅存在于 socket 的 task.failed。因此，运行开始之后，本对端会把失败原因记录为一个步骤，并发出 outcome_kind: blocked；取消则发出 outcome_kind: abandoned。两者都走应用 outbox。在 task.started 之前被拒绝的重复项仍然是 task.failed，无法终结已经拥有该 run id 的调度。

校验

做包开发时，先安装固定依赖并跳过生命周期脚本，然后运行确定性检查：

npm install --ignore-scripts --no-package-lock
npm run validate

包的测试脚本显式对 test/.node-test.mjs 运行 node:test。仅 Node 的后缀让这些套件避开仓库根目录的 Vitest 发现，同时仍保留在 npm run validate 中。

校验会检查 bundle 和 manifest、有证据支撑的就绪状态、工作区与子环境边界、取消与重复竞态、非托管的 protocol-v1 心跳，以及固定版本 SDK 在断连时的 HTTP 故障恢复。它不会联系 OrgX 或 DeepSeek。

MCP 操作发现

执行前，Harness 会同步当前的 tools/list 清单；它没有固定的托管工具别名，也不假设响应字段。显式给出的 ORGX_MCP_URL 值会原样保留。写入失败时，不会换另一个工具名重试。可移植的工作回执保留完整文档；网关终端回执则使用各自独立的运行契约。