DeepSeek Harness：把 Agent 跑起来只是开始

1. 为什么需要 Agent Harness（而不是写一个 ReAct while 循环）

一个"能调用工具的大模型"几分钟就能写出来；一个"能在生产里长期可靠运行、可恢复、可审计、可替换组件"的 Agent，是另一回事。Harness（马具/挽具）这个比喻非常精准：它不替马决定往哪走，而是把马、车、缰绳、刹车、载货、仪表盘可靠地组装在一起。

1.1 "Demo 很简单、生产化很难"到底难在哪

1.2 它在 Agent 技术栈里处于哪一层

Harness 不直接实现模型能力，也不实现 UI；它位于"产品"与"能力适配器"之间，是运行时与编排层。它和 LangGraph / AutoGen / OpenAI Agents SDK 属于同一抽象层（见第 18 章对比），但把"插件内核 + 事件日志"作为一等公民。

2. 先跑起来：建立第一印象（Lab 0）

先不求懂，先把东西跑起来、看到"实际挂载了哪些插件""最终配置长什么样"。这一步能把所有抽象名词变成你屏幕上真实的东西。

2.1 安装与运行（来自 development.md）

# 前置：Node 22.19+ / 24+，pnpm 11.7.0（Corepack 启用）
corepack enable
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install          # 同时装 worktree-local lefthook 钩子与翻译配对 merge driver
pnpm run typecheck    # 成功退出即环境就绪
pnpm run build        # tsc(host)→tsdown(host)→tsc(client)→tsdown(client)→web

# 运行 Web（浏览器入口，默认 http://127.0.0.1:3080）
pnpm dsh --profile web
# 或免安装直接试（README）
npx @deepseek-ai/dsh web

# Headless：一行命令让 Agent 直接干活（需 DEEPSEEK_API_KEY）
DEEPSEEK_API_KEY=sk-... pnpm dsh --profile headless "summarize this workspace"

2.2 看"实际挂载了什么"比读文档更重要

文档强调：组合（composition）、派生标志（flag）、配置转储（dump）都由同一套 applyEntryPatches 算法生成，所以 --dump-config 的结果 等于 真正启动时要挂载的插件树，不会漂移。这是理解"实际启动结果"的最佳入口。

# 导出最终配置（含所有 bundle / patch 层合并后），离线、可读、可加载
pnpm dsh --dump-config --profile web
# 只看默认模板、忽略用户补丁层
pnpm dsh --dump-config --profile web --default-only

2.3 Lab 0 目标与完成标准

3. 一张图理解 DeepSeek Harness

先建立一张"系统全景图"。记住四个角色：配置树（谁被挂进来）、核心运行时（循环/会话/工具/提示）、能力缝（模型/文件/沙箱…）、外部世界。下面这张图里的每个框，后面都会单独成章。

4. Cordis 与 "Everything is a Plugin"

DeepSeek Harness 的底座是 Cordis（一个事件驱动、插件化的运行时内核）。理解四个词就够了：Plugin（插件）、Service（服务）、Event（事件）、Effect（副作用）。它们都挂在一个共享的 Context 上。

4.1 四问框架

4.2 四个核心概念

4.3 事件的四种分发模式（尤其 Waterfall）

文档特别强调 Cordis 事件有 4 种 dispatch 模式，理解它们对读源码至关重要：

4.4 "没有 privileged core" 与可卸载

项目反复强调：核心功能本身也是插件。好处是——当你移除一个能力，它注册的 service、事件监听、effect 全部被反向撤销（unwind），系统回到"没装过它"的状态。

4.5 最小插件示例

// 一个"在每次 turn 开始时打印"的插件（基于 Cordis 惯例）
export const logTurnStart = (ctx) => {
  ctx.on('turn/start', (turn) => {
    console.log(`[turn] 开始: ${turn.id}`);
  });
};
// 通过 package.json 的 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
// 或在 cordis.yml 的 include 列表里挂上这个插件即可生效。

5. Profiles、Bundles、Patches 与插件树

"替换一项能力不该改动整个系统"——这是配置层的设计目标。DeepSeek Harness 用三层概念把"挂什么插件、以什么顺序、如何覆盖默认"做成了架构能力而非配置技巧。

5.1 层级关系与"配置层应用顺序"

5.2 插件树长什么样

