DEEPSEEK HARNESS · OFFLINE TUTORIAL
01 · 顶层架构
先建立 DSH 的世界观
1. DSH 不是“一个巨型 Agent 类”
最常见的错误路径是：找到 agent.ts → 找 while-loop → 找模型调用 → 找工具调用 → 以为项目已经看懂。DSH 的关键不在一个巨型类，而在插件组合、可替换 Service、事件扩展点、可回放 Session Log。
核心规则：如果一个需求可以通过 Service / Provider / Event / Guard / Scope 表达，就不要先去改 Agent Loop。
2. 五层地图
| 层 | 职责 | 典型内容 |
|---|---|---|
| Composition | 把插件组装成运行时 | CLI、Boot、Bundle、Profile |
| Core Spine | 执行主干 | Session、Prompt、Tools、Agent、Agent Loop、LLM |
| Capabilities | 具体可替换能力 | FS、Shell、Sandbox、LSP、Web、Subagent、Jobs |
| Durability | 可靠性与横切能力 | Persistence、Compaction、Guard、Telemetry |
| Surface | 产品与协议表面 | Host、Client、API、SDK、Web UI |
3. 六条“宪法”
- Everything is a Plugin。
- 依赖 Service Definition，不依赖 Provider。
- 模型真正看到的上下文应当能从 Session Log 重建。
- Policy 通过 Event / Guard 插入，Mechanism 留在 Service。
- Agent Loop 只拥有 generic control-flow。
- Registration 必须有生命周期。
4. 新需求应该落在哪里
| 新需求 | 优先落点 |
|---|---|
| 新模型厂商 | LLM Adapter / Provider |
| 新工具 | Tool Plugin |
| 远程文件系统 | ctx.fs Provider |
| 工具权限 | tools/* Event / Guard |
| 先读后写规则 | fs/* Policy |
| 需要长期保存的新事实 | SessionEvent |
| 仅单个 Agent 生效 | agent-scoped Context |
| 所有 Agent 的通用控制语义 | 才考虑 Agent Loop |