Levix-Digital/plan-memory

📐 项目计划记忆技能 (plan-memory)

路径: <skills_root> 是包含此技能的文件夹（此 SKILL.md 所在文件夹的父目录）。运行命令时请使用真实的绝对路径。

plan-memory 技能为项目保留100% 完整、未压缩的架构计划、战略路线图和多步骤蓝图，项目上的所有协作者共享。

• 事实来源：项目仓库中每个计划对应一个 Markdown 文件，位于 docs/plans/<plan_id>.md（YAML 前页元数据 + 计划正文）。计划经过版本控制、审查并与代码合并。可通过项目中的 .dev-cycle.json 文件的 "plans_dir" 配置更改文件夹。
• 搜索索引：位于 ~/.ai-code-agent-memory/plan-memory/db 的本地 ChromaDB（可通过 PLAN_MEMORY_DB 覆盖），集合名 plan_index。它是可丢弃的：每个命令都根据文件（通过 SHA-256）同步索引，并且 rebuild_index（引擎）会重新创建它。
• 项目：从当前目录的 Git 仓库（或 --dir 指定的目录）解析：首先尝试 .dev-cycle.json 中的 project_name，否则使用仓库文件夹名称，并规范化为 kebab-case。使用 --project 可覆盖。
• 层级：待办事项（docs/BACKLOG.md）无需发现即可在几秒内捕获工作，并按史诗分组；路线图（docs/ROADMAP.md）对发布版本进行排序并分配项；当用户提升待办项时创建计划，并包含发现和规划过程（参见“待办事项”和“路线图”）。
• Spec Kit 信封：当项目使用 Spec Kit 时，功能计划是一个信封（spec_dir），指向包含详细信息的 Spec Kit 文件夹（specs/NNN-slug/）；搜索、漂移检测和 get_plan 会读取该文件夹中与计划相关的构件（参见“使用 Spec Kit 的计划”）。
• 指导原则：零压缩 / 零丢失。计划以其完整内容（Mermaid 图表、表格、步骤、公式、理由）被保留，作为每个开发者和会话的持久知识。

---

🏛️ 计划文件格式

---
plan_id: my_app_blueprint_v1_2_0_two_stage_search
project: my-app
title: 使用本地重排的两阶段搜索
kind: feature              # feature (默认) | bug
version: v1.2.0
status: in_progress        # draft | planned | active | in_progress | completed | superseded
author: 张三           # 创建者的 git user.name
created_at: '2026-10-15T16:36:00'
updated_at: '2026-10-16T09:10:00'
session_id: 8abbc3bf-...   # 制定计划时的对话 ID (可选)
tags: [search, reranker]
supersedes: my_app_blueprint_v1_1_0_search
superseded_by: null
parent_plan_id: null
backlog_items: [FEAT-004]  # 计划交付的待办项 (可选)
spec_dir: specs/004-reranker  # 包含计划详细信息的 Spec Kit 文件夹 (可选)
milestones:
- name: M1 运行时基础
  done: true
  done_at: '2026-10-15'
  by: 张三
- name: M2 重排器
  done: false
status_log:
- at: '2026-10-15T16:36:00'
  by: 张三
  status: active
  note: 计划已创建
---

# 计划标题

...Markdown 格式的完整计划正文...

• 脚本仅重写前页元数据；正文由 save_plan 一次性写入（或手动编辑）。里程碑和状态更改会产生小而可读的差异。
• 文件名即计划 ID。血缘字段（supersedes, superseded_by, parent_plan_id）引用其他计划 ID。
• 脚本从不提交。 代理将计划文件与它们所描述的工作一起提交（参见“团队工作流程”）。

---

⚙️ 命令

所有脚本位于 <skills_root>/plan-memory/ 目录下，并接受 --dir <项目目录>（默认：当前目录）和 --project <名称> 参数。

1. 保存/更新带血缘关系的计划 (save_plan)

