DeepSeek Harness in Depth

外观

examples/ 目录存放可运行的演示叶子——轻薄 cordis.yml 组合——而 packages/examples/ 存放这些叶子加载的可复用演示包。二者共同构成从“安装 dsh”到“真实 agent 对真实模型行动”的最短路径，同时充当无密钥 acp-snapshot 与真实 API e2e 测试套件的基底。本页逐一映射每个示例、如何运行、演示了什么。

两层结构 ​

examples/AGENTS.md 说得很清楚：examples/ 是一个 workspace 成员，是可运行与测试 Cordis 配置的模块解析根，但不是构建目标。其根 examples/package.json（dsh-examples 伞形）把每个叶子的 cordis.yml 插件并集声明为 workspace:* 依赖，使任意叶子的 plain-Node（:lib）启动都能通过真实包的 exports → lib 解析其插件。每个叶子自身的 package.json 仅是元数据（name、description），没有脚本。

packages/examples/README.md 补充了余下部分：-demo npm 后缀把每个包标记为非产品表面。agent-spine-demo 是共享 spine；acp-demo 增加一个自动化入口；jsonrpc-demo 启动部署拥有的插件树。产品一次性执行属于 dsh --profile headless；这里没有任何包提供它。

演示叶子（examples/） ​

叶子用途演示内容
acp-agent/一个基于 JSON-RPC stdio 的 ACP 自动化服务器Agent Client Protocol、Code Mode、子代理、沙箱
headless-agent/一次完整的 headless 编码 agent 轮次DeepSeek V4 + bash/fs 工具、子代理、workflow、Ralph、todo_write、JSONL 持久化
jsonrpc-agent/无人值守的 JSON-RPC 编码 agent 组合Python SDK 内置的 JSON-RPC 运行时
mcp-memory/三个默认关闭的第三方记忆 MCP 参考配置MCP 客户端互操作（Memorix、MCP Reference Memory、Engram）
web-cordis/自指 Cordin 工具演示dsh-tool-cordis：agent 就地检查/挂载插件
web-schedule/Session-local Schedule 覆盖层schedule_create/list/delete、时间上下文提醒

acp-agent ​

面向父 agent / 子代理提供者的自动化型 Agent Client Protocol 服务器。运行（均需仓库根 .env 中的 DEEPSEEK_API_KEY）：

sh
pnpm run demo:acp      # JSON-RPC stdio ACP
pnpm run demo:code-mode # 同协议，Code Mode 工具传输

stdout 保持协议纯净（换行分隔的 ACP JSON-RPC）；诊断走 stderr。每个 session/new 获得一个会话作用域的 cwd，DSH_PERMISSION_MODE 在 workspace-write 与 danger-full-access 间选择。它是 ACP 快照测试的主要示例（examples/acp-agent/tests/snapshots/）。

headless-agent ​

headless 编码 agent 的无密钥/真实模型回放组合。经产品命令运行：

sh
pnpm dsh --profile headless "fix the failing test in this workspace"

它显式挂载共享 agent spine、一个根 agent、持久化与检查点策略。其快照套件通过 tests/fixtures/headless-driver.ts 驱动该配置，后者以 JSONL 输出规范化会话事件。e2b.cordis.yml 把本地文件系统/子进程换成单个共享 E2B 沙箱（E2B_API_KEY）——一个 provider 组合 POC。

jsonrpc-agent ​

Python SDK 内置 JSON-RPC 运行时的无人值守组合——不加载终端 UI、logger、审批 UI 或 user-questions 工具，因为 stdout 属于 SDK 协议。工具：前台 bash、read/write/edit、subagent（一个进程内 spawn provider）、todo_write。运行时环境：DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DSH_CWD、DSH_SESSION_ROOT、DSH_SYSTEM_PROMPT。内置可执行文件已携带它点名的每个插件，所以目标机器无需 Node.js。minimal.cordis.yml 变体（持久 PTY + str_replace_editor）是 Web 端 minimal 预设的完整独立对应物；minimal.py 经 Python SDK 运行它。通过 jsonrpc-demo 包，用 demo:acp 风格的 bin 运行其演示。

mcp-memory ​

三个默认关闭的参考配置，经 @deepseek-ai/dsh-mcp-client 连接一个外部记忆系统。用 --patch 选一个：

sh
dsh web --patch "$PWD/examples/mcp-memory/memorix.cordis.yml"
# 或 mcp-reference-memory.cordis.yml，或 engram.cordis.yml

DSH 启动 stdio 子进程 / 连接 HTTP 服务、发现 MCP 工具，并把它们暴露为 mcp__<serverName>__<tool>。它不安装、初始化或监管第三方服务。已测试的 pin：memorix@1.3.0、@modelcontextprotocol/server-memory@2026.7.4、engram@v1.20.0。字节级可复现正是快照所要求的。

