zsspub/dsh-personal-todo

---

summary: 为 DeepSeek Harness 提供基于 SQLite 的个人待办工具与 Web 面板。 read_when:

• 你需要跨 DSH 会话和项目共享持久待办。
• 你正在安装或配置 dsh-personal-todo Bundle。

---

dsh-personal-todo

English | 中文

dsh-personal-todo 是一个可安装的 DeepSeek Harness Bundle。待办可以由用户自行推进，也可以按需交给普通 DSH Agent Session 执行；无需预先选择“人工任务”或“Agent 任务”类型。

功能

• 用户说“看看我的待办”等纯展示请求时，Agent 优先调用 personal_todo_show；工具执行区只保留宿主的紧凑记录，完整的可交互待办卡片在回答结束后的 turn 尾部展示，不再逐项输出 Markdown 表格。卡片在固定高度内滚动展示全部匹配项，可刷新、编辑、流转状态、交给 Agent、停止并接手、查看对话、取消、归档、恢复和删除，也可打开右侧面板并定位到指定任务。
• Web 客户端使用 Nanostores 建立唯一数据中心，并通过 React useSyncExternalStore 订阅；对话中的多张历史卡片、右侧面板、侧栏未完成数量和 @ 待办引用共享同一套实体、详情、查询缓存和操作状态。任一位置操作成功后，其他位置立即同步。
• 在聊天输入框输入 @，先选择待办或进行中分类，按 Tab 进入待办列表，再选中待办插入引用；不展示已完成、已取消和归档。分类内可输入关键词搜索标题、备注或负责人，最多显示 50 项；发送时读取最新待办详情。此入口需要 DSH 的 ui-input-trigger >=0.1.2-rc.1。
• 使用 schema 版本、WAL、foreign keys、busy timeout 和仅限所有者的文件权限实现持久 SQLite 存储。
• 每个交给 Agent 的待办关联一个持久主会话，后续沟通直接在原对话中进行。
• 自动识别 Agent 委派的子 Session，并将嵌套子会话作为待办的相关对话保存。
• DSH 重启只恢复状态展示，不激活 Agent、不自动发送消息或续跑。
• 侧栏入口显示未归档的待办与进行中任务总数，不再区分待回复或待审核。
• 主进度为待办 pending、进行中 in_progress、已完成 completed，次级状态为已取消 cancelled；归档独立。Agent 执行信息单独展示，不增加主状态。
• 保存任务、会话关联和用户操作历史；旧 Run 和结果保留，新执行不再新增 Run 或同步问题、摘要。
• 提供创建、查询、编辑、删除和 JSON 备份工具；不要求 Agent 调用状态同步工具。
• 将任务中心注册为宿主右侧 Sidebar 原生 Tab，复用宿主的打开、关闭、全屏、拖拽宽度和多 Tab 能力。面板显示待办、进行中、已完成三个主 Tab，“更多”仅收纳已取消和归档；“数据”菜单与状态筛选分离。卡片按负责人分组，详情支持手动流转和查看原对话。没有当前会话时，侧栏入口保持禁用。
• 任意生命周期状态的待办都可移入独立归档视图，并可恢复到对应列表或永久删除。
• 提供 typed 中英文 Client 字典。

环境要求

• 支持右侧 Sidebar Tab API、sessionQuery 和 Agent 生命周期通知的 DeepSeek Harness Web profile；本次按 0.1.7-rc.2 接口实现。
• Web profile 需要 @deepseek-ai/dsh-client-ui-tool 0.1.7-rc.2；项目使用 @deepseek-ai/cordis ~4.0.4。
• Node.js ^22.19.0 || >=24.0.0。
• 开发环境使用 pnpm 11.7.0。

安装

安装固定的 GitHub revision，直接使用仓库中提交的 lib/ 构建产物：

pnpm dsh plugin --profile web add github:zsspub/dsh-personal-todo#<commit-sha>

本地开发时使用：

pnpm dsh plugin --profile web add /absolute/path/to/dsh-personal-todo

Bundle patch 会挂载 Host 服务与工具，Web manifest 会自动加载 Client。

Agent 工具

工具	用途
personal_todo_add	新建待办，只保存不执行；可设置备注、负责人、优先级、截止时间和标签，未声明优先级时默认为中优先级。
personal_todo_show	纯展示请求使用。在回答结束后的 turn 尾部渲染实时可交互卡片，模型只收到数量摘要，并被要求只补充一句简短说明、不逐项复述或生成 Markdown 表格。
personal_todo_list	供 Agent 后续编辑、删除或数据处理时查询完整 JSON；也为旧会话日志提供同款卡片展示。
personal_todo_update	替换任意已提供的可变字段；null 清空备注、负责人或截止时间，[] 清空标签。
personal_todo_delete	按 UUID 永久删除一条待办。
personal_todo_export	无参数，返回完整备份的 { filename, json }；保存文件时使用宿主文件工具。
personal_todo_import	接收 { json } 备份内容，返回新增、跳过及转为待处理的数量；不直接读取文件。

