迷你运行时 huangjunsen0406/mini-dsh

mini-dsh

一个手写的最小运行时，遵循 DSH 的设计理念，基于 @deepseek-ai/cordis 构建。

这是一个用来学习 DSH 核心设计的最小项目——不是完整的 DSH 产品。

它刻意保留了五样东西：

1. Cordis Context / Plugin / Service
2. Session Event Log -> deriveMessages()
3. Tool Registry -> register / schemas / execute
4. LLM Provider Adapter
5. Agent Loop -> model -> tool -> model -> answer

它还保留了 Bash/File 工具，以及官方的 @deepseek-ai/dsh-mcp-client + Context7，用来证明「一切皆插件」。Context7 是可选的：连不上时命令行照样能启动——只是拿不到那些 MCP 工具。

演示

mini-dsh CLI

环境

- Node.js >= 20.18.1
- pnpm 11.22.0（见 package.json 里的 packageManager）

运行

pnpm install
cp .env.example .env
fill in DEEPSEEK_API_KEY
pnpm start

.env.example 里设置的是 deepseek/deepseek-v4-flash。如果 MINI_DSH_MODEL 完全缺失（比如你没复制 .env），入口会回退到 deepseek/deepseek-v4-pro（src/index.js:41）。

可选：填上 CONTEXT7_API_KEY。当 mcp.context7.com 连不上时，你只会看到 [plugin] failed——进程不会挂掉。

Context7 连上之后的路径：

@deepseek-ai/dsh-mcp-client
-> https://mcp.context7.com/mcp
-> ctx.tools.register(...)
-> mcp__context7__resolve-library-id
-> mcp__context7__query-docs

命令行

/tools
/models
/model
/model deepseek/deepseek-v4-pro
/model deepseek/deepseek-v4-flash
/history
/prompt
/reset
/exit

写入和 bash 执行前会先问 [Y/n]。智能体运行期间按 Esc 可以取消当前运行（方向键不会取消）。

为什么 Agent Loop 里没有 12 步上限？

学习版刻意写成：

while (true) {
const response = await model()

if (!response.toolCalls?.length) {
return response.content
}

await executeTools(response.toolCalls)
}

唯一的正常结束条件，就是模型不再请求工具。

这里刻意省略了：

- maxSteps
- token/cost budget
- compaction
- no-progress detector
- stop hooks
- steering queue
- 完整的权限系统（学习版在唯一一道真实边界——命令行的 [Y/n] 确认——前面，加了一道应用层路径门禁和命令黑名单）
- 完整的模型配置中心
- TUI/Web UI

这些对成熟产品非常有用，但理解 Agent Harness 的核心并不需要。

注意：所以理论上，一条糟糕的模型/工具链可能会无限循环。这个项目是用来学习的——别把它当成生产环境的 Agent Runtime。

给初学者：从零写一遍

不要先通读整个仓库。先浏览 ARCHITECTURE.md 建立整体印象，然后新建一个空项目，自己动手写，按 LEARNING.md 一个里程碑一个里程碑地推进。

推荐阅读顺序

src/index.js
↓
src/plugins/sessions.js
src/plugins/system-prompt.js
src/plugins/tools.js
src/plugins/llm.js
src/plugins/agents.js
src/plugins/agent-loop.js
src/plugins/sandbox.js
↓
src/core/session-runtime.js
↓
src/core/system-prompt-runtime.js
src/plugins/runtime-context.js
↓
src/core/tool-runtime.js
↓
src/core/llm-runtime.js
↓
src/core/agent-runtime.js
↓
src/core/agent-loop-runtime.js ← 核心 ↓ src/plugins/cli.js ↓ src/utils/path.js src/core/sandbox-runtime.js ↓ src/models/deepseek.js ↓ src/tools/bash.js src/tools/files.js ↓ src/plugins/external-plugins.js plugins.config.js ↓ test/core.test.js ← 行为文档：每个 runtime 一个示例

最重要的心智模型

Cordis Context
│
┌────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
▼ ▼ ▼ ▼ ▼ ▼
sessions systemPrompt tools llm agents agentLoop
│ │ Agent
bash / files DeepSeek
│
ctx.sandbox
path / command / Y/n
└── dsh-mcp-client (optional)
│
Context7

Agent Loop 对 Context7 和 Bash 一无所知，它只认识 ctx.tools。Agent 只是个薄薄的包装：sessionId + model + loop（src/core/agent-runtime.js）。

这才是这个项目里最值得学的东西。

测试

pnpm test
pnpm check

测试里有个用例：智能体连续调用 20 次工具后才结束——证明 Loop 已经没有过去那个 12 步的上限了。

来 LINUX DO 学 AI