《DeepSeek Harness 源码与架构学习教程》
面向熟悉 JavaScript、TypeScript 和前端工程化，希望建立 Agent Runtime 源码、调试与插件扩展能力的开发者。
30 秒解释
DeepSeek Harness 是一个以 Cordis 插件系统为组合内核的 AI Agent 运行平台：Profile 决定装哪些能力，Agent Loop 调度模型与工具，Session Log 保存可回放事实，Host 与 Browser 各自运行一棵插件树。
5 分钟解释
用户输入经 API 进入 Agent 收件箱（Inbox）；ReactLoopAgent 打开轮次（Turn）并执行一个或多个步骤（Step），从 Session Surface 派生模型历史，装配系统提示词（System Prompt），再由 LlmRuntime 准备并流式调用 Adapter。模型若产生工具意图，ToolRuntime 完成 Schema、权限、批准、Guard、调度和结果规范化，把 tool/result 写回日志，再进入下一 Step。
Web 端不是被动页面：SessionController 用 page() 与 follow() 传输事件，Client Session、Notifier 和 ConversationNodeAssembler 生成不可变快照，React 用 useSyncExternalStore 与 keyed Slot 渲染。最终实践会实现一个 Host 工具 + Browser 卡片的双面插件。
10 张 Archify 交互图
| 范围 | 图解入口 |
|---|---|
| 整体 | 整体系统与插件边界 |
| 第 1 章 | Profile 启动链 |
| 第 2 章 | Cordis 插件生命周期 |
| 第 3 章 | Session Log 与投影 |
| 第 4 章 | 一次 Agent Turn |
| 第 5 章 | System Prompt 装配 |
| 第 6 章 | LLM 流式调用 |
| 第 7 章 | 工具执行与批准 |
| 第 8 章 | Host 到 React 数据流 |
| 二次开发 | workspace_summary 双面插件 |
图均为独立 HTML，可缩放、搜索、追踪关系、切换明暗主题和导出；正文同时保留简短文字流程。
学习目标与周期
完成后应能解释整体架构、沿真实调用链定位源码、运行定向测试、排查一次故障，并独立完成一个小型插件。建议 6–8 周、50–70 小时，顺序是“全景 → 主链 → 调试 → 扩展”。
总导航
证据基线
- 【已验证】本地源码版本：
0.1.2-alpha.4。 - 【已验证】锁定提交：
4e84901e6471b79ec0338099867ebb4606d12bb5。 - 【已验证】旧基线到新版共有 8,212 个文件变化，workspace package 从 221 增至 251。
- 【待确认】需要真实模型 Key 的端到端调用不作为已验证结果。