DeepSeek Harness 运行时工程导论
想边学边练？可前往 7 天学会 DeepSeek Harness 子站，按 Day 1–7 渐进式路径完成 Cordis 插件内核、技能实验室与生产部署实战。
本章你将获得什么
本文不是「如何托管一个本地文档站」的教程，而是 DeepSeek Harness Agent 运行时工程 的系统导论。读完本章，你应能回答：为何从链式编排转向运行时插件内核；Cordis 五核心如何落地；Bundle/Profile/Patch 如何治理配置；四种预设如何权衡能力与安全；Host/Preset/Client 三平面如何分工；与 LangChain、MCP 是替代还是互补。
一、核心理念：Agent = Model + Harness
1.1 公式拆解
Agent = Model + Harness 把 Agent 拆成推理层与运行时层：
| 组件 | 职责 | 典型失败模式 |
|---|---|---|
| Model | 推理、规划、NLU/NLG | 幻觉、上下文溢出、工具参数格式错误 |
| Harness | 工具调度、Session、插件生命周期、沙箱、审批、可观测 | 副作用泄漏、误执行、Session 不可恢复、循环依赖 |
1.2 运行时优先 vs 管道优先
管道式框架把 Prompt、Tool、Parser 串成链，执行完即结束。DSH 选择 Runtime-first：Agent 长期驻留，能力以插件挂载/卸载；副作用经 ctx.effect() Teardown 回收；预设切换等价于换 Bundle 组合。
1.3 决策矩阵：何时引入 Harness
| 场景 | 仅 Model API | 需要 Harness |
|---|---|---|
| 一次性问答 | 足够 | 过度 |
| 多轮工具调用 | 需自建循环 | 原生 |
| 生产审计 | 需自建 Log | Session 一等 |
| 插件热更新 | 需重启进程 | Patch/Bundle |
| 多租户隔离 | 复杂 | Profile 分层 |
二、历史脉络：为何需要 Harness
2.1 工程鸿沟
| 阶段 | 现象 | 根因 |
|---|---|---|
| 原型 | Notebook 能跑 | 无 Session、无审计 |
| 试点 | 误删文件、Key 泄露 | 无沙箱、无审批 |
| 生产 | 无法复现投诉 | 无溯源、无 Trace |
2.2 DSH 定位
DeepSeek Harness 提供 Cordis 插件内核、四预设 Bundle、npx @deepseek-ai/dsh web（默认 http://127.0.0.1:3080）、cordis.yml 配置入口。侧重 可部署 Agent Host，非一次性 SDK 调用。
2.3 生态时间线
2.4 从 Demo 到生产的典型断层
许多团队在 Demo 阶段用 LangChain 或裸 API 快速验证，上线时才发现缺少：工具误执行的回滚、Session 的可恢复性、MCP Server 的生命周期管理、以及跨环境的配置治理。Harness 把这些横切能力下沉到运行时，而不是让每个业务团队重复造轮子。
三、Cordis 插件内核深讲
Everything is a Plugin：模型、工具、Agent 循环、Web UI、MCP 客户端均为插件。
3.1 五核心
| 核心 | 机制 | 工程含义 |
|---|---|---|
| Plugin | apply(ctx) | 注册服务、工具、路由 |
| Context | ctx | provide/inject/effect |
| Dependencies | inject(token) | 显式依赖，禁隐式全局 |
| Events | observe/wrap/parallel/sequential | 横切：日志、审批、Tracing |
| Teardown | ctx.effect 清理 | 可逆副作用 |
3.2 apply(ctx) 示例
export default {
name: "hello-world",
apply(ctx) {
ctx.provide("helloService", {
greet(name: string) { return `Hello, ${name}`; },
});
ctx.effect(() => {
const t = setInterval(() => {}, 60000);
return () => clearInterval(t);
});
},
};
3.3 Dependencies 与 inject
const hello = ctx.inject<{ greet(n: string): string }>("helloService");
显式 inject 替代全局单例：单元测试可 mock token；多 Bundle 并存时 token 命名空间避免冲突；启动期 DAG 环检测在 apply 前失败，而非运行中随机崩溃。
| 失败模式 | 症状 | 修复 |
|---|---|---|
| 循环依赖 | 启动 exit 1 | 抽第三插件或 lazy inject |
| Token 冲突 | 后挂载覆盖前 | 前缀如 tools.readFile |
| 缺 Teardown | 内存/端口泄漏 | Leak Lab 重启对比 |
3.4 Events 四种语义
| 模式 | 用途 | 典型插件 |
|---|---|---|
| observe | 旁路审计、Metrics | otel-plugin |
| wrap | 审批、参数校验 | approval-plugin |
| parallel | 非阻塞通知 | webhook-notify |
| sequential | 多级管道 | sanitize→execute |
3.5 Teardown 与资源契约
ctx.effect(fn) 注册卸载回调：关闭 fs.watch、kill 子进程、disconnect MCP、clearInterval。遗漏 Teardown 的表现：Host 重启后端口仍占用、幽灵 tool 回调、Session 写入竞态。插件作者应在 PR 中证明 teardown 被调用（单测 mount/unmount 循环）。
3.6 时空可组合性
空间组合：多个插件在同一 Host 并存，通过 inject 协作。时间组合：Patch 在不重启 Model 的情况下调整工具可见性；Bundle 升级触发有序 unmount→mount。这与 Kubernetes 的声明式编排类似，但粒度在 Agent 能力而非 Pod。
四、Bundle / Profile / Patch 三层配置
| 层 | 含义 | 变更频率 | 版本控制 |
|---|---|---|---|
| Bundle | 插件能力包 | 低（发版） | semver tag |
| Profile | 环境：模型、日志、OTel | 中（环境） | 分支/目录 |
| Patch | 局部覆盖 | 高（实验） | 短期 PR |
决策规则：新增工具集→新 Bundle 或 Bundle MINOR；换模型/Key→Profile；临时禁用某 tool→Patch（两周内合并进 Profile 或删除）。
4.1 Patch 反模式
| 反模式 | 后果 | 治理 |
|---|---|---|
| Patch 永久堆在 main | 无人知 effective 配置 | CI 统计 patches 行数 |
| Patch 改 Bundle 核心 | 升级 Bundle 丢 Patch | Patch 仅改 Profile 字段 |
| 无 expire 注释 | 实验泄漏 prod | PR 模板要求 expire 日期 |
五、四种预设
| 预设 | 工具范围 | 典型用户 | 风险等级 |
|---|---|---|---|
| Standard | 读文件、搜索、受限 HTTP | 知识问答、内网助手 | 低 |
| Code | git、bash（审批）、LSP | 开发辅助、CI Bot | 中 |
| Minimal | ≤5 个轻量 tool | 分类、提取、降本 | 低 |
| Creator | 高权限组合 | 实验、红队 | 高 |
Creator 生产必须：独立 Host、强制 approval.strict、全量 Session Log、Profile 显式 creator.enabled: false 于 prod。
5.1 预设切换的工程语义
切换预设 ≠ 换 Prompt：等价于卸载旧 Bundle 工具集、加载新 Bundle、可能清空部分 Session 上下文。UI 切换 preset 时，Host 应创建新 Session 或显式警告，避免用户误以为历史 tool 权限仍有效。
六、子系统地图
6.1 Host / Agent Preset / Client 三平面
| 平面 | 对象 | 操作者 | 变更渠道 |
|---|---|---|---|
| Host | 进程、端口、资源 limit | 平台/SRE | K8s、systemd |
| Agent Preset | Bundle+Profile+Patch | 架构师 | cordis.yml PR |
| Client | Web UI、CLI、API | 终端用户 | 无配置权限 |
职责分离防止：用户在 UI 误开 Creator；开发在 Patch 里写 prod Key；运维直接改容器内 yml 不进 Git。
七、工具管道与 MCP
工具管道五阶段：注册（插件 provide registry）→ 描述（schema 给模型）→ 选择（LLM tool_call）→ 治理（wrap 审批 + sandbox path）→ 回注（tool_result 进 context）。
MCP 客户端插件把远程 Server 的 tools 映射进同一 registry，禁止 Agent 绕过 Host 直连 MCP（否则无 Log、无审批）。
7.1 工具描述工程要点
description 应含：路径约束、何时勿用、与相似 tool 的差异。parameters.required 严格；过大 enum 应分页或改用 search tool。
八、Session 与多 Agent
| 能力 | 语义 | 工程用途 |
|---|---|---|
| Resume | 同一 sessionId 继续 | 进程崩溃恢复 |
| Fork | 复制事件前缀后分叉 | A/B 方案对比 |
| Replay | 确定性重放 | CI 回归、事故复现 |
| Spawn | 新 sessionId 子 Agent | 并行子任务 |
上下文压缩策略：sliding_window（丢早期）、summarize（摘要）、tool_result_trim（截断大输出）、hybrid（生产推荐）。压缩必须保留 system 安全约束块。
工作流/计划模式：Planner 插件输出步骤 DAG，Executor Spawn 子 Session 逐步执行，汇总插件合并结果。
九、架构全景
十、场景与反模式
正例：内网文档 QA（Standard + MCP Confluence + deny 外网）；PR 审查 Bot（Code + strict approval + 只读 token）；边缘分类（Minimal + maxTurns）。
| 反模式 | 症状 | 正确做法 |
|---|---|---|
| 把 DSH 当静态站托管 | 无 Agent 能力 | 跑 Host + cordis |
| 跳过 Teardown | 泄漏 | 每个插件写 effect |
| prod 默认 Creator | 数据泄露 | Profile 禁用 |
| Patch 永久堆积 | 配置漂移 | 合并或删除 |
| MCP 旁路调用 | 无审计 | 经 Host registry |
十一、与 LangChain / MCP 对比
| 维度 | DSH Harness | LangChain | 纯 MCP |
|---|---|---|---|
| Agent 驻留 | 原生 Host | 需自建服务 | 无 Agent 循环 |
| Teardown | ctx.effect 一等 | Callback 可选 | N/A |
| 配置三层 | Bundle/Profile/Patch | 代码为主 | Server 配置 |
| Session/Resume | 内置 jsonl | 需自建 | N/A |
| 工具标准 | 内置 + MCP | 多种 adapter | MCP only |
互补架构：DSH 作运行时 Host；MCP 扩展工具生态；复杂 RAG 链可封装为 Cordis 插件而非另起进程。
十二、学习路径
推荐阅读顺序：本文 → 快速开始 → 开发指南 → 从零到一 → 最佳实践。每章配合 七天子站 动手实验。
十三、小结
DeepSeek Harness 将 Agent 从「能跑的脚本」提升为 可部署、可观测、可组合 的运行时系统。核心记忆点 ：Agent = Model + Harness；Cordis 五核心；Bundle/Profile/Patch；四预设风险分级；三平面职责分离。下一步请进入 快速开始 完成首启，或在 七天子站 按 Day 1 实验 Cordis 挂载顺序。
十四、Cordis Host 启动阶段详解
Host 启动是一条 fail-fast 流水线：解析 cordis.yml → 校验 schema → 展开 Bundle manifest → 合并 profiles[profile] → 按序应用 patches → 构建插件依赖 DAG 并环检测 → 拓扑排序 → 依次 apply(ctx) → 监听端口 → 发布 ready。
挂载顺序原则：日志与 OTel 基础插件最先；沙箱插件先于文件/Shell 工具；审批 wrap 必须在 tool executor 之前注册；MCP 客户端在工具 registry 就绪后连接 Server。错误顺序的典型症状：tool 无 approval 拦截、或 sandbox 未生效时 bash 已注册。
| 启动阶段 | 失败信号 | 排查 |
|---|---|---|
| ParseYAML | exit 1 无端口 | yml 缩进/未知 bundle |
| ExpandBundle | unknown bundle | 检查 bundle 名与版本 |
| TopoSort | cyclic dependency | 拆分插件 inject 环 |
| ApplyPlugins | timeout | MCP server 未启动 |
十五、工具调用全链路桌面推演
用户消息：「读取 package.json 的 name 字段」。完整链路如下：
- Client 写入 Session Log（
user_message事件） - Host 组装 messages + tools schema + system
- LLM 返回
tool_call: read_file - wrap 审批插件检查 path 是否在 sandbox
- sandbox 解析相对路径，deny
../逃逸 - executor 读盘返回内容
- Log 写入
tool_result - LLM 二次推理生成自然语言答案
- Client 渲染 assistant 消息
每阶段应对应 OTel span 名：dsh.http.request → dsh.session.turn → dsh.llm.completion → dsh.tool.execute。事故调查时按 span 时间线对齐 Session jsonl 事件序号。
十六、Bundle manifest 与 semver 治理
每个 Bundle 发布附带 manifest：列出插件清单、tool 名称、默认 risk level、最低 Host 版本。语义化版本：MAJOR 删除或重命名 tool（需 Replay 全量）；MINOR 新增 tool；PATCH 仅 bugfix 不改变 schema。
CI 流水线应：对比 manifest 与代码注册表；对 MAJOR 触发 breaking change 审查；staging 环境 Replay 最近 50 条生产 Session 样本。跨项目复用能力应发布新 Bundle，而非复制 Patch 片段。
十七、Profile 四环境矩阵
| 字段 | local | ci | staging | prod |
|---|---|---|---|---|
| bundle | standard | minimal | 与 prod 同 | code/standard |
| approval | permissive | off/mock | strict | strict |
| otel | 可选 | off | 全采样 | 采样 10% |
| creator | 可开 | 禁 | 禁 | 禁 |
| session.store | 本地目录 | tmpfs | PVC | S3/PVC |
staging 的 model 配置应与 prod 一致，否则 Replay 行为漂移。ci Profile 用 Minimal 加速 smoke，不测 tool 全集。
十八、Spawn / Fork / Replay 精确定义
- Spawn：父 Session 委派子任务，生成新
sessionId，子 Agent 可有缩小 tool 集；父 Session 等待子 summary 事件。 - Fork：从事件索引
k复制前缀，创建分支 Session 探索不同 Patch；用于对比两种修复方案。 - Replay：读取历史 jsonl，mock LLM 与 tool 响应，验证 Host 升级后行为一致。
反模式：Fork 分支无 TTL 清理占满磁盘；Spawn 无 timeout 导致父 Session 永久 pending。
十九、MCP 拓扑与 Sidecar 模式
常见拓扑：stdio Sidecar（Host spawn 子进程 MCP Server）；连接池（多 Session 共享同一 Server 进程）；Remote SSE（网络 MCP，需 TLS 与认证）。
无论哪种，tools 必须经 Host registry 注册，走同一 wrap 与 Log。禁止 Client 配置独立 MCP 连接绕过审批。
| 模式 | 优点 | 风险 |
|---|---|---|
| stdio | 简单、隔离 | 进程泄漏 |
| 连接池 | 低开销 | 状态污染 |
| Remote | 集中运维 | 网络延迟、投毒 |
二十、上下文压缩生产案例
场景：Code 预设跑测试，jest 输出 200KB。策略：tool_result_trim 保留 FAIL 段与 stack 头尾；summarize 压缩更早 turn 的用户闲聊；system 块标记为不可压缩。
勿单独使用 sliding_window 丢弃含安全约束的 system 消息。压缩触发条件建议：context.tokens > 0.8 * model.limit 时 hybrid 策略启动。
二十一、OpenTelemetry 四类看板
- Host 健康：CPU、内存、GC、MCP 连接数、Session 写入延迟
- Agent 质量：task 成功率、平均 turn 数、tool_error_rate
- 安全：approval_block_rate、Top blocked tools、sandbox deny 次数
- 成本：token_per_task、summarize 二次调用成本
Trace 标准链路：http → session → llm → tool → mcp。告警：teardown_fail > 0 持续 5 分钟。
二十二、LangChain 迁移对照
| LangChain | DSH |
|---|---|
| Chain | Session 事件流 |
| Tool | Cordis 插件注册 |
| AgentExecutor | Agent Loop 插件 |
| Memory | Session Log |
| Callback | observe 事件 |
迁移步骤：把 Chain 拆成 Session 事件；Tool 改为插件 apply；Executor 逻辑迁入 Loop 插件；用 Replay 验证输出 parity。
二十三、Incident 响应剧本
误删文件：Patch disable tools.bash → Log 定位 sessionId 与 turn → Replay 确认 → 补 approval 规则 → 通知用户。
MCP Server 投毒：断连 → 轮换 Server 镜像 digest → 审计受影响 Session → 强制 Fork 重跑关键任务。
API Key 泄露：Vault 轮换 → 作废活跃 Session → 审查 Log 是否 exfil → postmortem 补 deny 规则。
二十四、Skill 系统 vs Cordis 插件
插件：TypeScript 模块，apply(ctx) 注册能力，版本随 Bundle 发布。Skill：声明式领域包，UI 或配置启用，内部仍走同一 sandbox 与 approval，不能 bypass wrap。
Skill Labs（见七天子站）用于验证 Skill 与 Bundle 组合，再 promote 到 Profile。
二十五、工作流与计划模式
Planner 插件调用 LLM 输出 JSON 计划：steps[{id, tool, args}]。Executor 按 DAG 顺序 Spawn 或 in-process 执行。Human-in-the-loop 步骤插入 approval gate。
行业案例 1：金融合规只读 Agent
Bundle 选 Standard，自定义插件注册 sql_query_readonly ，Profile 设 approval.mode: strict，Session 保留 30 天。沙箱 deny 写路径与 exec。MCP 不接外网。Replay 每条 SQL tool_call 审计。
行业案例 2：CI 自动修复 Bot
Minimal 起步降 token，Patch 开放受限 git_push；maxTurns 防死循环；Fork 对比两种 fix 方案；合并前人工 approval。OTel 追踪每 PR 的 tool 次数。
行业案例 3：内网文档 QA
Standard + MCP Confluence Server；Profile sandbox.denyNetwork: true；context hybrid 压缩长文档检索结果。禁止 Creator。
行业案例 4：客服意图分类
Minimal 仅 classification tools；较 Standard 降本约 40%；无文件系统访问；Session 不存 PII 原文。
行业案例 5：代码审查助手
Code 预设 + 只读 git token；strict approval 拦截 push；OTel 导 出到现有 Grafana。
行业案例 6：红队 Creator 实验
独立 VM、egress deny、全量 Log、实验后销毁 Host；绝不使用生产 Key。
行业案例 7：多租户 SaaS
每租户独立 Profile 前缀；Session 路径隔离；配额插件 wrap 限制 turn/day。
行业案例 8：跨区高可用
Host 无状态；Session 存 S3；sticky session 或 sessionId 客户端持有；Bundle pin digest。
二十六、STRIDE 威胁建模
| 威胁 | DSH 控制 |
|---|---|
| Spoofing | MCP Server 认证、tool token 校验 |
| Tampering | append-only Session、签名校验 optional |
| Repudiation | approval audit 事件 |
| Info Disclosure | sandbox deny、Session 加密 at rest |
| DoS | maxTurns、rate limit、tool timeout |
| Elevation | Creator 隔离、Profile 禁 prod |
二十七、生产 Readiness 十五问
- prod Profile 是否显式禁用 Creator？
- Session 是否持久卷且备份？
- OTel 是否接入现有栈？
- approval 是否 strict 且 auditable？
- sandbox.workspace 是否最小目录？
- API Key 是否来自 Vault 非 yml 明文？
- Bundle 是否 pin semver/digest？
- patches 数组是否为空或极少？
- 是否具备 Replay CI job？
- 是否有 Incident runbook？
- MCP Server 是否 pin 版本？
- context 压缩是否保留安全 system？
- 多实例是否共享 Session 存储？
- K8s readiness 是否检查 MCP 连通？
- 团队是否完成 getting-started 验收？
二十八、dsh_frontend 课程对齐表
| 课程模块 | 本文章节 |
|---|---|
| Agent = Model + Harness | 第一章 |
| Cordis 五核心 | 第三章 |
| 时空可组合 | 3.6、第四章 |
| Bundle/Profile/Patch | 第四章 |
| 四预设 | 第五章 |
| 工具管道/沙箱/审批/MCP | 第六、七章 |
| Session/OTel/压缩 | 第八章 |
| 三平面 | 6.1 |
| Spawn/Skill/工作流 | 八、二十五章 |
29、Standard 预设工程细节
风险等级：低。
面向通用助手：读 workspace 文件、搜索、受限 HTTP。不含任意 Shell。生产默认首选。工具数量建议 ≤15，避免模型选择混乱。描述中强调「勿用于删除或修改」。
| 检查项 | 要求 |
|---|---|
| prod 启用 | 允许 |
| approval | 按 Profile |
| Replay 样本 | 发版前 ≥20 条 |
30、Code 预设工程细节
风险等级：中。
面向软件工程：git status/diff、bash（必经 approval）、LSP 跳转。sandbox.workspace 设为仓库根；denyPaths 含 .env、node_modules/.cache。CI 场景用只读 deploy key。
31、Minimal 预设工程细节
风险等级：低。
极简 tool 集（通常 ≤5）：适合分类、字段提取、路由。配合 maxTurns 与 aggressive compress 降本。复杂多步任务应提示用户切换 Code。
32、Creator 预设工程细节
风险等级：高。
实验性高权限组合：可能含宽沙箱、多 MCP、低 friction approval。禁止作为 prod Profile 的 bundle 默认值。仅隔离环境，全 Log，事后销毁。
| 检查项 | 要求 |
|---|---|
| prod 启用 | 禁止 |
| approval | strict + 隔离 |
| Replay 样本 | 发版前 ≥20 条 |
附录 A：术语表
- Harness：包裹 Model 的运行时：调度工具、持久 Session、执行插件生命周期。不等于模型权重或推理引擎本身。
- Cordis：DSH 内置插件内核，提供 Context、inject、Events、Teardown 语义。
- Bundle：可版本化的插件与 tool 集合，如
@deepseek-ai/bundle-standard。 - Profile：命名环境配置块：model、session、sandbox、approval、otel 等。
- Patch：对 effective 配置的短期覆盖，应带 expire 并尽快合并。
- Preset：面向用户的 Bundle 别名：Standard/Code/Minimal/Creator。
- Session Log：append-only jsonl 事件流，含 user、assistant、tool、approval 事件。
- Teardown：插件卸载时执行的清理函数，由 ctx.effect 注册。
- wrap：Events API 中的拦截器层，approval 插件在此 deny/allow。
- Spawn：创建独立子 Agent Session，有独立 sessionId 与 tool 集。
- Fork：从某 turn 复制 Session 前缀后分叉探索。
- Replay：用录制事件回放，mock 外部依赖，用于 CI。
- MCP：Model Context Protocol，标准化外部 tool Server。
- OTel：OpenTelemetry，统一 traces/metrics/logs。
- Skill：声明式能力包，由 UI 或配置启用，仍受 sandbox 约束。
附录 B：参考链接
- 官方仓库：https://github.com/deepseek-ai/deepseek-harness
- 七天子站：https://dsh.chenxiaoshivivid.top/
- 快速开始：getting-started
- MCP 规范：https://modelcontextprotocol.io/
附录 C：源码阅读路线
建议顺序：docs/architecture.md → packages/cordis/context.ts → bundle loader → bundles/standard → packages/host → apps/web。阅读时带着三问：apply 顺序？tool 如何 register？teardown 谁调用？
生产环境应将 Bundle 版本 pin 在 cordis 或部署 manifest 中，避免 npx latest 导致 tool schema overnight 变化引发 Replay 失败。
编写 Cordis 插件时，单元测试应覆盖 mount→inject→unmount 循环，断言 teardown 后无 open handle。
MCP Server 进程崩溃时，Host 应写入 mcp_disconnect 事件并在 UI surfaced，而非 silent retry 耗尽 turn。
context.compress 选 hybrid 时，建议对 system prompt 打 tag immutable，压缩器跳过该块。
多实例 Host 必须共享 session.store 后端，否则 Resume 在负载均衡下会 404 Session。
approval.rules 的 match 模式建议从 strict 到 permissive 分层，避免一条 deny 规则误杀 read_file。
Spawn 子 Agent 应继承父 sandbox 约束的子集而非超集，防止 privilege escalation。
Fork Session 应设置 TTL job 清理 .dsh/sessions/fork-* 避免磁盘占满。
OTel resource 属性应含 service.name=dsh-host 与 deployment.environment 便于仪表盘过滤。
Skill 启用不应动态 widen sandbox；若 Skill 需要新 path，应走 Profile 变更 PR。
LangChain 迁移时，先把 Callback 映射到 observe，再迁 Tool 为插件，最后删 Chain 代码。
Incident 后务必新增 Replay case 进 CI，防止同一 tool 误执行回归。
Creator 实验日志应单独 retention bucket，避免与 prod Session 混备。
工具 description 中文/英文应一致，避免模型在 multilingual prompt 下选错 tool。
Host ready 探针应检查 MCP optional server 连通，而非仅 HTTP 200。
附录 D：一次完整请求的工程时间线
下面用「用户要求在仓库里加路由」为例，把 Host Plane 到 Client Plane 的事件顺序钉死。理解这条时间线，比背术语更能指导排障。
D.1 为什么「看起来卡住」往往不是模型慢
| 表象 | 更可能的运行时原因 | 首选检查 |
|---|---|---|
| UI 转圈很久 | 审批 ASK 等待人工，或 MCP Server 挂起 | Session 最后事件是否 APPROVAL / MCP |
| 同一命令执行两次 | Effect 泄漏或热更新后旧插件未 Teardown | 插件树与定时器句柄 |
| Replay 与当时不一致 | Bundle 未 pin，tool schema overnight 变化 | manifest 版本与 schema hash |
| Fork 后权限变大 | 子会话错误继承超集沙箱 | Spawn/Fork 策略是否子集约束 |
| Token 飙升 | 压缩策略关闭或 immutable 标签缺失 | compaction 配置与 system prompt 体积 |
D.2 Profile 切换的语义边界
切换 Profile 不是换皮肤：它会重建 Agent Preset Plane 上的工具实例与 Prompt 片段。Host Plane 单例（全局 tools 注册表实现、llm 适配器进程内缓存）可能保留，但会话隔离 Realm 会按 isolate 规则重建。因此生产变更应记录：「哪些服务是 Host 级单例、哪些是会话级」。否则会出现「换了 Minimal 仍能调用网页搜索」这类幽灵能力——通常是旧会话未隔离或 Patch 错误合并。
D.3 配置合并的工程约定
建议团队约定三级优先级（高覆盖低）：运行时 CLI 覆盖 > Patch > Profile 默认 > Bundle 默认。任何「为什么我的 deny 没生效」工单，先打印有效配置快照（resolved config），再查规则优先级。把 resolved config 写入 Session 启动事件，是事后审计的廉价高收益实践。
D.4 与评测体系的接口
Minimal 预设存在的意义是让「模型能力」与「工具面宽度」解耦。若用 Standard 跑 Terminal Bench 同类任务，分数会混入工具与审批策略噪声。工程上应维护：bench.profile=minimal 与 prod.profile=standard 两套流水线，共享同一模型适配器插件版本，以便横向对比。
D.5 安全设计的分层
- 描述层：工具 description 不诱导越权；
- 策略层：approval 矩阵 auto/ask/deny；
- 沙箱层：workdir 与网络策略；
- 隔离层：Creator / 不可信代码进强隔离；
- 审计层：Session Log + OTel 不可抵赖。
缺少任一层，都会在演示环境「看起来安全」、生产环境「一次越权」。
D.6 多 Agent 的成本与一致性
Spawn 带来隔离与并行，也带来：上下文复制成本、结果聚合契约、失败偏序。建议父 Agent 只接收结构化摘要（JSON schema），禁止子 Agent 直接写共享工作区的同一文件而无锁。Fork 适合「反事实探索」，不适合作为默认并行手段——共享历史会让审计变复杂。
D.7 技能（Skill）与插件的边界
Skill 是可复用的任务配方（例如「标准 Git 提交流程」），插件是运行时能力单元（例如 git 工具集）。Skill 不应在运行时动态扩大沙箱路径；需要新权限就走 Profile/Patch 变更评审。把 Skill 当成「免审插件」是常见事故源。
D.8 观测信号最小集
上线前至少具备：dsh.session.started、dsh.tool.calls（含 name/result）、dsh.approval.decision、dsh.model.tokens、dsh.effect.leak_suspect（若有检测器）、dsh.mcp.up。没有审批与泄漏信号的仪表盘，只能证明「模型还在说话」，不能证明「运行时还健康」。
D.9 教学与生产的分工
七天学会子站负责建立直觉（生命周期动画、预设对比、审批模拟）；本系列文档负责把直觉升级为可交付规范（配置分层、威胁建模、Incident 剧本、兼容性矩阵）。两者交叉阅读时，用实验室验证机制，用文档固化团队约定。
D.10 阅读官方源码的顺序建议
- 启动入口与 Profile 装载；
- Cordis
apply与服务 provide 路径； - agent-loop 插件的工具调用状态机；
- approval wrap 点；
- sessions append 与 checkpoint；
- MCP 客户端发现与工具注入。
按此顺序，你不会在 UI 组件里迷路。
附录 E：团队沟 通用的「运行时词汇表」
跨职能协作时，词汇不统一会造成错误分工：产品以为「再写长一点提示词」就能修审批误杀，平台以为「换模型」就能修 Effect 泄漏。建议把下列词条写进内部术语表。
| 词汇 | 推荐定义 | 不应混淆为 |
|---|---|---|
| Harness | Agent 持续运行与能力装配的运行时 | 某一家模型的商标功能 |
| Profile | 命名的能力与安全姿态组装 | UI 主题 |
| Patch | 声明式覆盖层 | 随手改源码 |
| Teardown | 挂载副作用的反向清理 | 进程被 kill |
| Session Log | append-only 执行轨迹 | 普通应用 access log |
| Approval | 工具调用策略裁决 | 登录鉴权 |
| Spawn | 新隔离子会话 | 线程 |
| Fork | 基于历史检查点的分支 | Git 分支的字面等同（仅类比） |
| Compaction | 上下文压缩并保留决策点 | 简单截断开头 |
| Bundle | 可版本分发的插件包 | zip 随便打包 |
把词汇表贴在 on-call 频道置顶，能减少大量错因归因。导论的目标，正是让你拥有这张表背后的判断力：先问「这是模型问题还是运行时问题」，再决定是调 Prompt、改 Profile，还是修插件生命周期。