跳到主要内容

DeepSeek Harness 常见问题（深度问答）

如何使用本文

共 45 个深度问答，按主题分类。每个答案包含原理、怎么做、常见误区三部分。配套实战见 七天学会子站 与文档 入门、快速开始、开发指南、最佳实践。

目录​

概念​

安装配置​

插件开发​

预设选型​

安全审批​

Session/可观测​

多 Agent​

生产运维​

与其它框架对比​

Q1: DeepSeek Harness 和直接调用大模型 API 有什么本质区别？​

原理

直接 API 是「一问一答」无状态请求；Harness 是持久 Agent 运行时，负责在多轮对话中挂载插件、执行工具、记录 Session 事件、管理审批与沙箱。原理是 Agent = Model + Harness：模型只负责推理，Harness 负责「手、记忆、规则」。

怎么做

安装 DSH 后通过 Web UI 或 CLI 启动 Cordis 内核，选择 Profile（如 Standard），配置模型 Key。Harness 自动加载 Bundle 中的插件图谱，你的对话发生在 Session 内，工具调用走管道。阅读 入门介绍 理解架构图。

常见误区

误区：认为 Harness 只是「带工具的 ChatGPT 壳」。实际上插件化、Teardown、事件溯源是核心差异，忽略会导致生产泄漏与不可审计。

Q2: Cordis 插件内核中的「Everything is a Plugin」是什么意思？​

原理

模型接入、Agent 循环、工具注册、Web UI、MCP 客户端等在 DSH 中均以 Cordis 插件形式存在。内核只做依赖解析、生命周期与事件总线，能力由插件组合。原理是可逆副作用 ctx.effect() 保证挂载/卸载对称。

怎么做

编写插件实现 apply(ctx)，用 ctx.provide 注册服务，用 ctx.effect 注册 Teardown。通过 Bundle 声明插件列表，Profile Patch 调整启用集。见 开发指南。

常见误区

误区：把所有逻辑写进单个「大插件」。应拆分为可测试、可 Teardown 的小插件，避免循环依赖。

Q3: Bundle、Profile、Patch 三层配置如何协同？​

原理

Bundle 是基础能力包（含插件列表与默认策略）；Profile 是环境级配置（如 standard、code）；Patch 是局部覆盖（YAML/JSON），用于生产/评测差异。原理是组合优于继承，Patch 可版本化与回滚。

怎么做

仓库维护 bundles/、profiles/、patches/ 目录。启动参数或 env 指定 PROFILE=prod-standard 加载对应 Patch。生产与评测 Patch 分文件，见 最佳实践 · Profile 分离。

常见误区

误区：在 Web UI 手工改配置当 Patch。手工改无法审计、无法 CI 门禁。

Q4: 什么是可逆副作用（Reversible Effects）？为什么生产必须关心？​

原理

插件通过 ctx.effect(fn) 注册副作用，fn 返回 Teardown 函数。卸载插件或关闭实例时必须执行 Teardown，释放连接、监听器、临时资源。原理是长期运行进程不同于一次性脚本，资源泄漏会累积。

怎么做

每个 effect 写对称 Teardown；PR 用 泄漏实验室 验证。Code Review 检查表见 最佳实践。

常见误区

误区：「进程重启就好了」——生产不能频繁重启，且 K8s 滚动升级时旧 pod Teardown 不完整会影响连接池。

Q5: DSH 说的「三层平面」指什么？​

原理

通常指控制面（配置、插件挂载）、数据面（Session Log、上下文）、执行面（工具、沙箱、审批）。原理是职责分离便于扩展与审计。

怎么做

设计功能时明确属于哪一面：例如审批策略属控制面+执行面交界；Session 压缩属数据面。多 Agent Spawn 跨控制面与执行面。

常见误区

误区：把 Session Log 当数据库随便改。Log 应 append-only，改历史破坏 Fork/Replay。

Q6: Node.js 版本有什么要求？pnpm 和 npm 选哪个？​

