imccyu
dadb92302f
- TodoPanel mounts through a 'conversation.input.dock' list entry (todoDockEntry, QueueDock posture, order -1 above the queue rows) instead of a ConversationRoot hardcode; the inner component is unchanged and takes useSession from the dock entry's standard kit. - The verify-todo-display.mjs chromium probe is replaced by an assembled keyless snapshot (apps/web/tests/todo-display.snapshot.ts, the code-mode-fixture idiom) pinning the TodoRow summary/state, the dock panel content, and the collapse round-trip over built bundles. - Fake snapshots across specs gain the todos field; bilingual note/READMEs updated for the dock mount and the snapshot.
64 lines
4.0 KiB
Markdown
64 lines
4.0 KiB
Markdown
# @deepseek-ai/dsh-tool-todo
|
||
|
||
[English](README.md) | 中文
|
||
|
||
面向模型的 `todo_write` 工具：agent（智能体）的完整任务列表，每次调用都会整体替换。
|
||
|
||
## 功能
|
||
|
||
注册一个工具 `todo_write(todos: [{ content, status }])` 到 `ctx.tools`。模型每次调用都会发送完整列表，不存在部分更新或单项编辑。每次调用都会向调用 agent 的会话日志追加 `todo/write` 事件（完整列表快照），具体调用 `agent.session.append('todo/write', { todos })`；当前列表是最新的该类事件（回放时后写者胜）。
|
||
|
||
`status` 是 `pending`、`in_progress` 或 `completed` 之一。
|
||
|
||
## 单一所有者
|
||
|
||
该列表属于调用工具的唯一 agent 会话。不存在 subagent／共享／swarm scope：非 agent 调用方（没有 `exec.agent`）无处写入列表，因此会被拒绝。这是有意设置的 scope 限制，详见 Agent Note。
|
||
|
||
## 验证
|
||
|
||
除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`、同时存在多个 `in_progress` 任务的情况（连贯计划最多只有一个活跃任务），以及 `content`/`status` 之外的任何条目键——扩展条目形状（id、嵌套）会响亮失败而不是被静默压平，保证落日志的快照与模型自认为写入的内容一致。顺序与保持列表最新的纪律由模型根据工具描述负责。
|
||
|
||
## 渲染
|
||
|
||
规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久列表：[TUI 应用](../../examples/tui-demo)将其显示为持久计划，[web 客户端](../../client/ui-conversation)则基于 `ConversationSnapshot.todos` 渲染计划横条与专属工具行（[Agent Note](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md)）。
|
||
|
||
## 导出形状
|
||
|
||
函数／命名空间插件：导出 `name`/`inject`/`apply`，不提供默认导出。意外的 `export default` 会通过 Loader 的 `unwrapExports` 折叠模块并丢弃 `inject`（参见 [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）。
|
||
|
||
## 模型体验
|
||
|
||
### 工具 schema
|
||
|
||
#### 模型所见内容
|
||
|
||
模型会看到生成的 [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo)。
|
||
|
||
#### Token 影响
|
||
|
||
工具可见的每个请求都有固定 schema 成本。
|
||
|
||
#### KV Cache 影响
|
||
|
||
只要定义和可见性不变，前缀就保持稳定。插件生命周期或 scope 限制可能会使此 schema 之后的复用失效。
|
||
|
||
### 工具调用历史与结果
|
||
|
||
#### 模型所见内容
|
||
|
||
每个 assistant 工具调用都会在参数中保留整个替换列表。成功时精确返回 `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.`。稳定失败文本为 ``Error: invalid todo: `content` must be a non-empty string``、`Error: invalid todos: duplicate content "<content>"`、`Error: invalid todos: at most one task may be in_progress, got <count>` 和 `Error: todo_write requires an owning agent session`。完整 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
|
||
|
||
#### Token 影响
|
||
|
||
Token 增长与模型每次提交的完整列表成比例，且这些调用参数会保留到压缩（compaction）。结果本身很小，且形状固定。
|
||
|
||
#### KV Cache 影响
|
||
|
||
仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
|
||
|
||
## 已知限制与延后工作
|
||
|
||
- **仅单一所有者 scope**：列表属于唯一调用 agent 会话；subagent／共享／swarm scope 是有意裁减（参见「单一所有者」一节），非 agent 调用方会被拒绝。
|
||
- **项目形状有意保持最小**：`content` 加三态 `status`；整表替换不需要稳定 id、优先级或 active-form 字段。
|
||
- **整表替换是唯一操作**：没有部分更新，也没有回读工具；模型每次调用都必须重新发送完整列表。
|