Guide Creator — 通用项目文档指南生成器

为任何项目创建和维护标准化的 guide 文档体系。提炼自实际项目（福音雪镇）经过 20+ 版本迭代验证的文档最佳实践。

Quick Start

模式 1：初始化项目文档

用户说："初始化项目guide" / "创建项目文档" / "init guide"

1. 运行 scripts/init_guide.py --project-name "项目名" --type game|web|cli|lib|general --root /path/to/project
2. 自动创建 start.md + guide/ 目录及全部模板文件
3. 按提示填充关键内容（启动命令、文件清单、架构图等）

模式 2：更新项目文档

用户说："更新guide" / "总结经验教训" / "update guide"

1. 运行 scripts/update_guide.py --action add-changelog|add-pitfall|bump-version|sync-files --root /path/to/project
2. 或直接告诉 AI 本次更新内容，由 AI 生成格式化条目并追加

模式 3：上下文恢复

AI 在新对话开始时，按推荐顺序读取文档快速理解项目。

推荐阅读顺序：start.md → guide/guide.md → guide/08-changelog.md → guide/09-pitfalls.md → 按需读取 01~07

Key Rules

文件结构规范

project-root/
├── start.md                    # 启动说明（怎么跑 + 文件清单）
└── guide/
    ├── guide.md                # 项目总览索引（入口文件）
    ├── 01-design.md            # 设计理念（必须）
    ├── 02-{domain}.md          # 按项目类型（可选）
    ├── 03-{domain}.md          # 按项目类型（可选）
    ├── 04-{domain}.md          # 按项目类型（可选）
    ├── 05-{domain}.md          # 按项目类型（可选）
    ├── 06-tech.md              # 技术架构（必须）
    ├── 07-plan.md              # 开发计划（必须）
    ├── 08-changelog.md         # 更新日志（必须）
    └── 09-pitfalls.md          # 踩坑记录（必须）

必须文件（所有项目类型）：start.md、guide.md、01-design.md、06-tech.md、07-plan.md、08-changelog.md、09-pitfalls.md

可选文件（02~05，按项目类型）：

• 游戏：地图(02)、NPC/实体(03)、属性/数值(04)、AI系统(05)
• Web应用：路由(02)、组件(03)、状态管理(04)、API(05)
• CLI/库：命令(02)、核心模块(03)、数据模型(04)、算法(05)
• 通用：架构(02)、核心模块(03)、数据模型(04)、逻辑(05)

格式约束

1. 版本号：vX.Y 格式（如 v2.3），记录在 guide.md 元信息和 08-changelog.md 顶部
2. Changelog 条目格式：## vX.Y — 标题摘要 (YYYY-MM-DD) + 按子系统分组 + 🐛Bug修复 + 📝代码改动
3. Pitfall 条目格式：## 🔥 坑N：标题 + 问题现象 + 问题根因 + 解决方案 + ⚠️开发注意 + 加粗通用原则
4. 文档索引表：guide.md 中维护完整的文档索引表（文档名 + 内容摘要 + 说明）

更新时机

文件保护

• 不要删除已有的 changelog/pitfalls 条目，只追加
• guide.md 的文档索引表中引用的文件必须存在且非空
• changelog >500 行时归档到 guide/archive/
• pitfalls >30 条时按类型分组（UI类/数据类/LLM类/性能类等）

详细模式指令

完整的模式执行指令请参考以下文件：

• Guide 体系规范：references/guide-spec.md — 文件结构、章节要求、版本号规范、更新触发规则、归档策略
• 文档模板：references/templates/ — 所有文档的标准模板
  • start-template.md — start.md 模板
  • guide-template.md — guide.md 模板
  • changelog-template.md — changelog 模板
  • pitfalls-template.md — pitfalls 模板
  • sub-doc-templates.md — 01~07 子文档模板集

初始化模式 — 详细执行步骤

当用户触发初始化（说 当用户触发初始化（说"初始化项目guide"、"创建项目文档"等）时：

