DeepSeek Harness 学习站

外观

附录 B · 源码地图 ​

前置阅读：附录 A · 术语表

本源码地图提供 DeepSeek Harness 完整源码导航，按包组和功能分类。

B.1 仓库顶层结构 ​

deepseek-harness/
├── AGENTS.md              # 项目级 Agent 指南（CLAUDE.md symlink）
├── package.json           # 主仓配置
├── pnpm-workspace.yaml    # workspace 配置
├── tsconfig.base.json     # TS 基础配置 + paths 映射
├── tsconfig.host.json     # Host 聚合
├── tsconfig.client.json   # Client 聚合
├── tsdown.config.ts       # 运行时 bundle 配置
├── knip.json              # knip 配置
├── .oxlintrc.json         # oxlint 配置
├── vendor/                # Vendored Cordis 源码
├── packages/              # 54 个包组
├── python/                # Python SDK
├── native/                # node-addon-landlock-run
├── examples/              # Runnable cordis.yml leaves
├── .agents/               # Agent workflows 和 notes
├── docs/                  # 架构、catalogs、postmortems、cookbook
├── scripts/               # 仓库 gates 和 generators
├── website/               # VitePress 文档站
├── apps/                  # 应用入口
│   ├── cli/               # CLI 入口
│   └── web/               # Web 入口
└── study-docs/            # 本学习站

B.2 packages/ 包组导航 ​

core/ — 产品 API 脊柱 ​

包职责关键文件
sessionSession 事件溯源src/types.ts（SessionEventMap）、src/repair.ts（崩溃恢复）
system-prompt系统提示装配src/index.ts
tools工具注册表与执行管道src/index.ts（ToolRuntime/defineTool）
agentAgentRegistrysrc/index.ts
agent-loopAgent Loop 实现src/index.ts

llm/ — LLM 能力 ​

包职责关键文件
llmLlmRuntime Service Definitionsrc/index.ts、src/assembler.ts（BlockAssembler）
llm-deepseekDeepSeek providersrc/adapter.ts（DeepSeekAdapter）

shell/ — Shell 能力 ​

包职责关键文件
shellShellExecutor Service Definitionsrc/index.ts
bash-local本地 bash providersrc/index.ts
bash-sandbox沙箱 bash providersrc/index.ts
pwsh-local本地 pwsh providersrc/index.ts
tool-bashbash 工具 Consumersrc/index.ts

fs/ — 文件系统能力 ​

包职责关键文件
fsFileSystem Service Definition + 策略src/index.ts
tool-fsfs 工具 Consumersrc/index.ts
tool-fs-searchfs 搜索工具src/index.ts

subprocess/ — 子进程能力 ​

包职责关键文件
subprocessSubprocessRuntime Service Definitionsrc/index.ts

terminal/ — 持久终端 ​

包职责关键文件
terminal持久会话src/index.ts

web/ — Web 能力 ​

包职责关键文件
webWebRuntime Service Definitionsrc/index.ts
tool-webweb 工具 Consumersrc/index.ts

lsp/ — LSP 能力 ​

包职责关键文件
lspLsp Service Definitionsrc/index.ts

compaction/ — 压缩能力 ​

包职责关键文件
compactionCompactionEngine Service Definitionsrc/index.ts

subagent/ — 子代理能力 ​

包职责关键文件
subagentSubagentRuntime Service Definitionsrc/index.ts

workflow/ — 工作流能力 ​

包职责关键文件
workflowWorkflowEngine Service Definitionsrc/index.ts

skill/ — 技能能力 ​

包职责关键文件
skillSkillService Service Definitionsrc/index.ts

context/ — 请求上下文 ​

包职责关键文件
contextrequest-context pluginssrc/index.ts

bundle/ — 可安装 bundle ​

包职责关键文件
bundlebundle 框架src/index.ts
basebase bundle patchcordis.patch.yml
web-appweb-app bundle patchcordis.patch.yml
headlessheadless bundle runnersrc/index.ts

preset/ — Preset 组合 ​

包职责关键文件
agent-presetsAgentPresets 服务src/index.ts、src/mount.ts、src/preset.ts、src/discovery.ts

guard/ — 循环卫生 ​

包职责关键文件
guardloop-hygiene + tool-timeoutsrc/index.ts

self-modification/ — 自修改 ​

包职责关键文件
self-modificationagent 检查/mount 自己的 pluginssrc/index.ts

hooks/ — Hook 桥接 ​

包职责关键文件
hooksClaude Code/Codex hook bridgessrc/index.ts

