待办时间日志 · dsh-todo-time-log

待办清单，也是一本时间账本。
一个 DeepSeek Harness（dsh）插件：管理待办的同时，自动记下每条待办的创建时间与完成时间，
用表格 / 看板 / 甘特图 / 日历四种视角，一眼看清「这件事做了多久」。

为什么是它

大多数待办工具回答「还有什么没做」。这个插件还想回答另一个问题：「这件事花了多久？」

• 🕒 时间是一等公民 —— 创建时刻、完成时刻、两者之间的真实耗时全部自动记录；甘特图里一根条，就是一条待办从创建到完成的完整生命周期。
• ⚡ 随手就能记 —— 面板表单、一句话对话、/todo 命令、让智能体直接调用工具，四个入口共用同一套解析规则，结果完全一致。
• 🔒 数据在你自己的机器上 —— 本地 JSON 文件，不联网、不上传；原子写入 + 跨进程写入保护，文件损坏会自动备份并重建。

---

界面速览

四种视图共用同一张数据卡片，切换视图不会丢掉当前的筛选与排序。

_{表格视图：「创建时间 / 完成时间」两列是主角，完成时间未产生时显示 -}

_{看板：按状态分列，卡片带优先级、类型与用时     泳道：状态 × 分类分组，泳道可折叠、可在内新建}

_{甘特图：一根条 = 创建 → 完成，未完成延伸到「现在」并标「进行中」；可按分类分组、切换近 7 / 30 天}

_{日历：按创建或完成时间落格，点某天处理当天全部条目     暗色主题：颜色全部走宿主主题 token，随系统明暗自动切换}

对话录入与完成反馈的交互过程见下方「操作示范」（静态示意图）。配图由仓库里的真实 client.js + 宿主真实主题 token 静态渲染，不是真机截图；生成方式见 docs/images/README.md。

---

操作示范

① 新建一条待办

1. 在顶部输入框写标题，顺手可以打 #工作 指定分类、@lib/store.js 引用工作区文件。
2. 分类、优先级（高 / 中 / 低）、类型（缺陷 / 新功能 / 改进 …）都能直接点选。
3. 按 Enter 或点「添加」。带标记时由 Host 统一解析，标题里不会残留 #分类 / @文件。

② 完成 → 自动记录 → 可撤销

1. 点行内的「完成」（看板里是卡片上的 checkbox），完成时刻自动写入。
2. 底部浮出 toast，「撤销」可以一键退回未完成状态。
3. 表格的「完成时间」列立即出现时间；页面高度不变，视线不被打断。

③ 一句话记多条

1. 打开「对话录入」，先确认工作区 —— @ 文件补全按工作区隔离。
2. 一句话可以写多条，支持 #分类、@文件、!优先级、^类型。
3. 发送后逐条回执；不满意可以整批撤销。

④ 看板上的日常操作

1. 顶部四个分段切换视图：表格 / 看板 / 甘特图 / 日历。
2. 看板支持分组（状态 / 分类 / 状态×分类泳道）、密度、搜索与筛选。
3. 卡片「⋯」里可以移到分类、改优先级 / 类型、编辑、删除。
4. 已完成列默认只显示最近 10 条，可展开查看全部。

---

特性一览

能力	说明
🕒 创建 / 完成时间	全自动记录，本地时间 YYYY-MM-DD HH:mm:ss，未完成显示 -；重复完成、重复取消都会给出明确提示
🗂 四视图	表格 / 看板 / 甘特图 / 日历，同一份数据四种视角；切换视图保留筛选与排序
📊 甘特图	纯前端计算（不新增接口）：条形 = 创建 → 完成，未完成延伸到「现在」，支持全部 / 近 7 天 / 近 30 天
🏷 分类 · 优先级 · 类型	项目分类（可从「已用分类 / 工作区 / 文件夹」建议里选）、高 / 中 / 低优先级、缺陷 / 新功能 / 改进 / 疑问 / 杂项 / 其他
📎 @工作区文件	把待办关联到代码文件；只给文件、不给分类时，自动取文件所在目录作为分类
✍️ 四种录入	面板表单、对话式一句话（新任务 写周报 #工作）、/todo 斜杠命令、智能体工具 todo_time_log
🤖 智能体工具	智能体可 list / get / create / complete / uncomplete / update / delete / health，与 UI 共用同一实现
🔒 本地数据	<DSH_PROFILE_DIR 或 ~/.dsh>/todo-time-log/todos.json；临时文件 + rename 原子替换、写入串行化、跨进程文件锁
🌗 主题与无障碍	全部颜色走 --dsw-alias-* token，明暗主题自适应；aria-live、aria-sort、键盘操作、减少动效偏好
⌨️ 面板快捷键	/ 聚焦搜索、n 聚焦新建、f 循环切换筛选

