极简智能体内核 mgh233/nano-dsh

Nano-DSH

Nano-DSH 是一个小型同步教学 harness，演示 CLI 任务如何经过动态插件、真实工具和 DeepSeek 模型步骤，变成一次 Agent Run。

1. 一次完整的 Agent Run

常规无头运行从这条命令开始：

nano-dsh "Fix the selected workspace" --workspace "$PWD/../nano-dsh-workspace" --api-key-file "$PWD/.key"

这是端到端的执行轨迹，也是理解这个仓库最有用的心智模型。

sequenceDiagram
participant CLI as CLI
participant Boot as Profile and Loader
participant Runtime as Context and Fibers
participant Agent as AgentLoop
participant Model as DeepSeek
participant Tools as Editor and Bash

CLI->>Boot: CommandLineArgs(task, workspace, api-key-file)
Boot->>Runtime: load Profile, Bundles, and Plugin Fibers
Runtime->>Agent: activate AgentLoop and register AgentFactory
Runtime->>Agent: Headless Runner calls agents.create(workspace)
Agent->>Model: Model Step 1 with Session Events and Tool definitions
Model->>Tools: Tool Calls for editor and bash
Tools->>Agent: Tool Results become Session Events
Agent->>Model: later Model Step with prior Tool Results
Model->>CLI: final assistant response
CLI->>Runtime: dispose Fibers in reverse order

下面是同一条轨迹，附上具体代码位置。

1. CLI 在 nano_dsh/__main__.py 中解析 task、--workspace 和 --api-key-file。它解析路径并创建 CommandLineArgs。
2. main() 把 cmdline_args 作为根 Service 传给 nano_dsh/boot.py。它选择 profiles/headless.toml。
3. Profile 列出 bundles/base.toml 和 bundles/headless.toml。nano_dsh/loader.py 按这个顺序读取它们，并导入每个插件模块。
4. Context 为每个插件创建一个 Fiber。每个 Fiber 先发出 PENDING。只有当所有必需的 Service 都可用后，Fiber 才会变成 ACTIVE。正常顺序是 sessions、agents、tools、bash、editor、deepseek、agent_loop、headless_startup 和 headless_runner。
5. deepseek 读取单行密钥文件并提供 llm。一旦 sessions、agents、tools 和 llm 就绪，nano_dsh/plugins/agent_loop.py 就会激活。它注册 AgentFactory，但此时还不创建 Agent。
6. nano_dsh/plugins/headless_runner.py 是 Driver。它用 llm.system_prompt 和 User Task 启动 Execution Trace。然后调用 agents.create(workspace).run(task)。工厂创建一个新的内存 Session。
7. Agent 追加一条用户 Session Event，并通过 nano_dsh/plugins/deepseek.py 发送 Model Step 1。模型可以返回针对 str_replace_editor 和 bash 的 Tool Calls。
8. nano_dsh/plugins/editor.py 或 nano_dsh/plugins/bash.py 执行每次调用。可预期的拒绝会返回 ToolOutput(content, failed=True)。ToolsService 将其记为失败，并通过 ToolResultEvent 把内容返回给模型。
9. 循环会带着先前的 assistant 事件和 Tool Results 发送后续的 Model Step。当某个 Model Step 没有 Tool Calls 时，循环停止。它要求并返回非空的最终内容。
10. boot() 成功后，main() 调用 context.dispose()。正常清理按逆序访问 Fibers 和 Effects。意外的 Boot、Plugin、清理、JSON、网络、文件系统、编码或子进程超时错误会直接抛出，并带上原生的 Python traceback。

Execution Trace 从 System Prompt 开始。接着依次打印 User Task、Reasoning Content、assistant content、Tool Calls、Tool Results 和运行时事件。追踪层不记录 Provider API key 或 HTTP headers。Tool 输出原样打印。

2. 最小词汇表

| 术语 | 在 Nano-DSH 中的含义 |
| Profile | 一个 TOML 文件，用于选择一组有序的 Bundles。headless Profile 是 profiles/headless.toml。 |
| Bundle | 一组有序的 Plugin Specifications，以 TOML 表示。它决定 Fiber 的创建顺序，而不是激活顺序。 |
| Plugin | 一种可加载的能力。它的 apply(ctx, config) 函数可以提供 Services，也可以注册 Effects。 |
| Fiber | 一个已应用的 Plugin 实例。它有生命周期状态，并拥有加载期间创建的 Effects。 |
| Service | Context 中一个具名能力。Plugin 依赖的是 Service 名称，而不是具体的 Plugin 身份。 |
| Effect | Fiber 拥有的启动动作，以及可选的 disposer。正常销毁时，disposer 按注册的逆序执行。 |
| Session Event | 一条带类型的内存记录，记录用户输入、assistant 输出或 Tool Result。 |
| Provider | 提供 Service 的 Plugin。DeepSeek Provider 提供 llm。 |
| Tool Call | 模型发出的请求，包含 Tool 名称和 JSON 参数。它会变成一次 Tool Execution，然后变成一个 Tool Result。 |