原理

官方要求 Node >= 18，推荐 20 LTS。原理是 Cordis 与现代工具链依赖 ES module 与新 API。

怎么做

npx @deepseek-ai/deepseek-harness 或 clone 后 npm install && npm run dev。monorepo 可用 pnpm 节省磁盘。见 快速开始。

常见误区

误区：用 Node 16 或混用包管理器锁文件导致依赖解析不一致。

Q7: 启动后 Web UI 打不开怎么排查？​

原理

原理：Harness 绑定监听地址与端口，可能被占用或防火墙拦截；云主机还需安全组。

怎么做

查控制台 Listening on http://...；ss -tlnp 看端口；本机 curl；云厂商开 inbound。Docker 映射 -p 3000:3000。

常见误区

误区：只查 Harness 不看反向代理（Nginx）是否配了 WebSocket 升级。

Q8: 模型 API Key 应该放在哪里？​

原理

原理：Key 属于秘密，不应进 Session Log、插件源码或 Git。

怎么做

使用环境变量或 .env.local（gitignore）；生产用 Vault/K8s Secret 注入。轮换时滚动重启实例。

常见误区

误区：把 Key 写在 Profile Patch 并 commit。

Q9: 如何在 Docker / Kubernetes 中部署？​

原理

原理：Harness 是有状态组件（Session Log），需持久卷与优雅关闭。

怎么做

镜像内置 Bundle 版本；挂载 PVC 到 Session 目录；配置 liveness/readiness；SIGTERM 触发 Teardown。参考 最佳实践 · 多实例。

常见误区

误区：无持久卷导致 pod 重启丢 Session；无 graceful shutdown 导致 Teardown 跳过。

Q10: 最小插件长什么样？​

原理

原理：插件是 { name, apply(ctx) } 对象，apply 内注册能力与副作用。

怎么做

export default { name: 'hello', apply(ctx) { ctx.provide('hello', () => 'world'); } };

挂载后在内核可视化器观察。Day2 见 从零到一。

常见误区

误区：忘记 name 唯一性，与内置插件冲突导致 mount 失败。

Q11: 如何向 Agent 暴露自定义工具？​

原理

原理：工具需 Schema（名称、描述、参数 JSON Schema）、执行函数、可选审批分类。描述质量影响模型调用正确率。

怎么做

在插件中注册 tool handler，声明 parameters；走工具管道自动进入 Agent 图谱。复杂工具拆 input validation 与执行。

常见误区

误区：Schema 过于宽泛（z.any()），模型传错参导致运行时错误。

Q12: 插件之间如何共享服务？​

原理

原理：Cordis 依赖注入，ctx.provide / ctx.inject（以官方 API 为准）解析依赖图。

怎么做

在 apply 中 provide 接口；依赖方声明 depends 或 inject。避免全局单例绕过 Teardown。

常见误区

误区：循环依赖导致 mount 顺序不确定；应用拓扑排序或拆分插件。

Q13: 如何调试插件挂载失败？​

原理

原理：mount 失败常因依赖缺失、版本冲突、同步 throw。

怎么做

看启动日志 dsh.plugin.mount.errors；在 内核可视化器 看依赖图；Minimal Profile 只挂目标插件 isolate。

常见误区

误区：在生产 Profile 直接试挂未 review 插件。

Q14: 发布插件到社区要注意什么？​

原理

原理：社区插件会被他人挂载到各种 Profile，需明确权限需求与 Teardown 质量。

怎么做

README 写清 env、Profile 要求；打 dsh-plugin topic；通过 CR 检查表；提供 Minimal 测试说明。毕业作业见 从零到一 Day7。

常见误区

误区：默认请求 Creator 权限；应最小权限原则。

Q15: 四种预设 Standard / Code / Minimal / Creator 怎么选？​

原理

原理：预设是不同工具+审批+Token 默认的 Bundle，不是 UI 主题。

怎么做

