@@ -6,7 +6,7 @@ harness 扩展表面的参考形态。代码片段省略了 import 和辅助实
## 工具插件
工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md ](adding-a-tool.md )——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON- Schema `ToolDefinition` （ `defineTool` 是为第一方工具提供的类型化语法糖。
工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md ](adding-a-tool.md )——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON Schema `ToolDefinition` （ `defineTool` 是为第一方工具提供的类型化语法糖。
## 钩子插件（以权限门禁为例）
@@ -100,29 +100,29 @@ export function apply(ctx: Context) {
| 产品功能 | 插件机制 |
|---|---|
| 钩子系统（用户级 + 项目级） | `agent/session-start` 、`agent/pre-step` 、`agent/request` 、`tools/pre-execute` 、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器； `agent/turn-stopping` 则可通过 steering 触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话回合 ，独立的命令/工具生产方分别提供人类/模型控制 |
| 钩子系统（用户级 + 项目级） | `agent/session-start` 、`agent/pre-step` 、`agent/request` 、`tools/pre-execute` 、`tools/post-execute` 和 `agent/turn-stopping` 上的监听器； `agent/turn-stopping` 则可通过 steering（中途引导） 触发下一步；`dsh-hooks-claude` / `dsh-hooks-codex` 桥接器将钩子配置文件映射到这些 seam 上 |
| `/goal` | `ctx.goals` 管理持久状态，`dsh-goal-session` 通过公共 `Agent` 调度同会话 Round ，独立的命令/工具生产方分别提供人类/模型控制 |
| `/loop` | 在 `turn/end` 会话事件上 `followup()` 下一次迭代；或强制继续 |
| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的 prompt /工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code` ）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
| 排队消息 + steering（中途引导） | 核心 `Agent.followup()` / `Agent.steer()` |
| 动态工作流 | `ctx.workflows` + worker-thread 引擎 + `workflow` 工具；结构化的进程内子任务通过作用域化的提示词 /工具注册、单调工具守卫、最终 `tools/result` 提交（包括外层 `run_code` ）和结构化输出执行的单调 `concludeTurn()` 标记来强制输出 |
| 排队消息 + steering | 核心 `Agent.followup()` / `Agent.steer()` |
| 上下文压缩（ ） （ `ctx.compact` seam + `dsh-compact-basic` ；自动压力检查运行在串行 `agent/pre-step` ，规范化溢出恢复运行在 `agent/request-error` ，手动调用方使用同一个压缩服务（[压缩 Agent Note ](../../.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md )——面向模型的 `/compact` 消费方工具已推迟） |
| 系统提示词可配置性 | `ctx.systemPrompt.section()` ，支持排序与作用域局部覆盖 |
| AGENTS.md（ ） provider |
| AGENTS.md（ ， ） tool-result 监听器调用 `agent.inject()` |
| AGENTS.md（ ） 提供方 |
| AGENTS.md（ ， ） 工具结果 监听器调用 `agent.inject()` |
| 内置工具 | `ctx.tools.register()` ； `dsh-tool-*` 系列（ ）
| ToolSearch / 渐进式披露 | 当可见集变化时替换一个作用域化的 `ctx.tools.restrict()` 注册；注册表保持展示、查找和执行三者对齐 |
| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装器 可替换 `exec.signal` 、委托执行，并在同一词法生命周期内检视规范化结果 |
| 工具截止时间 / 重试 / 指标 | 用 `tools/execute` 包裹核心分发；包装层 可替换 `exec.signal` 、委托执行，并在同一词法生命周期内检视规范化结果 |
| 最终工具结果指标 / 审计 / 捕获 | 用 `tools/result` 观察不可变的权威结果；仅当插件需要变换结果或附加上下文时才使用 `tools/post-execute` |
| 单调终端轮次策略 | 从成功的终端工具调用 `ToolExecution.concludeTurn()` ；同一响应中后续工具调用仍可由守卫阻止，循环在该步骤后停止 |
| 子进程沙箱（ ） `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
| 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode` ](../../packages/plan/plan-mode/README.md ) — 落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn` /`-fork` /`-acp` /`-codex` /`-claude-code` /`-dsh-sdk` ） `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
| Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode` ](../../packages/plan/plan-mode/README.md )： `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
| sub agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn` /`-fork` /`-acp` /`-codex` /`-claude-code` /`-dsh-sdk` ） `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
| MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
| S kill（ ） `inject()` 注入 skill 内容 |
| 记忆 | section provider + 工具 |
| s kill（ ） `inject()` 注入 skill 内容 |
| 记忆 | section 提供方 + 工具 |
| 定时任务（ ） `followup(…, {source: {kind: 'cron', …}})` ／忙碌时 `inject()` 通知 |
| UI（ ； （ ） ） `session/event` （助手分片、边界、工具活动）；输入 → `followup()` |
| 遥测 / 可回放 trace | `session/event` → JSONL； `sessions.create(id, { seed })` |
| 模型适配器 | 通过 `registerAdapter` 注册 `LlmAdapter` 子类（`dsh-llm-deepseek` 、`dsh-llm-pi-ai` ）
| 插件热重载 | 每个注册都是一个 `ctx.effect` → vendor 的 HMR（ ）
| 插件热重载 | 每个注册都是一个 `ctx.effect` → 随仓库提供 的 HMR（ ）
Turtle