工具全集与能力分类
每一个模型可见工具的输入、输出、策略与 UI 意图
结论：DeepSeek Harness 没有一张固定的“默认工具表”，只有可证明完整的工具包上界和由 composition 解出的运行时视图
固定基线上，上游生成目录覆盖 24 个 shipped tool package、52 个 schema 条目和 51 个唯一生成名称；唯一重名是一次性 shell 与持久 PTY 两种实现都注册为 bash。生成器还记录了未单独生成 schema heading 的 shipped 配置别名 subagent_fork，所以被目录代表的 distinct shipped names 是 52 个。这些名字绝不会默认同时出现：标准 Web 预设在 Linux/有 attachment service 的基线组合中是 25 个 root 工具，minimal 预设只有 2 个，Code/Cordis/自定义 preset、scope restriction、动态插件和子 Agent 身份还会继续改变集合。
本章的“全集”从生成目录的 package headings 与 tool headings 计数，并逐行核对 package map；“实际集合”则从 shipped preset 与 host service 条件重新求值。生成器对每个工具包启动独立真实 Context、读取 ctx.tools.schemas()，并用磁盘 glob 阻止漏列新工具包。TOOLCAT-GENERATEDTOOLCAT-GENERATOR
1. 三个不能混为一谈的集合
| 集合 | 固定基线结论 | 回答的问题 | 不能推出什么 |
|---|---|---|---|
| 生成目录上界 | 24 package sections；52 schema 条目；51 唯一生成名称；另记 1 个 shipped alias | 所有 shipped packages/*/tool-* 在选定配置下能贡献什么 | 不表示一个 Agent 同时看见全部 |
| Composition 集合 | preset + host services + platform + feature flags | 某一部署装载了哪些 definition | 不表示每个 scope 都有权看见 |
| Request 集合 | scope view + restriction + native/code/both projection | 本次模型请求实际收到哪些 schema | 不表示调用一定获批或后端可用 |
还有第四个时间维度：definitions 是 live Cordis effects。排队后、真正 start 前的热装载/卸载可改变 visibility 或并行分类；因此审计必须保存 request header 与 durable call/result，不能只拿进程当前 catalog 反推历史。
2. 生成目录为何比静态 grep 更可信、又为何仍不是运行时真相
glob packages/*/tool-* → completeness guard
for each manifest entry:
fresh Context → SystemPrompt → ToolRuntime → package-specific seams
→ mount plugin → ctx.tools.schemas(scope) → sort → dispose
render package map + name + description + JSON-Schema + source linkManifest 漏掉磁盘上的工具包会直接失败；已列工具包因缺 service 而 pending、最终一个 schema 都没注册也会失败。每个 package 独立 boot，避免前一个包的注册被错误归因到后一个包。TOOLCAT-GENERATOR
3. 完整 package/name 地图（24 包，51 个生成名称 + 1 个 shipped 配置别名）
| 能力族 / package | 模型可见名称 | 主要 seam / 副作用 |
|---|---|---|
Human · tool-ask-user | ask_user_question | 等待 UI/provider 人类回答；call 在等待期间保持打开 |
Code transport · tools | run_code | Code Mode 保留 transport；嵌套 subcall 重新进入完整 tool pipeline |
Plan · plan-mode | exit_plan_mode | 评审计划；批准后写 plan/mode inactive |
| One-shot shell | bash / pwsh | 新进程、可选后台 job；平台二选一 |
Runtime self-modification · tool-cordis | cordis_define, cordis_inspect_list, cordis_inspect_query, cordis_inspect_self, cordis_run, cordis_stop, cordis_undefine | 进程内定义、检查、启动和卸载动态 package；shipped tree 默认不装 |
| Persistent shell | bash | owner-isolated PTY 状态；与 one-shot bash 同名但不是同一 definition |
| Standalone editor | str_replace_editor | view/create/literal replace/insert over ctx.fs |
| Filesystem | read, read_image, write, edit | 观察事件、写/edit intent、durable attachment；image 注册依赖 attachment service |
| Filesystem discovery | glob, grep | 固定 argv 调 packaged ripgrep；可把完整 capped 结果 spill |
| Terminal | terminal_open, terminal_read, terminal_send, terminal_signal, terminal_list, terminal_close | 持久 PTY 生命周期；send 可注册 background job |
| Goal | create_goal, get_goal, update_goal | Session-owned durable goal/revision/round 状态与权限检查 |
| Schedule | schedule_create, schedule_delete, schedule_list | 仅 opt-in live root scope；写 schedule/change |
| Language server | lsp | 稳定 schema，provider 不可用时结构化拒绝 |
| Fixed iteration | ralph | 每轮创建 fresh structured child，前台执行固定 workflow |
| Skill | skill | 读取可信 instruction catalog/body；可注入 replacement catalog |
| Session query | session_search, session_event_search, session_trace, session_event_trace, session_event_read | 显式授权的词法检索、lineage 与 exact event read；默认标准 preset 不装 |
| Delegation | subagent（shipped alias subagent_fork） | provider/name/background mode 都由配置决定；child 有独立 Session |
| Child control | send_message, interrupt_agent, list_agents | continuable child 的 follow-up/interrupt/list |
| Child return channel | report | 只注册到 continuable in-process child，向直接 parent 写 user-role message |
| Background jobs | job_list, job_output, job_kill | 统一控制 shell、PTY send 与 one-shot subagent jobs |
| Todo | todo_write | 写 todo/write；是否允许多个 in-progress 是必选部署配置 |
| Programmable orchestration | workflow | 受限 worker script 编排 Agent；script 本身无 fs/network/timer |
| Web | web_search, web_fetch | provider-neutral seam；search/fetch 是否存在由 composition 决定 |
上游 package map 同时记录每个包的 Requires、Writes/Affects、shipped aliases 与 deployment note；其后保留每个 tool 的精确 description、参数 JSON Schema 和生产源码链接。本表是完整索引，不复制 1,800 余行 schema。TOOLCAT-PACKAGE-MAP
4. 标准 Web root 的实际 25 个工具
| 来源 | 名称 | 数量 |
|---|---|---|
| 平台 shell | Linux/macOS bash；Windows pwsh | 1 |
| Filesystem + search | read, read_image, write, edit, glob, grep | 6 |
| Jobs + skill | job_list, job_output, job_kill, skill | 4 |
| Goal + plan | create_goal, get_goal, update_goal, exit_plan_mode | 4 |
| Delegation | subagent, subagent_fork, send_message, interrupt_agent, list_agents | 5 |
| Workflow | workflow, ralph | 2 |
| Interaction/state/web | ask_user_question, todo_write, web_search | 3 |
| 总计 | 25 |
标准 preset 明确平台 shell 二选一、装载 fs/search/jobs/skill/goal/plan、两个 delegation 名称、三项 control、workflow/Ralph/ask/todo，并把 fetch:false；host 基线装载 local attachment store，所以 read_image 注册。TOOLCAT-STANDARD-BASETOOLCAT-STANDARD-ORCHESTRATIONTOOLCAT-ATTACHMENT
exit_plan_mode 即使 planning inactive 仍留在 schema，以避免模式切换改变 tool catalog、破坏 request-cache prefix；执行时再拒绝不合法状态。Codex/Claude Code delegation rows 在该 preset 中明确 disabled，web_fetch 也不出现。
5. Minimal 预设不是 standard 的“少一点”，而是另一种完整产品假设
Minimal 使用 complete persona，关闭 runtime context snapshot，不装 compaction，只暴露 persistent bash 与 str_replace_editor。它为 PTY 与 bare local filesystem 各自建立 isolated realm。TOOLCAT-MINIMAL
这解释了为什么“Harness 支持 51 个工具”和“这个 Agent 只有 2 个工具”可以同时为真。能力不是二进制产品清单，而是 profile/preset 给 Agent 的可组合语言。
6. 相同名称不等于相同语义：两个 bash
| 实现 | 进程模型 | 状态 | 典型 composition |
|---|---|---|---|
dsh-tool-bash | 每次调用新进程，经 ctx.shell | cwd/env 由请求与 executor 决定；无 PTY 连续状态 | standard/base |
dsh-tool-bash-persistent | 复用 owner-isolated PTY，经 ctx.terminals | shell 状态跨 calls 保留 | minimal |
7. Filesystem 家族：发现、读取、变更与观察被拆开
| 工具 | 动作 | 关键策略 | 展示意图 |
|---|---|---|---|
glob/grep | packaged rg 的 fixed-argv 发现 | timeout/cap/spill；不经 shell，也不经 ctx.fs | search result groups |
read | 有界 UTF-8 line window | 记录 present/absent version observation | read card + locations |
read_image | 有界 bytes → content-addressed attachment | 先验 extension/media/model route gates | durable image block + metadata |
write/edit | create/overwrite 与 literal replacement | 默认 observation policy 要求 unchanged version；sandbox 可升级审批 | diff intent + durable meta |
str_replace_editor | 把 view/create/replace/insert 合成一 tool | 用于 minimal 的紧缩接口；依旧走 fs seam | generic/diff |
值得注意：glob/grep 语义上是只读，却没有 opt in 并行；读写语义与 scheduler 分类是两个独立维度。
8. Shell、Terminal 与 Job：执行能力与生命周期控制正交
bash/pwsh --run_in_background--> Job Registry <--terminal_send / one-shot subagent
|
job_list / job_output / job_kill
terminal_open/read/send/signal/list/close → persistent PTY registryJob 工具不是 shell 专属 API，而是跨 producer 的统一后台任务控制面。Terminal 六件套则显式暴露会话建立、I/O、signal 与 close，换取更强状态性；standard 没装它，minimal 甚至不暴露 terminal controls，只把 persistent PTY 包装成同名 bash。
9. Plan、Goal、Todo 与 Ask：四种人机/协作状态，不是一张任务表
| 原语 | 生命周期 | 谁拥有真相 | 工具动作 |
|---|---|---|---|
| Plan mode | Agent mode，跨 steps | plan/mode 事件 + reviewer | exit_plan_mode 提交完整计划 |
| Goal | Session 多 round、可继续 | Goal service/projection | create/get/update |
| Todo | Session 内最新 checklist projection | todo/write | 整表 replacement write |
| Question | 单次 tool call 的 suspension | UserQuestion provider | 等待并返回回答 |
第 15 章分析它们的 durable semantics；本章只强调 tool surface 不应按名称相似度合并。
10. Delegation、Workflow 与 Ralph：三种不同的编排自由度
| 工具 | 模型决定什么 | Runtime 固定什么 | 结果通道 |
|---|---|---|---|
subagent* | 一次 child prompt、label、foreground/background | provider、depth、background mode | tool result、job settlement 或 continuable child |
workflow | 受限 JS 中的 fan-out/control flow | worker isolation、agent bridge、并发/总量 cap | 前台聚合 result |
ralph | objective 与可选 rounds | 每轮 fresh child 的固定迭代脚本 | 前台最终 result |
send_message/interrupt_agent/list_agents 管理 continuable child；report 反向存在于 child scope，而不是 root catalog。第 24–26 章继续追踪 Session、activation 与 inbox。
11. Web、LSP、Session Query 与 Skill：schema 稳定，provider 能力可以缺席
这些工具都把模型可见 contract 与后端 provider 分开：web_search/web_fetch 走 ctx.web，lsp 走 ctx.lsp，Session Query 走可关闭 FTS 的 ctx.sessionQuery，Skill 走 scope-layered catalog。Schema 可保持 prefix 稳定，但执行可能返回 unavailable/disabled；“模型看见工具”从来不等于“provider 必然成功”。
这种稳定 surface 对 KV cache 和替换 provider 很友好；代价是 capability discovery 不能只看 schema。高质量 host 还应把 provider readiness、policy mode 与故障原因呈现在 UI/telemetry，而不是让模型用失败调用探测。
12. Cordis 工具集是刻意 opt-in 的“修改自身运行时”能力
七个 cordis_* 工具能定义、检查、运行、停止和取消定义动态 package。运行中的 package 可继续注册新的模型工具，直到 stop/undefine/restart；因此 51 名上界在启用它后天然不是闭包。
生成 package map 明确记载这套工具不在任何 shipped tree 中；缺少 dynamicCordisRunner 时根本不会激活。它不是“隐藏默认超能力”，而是 deployment 必须主动承担的真实 runtime-code trust boundary。TOOLCAT-PACKAGE-MAP
13. 并行分类：只有 8 个唯一名称/定义明确 opt in，其余全部 fail closed 为 exclusive
| 明确 parallel-safe | 理由 | 在标准 root 中？ |
|---|---|---|
read, read_image | 只读；观察 race 由后续 mutation 的 in-lock version check 关闭；attachment content-addressed | 是 |
web_search, web_fetch | provider read，不改 parent Agent state | 仅 search |
session_trace, session_event_trace, session_event_read | 授权后的 exact/lineage reads | 否，query package opt-in |
subagent definition（含配置别名） | child 不改 parent Session；唯一 parent write 是同步可交换 task insertion | subagent 与 subagent_fork |
仓库生产源码中排除 helper/generated/test 后只有上述 8 处 isConcurrencySafe: () => true。Registry 只有在 classifier 精确返回 true 时给 parallel；缺失、非法参数或 throw 都是 exclusive。glob/grep、goal reads、job list 等看似“读”的工具仍是 barrier。TOOLCAT-PARALLEL-OPTINSTOOL-SCHEMA-PROJECTION
14. “危险性”不是工具名上的一个布尔值
| 风险轴 | 代表工具 | 真正控制点 |
|---|---|---|
| 文件 mutation | write/edit/editor | fs intent、observed version、sandbox escalation、approval |
| 任意进程 | bash/pwsh/terminal | sandbox provider、shell policy、timeout、signal/job kill |
| 外部数据流 | web/MCP/LSP | provider URL/credential/SSRF boundary、output retention |
| 跨 Agent | subagent/control/workflow | parent authority、depth/caps、workspace effects、continuation ownership |
| 持久状态 | goal/todo/schedule | session/root authority、event validation、durability barrier |
| 运行时代码 | run_code/cordis_* | VM/worker surface、nested pipeline、opt-in composition |
本表是 threat-model 分类，不是源码里的 risk score。Harness 的做法是把风险分散到 provider confinement、pre approval、monotonic guard、tool-specific event gate 与 execution owner；第 19、20、31 章分别验证这些边界。
15. 输入、输出与 UI 意图：目录只承诺模型 schema，执行 contract 还在 ToolDefinition
生成器为每项输出 name、description、parameters JSON Schema 和 source；output schema、canonical value、timeout/concurrency metadata、presenters 与 finalizer 不在生成目录页面内。必须把第 16 章 ToolDefinition 分析和本章 package map 合看。TOOLCAT-GENERATORTOOL-DEFINITION
UI 也不按 tool name 硬编码全部卡片。工具返回 provider-neutral generic/terminal/diff/search/read/web render intent；Host 用当前 scope definition 配对 call/result，配对缺失或 presenter throw 时保留原 event 并退回 generic card。TOOL-PRESENTATION-INTENTSTOOL-HOST-PRESENTER
16. 可用性矩阵：注册、可见、可调度、获批、后端就绪是五道门
package mounted?
→ required service satisfied and tool registered?
→ current Agent scope can see it?
→ presentation mode exposes native name or Code SDK?
→ pre-policy + approval + guards allow this call?
→ provider/runtime is ready and body succeeds?任何一层为否，都可能表现为“没有 schema”“UNKNOWN_TOOL”“需要审批”“provider unavailable”或普通 error result。把它们都叫“权限问题”会让诊断走错层。
17. 已确认的文档/组合漂移与审计陷阱
| 陷阱 | 正确读法 |
|---|---|
| 把生成 catalog 当 standard 默认 | 它是逐包 isolated boot 的上界，standard 要从 preset 重算 |
| 按“只读”猜 parallel | 只有显式 classifier true 才 parallel；其余 exclusive |
| 按 tool name 推断实现 | bash 有两套 shipped definition；subagent name 也可配置 |
| schema 存在即 provider ready | LSP/Web/Query 等可用稳定 schema + execution-time unavailable |
| 用当前 presenter 还原历史 UI | Host 确实 live-read 当前 definition；旧 call 跨页时会 generic fallback |
| 认为 Code Mode 删除能力 | 它改变 wire entrance；SDK 中仍保留 end capabilities，subcall 重进 pipeline |
18. 设计评价与验证状态
| 选择 | 收益 | 代价 |
|---|---|---|
| 工具包与 provider seam 分离 | 稳定 schema 可替换后端 | schema 无法表达 readiness |
| 生成 catalog 通过真实 boot 收集 | 能捕获动态 schema、配置名称与注入条件 | 仍只代表 generator 选择的配置分支 |
| Preset 决定能力语言 | 同一 runtime 支持 2-tool minimal 到 full agent | “默认工具数”必须附带 surface/platform/service 条件 |
| 并发显式 opt in | 未知第三方工具默认安全串行 | 纯读工具漏声明会损失吞吐 |
| Provider-neutral presentation | Web/CLI 可共享语义且 replay 有 fallback | 热更 presenter 可能改变旧事件的当前展示 |
本章逐项核对了生成 tool catalog、generator completeness/boot 逻辑、全部 24 package map rows、standard/minimal shipped presets、attachment condition、全仓生产 isConcurrencySafe 声明与 ToolRuntime classifier。计数来自固定基线文本的可复现 heading 统计。上游依赖未安装，因此不声称本机执行了 generator 或 upstream tests；站点自身构建与一致性检查会在提交前运行。
我的学习体会
内容仅自动保存到当前浏览器，不上传、不进入仓库。你可以导出 Markdown 自行归档。