session/ — 持久 session 数据 ​

包职责关键文件
session-persistencePersistenceCoordinatorsrc/coordinator.ts
session-persistence-sqliteSQLite 后端src/schema.ts
session-projectionProjectionDefinitionsrc/index.ts
session-titlessession 标题src/index.ts
session-telemetrysession 遥测src/index.ts

identity/ — 匿名身份 ​

包职责关键文件
identityanonymous identitysrc/index.ts

settings/ — 用户设置 ​

包职责关键文件
settingsuser-settings capabilitysrc/index.ts

credentials/ — 凭证引用 ​

包职责关键文件
credentialscredential-reference capabilitysrc/index.ts

acp/ — ACP 服务器 ​

包职责关键文件
acpautomation-only ACP serversrc/index.ts

interaction/ — 交互能力 ​

包职责关键文件
interactionapproval/interaction capabilitiessrc/index.ts

boot/ — 共享启动 ​

包职责关键文件
app-bootshared app-bin gluesrc/profile.ts（profile 组合）

sdk/ — JSON-RPC 协议 ​

包职责关键文件
protocolwire types + transportsrc/types.ts、src/transport.ts
serverJSON-RPC 方法src/server.ts
client子进程管理 + 通知订阅src/client.ts

client/ — Web 客户端 ​

包职责关键文件
runtime数据对象层（React-free）src/client/contract/conversation.ts、src/client/conversation/definition-registry.ts、src/client/conversation/event-registry.ts
web-react渲染机制层src/boot.tsx
ui-conversation对话 UIsrc/client/conversation-nodes/assistant.ts、inbox.ts、message.ts
ui-deliverables交付物 UIsrc/client/turn-deliverables.ts
ui-goal目标 UIsrc/client/goal-command-input.ts
ui-theme主题src/styles/
ui-workspace工作区 UIsrc/client/
ui-sidebar侧边栏 UIsrc/client/
ui-user-questions用户问题 UIsrc/client/

api/ — 远程 BFF ​

包职责关键文件
remotesBFF assemblysrc/index.ts
gatewayTypert RPC gatewaysrc/index.ts

typert/ — 类型图 ​

包职责关键文件
typerttype graph generator/loader/registrysrc/index.ts

e2b/ — E2B POC ​

包职责关键文件
e2bsandbox + FS/subprocess adapterssrc/index.ts

todo/ — Todo 工具 ​

包职责关键文件
todotodo_write toolsrc/index.ts

plan/ — Plan 模式 ​

包职责关键文件
planplan mode as logged statesrc/index.ts

examples/ — 示例 bundle ​

包职责关键文件
examplesdemo bundlescordis.yml

support/ — 开发/测试基础设施 ​

包职责关键文件
supportdev/test infrastructuresrc/index.ts

util/ — 零依赖工具 ​

包职责关键文件
utilzero-dependency utilitiessrc/index.ts

B.3 apps/ 应用入口 ​

cli/ ​

CLI 入口。

文件职责
src/bin.tsCLI bin 入口
config/agent-presets/四个 shipped presets（minimal/standard/code/cordis）
tests/snapshots/interactive-terminal journey snapshots

web/ ​

Web 入口。

文件职责
tests/snapshots/browser-rendered web GUI journey snapshots

B.4 docs/ 文档导航 ​

顶层文档 ​

文件职责
architecture.md架构总览（≤1,800 words）
development.md贡献者设置、日常 workflow、CI 摘要
cordis-primer.mdCordis 五大思想
glossary.md术语表
testing.md测试策略
defensive-patterns.md防御性模式

subsystems/ ​

每个子系统一个 reference page：类型定义、语义、生成的 Cordis API。

cookbook/ ​

文件职责
adding-a-package.md添加新包完整 checklist
adding-a-tool.md工具开发参考
adding-a-conversation-node.md添加 Web Client conversation node
extension-cookbook.md扩展 cookbook

postmortem/ ​

事故故事。0001-acp-default-export-drops-inject.md 是经典案例。

.agents/notes/ ​

Agent Notes：active decision records。

子目录职责
implemented/shipped reality（present tense）
archived/frozen history

B.5 关键源码快速定位 ​

Session 核心 ​

内容位置
SessionEventMappackages/core/session/src/types.ts
崩溃恢复packages/core/session/src/repair.ts
SurfaceEventTypepackages/core/session/src/types.ts
SESSION_FORMAT_VERSIONpackages/core/session/src/types.ts
SCHEMA_VERSIONpackages/session/session-persistence-sqlite/src/schema.ts
APPLICATION_IDpackages/session/session-persistence-sqlite/src/schema.ts

