siddhartha-yz/dsh-mcp-gateway

dsh-mcp-gateway

为 ChatGPT Web 提供一个成熟的 DSH Harness。

ChatGPT Web 仍然是唯一的主要推理/模型智能体。本项目通过 MCP 将普通的 ChatGPT 对话连接到 DSH，因此 DSH 管理的工具、技能、任务、会话、策略、MCP 客户端以及兼容的社区扩展都可以成为 ChatGPT 的能力，而无需为每个扩展重建定制的封装。

仓库级架构契约是 AGENTS.md。当较旧的原型代码或文档与该契约冲突时，以契约为准，除非仓库所有者明确更改产品方向。有序的个人开发路线图是 docs/roadmap.md。

目标架构

ChatGPT Web Chat
|
OAuth + MCP
|
v
ChatGPT  DSH adapter
|
v
DSH Harness
|
+-- DSH tools / skills / extensions
+-- sessions / jobs / policy / MCP clients
-- optional execution providers
|
+-- local machine
-- selected local-shell-mcp capabilities

适配器应尽可能薄且通用。DSH 是 harness/运行时权威；local-shell-mcp 主要是经过验证的公共隧道/OAuth/远程 worker 模式以及选定的差异化执行能力的来源，而不是主要 harness。

与 local-shell-mcp 的关系

local-shell-mcp 在这里不是 harness 核心。它的有用贡献是经过验证的 ChatGPT Remote MCP/OAuth 和公共隧道模式，以及差异化执行能力，例如远程 worker 和浏览器控制。这些能力在有用时可以组合在 DSH 之后。

最近的 LSM 会话/延续工作仍然是有用的参考资料，但本仓库不会将该运行时复制到网关中。DSH 拥有 harness 生命周期和能力组合。

当前状态

第一个直接的 DSH Harness 接缝已实现。一个驻留在 DSH 中的小型 Cordis 插件使用 DSH 自己的 ctx.tools 注册表：

DSH tool/community plugin
| ctx.tools.register(...)
v
DSH ToolRuntime
| schemas() / execute()
v
loopback ChatGPT bridge
|
v
OAuth MCP gateway
|
v
ChatGPT Web

主要兼容性接口被有意设计得小而稳定。ChatGPT 可以保留相同的已批准 MCP 工具，同时 DSH 获得经过审查的社区扩展：dsh_tool_catalog 在 DSH 侧的 chatgpt-external-v1 能力配置文件完成投影后，读取实时的预设范围 ToolRuntime 目录；dsh_tool_call 仅通过 ctx.tools.execute(...) 执行仍被该配置文件批准的工具。因此 DSH 策略/防护仍然是权威的，并且此路径不要求 ChatGPT 刷新或重新批准其 MCP 工具快照。

通用 Harness 操作同时覆盖 DSH 工具和 DSH 社区技能：
- dsh_tool_catalog：读取 DSH ToolRuntime 当前的外部 ChatGPT 投影。
- dsh_tool_call：仅当某个工具仍处于已批准状态且存在于该投影中时，才通过 DSH 受保护的 ToolRuntime 流水线执行该工具。
- dsh_skill_catalog：列出 DSH 原生 SkillRegistry 中可供 Harness 工作区模型调用的条目。
- dsh_skill_load：从该注册表加载一个兼容的社区技能的指令。

默认的 chatgpt-external-v1 配置文件涵盖确定性实用工具、文件系统操作、shell/作业、Web 访问、图像读取以及 DSH 插件发现。DSH AgentLoop 生命周期/编排工具（如目标/待办控制、子代理、workflow、ralph、send_message、ask_user_question 和 exit_plan_mode）被排除在发现和猜测名称执行之外。ToolRuntime 的 skill 辅助工具也被排除，因为技能已经有专门的 dsh_skill_catalog / dsh_skill_load 接口。经过审核的社区 ToolRuntime 条目可以通过 DSH 桥接覆盖层中的 allowExtraTools 逐个添加；保留的 AgentLoop 和技能名称无法通过该通用选择加入机制启用。OAuth 网关不包含此策略的任何副本。

