[AI/Agent/DSH] 源码深度解读: DeepSeek Harness

1 DeepSeek Harness 源码分析

  • 主要编程语言:TypeScript
  • 包管理器:pnpm
  • ...

0. 摘要

  • DeepSeek Harness（dsh） 是 DeepSeek AI 官方开源的 Agent Harness（智能体运行时框架），当前处于 0.1.2-alpha.2 开发者预览版。它不是"一个聊天机器人应用"，而是一套可组合、可插拔的智能体运行时：以 Cordis 插件框架为底座，采用"一切皆插件"架构——模型适配器、工具注册表、会话日志、Agent 主循环本身全部是插件，任何一层都可以通过配置文件替换。

  • 仓库是一个 pnpm monorepo（251 个 @deepseek-ai/dsh-* npm 包 + 9 个 vendor 框架包），TypeScript 为主（约 64.5 万行源码），提供 Web GUI / Headless 一次性运行 / SDK（TS+Python）/ ACP 四类产品形态，内置文件系统、Shell、持久终端、子代理、Web 搜索、技能（Skill）、工作流、后台任务等能力族，并具备 Landlock / Seatbelt / bwrap / Windows ACL 多层进程沙箱。

1. 项目定位（Step 1：README）

📍 定位：DeepSeek AI 官方的开源 agent harness（智能体运行时/框架）
🎯 解决：让"Agent 能力"（模型调用、工具、持久会话、沙箱、子代理、GUI/SDK 接入）
       以插件化、可配置、可替换的方式组装和运行
⭐ 成熟度：developer preview，快速迭代中，明确声明将出现破坏性变更
📄 许可证：MIT（第三方依赖见 THIRD_PARTY_NOTICES.md）
📚 设计基石：Cordis 框架 + 论文《A Programming Paradigm for Spatiotemporal Composability/一个时空可组合性的程序范例》

与竞品的差异点

从 README/架构文档推断：

  • 相比 Claude Code / Codex / OpenClaw 等单进程 Agent，dsh 将框架层（Cordis）源码 vendor 进仓库（可审计、可打补丁、可固定版本），并把产品面拆成 5 种 Profile（web / headless / sdk / sdk-minimal / acp），用"配置文件 patch 叠加"完成组合，而非新增可执行程序。
  • 相比 LangChain/LlamaIndex 等编程框架库，dsh 强调"可运行的完整 harness"：自带模型接入、工具集、持久会话、沙箱、权限审批、Web UI，可直接 npx @deepseek-ai/dsh web 跑起来。

仓库元数据：

项 值
根包 @deepseek-ai/dsh-root v0.1.2-alpha.2
版本基线 git tag dsh-v0.1.2-alpha.2（最新 release commit 0a53fb55be）
分支 master（唯一主干）
默认浏览器服务 http://127.0.0.1:3080
主要语言 TypeScript（ESM, "type": "module"）
包管理器 pnpm@11.7.0
Node 引擎 ^22.19.0 || >=24.0.0

2. 仓库规模

对仓库做本地扫描（排除 .git / node_modules / vendor / snapshots / .dsh-build / dist / lib / coverage / patches 后）：

语言 文件数 行数
TypeScript 3,016 644,793
Markdown（文档/README/说明） 2,657 238,385
TypeScript/React（*.tsx，Web 前端） 299 79,472
YAML（Cordis 配置 patch / CI） 1,380 37,338
JSON（清单/目录） 604 30,638
Python（Python SDK） 20 5,501
JavaScript（构建/脚本） 41 4,700
Shell 5 392
合计 8,356 ~104 万行（含文档）
  • TypeScript 为绝对主体，约 64.5 万行；文档量巨大（23.8 万行 Markdown），且大量文档为生成产物（catalog / module-graph 等），说明工程化、文档化程度极高。
  • packages/ 下共 251 个包；apps/ 下 2 个（cli、web）；vendor/ 下 9 个框架包(cordis/cosmokit/group/include/hmr/loader/logger-console/schemastery/timer)。

3. 技术栈与工程化基础（Step 5：依赖）

3.1 依赖载体

