dsh-todo-assistant

中文 | English

Todo Assistant

为 DSH 会话中的旁支任务保存上下文，并在需要时把它交接给未来的会话。

开发时，你可能突然发现一个 Bug、想到一项配套功能，或意识到当前实现还缺少某个步骤。但主任务正在进行，你不想现在中断；等以后回来处理时，也不想重新调查一遍，更不想再次向 AI 解释来龙去脉。

Todo Assistant 让你先把这件事记下来。AI 会整理与该任务相关的必要信息，任务卡片可以在之后被查看、补充，并带入新会话或当前输入框。

它不只是记录"还有什么没做"，也帮助保留"为什么要做、之前已经知道什么、下一步该做什么"。

右侧栏还有一个“计划”页：把 Markdown 计划导入成项目和阶段，按阶段查看依赖、验收和执行结果，并从某个阶段直接开始新会话或插入交接材料。

适合哪些场景？

发现 Bug，但暂时不修

你正在实现一个大功能，顺手发现了另一个模块的问题。先把问题和相关线索记下来，继续完成当前主任务；之后再单独处理。

想到配套功能，不想打断主线

实现过程中，你发现还需要一个设置项、一个编辑入口，或某个补充流程。先记录想法，等当前阶段完成后再回来处理。

把任务交给另一个会话

当你准备处理一张卡片时，可以让插件新建一个会话，并把卡片内容作为开场上下文；也可以将提示插入当前会话的输入框，由你决定何时发送。

减少重复调查和重复说明

卡片可以保留开发者的原始请求、任务相关信息、文件路径、下一步、必读内容和补充记录。必要时还可以按需回读原始会话中的指定片段，而不是一开始就把整段历史全部塞进上下文。

核心工作方式

• 先捕获，再处理。 记录旁支任务不要求你立刻离开当前工作。
• 只保留相关信息。 卡片围绕当前待办组织信息，避免把主任务的全部上下文无差别复制进去。
• 按需读取原文。 原始会话内容可以先查看目录，再选择需要的片段；回读成本较高，因此不会被当作普通的每轮提醒。
• 交接由你决定。 可以新开会话，也可以插入当前输入框；插入操作不会自动发送。
• 创建需要明确同意。 AI 不应擅自创建待办。使用标记语法本身即表示你同意记录。
• 提醒保持轻量。 插件根据当前会话访问的文件路径与该会话创建的未完成卡片做粗略相关性匹配，不需要每轮调用模型。

快速开始

1. 安装

在 DSH 中执行：

plugin_manager install_bundle  target = https://github.com/zangoose335/dsh-todo-assistant.git

install_bundle 需要审批，并且安装后需要重启 DSH。也可以从本地仓库安装，或按需固定到某个 Git commit。安装细节见下文。

2. 在右侧栏打开插件

在右侧栏点击 +，选择 Todo Assistant（卡片）或 计划（项目计划）。

“计划”页默认跟随当前会话的工作区，也可以切到全部工作区或收件箱。卡片按工作区查看；不属于任何工作区的卡只在 「全部工作区」视图里可见。侧栏提供未完成、待修复、待添加、已完成和全部等视图。

3. 记录一项旁支任务

你可以直接告诉 AI 希望记录什么，并明确同意创建；也可以使用下面的标记语法。同一条回复里可以放多个标记，一次记录多个待办。

#MEMO 会议记录完成后需要支持修改标题。先完成当前主功能，之后再实现标题编辑，并确认修改后的标题能正确保存和显示。
#/MEMO

#DB 和 #MEMO 都是待办标记，作用相同；DB 是"待办"的拼音首字母，MEMO 是更容易被国际用户理解的替代写法。它们不代表不同的任务类型。 AI 应根据内容判断这是待修复问题、待添加功能还是其他事项。

标记规则：

• #db、#DB、#memo、#MEMO 不区分大小写。
• 使用 #DB … #/DB 或 #MEMO … #/MEMO 成对包住要记录的内容；结束标记可以省略，此时记录到消息末尾。
• 代码围栏和行内代码中的标记会被忽略。
• 标记内容表示开发者已同意记录，AI 不需要再次询问是否创建。
• 没有标记时，AI 仍必须先得到开发者明确同意，不能自行创建待办。

输入框支持 #db / #memo 的轻量补全。AI 回复上的"记录待办"面板也可以帮助选择回复中的段落并送入捕获流程。

卡片包含什么？

每张卡片首先是一份任务简报，再附带来源与现场：

