Jotaro Space
DeepSeek Harness Package Map：按 packages 分组继续逐包阅读
JotaroRD
  2026-08-14 01:16:00   2026-09-04 18:20:23  

为什么需要 Package Map

DeepSeek Harness 有 200 多个一方包。逐包无脑打开会迷路。正确方式是先按 group 建立地图，再在 group 内看 Service Definition、Provider、Consumer 的关系。

权威入口是：

  • packages/README.md
  • 各 group 的 README.md
  • 各 package 的 README.md
  • docs/module-graph.md

阅读模式

每个 group 先问三个问题：

  1. 它声明了什么 service 或事件？
  2. 哪些 package 是 provider？
  3. 哪些 package 是 model-facing tool、UI 或外部 protocol Consumer？

如果一个 group 只有工具没有 Service Definition，说明它可能只是 Consumer。如果只有 provider 没有 Consumer，说明 Consumer 在别的 group。

核心 group 速查

Group 阅读重点
core Agent spine：session、prompt、tools、agent、loop
llm LLM service、adapter、retry、token
fs filesystem service、local/sandbox provider、file/search tools
shell Bash/PowerShell service、local/sandbox provider、shell tools
subprocess process-tree provider
terminal persistent PTY
session persistence、projection、title、telemetry
session-query history search/query tool surface
client browser shell、runtime、UI plugins
host webserver、API proxy、directory picker
api remote gateway
typert type graph and remote generation
sdk JSON-RPC protocol/client/server
interaction approval、permission、commands、questions
subagent provider registry、child agents、delegation tools
workflow workflow seam and worker-thread engine
storage non-session storage hub
attachment durable attachment identity
spill oversized result spill policy
bundle installable profile layers
boot app-bin startup glue

推荐逐包路线

第一轮只看 README：

1
2
3
4
5
6
7
8
9
packages/README.md
packages/core/README.md
packages/core/agent-loop/README.md
packages/core/tools/README.md
packages/core/session/README.md
packages/bundle/base/README.md
packages/bundle/web-app/README.md
packages/client/README.md
packages/host/README.md

第二轮看源码：

1
2
3
4
5
6
apps/cli/src/bin.ts
packages/boot/app-boot/src/index.ts
packages/core/agent-loop/src/agent.ts
packages/core/tools/src/index.ts
packages/core/session/src/index.ts
packages/core/system-prompt/src/index.ts

第三轮看配置：

1
2
3
packages/bundle/base/cordis.patch.yml
packages/bundle/web-app/cordis.patch.yml
examples/*/cordis.yml

第四轮看生成目录：

1
2
3
4
docs/tool-catalog.md
docs/config-catalog.md
docs/persistence-catalog.md
docs/module-graph.md

如何判断一个包能不能改

改包之前先判断：

  • 是否在 packages/core/agent-loop？如果是，优先找插件扩展点。
  • 是否是 Service Definition？改它会影响所有 provider 和 Consumer。
  • 是否是 provider？要保证 Consumer 不依赖具体实现。
  • 是否模型可见？需要 snapshot 或 session event。
  • 是否文档配对？要更新 .zh.md 和 .i18n.yaml。
  • 是否涉及 lifecycle/concurrency/subprocess/sandbox？要读 defensive patterns。

常见坑

第一，不要把 group 当 import namespace。包名是 @deepseek-ai/dsh-*，group 是源码组织。

第二，不要手写包清单到新文档。packages/README.md 才是维护中的总表。

第三，不要从 provider 反向 import Consumer。能力边界应当从 Service Definition 出发。

第四，生成图和 catalog 是源派生物，改源码或生成器。

继续读

  • packages/README.md
  • docs/module-graph.md
  • docs/capability-seams.md
  • docs/cookbook/adding-a-package.md
  • docs/cookbook/extension-cookbook.md