3. 分五层读代码

一次读一层。每一层回答不同的问题。

1. Apps

- 文件：nano_dsh/__main__.py、nano_dsh/plugins/headless_startup.py 和 nano_dsh/plugins/headless_runner.py。
- 输入：命令行任务、Workspace 路径和 API-key-file 路径。
- 输出：标准输出上的最终 assistant 文本，以及标准错误上的完整 Execution Trace。
- 为什么存在：这一层校验面向用户的输入，并启动恰好一次 headless Agent Run。Runner 是 Driver。只有在装配提供其所需的 Services 之后，它才启动 Agent。

2. Boot 与 Bundle 组合

- 文件：nano_dsh/boot.py、nano_dsh/loader.py、profiles/headless.toml、bundles/base.toml、bundles/headless.toml。
- 输入：根 Services 和选定的 Profile。
- 输出：组装好的 Context，其中每个已启用的 Fiber 都是 ACTIVE。未解析的 Fiber 会触发内部 assert 失败。
- 为什么需要它：它让应用组合变成声明式的。它也说明 Bundle 决定创建顺序，而 Service 的可用性决定激活顺序。

3. Cordis 运行时

- 文件：nano_dsh/cordis.py、nano_dsh/contracts.py。
- 输入：Plugin Specifications、所需的 Service 名称、Plugin 的 apply 函数。
- 输出：活跃的 Fiber、已发布的 Service、Fiber 拥有的清理逻辑。
- 为什么需要它：这是最小化的动态生命周期。Consumer 可以保持 PENDING，等 Provider 到来时激活，Service 消失时回到 PENDING，再回来时重新激活。正常清理按注册的逆序运行 disposer。

4. 智能体核心

- 文件：nano_dsh/plugins/agents.py、nano_dsh/plugins/sessions.py、nano_dsh/plugins/tools.py、nano_dsh/plugins/agent_loop.py、nano_dsh/plugins/bash.py、nano_dsh/plugins/editor.py。
- 输入：任务、Workspace、llm Service、已注册的 Tool 定义。
- 输出：只追加的 Session，以及第一个不带 Tool Calls 的 Model Step 的非空内容。带 Tool Calls 的 Model Step 内容可以为 null。可预期的 Tool 拒绝返回 ToolOutput(content, failed=True)。
- 为什么需要它：这一层把 AgentFactory 注册和 Agent 创建分开。它也让顺序执行的 Tool 和 Session 状态独立于服务商的传输格式。

5. 服务商

- 文件：nano_dsh/plugins/deepseek.py。
- 输入：Session Events、Tool 定义、单行 API key。
- 输出：规范化的 assistant 输出，包含最终内容、可选的 Reasoning Content、零个或多个 Tool Calls。
- 为什么需要它：这是智能体核心与 DeepSeek Chat Completions 协议之间的边界。它让 Reasoning Content 在用到 Tool 的 Model Step 之间保留下来，同时不让核心依赖协议消息。

4. 快速开始

要求：Python 3.12 和 DeepSeek API key。生产代码除 Python 标准库外没有运行时依赖。

在仓库根目录下，创建隔离的 Python 环境并安装本地命令：

python3.12 --version
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

创建 .key，里面恰好一行非空内容。这一行就是 API key。不要加引号，也不要加多余的行。

printf '%s\n' 'your-api-key-goes-here' > .key
mkdir -p "$PWD/../nano-dsh-workspace"
nano-dsh "Inspect the Workspace and describe its files." --workspace "$PWD/../nano-dsh-workspace" --api-key-file "$PWD/.key"

命令行会自己选择 headless 配置档。你不用传配置档参数。--workspace 必须指向已存在的目录。默认工作区是当前目录。默认 API-key 文件是当前目录下的 .key。

5. 测试

附带的 Live Acceptance Suite 使用三个一次性 Bug Fixture：一个逻辑错误、一个边界错误、一个缺失实现。验收时，每次运行都必须使用真实的 DeepSeek API，调用 str_replace_editor 和 bash，把工具结果返回给后续的模型步骤，通过 fixture 的 unittest 套件，并以最终助手文本结束。

这样运行： bash
python examples/example.py --api-key-file .key

成功的场景开头是这样： text === SYSTEM === You are a coding agent. ... === USER === Correct the inventory availability calculation. ... === REASONING === ... === TOOL CALL === ... === TOOL RESULT === ... === ASSISTANT === ... logic-bug: PASS

三个 fixture 都重复同样的序列。最后一行是 Summary: 3/3 PASS。把标准输出通过 tee 保存完整记录： bash
python examples/example.py --api-key-file .key | tee example-output.log

脚本对每个 fixture 只尝试一次，不会自动重试。

引用

如果你觉得这个仓库有用，请这样引用： bibtex
@misc{mu2026nanodsh,
author = {Guohong Mu},
title = {Nano-DSH: A Minimal Python Reconstruction of DeepSeek Harness},
year = {2026},
howpublished = },
}