载体 内容
pnpm-workspace.yaml workspace 聚合：vendor/*、packages/*/*、native/landlock-run、apps/*、website、python/sdk-runtime
package.json（根） dev 工具链：TypeScript 6、tsdown（打包）、vitest 4（测试）、oxlint（lint）、lefthook（git hooks）、tsx（TS 直跑）、mermaid（文档图）、jscpd（查重）
apps/cli/package.json 产品依赖地图：约 70 个 workspace 插件包 + commander、js-yaml
vendor/README.md Cordis 全家桶 vendor 清单及本地修改日志（19 项）

3.2 关键外部依赖（决定项目"基因"）

  1. @deepseek-ai/cordis（vendor, 4.0.0-rc.7） —— 整个框架的根基：插件贡献服务、类型化事件、可逆 effect。
  2. @deepseek-ai/cordis-plugin-loader / include / hmr / timer / group / logger-console（vendor） —— 配置加载、patch 叠加、热重载、定时。
  3. @earendil-works/pi-ai —— 可选的 LLM 多 Provider 后端（llm-pi-ai），携带模型目录。
  4. node-pty / koffi —— 持久 PTY（含 Windows ConPTY）、Windows 上的 JSONL 写穿耐久化。
  5. @anthropic-ai/claude-agent-sdk / @openai/codex —— 可选的 Claude Code / Codex 子代理 Provider（hooks/ 与 subagent/ 族）。
  6. 原生组件：native/landlock-run（C11，~300 行，musl 静态链接）—— Linux Landlock 自限后 exec 启动器。

3.3 技术复杂度评估

📊 复杂度：重量级
依赖面极宽：251 个自研包 + 9 个 vendor 框架包 + 外部可选 SDK（pi-ai / codex / claude-agent-sdk / e2b 远程沙箱）。包按"能力族"分 40+ 组，每组有严格的 Service Definition / Provider / Consumer 三层契约。

需要较多背景知识（Cordis 插件模型、事件系统、TS 泛型深度、原生沙箱）才能完全看懂。

4. 目录结构与模块地图（Step 3 输入 + Step 4 输入）

deepseek-harness/
├── apps/                    # 产品装配层（唯一 Node 应用启动器）
│   ├── cli/                 #   @deepseek-ai/dsh  CLI：profile 启动/插件管理/web 别名
│   └── web/                 #   Web 前端产物（Vite 构建，纯静态 shell）
├── packages/                # ★ 251 个 @deepseek-ai/dsh-* 包，按能力族分组
│   ├── core/                #   产品 API 脊梁：session log / system-prompt / tools / agent / agent-loop
│   ├── api/  typert/        #   远程 BFF 装配 + Typert RPC 网关 / 类型图生成
│   ├── llm/  e2b/           #   LLM 能力族（llm + deepseek/pi-ai 双适配器）；E2B 远程运行时
│   ├── session/ session-query/   # 持久会话数据面（JSONL/SQLite 后端、投影、标题、遥测）；会话检索
│   ├── fs/ shell/ terminal/ code-runtime/ lsp/   # 能力族：文件系统/Bash/PTY/代码执行/LSP
│   ├── sandbox/  native/    #   进程隔离：bwrap/Landlock/Seatbelt/Windows ACL
│   ├── skill/  subagent/  jobs/  workflow/  web/  # Skill 技能 / 子代理 / 后台任务 / 工作流 / Web 工具
│   ├── sdk/  acp/  hooks/   #   TS SDK（JSON-RPC）/ ACP 服务器 / Claude Code & Codex 桥接
│   ├── host/  client/       #   Web GUI 宿主管路（HTTP+SPA）/ 浏览器端（shell+UI 插件）
│   ├── boot/  bundle/       #   app 启动胶水 / 可安装的 profile patch 层（base/web-app/headless/sdk-app/acp-app）
│   └── preset/ guard/ extensions/ interaction/ ...  # 预设/循环卫生/运行时自改/人机协作审批
├── docs/                    # ★ 23 万行文档：architecture / subsystems / catalogs（生成）
├── native/landlock-run/     # Landlock 原生 launcher（C11 + 三包 npm 家族）
├── python/
│   ├── sdk/                 #   Python SDK（deepseek-harness-sdk，同协议双子实现）
│   └── sdk-runtime/         #   Python 运行时 wheel（打包 dsh CLI 单 exe）
├── scripts/                 # ★ 大量工程脚本：构建 / 校验 / catalog 生成 / 发布
├── vendor/                  # Cordis 全家桶（cosmokit/schemastery/cordis/loader/include/group/timer/hmr/logger-console）
├── website/                 # 文档站构建
└── snapshots/ patches/ .agents/ .github/   # 快照夹具 / node-pty 补丁 / agent 设计笔记 / CI

4.1 packages/ 能力族分组（40+ 组，每组一个 README 作为权威包地图）

组 职责 代表性 ctx key
core/ 会话日志、提示词装配、工具注册表、Agent 契约与默认主循环 ctx.sessions / systemPrompt / tools / agents / agentLoop
llm/ LLM 能力族：消息/流词汇 + llm-deepseek（官方直连）与 llm-pi-ai（多 Provider）双适配器 ctx.llm
session/ 持久化数据面：JSONL/SQLite 后端、检查点、投影、标题、遥测 ctx.sessionPersistence / sessionProjections
fs/ shell/ terminal/ code-runtime/ lsp/ 文件 / Bash / 持久 PTY / 代码执行 / 语言服务器 能力族 ctx.fs / shell / terminals / codeRuntime / lsp
sandbox/ 进程隔离 seam，bwrap/Landlock/Seatbelt/Windows ACL 后端 ctx.sandbox
skill/ 技能注册表 + 本地 Provider + 模型侧 catalog/loader ctx.skills
subagent/ 子代理 Provider 注册表 + 委派工具（含 Claude Code / Codex / ACP / TS SDK 后端） ctx.subagents
webhook/ 外部事件验证、信任规则、fire-and-forget Workspace Session ctx.webhookRuntime
sdk/ acp/ JSON-RPC 协议 + TS 客户端/服务端；自动化 ACP 服务器 —
host/ client/ Web GUI 宿主（HTTP+SPA）与浏览器端（shell + 44 个 UI 插件） ctx.webServer / connection
bundle/ 可安装的 dsh --profile patch 层：base/web-app/headless/sdk-app/sdk-minimal/acp-app —

5. 架构核心：一切皆插件（Step 4 核心）

5.1 Cordis 底座

Cordis 是 dsh 的框架层：插件向共享 Context 贡献服务、类型化事件与可逆 effect（可随插件卸载而回滚）。架构文档原文强调：

"Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so each is replaceable from configuration. There is no privileged core to patch."

dsh 将 Cordis 源码 vendor 进仓库（重命名为 @deepseek-ai/cordis 等 9 包），并维护一份 19 条的本地修改日志（vendor/README.md），涉及：fiber.ts 生命周期加固（重入清理、卸载快照）、Loader/Include 事务化配置对账、Windows 下 HMR 路径与写穿耐久化、Node 24.12 运行时形状检测修复等。这是本仓库"完全拥有框架层"工程哲学的体现。

5.2 Profile / Bundle 组合机制（最核心的设计）

Profile（配置文件组合） = 一个命名组合，存放在 Harness home（$DSH_HOME/profiles/<name>/）：

  • package.json 中 dsh.profile.bundles 声明有序 bundle 列表 + patchReload 生命周期（live 热重载 / startup 一次性应用）；
  • 用户自己的 cordis.patch.yml 作为个人 patch 层。

Bundle（分发格式） = 一段 Cordis 配置行（patch）+ 其挂载的代码，dsh.bundle 指向 patch 文件。插入的行可被上层继续 patch。

组合顺序（对空根配置 [] 逐层叠加）：

[dsh-base / web-app / headless / sdk-app / sdk-minimal / acp-app 各 bundle patch（按 bundles 顺序）]
    → profile 的 cordis.patch.yml
    → $DSH_HOME/cordis.patch.yml（机器级偏好，最高优先级于 profile 层）
    → --patch overlay 补丁覆盖层（argv 顺序）
    → 遥测开关（DSH_TELEMETRY_DISABLED）
  • patch 按 行 id 定位并整体替换该行配置（不是 merge），"最后写入者胜"；
  • 每层都"可被上层 patch"——用户配置永远能覆盖 bundle 默认值；
  • dsh --profile web --dump-config 可打印组合后的完整树。

核心源码位置：apps/cli/src/profile-boot.ts（composeProfile / composeLive / runProfile）、packages/boot/app-boot/、packages/bundle/base/cordis.patch.yml（base bundle 的"插件行清单"，含逐行注释）。

5.3 事件系统（三个域，作为扩展点）

域 语义 例子
Session events 追加到日志的持久事实，经 session/event 广播，重载后仍存在 turn/*、step/*、user/message、assistant/*、tool/*
Agent events 携带活动 Agent 的实时观察/拦截 agent/*：inbox / step / status / request / validation / continuation
Capability events 在不 import 主循环的前提下，把策略/适配器挂到 seam(缝) 上 fs/*、tools/*、telemetry/*

其中 agent/pre-step、agent/request、llm/stream、tools/pre-execute|execute|post-execute 是 waterfall（瀑布式）事件，监听者必须调用 next() 委托；agent/turn-stopping 是串行事件。

5.4 Turn / Step 主循环（默认驱动 core/agent-loop）

  • Turn=一次输入消费周期；Step=一次模型请求+其引发的工具调用，一个 Turn 含 0..N 个 Step
turn/start
  ├─ 认领 next-step 输入 + 一条排队消息
  ├─ 组装 prompt sections + tool schemas
  ├─ agent/pre-step（可改写/拒绝）
  ├─ step/start
  │   ├─ 把进入的消息追加为 user/message
  │   ├─ 从日志推导模型历史（deriveMessages）
  │   ├─ agent/request → llm/stream → assistant/chunk* → assistant/message
  │   └─ tool/call* → tools/pre-execute|execute|post-execute → tool/result*
  ├─ step/end
  ├─ 还有欠账（工具还要请求 / 新输入到达）→ 认领 → 下一 step
  └─ agent/turn-stopping
turn/end

关键不变量："Model-visible means logged"——任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增 SessionEvent 并从日志渲染。

5.5 Capability Seam（能力缝）

一个可替换能力 = 三角色：Service Definition（接口）→ Service Provider（实现）→ Consumer（通常是对模型开放的工具）。

三个角色可在一个包里，但"一个角色不算 seam"。

典型收益：文件系统与子进程共享同一执行世界，把 Provider 指向远程沙箱，Bash/PTY/LSP 全部随之切换；子代理 Provider 从"进程内新子 Agent"到"另一产品里的委派 turn"都可换。

5.6 会话日志与投影

  • core/session 维护追加式 SessionEvent 日志 + 内存 store；
  • dsh-session-projection 提供 ctx.sessionProjections：注册单元增量折叠已提交事件，宿主消费者用 stateOf() 读类型化状态；
  • fork / resume / transcript / telemetry / 持久化全部从该流派生。

6. 核心模块深度分析（Step 4 展开）

6.1 应用入口：apps/cli（唯一 Node 应用启动器）

入口文件链：bin.ts → args.ts → profile-boot.ts / plugin.ts / dump-config.ts。

  • src/bin.ts（23 行，v8 ignore 的自执行分发）：读版本 → parseDshArgs → 按 mode 动态 import 对应 runner。profile 走 runProfile，plugin 走 pnpm 转发，dump-config 打印组合树。
  • src/args.ts：用 commander 定义命令行文法，关键设计——启动器只解析自己的 flag（--profile、--patch、--dump-config），遇到第一个不认识的 token 即把剩余参数原样交给被启动的 App（dsh --profile web --help 打印的是 web App 的 help）；web 是 --profile web 的硬编码别名。
  • src/profile-boot.ts（307 行，全仓最重要的启动逻辑）：
    • prepareProfile 重新写空根配置 cordis.yml（防止 Loader 把组合结果回写造成重复插入）；
    • composeProfile 叠加 bundle 层 / profile 层 / home 层 / --patch 覆盖层 / 遥测开关；
    • composeLive 对每代重组合 structuredClone（避免 id-targeted patch 原地修改 bundle 的 insert 行对象）；
    • 信号治理：SIGTERM→0，SIGINT→130；installFailLoud 兜底；
    • patchReload: live 的 profile 安装配置 HMR 监视（cordis.patch.yml 编辑即时生效）。

启动方式：

命令 模式 用途
dsh web（= --profile web） 浏览器 GUI 默认 127.0.0.1:3080
dsh --profile headless "job" 一次性 跑完一个持久会话、打印答案、退出
dsh --profile sdk JSON-RPC stdio 供 TS/Python SDK 客户端驱动
dsh --profile sdk-minimal JSON-RPC stdio 独立最小 agent 树（不叠 dsh-base）
dsh --profile acp ACP stdio 供自动化客户端（Agent Client Protocol）
dsh plugin --profile <name> add <pkg> 插件管理 转发给 profile 目录内的 pnpm

6.2 产品脊梁：packages/core（8 个包）

包 职责
scope/ 按 agent 隔离的"作用域注册原语"（库，无 ctx key）——各注册表的地基
session/ 追加式会话事件日志
system-prompt/ 按有序 section 装配系统提示词 + 工具 schema + 变量
tools/ 作用域化工具注册表 + 受保护的执行管线
agent/ 公开的 Agent 契约 + 活动注册表 + agent/* 事件（扩展插件依赖它）
agent-loop/ Agent 接口的默认实现（可替换驱动）
agent-default-model/ 部署默认模型选择
agent-tool-presentation/ 预设的每-agent 工具呈现选择器

设计要点：agent（契约）与 agent-loop（实现）分离，保证主循环可替换；可运行组合在 examples/agent-spine-demo。

6.3 模型能力：packages/llm

  • llm/：定义消息、内容块、流 chunk 词汇 + 适配器 seam（ctx.llm），是会话日志与所有插件共用的词汇表；
  • llm-deepseek/：官方 deepseek-official 直连（chat-completions、thinking、图像输入）；
  • llm-pi-ai/：通过 pi-ai 目录/协议提供多 Provider 路由；
  • llm-retry/：在持久 agent-step 边界按各 Provider 策略重试失败请求（监听 agent/request-error）；
  • token-meter/：从持久日志按固定启发式测量请求/上下文压力。

6.4 会话数据面：packages/session（14 包，四族）

  • 持久化：session-persistence（服务定义+共享写协调）→ 默认 JSONL 后端（可 Zstandard 压缩）与 opt-in SQLite 单库后端；session-checkpoint-policy 保证模型请求/工具副作用/已完成 step 在下一次动作前落盘；
  • 投影：session-projection（折叠已提交事件成当前值）+ 缓存 + 统计；
  • 标题：日志驱动标题 + 可选 LLM 生成 Provider（首条/全部人话消息）；
  • 遥测：OpenTelemetry，FULL / FEEDBACK_ONLY / DISABLED 三模式。

6.5 能力族（fs / shell / terminal / code-runtime / lsp / skill / subagent / workflow / web / jobs）

全部遵循"Seam 定义 + Provider + 模型侧工具 Consumer"三角色模式，列举关键者：

  • fs/：fs-local（本地）/ fs-sandbox（沙箱化，唯一写路径）两个 Provider；tool-fs（edit/read/read_image/write）、tool-fs-search（glob/grep，打包 @vscode/ripgrep 二进制，免装 host rg）、tool-str-replace-editor；fs-observation-policy 强制"先读后写/编辑"策略。
  • shell/：Bash 执行 seam；bash-local / pwsh-local（Windows 双子）；tool-bash / tool-pwsh。平台 gating：bundle 层用 disabled: !!js process.platform === 'win32' 表达式，每个机器只挂一个 shell 栈。
  • terminal/：持久 PTY 能力族（node-pty，Windows 走 ConPTY），owner 隔离会话 + 6 个 terminal_* 工具。
  • code-runtime/：worker-thread 代码执行 Provider + PTC（program-to-computer）模式。
  • sandbox/：进程隔离 seam，后端含 bwrap / Landlock / Seatbelt / Windows ACL（dsh-sandbox-windows-acl 用受限 token 跑 Windows 文件效果策略）。
  • subagent/：Provider 注册表 + tool-subagent（subagent/subagent_fork 委派工具）+ tool-subagent-control（send_message/interrupt_agent/list_agents）；Provider 后端含进程内 fork/spawn、Claude Code、Codex、ACP、TS SDK。
  • skill/：技能 Provider 注册表 + tool-skill（skill 工具）+ skill-filesystem 本地 Provider。
  • workflow/：工作流 seam + worker-thread 引擎 + workflow / ralph 工具。
  • web/：tool-web（web_fetch/web_search），Provider 选择藏在 ctx.web 后。
  • jobs/：通用后台任务运行时 + job_list/job_output/job_kill 控制工具。

6.6 Web GUI：host/（宿主）+ client/（浏览器）+ apps/web

  • host/（7 包）：webserver（HTTP 路由/升级/索引兜底）、frontend-static（SPA dist）、directory-picker（工作目录选择 seam：原生/应用内浏览/自适应）、plugin-inventory（Loader 条目只读投影）。
  • client/（44 包）：浏览器端 shell 引导、RPC 连接保持、React-free 可观察 store、国际化；UI 通过 slot 系统组合——每个插件向声明的扩展槽填充带类型 props/stores 的组件树；ui-* 插件覆盖会话、聊天、审批、工具树、子代理、设置、权限预设、目录选择等。
  • apps/web：Vite 构建的静态 shell（vite.config.ts + index.html），由 dsh-base bundle 的 web-app 层伺服。

6.7 SDK / ACP / Python

  • sdk/：新行分隔 JSON-RPC 协议 + TS client/server。TS 客户端与 Python SDK 是同一协议的设计双子。
  • python/sdk：deepseek-harness-sdk pip 包，无独立入口——启动打包进 wheel 的 dsh CLI（--profile sdk），需要显式 dsh_home（刻意不去发现 ~/.dsh）；DeepSeekHarness 惰性启动、复用运行时，返回 RunResult(session_id, final_response, finish_reason, events, notifications)。
  • python/sdk-runtime：运行时 wheel 把 dsh CLI 打包为 deepseek-harness-sdk-runtime-<platform>-<arch>（单 exe，含 build-exe-for-python-sdk.ts），跑 SDK 不需要系统 Node.js。
  • acp/：Agent Client Protocol（automation-only）服务器。

6.8 原生层：native/landlock-run

约 300 行 C11（musl 静态链接），实现"自限后 exec"：给自身安装 Landlock 规则集再 exec 包装命令，规则集跨 execve 继承，命令及其所有子进程都被限制，启动器本身不受限。Fail-closed：内核无法强制则直接退出不运行命令。Linux 5.13+，发布为 entry + 平台 optional 三包（linux-x64/arm64），JS API 极小（launcherPath() / probe() / grantArgs()）。

6.9 安全设计（SAFETY.md + 沙箱）

  • 官方明确：实验性、未做安全审计、不可当生产安全控制；可执行模型生成代码、加载第三方插件、访问网络/进程/凭据/文件。
  • 多层防御：沙箱（Landlock/Seatbelt/bwrap/Windows ACL）+ 审批提示 + 权限预设（interaction/permission-preset）+ 工作区写限制；dsh-base 默认把文件写限制在 workspace 内并对危险动作请求授权。
  • 运行建议：最小权限、一次性 VM/容器、备份、审阅插件与命令。

7. 模型可见工具目录（Tool Catalog 抽样）

docs/tool-catalog.md 是生成且新鲜度受校验的工具 schema 目录（引导每个 tool-* 包 + 完整性守卫，缺包即 CI 失败）。抽样：

工具包 模型可见名称 说明
tool-bash / tool-pwsh bash / pwsh 一次性 shell 执行（每平台各一）
tool-bash-persistent bash owner 隔离持久 PTY
tool-terminal terminal_open/read/send/... 6 个持久终端工具（opt-in）
tool-fs edit/read/read_image/write 文件读写 + 图片读取
tool-fs-search glob/grep ripgrep 二进制发现
tool-str-replace-editor str_replace_editor 字面替换编辑器
tool-web web_fetch/web_search Web 检索/抓取
tool-subagent subagent/subagent_fork 委派子代理
tool-subagent-control send_message/interrupt_agent/list_agents 后台子代理控制
tool-jobs job_list/job_output/job_kill 后台任务控制
tool-skill skill 技能加载
tool-workflow / tool-ralph workflow / ralph 工作流执行
tool-goal create_goal/get_goal/update_goal 同会话目标
tool-todo todo_write 待办清单
tool-session-query session_search/session_trace/... 会话检索（opt-in）
tool-ask-user ask_user_question 暂停等人工答复
tool-cordis cordis_define/inspect/run/... 运行时自改（opt-in，不进默认树）
experimental-tool-agent-team team_task_create/spawn_teammate/... 实验性 Agent 团队（默认禁用）

8. 代码质量与工程规范

这是一个工程纪律极强的仓库，可从 package.json 脚本与 scripts/ 看到"gate 文化"：

  • 校验脚本（40+ 个 verify-*）：verify-runtime-closure、verify-package-dependencies、verify-application-entrypoints（确保所有 Node 应用都走 dsh，绕过即失败）、verify-vendored-links、verify-client-domain-graph、verify-type-equiv、verify-md-links 等，几乎每个产物都有对应的"新鲜度门"。
  • 生成 + 校验闭环：gen-*-catalog 与 verify-*-catalog 成对（config / tool / cordis / module-graph / persistence / third-party-notices / doc-graphs），CI 强制重新生成与提交一致。
  • 测试矩阵：vitest 多配置（vitest.e2e / snapshot / expected / web / web.perf / web-stress）、覆盖率分区、快照录制/刷新、Web 快照（test:web:ci 跑 DOM 快照）、Windows 三个 gate（blocking/complete/observational，用 Wine）。snapshots/ 目录存在大量会话快照夹具。
  • AGENTS.md（16.5KB）+ 双语文档：docs/ 几乎每篇都有 .zh.md 镜像 + .i18n.yaml，并有 verify-translation-pairing 等翻译一致性校验；.agents/notes/ 记录了大量"已实现架构决策"笔记。
  • 包纪律：扩展插件只依赖 Service Definition 不依赖具体 Provider；每个包 README 必须含 purpose/config/extension points/Model Experience + Known Limitations（有白名单豁免机制）。

9. 速读结论

五维评分

维度 评分 一句话
文档清晰度 ⭐⭐⭐⭐⭐ 架构/子系统/目录/事件/catalog 全覆盖，中英双语，且多为"生成+校验"产物
上手难度 ⭐⭐(不友好) 概念门槛高：Cordis 插件模型、patch 叠加、事件域、能力缝；但 npx dsh web 即可跑
代码质量 ⭐⭐⭐⭐⭐ 分层极干净、契约先行、gate 文化、测试矩阵全、注释详实
技术前沿性 ⭐⭐⭐⭐⭐ 一切皆插件 harness、多沙箱后端、多 Provider LLM、Claude Code/Codex 桥接、PTC 模式、self-modifying cordis 工具集
工程规模 ⭐⭐⭐⭐⭐ 251 包 + 64.5 万行 TS + 23.8 万行文档，重量级 monorepo

值得学习的点

  1. apps/cli/src/profile-boot.ts ——"配置即组合、patch 即覆盖、克隆防别名"的启动器工程范本。
  2. vendor/README.md 的 19 条本地修改日志 —— 如何把框架 vendor 进产品并系统化维护 fork。
  3. Capability Seam 三角色模式 —— Service Definition / Provider / Consumer 的演进边界设计。
  4. "Model-visible means logged" —— 以追加式会话日志作为模型上下文唯一事实源。
  5. 验证体系 —— 生成式 catalog + 校验门 + 完整性守卫 + 多平台 gate 的全链路质量闭环。

适合场景 / 不适合场景

  • 适合：想了解"企业级 Agent harness 如何从框架到产品落地的完整形态"、研究插件化运行时架构、为 Agent 产品做技术选型评估。
  • 不适合：想找一个轻量可快速改造的 Agent 脚手架（此项目体量与概念密度过高）；需要在预览期就获得 API 稳定性的生产项目（官方明示将有破坏性变更）。

10. 附录

  • 数据来源：仓库 README（中英）、docs/architecture.md、docs/module-graph.md、docs/tool-catalog.md、packages/*/README.md、vendor/README.md、apps/cli/src/*、native/landlock-run/README.md、python/sdk/README.md、SAFETY.md、git 元数据；代码量为本机扫描实测（口径见 §2）。
  • 未覆盖：各包 src/ 逐文件级实现细节（如需深入某一能力族可进一步展开）；website/ 文档站构建细节；snapshots/ 夹具内容。

Z FAQ for DSH

Q: DSH中的 Tree Shaking 是什么？

DSH Tree‑Shaking（运行时摇树，不是编译打包的tree‑shaking）

Cordis内核根据插件inject/provide依赖图，启动时【自动裁剪】插件树：

  1. 某插件所需服务没有被任何已加载bundle/profile提供 → 该插件直接丢弃，不加载、不执行apply。
  2. 下游没有任何插件inject依赖它提供的服务 → 该插件也被裁掉。
  3. 只保留能形成【完整依赖链路】的【插件子集】，减少内存与副作用。

区别：普通JS tree‑shaking是【编译阶段】删死代码；DSH是【运行时】对【插件树】做动态裁剪。

触发来源：profile/bundle/patch共同决定可用服务集合，DSH自动做树裁剪，无需手动注释插件。
调试命令：dsh --profile xxx --dump‑config，输出里能看到哪些插件被shaken（被裁剪剔除）。

总结：按依赖图，启动时把“没人需要、依赖缺失”的插件直接从插件树扔掉。

Y 推荐文献

X 参考文献

posted @ 2026-09-02 09:41  数据知音  阅读(228)  评论(0)    收藏  举报