BattlePlan 是做什么的?
从任务跟踪器中读取所有未完成任务,将其与上次规划之后实际发生的情况进行核对,然后转化为一个简短的并行工作线程列表,每个线程都包含一个启动提示,使得全新的代理会话可以无冷启动地接手。
第 0 步 — 每次调用从这里开始
BP="${SKILLS_HOME:-$HOME/.claude/skills}/BattlePlan/Tools"
uv run --script "$BP/setup_tracker.py" check
success: false或没有配置 → 首先运行 Workflows/Setup.md。禁止自行发明跟踪器、标签页名称或上下文。- 配置存储在
$BATTLEPLAN_CONFIG中,否则为${AGENT_SKILLS_CONFIG:-~/.config/agent-skills}/BattlePlan/config.json。配置包含所有者、跟踪器后端、计划目录和上下文层级。技能目录绝不包含个人数据,因此可以自由共享和更新。
路由
| 调用方式 | 工作流 |
|---|---|
| “设置 battleplan”、无配置、新跟踪器、新上下文 | Workflows/Setup.md |
/BattlePlan [context] [--mine] [--skip-audit] [--launch]、--audit | Workflows/Plan.md |
/BattlePlan --close | Workflows/Close.md |
/BattlePlan --draft(无人值守)、调度草稿 | Workflows/Draft.md |
--add、--done、--cancel、--restore、--sweep、batch-add、从工单或会议中导入任务 | Workflows/Tasks.md |
日循环
傍晚 定时(工作日) 早晨
/BattlePlan --close ──▶ /BattlePlan --draft ──▶ /BattlePlan
完成,每个线程的下一步, 读取跟踪器 + 交接文件 + 打开草稿;你只需
恢复命令 会话;写入一份草稿 确认异常,然后继续
当上一步被跳过时,每一步仍可独立工作:无交接文件 → 回顾会回退到上一个工作日;无草稿 → /BattlePlan 实时构建计划。文件存储在 plans_dir 中:
| 文件 | 由谁写入 | 内容 |
|---|---|---|
YYYY-MM-DD-handoff-<host>.md | --close | 第一行 Closed: <带偏移的ISO 8601时间> on <host>,接着是已完成项、进行中项(下一步 + 恢复命令)、延续项 |
YYYY-MM-DD-draft-<host>.md | --draft | 计划及预填的审计提案;不向跟踪器写入任何内容 |
YYYY-MM-DD-plan.md | /BattlePlan | 确认后的计划,以便 --close 可以将计划与实际情况对比 |
<host> 是一个别名(mac、wsl、linux 或 $BATTLEPLAN_HOST_ALIAS),绝不使用主机名,因为这些文件可能跨机器共享。会话 ID 仅能在创建它的机器上恢复:向其他主机显示下一步操作,但绝不显示其恢复命令。
多主机: 设置 plans_git_sync: true 并将 plans_dir 放入一个 git 仓库中。提交仅影响刚刚写入的文件(git commit -- <path>),并在 fetch + merge --ff-only 之后执行。切勿 stash、reset 或 clean:其他会话可能在该仓库中持有未提交的工作。如果快进失败,则本地提交并说明推送待处理。
工具
| 脚本 | 功能 |
|---|---|
| `setup_tracker.py check | init` |
pull_tasks.py [context] [--mine] | 以 JSON 格式输出未完成任务,包含计算后的紧急程度、截止日期、所有者类型、依赖关系、工单 |
recap_sessions.py --tasks pull.json [--since auto] [--context X] | 自上次交接以来的代理会话 + git 提交,通过工单 ID 关联到任务 |
| `manage_tasks.py add | batch-add |
| `run_draft.sh --install | --check |
tracker.py | 存储后端(csv、xlsx、gsheets)和配置加载;被其他脚本导入 |
所有脚本都是 uv run --script 文件,具有内联依赖(PEP 723):无需管理虚拟环境。测试:uv run --with pytest --with openpyxl pytest tests/。
不可协商规则
- 回顾仅提建议,由人确认。 绝不以证据为依据自动标记任务完成。
- 写入时使用精确的行引用。 拉取之后,使用
Tab!row引用一次batch-done调用归档;当行已知时绝不回退到子字符串搜索。 - 保密上下文(
"confidential": true)仅在跟踪器和交接文件中显示工单 ID 和简短通用摘要。manage_tasks.py拒绝 IP、URL 和该上下文的forbidden_patterns。 - 未经明确确认绝不启动线程。
- 跟踪器命令按顺序执行 — Google Sheets 大约每分钟允许 60 次读取,而每条命令都会读取每个标签页。
依赖项
uv(brew install uv,或 curl -LsSf https://astral.sh/uv/install.sh | sh)。git 用于回顾的提交扫描。仅 Google Sheets 后端需要:具有工作表编辑器权限的 service account JSON 密钥。会话回顾会读取 Claude Code 转录(~/.claude*/projects);对于其他代理,仅报告 git 活动和交接文件。