trekker

Trekker

概述

Trekker 是一款面向 AI 编码 Agent 的命令行问题跟踪器。它使用 SQLite 在本地存储数据（.trekker/trekker.db），并支持 Epic、任务、子任务、依赖关系、评论、全文搜索和审计历史日志。任何命令都可以使用 --toon 输出更节省 Token 的内容。

适用场景： Agent 工作会话跟踪、本地任务管理、看板式工作流、依赖感知的任务排序、用于在不同会话间保留上下文的检查点评论。

不适用场景： 团队级项目管理（请使用 GitHub Issues/Linear）、实时协作、以远程为主的工作流、与 CI/CD 集成的问题跟踪。

基本命令

trekker init
trekker --toon ready
trekker --toon task list --status in_progress
trekker --toon task list --status todo
trekker --toon task list --epic EPIC-1
trekker --toon task show TREK-1
trekker --toon epic list
trekker --toon epic show EPIC-1
trekker --toon comment list TREK-1
trekker --toon search "query" --type task
trekker --toon list --status in_progress
trekker --toon history --entity TREK-1
trekker epic create -t "Title" -d "description" -p 2
trekker task create -t "Title" -d "description" -e EPIC-1 -p 2 --tags "a,b"
trekker subtask create TREK-1 -t "Title" -d "description" -p 2
trekker task update TREK-1 -s in_progress
trekker task update TREK-1 -s completed
trekker epic complete EPIC-1
trekker dep add TREK-2 TREK-1
trekker comment add TREK-1 -a "agent" -c "Summary: what was done and which files changed"

状态 — 任务/子任务：todo、in_progress、completed、wont_fix、archived | Epic：todo、in_progress、completed、archived

优先级 — 0 紧急，1 高，2 中（默认），3 低，4 待办，5 以后处理

各命令支持的有效标志

只使用此处列出的标志。切勿猜测或编造标志。

命令	有效标志
epic create	-t -d -p -s
epic list	--status
epic update	-t -d -p -s
epic show/complete/delete	（无标志，仅需 ID）
task create	-t -d -p -s -e --tags
task list	--status --epic
task update	-t -d -p -s -e --tags --no-epic
task show/delete	（无标志，仅需 ID）
subtask create	-t -d -p -s
subtask update	-t -d -p -s
subtask list/delete	（无标志，仅需 ID）
comment add	-a -c（两者均必需）
comment update	-c
comment list/delete	（无标志，仅需 ID）
dep add/remove	（无标志，需提供两个 ID）
dep list	（无标志，仅需 ID）
search	--type --status --limit --page --rebuild-index
history	--entity --type --action --since --until --limit --page
list	--type --status --priority --since --until --sort --limit --page
ready	（无标志）
wipe	-y

不存在的标志（Agent 经常会臆造这些标志）：

• --offset — 请改用 --page 和 --limit
• --assignee — trekker 没有 assignee 字段
• --label — 请在 task create/update 中改用 --tags
• --verbose / --json / --quiet — 请使用 --toon 输出精简内容；默认输出详细信息
• --filter — 请分别使用 --status、--type、--priority 标志
• task list 不支持 --sort — 仅 trekker list 支持
• --all — 所有命令都不支持此标志
• --force / -f — 只有 wipe 支持 -y
• --name / -n — 请改用 -t / --title

不确定标志时，请对任意命令运行 --help：

trekker --help
trekker task --help
trekker task create --help

常见错误

错误	正确做法
创建任务前未先搜索	创建前始终运行 trekker search "keyword"，以避免重复
完成任务时未添加摘要评论	添加 Summary: 评论，说明完成的工作以及哪些文件有更改
未使用 --toon 标志	始终使用 --toon，以减少 Agent 场景中的令牌用量
开始工作前忘记将状态设为 in_progress	开始前设置状态，让其他 Agent 知道该任务已被认领
使用 epic delete 而不是 epic complete	epic delete 会悄悄使任务变成孤立任务；使用 epic complete 将其归档
依赖方向反了	dep add TREK-2 TREK-1 表示 TREK-2 依赖 TREK-1（TREK-1 阻塞 TREK-2）
重置上下文前未添加检查点评论	添加 Checkpoint: 评论，列出已完成事项、后续步骤和受影响的文件
规划前就开始编码	编写代码前创建 epic，并将其拆分为带依赖关系的任务
任务描述含糊	包含实现步骤、要修改的文件和验收标准
搜索时未筛选类型	使用 --type task 或 --status in_progress 缩小搜索范围
搜索查询为空 trekker search ""	FTS5 不接受空字符串；始终提供搜索词
任务只是延期，却使用 wont_fix	wont_fix 表示永远不会处理；对于延期或被取代的工作，请使用 archived
comment add 缺少 -a 或 -c	-a（作者）和 -c（内容）都是必需参数
重复运行 trekker init	该命令不是幂等的；如果 .trekker/ 已存在，就会报错
忘记将 .trekker/ 加入 gitignore	初始化后将 .trekker/ 添加到 .gitignore，除非要共享任务状态

委派

• 任务发现与优先级排序：使用 Explore Agent 扫描代码库并识别工作
• 多任务执行：使用 Task Agent 并行完成子任务

参考

• Agent 工作流与会话管理
• 命令与 CLI 用法