组合的本质是：从一个空 entry 列表出发，逐层 apply patch，最终得到一棵"插件树"。下面是一个 Web profile 的示意树：

5.3 一个"默认 → 用户覆盖"的具体例子

假设默认 bundle 里有一个工具插件 entry id 为 fs-tools，其 config 限制只能读 /workspace：

# 默认 bundle 的 cordis.patch.yml（节选）
- id: fs-tools
  config:
    root: /workspace
    writable: false

用户在 ~/.dsh/cordis.patch.yml 想允许写入并改根目录。因为补丁是整段替换而非深合并，必须把要保留的字段也写上：

# ~/.dsh/cordis.patch.yml（home 层，优先级最高）
- id: fs-tools
  config:
    root: /home/me/project   # 覆盖 root
    writable: true           # 开启写入（root 字段也必须重述，否则会被丢掉）
# 想新增一个自己的工具：
- insert:
  - id: my-time-tool
    plugin: my-time-tool      # 从 node_modules 解析

5.4 为什么 --dump-config 这么重要

renderConfigDump 用与 boot() 完全相同的 applyEntryPatches 算法离线合成配置并渲染 YAML，且把共享同一来源文件+补丁层的连续行加上 # == 注释标明来源。结论：dump 出来的就是你真正会挂载的树，三者（composition / flag / dump）不会漂移。

6. 一次请求如何完成：Turn Flow（时序）

以"用户在 Web 里发一句话"为线索，追踪一次完整执行链。先记住一句话：Turn 是一次"用户发起的工作单元"，Step 是其中一次"模型请求 + 其工具调用"。一个 Turn 可以有多个 Step。

6.1 时序图（含持久化事实标注）

6.2 Turn 与 Step 的区别（必考）

6.3 几个容易混淆的概念

6.4 逐段通俗解释

把上面的时序当成"一个助手接活"的过程：你（UI）把任务放进收件箱（Inbox）→ 助手开一张工单（Turn start）→ 助手先读公司手册并整理手头资料（System Prompt + 历史消息）→ 打电话问专家（LLM 请求）→ 专家边说边传（流式）→ 专家说"去查下文件"（Tool Call）→ 助手先请示主管能否查（pre-execute 审批）→ 查到后脱敏再记录（post-execute）→ 把结果写进工单本（Session Log）→ 若专家还要继续问，就再开一页（下一个 Step）→ 直到专家说"搞定了"，工单关闭（Turn end）。

7. Agent Loop 的源码实现（packages/core/agent-loop）

第 6 章讲了"发生了什么"，本章讲"代码里怎么驱动"。Agent Loop 的驱动 API 由 agent-loop 包提供（packages/core/agent-loop），通过 Cordis 插件挂载到 Context 上，驱动 turn/step 循环。

7.1 四问框架

7.2 Inbox 与 claim

// 来自 docs/subsystems/core.md 的语义（Inbox 挂在 agent 上）
interface Inbox {
  append(msg: ClaimableInput): void      // 入队
  claim(): ClaimableInput | undefined   // 取走一条
  // 还有 prepend / replace / remove / clear / splice
}
// Agent 接口暴露 readonly inbox: Inbox
// 输入先 append 入 inbox，再被 claim() 取走

7.3 驱动循环（伪代码骨架）

// 伪代码骨架（概念性，非精确源码）
async function drive(agentCtx) {
  while (true) {
    const input = agentCtx.inbox.claim();      // ② 取输入
    if (!input) { await waitForInput(); continue; } // 等待/唤醒
    // ③ turn/start 事件入日志
    do {
      // ④ step/start 事件入日志；agent/pre-step waterfall 触发
      const msgs = agentCtx.session.deriveMessages(); // ⑥ 历史
      const prompt = await agentCtx.systemPrompt.assemble(); // ⑤
      const out = await agentCtx.llm.call({ messages: [...msgs], prompt }); // ⑦⑧⑨
      if (out.hasToolCalls) {
        for (const call of out.toolCalls) {
          const res = await runToolPipeline(agentCtx, call); // ⑩-⑬ tools/* 事件
          // ⑬ tool/result 事件入日志
        }
        // → 回到 do 循环，跑下一个 step
      } else { break; }            // 模型不再调用工具 → 结束
    } while (true);
    // ⑮ agent/turn-stopping → turn/end 事件入日志
  }
}