仓库中的 task_state 插件是一个经过明确审核的额外能力。它通过 DSH 原生的 storageDomain 存储紧凑的工程任务记录：标题/目标/工作区、当前摘要和计划、候选后续步骤、引用、状态、修订版本以及有界的检查点历史。其 resume 操作仅将暂停的记录改回 active；它不会恢复进程、调用模型、选择操作或继续工作。对现有任务的变更需要最新的 if_revision，因此过期的对话会失败关闭，而不是静默覆盖较新的检查点。

仓库中的 shell_session 插件是另一个经过审核的额外能力。它在隔离的 DSH TerminalSessionService 加上原生 terminal-bash 后端之上暴露 open/list/status/send/read/signal/close。该适配器不包含任何 PTY、进程或沙箱实现：DSH 保留精确 Agent 所有权、持久化的 cwd/环境/进程上下文、有界的回滚/输出、前台信号、超时、进程树清理以及共享沙箱策略。现有的一次性 bash 工具仍可用于更简单的命令。
该仓库的 browser_session 插件是一个经过审查的运行时扩展，用于持久化 Chromium 交互。它暴露 open/list/status/snapshot/act/script/close，且不包含内部模型循环、调度器或自主浏览器任务。浏览器会话严格按 Agent 隔离；在会话存活期间，页面、cookie、DOM 和内存中的浏览器状态在工具调用之间持续存在。Playwright 仅提供协议控制。DSH 仍是文件效果策略的权威：插件解析当前 DSH sandboxPolicy，并要求配置的 DSH 沙箱提供程序以失败关闭（fail-closed）方式对其进行验证。对于 workspace-write，Chromium 随后使用经过审查的 @deepseek-ai/dsh-sandbox-local 0.1.2-rc.1 bwrap 挂载配置（/ 只读，私有 /proc 和 /tmp，工作区以可写方式绑定挂载），因为 DSH 的 Landlock 回退会故意阻止 Chromium 为其自身用户命名空间沙箱所需的 /proc/*/uid_map 写入。一个窄范围的本地 dsh-browser-worker 仅在专用 AppArmor userns 配置文件和 NoNewPrivs=1 下启动该确切的 bwrap+Chromium argv（对于 danger-full-access 则直接启动固定版本的 Chromium）。该 worker 仅通过 Unix SO_PEERCRED 接受来自活动 dsh-web-host.service MainPID 的 spawn 请求，不包含 shell/模型/调度器，并负责浏览器进程树/配置文件的清理。运行时锁固定 playwright-core 以及用于对等凭据查找的小型 Koffi 绑定，而部署则以可复现方式安装匹配的 Chromium 构建。

默认网关模式有意设计为 meta-only：tools/list 仅暴露那四个稳定的 DSH 元工具，各个 DSH ToolRuntime schema 不会投射到 ChatGPT 中，并且网关不会通告现代工具列表变更订阅。这使得冻结快照属性成为强制执行的协议边界，而不是对客户端行为的假设。当操作者希望兼容的 DSH 工具作为一等 MCP 工具出现时，可以显式启用 --tool-surface projected 作为单独的 UX 模式。
桥接直接使用 DSH 的原生预设作用域进行发现。agentPresets.standingKeyFor(presetId) 会解析部署当前的默认预设，而无需启动 Agent、Session 或模型轮次；ToolRuntime.schemas(scope) 和 SkillRegistry 查找都使用该常驻作用域。工具执行通过 ToolRuntime.execute(...) 进行，其 0.1.2-rc.1 API 需要 Agent 来进行 agent 作用域的策略和模态检查。因此，桥接会在首次工具调用时惰性创建那个仅含元数据的执行 Agent。其持久辅助 id 是工作区 cwd、预设 id、解析后的组合路径，以及 DSH 用于检测新常驻代际的相同 mtimeMs/大小文件戳的非可逆哈希，再加上内容摘要以避免大小相等的重写产生别名。只有在那个确切的工作区/预设组合代际仍然适用时，重启才会恢复同一个辅助；不同的工作区、更改的默认预设或编辑过的组合会获得不同的辅助。Setup 在 agentPresets.mount(...) 之后重新检查预设路径/戳，如果热重载与辅助创建发生竞争，则失败关闭。Catalog/skill 读取不会创建辅助会话，普通重启也不再每次启动都累积一个新的持久辅助。

对于执行受路由模型声明模态门控的原生 DSH 工具，惰性执行 Agent 指向一个本地仅含元数据的 ChatGPT Web 路由。该路由声明 text + image 输入，以便 DSH 自己的 read_image 门控可以验证外部 ChatGPT 消费者，但其 stream() 方法总是失败，并且桥接从不向 Agent 提交提示。因此它不执行任何推理，不需要模型 API 密钥，也不可能成为隐藏的第二个模型。0.1.2-rc.1 升级冒烟测试验证了预设作用域的 bash 执行，以及原生 read_image 在未配置提供商凭据的情况下通过桥接返回图像块。

DSH 的 additionalContexts 也在外部 agent 边界上得以保留。DSH 将这些后续用户上下文用于守卫提醒，以及用于嵌套 Code Mode 结果，例如 run_code 返回的图像。桥接会在这些上下文中物化由附件支持的图像，MCP 适配器会将其可见的文本/图像块追加到工具结果中，因此用 ChatGPT Web 替换 DSH 自己的模型循环不会静默丢弃策略或嵌套多模态上下文。
这意味着添加一个兼容的技能无需 Python 包装器、网关重启或 ChatGPT 应用重新发布。新的 ToolRuntime 能力同样无需 Python 包装器，但它必须被 DSH 侧的外部能力配置文件所接纳（默认情况下为内置能力，经过审核的社区工具通过 allowExtraTools 接纳）。固定的元工具会按需发现由此产生的实时投影。仅在可选的 projected 工具表面模式下，DSH 侧桥接会跟踪原生 tools/change 失效事件，网关会发布 MCP tools/list_changed，从而让支持动态刷新的客户端获得一等公民级别的已批准条目。

DSH 侧桥接插件位于 dsh-bridge-plugin/，部署叠加层为 deploy/dsh/chatgpt-bridge.cordis.yml。

OAuth / MCP

保留现有的嵌入式 OAuth 实现。它提供持久化的动态客户端注册、PKCE/公共客户端支持、所有者批准、资源/签发者绑定的令牌、刷新轮换、撤销、有界注册状态，以及针对公共 MCP 端点的 DNS 重绑定防护。

主要 harness 模式不需要模型提供方 API 密钥。使用桥接叠加层运行 DSH Web Host，然后将 OAuth 网关指向其回环桥接：

python -m pip install --constraint deploy/server-constraints.txt -e '.[server]'

export DSH_MCP_GATEWAY_ADMIN_PIN='choose-a-long-owner-pin'

dsh-mcp-gateway \
--public-base-url https://gateway.example.com \
--dsh-harness-url http://127.0.0.1:3080 \
--state-dir .dsh-mcp-gateway

公共端点为：

https://gateway.example.com/mcp

GET /healthz 检查网关进程。在 harness 模式下，GET /readyz 检查回环 DSH 能力桥接；它从不探测 LLM 提供方。

开发

python -m pip install -e '.[dev]'
ruff check src tests scripts
python -m unittest discover -s tests -v

CI 使用的服务器依赖图固定在 deploy/server-constraints.txt 中。

设计不变量

- ChatGPT 是唯一的主要推理 Agent。
- DSH 是 harness/运行时权威。
- DSH 社区能力应通用地跨越适配器，而不是获取定制的网关包装器。
- 稳定的元工具是扩展发现/调用的正确性路径；动态一等公民工具投影是可选的用户体验。
- 工具执行保持在 DSH 自身受保护的 ToolRuntime 管道内。
- 公共 OAuth/MCP 边界保持在回环 DSH Web Host 之外。
- local-shell-mcp 是可选的执行/访问提供方和参考，而非主要 harness。
- 网关拥有的会话/延续实验是遗留工作，而非当前架构。

许可证

MIT。参见 LICENSE。安全报告指南见 SECURITY.md。