DeepSeek Harness 的 TUI 工具裁剪与按需启用：`todo_write` 如何从默认工具变为一行配置的 opt-in

DeepSeek Harness 的 TUI 工具裁剪与按需启用todo_write如何从默认工具变为一行配置的 opt-in【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harnessDeepSeek Harness 是一个以 Everything is a Plugin 为理念的 Agent 框架其 TUI终端用户界面前端通过 Cordis 组合composition装配 agent。本文将基于仓库内一份已归档的技术决策记录.agents/notes/archived/simplification/2026-07-21-tui-todo-write-opt-in.md完整还原todo_write从 TUI 默认工具集中移除、改为一行配置开启这一裁剪决策的来龙去脉。读完你将掌握TUI 默认工具清单为何要精简、todo_write的按需启用方法含cordis.yml与~/.dsh个人 overlay 两种入口、以及默认关闭 / 按需开启两条路径如何同时被测试与快照机制保障。问题背景todo_write不是核心编码工具却占用了每次 turn 的预算在裁剪之前随 TUI 一同发布的cordis.yml组合默认加载了deepseek-ai/dsh-tool-todo从而把todo_write工具暴露给模型。决策记录给出的反对理由很明确todo_write是任务跟踪便利工具task-tracking convenience而非像bash或read/write/edit这类文件系统工具一样的核心编码能力绝大多数 TUI 会话根本不会调用它但一旦发布它就会在每个 turn 的工具列表wire tool list和系统提示词system prompt中持续占据预算造成 token 与上下文的浪费。同时TUI 的计划plan渲染是事件驱动的并不依赖工具是否存在packages/ui/tui/src/index.ts监听todo/write会话事件TodoComponent.render在列表为空时返回空内容returns nothing。因此前端大门front door对工具缺席或在场都完全容忍与插件之间没有运行时耦合。这为从默认组合中移除该工具提供了结构前提裁剪不会破坏 TUI 的计划渲染能力。决策默认移除一行配置开启决策的核心结论如下TUI agent 的cordis.yml不再加载tool-todotodo_write变为 opt-in按需启用code-mode.cordis.ymloverlay 继承基础组合因此其生成的 SDK 也随之移除todo_write启用只需一个入口——在cordis.yml或~/.dsh个人 overlay中加入deepseek-ai/dsh-tool-todo启用后行为不变模型写入整份todo/write快照TUI 正常渲染计划TodoItem类型与todo/write事件仍保留在deepseek-ai/dsh-session中TUI 的计划渲染仍保持接线因此默认关闭与按需开启两条路径都是一等公民兄弟示例 acp-agent、headless-agent、jsonrpc-agent 仍然发布该工具。这一决策体现了 DeepSeek Harness 的插件哲学能力是否随默认发行取决于它是否是核心路径非核心能力通过组合配置按需加入而不是硬编码进默认栈。todo_write工具本身整体替换、单一属主、部署策略化要理解这次裁剪需要先理解被裁剪的工具本身。todo_write由packages/todo/tool-todo包提供其设计建立在四条承诺之上见 package README 的实现细节整体替换、日志支撑的状态Whole-list replace, log-backed state模型每次更新都必须重发整份列表todo/write快照落在事件溯源的会话日志session log上持久化、重放、恢复重建都来自日志而非独立服务单一属主Single owner列表属于调用它的那个 agent 会话子代理等其他 agent 各自持有自己的列表无法跨 agent 共享来自 agent 会话之外的调用会被拒绝部署策略而非编码规则Deployment policy, not a coded ruleallowParallelInProgress是必填的组合选择因为工具无法观测运行时并发持久化日志的不变式刻意不约束进行中数量保证一份日志在不同策略下都能重放校验保证日志快照诚实Validation keeps the logged snapshot honestschema 层拒绝未知字段execute层拒绝空内容或重复内容使持久化快照与模型自以为写入的内容保持一致。数据模型TodoItem每个条目刻意保持最小化来源packages/todo/tool-todo/src/types.ts事件契约见 Todo 子系统文档interface TodoItem { /** 该任务是什么——UI 中显示的一行简短命令式文本。 */ content: string /** 生命周期状态。in_progress 标记当前正在进行的任务并行工作时可以标记多个。 */ status: pending | in_progress | completed }没有 id、优先级或 activeForm 字段——因为列表在每次写入时整体替换last-write-wins条目无需稳定身份。包通过声明合并declaration merge把todo/write: { todos: TodoItem[] }并入SessionEventMap该事件只写日志log-only并携带完整替换列表。配置项allowParallelInProgress启用todo_write时配置项allowParallelInProgress必填、无默认值来源packages/todo/tool-todo/README.md最小配置- name: deepseek-ai/dsh-tool-todo config: allowParallelInProgress: true字段默认值含义allowParallelInProgress必填是否允许多个 todo 同时处于in_progress同时选择模型描述中活动状态子句true用于可能并发运行工作的 agent子代理、后台命令、workflow 扇出false用于单活动任务纪律组合中省略该字段会在加载时失败非布尔值会被拒绝。完整的字段说明以生成的 配置目录 为准。如何按需启用cordis.yml与~/.dsh个人 overlay按照决策记录启用todo_write是一个入口one entry编辑 TUI agent 的组合文件cordis.yml在插件列表中追加- name: deepseek-ai/dsh-tool-todo config: allowParallelInProgress: false或者使用~/.dsh个人 overlay不修改仓库/发行组合而是通过个人配置层叠加同一插件条目实现本地启用、随发行更新自动继承。启用后模型即可通过todo_write工具写入整份todo/write会话事件TUI 的计划渲染无需任何改动即可展示。若需恢复默认发布状态只需移除这一条cordis.yml条目并把快照与测试工具中的 opt-in 标志改回即可详见下文测试。测试策略两条路径各有专属覆盖决策记录强调裁剪的目标是同时支持启用与禁用两种情形因此测试体系为两条路径分别保留了覆盖相关测试位于apps/cli/tests/profiles/headless/tests/todo-write.e2e.ts与packages/todo/tool-todo/tests/等启用路径的证明快照测试只在场景设置enableTodo时挂载ToolTodo只有todo-plan场景这样做其session.jsonl/terminal.expected.txt固化了渲染出的计划默认路径的验证其余每个场景都以无 todo的默认组合运行验证裁剪后的发行栈测试工具层面的 opt-intests/harness.ts把ToolTodo做成todoopt-in只有tests/todo-write.e2e.ts设置它——这样带 key 的 todo e2e 仍驱动真实工具而其他套件匹配发行栈无 key 冒烟测试tests/tui-keyless-smoke.e2e.ts直接启动真实cordis.yml且不对 todo 做任何断言证明默认启动不受影响。备选方案与拒绝理由决策记录列出了两个被否决的备选方案值得作为设计权衡的参考在 TUI 默认发行中保留todo_write——被拒绝它是 opt-in 便利工具而非核心工具发布它等于让每个 turn 的工具列表与提示词预算花在多数会话用不到的功能上仍发布该工具的示例保留了插件真实组合的覆盖。连 TUI 计划渲染与 todo 测试一起删除——被拒绝需求是同时支持启用与禁用两种情形而事件驱动的TodoComponent已在零插件耦合下渲染计划删除等于丢弃一个可用能力而毫无收益启用路径保留了专属覆盖。影响与结论默认 TUI 的工具列表与系统提示词减少一个工具需要任务跟踪的会话只需增加一个插件条目重新生成的examples/tui-agent/composition.md及其叶子条目表格不再列出tool-todoscripts/gen-doc-graphs.ts中的精选摘要同步移除deepseek-ai/dsh-tool-todo包本身不变仍由 acp/headless/jsonrpc 示例发布其覆盖要求在那些示例中继续满足若要恢复默认发行只需重新加入那一条cordis.yml条目并把快照与测试工具中的 opt-in 标志改回。从更宏观的视角看这次裁剪是 DeepSeek Harness 插件化架构的一个典型治理案例默认栈只承载核心能力非核心能力以一行配置的 opt-in 形式存在事件驱动的前端与工具发布解耦使得默认发行保持精简的同时按需能力依旧是一等公民。如果你正在定制自己的 agent 组合可以以此模式为参考把低频便利工具移出默认栈、用组合配置按需挂载并确保前端渲染与工具存在性解耦、为两条路径分别保留测试覆盖。【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址: https://gitcode.com/gh_mirrors/de/deepseek-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考