将完整计划写入 docs/plans/<plan_id>.md，不进行裁剪或摘要。保存现有 ID 会更新标题、正文和字段，保留作者、创建日期和里程碑进度。--supersedes 将旧计划标记为 superseded。save_plan 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory save_plan \
  --title "集成路线图：Python -> Rust, 模型路由器与模型工具包" \
  --file "path/to/plan.md" \
  --version "v1.2.0" \
  --tags "roadmap,rust_refactor,model_router" \
  --milestones "优先级 1,优先级 2,里程碑 3" \
  --status "active" \
  --session-id "<session_id>" \
  --supersedes "<old_plan_id>"

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory save_plan [参数]。 选项：--id（默认：<project>_<title> 的 slug）、--parent-id、使用 --content 替代 --file、--kind feature|bug、--backlog-items "BUG-001,FEAT-002"（关联项，将其状态设为 planned）、--spec-dir specs/NNN-slug（计划是该 Spec Kit 文件夹的信封）。

2. 里程碑与进度追踪器 (check_milestone)

check_milestone 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

# 列出最新活动计划（或使用 --id <plan_id>）的进度和检查清单：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --list

# 标记一个里程碑为已完成（记录日期和作者）：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "优先级 1" --notes "通过 PR #319 完成"

# 将里程碑回退为待处理：
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory check_milestone --milestone "优先级 1" --uncheck

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory check_milestone [参数]。 完成的第一个里程碑会将 active 计划移至 in_progress；最后一个里程碑会将其移至 completed。

3. 架构漂移检测器 (detect_drift)

将任何实现提案、问题或新的提示与活动计划进行比较：语义相似性、里程碑覆盖范围和顺序，以及项目自身的反模式规则。detect_drift 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --proposal "优先级 1：用 Rust 构建原生 ReAct 编排器，替换 Python LangGraph"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory detect_drift --file "path/to/proposal.md" --strict   # 冲突时退出码 != 0

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory detect_drift [参数]。

反模式规则位于项目 .dev-cycle.json 文件的 drift_rules 键中（从 --dir 向上查找）。如果没有规则，则仅检查相似性和里程碑。

"drift_rules": [
  { "tech": "langchain", "conflict_msg": "基线计划移除了 LangChain。" },
  {
    "tech": "并行数据库",
    "negative_markers": ["单一来源", "settings.db"],
    "proposal_allow": [],
    "conflict_msg": "提案暗示使用并行数据库，违反了单一事实来源原则。"
  }
]

当生效中的计划（active / in_progress）提到 tech 并带有拒绝标记，且提案提到 tech 但未包含允许的短语时，规则会引发冲突。

• negative_markers（可选）：标记拒绝的词。默认值：remove, replace, without, forbidden，... 及其葡萄牙语对应词；在现有计划尚未翻译之前保留。
• proposal_allow（可选）：使提及可接受的短语。默认值：without <tech>, remove <tech>, replace <tech>，... 及其葡萄牙语对应词。

4. 列出计划 (list_plans)

list_plans 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory list_plans [--status active] [--kind bug]

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory list_plans [参数]。

5. 读取完整计划 (get_plan)

get_plan 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan --id "<plan_id>"
"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory get_plan                  # 最新的活动计划

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory get_plan [参数]。

6. 语义搜索 (search_plans)

search_plans 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory search_plans --query "如何在聊天中实现模型路由器" [--limit 5] [--all-projects]

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory search_plans [参数]。

7. 更新生命周期状态 (update_plan_status)

设置计划状态，记录到状态日志，并同步更新关联的待办项。update_plan_status 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory update_plan_status --id "<plan_id>" --status "completed" --notes "已交付优先级 1 和 2。"

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory update_plan_status [参数]。

8. 导出 (export_plan)

将计划复制到其他地方，支持 JSON 或带/不带前页元数据的 Markdown 格式。export_plan 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory export_plan --id "<plan_id>" --format json --output-dir "out/"

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory export_plan [参数]。

9. 重建索引 (rebuild_index)

rebuild_index 在原生引擎上运行。在 sh shell 中（Linux, macOS, Git Bash）：

"<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory rebuild_index [--project <名称>] [--dir <路径>]

在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory rebuild_index [参数]。

---

📥 待办事项 (backlog)

规划的第一级：一个 Markdown 文件（.dev-cycle.json 中的 backlog.file，默认为 docs/BACKLOG.md），由第一次 add 操作从 templates/BACKLOG_TEMPLATE.md 创建。