日常对话 Standard；写代码 Code；基准评测 Minimal；受控创作 Creator（隔离环境）。 预设实验室 并排对比。

常见误区

误区：生产为了省 Token 用 Minimal；或图方便开 Creator。

Q16: Minimal 适合哪些场景？​

原理

原理：工具少、Token 低、行为可重复，适合 CI 与回归。

怎么做

维护 eval-minimal Patch；固定模型参数；只读工具为主。不与生产共用 Pool。

常见误区

误区：用 Minimal 做复杂代码任务然后抱怨「Agent 不好用」。

Q17: Code Profile 和 Standard 能否同一实例？​

原理

原理：可以但工具图谱叠加会增大模型选错工具概率与安全面。

怎么做

推荐分 Pool 或分实例；路由 Header 区分。Code 实例加强 shell 审批。

常见误区

误区：Code 与用户对话混用导致 shell 工具对用户 Session 可见。

Q18: Creator 为什么需要安全警告？​

原理

原理：Creator 工具权限高，模型误调用可造成不可逆破坏。

怎么做

独立集群、全审批、短生命周期、审计延长。生产用户面禁用。见 最佳实践 · Creator 隔离。

常见误区

误区：「我是开发者不怕」——模型行为非完全可控。

Q19: 文件系统沙箱能防什么、不能防什么？​

原理

原理：沙箱限制工具路径，防误操作与模型越界，非防恶意插件。

怎么做

配置 workspace 根、路径规范化、禁止沙箱外 write；对外诚实声明边界。

常见误区

误区：宣称「绝对安全」；或沙箱内仍允许任意 shell。

Q20: 如何设计工具审批矩阵？​

原理

原理：按工具类型、路径、命令模式、角色分级，默认拒绝高风险。

怎么做

表格化策略；approval-sim 预演；结果写 Session Log。见 最佳实践 · 审批矩阵。

常见误区

误区：只有 allow/deny 两档，无「首次确认」「配额」中间态。

Q21: MCP 外部工具的安全风险如何控？​

原理

原理：MCP server 能力不受 DSH 沙箱完全约束，取决于 server 实现。

怎么做

MCP server 白名单；按 server 分级审批；Teardown 关闭连接；审计 tool name 与 args。

常见误区

误区：连接不可信 MCP 并给 Standard Profile 全自动通过。

Q22: 如何防止 Session 中的敏感数据泄露？​

原理

原理：Log 与 trace 可能含用户输入、工具输出、密钥若配置不当。

怎么做

日志脱敏；Key 仅 env；导出 Session 前 PII 扫描；Retention 分级。

常见误区

误区：把完整 Session 贴到公开 Issue。

Q23: Session Log 是什么？和聊天历史有何不同？​

原理

原理：Log 是 append-only 事件流（消息、工具调用、审批、压缩、fork），支持溯源而非仅消息数组。

怎么做

启用持久卷；用 Resume 恢复；Fork 做分支实验；Replay 复盘事故（只读模式）。Day5 从零到一。

常见误区

误区：直接删改 Log 文件「修对话」——破坏审计与 Fork 链。

Q24: Resume、Fork、Replay 分别怎么用？​

原理

原理：Resume 继续同 Session；Fork 从某事件点复制新 Session；Replay 重放事件 often 用于调试。

怎么做

UI 或 API 选 checkpoint；Fork 后独立 evolution；Replay 禁写工具或隔离环境。

常见误区

误区：Replay 在生产直接重放写操作造成二次破坏。

Q25: OpenTelemetry 应该采哪些指标？​

原理

原理：除模型延迟外，Harness 特有信号是工具成功率、审批积压、插件 mount 错误、Session 体积。

怎么做

接入 OTel Collector；见 最佳实践 · OTel 指标表。

常见误区

误区：只监控 GPU/模型，工具 timeout 淹没用户体验。

Q26: 上下文压缩会不会丢重要信息？​

原理

