1. 为什么 todowrite 的提示词值得单独写一篇如果你正在用 OpenCode 搭 Agent大概率遇到过这种场面你让它「加个暗色模式」它二话不说直接改 CSS改完发现状态没接上、组件没联动、测试也没跑。问题不在模型能力而在你给 todowrite 这个工具的提示词没写清楚——它不知道该在什么时候把任务拆成待办清单也不知道拆完之后每一步要覆盖哪些维度。todowrite 是 OpenCode Agent 里负责「把自然语言需求翻译成结构化任务清单」的工具。它本质上是一个状态机写入器Agent 判断当前任务足够复杂、步骤足够多、有明确的交付边界时就调用 todowrite 把计划落成一条条可追踪的待办项。写得好Agent 会像资深工程师一样先规划再动手写得糊它要么过度设计把「改个按钮颜色」拆成八步要么该拆不拆一口气写完一堆耦合代码。这篇面向需要为 Agent 定义任务清单写入能力的开发者给你可直接复制的提示词模板、字段说明以及在 OpenCode 里验证 todowrite 是否按预期生成待办项的完整流程。TaoToken 在这里的角色是提供统一的 Key 和 API 通道让你在调试 Agent 工具调用时不用来回切换多个供应商配置官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 。先说清楚 todowrite 适合谁如果你只是让 Agent 做单轮问答、查个文档、改一行配置那不需要它强行调用只会浪费 token 和时间。但只要你面对的是「跨 UI、状态、样式、集成、测试」这类多领域任务todowrite 就是让 Agent 保持工程纪律的关键工具。下面从提示词结构开始拆。2. todowrite 提示词模板与字段说明OpenCode Agent 任务清单写入写 todowrite 的提示词核心是回答三个问题什么时候触发、拆成什么样、每个字段填什么。我把它整理成一个可复用的模板你可以直接贴进 OpenCode 的 tool description 或 system prompt 里。2.1 触发条件三个以上独立步骤才值得写清单提示词里必须明确「不触发」和「触发」的边界否则 Agent 会滥用。参考写法当且仅当满足以下任一条件时调用 todowrite 1. 任务需要跨越三个以上独立技术领域如 UI、状态管理、样式、集成、测试 2. 用户显式要求「运行测试」「构建」「验证」等收尾动作 3. 任务存在隐式依赖前一步的输出是后一步的输入。 以下情况禁止调用 todowrite - 单一且直接的任务如改一个常量、修一个拼写 - 少于三步的简单任务 - 纯对话、检索、问答类任务 - 琐碎且无组织收益的任务。这段的作用是给 Agent 一个「认知负荷」判断标准。少于三步的简单任务强行写清单就是形式主义调用工具本身消耗 token 和时间得不偿失。2.2 字段结构每条待办必须可验证todowrite 的每条待办项建议包含四个字段缺一不可字段含义示例id唯一标识便于后续更新状态todo-1content祈使句描述的具体动作创建主题切换按钮组件status当前状态初始为 pendingpendingpriority优先级high/medium/lowhigh提示词里要强调content 必须是祈使句且包含可验证的完成标准。比如「编写暗色模式样式」不如「在 styles/theme.css 中定义 dark 主题变量并导出」来得可验证。2.3 拆解维度UI、State、Style、Integration、Test这是从实际案例里提炼出来的五维拆解法。提示词里可以这样写拆解任务时按以下维度检查是否覆盖完整 - UI 层用户可见的交互元素 - State 层全局状态管理与数据流 - Style 层样式变量与主题定义 - Integration 层现有组件接入新状态 - Test 层测试、构建、错误处理。 若用户只提到部分维度主动推断缺失的收尾步骤 例如用户说「跑测试」应补充「处理测试中出现的失败或错误」。最后一句是关键。用户说「跑测试和构建」但没说报错了怎么办。作为开发者跑测试报错不管等于没做。提示词要引导 Agent 主动补全这个闭环。2.4 完整可复制模板把上面几段拼起来就是一个可直接用的 todowrite 提示词模板你是 OpenCode Agent 的任务规划器。当任务满足触发条件时 调用 todowrite 生成结构化待办清单。 触发条件 - 跨越三个以上独立技术领域 - 用户显式要求测试/构建/验证 - 存在隐式依赖链。 禁止触发 - 单一直接任务、少于三步、纯对话检索、无组织收益的琐碎任务。 拆解维度UI、State、Style、Integration、Test。 每条待办包含 id、content、status、priority。 content 用祈使句包含可验证的完成标准。 主动推断用户未明说的收尾步骤补全闭环。这个模板不依赖具体模型OpenCode 里配置好工具描述后即可生效。接下来讲怎么在 OpenCode 里把它接上并验证。3. 在 OpenCode 中接入 todowrite 的可复制配置提示词写好了得让 OpenCode 真正加载它。OpenCode 的工具配置通常放在项目根目录的配置文件里不同版本路径略有差异常见的是opencode.json或.opencode/config.json。下面给一份可复制的 JSON 片段路径按你实际项目调整。3.1 工具定义配置{ tools: { todowrite: { enabled: true, description: 当任务跨越三个以上独立技术领域、或用户显式要求测试构建、或存在隐式依赖链时调用此工具生成结构化待办清单。禁止用于单一直接任务、少于三步的简单任务、纯对话检索类任务。, parameters: { todos: { type: array, items: { type: object, properties: { id: { type: string }, content: { type: string }, status: { type: string, enum: [pending, in_progress, completed] }, priority: { type: string, enum: [high, medium, low] } }, required: [id, content, status, priority] } } } } } }3.2 模型通道配置OpenCode 需要连到一个模型服务。如果你用 TaoToken 作为统一通道配置里填 Base URL 和 Key 即可。Base URL 用 https://taotoken.net/api Key 在控制台生成。三件套要写全Base URL、Key、Model ID。{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 } } }Model ID 按你实际使用的模型填不要照抄。Key 建议放环境变量别硬编码进仓库export TAOTOKEN_API_KEYsk-你的Key配置里改成apiKey: ${TAOTOKEN_API_KEY}。3.3 提示词挂载位置todowrite 的触发规则和拆解维度建议放在 system prompt 或工具 description 里。OpenCode 支持在配置中指定 system prompt 文件{ agent: { systemPromptFile: ./prompts/todowrite-planner.md } }把第 2 节的模板写进prompts/todowrite-planner.mdOpenCode 启动时会自动加载。这样提示词和配置分离改提示词不用动 JSON。配置完成后用opencode --debug启动观察日志里 todowrite 是否被注册。如果日志里出现tool registered: todowrite说明接入成功。接下来验证调用行为。4. 验证 todowrite 是否按预期生成待办项配置好了不代表行为正确得用真实请求验证。我试过用一个「添加暗色模式」的需求来测这个需求天然跨越 UI、State、Style、Integration、Test 五个维度是检验 todowrite 触发逻辑的好案例。4.1 发起验证请求在 OpenCode 交互界面输入给当前项目添加暗色模式运行测试和构建。预期行为Agent 不直接改 CSS而是先调用 todowrite 生成待办清单。如果它直接开始写样式说明触发条件没生效回去检查提示词里的触发规则是否被正确加载。4.2 检查生成的待办结构正常情况下todowrite 应该生成类似这样的清单{ todos: [ { id: todo-1, content: 创建主题切换按钮组件并接入设置面板, status: pending, priority: high }, { id: todo-2, content: 建立全局主题状态管理支持读取和切换当前主题, status: pending, priority: high }, { id: todo-3, content: 在样式文件中定义 dark 主题变量并导出, status: pending, priority: high }, { id: todo-4, content: 将现有组件接入主题状态系统完成联动, status: pending, priority: medium }, { id: todo-5, content: 运行测试和构建定位并处理出现的失败或错误, status: pending, priority: high } ] }重点看第 5 条用户只说了「运行测试和构建」但清单里补上了「定位并处理出现的失败或错误」。这说明提示词里的隐式意图推断生效了。如果第 5 条只写「运行测试」说明推断规则没起作用需要检查提示词里那段「主动推断用户未明说的收尾步骤」。4.3 观察状态流转todowrite 生成清单后Agent 执行每一步时应该更新对应待办的 status。从 pending 到 in_progress 再到 completed。你可以在 OpenCode 的调试面板里观察这个流转。如果所有待办一直是 pending说明状态更新逻辑没接上检查工具定义里 status 字段的 enum 是否完整。4.4 验证不触发场景反向验证同样重要。输入一个简单任务把首页标题的字体大小改成 18px。预期行为Agent 直接改不调用 todowrite。如果它生成了清单说明禁止触发规则没生效Agent 在过度设计。这时候回去检查提示词里「禁止触发」那段的措辞是否足够强硬。两个方向都验证通过说明 todowrite 的提示词和配置都到位了。5. 常见报错排查401、local proxy failed、reading choices、OAuth接入和验证过程中报错基本集中在通道配置和工具注册两块。下面按真实报错逐个排查。5.1 401 Unauthorized最常见。日志里出现401或invalid api key先检查三件事Key 是否填对、Base URL 是否是 https://taotoken.net/api 、环境变量是否被正确读取。如果你用了${TAOTOKEN_API_KEY}但没 exportOpenCode 读到的是空字符串自然 401。用echo $TAOTOKEN_API_KEY确认变量有值。5.2 local proxy failed日志里出现local proxy failed或connection refused通常是 Base URL 写错或网络不通。确认 URL 没有多余斜杠https://taotoken.net/api后面不要加/v1之类的路径除非文档明确要求。另外检查本地是否有其他进程占用了 OpenCode 的代理端口。5.3 reading choices 报错error reading choices或cannot read property choices of undefined说明返回体结构不符合预期。这通常是 Model ID 填错或者请求发到了不兼容的端点。确认 Model ID 和你实际使用的模型一致不要照抄示例里的claude-sonnet-4-20250514。如果换了模型Model ID 要同步改。5.4 OAuth 相关报错如果你用的是需要 OAuth 的模型服务日志里可能出现OAuth token expired或refresh failed。OpenCode 的 OAuth 流程和 API Key 流程是两套。用 TaoToken 的 Key 通道时不需要走 OAuth确认配置里没有残留的 OAuth 字段。如果之前配过 OAuth清掉相关配置再试。5.5 todowrite 不触发配置都对但 Agent 就是不调用 todowrite。检查三点工具 description 是否被正确加载看启动日志、system prompt 文件路径是否正确、触发条件里的「三个以上独立技术领域」是否被模型理解。可以把触发条件写得更具体比如直接列出「UI、State、Style、Integration、Test」五个维度名。5.6 待办项生成但状态不更新清单生成了但执行过程中 status 一直是 pending。检查工具定义里是否包含 status 字段的更新接口。todowrite 通常配套一个 todoupdate 工具如果只注册了 todowrite 没注册 todoupdate状态就无法流转。在配置里补上 todoupdate 的定义。排查完这些基本能覆盖 90% 的接入问题。剩下的多半是提示词措辞问题回去调触发规则即可。6. 把 todowrite 用顺手的几个实操建议提示词模板和配置都给了最后说几个实际用下来的经验。todowrite 的价值不在于「生成了清单」而在于「清单的粒度刚好」。太粗等于没拆太细Agent 光维护清单就耗掉大量 token。一个判断标准每条待办应该是一个「可独立验证的交付单元」。比如「创建主题切换按钮组件」可以独立验证——按钮渲染出来了、点击有反应。「编写暗色模式样式」就不太好验证改成「在 styles/theme.css 中定义 dark 主题变量并导出」就清晰了。另一个经验是优先级别滥用。如果所有待办都是 high等于没有优先级。UI 和 State 通常是 high因为它们是其他步骤的依赖Style 和 Integration 可以 mediumTest 看情况如果用户显式要求就是 high。还有一点todowrite 生成的清单不是一成不变的。执行过程中如果发现新依赖Agent 应该能追加或调整待办。提示词里可以加一句「执行中发现新的必要步骤时更新清单而非忽略」。这样 Agent 不会为了「保持原计划」而跳过必要工作。如果你在 OpenCode 里调试 todowrite 时想快速验证模型返回可以用 TaoToken 的模型对话入口直接发请求看返回结构省去在 OpenCode 里反复重启的时间。接入文档里有完整的请求示例。长期跑编码 Agent 的话Coding Plan 的通道更稳定适合把 todowrite 这类工具调用纳入日常流程。