Agent Loop ​

内容位置
AgentRegistrypackages/core/agent/src/index.ts
Agent Looppackages/core/agent-loop/src/index.ts
Contract regressionspackages/core/agent-loop/tests/contract-regressions.spec.ts

工具 ​

内容位置
ToolRuntimepackages/core/tools/src/index.ts
defineToolpackages/core/tools/src/index.ts
扩展点packages/core/tools/README.md

LLM ​

内容位置
LlmRuntimepackages/llm/llm/src/index.ts
BlockAssemblerpackages/llm/llm/src/assembler.ts
StreamChunkpackages/llm/llm/src/types.ts
DeepSeekAdapterpackages/llm/llm-deepseek/src/adapter.ts
mapUsagepackages/llm/llm-deepseek/src/adapter.ts

能力缝 ​

缝Service Definition
shellpackages/shell/shell/src/index.ts
subprocesspackages/subprocess/subprocess/src/index.ts
fspackages/fs/fs/src/index.ts
llmpackages/llm/llm/src/index.ts
webpackages/web/web/src/index.ts
lsppackages/lsp/lsp/src/index.ts
compactionpackages/compaction/compaction/src/index.ts
subagentpackages/subagent/subagent/src/index.ts
workflowpackages/workflow/workflow/src/index.ts
skillpackages/skill/skill/src/index.ts

持久化 ​

内容位置
PersistenceCoordinatorpackages/session/session-persistence/src/coordinator.ts
SQLite schemapackages/session/session-persistence-sqlite/src/schema.ts
ProjectionDefinitionpackages/session/session-projection/src/index.ts

Preset ​

内容位置
AgentPresets 服务packages/preset/agent-presets/src/index.ts
mount 守卫packages/preset/agent-presets/src/mount.ts
preset 类型packages/preset/agent-presets/src/preset.ts
preset 发现packages/preset/agent-presets/src/discovery.ts
四个 shipped presetsapps/cli/config/agent-presets/

Bundle ​

内容位置
base bundle patchpackages/bundle/base/cordis.patch.yml
web-app bundle patchpackages/bundle/web-app/cordis.patch.yml
headless bundle runnerpackages/bundle/headless/src/index.ts

Boot ​

内容位置
profile 组合packages/boot/app-boot/src/profile.ts

Web 客户端 ​

内容位置
ConversationNodeDefinitionpackages/client/runtime/src/client/contract/conversation.ts:170-228
ConversationDefinitionRegistrypackages/client/runtime/src/client/conversation/definition-registry.ts
ConversationEventRegistrypackages/client/runtime/src/client/conversation/event-registry.ts
Web Shell bootpackages/client/web-react/src/boot.tsx
Goal Command Input 示例packages/client/ui-goal/src/client/goal-command-input.ts
Assistant Nodepackages/client/ui-conversation/src/client/conversation-nodes/assistant.ts
Inbox Nodepackages/client/ui-conversation/src/client/conversation-nodes/inbox.ts
Message Nodepackages/client/ui-conversation/src/client/conversation-nodes/message.ts
Deliverables Definitionpackages/client/ui-deliverables/src/client/turn-deliverables.ts

SDK ​

内容位置
wire typespackages/sdk/protocol/src/types.ts
JsonRpcLineTransportpackages/sdk/protocol/src/transport.ts
HarnessSdkJsonRpcServerpackages/sdk/server/src/server.ts
HarnessClientpackages/sdk/client/src/client.ts

ACP ​

内容位置
ACP serverpackages/acp/acp/src/index.ts

B.6 配置文件导航 ​

TypeScript ​

文件职责
tsconfig.base.json基础配置 + paths 映射（@deepseek-ai/dsh-* 通配符）
tsconfig.host.jsonHost 聚合
tsconfig.client.jsonClient 聚合
packages/<group>/<pkg>/tsconfig.json包级配置（extends base，rootDir src，outDir lib/types）

构建工具 ​

文件职责
tsdown.config.ts运行时 bundle 配置
knip.jsonknip 配置
.oxlintrc.jsonoxlint 配置
vitest.config.tsvitest 配置

Workspace ​

文件职责
pnpm-workspace.yamlworkspace 配置（globs packages/*/*）
package.json主仓配置

Cordis ​

文件职责
examples/headless-agent/cordis.yml完整 profile 示例
packages/bundle/base/cordis.patch.ymlbase bundle patch
packages/bundle/web-app/cordis.patch.ymlweb-app bundle patch
apps/cli/config/agent-presets/*/cordis.yml四个 shipped presets