原理：压缩用摘要替换早期轮次，降低 token；系统指令与近期目标应保留。

怎么做

配置 triggerRatio；工具错误保留原文；压缩事件进 Log；staging A/B 完成率。

常见误区

误区：阈值过高从不压缩导致爆窗；或 aggressive 压缩丢 plan。

Q27: Spawn 和 Fork 子 Agent 有什么区别？​

原理

原理：Spawn 创建新 Agent 实例（新 Session/工具集可能不同）；Fork 从 Session 事件分叉。Spawn 偏编排，Fork 偏实验分支。

怎么做

Spawn 时指定 Profile 与子任务 quota；父 Session 记录 child id；子 Agent Teardown 独立。Day6 实验室。

常见误区

误区：Spawn 无限制导致 Agent 指数爆炸与 Token 破产。

Q28: 工作流模式与计划模式如何选？​

原理

原理：工作流是预定义步骤图；计划是模型动态生成步骤再执行。工作流可控，计划灵活。

怎么做

合规场景用工作流；探索性任务用 plan；Hybrid 计划+人工审批关键步。

常见误区

误区：复杂任务全用 plan 无 checkpoint，失败重跑成本极高。

Q29: 多 Agent 之间如何传递上下文？​

原理

原理：通过 Session 元数据、共享只读服务或父 Agent 摘要传递，避免整 Log 复制爆 token。

怎么做

定义 structured handoff（目标、约束、已完成步）；子 Agent 独立 workspace。

常见误区

误区：子 Agent 继承父 shell 环境导致权限串扰。

Q30: 如何做 Harness 版本升级与回滚？​

原理

原理：Bundle 版本绑定镜像 tag；Patch 版本化；Session Log 格式可能需迁移。

怎么做

Canary → 全量；Git tag 回滚；Minimal 基准门禁。 最佳实践 · 变更回滚。

常见误区

误区：生产直接 npm update 无 tag。

Q31: Session 磁盘满了怎么办？​

原理

原理：append-only Log 增长不可逆，需归档与 retention。

怎么做

紧急归档冷存储；临时缩短 retention；扩容；查异常大 tool output。

常见误区

误区：删随机 Session 文件无 manifest 更新导致 Resume 失败。

Q32: 如何控制 Token 成本？​

原理

原理：成本 = 模型单价 ×（input+output token）× 轮次；工具输出占 input 大头。

怎么做

Profile 预算；压缩；工具轮次上限；小模型路由；OTel 分 tenant 账单。

常见误区

误区：只限对话条数不限 tool 循环。

Q33: 多实例部署 Session 如何共享？​

原理

原理：需共享存储或 Session 服务，否则 Resume 粘错实例丢数据。

怎么做

NFS/S3+锁；网关 sticky；或 centralized session API。

常见误区

误区：无 sticky 无共享仍水平扩展。

Q34: DSH 和 LangChain / LangGraph 怎么选？​

原理

原理：LangChain 偏链式/图编排与集成生态；DSH 偏运行时插件化、Teardown、预设对比、Session 溯源。

怎么做

要运行时可控、可逆副作用、多 Profile → DSH；要快速原型丰富集成 → LangChain；可并存。见 最佳实践 · 选型。

常见误区

误区：期望 LangChain 链直接替换 Cordis 插件模型而不改架构。

Q35: DSH 和 OpenClaw 是什么关系？​

原理

原理：OpenClaw 侧重多通道消息网关；DSH 侧重 Agent 运行时与 Cordis 内核。互补多于竞争。

怎么做

消息入站 OpenClaw → 转发 Harness Session 处理 → 出站回复。各守边界。

常见误区

误区：在一个进程里混用两套生命周期无 Teardown 规划。

Q36: DSH 和 MCP 是什么关系？​

原理

原理：MCP 是工具协议标准；DSH 通过 MCP 客户端插件接入外部 server，工具进入 Agent 图谱。

怎么做

