面向科研工作的日常操作手册 · 通用版（示例已脱敏）
面向科研工作的日常操作手册 · 不含安装步骤（假设服务已经跑起来） 适用于本工具包装好的「本机任务看板 + 邮件双向桥」组合
一句话：把「脑子里记着的待办」变成能跨会话、跨设备、可验收的任务账本 —— 早上收到一封清单，白天干活，完成时回一封邮件就勾掉。不需要打开电脑上的任何界面。
同类工具很多，但为「agent 干活」而不是「人看板」设计的很少。下表把差别摊开， 并标注每项能力的来源 —— 「本工具包扩展」是随本仓库一起装的，不是上游自带。 最后一列给出现场验证方式，优点必须能被证伪，否则就是营销。
| 能力 | 来源 | 说明 | 怎么现场验证 |
|---|---|---|---|
| 跨会话持久化 | 上游 | agent 的内置任务列表会话一结束就消失；这里存在本机 SQLite，下周还在 | 重启会话后 issue list 仍能读到 |
| 工作目录自动归属 | 上游 | 在哪个目录干活，任务就记到哪个项目（按最长路径匹配），不用每次手选 | 在不同目录跑 context current，看 project 变化 |
| 并发安全的任务认领 | 上游 | 每条任务带版本号，写入必须带 --if-version；冲突返回退出码 5。两个 agent 不会抢同一条、也不会互相覆盖 |
用过期版本号写入，观察退出码 5 |
| 「干完等人验收」是内置状态 | 上游 | in_review 专为「做完了、等你确认」而设计；且规则明确 agent 不得自己标 done |
看状态选项里有 in_review；agent 会停下来问你 |
| 手机回邮件即回写 | 本工具包扩展 | 在微信「服务通知」里回复那封清单邮件，任务就勾掉了。不需要装 App、不需要公网入口、成本 ¥0 | 跑 send-test.cmd 再回一封 ping |
| 多视图 + 甘特时间线 | 上游 | 仪表盘 / 议题看板 / 列表 / 时间线 / 项目说明 五种视图；时间线支持日·周·月、隐藏已完成、跳到今天 | 打开时间线视图切「月」 |
| 任务挂在分支 / worktree 上 | 上游 | 一条任务可绑定一个 Git 分支或一个 worktree，干完自动关联 | 详情页「开发上下文」字段 |
| 全 JSON、可脚本化 | 上游 | CLI 每条命令输出一个带 schemaVersion 的 JSON；退出码语义化（0/2/3/4/5） |
issue list --json |
| 数据在本机、无账号 | 上游 | SQLite 单文件，断网可用，不注册、不遥测 | 断网后刷新页面仍正常 |
| 开机自启 + 一键只读自检 | 本工具包扩展 | 登录自动起服务；一条命令做十几项体检并给退出码 | 双击 selfcheck-taskboard.cmd |
| 手机 / 外网访问 | 本工具包扩展 | 经 Tailscale 反代出 HTTPS，服务本身始终只绑回环，绝不暴露到局域网 | 用手机打开自己的 https://<机器名>.<tailnet>.ts.net |
该不该用它，三条判断：
in_review，让 agent 停下来等你。诚实清单。缺了这张表，上面的优点就是营销。
| 做不到 | 原因 / 现状 | 变通 |
|---|---|---|
| 没有依赖关系可视化图 | 上游只存关系数据，甘特图里只能 hover 高亮 | 用 issue tree 看层级；关系在详情页右栏看 |
| 没有「分配给我」视图 | 无 assignee 聚合页，负责人只能在详情页改 | 用筛选（F）+ 搜索 |
| 不能批量选择操作 | 无多选 | 逐条拖拽，或走 CLI 脚本批量改 |
| 筛选维度有限 | 只有状态 / 优先级 / 标签；没有日期、没有负责人筛选 | URL 参数可拼 status/priority/label/linked/content/project/issue |
| 无云端同步 | 本地优先；多人协作要自己部署 Cloudflare Worker + D1 | 单机够用；多设备靠 Tailscale 访问同一个服务 |
| AI 相关功能不可用 | 本工具包把服务装到了非 Codex 宿主上，没有 Codex 运行时 → AI 聊天、AI 项目摘要、会话进度、侧边栏注入、托盘启动器均不可用 | 不受影响：任务/评论/附件/关系读写全部正常 |
| 演示项目可能删不掉 | 服务端无 PATCH 路由，且删除对非 temp- 前缀的项目抛 403；含任务也算门槛 |
它对功能零影响，保持原样即可 |
⚠️ 一个必须记住的前提：backlog 不等于「可以做」。backlog 是「还没批准执行」，
只有你明确授权了，agent 才会动它。这条是上游工作流协议的硬规则。
| 科研场景 | 怎么用这个面板 |
|---|---|
| 计算 / 建模类（跑脚本、调参、做评估） | 把「跑通脚本」升级成可验收的产出：不是「做实验」，而是「N 种算法各自的指标表 + 交叉验证设置说明」 |
| 论文写作类（前言/方法/结果/讨论） | 用父子结构：父议题 = 论文，子任务 = 每个章节/每张图/每次分析 |
| 结果整理类（显著性表、汇总图） | 把验收标准写进任务名，例如「整理 FDR 显著与名义显著的结果表」——这比「整理结果」清楚得多 |
| 文献阅读类（本地 Wiki、批量精读） | 用标签区分阶段；论文阅读适合「当天可闭环」的小粒度，别攒成一个大任务 |
一个通用建议：任务粒度当天可闭环是最省心的起点。 等你习惯了，再补上父子结构（把散落的子任务挂到主线父议题下）， 这样时间线视图才能真正看出「这条主线推进到哪了」。
| 状态 | 含义 | 谁能改 |
|---|---|---|
| backlog | 还没批准执行。它只是「记下来」，不是「可以做」 | 只有你授权后才进 todo |
| todo | 已批准，等人认领 | agent 可以认领 |
| in_progress | 正在做 | 认领者 |
| in_review | 做完了，等你验收 —— 这是给你留的检查点 | agent 干完自动移到这里 |
| blocked | 卡住了，等外部条件 | 认领者，需写清阻塞源 |
| done | 已验收完成 | 只有你确认后才能到这里 |
| canceled | 决定不做了 | 保留记录，不删除 |
流转关系：
backlog ──你授权──▶ todo ──认领──▶ in_progress ──干完──▶ in_review ──你验收──▶ done
│ │
├──▶ blocked └──▶ （打回 → in_progress）
└──▶ canceled
两个关键点：①
in_review是给你的，不是给 agent 的 —— 看到它就该去验收； ② agent 不得自己把任务标成done，必须你说「这个可以了」。这是制度，不是礼貌。
判据：一条任务应该能在一个 1–2 小时的专注块内推进到「能判定成不成」的状态。
| 写法 | 评价 |
|---|---|
❌ 做实验 |
是动词，没有完成标准 |
❌ 推进论文 |
太大，永远做不完，会一直挂在 in_progress |
✅ 跑通 N 种算法的交叉验证脚本 |
有明确产出（脚本能跑通），可判定 |
✅ 整理 FDR 显著与名义显著的结果表 |
产出是「一张表」，验收标准写进了标题 |
✅ 补写知识图谱方法学章节 |
产出是「一个章节」 |
超出 1–2 小时的，拆父子，别硬塞。
父议题（主线） 论文 A
├── 子任务 补写方法学章节 ← 可验收产出
├── 子任务 整理论文 Figure 2 的汇总表
└── 子任务 回复审稿人第 3 条意见
└── 评论 「今天试了 X，跑出来不对，原因是 Y」 ← 过程记录，别开新任务
最常见的误用：把「过程中的每一步」都开成任务。正确做法是—— 状态变化才动任务，过程写评论。
标签的价值在于长期稳定，不在于多。建议固定一组：
| 标签 | 用途 |
|---|---|
phase-1 … phase-6 |
论文/实验的推进阶段。这是最有价值的一组 —— 时间线视图配合它能看出节奏 |
for-agent |
标记这条是交给 agent 干的 |
hold |
暂时挂起 |
缺陷 / 特性 / 改进 |
留给工具链本身的问题 |
[任务面板] 的清单邮件。in_progress。这是你的 WIP 上限 —— 同时开五条，等于五条都推不动。poll-once.cmd 补一次。in_review。| 入口 | 地址 / 方式 |
|---|---|
| 本机浏览器 | http://127.0.0.1:47823 |
| 手机 | 自己的 https://<机器名>.<tailnet>.ts.net |
| 直接跟 agent 说 | 「把 XX 记到 <你的项目 id>」 |
手机走域名时，
/api/local/*会返回 409 —— 这是设计如此（环回专属端点不对外），不是故障。
c1 c2 或 1和2完成 —— 勾掉今天完成的。复盘 今天…… —— 会存成 state\review-日期.md。blocked 并写清在等什么（等数据、等审稿意见、等仪器）。phase-* 标签看主线的推进节奏。in_progress 的任务 —— 有的话要么拆小，要么降回 todo。粒度：一个可交付段落或一张图 = 一条任务。
父议题：论文 A
├── 补写方法学章节 ← in_review 后你读一遍再 done
├── 整理 Figure 2 的汇总表
└── 写 Discussion 第 2 段
要点：写作任务的 in_review 特别有用 —— agent 写完你看一眼，不满意就打回 in_progress 并写评论说明哪里要改，比重新口述一遍更省事。
粒度：一次可交付的计算或一次实验运行 = 一条任务。
父议题：主线 A
├── 跑通 N 种算法的交叉验证脚本
├── 输出各算法指标对比表
└── 排查某算法在特定划分下的异常
要点：
- 用 --git-branch 或 --worktree-path 把任务绑到分支，干完自动关联，不用事后回忆「那版代码在哪」。
- 结果表、图这类交付物直接作为附件上传（上限 25 MB），比在聊天里传来传去好找。
粒度：一次投稿动作 = 一条任务，用 due-date 记 deadline。
├── 提交稿件到目标期刊 due-date: 2026-10-01
├── 整理审稿人要求的补充结果表
└── 每周组会材料 recurrence: 每 1 周
要点：
- recurrence 记周期性事项 —— 组会材料、周报这类，设一次就不用再记。
- 投稿前的集中火力期，适合把一批任务一起推进 in_review，一次性验收。
本工具包会一并安装 manage-taskboard skill，agent 可以直接读写看板。
这是效率杠杆最大的一节 —— 你不用自己敲命令。
| 你说 | agent 会做 |
|---|---|
「把 XX 记到 <项目 id>，优先级 high」 |
创建任务 |
| 「现在有哪些没做的？」 | 列出 todo |
| 「这条我来做，标记开始」 | 认领：todo → in_progress（含完整绑定） |
| 「这条干完了，写个评论」 | 追加评论 |
| 「这条可以了」 | in_review → done（只有你说了才可以） |
| 「XX 卡住了，在等数据」 | 移到 blocked 并写清阻塞源 |
| 项 | 情况 |
|---|---|
写操作必须显式传 --thread-id |
非 Codex 宿主没有 CODEX_THREAD_ID 环境变量，所有写操作都要带上会话 ID，否则报 Codex conversation attribution requires --thread-id |
| 绑定参数必须成对 | --binding-codex-project-kind local 必须配 --binding-codex-host-id local；写成别的值会直接失败 |
只传 --thread-id 会留 legacy 绑定 |
认领/继续任务时应补齐 5 个 --binding-*，补齐后旧的 legacy 字段会被清空 |
| 部分功能不可用 | AI 聊天、AI 项目摘要、Codex 会话进度、侧边栏注入、托盘启动器 —— 因为没有 Codex 运行时。核心读写不受影响 |
backlog 门禁：backlog 里的任务，agent 不会自己认领 —— 它只是你的备忘录区。done 门禁：agent 干完只能移到 in_review，永远不会自己标 done。这两条把「agent 自称做完」和「真的做完」彻底分开了。你只需要盯 in_review 这一列。
Ctrl+Z 可撤销。C 新建、/ 搜索、F 筛选、Esc 关闭、详情页 R 聚焦评论、Ctrl+Enter 提交评论。inline 会嵌在正文里，用 attachment 则进附件列表。status/priority/label/project 等），存成书签就是「保存的视图」。Markdown 支持表格、任务列表；
mermaid代码块会渲染成只读流程图（失败时回退显示源码）。
# 1. 今天有什么（列出未完成）
taskctl issue list --status todo --json
# 2. 含已归档的全量列表（UI 里做不了）
taskctl issue list --archived all --json
# 3. 看一条任务的层级结构（父/子，UI 里没有树视图）
taskctl issue tree <PREFIX>-1 --direction descendants --depth 2 --json
# 4. 增量读评论（只取新评论，省上下文 —— 同一条任务反复跟进时非常有用）
taskctl comment list <PREFIX>-1 --after <上次返回的 nextCursor> --json
# 5. 建任务
taskctl issue create --project <项目 id> --title "标题" --status todo --priority high --json
# 6. 当前目录归属哪个项目
taskctl context current --json
退出码：
0成功 ·2用法错 ·3服务不可达（先跑start-taskboard.cmd）·4响应错误 ·5版本冲突（读最新版再重试）。
只有命令能做、界面做不了的：层级树 · 目录映射 · 附件批量导出 ·
archived 三态筛选 · 评论游标增量读 · 显式 --if-version。
taskctl的具体调用方式（包装脚本位置、固定路径写法）见 local-layout.md。
⚠️ 必须用邮件客户端的「回复」功能（这样主题才带
Re:）。绝不在企业微信群里回复 —— 那是单向通道，收不到任何东西。 未安装邮件桥时本节可跳过。
| 你写 | 效果 |
|---|---|
c1 c2 / done 1、2 |
标记第 1、2 项完成 |
把1、2项标记为已完成 |
同上（自然语言） |
1和2完成 / 第1项做完了 |
同上 |
done <PREFIX>-1 |
直接用编号标记完成 |
r1 新的标题 |
把第 1 项标题换成新内容 |
+ 补充材料 S2 |
追加一条新任务 |
复盘 今天…… |
写当日复盘 |
ping |
只测链路，不动作 |
三条铁律：
r1）、加任务（+）必须用严格语法 —— 宁可漏执行，也不误执行。r1 会报「找不到对应任务」，收到清单后尽快回复。| 键 | 作用 |
|---|---|
C |
新建任务 |
/ |
搜索 |
F |
筛选菜单 |
Esc |
关闭弹层 |
Ctrl+Z |
撤销 |
R（详情页） |
聚焦评论框 |
Ctrl+Enter |
提交评论 |
| 状态 | 一句话 |
|---|---|
| backlog | 记下来，但还没批准做 |
| todo | 可以做，等人认领 |
| in_progress | 正在做 |
| in_review | 做完了，等我验收 |
| blocked | 卡住了，在等外部条件 |
| done | 已验收 |
| canceled | 不做了（保留记录） |
优先级：urgent > high > medium > low > none
| 命令 | 用途 |
|---|---|
selfcheck-taskboard.cmd |
出问题先跑它（只读，十几项体检） |
status-taskboard.cmd |
服务在不在 |
stop-taskboard.cmd |
停服务 |
send-daily.cmd |
立刻再发一封清单 |
poll-once.cmd |
立刻处理邮件回复 |
自检退出码：0 正常 · 1 服务不健康 · 2 本次登录未执行自启 · 3 无法判定 · 10 配置或文件问题（优先级最高）。
一个静默失败模式：如果哪天「邮件照发、微信却毫无提醒」，几乎一定是微信侧的 「QQ邮箱提醒」出了问题（开关被关 / 绑定失效 / 装了 QQ邮箱 App 并开了「仅在客户端提醒」）。 上行链路是静默的，不会有任何报错。详见 mail-bridge.md。