B.7 脚本导航 ​

仓库 gates ​

脚本职责
scripts/check-workspace-constraints.tsworkspace constraints
scripts/run-gates.ts所有文档门禁
scripts/verify-md-links.tsMarkdown 链接检查
scripts/verify-md-wrap.ts一行一段检查
scripts/doc-typecheck.tsfenced ts blocks 编译检查
scripts/verify-type-equiv.ts类型粘贴 drift 检查
scripts/verify-doc-budgets.tswordcount ceilings
scripts/verify-export-jsdoc.tsJSDoc 完整性
scripts/verify-package-invariants.ts包 invariant 检查
scripts/verify-package-readme-limitations.tsKnown Limitations 检查
scripts/publint-all.tspublint
scripts/migrate-packed-session-fixtures.tsfixture 迁移

生成器 ​

脚本职责
scripts/generate-tool-catalog.ts工具 catalog 生成
scripts/generate-config-catalog.ts配置 catalog 生成
scripts/generate-persistence-catalog.ts持久化 catalog 生成
scripts/generate-module-graph.ts模块图生成

B.8 学习路径推荐 ​

入门（第一阶段） ​

  1. 00 · 项目总览
  2. 01 · Cordis 框架基础
  3. 02 · 仓库布局与构建体系
  4. 03 · 启动与组合体系

核心机制（第二阶段） ​

  1. 04 · 会话事件溯源
  2. 05 · Agent 与循环
  3. 06 · 系统提示装配
  4. 07 · 工具注册表与执行管道
  5. 08 · Code Mode 机制

能力缝（第三、四阶段） ​

  1. 09 · 能力接缝模式
  2. 10 · LLM 与 DeepSeek 适配器
  3. 11 · Shell 与 Subprocess 能力
  4. 12 · FS 能力与策略
  5. 13 · Web 与 LSP 能力
  6. 14 · Compaction 与 Subagent 能力
  7. 15 · Workflow 与 Skill 能力

持久化与组合（第五阶段） ​

  1. 16 · Session 持久化与投影
  2. 17 · Preset 与 Profile 组合
  3. 18 · Bundle 与 Patch 层
  4. 19 · Web GUI 与 ACP
  5. 20 · SDK 与 JSON-RPC 协议

实战（第六阶段） ​

  1. 21 · 添加新包与工具
  2. 22 · 添加 LLM 适配器与 Chat 节点
  3. 23 · 测试与门禁

附录 ​

  1. 附录 A · 术语表
  2. 附录 B · 源码地图

B.9 关键 Agent Notes ​

架构 ​

Note职责
2026-06-13-capability-seams.md能力缝 rationale
2026-07-15-agent-initiator-scope.mdagent initiator scope
2026-07-19-gui-web-client-architecture.mdweb client architecture
2026-07-22-slot-type-chain-implementation.mdslot system standard
2026-08-09-client-conversation-node-assembly.mdConversation Node assembly
2026-08-10-session-log-version-mechanism.mdsession log version mechanism

测试 ​

Note职责
2026-06-19-real-api-e2e-ci.mdreal-API e2e CI
2026-06-19-acp-snapshot-tests.mdACP snapshot tests
2026-07-24-web-gui-browser-e2e-lane.mdweb e2e lane
2026-07-30-web-browser-snapshot-ci-gate.mdweb browser CI gate
2026-07-20-gui-testing-system.mdGUI testing system

流程 ​

Note职责
2026-07-04-doc-tiers-and-budgets.mddoc tiers and budgets
2026-07-10-readme-known-limitations-gate.mdREADME Known Limitations gate
2026-08-02-native-github-stacks-and-optional-rebases.mdGitHub stacks
2026-08-08-unified-github-label-taxonomy.mdlabel taxonomy
2026-08-09-concrete-prose-names-actors-and-recorded-facts.mdconcrete prose

Bug fix ​

Note职责
2026-07-28-themed-scrollbars-and-reserved-gutter.mdthemed scrollbars

B.10 vendor/ 导航 ​

Vendored Cordis ​

内容位置
manifest + sync procedurevendor/README.md
Cordis 源码vendor/packages/

Rescope mapping ​

vendored packages 被 rescoped（@deepseek-ai/cordis），private: true。mapping 见 docs/rescope.md。

下一步 ​

本源码地图提供了完整源码导航。回到 首页 或 学习导读 重新开始学习路径。

基于 DeepSeek Harness 源码整理的渐进式学习文档

MIT License · 仅供学习交流