---

安装

要求：DeepSeek Harness >= 0.2.0-rc.2 < 0.2.3-0（engines.dsh 声明，已在 0.2.2-rc.1 真机验证），Node.js ≥ 20。

方式一：插件管理器

在 DSH 的**插件管理（Plugin Manager）**里安装 bundle，包名填：

dsh-todo-time-log

也可以直接让当前会话的智能体执行：

plugin_manager action=install_bundle target=dsh-todo-time-log

安装成功后：左侧导航出现「待办时间日志」入口，中央面板可打开；Plugin Manager 中能看到中文名称、描述与图标。

安装会执行包安装（pnpm）、写入 dsh.bundle.patch 声明的 Host 行并启用 bundle；返回 application: "applied" 才算真正生效。Host 半改动需要关闭再开启插件（或重启桌面端）才会加载新模块，Client 半（dsh.client.immediately）随下一次页面刷新加载。

方式二：本地开发安装（link 方式）

plugin_manager action=install_bundle target=<本地仓库绝对路径>

修改 lib/*.js 后需在 Plugin Manager 里关闭再开启该插件（或重启桌面端）才会加载新的 Host 模块；UI 改动刷新页面即可。

卸载：plugin_manager action=remove_bundle target=dsh-todo-time-log。数据文件会保留，手动删除 todos.json 即可清空。

配置

来源	优先级	示例
cordis.patch.yml 行配置 config.dataFile	最高	config: { dataFile: 'D:/data/todos.json' }
环境变量 DSH_TODO_TIME_LOG_DATA	中	DSH_TODO_TIME_LOG_DATA=D:\data\todos.json
默认	最低	<DSH_PROFILE_DIR 或 ~/.dsh>/todo-time-log/todos.json

相对路径解析到配置目录下。当前构建未导出 Config schema，插件详情页没有配置表单，请用上面两种外部方式配置（原因见 docs/limitations.md）。

---

用法

四种录入方式

入口	怎么用	适合
面板表单	顶部输入框 + 分类 / 优先级 / 类型选择器，Enter 创建	手动逐条记录
对话式录入	面板右上「对话录入」，一句话写多条，逐条回执 + 撤销	一次记一堆
/todo 命令	Harness 主输入框：/todo 写周报 #工作 lib/store.js	不离开对话流
智能体工具	让模型调用 todo_time_log（create / complete / list …）	让 AI 代记、代查

快捷标记（三处输入通用）

新任务 写周报 #工作 @src/auth/login.ts
修复登录缺陷 #工作 !high ^bug
买牛奶 @生活；回邮件 [工作]
项目：学习 整理笔记，读完第三章

标记	写法	说明
分类	#工作 / @生活 / [工作] / 项目：工作 / 分类：工作	取最左的非空值，并从标题里剥离
优先级	!high / !medium / !low（!h !m !l、!高 !中 !低）	未写则回退到表单选择器
类型	^bug / ^feature / ^improvement / ^question / ^chore / ^other（中文 ^缺陷 / ^新功能 …，也支持 类型：bug / type:bug）	未知值保留原文
文件	@路径/文件、@"docs/My File.md"	记为工作区相对路径；没有显式分类时自动取文件所在目录
多条	换行、；、; 分隔	只有填充词的行会被跳过，不会创建空待办

解析实现只有一份（lib/parse.js 的 parseQuickAdd()），面板、/todo 命令与工具 quick_add 共用，不存在两边规则漂移。

智能体工具 / HTTP

todo_time_log { "action": "create", "title": "修复登录", "priority": "high", "type": "bug" }
todo_time_log { "action": "list", "filter": "pending", "sortBy": "priority", "direction": "asc" }
todo_time_log { "action": "complete", "id": "ttl_…" }

# 需要携带 DSH 登录态（未登录 401、跨站/不可信来源 403）
curl -s http://127.0.0.1:<port>/api/dsh-todo-time-log/health

HTTP 接口与智能体工具共用同一个业务实现（executeTodoAction），因此不存在「UI 能做的工具做不到」的情况；接口经宿主认证，未登录返回 401、跨站/不可信来源返回 403。

---

数据与安全

• 本地优先：数据只存在本地 JSON 文件，不联网、不上传、不触发模型调用。
• 写入可靠：临时文件 + rename 原子替换；全部写操作串行化；跨进程写入用文件锁 + mtime 合并，避免多窗口互相覆盖。
• 损坏自愈：JSON 损坏 / 结构异常 / 版本不支持会分别归档备份，然后重建空列表并给出提示；修复与异常提示只投递一次，不刷屏。
• 版本迁移：v1 → v5 全部自动迁移，下一次写入即落盘新版本。
• 接口边界：/files、/quick-add 只接受 /workspaces 返回的候选工作区；文件引用只接受工作区相对路径，绝对路径、盘符、.. 一律拒绝。

兼容性

项	值
插件 ID / 包名	dsh-todo-time-log（dsh 不加命名空间前缀，与官方插件一致；短别名 todo-time-log / ttl）
DSH	>=0.2.0-rc.2 <0.2.3-0（已实测 0.2.2-rc.1）
Node.js	≥ 20
数据版本	version: 5（旧版本自动迁移）
HTTP 接口	POST /api/dsh-todo-time-log/*（经宿主认证：无登录态 401、跨站/不可信来源 403）
安装位置	中央面板 main + 侧边栏 sidebar.panellist

兼容性门禁：DSH 在 profile 启动时按已安装版本的 engines.dsh 做 preflight，不满足的插件会被禁用，并在 Plugin Manager 里显示 incompatible-version。升级 DSH 后若遇到该提示，安装声明范围覆盖新版本的插件版本即可。

开发

npm install
npm run build      # esbuild：src/client/ → lib/client.js
npm test           # 342 个用例：解析 / 数据层 / HTTP（含宿主认证）/ UI 渲染 / 并发写入
npm run verify     # check + lint + typecheck + build + test + audit（发布前必跑）

• Client 源码在 src/client/（ES 模块），构建产物 lib/client.js 是单文件模块表，不要手改。
• CI 跑 Node 20 / 22 / 24 × Ubuntu / Windows，并在 Linux job 校验构建产物与源码同步。
• 详细说明：docs/development.md。

文档

文档	内容
docs/architecture.md	目录结构、数据模型、Host / Client 架构、四视图与界面层级、toast 实现
docs/development.md	测试矩阵、手工验证清单、发布流程
docs/limitations.md	已知限制与 TODO（配置 schema、时区、启发式解析等）
docs/verification.md	独立第三方 QA 验证报告（PASS / FAIL / 盲区）
docs/verification-log.md	本机分阶段验证记录（含九期 DSH 0.2.2 兼容性证据）
docs/publishing.md	npm 发布流程、OIDC 可信发布、排错
docs/preview/	更多渲染预览（空态 / 骨架屏 / 错误态 / 各种看板状态）

License

MIT © FantasyStarry

---

In English — A todo plugin for DeepSeek Harness that records and shows each todo's created and completed time. Four views (table / board / Gantt / calendar) where every Gantt bar is the real created→completed lifetime; project categories, priority, type, @workspace-file references, a /todo slash command with natural-language capture, and a todo_time_log agent tool. All data stays in a local JSON file.