前言¶
做智能体应用时，待办工具回答的是「还有什么没做」。用户真正关心的往往是另一个问题：这条待办从建到完花了多久。dsh-todo-time-log 做的是把待办和耗时合并成一件事：管理待办的同时自动记录创建时间与完成时间，再用表格、看板、甘特图、日历四种视图呈现真实耗时。
下面介绍这个插件。它是 FantasyStarry 维护的 DeepSeek Harness（DSH）插件，分类是工作流，许可证为 MIT，npm 包名 dsh-todo-time-log。已有的待办方案多停留在清单层面，要么只有时间字段却缺少视图组织，要么视图齐全但不记录完成时刻。它把「记账」和「看账」接在一起，数据存在本地 JSON 文件，不联网、不上传。
一、核心能力¶
时间记录是默认行为，不是配置项。每条待办写入创建时刻（本地时间 YYYY-MM-DD HH:mm:ss），完成时自动写入完成时刻，未经完成就显示 -。重复完成、重复取消会给出明确提示。表格的「完成时间」列直接给出「用时 / 进行中」两行，未完成的条目同时显示已耗时与「进行中」标记。
四种视图共用同一份数据卡片，切换视图保留当前筛选与排序，排序统一走表头：
- 表格：创建时间、完成时间两列是主角。
- 看板：按状态分列，卡片带优先级、类型与用时；支持按状态、分类或状态×分类泳道分组，泳道可折叠、可在里面新建。
- 甘特图：一根条 = 创建 → 完成，未完成的条目延伸到「现在」；支持按分类分组，可切换全部 / 近 7 天 / 近 30 天。甘特图是纯前端计算，不新增接口。
- 日历：按创建或完成时间落格，点某天处理当天全部条目。
每条待办还可以带分类、优先级（高 / 中 / 低）、类型（缺陷 / 新功能 / 改进 / 疑问 / 杂项 / 其他）；用 @工作区文件 关联代码文件时，如果没有显式分类，会自动取文件所在目录作为分类。
二、四种录入入口¶
面板表单、对话式一句话、/todo 斜杠命令、智能体工具 todo_time_log 四个入口共用同一套解析规则（lib/parse.js 的 parseQuickAdd()），不存在两边规则漂移。
标记语法三处通用：
新任务 写周报 #工作 @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"，记为工作区相对路径。 - 多条：换行、
；、;分隔；只有填充词的行会被跳过，不会创建空待办。
智能体工具挂在 todo_time_log 上，支持 list / get / create / complete / uncomplete / update / delete / health，与 UI 共用同一实现：
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_PROFILE_DIR 或 ~/.dsh>/todo-time-log/todos.json，用临时文件 + rename 原子替换、写入串行化、跨进程文件锁保护；文件损坏时自动备份并重建。页头「数据」菜单提供 JSON 无损备份与 CSV 导出（给 Excel 统计）；导入先预览再写入，支持合并 / 仅新增 / 覆盖全部，自动备份并可直接撤销。面板快捷键：/ 聚焦搜索、n 聚焦新建、f 循环切换筛选。
三、安装与启用¶
要求：DeepSeek Harness >= 0.2.0-rc.2 < 0.2.3-0（engines.dsh 声明，已在 0.2.2-rc.1 真机验证），Node.js ≥ 20。
在插件管理器（Plugin Manager）里安装 bundle，包名填 dsh-todo-time-log。也可以让当前会话的智能体执行安装：
plugin_manager action=install_bundle target=dsh-todo-time-log
安装会执行包安装（pnpm）、写入 dsh.bundle.patch 声明的 Host 行并启用 bundle。只有返回 application: "applied" 才算真正生效。Host 半改动需要关闭再开启插件（或重启桌面端）才会加载新模块；Client 半（dsh.client.immediately）随下一次页面刷新加载。安装成功后，左侧导航出现「待办时间日志」入口，Plugin Manager 中能看到中文名称、描述与图标。
本地开发用 link 方式安装，target 换成本地仓库绝对路径；修改 lib/*.js 后同样需要关闭再开启插件（或重启桌面端）加载新的 Host 模块，UI 改动刷新页面即可。卸载：
plugin_manager action=remove_bundle target=dsh-todo-time-log
卸载后数据文件保留，手动删除 todos.json 即可清空。
配置数据文件路径有两条外部途径，当前构建未导出 Config schema，插件详情页没有配置表单，所以只能走这两种方式：
# cordis.patch.yml 行配置（优先级最高），写入 plugin 的 config
config: { dataFile: 'D:/data/todos.json' }
# 环境变量 DSH_TODO_TIME_LOG_DATA（优先级次之）
export DSH_TODO_TIME_LOG_DATA=D:\data\todos.json
两者都不设时使用默认路径。相对路径解析到配置目录下。具体限制原因见仓库 docs/limitations.md。
四、典型用法¶
- 在面板顶部输入框写标题，顺手打
#工作指定分类、@lib/store.js引用工作区文件；分类、优先级、类型可直接点选。按 Enter 或点「添加」，带标记时由 Host 统一解析，标题里不会残留#分类/@文件。 - 点行首的勾选圈（看板里是卡片上的勾选框）完成待办，完成时刻自动写入，底部浮出 toast；「撤销」可以一键退回未完成状态，「完成时间」列立即出现时间。
- 需要一次记多条时，点新建框右侧的「批量」进入对话式录入，先确认工作区（
@文件补全按工作区隔离），一句话写多条，发送后逐条回执，不满意可整批撤销。 - 不想离开对话流时用斜杠命令，在 Harness 主输入框写：
/todo 写周报 #工作 lib/store.js
- 想让模型代记、代查时调用智能体工具
todo_time_log，参数与面板表单同源，action 覆盖增删改查与健康检查。
五、适用场景与注意事项¶
适合把 DSH 当工作台、希望待办清单同时是一份时间记录的人，尤其是需要让智能体按规则代记待办、再回头用甘特图或日历复盘耗时的场景。
需要注意几点。安装前应检查源码与许可证（仓库为 MIT，LICENSE 在根目录），并以当前 DSH 进程权限运行插件。它不是独立应用，必须先有可用的 DeepSeek Harness，版本需满足 engines.dsh 约束。插件详情页目前没有配置表单，数据文件路径要用 cordis.patch.yml 或环境变量指定。所有数据都在本地，不联网、不上传。
六、小结¶
这个插件的价值在于把「待办清单」和「时间账本」合成一个界面：录入入口多但不分裂，四种视图共享一份解析和数据，完成动作即记账，撤销和导入导出都带上了。如果你是 DSH 用户，待办又恰好需要回答「做了多久」，可以从这里入手。
- 目录页：https://www.skillhub.cn/plugins/FantasyStarry/dsh-todo-time-log
- GitHub：https://github.com/FantasyStarry/dsh-todo-time-log
- npm：https://www.npmjs.com/package/dsh-todo-time-log
