todo-assistant
DSH 插件：跨会话的旁支任务工作台——把会话里「先不做但别忘」的事记成卡片，之后单独开会话处理。A DSH plugin: a cross-session workspace for side tasks found mid-session.
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:zangoose335/dsh-todo-assistant#cc59cf4229eebd7703810337b9d49735732a2f25Todo Assistant 以 todo-assistant 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
跨会话的旁支任务工作台：把会话里"先不做但别忘"的事记成卡片，之后单独开会话处理。 设计见 docs/DESIGN.md。安装见 安装，许可见 LICENSE（MIT）。
当前功能：
todo_add（完整 schema + git 坐标 + mustRead/park + 开发者原话 + 路径归一化）、去重拦截、
#DB … #/db / #MEMO … #/memo 标记、AI 回复上的「记录待办」段落面板、输入框 #db 补全与 # 引用框；todo_read / todo_note / todo_status / todo_list / todo_recall（两段式原文回读）；| 文件 | 作用 |
|---|---|
host.js | Host 插件入口：打开 todo_assistant storage domain，注册 /api 路由与 todo_add 工具 |
domain.js | 领域声明（zod record schema）与纯逻辑：建卡、捕获校验、改卡、ID、L0 投影 |
api.js | 数据操作与线协议：list / create / patch / remove / note.add / note.remove |
tool.js | 六个工具定义：todo_add / todo_read / todo_note / todo_status / todo_list / todo_recall |
git.js | 写卡时的代码坐标：git rev-parse（subprocess）优先，.git 文件读取兜底 |
detect.js | 检测规则：工具调用 → 路径 → 卡片匹配 → 提醒行 / 角标集合 |
recall.js | L2 回读：原始日志 → 目录（seq/轮次/角色/首行/token）→ 指定 slice 的正文 |
dedupe.js | 近似重复：同工作区 + 共享触及文件 + 标题相似度 |
client.js | 浏览器 half：右栏页签类型 + 卡片 UI（无构建步骤，只用 baseline react） |
scripts/verify-domain.mjs | 无头验证：用安装里的真实 storage 栈打开 domain 并跑完整个线协议 |
domain.js / api.js 刻意不写任何包导入，测试脚本可以脱离 profile 直接驱动它们；
真实依赖由 index.js 注入 createTodoSpec({ z, defineDomain, domainTable })。
#DB 标记（输入即同意）在消息里写：
#DB 导出 CSV 时表头重复
第二行也算待办内容
#/db
#DB / #db，或英文的 #MEMO / #memo（两者等价，同一捕获链路）；结束标记 #/db / #/memo 可省略（省略时到消息结尾），两种结束标记可互换；user/message（只认人打的，source.kind === 'user'）上扫描，命中就排进该会话的队列；request。识别点在 host 侧（agent/inbox/claimed，早于 prompt 装配），所以不依赖 composer 的提交钩子；也不改发送流程。
输入框里有轻量补全：打 #db 会变成 #DB #/DB，打 #memo 会变成 #MEMO #/MEMO，光标停在两个空格之间。实现只用公开的 useInput + inputActions（先插 #/db、再把 #db 替换成 #DB ），不碰编辑器内部与 DOM。
右上角的圆形 (i) 按钮展开「待办助理使用说明」：插件定位、为什么值得用（记卡带现场、读卡省 token、主线不断、重复提醒、规则写一次）、按场景的用法（问 AI 记卡 / 事后 #x.y 接着做 / 一次多条 / #db 输入即记录 / # 引用 / 开始任务收尾 / 通用规则），以及 #x.y 编号含义。文案在中英两份 i18n 里，改措辞直接改 client.js 的 help.body。
点 AI 回复上的「记录待办」后：
todo_add；--dsw-radius-panel + --dsw-elevation-prominent）。todo_add 落卡时，host 会把当前轮里人打的用户消息（source.kind === 'user'，跳过文件变更/技能等系统注入）逐字存进卡片的 request.text（上限 8000 字，超了标 truncated），模型完全不参与这段文本。
todo_read 默认输出里带 developer request (verbatim)；如果消息里带了 #DB … #/db，只记对应那一段，标记本身不入库；一条消息里多个标记时按出现顺序各记一段（request.block 记序号）。识别点允许标记紧跟在中文标点后（两条：#db …），但贴在单词里（abc#db）不算。
这样 AI 的理解有偏差时，你能对着原话立刻纠正；它也永远不会被"总结"掉。
右栏面板里有一块可折叠的「通用规则」，按工作区保存：
todo_assistant 域的 rules 表里，key = 工作区路径（rules.get / rules.set 两个端点）；todo_status(id, status)：唯一能改状态的工具（open / doing / done / dropped），描述里写死必须先得到开发者确认；#x.y 标记为完成，确认后再调 todo_status」；done，不需要你自己去右栏改。每张卡有一个短标签 #3.2，与内部 id（td_x7k2）并存：
header.parentSession 上溯到根，卡片归到根的组；x.0）；1.<旧编号>（1.1…1.N）；迁移后旧会话再进新卡会另开 major —— 历史桶不吸收新卡；#x.y；入参接受 3.2、#3.2 和 td_x7k2。todo_assistant（下划线）：storage 层强制 UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/，
连字符会被 defineDomain 直接拒绝。storage-domain 的默认 json backend，所以卡片落在 ~/.dsh/storages/todo_assistant.json（单文件 layout）。workspace 存会话所属工作区的规范化路径；不属于任何仓库的卡放 inbox。todo_add 是表单，不是自由写总结：
title / kind / nextStep / touchedFiles / mustRead（必填）+ symptom / cause / intent / park / symbols（可选）；title ≤40、mustRead ≤3 条且每条 ≤200、park.label ≤30、park.why ≤60；touchedFiles 为空只警告不拦截；touchedFiles 在写入时归一化：绝对路径按工作区剥成相对路径、去掉 ./ 与目录尾斜杠、反斜杠转正斜杠、去重；工作区之外的绝对路径保持原样。所以模型写 /Users/.../src/a.ts 也能参与路径提醒与去重（两者都按归一化后的形式比较）。origin（sessionId / turn / seqRange / cwd）与 code（commit / branch，来自 git rev-parse，subprocess 不可用时读 .git/HEAD + refs / packed-refs）全部由 host 填，模型不产出；workspace 由 session cwd 经 workspaceRegistry.resolveByPath 归一化，和右栏的工作区过滤对齐。todo_list(workspace?, status?)：只有索引（id / 标题 / 状态 / 类型），默认看本会话工作区里 open+doing 的卡；workspace: '*' 跨工作区。todo_read(id, part?)：无参返回卡片本体（core + mustRead 正文 + park 的 label/why + 坐标 + 触及文件 + note 数）；part: 'notes' 给补充历史；part: 'park:n' 给该条备查指针（含 where，正文留给 M6 的 recall）。
mustRead 每条本来就 ≤200 字，是"必读材料"，所以放在默认返回里；park 只给 label/why，正文按设计不主动加载。todo_note(id, text, kind?)：追加，text ≤300 字，kind = supplement / evidence / status；先校验再落库，不重写卡片。右栏卡片右上角的 ⌄ 展开详情（同一份数据走 POST /api/todo-assistant/detail），可直接删补充。
零模型调用，全部在 host 侧算：
session/event 里的 tool/call 参数（read/write/edit/read_image 的 file_path，grep/glob 的 path），按会话 + 轮累积；open/doing 的卡（origin.sessionId 匹配）；src/auth/router.ts vs src/auth/token.ts 命中；src/a.ts vs src/b.ts 不命中）；step/end 触发检测，turn/start 重置本轮预算，已提醒的卡不会在同轮重复；ctx.systemPrompt.context({ name: 'todo-assistant/reminder', order: 130, text })，在下一次装配（同轮下一步）给一行：
A file touched this step (src/auth/router.ts) relates to todo #td_x7k2「…」; call todo_note if there is evidence worth keeping.
装配即消耗，下一轮之前不会再出现；list 请求带上 sessionId，命中卡在 L0 上带 hit: true，右栏显示「相关」并描边；turn/start 重置。未接的信号（DESIGN §7 已决定不做）：commit 变化、从触及文件反推符号。两者也是零模型调用，问题在质量——卡的 code.symbols 常为空、符号名是通用词易误报、commit 多是陈旧性信号；路径信号已覆盖"同一个地方又动了"这一主场景，漏的是"文件移动/改名、只改符号、按符号 grep"三类。
todo_recall(id, slice?) 是 L2，两段式，最贵的一次读取（正文会永久留在上下文里、每步重复计费）：
slice → 目录：卡片 origin.seqRange 里每条消息的 seq / 轮次 / 角色 / 首行 40 字 / token 估算，外加总量；slice: [from, to] → 只返回这一段正文（每条消息截 2000 字、整次上限 12000 字，超了标注 truncated）。数据来自 ctx.sessionQuery.readSession(id) 的原始日志（不是当前 surface），所以即使那段历史已被压缩替换，也能读回原貌；token 估算优先用 ctx.tokenMeter.estimateMessage，没有就按 ~4 字符/token 粗估。
工具描述里写死了硬规矩：不得自行 recall，必须先征得开发者同意；先给目录，再由开发者选段。
这条约束是指令而非强制（没有 UI 审批拦着）。两次行为探针（"早期轮次已压缩，需要知道当时为什么排除方案 A"）里模型都是先 todo_read、再停下来请求批准，日志里未授权调用为 0；据此决定不加机械审批，真出现一次漏网再加（DESIGN §6.4）。
手工建的卡 origin.seqRange 是 [0,0]，没有可回读区间，会返回 unavailable。
todo_add 落库前先算一遍"这是不是同一张卡"（§6.5）：
workspace、状态 open/doing 的卡；touchedFiles 精确相同 且 标题相似度 ≥ 0.55（字符 bigram Dice，忽略大小写/空白/标点）；status: 'duplicate' + 候选 id/标题/相似度/共享文件，让模型去问开发者；开发者同意后用 todo_note 把新事实追加到那张卡；touchedFiles 为空的捕获不参与去重（只靠标题太容易误判）。误判代价是模型多问一句，比"同一件事两张卡"便宜。
卡片上的「处理」展开两个动作（DESIGN §3.11）：
ctx.remote.session.create({ workspaceId | cwd }) → .prompt({ mode: 'queue', content: [{type:'text', text: seed}] }) → ctx.uiWorkspace.openSession(sessionId)。
seed 是卡片的 L1：标题、现象/原因/意图、下一步、触及文件、必读（含正文）、备查 label/why、写卡时的 commit、补充条数。新会话从一开始就知道自己在处理哪张卡。inputActions.captureInsertion() + insertText() 往当前输入框里插一句
现在切到待办 #1.3「…」：先用 todo_read 读它，再按里面的「下一步」继续；改完后问我是否标记完成。
只预填、不自动发送 —— 不替人发消息，也不打断正在跑的轮次；回车由开发者按。两种方式都会在卡片上记 handling: { sessionId, at }（POST /api/todo-assistant/handle），
列表与详情都不再显示处理标记（2026-10 移除）：会话接手只创建/发送种子，不写 handling。
字段仍保留在数据模型里以兼容旧卡，todo_read 也还能读到，但 UI 不写入、不展示。
关联改动：卡片的状态不再用下拉菜单——编号左侧的 radio 直接标完成/取消，× 菜单给「删除 / 归档 / 取消」，
kind 标签移到左下角，× 移到右上角。
与设计的一处偏差：设计里「处理」是卡片上的
[处理 ▾]菜单；这里同样是点一下展开两个选项， 只是菜单行内展开而不是浮层。
形态：/api 通道上的 exact Fetch 路由。不是 @Remote，不是 rpc.handle，也不是自建
webServer 路由。
ctx.connection.fetch.register({ path: '/api/todo-assistant/<endpoint>', methods: ['POST'], requestBody: 'buffered', fetch })。路由挂在 Connection 已有的 /api 前缀下，Host/Origin
信任围栏与浏览器 cookie 鉴权在进入 handler 之前就生效（无 cookie → 401）。fetch('api/todo-assistant/<endpoint>')（document-relative，兼容挂载前缀）。@Remote：那些 namespace 由 TypeScript 装饰器在构建期生成，再由应用自己的 ctx.remote
装配挂载；纯 JS 插件没有这条构建链。ctx.connection.rpc.handle()：它挂路由时读的是 Connection 服务自己的 fiber
（get rpc() 里 const owner = this.ctx），那条 fiber 只 inject 了 webRuntime，必然抛
cannot get property "webServer" without inject。intercept('/api', …) 不碰 webServer，但
/api 的中继已被 API Gateway 独占。线协议（裸 JSON，不套 Gateway 信封）：
POST /api/todo-assistant/<endpoint>
{ ...payload }
→ { "ok": true, "value": ... }
→ { "ok": false, "error": { "code": "todo/title-required", "message": "...", "details": {} } }
离线（不需要启动 GUI，不动 profile）：
node scripts/verify-domain.mjs
它用本地 dsh 安装里的真实 storage / storage-json / storage-domain 打开本插件的 domain，
跑完增删改查与 note 追加/删除，最后关闭再重开，确认记录跨重启存活。
安装后（当前 profile）：
# 1. 已激活
# 在会话里 cordis_inspect_query → Slots.listSubTree(root: "sidebar.right.pane.tab")
# 应看到 key = "todo-assistant" 的 occupant
# 2. 冒烟调用（需要浏览器 session cookie，见下；无 cookie 应返回 401）
curl -sS -X POST "http://127.0.0.1:3080/api/todo-assistant/list" \
-H 'content-type: application/json' \
-H 'Host: 127.0.0.1:3080' -H 'Origin: http://127.0.0.1:3080' \
-b "$COOKIE" \
--data '{"all":true}'
cookie 就是浏览器里那份 dsh-auth-*（签名密钥在 ~/.dsh/.credentials.yaml 的
client-connection/browser-session 记录里；签名 key 要先 base64url 解码）。
三种方式，任选一种。都需要在 DSH 里调用 plugin_manager install_bundle（需要审批），装完重启 dsh。
1. 从本地目录（开发用） —— 源码留在这里，不要放进 ~/.dsh：
plugin_manager install_bundle target = <本仓库绝对路径>
2. 从 GitHub 直接装 —— 不用先 clone：
plugin_manager install_bundle target = https://github.com/zangoose335/dsh-todo-assistant.git
想锁版本就在地址后加 #<commit>，例如 ...#77215f3。
3. 从 npm（发布后）：
plugin_manager install_bundle target = todo-assistant@0.1.0
install_bundle 要求 PATH 里有 pnpm（本机通过 corepack enable pnpm 提供）。
方式 1 装完后 profile 里是一个符号链接：
~/.dsh/profiles/web/node_modules/todo-assistant -> <本仓库绝对路径>
不同方式装的是同一个包名，切换前先 remove_bundle 掉旧的那份。
必须重启 dsh 才会加载 host half：linked 包的安装内导入（zod、@deepseek-ai/dsh-storage-domain）
依赖启动时建立的 profile 解析表，运行中的进程不会在安装后重建它。之后每次改 host 代码都要重启；
只改 client.js 刷新页面即可。
右栏 → 顶部 +（Add）打开 guide → 点「待办助理」。页签布局按会话记在 localStorage，重开仍在。
MIT © 2026 黑桃伍