Plan Keeper — 跨会话任务规划器

⚡ 立即执行（必做，不可跳过）

当你读到这一段时，立即按以下顺序执行：

1. 检查 plan-keeper 是否已配置

项目目录下有没有 .atomcode\skills\plan-keeper\skill.md？

• 没有 → 执行初始化：
  1. 创建目录（逐级）：.atomcode\ → .atomcode\skills\plan-keeper\ → .atomcode\records\
  2. 写入 .atomcode\skills\plan-keeper\skill.md：
  yaml imports: skills: [] records: []
  3. 问用户项目描述 → 提取任务名 → 写入 current-plan.md（项目根目录）
  4. 搜索 **/skills/*/skill.md 找可用技能
  5. 列出全部技能，推荐项预勾选 [x]，输入编号切换，done 确认导入
  6. 选中的技能写入 imports，逐个 read_file 加载

• 有 → 跳到下一步

2. 校验并加载已导入技能

1. 读 imports.skills 列表
2. 每个技能：优先 <项目技能目录>/<name>/skill.md，其次 <全局技能目录>/<name>/skill.md
3. 用 read_file 加载内容
4. 输出 ✅ 技能已全部加载：[N 个]

3. 检查任务状态

1. 读 current-plan.md（项目根目录）
2. 输出当前任务状态

以下为 plan-keeper 的完整规则文档：

导入依赖（IMPORT）

plan-keeper 是本项目的 main 入口。通过 imports 声明要加载的技能和任务记录，自动级联加载。

imports:
  skills:
    # - <技能名>          ← 按需添加（优先项目技能目录，其次全局技能目录）
  records:
    # - <任务名>          ← 按需添加：<项目记录目录>/<name>.md

初始化时 imports 为空，通过 /plan-keeper 命令按项目需求添加。

导入类型

对话中提及其他任务时，plan-keeper 自动拉取对应记录。详见 RECORDS 章节 的跨任务引用。

导入规则

全局与项目级合并策略

plan-keeper 同时存在全局安装（系统内置）和项目配置（.atomcode/skills/plan-keeper/skill.md）两个层级，采用合并去重策略：

合并规则：
1. 全局规则 + 项目规则全部生效
2. 同名规则，项目级覆盖全局级
3. imports 合并去重
4. 项目级 > 全局级

任务记录（RECORDS）

计划开始新任务时，plan-keeper 自动创建或更新记录文件。

自动创建规则

当 /plan-keeper new <任务名> 或 current-plan.md 中定义了方案名称时：

1. 检查 .atomcode/records/<任务名>.md 是否存在
2. 不存在 → 用 write_file 创建新记录文件，写入模板
3. 存在 → 追加新条目到文件末尾

记录文件格式

# <任务名> — 任务记录

## 目标
[一句话描述]

## 索引关键词
<!-- AI 自动维护，写入关键段落时同步添加标签 -->
- [🔖 核心逻辑] -> `#L行号`
- [🔖 关键决策] -> `#L行号`

## 任务日志

### YYYY-MM-DD — [本次任务标题]
- **改前**：[改了什么]
- **结论**：[学到了什么 / 决策依据]
- **状态**：✅ 已完成 [🔖 关键词]

跨任务引用

详见执行规则中的"规则 7 — 跨任务引用"，有详细的优先级逻辑（优先检查当前方案，其次查 records 历史）。

标签索引

每写入一条记录时，AI 自动为关键段落添加 [🔖 <关键词>] 标签，用于跨会话精准定位。详见执行规则中的"规则 8 — Tag-First 标签索引"。

全局索引（GLOBAL INDEX）

.atomcode/index.md 是跨任务、跨会话的全局目录，类似书的索引页。AI 通过检索标签来定位内容，无需全量加载 records 文件。

index.md 模板

AI 在首次 init 或检测到 index.md 不存在时自动创建：

# 📚 全局任务索引 (Global Index)

> AI 检索时直接搜索 `[🔖 关键词]`，定位到对应文件的行号读取上下文。

## 📍 核心逻辑与决策
<!-- - [🔖 关键词] -> `records/<任务名>.md` #L行号 -->

## 🔗 任务依赖与阻塞
<!-- - [🔖 依赖: <前置任务名>] -> `records/<任务名>.md` #L行号 -->

## 💾 上下文快照
<!-- - [🔖 快照: <任务名>_暂停_YYYYMMDD_HHMM] -> `records/<任务名>.md` #L行号 -->

> 模板中的 <!-- --> 是示例占位符，AI 写入实际标签时需去掉注释标记，填入真实文件名和行号。

索引更新规则

初始化（INIT）

plan-keeper 的初始化分为自动触发和手动执行两种入口，执行相同的完整交互流程。

交互流程（自动 + 手动共用）

无论自动还是手动触发，都执行以下流程：

step 1 — 创建目录结构
检测 .atomcode/skills/plan-keeper/skill.md 是否存在。不存在时创建：
- .atomcode/skills/plan-keeper/skill.md（imports 为空）
- .atomcode/records/ 目录

step 2 — 咨询项目意图
问用户："这个项目主要是做什么的？一句话描述。"

从回答中提取两个信息：
- 项目描述 → 写入 current-plan.md 的"原始目标"
- 任务名 → 自动从描述中提炼（如"做 Windows 桌面自动化工具"→ 任务名"Windows 桌面自动化"），然后问用户确认

step 2.5 — 确认 build 命名格式
问用户："build 产物的命名格式是什么？"
- 默认格式：<原名>_MMDDHHMM（时间戳），如果有 git commit hash 则在时间戳后追加 _<短hash>
- 示例：ACP学习网站_07011647.exe 或 ACP学习网站_07011647_abc1234.exe
- 如果用户接受默认，写入 current-plan.md 的 build 命名规则
- 如果用户有自定义格式，按用户说的记录

step 3 — 初始化任务看板 + 记录文件
创建 current-plan.md，写入：
- 方案名称：用户确认的任务名
- 原始目标：项目描述
- 方案步骤：暂空（待后续分解）

同时创建 .atomcode/records/<任务名>.md，写入项目描述作为首条记录。

step 4 — 扫描全部技能 + 自动推荐标记
1. 全局扫描：先问用户全局 SKILL.md 的存放位置，或使用通配搜索：
→ 全局 skill.md 放在哪个目录？（留空则全局搜索，耗时可能较长） >
- 用户输入路径 → 扫描该目录下所有子目录中的 skill.md
- 留空 → 从磁盘根目录搜索 **/skills/*/skill.md（匹配任何层级的 skills/ 目录），同时搜索项目本地 **/skills/*/skill.md
- 提示耗时：「⏳ 全局搜索可能较慢，请稍候…」
2. 将用户的项目描述与每个技能的名/描述做关键词匹配，自动标记推荐（用 [x] 表示推荐勾选，[ ] 表示未推荐）
3. 全部技能一次性列出，按相关度排序

step 5 — 交互式勾选导入（纯文本交互）
1. 展示全部技能列表（带编号），推荐项已预勾选 [x]：

```
→ 扫描到 8 个可用技能（推荐项已预勾选 [x]，输入编号切换，Enter 确认）：

 [x] 1. desktop-automation-windows  — Windows 桌面自动化最佳实践           ⭐
 [x] 2. desktop-automation-reviewer — 桌面自动化代码评审专家                ⭐
 [x] 3. python-reviewer             — Python 代码评审专家                   ⭐
 [x] 4. mcp-reviewer                — MCP 代码评审专家                      ⭐
 [ ] 5. pytest-coverage             — pytest 覆盖率测试
 [ ] 6. karpathy-guidelines         — LLM 编码行为准则
 [ ] 7. build                       — PyInstaller 打包                      [全局]
 [ ] 8. engineering-lite            — 工程精简开发流                        [全局]

```

2. 用户输入规则：
   | 输入 | 行为 |
   |---|---|
   | 1 | 切换编号 1 的勾选状态（[x] ↔ [ ]） |
   | 1,5,6 | 同时切换 1、5、6 的勾选状态 |
   | all | 全部选中（全部变为 [x]） |
   | done / confirm / ok | 确认当前选择并导入 |
   | 其他数字/逗号组合 | 对应编号依次切换 |

3. 确认后 → 写入 imports.skills（全局技能自动写入本地 imports），并加载到当前会话

输出示例：

✓ plan-keeper 已就位

项目描述："做一个 Windows 桌面自动化工具"
→ 任务名确认为：Windows 桌面自动化
→ ✓ 创建 current-plan.md
→ ✓ 创建 records/Windows 桌面自动化.md

→ 扫描全局技能 + 本地技能...
→ 找到 8 个可用技能，4 个已预勾选（按关键词匹配度自动标记）
→ 输入编号切换勾选（如 "1" / "1,5,6" / "all"），Enter 确认

   [x] 1. desktop-automation-windows  — Windows 桌面自动化最佳实践           ⭐
   [x] 2. desktop-automation-reviewer — 桌面自动化代码评审专家                ⭐
   [ ] 3. python-reviewer             — Python 代码评审专家                   ⭐
   [x] 4. mcp-reviewer                — MCP 代码评审专家                      ⭐
   [ ] 5. pytest-coverage             — pytest 覆盖率测试
   [ ] 6. karpathy-guidelines         — LLM 编码行为准则
   [ ] 7. build                       — PyInstaller 打包                      [全局]
   [ ] 8. engineering-lite            — 工程精简开发流                        [全局]

> 3
   [x] 1. desktop-automation-windows  — Windows 桌面自动化最佳实践           ⭐
   [x] 2. desktop-automation-reviewer — 桌面自动化代码评审专家                ⭐
   [x] 3. python-reviewer             — Python 代码评审专家                   ⭐
   [x] 4. mcp-reviewer                — MCP 代码评审专家                      ⭐
   [ ] 5. pytest-coverage             — pytest 覆盖率测试
   [ ] 6. karpathy-guidelines         — LLM 编码行为准则
   [ ] 7. build                       — PyInstaller 打包                      [全局]
   [ ] 8. engineering-lite            — 工程精简开发流                        [全局]
> Enter

✓ 已导入 4 个技能
✓ 初始化完成。当前项目已就绪：Windows 桌面自动化

自动触发逻辑

当进入一个新项目目录且检测到无 .atomcode/skills/plan-keeper/skill.md 时：

1. 执行上述完整交互流程（step 1 → step 5）
2. 不提示"先建目录再运行手动命令"——直接走完整流程

触发条件：新项目目录 + plan-keeper 首次加载 + skill.md 不存在。

手动初始化 / 重新初始化

当用户运行 /plan-keeper init 时：

如果已有旧配置（skill.md 或 current-plan.md 存在）：

1. 创建归档目录 .atomcode/archive/<YYYY-MM-DD-HHMM>/
2. 将 <项目技能目录>、.atomcode/records/、.atomcode/index.md、current-plan.md 备份到归档目录
3. 输出："📦 旧配置已归档至：.atomcode/archive/<YYYY-MM-DD-HHMM>/"
4. 问用户："要删除归档吗？(y/n)"
5. 无论 y/n，继续执行完整交互流程（step 1 → step 5），新建全新配置

如果无旧配置（全新项目）：直接执行完整交互流程（step 1 → step 5），与自动触发行为一致。

技能加载验证

自动验证规则

plan-keeper 导入 skills 后，AI 必须在开始工作前验证技能是否已实际加载：

1. 每次对话开始时，读取 current-plan.md 和 imports 中的 skills 列表
2. 对每个已导入的 skill，用 use_skill <技能名> 读取其内容
3. 如果技能内容未加载 → 输出"⚠️ 技能 <技能名> 未加载，正在加载..."，然后自动调用 use_skill 加载
4. 所有技能加载完成后 → 在回复开头输出"✅ 技能已全部加载：[技能名列表]"

不验证不工作：在验证完成前，AI 不允许执行任何 write_file / edit_file / bash 等产生实际产出的操作。

手动验证命令

/plan-keeper verify

验证当前项目所有导入的技能是否已实际加载。

动作：
1. 读取 skill.md 的 imports.skills
2. 对每个技能调用 use_skill 检查是否可加载
3. 输出验证结果：
- ✅ engineering-lite — 已加载
- ⚠️ karpathy-guidelines — 未加载（自动加载中...）
4. 自动加载未加载的技能

/plan-keeper list

列出当前项目已导入的内容（skills + records）。

动作：
1. 读取 skill.md 的 imports 区块
2. 分别列出 skills 和 records

输出示例：

skills: engineering-lite ✓, karpathy-guidelines ✓
records: 控制电脑, 技能设计

/plan-keeper list all

列出所有可用技能（全局 + 项目本地），附带加载状态。

发现顺序：
1. <全局技能目录>（全局技能目录）
2. <项目技能目录>（项目本地技能目录）

动作：
1. 按顺序扫描上述位置，读取每个子目录下的 skill.md，提取技能名 + 描述（YAML frontmatter）
2. 全局技能 → 来源自 <全局技能目录>/<name>/skill.md，标记 [全局]；不从全局自动写入本地 imports
3. 合并去重（同名技能只显示一次，本地版本优先于全局）
4. 标记加载状态（已导入 ✓ / 未导入 ○），排除 plan-keeper 自身
5. 按类型分组输出（全局 skill → 本地 skill）
6. list all 纯读取，不修改任何文件

输出示例：

本地 skills:
  desktop-automation-windows  — Windows 桌面自动化最佳实践              ✓
  desktop-automation-reviewer — 桌面自动化代码评审专家                   ✓
  python-reviewer             — Python 代码评审专家                      ✓
  mcp-reviewer                — MCP 代码评审专家                         ○
  pytest-coverage             — pytest 覆盖率测试                        ○
  karpathy-guidelines         — LLM 编码行为准则                         ○

全局 skills:
  build                       — PyInstaller 打包                        ○

/plan-keeper add <name>

导入技能到当前项目。

动作：
1. 搜索目标（扫描全局 + 本地 skill 目录，同名时本地版本优先）
2. 如未找到 → 返回相似列表，不操作
3. 如已导入 → 提示"已在 imports 中"
4. 通过则写入 skill.md 的 imports.skills，并加载到当前会话

/plan-keeper add all

导入所有全局可用技能。

动作：
- 扫描全局技能列表 + <项目技能目录>
- 跳过已导入和 plan-keeper 自身
- 全部写入 imports.skills，一次性加载

/plan-keeper remove <name>

从当前项目移除已导入的技能。

动作：
1. 检查 imports 中是否存在
2. 不存在 → 提示"未导入"
3. 存在 → 从 imports.skills 删除对应行

/plan-keeper search <query>

搜索可用技能（全局 + 本地），不绑定特定工具的 API。

扫描范围（全局 + 本地，同名时本地版本优先展示）：

1. <全局技能目录> 下的 skill.md（或其他工具的等效 config 路径）
2. <项目技能目录> 下的 skill.md（或其他工具的等效项目路径）

动作：
1. 按顺序扫描上述位置，读取每个子目录下的 skill.md，提取技能名
2. 合并去重（同名技能只显示一次，本地版本优先于全局）
3. 标记导入状态（已导入 ✓ / 未导入），排除 plan-keeper 自身
4. 对技能名做模糊匹配，按相关度排序后返回

输出示例：

搜索 "engineer":
  engineering-lite  — 工程精简开发流              [未导入]

/plan-keeper verify

验证当前项目所有导入的技能是否已实际加载（内容已被 AI 读取）。

动作：
1. 读取 skill.md 的 imports.skills
2. 对每个技能调用 use_skill 检查是否可加载
3. 输出验证结果：
✅ engineering-lite — 已加载 ⚠️ karpathy-guidelines — 未加载（自动加载中...）
4. 自动加载未加载的技能

/plan-keeper new <任务名>

手动创建新任务（触发规则 2 相同的流程，只是将入口从对话改为命令）。

动作：
1. 按规则 2 的名称确认规则（首次问用户确认，已有直接追加）
2. 创建 current-plan.md + .atomcode/records/<任务名>.md
3. 输出"新任务已创建：<任务名>"

/plan-keeper reload

重新加载所有已导入的技能（用于新会话或手动刷新）。

动作：
1. 读取 .atomcode/skills/plan-keeper/skill.md 的 imports.skills 列表
2. 对每个技能调用 read_file 读取其内容（优先本地 <项目技能目录>，其次全局 <全局技能目录>）
3. 输出加载结果：
✅ desktop-automation-windows — 已加载 ✅ python-reviewer — 已加载 ⚠️ karpathy-guidelines — 未找到源文件
4. 删除 .atomcode/.pk_start 标记文件（若存在）
5. 输出 "✅ 技能已全部加载：[N 个]"

命令执行规则

执行规则

0. 自动触发

任何非零的工作（哪怕单步），只要涉及产出一个文件，必须先初始化一个 plan-keeper 计划条目，再动手。

计划条目至少包含：目标、状态、验证方式。这是硬性触发条件——写文件前必须执行。

> 项目初始化（目录结构创建、skill.md 写入）由 INIT 章节的自动/手动初始化处理，不属于本条规则的范畴。

1. 对话开始时

启动流程（按序执行）：

第 1 步 — 检查 plan-keeper 是否已配置
检测项目目录中是否存在 <项目技能目录>/plan-keeper/skill.md：
- 不存在 → 自动执行完整初始化流程（Step 1 → Step 5），不询问
- 存在 → 继续第 2 步

第 2 步 — 检测 session_start hook 标记
检查 .atomcode/.pk_start 是否存在：
- 存在 → 新会话，执行 /plan-keeper reload 加载所有技能，删除 .pk_start
- 不存在 → 同一会话内继续，跳过 reload（技能已在上下文中）

第 3 步 — 检查任务状态
读取 current-plan.md：

• 存在且有未完成任务 → 回复开头说"当前有未完成任务：[方案名称]，步骤 X/Y"
• 存在但任务已完成（状态标记 ✅）→ 问用户："上次任务已完成，是新任务还是回溯查看？"
• 不存在 → 正常开始新任务

边界情况：

2. 任务开始时

用 write_file 创建 current-plan.md，写入原始目标、分解步骤、验证方式。

任务名称确认规则（混合模式）：

示例：

用户："优化控制电脑" → records 已有 → 直接追加，不问
用户："新做一个键盘映射" → 首次 → 问"任务名确认叫'键盘映射'吗？"

current-plan.md 模板：

# 当前方案：[方案名称]

## 原始目标
[一句话描述最终要达成的目标]

## 方案步骤
- [x] 步骤 1 — [验证方式]
- [x] 步骤 2 — [验证方式]
- [ ] 步骤 3 — [验证方式]
- [ ] 步骤 4 — [验证方式]

## 当前状态
[当前卡在哪一步、下一步打算做什么]

## 方案变更记录
- [2026-06-30 15:40] 方案A → 方案B: 原因是 _save_config 依赖 self._config 不可靠，改为直接从UI控件读取

3. 每完成一步

用 edit_file 将 current-plan.md 中的 [ ] 改为 [x]，更新"当前状态"。

同步写入 records 文件：每完成一步，同时在 records/<方案名称>.md 中追加进度日志，格式与记录模板一致：

### YYYY-MM-DD HH:MM — 步骤 X：[步骤名]
- **改动**：完成了什么
- **结论**：当前状态摘要
- **状态**：⏳ 进行中

这样即使任务未完成，records 文件也保持最新，跨任务引用时读到的是当前进度而非空文件。

4. 方案变更时

• 不要覆盖原方案
• 在"当前状态"区块追加一行
• 更新步骤列表
• 同步写入 records 文件变更记录

5. 任务完成时

在 current-plan.md 的"当前状态"写"✅ 已完成"。

同时向 records/<方案名称>.md 追加总结条目，格式与记录模板一致：

### YYYY-MM-DD HH:MM — 任务完成：[方案名称]
- **背景**：任务概述
- **改动**：最终达成的目标
- **结论**：关键决策 / 经验结论
- **状态**：✅ 已完成

完成后的 current-plan.md 保留不动（方便回溯），records 文件作为历史档案持续累积。

6. 防偏离检查

每次执行工具调用前，快速核对：
> "这个工具调用是否仍然服务于 current-plan.md 中定义的原始目标？"
如果不是，先更新计划再执行。

7. 跨任务引用

对话中出现已导入 records 中的任务名时：

1. 优先检查 current-plan.md — 如果该任务名匹配当前活跃方案，直接读 current-plan.md（实时进度）
2. 次优检查 records 文件 — 如果当前方案不匹配，读 .atomcode/records/<任务名>.md（历史记录）
3. 返回最新的一条日志（按时间倒序）

这样进行中的任务能被实时查询，已完成的任务也能被归档回溯。

8. Tag-First 标签索引

每次 write_file 或 edit_file 写入 records/ 下的记录文件时，必须同步打标签并更新索引。

动作：
1. 自动提取：分析本次修改的核心意图（方案决策、逻辑调整、关键配置），提炼 1-2 个关键词
2. 写入标签：在写入段落的末尾追加 [🔖 <关键词>]。例如：- **结论**：改用 pywinauto 替代 pyautogui [🔖 技术选型]
3. 更新索引：若该标签首次出现，追加到 .atomcode/index.md 的对应分类下：
text - [🔖 技术选型] -> `records/<任务名>.md` #L行号
4. 检索方式：当用户提问含已注册关键词时，AI 必须先查 index.md 获取标签映射，再用 read_file 精准读取该行附近的上下文，而非全量加载整个 records 文件。
> ⚠️ #L行号仅为粗略定位锚点。若文件顶部追加了新内容导致行号漂移，AI 应优先通过全文搜索 [🔖 <关键词>] 文本字符串来定位，或读取行号前后 5-10 行做模糊匹配，以确保读到正确的段落。

9. 依赖标签化

当执行当前任务过程中，发现必须先完成另一个前置任务才能继续时（阻塞依赖，非用户主动切换），按以下规则处理：

> 注意：本规则与 规则 1 的"先放放换个任务"不同。规则 1 是用户主动切换（保持原计划不变+快照），本规则是 AI 检测到逻辑依赖后自动切换（更新状态为搁置）。

1. 标注依赖：在当前 records/<当前任务>.md 的最新进度处写入阻塞原因，添加标签 [🔖 依赖: <前置任务名>]
2. 切换计划：将当前 current-plan.md 的状态更新为"⏸ 搁置（等待前置任务：<前置任务名>）"，然后为前置任务创建或加载新计划
3. 回溯恢复：前置任务完成后，AI 检索 .atomcode/index.md 中的 [🔖 依赖: <前置任务名>]，定位所有被搁置的任务，逐一恢复
4. 恢复时：AI 无需重读历史全量记录，只需读取被搁置处的最新日志行 + 对应的标签上下文即可

示例：

当前: 开发登录页面UI
→ 发现需要先重构API权限模块
→ records/登录页面.md: "等待权限模块重构完成 [🔖 依赖: 权限模块重构]"
→ current-plan.md 状态: ⏸ 搁置
→ 切换到 权限模块重构 任务
→ 权限模块重构完成后 → 检索 [🔖 依赖: 权限模块重构] → 定位到登录页面开发 → 恢复

10. 上下文快照存档

当任务被中断、会话结束、或用户要求"先放放换个任务"时，在当前 records/<任务名>.md 末尾追加快照区：

### ⏸ 暂停快照 [🔖 快照: <任务名>_暂停_YYYYMMDD_HHMM]
- **关注文件**：`src/main.py`, `config.yaml`
- **当前逻辑**：（正在处理的变量/函数/逻辑简述）
- **下一步**：（恢复后第一件要做的事）
- **状态**：⏸ 搁置

同步索引：将创建的快照标签 [🔖 快照: <任务名>_暂停_YYYYMMDD_HHMM] 注册到 .atomcode/index.md 的快照区块。

同一任务同一天多次暂停：新快照直接覆盖旧快照记录（恢复工作通常只需要最后一次的断点）。index.md 中对应的标签也同步覆盖。

恢复还原：用户要求恢复该任务时，AI 检索对应的快照标签，读取 3 行快照信息即可无损耗还原中断时的思维现场，无需重读全部历史日志。

进化记录

<!-- plan-keeper-evolution:
- 2026-06-30: 初始化 skill.md，定义 plan-keeper 核心机制、导入依赖、管理命令、执行规则
- 2026-06-30: 新增 imports 双轨（skills + records），任务记录动态创建，init 命令
- 2026-07-01: 合并 INIT 章节（自动+手动统一入口），消除规则 0/0a 层级混排
- 2026-07-01: 自动初始化改为完整交互流程（不再只建目录就停），手动 init 新增归档逻辑
- 2026-07-01: 引入读书式索引机制：全局 index.md + [🔖 标签] 替代压缩摘要
- 2026-07-01: 新增三条执行规则（Tag-First 标签索引、依赖标签化、上下文快照存档）
- 2026-07-01: INIT 新增 step 2.5（build 命名格式咨询），默认 MMDDHHMM 时间戳 + 可选的 git hash 后缀
- 2026-07-01: 新增技能加载验证机制（自动验证规则 + /plan-keeper verify 命令），不验证不工作
-->