这个骨架把第 6 章的 15 步一一对应起来了。AgentHandle 上的 dispose() 会停止循环、注销 agent、unwind 其 scoped world；agent.cancel(cause) 在当前 step / tool 执行处中断；agent/status 事件反映 idle/running。

7.4 取消、错误与恢复路径

• 取消：agent.cancel(cause) 中断正在进行的 step/tool；已写入日志的部分保留，未完成的 step 不记录（或记录中断事件）。
• 错误：工具/模型异常转为 step 失败；错误作为 tool/result 事件的 error 字段入日志，模型可据此调整。
• 恢复：因为一切皆事件日志，重放日志即可在断点续跑——详见第 15 章。

8. Session Event Log：模型上下文的事实来源

这是整个项目最反直觉也最重要的设计。Session Log 是一份 append-only 的事件日志，它是模型上下文的唯一事实来源。你看到的 messages 数组，只是对这份日志的一个"投影"（projection）。

8.1 为什么是日志，而不是"保存最终 messages 数组"

8.2 "Model-visible means logged"

项目有一条铁律：任何进入模型视野的内容，都必须能从日志重建。System Prompt、工具 schema、注入的上下文——只要模型"看得到"，就必须是日志的派生结果，而不是某次运行临时塞进去的内存值。否则换一台机器重放，模型看到的东西就对不上了。

8.3 事件类型（节选自 docs/subsystems/session.md）

8.4 一个事件日志示例

[{ "type": "turn/start", "turn": 1 }
, { "type": "user/message", "turn": 1, "text": "读取 src/app.ts 并总结" }
, { "type": "step/start", "turn": 1, "step": 1 }
, { "type": "assistant/chunk", "turn": 1, "step": 1
  , "text": "我先" } // 流式分段
, { "type": "assistant/chunk", "turn": 1, "step": 1
  , "text": "读文件" }
, { "type": "assistant/message", "turn": 1, "step": 1
  , "text": "我先读文件" }
, { "type": "tool/call", "turn": 1, "step": 1, "id": "c1", "name": "read-file", "args": {"path":"src/app.ts"} }
, { "type": "tool/result", "turn": 1, "step": 1, "id": "c1"
  , "content": [{"type":"text", "text":"export const App = () => ..."}] }
, { "type": "step/end", "turn": 1, "step": 1 }
, { "type": "turn/end", "turn": 1 }]

8.5 从日志派生出的能力

8.6 Event Sourcing vs 普通状态存储

9. System Prompt 与上下文组装

System Prompt 不是一段写死的字符串，而是一组可注册、可排序、可作用域化的"提示段（prompt section）"，在每次模型请求前通过 waterfall 事件动态拼装。

9.1 四问框架

9.2 静态 vs 动态上下文

9.3 哪些进日志、哪些只是派生

• 进日志（事实）：用户消息（user/message）、assistant 输出（assistant/message + assistant/chunk）、tool/call、tool/result——这些是模型真正"看到并回应"的内容。
• 只派生（过程）：System Prompt 的拼接动作、waterfall 调用顺序、某段是否启用——这些靠重放插件状态重算，不必存。

9.4 最小"模型上下文插件"示例（Lab 3 预览）

// 给某个 agent 注入一段动态背景
// section() 接收 PromptSection，含 name / order / scope / content
ctx.systemPrompt.section({
  name: 'project-rules',
  order: 100,
  scope: agentScopeKey,
  content: `当前项目规则：使用 TypeScript strict 模式；提交信息用 Conventional Commits。`
});

10. Tool Registry 与安全执行管线

工具是"模型能调用的函数"。但生产里的工具不能"模型一说就执行"——中间要插权限、审批、沙箱、策略。DeepSeek Harness 把这条链做成 tools/pre-execute → tools/execute → tools/post-execute → finalizeContent → tools/result 管线，每一段都是可监听的事件。

10.1 工具如何注册（最小自定义工具，Lab 2 核心）

// 一个"当前时间"工具：注册、Schema、执行、结果
ctx.tools.register({
  name: 'current-time',
  description: '返回当前 ISO 时间',
  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
  execute: async (toolCtx, args) => {
    return { content: [{ type: 'text', text: new Date().toISOString() }] };
  },
});

逐行解释：register(definition) 把工具挂进注册表（返回 disposer）；inputSchema 是 JSON Schema，会被 ctx.tools.schemas(scope) 投影注入 System Prompt 让模型知道怎么调用；execute 返回 {content:[...]}（与 tool/result 事件格式一致）。模型看到 schema → 发起 tool/call 事件 → 管线接管。