1. 确认项目信息：询问项目名称和类型（游戏/web/cli/lib/通用）
2. 运行初始化脚本：python3 scripts/init_guide.py --project-name "名称" --type 类型 --root 项目根目录
3. 引导填充 start.md：帮助用户填写启动命令、服务地址、文件清单表
4. 引导填充 guide.md：帮助用户填写元信息、架构图、实体/模块概览
5. 验证检查清单：
   • start.md 启动命令可执行
   • guide.md 文档索引表中的所有文件都存在
   • 01-design.md 至少有项目定位描述
   • 06-tech.md 至少有文件结构
   • 08-changelog.md 有 v0.1 初始版本记录
   • 09-pitfalls.md 有文件头和空模板

更新模式 — 详细执行步骤

当用户触发更新（说 当用户触发更新（说"更新guide"、"总结经验教训"等）时：

1. 读取当前版本：从 guide/08-changelog.md 获取最新版本号
2. 收集更新内容：询问用户本次完成的功能/修复/改动
3. 生成 changelog 条目：
   • 版本号递增（补丁 +0.1，功能 +1.0）
   • 按子系统分组描述改动（含方法名和具体行为）
   • 🐛 Bug修复章节（问题+根因+修复）
   • 📝 代码改动章节（文件:方法 列表）
4. 检查踩坑记录：询问是否有踩坑需要记录
   • 生成 pitfall 条目（编号+现象+根因+方案+⚠️注意+通用原则）
   • 检查通用原则章节是否需要新增
5. 同步更新：
   • guide.md 版本号同步
   • start.md 文件清单检查（有新文件则更新）
   • 07-plan.md checklist 更新（如有）
6. 自动提醒：功能开发完成后，主动提示用户更新文档

上下文恢复模式 — 详细执行步骤

AI 在新对话中需要理解项目时，按以下分层策略读取文档。目标：用最少的文件读取获得最大的项目认知。

第1步：start.md — 30秒知道怎么跑

读取文件：项目根目录的 start.md

提取信息：

• 项目名称和一句话简介
• 启动/关闭/重启命令
• 服务地址（如有）
• 项目文件清单表（快速了解项目组成）

读取后应能回答：

• 这个项目怎么启动？端口是多少？
• 项目有哪些文件？每个文件做什么？

第2步：guide/guide.md — 2分钟获得全景

读取文件：guide/guide.md

提取信息：

• 技术路线（语言、框架、依赖）
• 当前版本号
• 文档索引表（知道还有哪些详细文档可读）
• Mermaid 架构图（核心系统间的关系）
• 核心实体/模块概览表

读取后应能回答：

• 项目是做什么的？核心目标是什么？
• 用了什么技术栈？
• 有哪些核心模块/子系统？它们之间什么关系？
• 当前开发到什么阶段了？

第3步：guide/08-changelog.md — 了解最新进展

读取策略：

• 如果文件 <200 行：全部读取
• 如果文件 >200 行：只读取最新 2-3 个版本 + 底部 Checklist

提取信息：

• 最新版本做了什么改动（功能/修复/重构）
• 未完成的 TODO 项（- [ ] 标记的）
• 已知的紧急问题（🔴 标记的）

读取后应能回答：

• 最近做了什么？
• 还有什么没做完？哪些是紧急的？
• 上次修了什么 Bug？

第4步：guide/09-pitfalls.md — 避免重蹈覆辙

读取策略：

• 必读：文档末尾的「📋 通用开发原则」章节（这是最高优先级）
• 按需读：最近 5 条踩坑记录的标题和⚠️开发注意部分
• 如果即将修改某个子系统，搜索相关的坑记录

提取信息：

• 通用开发原则列表（直接作为开发约束使用）
• 已知的陷阱和规避方法
• 反复出现的问题模式

读取后应能回答：

• 开发时有哪些必须遵守的原则？
• 修改 XXX 时有什么需要注意的？
• 之前踩过什么坑？怎么解决的？

第5步：按需深入

根据用户的具体需求，选择性读取：

恢复模式选择