• 目标（goal）：要解决什么问题、实现什么需求；
• 背景（why，可选）：为什么需要它；
• 已确认事实与决定（confirmed）：每条都标出可信度；
• 约束（constraints）：实现时不能违反的条件；
• 线索（leads）：文件、符号或文档路径，只作辅助；
• 下一步（nextAction）：开始执行时先做什么；
• 待确认（openQuestions，可选）：尚未确认、可能影响执行的问题。

brief.nextAction 是唯一的规范下一步。旧字段 nextStep 作为兼容镜像保留：只提供 brief 可以建卡，只提供 nextStep 仍兼容；两者冲突时以 brief 为准并返回 warning，任何正常写入都会同步二者。

简单任务可以只有 goal + nextAction，不要求填满其他字段。每条 brief 信息必须标明 requirement（开发者要求）、decided（已确认决定）、verified（已验证事实）、 inferred（AI 推断）、unknown（未知）或 superseded（已被替代）；推断不会被写成已确认事实。

只有来源指针、没有实质任务说明的输入会被拒绝：无 brief 且只有 touchedFiles/park/symbols 时返回 todo/brief-required，brief 只有 leads 时返回 todo/brief-source-only，forceCreate 也不能绕过。 旧式调用只给 nextStep、不带来源字段时仍然兼容；带真实文件路径时按“只有路径”处理，需要补简报或至少一条 mustRead 事实。

旧卡没有 brief 时，插件从 core、mustRead、park 和 touchedFiles 派生只读简报。派生信息只用于读取， 不会批量改写旧数据；旧卡的可信度默认按 unknown 处理，不能当成已验证事实。派生简报不能凭空补出 confirmed/constraints，也不会把 mustRead 自动升级为已验证。

开发者原话由 Host 从用户消息中保存，不依赖 AI 转述，因此可以用来核对 AI 是否误解了原始需求。带 #DB/#MEMO 标记时，标记内的文本会完整保存；没有标记时，AI 只摘取与当前待办有关的那几句。若模型没有给出摘录，多段消息只保存第一段；第一段只是创建指令时不保存 request。

处理任务与交接上下文

打开卡片后，你可以选择：

• 新会话中处理：创建一个新会话，并将卡片整理成开场上下文。开场会要求先读代码/资料并给出方案，不直接改文件；确认方案后再实现。处理中需要你决定时，会在任务过程中使用 DSH 的提问面板，而不是等到最后才问。
• 插入当前会话：将一条处理提示插入当前输入框。它只会预填，不会自动发送；需要你决定时，同样会在处理过程中提问。

处理完成后，AI 应询问你是否将卡片标记为完成；得到确认后才更新状态。

卡片也支持追加 note，以记录新证据、进度或补充事实，而不是悄悄覆盖原始记录。

项目计划（Project Plan）

右侧栏的第二个入口“计划”用来放跨会话的项目计划；它和“待办”页并存，互不影响。

• 项目列表：项目名、目标、状态、当前阶段、阶段数和待处理提议数。
• 导入 Markdown：粘贴一份计划，先解析成预览：识别出的阶段、需要你确认的推断（依赖绑定、自动编号）、没认出来的段落（不会保存）。确认后再保存；有推断但没确认时保存会被拒绝。
• 阶段：支持阶段与子阶段、依赖、验收、必须保留的上下文、决策、相关文件、状态和执行结果；可以新增、编辑、拆分、删除（被其他阶段依赖或有子阶段时会拒绝）、改状态、记录结果、设当前阶段。
• 阶段结果与证据：AI 只能“提出结果”（做了什么、改了哪些文件、测试命令和结果、遗留问题），不能直接标记完成；插件会把 AI 说的测试和当前会话真实跑过的工具结果核对——真跑过的标“工具结果”，没跑过的仍是“AI 声称”，实际跑过但漏说的会补进来。你在计划页点“应用”才写入结果，勾“我确认这些测试结果”可把无工具证据的测试记为“开发者确认”。
• 计划变化：AI 还可以提“新增阶段、拆分阶段、改依赖、改验收”四种提议；程序自己算出字段级 diff 和受影响阶段（改动阶段 + 下游依赖 + 共享验收/决策的阶段），AI 只解释原因。版本不一致时提议会被直接拒绝，应用时再拦一次。
• 项目级修改与审计：AI 还能提项目名字、目标、状态、当前阶段、项目决策、项目风险六项修改，但同样只能提议。计划页“应用”要再点一次“确认应用”才写入；已应用/已拒绝的提议能在“提议历史”里查，变更历史会标出“提议应用/直接编辑”和类型；diff 的新增用绿色、删除用红色。
• 版本与决策历史：变更历史可点开看该版前后差异，也能看“初始计划”和“初始 vs 当前”；支持分页加载；决策历史列出项目/阶段决策和风险的增删，提议结果留在提议历史。历史只存结构化摘要，不重建任意中间版本的完整计划。导出默认只带变更摘要（版本/类型/原因/影响阶段），需要时可选带完整 diff。
• 阶段交接：“开始阶段”为该阶段开一个新会话，开场包含项目目标、阶段目标/下一步、直接前置阶段的实际结果、决策、验收、风险、未解决项、来源指针和工作区规则；“插入交接”只把同一份材料写进当前输入框，不自动发送。材料只带指针，不带历史或文档正文；超过约 4000 字时保留关键项，并提示用 todo_plan_read 补看。
• 导出：把当前计划导出为 Markdown，写进项目所在工作区的文件夹；文件名取项目名，重名自动加 -2，不覆盖同名文件。收件箱里的计划需要先放进一个工作区。
• 只读工具：AI 可以用 todo_plan_read 查看项目/阶段/依赖/验收/结果，用 todo_plan_context 生成阶段交接；两者都不会改计划。