10.2 执行管线（含事件）

10.3 四问框架

10.4 失败 / 超时 / 取消 / 部分结果

• 失败：execute 抛错 → 仍经 tools/post-execute → finalizeContent → tools/result，错误作为 tool/result 事件的 error 字段入日志，模型可据此调整。
• 超时/取消：在 execute 阶段可被中断；已产生的中间态由 effect 回滚。
• 部分结果：post-execute 阶段的 finalizeContent 可裁剪过大输出，只把"安全且必要"的部分喂回模型。

11. Capability Seams：让能力可替换的"接缝"

如果一个能力只能"写死调用某个 SDK"，那它就无法替换、无法测试、无法远程化。DeepSeek Harness 用"能力缝（Capability Seam）"解决这个问题：把能力的定义、提供、消费三者拆开。

11.1 三种角色（缺一不可）

11.2 能力缝示意图

11.3 哪些能力是 seam

11.4 推演：本地文件系统 → 远程沙箱

假设某 Agent 通过 ctx.fs.read(path) 读文件。要换成"远程沙箱里的文件系统"：

• Definition 不变（还是 read/write 接口）；
• 只换 Provider：从"本地 fs 实现"换成"把调用转发到远程沙箱 RPC 的实现"；
• Consumer（所有调用 ctx.fs.read 的插件）一行都不用改。

这就是 seam 的价值：替换环境能力时，模型能力和业务代码保持不变。

11.5 与常见架构模式的对应

能力缝 ≈ 依赖注入（DI） + 适配器模式 + 端口与适配器（Hexagonal）：Definition 是端口（Port），Provider 是适配器（Adapter），Consumer 在内部通过端口调用。项目的特色是把它提升到"运行时一等公民"并以插件方式组合。

12. Scope、生命周期与副作用回滚

当一个系统里可能同时跑多个 Agent、或某个能力只应对"某一个 Agent"生效时，你需要"作用域（Scope）"。否则会出现能力污染、资源泄漏、互相干扰。

12.1 全局 Context vs Agent Context

• Global Context（根 Context）：整个应用共享，跨 Agent。适合全局服务（如 LLM 适配器、持久化）。
• Agent Context（作用域 Context）：每个 Agent 一份，由 ctx.scope(agentCtx) 派生。适合"只对这个 Agent 生效"的工具、提示、用户偏好。

12.2 作用域化注册原语

ctx.tools.schemas(scope)        // 投影该 scope 可见的工具 schema
ctx.systemPrompt.section({...})  // 注册提示段，可含 scope 字段
ctx.systemPrompt.context({...})   // 注册动态上下文，可含 scope
ctx.systemPrompt.assemble({scope}) // 组装该 scope 的完整提示

12.3 插件加载/卸载与副作用回滚

每个插件在 Context 上声明的 service、事件监听、effect（定时器、watcher、句柄）在卸载时自动反向撤销（unwind）。这就是第 4 章"没有 privileged core"的生命周期保障。

12.4 多 Agent / 子 Agent 隔离

子 Agent（subagent）通过 scope 获得独立上下文：它的工具、提示、会话与父 Agent 隔离。父 Agent 调用子 Agent 时，子 Agent 在自己的 scope 内跑完整 turn/step，结果回传父 Agent——父子互不污染状态。

13. Web、Headless 与 UI 状态同步

DeepSeek Harness 不是"一个程序"，而是一组共享同一内核、由不同 profile 组合出不同形态的运行入口。

13.1 三种运行形态

它们共享：Agent Loop、Session Log、Tool Registry、能力缝。差异只来自"挂了哪些插件"——也就是 profile 的 bundle 组合。

13.2 UI 如何消费状态（且不是真相源）

Client 通过 Typert 生成的 Host-for-Client Remote 投影（ctx.remote 及作用域 agentCtx.remote）调用 Host 方法、订阅 Session 事件来渲染。UI 是观察者，不是状态拥有者。

13.3 如何增加另一种运行入口

新增一个入口 = 新增一个 profile（bundle 组合） + 一个把你想要的"前端形态"作为插件挂上。内核、循环、日志都不用动。这正是"替换一项能力不应修改整个系统"的体现。

14. Host/Client、Monorepo 与构建系统