部署 MCP server；Harness 配置 client 插件；审批按 server 分级。 开发指南 · MCP。

常见误区

误区：认为装了 MCP 就不需要 Harness 审批与沙箱。

Q37: Agent 运行时和 Serverless Function 执行 Agent 有何不同？​

原理

本题属于「概念」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

查阅 开发指南 与 最佳实践；在 子站实验室 做对照实验；涉及生产配置变更走 Patch 版本化与 canary 流程。

常见误区

误区：用通用 LLM 应用经验直接套用，忽略 Teardown、Profile 与 append-only Log 约束。

Q38: 如何在离线环境安装 Harness？​

原理

本题属于「安装配置」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q39: TypeScript 和 JavaScript 插件有何限制？​

原理

本题属于「插件开发」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q40: 能否自定义第五种预设？​

原理

本题属于「预设选型」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q41: 双人审批如何与 Harness 集成？​

原理

本题属于「安全审批」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q42: Session Log 能否导出做法务证据？​

原理

本题属于「Session/可观测」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q43: 子 Agent 数量配额如何配置？​

原理

本题属于「多 Agent」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q44: Harness 如何做蓝绿部署？​

原理

本题属于「生产运维」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

Q45: AutoGPT 类框架与 DSH 差异？​

原理

本题属于「与其它框架对比」扩展。Harness 作为 Cordis 驱动的运行时，需要从插件生命周期、Session 溯源与安全边界理解该问题，而非仅从单次 API 调用角度思考。

怎么做

常见误区

仍有问题？​

附录：主题索引与交叉阅读​

Q1 延伸阅读​

关于「DeepSeek Harness 和直接调用大模型 API 有什么本质区别？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理直接 API 是「一问一答」无状态请求；Harness 是**持久 Agent ...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，DeepSeek Harness 和直接调用大模型 API 有什么本质区别 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q2 延伸阅读​

关于「Cordis 插件内核中的「Everything is a Plugin」是什么意思？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理模型接入、Agent 循环、工具注册、Web UI、MCP 客户端等在 DSH ...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，Cordis 插件内核中的「Everything is a Plugin」是什么意思 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q3 延伸阅读​

关于「Bundle、Profile、Patch 三层配置如何协同？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理Bundle 是基础能力包（含插件列表与默认策略）；Profile 是环境级配置...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，Bundle、Profile、Patch 三层配置如何协同 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q4 延伸阅读​

关于「什么是可逆副作用（Reversible Effects）？为什么生产必须关心？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理插件通过 ctx.effect(fn) 注册副作用，fn 返回 Teardo...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，什么是可逆副作用（Reversible Effects）？为什么生产必须关心 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q5 延伸阅读​

关于「DSH 说的「三层平面」指什么？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理通常指控制面（配置、插件挂载）、数据面（Session Log、上下文）、执行面...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，DSH 说的「三层平面」指什么 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q6 延伸阅读​

关于「Node.js 版本有什么要求？pnpm 和 npm 选哪个？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理官方要求 Node >= 18，推荐 20 LTS。原理是 Cordis 与现代...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，Node.js 版本有什么要求？pnpm 和 npm 选哪个 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q7 延伸阅读​

关于「启动后 Web UI 打不开怎么排查？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：Harness 绑定监听地址与端口，可能被占用或防火墙拦截；云主机还需安全...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，启动后 Web UI 打不开怎么排查 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q8 延伸阅读​

关于「模型 API Key 应该放在哪里？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：Key 属于秘密，不应进 Session Log、插件源码或 Git。...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，模型 API Key 应该放在哪里 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q9 延伸阅读​

关于「如何在 Docker / Kubernetes 中部署？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：Harness 是有状态组件（Session Log），需持久卷与优雅关闭...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，如何在 Docker / Kubernetes 中部署 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q10 延伸阅读​

关于「最小插件长什么样？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：插件是 { name, apply(ctx) } 对象，apply 内...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，最小插件长什么样 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q11 延伸阅读​

