. 项目定位与总体印象
DeepSeek Harness 是什么：一切皆插件（all-plugin）的 Cordis Agent Harness，开发者预览阶段
多端形态：CLI（apps/cli）、Web（apps/web）、Desktop（apps/desktop + desktop-host）
技术栈：TypeScript + pnpm workspace monorepo + Node.js，C++ 内核（cpp_src/）与 Python SDK（python/）并存
素材来源：根 README.zh.md、docs/architecture.md

1. 基石：Cordis 插件范式
   Cordis 是什么：来自“时空组合性”论文的底层框架（vendor/ 内 vendored 副本）
   核心机制：ctx 注入、Service Definition/Provider、注册即副作用（ctx.effect() / ctx.on()）、Waterfall 监听链
   为什么选它：对比传统依赖注入 / Hook 框架
   素材来源：docs/cordis-primer.md（有中文版）
2. 运行时三层架构（全文核心章节）
   核心层（packages/core）：agent-loop、Session Event Log、prompt assembly、tool runtime——只依赖接口，不 import 具体 Provider
   能力层：ctx.llm / ctx.tools / ctx.sessions 等 Provider 实现，模型调用三段式 prepare-call → stream → finish
   投影层：Session Projection 提供有类型状态读取，禁止遍历原始事件日志
   素材来源：docs/architecture.md 的 Core packages / Turn flow / Events 三节