这一章先讲"问题"，再讲"配置"。核心问题：同一套 Cordis 插件既要跑在 Node（Host），又要跑在浏览器（Client），但两侧的 Context 接口声明会冲突。

14.1 为什么分 Host 与 Client 两个聚合

Host 与 Client 两侧都会在相同 key 下 declaration-merge Cordis 的 Context 接口，但服务不同（Node 侧有 fs/subprocess，浏览器侧有 DOM/React）。若放进同一个 ts.Program，声明合并会冲突报错。因此仓库用两个独立的 TypeScript aggregate：

14.2 构建顺序本身就是架构约束

tsc -b tsconfig.host.json      # 1. Host 类型检查/产物
tsdown --env.DSH_BUILD_FACE host   # 2. Host 打包（含 Typert）
tsc -b tsconfig.client.json    # 3. Client 类型（引用 Host 产物）
tsdown --env.DSH_BUILD_FACE client # 4. Client 打包
pnpm run build:web             # 5. Web 构建

为什么是这个顺序？因为 Typert 只在 Host tsdown 运行，它分析 Host 类型，生成 Host 反射产物与 Host-for-Client Remote 投影。Client tsdown 不启动 Typert，而是消费 Host 阶段生成的 /remote 声明。所以 Host 必须先于 Client。顺序不是随意的，它体现了"Client 依赖 Host 的远程契约"。

14.3 Typert 与 Remote Contract

• 业务服务用 @Remote / @RemoteScope 声明"Host 可调、Client 可订阅"的方法。
• Host 构建生成 Host-for-Client 类型与运行时贡献；Client 的 api-remotes 组合加载到 ctx.remote 与作用域 agentCtx.remote。
• 生成的 Remote 声明是例外：typecheck/lint/doc-typecheck 先生成它们。

14.4 Monorepo 布局