## Bugs | Features | Improvements | Adjustments | Epics | Closed

### BUG-001: Frontier 预设选择了过时的模型 ID
- **严重性**: 高              # 错误: critical | high | medium | low
- **状态**: open                # open | planned | in_progress（在 Closed 下为 done | dropped | duplicate | superseded）
- **发现于**: 2026-10-16, v0.45.0, PR #333
- **计划**: -                     # 提升后的计划 ID
- **描述**: `/preset frontier` 设置了 `claude-3-7-sonnet`，供应商可能会拒绝。

功能（FEAT-NNN）、改进（IMP-NNN）和调整（ADJ-NNN）具有 Priority（high, medium, low）而不是 Severity。除史诗外的任何项都可能包含 - **Epic**: EPIC-NNN。史诗（EPIC-NNN，位于 ## Epics 部分）对完整产品的项进行分组；它们具有 Priority、Status（open 直至关闭）、Found 和 Description，没有 Plan，并且永远不会被提升：其子项会被提升。当某个史诗的所有子项都已关闭时，validate 会对其发出警告。ID 永远不会被重用：已关闭的项保留在 ## Closed 部分下，并带有一条 - **Closed**: 注释（日期和拉取请求、原因、duplicate of <ID>，或 superseded by <ID>[, <ID>...]）。当一个项被不同的、定义更明确的项替换时（一个想法在构思后被拆分或重塑），它被认为是被取代的 (superseded)；重复项 (duplicate) 是同一个请求被捕获了两次。

backlog 在原生引擎上运行：在 sh shell 中（Linux, macOS, Git Bash）使用 "<skills_root>/dev-cycle-protocol/bin/dev-cycle" plan-memory backlog <命令> [参数]。在 PowerShell 中，请运行 & "<skills_root>/dev-cycle-protocol/bin/dev-cycle.ps1" plan-memory backlog [参数]。

任务	命令
捕获	backlog add --type bug|feature|improvement|adjustment|epic --title "<标题>" --description "<描述>" [--severity S] [--priority P] [--epic EPIC-NNN] [--found-in "v1.2.0, PR #12"]
捕获失败的手动测试	backlog add --from-failed --run vX.Y.Z-rc.N [--severity S]
汇总（优先显示错误，然后再显示新工作）	backlog summary [--json]
列出，显示	backlog list [--type T] [--status S] [--epic EPIC-NNN] [--all] [--json], backlog show <ID>
更改	backlog set <ID> [--title] [--description] [--severity] [--priority] [--status] [--plan] [--epic ID|-]
提升为计划	backlog promote <ID> [<ID> ...] [--title T] [--id PLAN_ID] [--version V] 或 --into <PLAN_ID>
关闭	backlog close <ID> [--ref "PR #12"], drop <ID> --reason R, duplicate <ID> --of <ID>, supersede <ID> --by <ID>[,<ID>...], reopen <ID>
验证	backlog validate

• 捕获几乎没有成本：不需要发现，不需要计划。用户通过 /backlog 命令执行；代理为在工作范围之外发现的错误执行。
• 提升会根据 templates/BUG_PLAN_TEMPLATE.md（每个项都是错误：复现、证据和根本原因、修复设计、回归测试）或 templates/FEATURE_PLAN_TEMPLATE.md 创建一个 draft 计划，并将项复制到其 Backlog items 部分，并在两者之间建立双向链接。发现过程写在该计划中；然后将其保存为 active 状态，并附带里程碑，以供批准。
• 关联项跟随其计划：当计划为 draft 或 active 时，它们为 planned；当计划进行中时，它们为 in_progress；当计划完成时（引擎上的 check_milestone 和 update_plan_status），它们作为 done 关闭。
• 分类由用户决定：代理永远不会自行提升、丢弃或重新设定优先级。
• 脚本从不提交，并且拒绝重写其结构无法读取的文件，因此手动编辑永远不会丢失。

---

🗺️ 路线图 (roadmap)

按交付顺序排列的产品发布版本（.dev-cycle.json 中的 roadmap.file，默认为 docs/ROADMAP.md），由第一次 `ad...

[为简洁起见，翻译后的内容截断至此]