社区导读

简体中文

English

简体中文

English

外观

源文件索引：packages/todo ​

本页由 study-tools/generate-source-index.mjs 根据官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec 生成，共 9 个代码或界面源文件。每个标题对应一个真实路径；用途和拆分原因是面向初学者的结构化解释，自动索引不等于人工精读。

图例 ​

本页所有条目共用以下说明：

  • 自动索引只提供定位线索，复杂行为需要回到源码和测试确认。
  • 条目中的行数、声明、结构线索和静态 import 数字是文件级定位证据，用来约束“为什么这样设计”的解释范围；它们用于定位，不替代人工源码阅读。
  • 源码链接固定到官方提交；如果当前条目与运行版本不同，应先重新生成索引再下结论。

packages/todo/tool-todo/src/client.ts ​

packages/todo/tool-todo/src/index.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把工具相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Model-facing whole-list replacement. Each call appends a todo/write snapshot to the calling agent's session; replay is last-write-wins, and UIs render from session events. A non-agent caller has no owning list and is rejected. Named exports preserve loader ...”；固定提交中扫描到的声明包括 name、inject、Config、apply、describe；本地静态 import 图显示它直接依赖 6 个源文件，并被 7 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/session/src/index.ts、packages/core/tools/src/index.ts、packages/session/session-projection/src/index.ts、examples/headless-agent/tests/harness.ts
  • 对应测试：packages/todo/tool-todo/tests/integration.spec.ts、packages/todo/tool-todo/tests/invariant.spec.ts、packages/todo/tool-todo/tests/loader-composition.spec.ts、packages/todo/tool-todo/tests/projection.spec.ts、packages/todo/tool-todo/tests/tool-todo.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 测试支持：packages/core/agent-loop/tests/mock-adapter.ts
  • 阅读顺序：先读 packages/todo/tool-todo/README.md、入口和消费者，再读当前契约，沿着 examples/headless-agent/tests/harness.ts、packages/todo/tool-todo/tests/integration.spec.ts、packages/todo/tool-todo/tests/invariant.spec.ts 看它怎样约束运行时，最后对照 packages/todo/tool-todo/tests/integration.spec.ts、packages/todo/tool-todo/tests/invariant.spec.ts、packages/todo/tool-todo/tests/loader-composition.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 226 行；扫描到的声明包括 name、inject、Config、apply、describe、toTodoList；源码顶部原注释（英文，仅作回查线索）：Model-facing whole-list replacement. Each call appends a todo/write snapshot to the calling agent's session; replay is last-write-wins, and UIs render from session events. A non-agent caller has no owning list and is rejected. Named exports preserve loader ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/src/invariant.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查工具必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant”；固定提交中扫描到的声明包括 name、inject、apply、validateTodos、validateEvent；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/session/src/index.ts、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts、packages/todo/tool-todo/tests/invariant.spec.ts
  • 对应测试：packages/todo/tool-todo/tests/invariant.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/core/session/src/index.ts、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和 packages/todo/tool-todo/tests/invariant.spec.ts 理解状态变化，最后对照 packages/todo/tool-todo/tests/invariant.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 66 行；扫描到的声明包括 name、inject、apply、validateTodos、validateEvent；源码顶部原注释（英文，仅作回查线索）：Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/src/types.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：类型契约
  • 这个文件有什么用：它描述工具中流转的数据长什么样、哪些字段必填以及各部分怎样关联，让不同模块先共享同一份约定。
  • 为什么这样设计：先把形状和规则集中声明，执行代码只负责使用已经检查过的数据；这样错误更早暴露，读代码时也有一张共同的地图。
  • 文件级设计证据：源码顶部注释把它定位为“Pure types of the todo domain: the ONE home of the todos projection-key declaration plus its payload types, free of this package's host-side value imports (dsh-tools, zod). Two namespace projections serve it — ./types for host consumers, ./client/types (the...”；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/session/src/types.ts、packages/todo/tool-todo/src/client.ts、packages/todo/tool-todo/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：examples/headless-agent/tests/coding-task.e2e.ts、examples/headless-agent/tests/compaction.e2e.ts、examples/headless-agent/tests/full-loop.e2e.ts、examples/headless-agent/tests/resume.e2e.ts、examples/headless-agent/tests/todo-write.e2e.ts、packages/client/ui-conversation/tests/todo-panel.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/todo/tool-todo/README.md、入口和消费者，再读当前契约，沿着 packages/todo/tool-todo/src/client.ts、packages/todo/tool-todo/src/index.ts 看它怎样约束运行时，最后对照 examples/headless-agent/tests/coding-task.e2e.ts、examples/headless-agent/tests/compaction.e2e.ts、examples/headless-agent/tests/full-loop.e2e.ts。
  • 代码证据：固定提交归档实际读取结果：约 27 行；源码顶部原注释（英文，仅作回查线索）：Pure types of the todo domain: the ONE home of the todos projection-key declaration plus its payload types, free of this package's host-side value imports (dsh-tools, zod). Two namespace projections serve it — ./types for host consumers, ./client/types (the...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/tests/integration.spec.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查工具的具体场景，包括“todo_write tool through the agent loop”、“model calls todo_write: a tool/call, a non-error tool/result, and a todo/write snapshot...”、“a second todo_write replaces the list (last-write-wins on the log)”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“todo_write tool through the agent loop”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 harness、waitForIdle、findEvent；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/agent-loop/src/index.ts、packages/core/agent-loop/tests/mock-adapter.ts、packages/core/agent/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 测试支持：packages/core/agent-loop/tests/mock-adapter.ts
  • 阅读顺序：先看它直接导入的被测实现 packages/core/agent-loop/src/index.ts、packages/core/agent/src/index.ts、packages/core/session/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 101 行；扫描到的声明包括 harness、waitForIdle、findEvent；扫描到的测试主题包括 “todo_write tool through the agent loop”、“model calls todo_write: a tool/call, a non-error tool/result, and a todo/write snapshot land”、“a second todo_write replaces the list (last-write-wins on the log)”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/tests/invariant.spec.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查工具的具体场景，包括“todo snapshot invariants”、“accepts historical and live parallel snapshots under the single-active tool policy”、“ignores unrelated dispatches and session events”、“rejects an invalid existing snapshot on late registration”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“todo snapshot invariants”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 setup、event；本地静态 import 图显示它直接依赖 6 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/session/src/index.ts、packages/core/tools/src/index.ts、packages/runtime-diagnostics/invariants/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/core/session/src/index.ts、packages/core/tools/src/index.ts、packages/runtime-diagnostics/invariants/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 78 行；扫描到的声明包括 setup、event；扫描到的测试主题包括 “todo snapshot invariants”、“accepts historical and live parallel snapshots under the single-active tool policy”、“ignores unrelated dispatches and session events”、“rejects an invalid existing snapshot on late registration”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/tests/loader-composition.spec.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查工具的具体场景，包括“tool-todo real Loader composition through cordis.yml”、“allowParallelInProgress: false narrows the description and rejects a parallel write”、“allowParallelInProgress: true permits a parallel write end to end”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“tool-todo real Loader composition through cordis.yml”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“Proves allowParallelInProgress is real configurability and not a constant: the flag is set in a cordis.yml booted through the real Loader, and both faces it controls — the model-facing description and the accepted input — follow it.”；固定提交中扫描到的声明包括 agent、resultText、boot；本地静态 import 图显示它直接依赖 9 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 139 行；扫描到的声明包括 agent、resultText、boot；扫描到的测试主题包括 “tool-todo real Loader composition through cordis.yml”、“allowParallelInProgress: false narrows the description and rejects a parallel write”、“allowParallelInProgress: true permits a parallel write end to end”；源码顶部原注释（英文，仅作回查线索）：Proves allowParallelInProgress is real configurability and not a constant: the flag is set in a cordis.yml booted through the real Loader, and both faces it controls — the model-facing description and the accepted input — follow it.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/tests/projection.spec.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查工具、状态投影的具体场景，包括“todos projection provider”、“serves null before the first todo/write”、“serves the latest whole list after writes, asOfSeq = last event seq”、“clears the standing plan on the next turn/start (turn/end keeps it)”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“todos projection provider”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“The todos projection provider (session-projection RFC knife 4 — the "a fourth domain is just its own registrations" acceptance probe): mounting tool-todo beside the registry serves the whole current list on the history tail page with a consistent asOfSeq (=...”；固定提交中扫描到的声明包括 request、harness、seedMessage；本地静态 import 图显示它直接依赖 11 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 124 行；扫描到的声明包括 request、harness、seedMessage；扫描到的测试主题包括 “todos projection provider”、“serves null before the first todo/write”、“serves the latest whole list after writes, asOfSeq = last event seq”、“clears the standing plan on the next turn/start (turn/end keeps it)”、“has no todos key when tool-todo is not composed”、“drops the key when the tool-todo fiber unloads (HMR safety)”；源码顶部原注释（英文，仅作回查线索）：The todos projection provider (session-projection RFC knife 4 — the "a fourth domain is just its own registrations" acceptance probe): mounting tool-todo beside the registry serves the whole current list on the history tail page with a consistent asOfSeq (=...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/todo/tool-todo/tests/tool-todo.spec.ts ​

  • 所属层：packages/todo：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查工具的具体场景，包括“dsh-tool-todo”、“registers a”、“appends a todo/write event carrying the whole list to the calling session”、“stores the trimmed content (the dedupe/length key), not the raw input”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“dsh-tool-todo”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：固定提交中扫描到的声明包括 agentWithSession、setup、callTodo、text；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/todo/tool-todo/README.md、packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/core/agent/src/index.ts、packages/core/session/src/index.ts、packages/core/system-prompt/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 235 行；扫描到的声明包括 agentWithSession、setup、callTodo、text；扫描到的测试主题包括 “dsh-tool-todo”、“registers a”、“appends a todo/write event carrying the whole list to the calling session”、“stores the trimmed content (the dedupe/length key), not the raw input”、“replaces the list on a second call (last-write-wins on the log)”、“rejects a malformed status before execute runs (registry arg-validation)”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。