project_initialization

Project Initialization Guide — 项目AI辅助体系初始化指南

重要说明: 本文件是AI执行初始化的操作手册，不是给人类阅读的文档。

触发方式:

• 方式1: 用户说"按project_initialization skill初始化本项目"
• 方式2: 用户说"阅读AI_INIT_GUIDE.md并执行"
• 方式3: AI检测到{{DIR}}/rules/目录下文件为空或包含占位符时主动建议

Phase 0: 检测当前状态

首先检查项目当前状态：

1. 读取配置文件

   • 检查 {{DIR}}/scripts/gen_references.py 是否存在
   • 检查 {{DIR}}/references/_scan.json 是否已生成
   • 判断是"首次初始化"还是"增量更新"

2. 检查模板完整性

   • 如果检测到 project_rule.md 中仍有 "Define XXX here" 等占位符
   • 说明之前未完成初始化，应重新执行完整流程

3. 确认CodeGraph状态

   • 运行 codegraph --version (3秒超时)
   • 如果未安装，执行 Phase 0.4 询问用户是否安装
   • 记录结果用于后续决策

输出检测结果：

📋 初始化状态检测:
- gen_references.py: [存在/缺失]
- _scan.json: [已生成/未生成]
- CodeGraph CLI: [已安装/未安装]
- 初始化类型: [首次初始化/增量更新]

Phase 0.4: CodeGraph 安装提示（仅当未安装时执行）

如果Phase 0.3检测到CodeGraph未安装，询问用户：

⚙️  检测到 CodeGraph CLI 未安装

CodeGraph 是一个代码关系图工具，可为 AI 提供项目结构探索能力（类/方法/符号搜索）。
安装后可减少约 90% 的 AI 工具调用，使 references/ 目录采用轻量模式。

是否现在安装 CodeGraph？
  1. ✅ 是，安装并配置（推荐）
  2. ❌ 否，跳过（将使用完整模式）

选择 1 → 执行 Phase 0.4.1 安装流程
选择 2 → 设置 HAS_CODEGRAPH = false，references/ 采用完整模式

Phase 0.4.1: CodeGraph 安装流程

用户选择安装后，执行以下步骤：

Step 1: 安装 CodeGraph CLI
  执行: npx @colbymchenry/codegraph
  
Step 2: 验证安装
  执行: codegraph --version
  成功 → HAS_CODEGRAPH = true
  失败 → 显示错误信息，询问用户是否继续（降级为完整模式）
  
Step 3: 初始化 CodeGraph（必须执行）
  说明: CodeGraph 必须在项目中建立索引才能使用
  执行: codegraph init
  等待初始化完成...
  
  如果初始化成功:
    → CodeGraph 已就绪，使用轻量模式
    → 继续后续流程
  
  如果初始化失败:
    → 显示错误信息
    → 询问用户: "CodeGraph 初始化失败，是否降级为完整模式？"
      - 是 → HAS_CODEGRAPH = false，使用完整模式
      - 否 → 中止初始化流程，让用户手动解决问题

安装成功后设置 HAS_CODEGRAPH = true，影响后续行为：

• project_rule.md §1 行为准则使用 CodeGraph 版本
• {{ENTRY}} 入口文件追加 CodeGraph 集成说明
• gen_references.py 使用 --lightweight 标志
• references/ 采用轻量模式

安装失败不阻塞流程，降级为完整模式继续。

Phase 1: 项目深度分析

1.1 运行结构扫描器（带 CodeGraph 验证）

关键步骤: 在执行扫描前，必须验证 CodeGraph 是否真正可用

如果 HAS_CODEGRAPH = true:
  Step A: 验证 CodeGraph 可用性
    执行: codegraph explore "test" --limit 1 2>/dev/null
    
    如果成功:
      → CodeGraph 可用 ✅
      执行: python {{DIR}}/scripts/gen_references.py --lightweight
      
    如果失败:
      → CodeGraph 不可用 ️
      自动降级: HAS_CODEGRAPH = false
      提示: "⚠️ CodeGraph 未正确初始化或不可用，已降级为完整模式"
      执行: python {{DIR}}/scripts/gen_references.py
      
如果 HAS_CODEGRAPH = false:
  直接执行: python {{DIR}}/scripts/gen_references.py