packages/*/*      # 包层（被 tsdown 显式 glob 纳入构建）
vendor/*          #  vendored: @deepseek-ai/cosmokit, schemastery 等
apps/*            # 产品装配；apps/cli 拥有 dsh bin
native/*         # 原生构建（如 Landlock launcher）
examples/         # 可运行 demo：union of cordis.yml plugins
website/ python/sdk-runtime/

15. 错误、取消、恢复与持久化

生产 Agent 一定会遇到：用户取消、模型抽风、工具超时、进程崩溃。DeepSeek Harness 的应对都围绕一个支点——Session Log 是事实来源。

15.1 错误路径

• 工具执行异常：错误作为 tool/result 事件的 error 字段入日志；模型可在下一步读到错误并自我纠正。
• 模型请求失败：LLM 适配器抛错 → step 失败事件 → 可重试或结束 turn。
• 未捕获异常：循环记录失败并结束 turn，已落盘日志保留，便于事后排查。

15.2 取消机制

AgentHandle.cancel() 在当前 step / 工具执行处注入中断。已完成的 step 与写入日志的部分保留；未完成的 step 不记录（或记中断事件）。这与"日志=事实"一致：取消只是"停止继续写新事实"。

15.3 恢复（Resume）：从日志续跑

因为一切事实都在日志里，Resume = 加载日志 → 重建 Context 状态 → 从末尾继续 claim 新输入。不需要保存"当时的 messages 数组快照"，因为 messages 本就是日志的投影，重放即得。

15.4 凭据与配置隔离

16. 测试所揭示的架构不变量

作者说"把测试当作可执行设计文档"。读测试能确认：系统真正保证了什么、哪些行为是不可破坏的核心不变量、哪些边界被重点防守。

16.1 测试体系（来自 development.md）

• vitest 为单元测试/集成测试框架；pnpm run check:all 跑本地综合门。
• 真实 API e2e（pnpm run test:e2e）在 DEEPSEEK_API_KEY 未设置时 self-skip——这是"无密钥也不报错"的工程自觉。
• 文档中的 ts type-equiv 围栏由 pnpm run verify-type-equiv 校验，保证文档里的类型片段与真实代码一致。

16.2 从文档反推的核心不变量

17. 代码不会主动告诉你的事（默会知识）

以下每条都按"现象 / 底层原因 / 实际风险 / 判断方法 / 推荐做法 / 证据"六要素组织。部分属工程推断已标注。

17.1 架构默会知识

17.2 源码阅读默会知识

17.3 生产实践默会知识

18. 设计取舍与替代方案（批判性对比）

不只要说它好。下面按你关心的维度对比：状态所有权、扩展机制、可恢复性、可审计性、生命周期、工具治理、配置组合、学习成本、运维复杂度、适用场景。

18.1 与"自己写简单 Agent Framework"对比

18.2 与常见方案在抽象层上的差异（外部比较）

18.3 关键架构取舍的结论

• 插件式 vs 单体循环：插件式胜在可组合/可测/可替换，代价是插件治理与学习成本。Harness 选择插件式并把"无特权核心"作为纪律。
• Event Log vs 最终状态：Log 胜在可重放/审计/分叉，代价是体积与裁剪。Harness 把 Log 当事实源。
• 事件驱动 vs 直接调用：事件驱动解耦、可拦截，代价是调用链不直观（需 next() 纪律）。
• Profiles/Bundles/Patch vs 固定配置：分层组合胜在"替换能力不改系统"，代价是补丁语义要严格（整段替换）。
• Capability Seam vs 内联 SDK：seam 胜在可替换/可测/可远程，代价是多一层接口。
• ReAct Loop vs Workflow/DAG：ReAct 灵活、适合开放任务；DAG 可控、适合固定流程。Harness 内核是 ReAct 式循环，图可由上层派生（工程推断）。

19. 六个渐进式动手实验（Labs）

从"跑起来"到"做一个小型生产化 Agent"。每个 Lab 都有：学习目标 / 前置知识 / 操作步骤 / 涉及文件 / 核心代码 / 预期结果 / 验证方法 / 常见错误 / 思考题 / 完成标准。

ctx.tools.register({
  name: 'current-time',
  description: '返回当前 ISO 时间',
  inputSchema: { type: 'object', properties: {}, additionalProperties: false },
  execute: async (toolCtx, args) =>
    ({ content: [{ type: 'text', text: new Date().toISOString() }] }),
});

ctx.systemPrompt.section({
  name: 'project-rules',
  order: 100,
  scope: agentScopeKey,
  content: `当前项目规则：TypeScript strict；Conventional Commits。`
});

// Provider 侧：把本地 fs 换成"远程沙箱"实现（接口不变）
ctx.fs.provide({
  read: async (path) => rpcToSandbox('read', path),
  write: async (path, data) => rpcToSandbox('write', path, data),
});
// Consumer 侧：所有调用 ctx.fs.read 的代码一行不改

20. 源码阅读地图（以 47f9438 为准）

所有链接指向 master@47f9438。建议按"概念 → 子系统文档 → 包源码 → 测试"的顺序。

21. 费曼复述与分级练习题

21.1 费曼复述（用自己的话讲出来）

先合上教材，尝试解释下列问题；展开看"合格答案要点 / 常见错误 / 追问方向"。

21.2 分级练习题

ctx.on('system-prompt/assemble', (assembly, context, next) => {
  // 修改 assembly（如注入额外 section）
  // 漏了 next(assembly)
});

22. 面试题与回答框架（15+）

23. 下一步学习路线与术语表

23.1 下一步

• 动手：完成 §19 的 6 个 Lab，尤其 Lab 6 的生产化 Agent。
• 读源码：按 §20 地图，从 packages/core/session 与 agent-loop 入手，对照测试。
• 对比：用同一任务分别用"简单 ReAct"和"Harness"实现，体会差异。
• 跟进：项目处于 Developer Preview（0.1.0-rc.5），接口会变；订阅仓库 release 与 .agents/notes 的 Agent Notes。
• 延伸：读 Cordis / cosmokit / schemastery 上游文档，理解插件内核本身。

23.2 术语表

23.3 源码索引（按主题）

• 配置组合：packages/boot/app-boot → boot/composeEntries/renderConfigDump/assertEntriesLoaded/Activated
• 循环：packages/core/agent-loop → attach/run/startTurn/startStep
• 会话：packages/core/session → SessionEvent/deriveMessages
• 工具：packages/core/tools → register/schemas/tools/pre-execute · tools/execute · tools/post-execute · tools/result
• 提示：packages/core/system-prompt → section/context/assemble · ctx.tools.schemas
• 范围：packages/core/scope → scope(agentCtx)
• LLM 缝：packages/llm → ctx.llm.call/适配器
• 入口：apps/cli/src/bin.ts → parseDshArgs/runProfile/runDumpConfig