tako 文档 GitHub

Handoff · 包重命名:taskboard → tasktracker

性质:纯 handoff 文档。不改动任何代码;记录本次命名对话的决策背景、 被否决的候选、影响面清单、以及逐文件的操作步骤,留给后续执行重命名时对照。

触发对话(2026-09-30):用户先问 taskboard.go:L1 有什么用 → 引申到「包名不合理」 → 排查与 eino plantask/Claude Tasks 的概念冲突 → 否决 tasks(概念歧义)、 planning(反三层分离、且与已删除旧包同名)、ledger(联想财务)、 board(联想前端 dashboard)→ 终定 tasktracker。


1. 决策:为什么是 tasktracker

1.1 三层分离约束(硬边界)

三层分离写死在 internal/taskboard/taskboard.go#L5-L6 及 doc/07 §4.1:

层 含义 命名禁区
Plan 给人审的方案(动手前拆步骤) ❌ 不能沾 plan/planning
Tasks 施工期勾选看板(开干后跟踪状态) ✅ 包名必须落在这一层
Actions bash/文件读写等干活工具 ❌ 不能沾 action/exec

1.2 被否决的候选(每次否决都是心智雷区)

候选 否决原因 谁的直觉
taskboard board 会联想到「前端 dashboard / UI 面板」,掩盖「跟踪施工状态」的核心职责 用户(核心否决)
planning 指 Plan 层,直接违背三层分离;且与 2026-09-26 删除的旧 internal/planning 同名,历史混淆 用户+文档
tasks 与 eino plantask、Claude Tasks 概念撞脸,每次读代码要做「哦是第三种 task」的消歧 用户+我们在 §2 一起确认
ledger / account 强联想「财务、钱」,虽然工程界有「事件流水账=ledger」的泛义,但压不过用户的先验语义 用户(核心否决)
dashboard / panel 纯 UI 概念,比 board 更坏 直接排除
kanban 比 board 好(是方法学不是 UI),但中文心智里仍是「看板=墙上那块板」,且用户没提这个词 保留但不推荐
worktrack 弱化了 task 前缀,但对外工具名是 TaskCreate/TaskUpdate(给模型看的),包名 vs 工具前缀拧巴 保留但不推荐

1.3 tasktracker 终定理由


2. 影响面(37 处引用 × 9 文件 × 1 README)

2026-09-30 全仓 grep "taskboard\." 结果(已排除包内注释中「见 taskboard.go」之类的文字性提及, 这些需跟着内部重命名再改)。数字只是参考,以改名时的实际 grep 为准。

2.1 需改 import 路径 + 包名引用

文件 引用形态(示意) 处数
cmd/yktako/main.go import "yk-tako-eino/internal/taskboard"、taskboard.New/NewStore、taskboard.Instruction 4
cmd/yktako/sink_test.go taskboard.ToolList 2
internal/adkrun/event.go import "…/taskboard"、taskboard.IsBoardTool 1+1=2
internal/adkrun/event_test.go taskboard.ToolList(断言 Kind=EventBoard 的用例) 9
internal/adkrun/turn_test.go 注释:「taskboard.IsBoardTool 判定」 1(文字)
internal/webui/server_test.go import、taskboard.New/NewStore/ToolCreate 4
README.md internal/taskboard 路径 + 文字说明 1+(多处文字)

2.2 包内部(目录移动后,import 路径变了,但包内自引用是 包名.符号,

因此把 package taskboard 改成 package tasktracker 后,所有 taskboard. 自引用都要同步改成 tasktracker.)

文件 需改
taskboard.go package taskboard → package tasktracker;文件本身也建议改名成 store.go(见 §3.1)
tools.go package taskboard;第 72 行注释「机制见 taskboard.go 的 SessionKey 注释」→「机制见 store.go」(如果文件也改名了)
middleware.go package taskboard;第 2、44 行注释提「eino plantask 同款」不必改,但提 taskboard.go 文件名的要同步
taskboard_test.go package taskboard → package tasktracker
tools_test.go package taskboard → package tasktracker
middleware_test.go package taskboard → package tasktracker
integration_test.go 外部测试包 package taskboard_test → package tasktracker_test;所有 taskboard. 导出符号引用全部改成 tasktracker.;import 路径改成 …/internal/tasktracker

2.3 可能的连锁:常量 IsBoardTool / EventBoard / SessionKey 值

这些不在本次必须改名范围内,但逻辑上已轻微错位,留待后续决策:

东西 错位点 是否本次改
IsBoardTool(name) bool(tools.go#L29-L36) 判断的是不是「账本/跟踪工具」,但名字还叫 Board ⚠️ 可选,建议改 IsTrackerTool,但要同步 adkrun 的引用
EventBoard EventKind(event.go#L28) 呈现事件四类之一叫 board,其实是「账本投影」 ❌ 本次不改(是呈现层的标签,不是包概念)
SessionKey = "taskboard_session_key_tasks"(taskboard.go#L25) 字符串里还嵌着 taskboard ⚠️ 强建议一起改,否则 grep 代码时永远能搜到 taskboard,且这个 key 是 checkpoint 内部用的(目前 checkpoint 也是内存的,无向后兼容负担)。现在不改以后就成死债
工具名 TaskCreate/TaskUpdate/... 给模型看的外部协议,和 Claude Tasks 对齐 ❌ 绝对不能改 — 这是模型协议层
Instruction 常量(middleware.go#L57-L61) 首行「任务看板约定」文字还是看板说法 ⚠️ 可选,改成「任务跟踪约定」比较顺手

3. 操作步骤清单(留给下次执行时逐条 tick)

3.1 改目录 + 内部文件(最小变更顺序)

3.2 改外部引用(按 §2.1 列表逐文件扫)

3.3 验证(必须全绿才能收尾)

3.4 本 handoff 文档的处理


4. 风险点清单

风险 概率 应对
SessionKey 改字符串后,如果有任何外部 checkpoint 持久化到磁盘(目前 adkrun.Store 是内存的,但将来接磁盘就有),会出现续跑找不到 key 目前极低 现在不改,将来接入磁盘 checkpoint 时就必须带迁移脚本;现在改是最佳时机,0 兼容成本
集成测试 gob 反序列化受影响 极低 gob key 是 SessionKey 字符串,改了后 新 run 用新 key,老 run(内存的进程都结束了)不存在
IsBoardTool 改 IsTrackerTool 时漏改 adkrun 引用 中 用 grep -rn "IsBoardTool" 全仓搜,改完 go build 会报错兜底,不会沉默
注释里「taskboard」文字性残留 高 残留不影响构建,纯美观;允许分批清理,但 SessionKey / import / package 声明必须一次改完
IDE / 其他构建缓存把旧路径留在 .vscode/、.idea/ 等 低 「手动移目录后重新跑 go build ./...」会重建 Go 索引

5. 本次对话的决策摘要(防止将来又绕一圈)

核心分歧:board → 你联想「前端 dashboard」;ledger → 你联想「财务账」; planning → 违背三层分离且踩历史包名;tasks → 与 eino/Claude Task 概念消歧成本高。

收敛标准:命名必须是「软件工程有现成先例」「不占用你的已有语义雷区」「落在 Tasks 层(施工跟踪)」。 满足全部三条的只有 tasktracker(参考 bugtracker/issuetracker 用法)。

对外协议不动:TaskCreate/TaskUpdate/TaskList/TaskGet 四个工具名(给模型的)、 pending/in_progress/completed/deleted 状态值、EventBoard 呈现类别标签—— 这些都不是 Go 包名层面的事,本次不碰。