列表默认返回 pending 和 in_progress，排除归档。传入 statuses: ["completed"] 可读取完成历史；查询全部归档时同时传入 archived: true 和四种主进度。通用编辑和 Agent 工具不能代替用户改变任务进度或确认完成。已移除 personal_todo_progress、personal_todo_block、personal_todo_submit_review，以及 needsAttention 筛选和计数。

对话卡片保存版本化、大小受限的展示快照，历史回放或刷新失败时仍有内容可看；只要原查询条件可恢复，卡片挂载、窗口重新聚焦、手动刷新和操作成功后都会读取当前数据。相同筛选条件的多张卡片共享全量分页请求和缓存，不重复访问 Remote。卡片不自行轮询；右侧面板可见时仍以 2 秒间隔刷新运行状态。刷新失败会保留已有数据并显示错误，不清空列表。

任务流程

默认“创建”只保存待办；“标为进行中”也不会创建会话或发送消息。例如“下班去驿站取快递”可以直接标记完成，也可以先标为进行中。只有“交给 Agent”“创建并交给 Agent”才显式派发任务消息。问题、回复、权限确认和结果全部留在原生对话，待办不维护第二套信息同步流程。

详情操作按当前任务情境收敛：普通待办显示“标记完成 / 交给 Agent / 更多”；执行中显示“查看对话 / 停止并接手 / 更多”；关联会话空闲后显示“标记完成 / 查看对话 / 更多”，再次交给 Agent 收进更多菜单。已完成、已取消任务突出“重新打开”，归档任务突出“恢复”。不再显示回复框、审核或继续修改按钮。低频管理操作收进更多菜单，删除仍需二次确认。

对话卡片不提供新建、复制、JSON 导入或导出，避免在历史消息中混入全局管理入口。表单草稿、菜单开关和确认弹窗只属于当前组件；实体、详情、筛选查询、计数和进行中操作由数据中心统一维护。同一待办正在操作时，其他卡片和面板会禁用重复操作。运行中的任务在完成、退回、取消、归档或停止接手前先显示停止确认；删除始终二次确认。Remote 成功前不提前改变生命周期，失败不会留下错误的乐观状态。

“更新插件功能”交给 Agent 后，任务进入进行中，同时展示执行信息：

executionStatus	展示	任务进度
null	不展示 Agent 信息	由用户手动管理
running	Agent · 正在执行	保留当前任务进度
idle	Agent · 空闲	不代表任务完成或等待用户输入
failed	Agent · 执行失败	保留当前任务进度
stopped	Agent · 执行已停止	保留当前任务进度
unavailable	Agent · 状态暂不可用	不影响任务管理和正常对话

执行标识来自主会话的 agent/status、agent/error、agent/disposed 与 session/event 通知，仅在内存中投影，不写 SQLite，不调用对话工具，也不使用会阻塞执行的 agent/turn-stopping hook。turn/end 的 error/max-tokens 显示失败，aborted/interrupted 显示停止，其余显示空闲；不推断业务完成、待回复或待审核。子会话结束不会结束主会话的运行标识。

首次查看冷会话时使用 sessionQuery.readSession，不会通过 resolveAgent 激活执行。并发读去重，成功结果缓存，失败显示暂不可用并至少间隔 30 秒重试。未结束的历史轮次在没有活动 Agent 时显示停止。宿主实时运行状态优先。任务完成仍由用户决定，重开和恢复归档不会自动执行。

typed Remote 保留 setStatus({ id, status }, signal) 和 stop({ id }, signal)；approve({ id }, signal) 等价于用户设置 completed，不再表示审核流程。移除 reply 和 requestChanges。重复设置相同进度不重复写活动记录。

配置

内置 Bundle 使用以下默认值：

字段	默认值	含义
databasePath	$DSH_HOME/personal-todo/todos.sqlite3	SQLite 文件的绝对路径。
journalMode	wal	SQLite journal mode，可选 wal、delete、truncate 或 persist。
busyTimeoutMs	5000	SQLite 等待写入锁释放的时间。
defaultListLimit	50	调用方未提供 limit 时的页大小。
maxListLimit	200	允许的最大页大小。
agentPreset	未设置	待办创建主会话时可选的 Agent preset。