最小 Markdown 语法：# 项目名 加首段作为总体目标；## Phase 4: 标题 为阶段，### Phase 4a: 标题 为子阶段（也接受 A、B2 这类编号）；阶段内用 Goal:/目标:、Acceptance:/验收:、Depends on:/依赖:、Context:/上下文:、Decisions:/决策:、Risks:/风险:、Next:/下一步:、Result:/结果: 加条目。代码围栏会被忽略，认不出的内容只出现在预览里，不会写进计划。

上下文读取与提醒

分层读取

• 索引：快速查看标题、状态和类型。
• 卡片：先读任务简报（目标/背景/已确认事实/约束/下一步/待确认），再按需看必读信息、文件和补充记录。
• 原始会话：先查看可回读消息的目录，再选择指定片段读取。

原始会话回读可能消耗较多 token。插件的工具说明要求 AI 先征得开发者同意，再查看目录并读取指定片段。手动创建、没有原始会话范围的卡片可能无法回读原文。

相关性提醒

插件会收集当前会话中的部分文件工具路径，并与该会话创建的未完成卡片比较。如果文件路径完全相同，或共享足够长的目录前缀，侧栏可能显示"相关"标记，并在后续步骤提醒 AI。

这是一种轻量路径信号，不是语义级的任务理解，也不能保证发现所有相关修改。它主要用于提示 AI：如果本轮产生了值得保留的新证据，可以通过 note 追加到卡片。

其他功能

• 按工作区查看；不属于任何工作区的卡在「全部工作区」中显示；
• 近似重复待办检测：共享文件是前提，标题或任务目标相似可辅助命中；同一文件但目标不同不会仅因标题相似被拦截； 命中只是提示，不会自动合并或取消创建；开发者确认创建后可用 forceCreate 继续，确认补充则用 todo_note；
• 短编号，例如 #3.2，便于在对话中引用卡片；
• # 引用选择器：正常会话中候选按当前会话所属工作区筛选；缺少会话 ID 时退回查询全部工作区；
• 每个工作区独立的通用规则，并在插件创建新会话时带入；
• 计划页：项目列表、阶段树、依赖/验收、导入导出、阶段交接，与卡片页并存；
• 卡片状态、补充记录和原始上下文回读工具。

当前阶段与限制

当前已完成 P0-BASE、T1–T4 的基础实现；T5/Gate 1 于 2026-10-19 严格复核、修复语义并完成真实运行验收，结论为通过（PASS，带范围限制）：

• TaskBrief 创建、持久化、读取、旧卡派生和右栏展示；
• brief.nextAction 与旧 nextStep 的统一契约；只给 brief 或只给旧 nextStep 都可建卡，冲突时以 brief 为准并返回 warning；
• brief 参与去重（共享文件 + 标题/目标相似度）；
• version-1 旧数据兼容；真实旧代码 be8ebf4 探针显示降级会丢 brief 和 sources。

Gate 1/T5 通过（PASS，带范围限制；2026-10-19 严格复核 + 语义修复 + 真实运行验收）。 验证依据：node scripts/verify-brief.mjs 118/118、node scripts/verify-domain.mjs 262/262、node scripts/verify-recall.mjs 35/35、 node scripts/verify-gate1.mjs 63/63（S1–S10 39/39）、node scripts/verify-legacy.mjs 11/11、git diff --check 通过。 §8.0 的确定性 S1–S10 全部通过；修正后的隔离语义探针 10/10 通过（S3 约束进 constraints、S4 无多余 verified 元约束、S5/S6 的 blocking 与 nextAction 正确、S9 先问追加还是新建）。 所有 wouldCallRecall=false 仍是模型自述，不是调用轨迹。详见 docs/GATE1-T5-ACCEPTANCE.md。