关于「如何向 Agent 暴露自定义工具？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：工具需 Schema（名称、描述、参数 JSON Schema）、执行函数...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，如何向 Agent 暴露自定义工具 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q12 延伸阅读​

关于「插件之间如何共享服务？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：Cordis 依赖注入，ctx.provide / `ctx.inje...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，插件之间如何共享服务 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q13 延伸阅读​

关于「如何调试插件挂载失败？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：mount 失败常因依赖缺失、版本冲突、同步 throw。...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，如何调试插件挂载失败 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q14 延伸阅读​

关于「发布插件到社区要注意什么？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：社区插件会被他人挂载到各种 Profile，需明确权限需求与 Teardo...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，发布插件到社区要注意什么 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q15 延伸阅读​

关于「四种预设 Standard / Code / Minimal / Creator 怎么选？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：预设是不同工具+审批+Token 默认的 Bundle，不是 UI 主题。...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，四种预设 Standard / Code / Minimal / Creator 怎么选 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

Q16 延伸阅读​

关于「Minimal 适合哪些场景？」，建议在掌握原理后动手：打开 七天学会 对应 Day，在 lab 验证假设。生产环境务必对照 最佳实践 清单。

维度要点
原理原理：工具少、Token 低、行为可重复，适合 CI 与回归。...
实践见上文「怎么做」
避坑见上文「常见误区」

从工程角度，Minimal 适合哪些场景 还涉及团队规范：代码审查、Patch 评审、on-call runbook 更新。Harness 问题往往不是单点配置，而是 Profile、插件、Session 三者的交互。排查时依次检查：当前 Profile 是否预期、插件 mount 是否完整、Session Log 最后事件是否异常工具调用。

补充问答：运维与架构边界​

Q46. 为什么我说「重启就好了」不是可持续策略？​

因为未 Teardown 的句柄、错误的 Profile 合并、MCP 半连接会在重启后按相同配置回来。重启只能证明问题与「长时状态」相关，下一步必须用插件树与 Session 定位根因，并补回归测试。

Q47. 如何判断该写插件还是接 MCP？​

需要进程内低延迟、强类型、与审批深度绑定 → 插件。需要跨语言复用、由别的团队运营工具生命周期 → MCP。两者都要时，用门面插件适配 MCP，并避免双重注册。

Q48. Session 文件暴涨怎么办？​

开启 compaction、外置大工具输出、按保留策略归档、检查是否有循环 tool 调用。同时查是否日志级别把模型全文 debug 进了同一卷。

Q49. 多 Host 如何共享会话？​

共享 session store（对象存储/DB），并保证 sticky 或无本地唯一假设。否则 Resume 会随机 404。检查点格式需版本化。

Q50. 模型换厂商后工具不调用了？​

先对比 tool schema 与 description 是否被适配器截断；再查新模型对 tool calling 的支持差异；最后才调 Prompt。用同一 Minimal 任务做 A/B。

Q51. 如何防止「评测刷分」？​

评测锁定 Minimal 与数据集版本；生产 Standard 不得用于官方分数宣称。对外分享注明工具面。

Q52. 审批会成为瓶颈吗？​

会。用规则自动处理只读与低风险，把人工注意力留给高风险；对重复 ask 做规则候选推荐（需人工确认后固化）。

Q53. Fork 会带来隐私问题吗？​

会。Fork 复制历史，权限与去标识策略必须继承。对敏感会话禁止 Fork 或强制脱敏。

Q54. 怎样证明插件没有泄漏？​

自动化：重复 mount/unmount + 句柄计数；实验室泄漏检测；生产指标 leak_suspect。代码审查不能替代。

Q55. DSH 能否完全替代 LangGraph？​

若你的核心需求是复杂业务状态机，LangGraph 仍强；若核心需求是可插拔运行时、热更新与会话溯源，DSH 更合适。可组合：图负责业务阶段，DSH 负责执行面。