web-cordis ​

@deepseek-ai/dsh-tool-cordis 的自指演示：agent 可以检查其运行中的 Cordis 进程，并在内存中挂载/卸载模型编写的插件（临时插件在卸载或退出时消失）。

sh
pnpm run demo:cordis      # 浏览器界面
pnpm run demo:cordis acp  # 改成 ACP 自动化服务器

web-schedule ​

让一个 dsh web 进程启用 session-local schedule 提醒：

sh
dsh web --patch examples/web-schedule/cordis.yml

模型使用 schedule_create/schedule_list/schedule_delete；浏览器把 IANA 时区附加到每次提示，时间上下文按该时区解释未限定的日期时间。提醒归发起它的 Session 日志所有；关闭进程会停止内存定时器而不删除记录，重新打开该 Session 会恢复等待。

可复用包（packages/examples/） ​

包npm 名（版本）作用 / bin
agent-spine-demo/@deepseek-ai/dsh-agent-spine-demo默认的 executor-less/UI-less agent spine 包（无 bin）
acp-demo/@deepseek-ai/dsh-acp-demoACP 自动化服务器应用；bin dsh-acp-demo
jsonrpc-demo/@deepseek-ai/dsh-sdk-jsonrpc-demo为 stdio JSON-RPC SDK 运行时启动外部 Cordis 配置；bin dsh-jsonrpc-agent

agent-spine-demo：所谓“spine” ​

Spine 是共享的、executor-less、UI-less 的 agent 包——公共服务、后台任务注册表与控件、可选持久化目标、具体 agent loop、本地 skill 与 agent-instructions provider，以及面向模型的 shell/skill 消费者。部署仍需自行选择 LLM 适配器、bash 执行器与呈现层。它挂载 dsh-llm、dsh-session、dsh-system-prompt、dsh-tools、dsh-skill + dsh-skill-filesystem、dsh-agent、dsh-goal + dsh-goal-round-driver、dsh-jobs-local、dsh-invariants（外加四个核心伴生包 dsh-session/dsh-agent/dsh-scope/dsh-agent-loop 的不变量）、dsh-agent-loop 与 dsh-llm-retry——以及 dsh-tool-bash、dsh-tool-skill、dsh-tool-jobs，并经 dsh-agent-instructions 提供 workspace 上下文。

ts
// packages/examples/agent-spine-demo/src/index.ts（节选）
export const name = 'agent-spine-demo'
// …导入 Timer、LlmRuntime、SessionStore、SessionTitleService、SystemPrompt、
// ToolRuntime、SkillRegistry、AgentRegistry、GoalService、LocalJobRegistry、
// InvariantRegistry + 不变量伴生包、AgentLoop、llmRetry，…

该插件刻意只暴露命名导出——Loader 的默认解包会丢弃其 Config schema（见 docs/postmortem/0001-acp-default-export-drops-inject.md）。

如何运行每个示例 ​

examples/ 叶子不带脚本；运行命令在根 package.json 的 scripts 里：

jsonc
"demo:acp":   "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
"demo:cordis":"node scripts/demo-cordis.mjs",
"demo:code-mode":"node scripts/demo-code-mode.mjs",
"mock:llm":   "node --import tsx packages/test-support/llm-mock-server/src/bin.ts"
  • demo:acp 针对 examples/acp-agent/cordis.yml 启动 ACP 包。
  • demo:cordis 默认运行浏览器端 Cordis 工具演示；pnpm run demo:cordis acp 选择 ACP 变体。
  • demo:code-mode 用 Code Mode 工具传输运行 ACP 协议。
  • mock:llm 为本地恢复测试启动可脚本化 LLM 故障服务器。

每个示例都包含无密钥与with-key两种冒烟（按 examples/AGENTS.md）：无密钥者通过 Loader 启动真实 cordis.yml 并断言输出 + 干净退出；with-key 者发送实时模型提示并核验外部状态，无 DEEPSEEK_API_KEY 时自跳过。

版本表 ​

延伸阅读 ​

  • 测试策略— 驱动 examples/acp-agent 的 ACP 快照套件（dsh-acp-snapshot）。
  • 拼接库— 每个 cordis.yml 加载的 Cordis 框架。
  • examples/AGENTS.md— 面向示例的贡献与测试约定。
  • packages/examples/README.md— 包/叶子分工与 -demo 命名契约。
  • packages/examples/agent-spine-demo/README.md— spine 包的配置面。
  • docs/postmortem/0001-acp-default-export-drops-inject.md— spine 为何用命名导出。

DeepSeek Harness in Depth