Gate 1 UI 冒烟已由开发者验证（2026-10-19）： # 引用框工作区筛选、完成/反向切换动画、减少动态效果、窄窗口布局、duplicate 提示均未发现问题。UI 冒烟不等于十场景语义验收。

范围限制： 旧插件 UI 和存储写回使用副本/测试工作区，未对真实 ~/.dsh 做破坏性升级/降级；S9 需要用户明确指向 #6.25；S2 约束有重复、S7 比最简多两个字段。真实 UI 十场景、真实 todo_recall、旧插件 UI、存储副本和场景 10 均已验证。

Stage 4（B1–B5、C1–C4）验证（2026-10-20）： verify-plan 74/74、verify-phase 66/66、verify-import 67/67、verify-context 46/46、verify-client 12/12、verify-evidence 32/32、verify-diff 28/28、verify-propose 20/20、verify-history 31/31，加上原有 5 个脚本共 865 项全部通过，git diff --check 通过。计划页手工验收记录见 docs/B5-ACCEPTANCE.md；C1 的真实提议/拒绝/应用、C2 的“改依赖”diff/受影响阶段、C3 的项目级提议/两步确认/提议历史、C4 的历史/初始对比/决策历史均已手工验收。

Stage 4 的 B1–B5、C1–C4 已完成（2026-10-20）：Project Plan 数据模型与三张表、阶段/依赖/验收/状态/执行结果、确定性 Markdown 导入与确认、阶段上下文包与只读工具、计划页（第二个右栏入口）和导出到工作区文件夹；C1 增加“AI 只能提议、工具结果才算证据、开发者应用后才生效”的阶段结果流程；C2 增加字段级 diff、受影响阶段和四种计划变化提议；C3 增加项目级六项提议、两步确认、提议历史与带颜色的 diff；C4 增加摘要版本历史、初始/当前对比、决策历史、分页与摘要导出。计划页已由开发者手工走通导入、拆分、当前阶段、开始阶段、插入交接和导出；普通卡片页未改动。

仍未实现：D1–D3（卡片/阶段拖拽交接）、E2–E4（卡片步骤与编号）。计划页暂不提供删除项目、阶段标题/目标编辑与删除提议；任意中间版本的完整计划无法重建（历史只存摘要，可看初始/当前/初始对比和单条变更）；Markdown 往返不保留测试证据明细；旧版本写回会丢掉 brief/sources，也会丢掉 projects/plan_proposals/plan_changes 三张表，升级前请备份 ~/.dsh/storages/todo_assistant.json。卡片拖拽仍只插入可见引用（如 #6.24「…」），完整正文通过三个操作按钮插入。

安装方式

所有方式都通过 plugin_manager install_bundle 安装，并且需要审批。

从 GitHub 安装：

plugin_manager install_bundle  target = https://github.com/zangoose335/dsh-todo-assistant.git

从本地仓库安装：

plugin_manager install_bundle  target = <仓库的绝对路径>

固定到某个 commit：

plugin_manager install_bundle  target = https://github.com/zangoose335/dsh-todo-assistant.git#<commit>

如果未来发布到 npm，也可以按包名和版本安装。install_bundle 需要 pnpm 位于 PATH 中。

安装或更新 Host 侧代码后，重启 DSH 以加载插件。只修改 client.js 时通常刷新页面即可；“计划”页依赖 Host 侧的新接口，更新后请先完整重启 DSH，再刷新页面。

安装后，在右侧栏点击 +，选择 Todo Assistant（卡片）或 计划（项目计划）。

开发与设计

本仓库包含实现与验证代码。若你希望了解数据结构、工具定义、标记解析、路径提醒、原文回读和 Host/Client 通信等实现细节，请阅读：

• docs/DESIGN.md：设计原则与实现决策
• docs/B5-ACCEPTANCE.md：计划页与 A–E 路线图的验收记录
• scripts/verify-domain.mjs：卡片/存储/回读的无头验证
• scripts/verify-plan.mjs、scripts/verify-phase.mjs：计划与阶段
• scripts/verify-import.mjs、scripts/verify-context.mjs：导入导出与交接
• scripts/verify-client.mjs：浏览器端页签注册冒烟
• scripts/verify-evidence.mjs：测试证据配对、提议与应用
• scripts/verify-propose.mjs：项目级提议、应用/拒绝与审计
• scripts/verify-history.mjs：版本摘要、初始/当前对比、决策时间线与导出
• scripts/fixtures/plan-a-e.md：A–E 路线图导入样例

许可

MIT © 2026 黑桃伍