部署策略需要其他值时，可覆盖 profile patch 中生成的插件配置。服务会拒绝相对路径、无效限制和高于当前支持版本的数据库 schema。

数据行为

标题会去除首尾空白，最多 200 个字符。备注会去除首尾空白，最多 10,000 个字符。负责人可选，去除首尾空白后最多 100 个字符；未设置负责人的待办显示在具名负责人分组之后的“未分配”组。每条待办最多包含 20 个唯一的小写标签，每个标签最多 32 个字符。截止时间必须是 RFC 3339 时间，并以规范 UTC 格式返回。

用户显式停止、完成、取消、退回待办和归档前，会先取消该任务专属主会话及关联子 Agent 的执行与排队消息，等待它们真正空闲，再写入状态。若取消失败或 15 秒内无法确认全部停止，则返回错误，不修改任务进度或 Run；部分 Agent 可能已经停止，运行标识会如实反映，用户可以重试。停止不撤销已经产生的外部修改。不要把待办专属执行会话用于无关工作。面板发现主会话运行时先要求停止确认；被动通知监听从不取消或干预对话。

新执行仅保存主会话关联和一次用户交付活动，不新增 Run。旧 Run、问题、结果和活动保留兼容；显式停止会结束旧活动 Run，完成设置 completedAt，重开清空该时间。归档设置 archivedAt，恢复仅清空归档时间，不自动执行。旧结果作为历史只读展示，不再作为当前运行状态来源。

数据库 schema 6 在首次加载时自动迁移：旧 blocked、in_review 主状态统一映射到 in_progress，原 waiting_input、submitted Run、归档、负责人、标签、会话和活动记录不变。备份版本独立于 SQLite schema；升级后旧插件不支持 schema 6，不应直接降级打开同一个数据库。

数据导入导出

在任务面板“新建待办”旁打开“数据”菜单，选择“导出 JSON”下载 UTF-8 备份；选择“导入 JSON”后先查看文件名、待办总数和旧版运行中记录数，确认后才写入。导出始终包含全部状态及归档待办，不受当前筛选、分页和详情最近 200 条活动的限制。导入成功后刷新当前列表和侧栏计数，不切换筛选。

导出格式为 { format: "dsh-personal-todo", version: 2, exportedAt, todos }，其中 todos 包含待办、标签、旧 Run、Session 关联和完整活动历史。备份中的 executionStatus 仅为旧持久 Run 的兼容派生值，不包含新的实时运行投影；新关联且无 Run 的任务为 null，导入保留人工任务进度但绝不启动会话。导入兼容版本 1 和 2；版本 1 的 blocked、in_review 映射到进行中。导入导出均限制为 20 MiB，超限明确失败，不截断数据；支持空备份，无需新增数据库迁移。

• 导入采用增量合并：本地已有相同待办 ID 时整项跳过，文件不会覆盖本地修改。重复导入不会产生副本。
• 仅含旧版运行记录（备份中 executionStatus: "running"）的新增任务转为 pending，清空活动 Run 关联和阻塞原因，对应 Run 以 cancelled 结束，记录中文活动说明。其他任务保留进度；会话关联、旧摘要、历史和归档保留。已有本地待办不受影响。
• 完整校验文件格式、字段和引用后，全部新增记录在一个事务中写入。文件内部重复标识，或新增 Run、Event、Session 标识与其他本地待办冲突时，整个导入失败且不留下部分数据。
• 会话关联不是会话备份。 不包含 DSH 会话正文、附件、插件配置或凭证；原 DSH 会话不存在时，待回复、审核修改和历史对话跳转不能靠此次导入恢复。
• 备份可能含个人信息及任务历史，请妥善保管。Agent 工具交换的是 JSON 内容，不是文件路径；大文件优先使用面板，避免模型上下文或工具输出限制。

typed Remote 提供 exportData({}, signal) 和 importData({ json }, signal)，分别返回 { filename, json } 和 { imported, skipped, resetToPending }。与 Agent 工具共用相同存储校验和事务规则，不在导入时创建会话、发送消息或恢复 Agent 执行。

开发

pnpm install
pnpm run check
pnpm run artifacts:check

pnpm run check 会构建 Host、Typert 和 Web 产物，检查源码与测试类型，执行 lint 和覆盖率测试，并通过 pnpm pack --dry-run 验证包内容。仓库提交构建后的 lib/ 文件，因此可以直接从 GitHub SHA 安装，无需 lifecycle 构建脚本。

许可证

MIT