3. 事件与持久化模型（最值得深写的部分）
   durable vs live 严格分离：session/event/* 可恢复事实 vs agent/* 进程内协调事件
   关键不变量：“模型可见 ⟺ 可从 Session Log 重建”；失败尝试写 assistant/attempt 而非 assistant/message
   工具执行管道固定顺序：tools/pre-execute → guards → execute → finalizeContent() → tools/result
   格式版本策略：SESSION_FORMAT_VERSION、SQLite 单调 SCHEMA_VERSION、相邻迁移只增不改
   素材来源：docs/event-producer-consumer.md、docs/tool-execution-pipeline.md、docs/persistence-catalog.md、docs/session-format-status.md
4. 能力接缝（Capability Seam）与包生态
   Seam 定义：Service Definition / Provider / Consumer 三角色齐备
   换 Provider 即整体迁移的例子：替换 fs/subprocess Provider 可让 Shell、终端、LSP 整体跑在远程
   57 个包组的分类学（建议按职能归组讲述，不要逐个列）：
   执行域：shell、subprocess、ssh、terminal、ptc-runtime、sandbox
   环境域：fs、lsp、workspace、sandbox
   智能域：subagent、workflow、skill、plan、todo、goal、compaction
   交互域：interaction、feedback、acp、webhook
   集成域：mcp、web（搜索/抓取）、computer-use、browser-use
   素材来源：docs/capability-seams.md、packages/README.md、docs/module-graph.md
5. 配置与组合
   Profile 与 Bundle 机制；配置叠加顺序：Bundle 序列 → Profile patch → $DSH_HOME patch → –patch；patch 是整块替换
   应用启动规则：只有 dsh profile 能启动 Node 应用，禁止包 bin / SDK argv 逃逸（安全设计）
   素材来源：docs/architecture.md、docs/config-catalog.md
6. 工程体系（体现仓库成熟度的章节）
   构建：tsc（lib/types）+ tsdown（runtime bundle），source plane vs artifact plane 分离
   测试分层：unit → test:coverage（100% 覆盖门禁）→ snapshot（录制回放）→ expected → e2e（真实 API）→ web/gui
   质量门禁：oxlint、hygiene、doc-sync、duplication 检测、中英双语文档同步
   防御性模式与 Agent Notes 决策记录文化
   素材来源：docs/testing.md、docs/development.md、docs/defensive-patterns.md、根 package.json scripts
7. 评价与思考（如果你要写“分析”，这章决定文档档次）
   亮点：接口驱动带来的可替换性、事件溯源式持久化、工程门禁之严格
   代价与权衡：包粒度极细的认知成本、pre-stable API 的迁移负担、vendoring 的维护成本
   风险提示：开发者预览期的兼容性破坏（参考 SAFETY.md）
   两个建议
   按受众裁剪：如果面向“想用 DSH 的开发者”，把第 3、5 章压缩成概览，扩写第 6 章和 CLI/Web 使用；如果面向“架构研究/技术分享”，保持现状甚至把第 4 章拆成两章。
   写作时的阅读顺序：docs/architecture.md → docs/cordis-primer.zh.md → docs/glossary.zh.md → docs/capability-seams.zh.md → 挑 docs/subsystems/ 里与你主题最相关的几篇（共 63 篇，不必全读）。注意 docs 大多有 .zh.md 中文版。
   需要我基于这个大纲直接开始写某一章的内容吗？

DeepSeek Harness 核心流程分析

项目定位

DeepSeek Harness（CLI 名称 dsh）是 DeepSeek AI 开发的开源 Agent 运行时框架，MIT 协议，TypeScript + Cordis 插件架构。核心理念：一切皆插件——模型、工具、技能、会话、沙箱、存储、Agent 循环、调度器、甚至 UI，全部是可替换的 Cordis 插件。发布首日 5.5 万 GitHub Star，被称为 GitHub 史上最快涨星项目。

五部分核心组件

DeepSeek Harness 的核心组件可以分为 5 个部分：

1. 上下文工程：append-only 会话日志（模型看到的每一条消息都可从日志重构，运行时不变量断言验证）、四种运行模式（Standard/Code/Minimal/Creator）不同上下文策略、Trajectory 视图按来源查看日志
2. 工具/插件系统：Cordis 微内核（只负责插件挂载/卸载/依赖管理）+ 一切皆插件（模型适配器、工具注册表、技能系统、沙箱、存储、Agent 循环、调度器、UI 全部可替换）
3. 状态持久化：append-only 事件日志（单一日志文件，支持 resume/fork/search/replay）、插件化存储层、会话状态管理
4. 权限/安全模型：fail-closed 沙箱阶梯（read-only → workspace-write → danger-full-access，拿不到沙箱后端就拒绝执行）、argv wrapping 命令限制、审批服务缺失即拒绝
5. 可观测性和审计：会话日志即不变量（运行时断言验证 outgoing request 与 session.deriveMessages() 字节匹配）、无 Key 回放测试（真实会话日志作为 fixture，mock 模型确定性回放）、Trajectory 视图

一次完整请求流程

用户通过 Web UI（http://127.0.0.1:3080）或 CLI 发起请求。

第一步：插件加载与模式选择。 Cordis 微内核加载配置的插件集。四种预设模式加载不同插件组合：Standard（完整编码 Agent，文件编辑+shell+搜索+技能+规划+子Agent+工作流）、Code（Standard 全部能力 + Code Mode SDK，模型生成 TypeScript 程序组合多步操作）、Minimal（只有持久化 bash + str_replace_editor，模型评测脚手架）、Creator（Standard + 运行时检查 + 内存中插件实验）。

第二步：构建系统提示词。 根据运行模式注入对应的工具描述和技能列表。Minimal 模式只有两个工具的描述，Standard 模式注入完整工具目录。

第三步：Agent 循环。 插件化的 Agent 循环（本身也是 Cordis 插件，可替换）。模型接收用户输入 → 推理 → 输出工具调用或文本响应。工具调用时：解析调用 → 沙箱策略匹配 → 执行 → 结果追加到上下文。

第四步：工具执行与沙箱。 工具执行按调用解析沙箱策略：read-only（只读）、workspace-write（推荐默认）、danger-full-access（完全访问）。Linux 优先探测 bubblewrap，回退到原生 Landlock 启动器；macOS 使用 seatbelt；Windows 使用 write-restricted token。关键设计：fail-closed——如果请求了受限模式但没有可用的沙箱后端，直接抛 SANDBOX_UNAVAILABLE 拒绝执行，不会裸奔。

第五步：会话日志记录。 每次 LLM 调度时，packages/core/agent-loop/src/invariant.ts 中的断言验证 outgoing request 的 messages 与 session.deriveMessages() 字节匹配。记录内容包括：系统提示词、思维链（reasoning）、工具调用与结果、子 Agent 调度、每一次上下文注入。

第六步：上下文压缩。 当上下文接近窗口限制时，触发压缩策略。具体实现取决于加载的插件组合。

第七步：子 Agent 调度。 支持生成子 Agent 处理子任务。子 Agent 的调度记录同样写入 append-only 日志。

第八步：返回结果。 流式推送 Agent 输出到 Web UI 或 CLI。

关键设计决策

1. 一切皆插件。 连 Agent 循环都是可替换的 Cordis 插件。这在所有 Agent 框架中是独一无二的——大多数框架的 Agent 循环是核心，不可替换。DSH 把它降维成了一个插件。

2. 会话日志即不变量。 模型看到的每一条消息，都必须能从 append-only 会话日志中重构。这不是约定，是运行时强制执行的——每次 LLM 调度时断言验证。这是目前 Agent 运行时工程中最有纪律性的设计之一。

3. 四种运行模式。 Standard（生产）、Code（批量操作）、Minimal（评测）、Creator（开发）。Minimal 模式是最大的看点——只有 shell 和文件编辑器，最小化 harness 优势来做公平的模型对比。DeepSeek V4-Flash 的发布 benchmark 就是用 Minimal 模式跑的。

4. Fail-closed 沙箱。 拿不到沙箱后端就拒绝执行，不会降级为裸奔。缺少审批服务同样意味着拒绝，而不是挂起。这是安全设计的黄金标准。

5. 无 API Key 的测试回放。 真实会话日志作为 fixture，从中派生确定性 mock 模型。同一个 .jsonl 日志文件既是 replay 输入又是期望输出。CI 中不需要 API key，不需要不稳定的 LLM-as-judge。循环行为的任何偏移都会表现为日志 diff。

6. 模型无关。 默认 catalog 支持 DeepSeek V4，但模型适配器是插件，支持 Anthropic、OpenAI、Bedrock、Vertex、Azure、Codex、自定义端点。第一天就支持竞品模型。

7. 沙箱升级作为模型 UX。 bash 工具的描述教会模型：被拒绝是一种策略结果，正确的应对是在同一轮重试时带上更宽的 sandbox_permissions 和 justification，触发用户的审批提示。

8. 1M 上下文 + 256K 输出。 默认模型参数：上下文窗口 1,000,000 token，最大输出 256,000 token。这是 DeepSeek 自己的工具链对 V4 的假设。

9. vendored Cordis fork。 DeepSeek 不仅依赖 Cordis，还 source-vendored 了一个 fork，pin 在 cordis 4.0.0-rc.7，打了 18 个本地 patch，重命名到 @deepseek-ai scope 下，完全拥有框架层。

与 Claude Code 的对比