roadmap

战略路线图管理

通过五种模式管理项目路线图：将 ROADMAP.md 与 GitHub 当前情况同步、从头创建规划文件、协作构思新功能、快速查看状态摘要，或显示帮助。

前置条件检查

gh --version 2>/dev/null && gh auth status 2>/dev/null

如果未安装 gh，请引导用户访问 https://cli.github.com。如果尚未通过身份验证，请引导用户运行 gh auth login。没有可正常使用且已通过身份验证的 GitHub CLI 时，不得继续。

宪法原则

CONTEXT.md 是项目宪法。 所有模式都必须读取并 遵守 CONTEXT.md 中定义的边界。如果 CONTEXT.md 存在， 请先读取，并据此约束所有分析和建议。

如果任何建议会违反 CONTEXT.md 的边界：

1. 明确指出违规之处
2. 说明会触及哪条边界
3. 提出符合边界的替代方案

模式分派

根据用户输入确定模式。如果未指定模式， 默认使用 sync。

参数	模式	用途
(无)	sync	将 ROADMAP.md 与 GitHub 同步，并推荐优先事项
sync	sync	与默认模式相同
generate	generate	从头创建 CONTEXT.md + ROADMAP.md
brainstorm	brainstorm	创意构思环节（只读）
status	status	快速只读摘要
help	help	显示可用模式

模式：sync

将 ROADMAP.md 与 GitHub 同步，并提供优先级建议。这是主要模式。

1. 通过 gh CLI 获取未关闭的问题、近期已关闭的问题和里程碑
2. 读取 ROADMAP.md 和 CONTEXT.md
3. 检查是否存在旧版章节布局——如果存在，询问用户是否要迁移到标准结构（愿景 → 当前重点 → 近期 → 未来 → 已完成 → 边界）
4. 检测 ROADMAP.md 与 GitHub 之间的不一致（标记为已完成但仍处于未关闭状态、仍未关闭但已关闭、完全缺失）
5. 更新 ROADMAP.md——修正不一致，并将已关闭的问题移至按季度分节的“已完成里程碑”
6. 使用 references/label-config.md 中的启发式规则，为没有 effort/* 标签的未关闭问题估算 LOE
7. 同步 GitHub 标签——创建缺失的标签，并添加或移除 roadmap/* 标签，使其与 ROADMAP.md 中的章节一致
8. 在 ROADMAP.md 的问题条目中附加 LOE 指标（[S]、[M]、[L]）
9. 根据依赖关系、影响与工作量的权衡、主题一致性和 LOE 平衡，生成 3-5 条优先级建议
10. 汇总所有变更和建议

详细工作流步骤见 references/sync.md。标签定义和 LOE 启发式规则见 references/label-config.md。

模式：generate

为新项目或缺少文档的项目创建 CONTEXT.md 和 ROADMAP.md。

1. 如果任一文件已存在，询问用户是重新生成、合并还是中止
2. 调查代码库——结构、依赖项、入口点和功能
3. 推断项目边界（“明确不做的事”）——项目不会做什么
4. 对类似工具和行业背景进行外部调研
5. 起草 CONTEXT.md，包含：核心定位、技术边界、数据事实来源、交互模式、验证标准
6. 获取所有 GitHub 问题和里程碑
7. 将问题归类到当前重点、近期、未来和已完成（按季度分组）
8. 为每个未关闭问题估算 LOE，并应用 effort/* 标签
9. 按标准结构起草 ROADMAP.md，并添加 LOE 指标
10. 先写入 CONTEXT.md，再写入 ROADMAP.md。对两者运行 markdownlint。

详细工作流步骤和模板见 references/generate.md。LOE 启发式规则见 references/label-config.md。

模式：brainstorm

通过协作构思探索新的可能性。此模式默认只读——除非用户明确批准，否则不要创建问题或修改 ROADMAP.md。

1. 阅读 CONTEXT.md 和 ROADMAP.md，了解当前状态和边界
2. 调查代码库中的扩展点、利用不足的功能以及新功能的切入点
3. 从外部研究类似工具、用户需求和趋势
4. 与用户一起运用构思技巧：“如果……会怎样……”， “还有谁……”， “为什么不……”， “缺少什么……”， “什么让人烦恼……”
5. 评估每个想法：根据 CONTEXT.md 检查边界、投入、影响和依赖项
6. 以结构化格式呈现想法（描述、理由、边界检查、投入、影响、下一步）
7. 询问用户要将哪些想法正式化——只有这时才创建问题 或更新 ROADMAP.md

详细工作流步骤和想法模板请参阅 references/brainstorm.md。

模式：status

快速只读概述当前路线图状态。不做任何修改。

1. 通过 gh CLI 获取问题数量和里程碑进度
2. 阅读 ROADMAP.md
3. 提供汇总表：整体指标、按类别划分 （增强功能/缺陷/文档）、按 LOE 划分（小/中/大）
4. 标记明显的不一致之处，不做深入分析

详细工作流步骤和表格模板请参阅 references/status.md。

模式：help

显示可用模式和用法：

roadmap — Strategic Roadmap Management

MODES:
  (default)    Sync ROADMAP.md + labels with GitHub, recommend priorities
  sync         Same as default
  generate     Bootstrap CONTEXT.md + ROADMAP.md from scratch
  brainstorm   Creative ideation session (collaborative, read-only)
  status       Quick read-only summary of current state
  help         Show this help message

LABELS (synced automatically):
  roadmap/current  → "Immediate Focus" section
  roadmap/next     → "Near-Term Vision" section
  roadmap/future   → "Future Vision" section
  effort/small     → 1-2 hours
  effort/medium    → half day to 1 day
  effort/large     → multi-day

KEY PRINCIPLES:
  CONTEXT.md is the project constitution (all modes respect it)
  Brainstorm mode is read-only until user approves ideas
  Generate mode asks before overwriting existing files
  Labels are synced to match ROADMAP.md sections
  LOE is auto-estimated for issues missing effort/* labels

输出指南

• 使用表格进行结构化比较
• 少量使用表情符号，且仅用于表示状态
• 提及 GitHub 问题时，始终包含问题编号
• 修改任何文件后运行 markdownlint