speccore 8.3.121 → 8.3.126

package/dist/commands/init.js

@@ -327,11 +327,12 @@ async function doInit(projectRoot, options, spinner) {
         spinner.stop('SpecCore initialized successfully!');
         logger_1.logger.info('');
         logger_1.logger.info('Next steps:');
-        logger_1.logger.info('  1. Edit .speccore/CONSTITUTION.md to define your tech stack');
-        logger_1.logger.info('  2. Edit .speccore/PROJECT/TEAM.md to add team members');
-        logger_1.logger.info('  3. Run: speccore analyze --scope global to analyze your codebase');
-        logger_1.logger.info('  4. Run: speccore iteration create --name=Q1 to start an iteration');
-        logger_1.logger.info('  5. Run: speccore doc2spec -f requirements.docx to import docs');
+        logger_1.logger.info('  1. 👀 View examples: .speccore/examples/config/CONSTITUTION-EXAMPLE.md');
+        logger_1.logger.info('  2. ✏️  Edit .speccore/CONSTITUTION.md to define your tech stack');
+        logger_1.logger.info('  3. 👥 Edit .speccore/PROJECT/TEAM.md to add team members');
+        logger_1.logger.info('  4. 🔬 Run: speccore analyze --scope global to analyze your codebase');
+        logger_1.logger.info('  5. 📁 Run: speccore iteration create --name=Q1 to start an iteration');
+        logger_1.logger.info('  6. 📄 Run: speccore doc2spec -f requirements.docx to import docs');
         logger_1.logger.info('');
         logger_1.logger.info('💡 WorkBuddy Integration: .workbuddy/ files created.');
         logger_1.logger.info('   Reopen this project in WorkBuddy to enable Speccore commands.');
@@ -364,6 +365,40 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 > 本文档是 SpecCore 与 AI 的**最高优先级契约**。analyze/split/execute 均据此执行。
 > AI 读取顺序：CONSTITUTION → context.json → 迭代目录
 
+## 字段对照总表
+
+> **AI 必读**：以下表格明确 CONSTITUTION.md 各字段与 PROJECT.yaml 的对应关系，以及每个字段的准确语义。请勿混淆。
+
+### 项目信息表字段
+
+| CONSTITUTION 列 | PROJECT.yaml 字段 | 语义说明 | 示例 |
+|:---|:---|:---|:---|
+| 工程标识 | \`name\` | 全局唯一技术标识，用于目录名、命令参数 | \`admin-web\`、\`backend-service\` |
+| 工程类型 | \`type\` | AI 据此生成针对性内容 | \`Java服务\`、\`H5移动端\` |
+| 工程名 | \`description\` | 人类可读的业务名称 | \`预订服务\`、\`后台管理\` |
+| 项目名称 | \`project_name\` | 给人和 AI 看的业务名称 | \`食堂后台管理\`、\`商户入驻系统\` |
+| 项目描述 | \`project_desc\` | 工程的详细说明、补充信息 | \`核心业务服务，处理订单全生命周期\` |
+| 工程源码路径 | \`code_path\` | 相对于项目根目录的代码位置 | \`./packages/backend\` |
+| **涉及需求端** | \`requirement_unit\` | **需求文档名称/标识，仅作 AI 参考，不做任何校验** | \`订单系统PRD\`、\`后台管理端需求文档\` |
+| 备注 | \`notes\` | 额外信息、特殊说明、TODO | \`核心业务\`、\`待上架\` |
+
+> ⚠️ **特别提醒 AI**：「涉及需求端」的值是**需求文档名**（如"订单系统PRD"），不是技术端标识（如 app/h5/admin）。技术端列表见下方「端列表」。
+
+### Git 配置表字段
+
+| CONSTITUTION 列 | PROJECT.yaml 字段 | 语义说明 | 示例 |
+|:---|:---|:---|:---|
+| Git 仓库 | \`git_repo\` | 仓库地址 | \`git@github.com:org/repo.git\` |
+| 默认分支 | \`default_branch\` | 默认分支名 | \`main\`、\`develop\` |
+| 保护分支 | \`protected_branches\` | 禁止直接 push 的分支列表 | \`main,release/*\` |
+| 分支前缀 | \`branch_prefix\` | 功能分支前缀 | \`feature/\`、\`feature/api-\` |
+
+### 公共默认值机制
+
+- 「Git 公共配置」章节定义公共默认值
+- 「Git 配置」表中用 \`—\` 表示使用该字段的公共默认值
+- 各工程只写和公共配置不同的字段
+
 ## 端列表（全局权威）
 
 > ⚠️ **工程标识是全项目唯一的端标识符**，所有命令（analyze/split/execute）、目录名（020-specs/{端}/）、模板目录（templates/{level}/{端}/）均使用此处声明的端名。
@@ -376,11 +411,11 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 | admin | 后台管理端 | Web管理后台 |
 
 > **端名规则**：
-> - 工程标识 = 工程名，一一对应（一个端 = 一个完整的服務/应用 = 一个 git 仓库）
+> - 工程标识 ≠ 工程名：工程标识是唯一技术标识（如 app/h5/admin），工程名是业务名称（如 "预订服务"）
 > - 全小写、无空格、用短横线分隔（如 order-service）
 > - 工程类型：AI 据此生成针对性内容（见下方工程类型枚举）
 > - 此列表是 analyze/split/execute 的唯一端名来源
-> - 「对应端」列引用此列表中的工程标识，每行只填一个
+> - 「对应需求端」列引用此列表中的工程标识，每行只填一个
 
 > **工程类型枚举**（可自定义）：
 > - 后端：Java服务 / Node服务 / Go服务 / Python服务
@@ -390,26 +425,111 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 
 ## 项目信息
 
-| 工程标识 | 项目名称 | 源码路径 | Git 仓库 | 默认分支 | 对应端 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| ${projectName} | 待填写 | ./ | ${gitUrl || '待配置'} | main | 待填写 |
+| 工程标识 | 工程类型 | 工程名 | 项目名称 | 项目描述 | 工程源码路径 | 涉及需求端 | 备注 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| ${projectName} | 待填写 | 待填写 | 待填写 | 待填写 | ./ | 待填写 | 待填写 |
 
-> ⚠️ **项目名称** 是给人和 AI 看的业务名称（如"食堂后台管理"、"商户入驻系统"），不同于技术上的工程标识。
->   AI 会据此理解项目业务范围，在分析/拆分/生成代码时作为上下文参考。
+> **字段说明**：
+> - **工程标识**：全局唯一技术标识（如 app/h5/admin），全小写、无空格、短横线分隔
+> - **工程类型**：AI 据此生成针对性内容（如 Java服务、H5移动端、Web管理后台）
+> - **工程名**：人类可读的业务名称（如 "预订服务"、"后台管理"）
+> - **项目名称**：给人和 AI 看的业务名称（如"食堂后台管理"、"商户入驻系统"）
+> - **项目描述**：工程的详细说明、补充信息（如"核心业务服务，处理订单全生命周期"）
+> - **工程源码路径**：相对于项目根目录的代码位置（如 ./packages/backend）
+> - **涉及需求端**：需求文档名称/标识，仅作参考（如"后台管理端需求文档"、"订单系统PRD"）。说明本工程大概会出现在哪些需求文档中
+> - **备注**：额外信息、特殊说明、TODO 等
 
 > 多工程示例（每个端 = 一个独立工程）:
 >
-> | 工程标识 | 项目名称 | 源码路径 | Git 仓库 | 默认分支 | 对应端 |
+> | 工程标识 | 工程类型 | 工程名 | 项目名称 | 项目描述 | 工程源码路径 | 涉及需求端 | 备注 |
+> | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+> | admin-web | Web管理后台 | admin | 后台管理端 | 运营后台管理系统 | ./packages/admin | 后台管理端需求文档 | 核心系统 |
+> | h5-app | H5移动端 | h5 | 移动H5端 | 用户端H5页面 | ./packages/h5 | 移动端需求文档 | 高优先级 |
+> | android-app | Android移动端 | android | Android端 | 原生Android APP | ./packages/android | APP端需求文档 | 待上架 |
+> | backend-service | Java服务 | backend | 后台服务 | 订单与支付核心服务 | ./packages/backend | 订单系统PRD | 核心业务 |
+>
+> **关键规则**：
+> - 「涉及需求端」仅作为 AI 参考上下文，说明工程与哪些需求文档相关，不做任何校验
+> - 一一对应：每行一个工程对应一个工程标识（不填多个）
+> - 如果一个服务拆成多个工程，应在「端列表」中分别声明
+
+## Git 公共配置
+
+> 公共默认值。各工程在「Git 配置」表中只写与公共配置不同的字段，未填写的字段自动使用此处默认值。
+> 用 \`—\` 表示使用公共默认值。
+
+### 默认配置
+
+| 默认分支 | 保护分支 |
+| :--- | :--- |
+| main | main,release/* |
+
+### 分支类型
+
+> 定义各种分支类型及其创建源分支。**分支名格式：\`{类型}/{前缀}{任务名}{后缀}\`**
+> - \`{类型}/\` = 类型自带（如 hotfix/、feature/）
+> - \`{前缀}\` = 任务名前的前缀（可选，**包含分隔符**），如 \`api-\`、\`backend_\`、\`v2.\`
+> - \`{任务名}\` = 如 Task-001-修复登录
+> - \`{后缀}\` = 任务名后的后缀（可选，**包含分隔符**），如 \`-urgent\`、\`_review\`
+>
+> ⚠️ **注意**：前缀/后缀的值请包含你想用的分隔符，代码不再自动添加任何符号。
+>
+> 示例 1（\`-\` 分隔）：前缀=\`api-\`、后缀=\`-urgent\` → 分支名=\`hotfix/api-Task-001-urgent\`
+> 示例 2（\`_\` 分隔）：前缀=\`api_\`、后缀=\`_urgent\` → 分支名=\`hotfix/api_Task-001_urgent\`
+> 示例 3（无分隔）：前缀=\`api\`、后缀=\`urgent\` → 分支名=\`hotfix/apiTask-001urgent\`
+
+| 类型 | 前缀（可选） | 后缀（可选） | 创建源 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| feature | — | — | develop | 新功能开发 |
+| bugfix | — | — | develop | 修复开发环境 Bug |
+| release | — | — | develop | 版本发布准备 |
+| hotfix | — | — | main | 生产环境紧急修复 |
+| support | — | — | main | 长期支持旧版本 |
+
+> **分支类型说明**：
+> - **分支名格式**：\`{类型}/{前缀}{任务名}{后缀}\`，前缀和后缀均可选
+> - **前缀列**：任务名前的前缀（**包含分隔符**），如 \`api-\`、\`backend_\`。不填则无
+> - **后缀列**：任务名后的后缀（**包含分隔符**），如 \`-urgent\`、\`_review\`。不填则无
+> - **feature**：日常功能开发，从 develop 创建，完成后合并回 develop
+> - **bugfix**：修复开发中的 Bug，从 develop 创建，完成后合并回 develop
+> - **release**：准备发布版本，从 develop 创建，完成后合并到 main + develop
+> - **hotfix**：生产环境紧急修复，从 main 创建，完成后合并到 main + develop
+> - **support**：长期支持旧版本，从 main 创建，用于维护历史版本
+> - 可自定义添加其他类型（如 refactor、docs、test 等）
+
+## Git 配置
+
+> 按工程标识对应。未配置的字段使用「Git 公共配置」中的默认值。
+
+| 工程标识 | Git 仓库 | 默认分支 | 保护分支 | 分支前缀 | 备注 |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| ${projectName} | ${gitUrl || '待配置'} | — | — | — | 待填写 |
+
+> **字段说明**：
+> - **工程标识**：引用「项目信息」表中的工程标识，一一对应
+> - **Git 仓库**：仓库地址（如 git@github.com:org/repo.git、https://...）
+> - **默认分支**：如 main、master、develop。填 \`—\` 表示使用公共默认值
+> - **保护分支**：禁止直接 push，只能通过 PR 合并（支持通配符如 release/*）。填 \`—\` 表示使用公共默认值
+> - **分支前缀**：功能分支前缀（如 feature/、bugfix/、hotfix/）。填 \`—\` 表示使用公共默认值
+> - **备注**：特殊 Git 策略说明
+
+> 多工程示例：
+>
+> | 工程标识 | Git 仓库 | 默认分支 | 保护分支 | 分支前缀 | 备注 |
 > | :--- | :--- | :--- | :--- | :--- | :--- |
-> | admin-web | 后台管理端 | ./packages/admin | git@xxx/admin.git | main | admin |
-> | h5-app | 移动H5端 | ./packages/h5 | git@xxx/h5.git | main | h5 |
-> | android-app | Android端 | ./packages/android | git@xxx/android.git | main | android |
-> | backend-service | 后台服务 | ./packages/backend | git@xxx/backend.git | main | backend |
+> | admin-web | git@xxx/admin.git | — | main,release/* | feature/admin- | 前端统一前缀 |
+> | h5-app | git@xxx/h5.git | — | — | feature/h5- | 使用公共默认 |
+> | backend-service | git@xxx/backend.git | develop | develop,release/* | feature/api- | 后端用 develop 分支 |
+>
+> 上例中：
+> - \`admin-web\`：默认分支使用公共 \`main\`，保护分支自定义 \`main,release/*\`
+> - \`h5-app\`：默认分支、保护分支均使用公共默认值，分支前缀自定义 \`feature/h5-\`
+> - \`backend-service\`：默认分支覆盖为 \`develop\`，保护分支覆盖为 \`develop,release/*\`
 >
 > **关键规则**：
-> - 「对应端」列的值必须引用「端列表」中已声明的端名
-> - 一一对应：每行一个工程对应一个端名（不填多个）
-> - 如果一个服务拆成多个工程（如 user-service + order-service 都属于 backend），应在「端列表」中分别声明
+> - 工程标识必须和「项目信息」表中的工程标识完全一致
+> - 用 \`—\`（ em dash ）表示使用该字段的公共默认值
+> - 保护分支支持精确匹配和通配符（如 release/*）
 
 ## 技术栈
 
@@ -438,12 +558,16 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 | ... | ... | ... |
 
 ## Git 分支策略
-- 默认分支: main  (可选: master / develop / trunk / release)
-- 任务分支: feature/{Task-ID}
-- 发布分支: release/{version}
-- 保护分支: main, master, release/*, production
-  > 保护分支上禁止直接 commit 和 push，只能通过 PR 合并
-  > 支持精确匹配和通配符（如 release/*）
+
+> 公共默认策略。各工程可在「Git 配置」表中覆盖。
+
+- **默认分支**: main（可选: master / develop / trunk）
+- **任务分支**: {branch_prefix}{Task-ID}（如 feature/Task-001）
+- **发布分支**: release/{version}
+- **热修复分支**: hotfix/{description}
+- **保护分支**: main, master, release/*, production
+  - 保护分支上禁止直接 commit 和 push，只能通过 PR 合并
+  - 支持精确匹配和通配符（如 release/*）
 `);
     } // if CONSTITUTION.md 不存在
     // PROJECT files
@@ -479,6 +603,8 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
     // .speccore/PROJECT.yaml — 项目配置（v8.3.25+）
     const projectName = require('path').basename(projectRoot);
     await (0, unified_config_1.initProjectConfig)(projectName);
+    // v8.3.115+: 生成示例配置文件，供用户仿照修改
+    await generateExampleConfigs(projectRoot);
     // Ask 引擎配置
     await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'config', 'ask.json'), JSON.stringify({
         routing: {
@@ -1462,7 +1588,13 @@ Iteration-NNN-name/            ← 迭代目录
 │       │       │   ├── created-at
 │       │       │   ├── estimated-hours ← 预估工时
 │       │       │   ├── feature       ← 功能单元名
-│       │       │   └── git-config    ← 子任务级 Git 配置
+│       │       │   └── git-config    ← 子任务级 Git 配置（v8.3.114+）
+│       │       │                         格式示例：
+│       │       │                           分支类型: hotfix
+│       │       │                           前缀: api-
+│       │       │                           后缀: urgent
+│       │       │                           源分支: main
+│       │       │                         → 分支名: hotfix/api-子任务名-urgent
 │       │       ├── TASK.md    ← 子任务追踪
 │       │       ├── TEST.md    ← 测试用例
 │       │       ├── RISK.md    ← 风险评估
@@ -1917,7 +2049,7 @@ async function checkUpgradeHints(projectRoot, speccoreDir) {
             const projShort = extractField('项目短名');
             const repo = extractField('代码仓库');
             // 替换整个"项目标识"章节为"项目信息"（从 ## 项目标识 到下一个 ## 之间）
-            updated = updated.replace(new RegExp('##\\s*\u9879\u76ee\u6807\u8bc6[\\s\\S]*?(?=##\\s|\\Z)'), `## 项目信息\n\n| 工程 | 项目名称 | 源码路径 | Git 仓库 | 默认分支 | 对应端 |\n| :--- | :--- | :--- | :--- | :--- | :--- |\n| ${projShort} | ${projName} | ./ | ${repo} | main | 待填写 |\n`);
+            updated = updated.replace(new RegExp('##\\s*\u9879\u76ee\u6807\u8bc6[\\s\\S]*?(?=##\\s|\\Z)'), `## 项目信息\n\n| 工程标识 | 工程类型 | 工程名 | 项目名称 | 源码路径 | Git 仓库 | 默认分支 | 对应需求端 |\n| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |\n| ${projShort} | 待填写 | 待填写 | ${projName} | ./ | ${repo} | main | 待填写 |\n`);
             migrations.push(`旧版「项目标识」纵向表 → 新版「项目信息」横向表（项目名称: ${projName}）`);
         }
         // ── 自动迁移：补充缺失的「保护分支」配置 ──
@@ -2152,4 +2284,356 @@ async function writeSetupGuide(projectRoot, _speccoreDir) {
     await (0, fs_extra_1.writeFile)(outputPath, html);
     return outputPath;
 }
+// ─────────────────────────────────────────
+// v8.3.115+: 生成示例配置文件
+// ─────────────────────────────────────────
+async function generateExampleConfigs(projectRoot) {
+    const examplesDir = (0, path_1.join)(projectRoot, '.speccore', 'examples');
+    const configDir = (0, path_1.join)(examplesDir, 'config');
+    await (0, fs_extra_1.ensureDir)(configDir);
+    // 示例目录 README
+    const readmeContent = `# SpecCore 示例目录
+
+> 本目录存放各类配置示例，供用户仿照修改。
+> 这些文件仅供人类参考，AI 不会读取。
+
+## 目录结构
+
+\`\`\`
+examples/
+├── README.md                    ← 本文件
+├── config/                      ← 配置文件示例
+│   ├── CONSTITUTION-EXAMPLE.md  ← CONSTITUTION.md 完整示例（多工程）
+│   ├── PROJECT-EXAMPLE.yaml     ← PROJECT.yaml 完整示例（多工程）
+│   ├── GIT-CONFIG-EXAMPLE.txt   ← 子任务 .meta/git-config 格式示例
+│   ├── DEPLOY-EXAMPLE.yaml      ← 部署配置示例（speccore deploy 使用）
+│   └── VERIFY-EXAMPLE.yaml      ← 测试验证配置示例（speccore verify 使用）
+└── project/                     ← 完整项目示例（预留，未来扩展）
+\`\`\`
+
+## 使用方式
+
+1. 查看 \`config/CONSTITUTION-EXAMPLE.md\`，仿照修改你的 \`.speccore/CONSTITUTION.md\`
+2. 查看 \`config/PROJECT-EXAMPLE.yaml\`，了解 YAML 结构和字段对应关系
+3. 查看 \`config/GIT-CONFIG-EXAMPLE.txt\`，了解子任务级 Git 配置格式
+4. 查看 \`config/DEPLOY-EXAMPLE.yaml\`，了解部署配置格式（用于 \`speccore deploy\`）
+5. 查看 \`config/VERIFY-EXAMPLE.yaml\`，了解测试验证配置格式（用于 \`speccore verify --config\`）
+6. 修改后运行 \`speccore update\` 自动同步到 PROJECT.yaml
+
+## 注意事项
+
+- 示例文件中的值为演示用途，请根据实际项目修改
+- 示例文件更新随 CLI 版本升级，如需最新示例可重新运行 \`speccore init\`
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(examplesDir, 'README.md'), readmeContent);
+    // CONSTITUTION.md 完整示例（多工程）
+    const constitutionExample = `## 字段对照总表
+
+> **AI 必读**：以下表格明确 CONSTITUTION.md 各字段与 PROJECT.yaml 的对应关系。
+> 人类只需填写 CONSTITUTION.md，PROJECT.yaml 由 CLI 自动生成/同步。
+
+### 项目信息表字段
+
+| CONSTITUTION 列 | PROJECT.yaml 字段 | 语义说明 | 示例 |
+|:---|:---|:---|:---|
+| 工程标识 | \`name\` | 全局唯一技术标识 | \`admin-web\` |
+| 工程类型 | \`type\` | AI 据此生成针对性内容 | \`Java服务\` |
+| 工程名 | \`description\` | 人类可读的业务名称 | \`预订服务\` |
+| 项目名称 | \`project_name\` | 给人和 AI 看的业务名称 | \`食堂后台管理\` |
+| 项目描述 | \`project_desc\` | 工程的详细说明 | \`核心业务服务...\` |
+| 工程源码路径 | \`code_path\` | 相对项目根目录 | \`./packages/backend\` |
+| **涉及需求端** | \`requirement_unit\` | **需求文档名称/标识，仅作 AI 参考** | \`订单系统PRD\` |
+| 备注 | \`notes\` | 额外信息 | \`核心业务\` |
+
+### Git 配置表字段
+
+| CONSTITUTION 列 | PROJECT.yaml 字段 | 语义说明 | 示例 |
+|:---|:---|:---|:---|
+| Git 仓库 | \`git_repo\` | 仓库地址 | \`git@github.com:org/repo.git\` |
+| 默认分支 | \`default_branch\` | 默认分支名 | \`main\`、\`develop\` |
+| 保护分支 | \`protected_branches\` | 禁止直接 push 的分支列表 | \`main,release/*\` |
+
+### 公共默认值机制
+
+- 「Git 公共配置」章节定义公共默认值
+- 「Git 配置」表中用 \`—\` 表示使用该字段的公共默认值
+- 各工程只写和公共配置不同的字段
+
+---
+
+## 端列表（全局权威）
+
+> ⚠️ **工程标识是全项目唯一的端标识符**，所有命令（analyze/split/execute）、目录名（020-specs/{端}/）、模板目录（templates/{level}/{端}/）均使用此处声明的端名。
+
+| 工程标识 | 描述 | 工程类型 |
+| :--- | :--- | :--- |
+| admin-web | 后台管理端 | Web管理后台 |
+| h5-mobile | 移动 H5 端 | H5移动端 |
+| miniapp | 小程序端 | 微信小程序 |
+| backend-api | 后台 API 服务 | Java服务 |
+
+> **端名规则**：
+> - 工程标识 ≠ 工程名：工程标识是唯一技术标识（如 admin-web），工程名是业务名称（如 "预订服务"）
+> - 全小写、无空格、用短横线分隔（如 order-service）
+> - 工程类型：AI 据此生成针对性内容（见下方工程类型枚举）
+> - 此列表是 analyze/split/execute 的唯一端名来源
+
+---
+
+## 项目信息
+
+| 工程标识 | 工程类型 | 工程名 | 项目名称 | 项目描述 | 工程源码路径 | 涉及需求端 | 备注 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| admin-web | Web管理后台 | 后台管理 | 运营后台 | 运营人员使用的后台管理系统 | ./packages/admin | 后台管理端需求文档 | 核心系统 |
+| h5-mobile | H5移动端 | H5商城 | 移动商城 | 用户端H5购物页面 | ./packages/h5 | 移动端需求文档 | 高优先级 |
+| miniapp | 微信小程序 | 小程序 | 微信小程序 | 微信内嵌小程序商城 | ./packages/miniapp | 小程序端需求文档 | 待上架 |
+| backend-api | Java服务 | 订单服务 | 订单与支付 | 订单创建、支付、退款核心服务 | ./packages/backend | 订单系统PRD | 核心业务 |
+
+> **字段说明**：
+> - **工程标识**：全局唯一技术标识（如 admin-web），全小写、无空格、短横线分隔
+> - **工程类型**：AI 据此生成针对性内容（如 Java服务、H5移动端、Web管理后台）
+> - **工程名**：人类可读的业务名称（如 "预订服务"、"后台管理"）
+> - **项目名称**：给人和 AI 看的业务名称（如"食堂后台管理"、"商户入驻系统"）
+> - **项目描述**：工程的详细说明、补充信息（如"核心业务服务，处理订单全生命周期"）
+> - **工程源码路径**：相对于项目根目录的代码位置（如 ./packages/backend）
+> - **涉及需求端**：需求文档名称/标识，仅作 AI 参考（如"后台管理端需求文档"、"订单系统PRD"）。说明本工程大概会出现在哪些需求文档中
+> - **备注**：额外信息、特殊说明、TODO 等
+
+---
+
+## Git 公共配置
+
+> 公共默认值。各工程在「Git 配置」表中只写与公共配置不同的字段，未填写的字段自动使用此处默认值。
+> 用 \`—\` 表示使用公共默认值。
+
+### 默认配置
+
+| 默认分支 | 保护分支 |
+| :--- | :--- |
+| main | main,release/* |
+
+### 分支类型
+
+> 定义各种分支类型及其创建源分支。**分支名格式：\`{类型}/{前缀}-{任务名}-{后缀}\`**
+> - \`{类型}/\` = 类型自带（如 hotfix/、feature/）
+> - \`{前缀}\` = 任务名前的前缀（可选）
+> - \`{任务名}\` = 如 Task-001-修复登录
+> - \`{后缀}\` = 任务名后的后缀（可选）
+>
+> 示例：配置了前缀 \`api-\`、后缀 \`-urgent\`，任务名为 \`Task-001\`，则分支名为 \`hotfix/api-Task-001-urgent\`
+
+| 类型 | 前缀（可选） | 后缀（可选） | 创建源 | 说明 |
+| :--- | :--- | :--- | :--- | :--- |
+| feature | — | — | develop | 新功能开发 |
+| bugfix | — | — | develop | 修复开发环境 Bug |
+| release | — | — | develop | 版本发布准备 |
+| hotfix | — | — | main | 生产环境紧急修复 |
+| support | — | — | main | 长期支持旧版本 |
+
+> **分支类型说明**：
+> - **分支名格式**：\`{类型}/{前缀}-{任务名}-{后缀}\`，前缀和后缀均可选
+> - **前缀列**：任务名前的前缀（如 \`api-\`、\`backend-\`），不填则无
+> - **后缀列**：任务名后的后缀（如 \`-urgent\`、\`-review\`），不填则无
+> - **feature**：日常功能开发，从 develop 创建，完成后合并回 develop
+> - **bugfix**：修复开发中的 Bug，从 develop 创建，完成后合并回 develop
+> - **release**：准备发布版本，从 develop 创建，完成后合并到 main + develop
+> - **hotfix**：生产环境紧急修复，从 main 创建，完成后合并到 main + develop
+> - **support**：长期支持旧版本，从 main 创建，用于维护历史版本
+> - 可自定义添加其他类型（如 refactor、docs、test 等）
+
+---
+
+## Git 配置
+
+> 按工程标识对应。未配置的字段使用「Git 公共配置」中的默认值。
+> 用 \`—\` 表示使用公共默认值。
+
+| 工程标识 | Git 仓库 | 默认分支 | 保护分支 | 分支前缀 | 备注 |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| admin-web | git@github.com:myorg/admin-web.git | — | — | — | 核心系统 |
+| h5-mobile | git@github.com:myorg/h5-mobile.git | — | — | — | 高优先级 |
+| miniapp | git@github.com:myorg/miniapp.git | — | — | — | 待上架 |
+| backend-api | git@github.com:myorg/backend.git | — | — | — | 核心业务 |
+
+> **字段说明**：
+> - **工程标识**：引用「项目信息」表中的工程标识，一一对应
+> - **Git 仓库**：仓库地址（如 git@github.com:org/repo.git、https://...）
+> - **默认分支**：如 main、master、develop。填 \`—\` 表示使用公共默认值
+> - **保护分支**：禁止直接 push，只能通过 PR 合并（支持通配符如 release/*）。填 \`—\` 表示使用公共默认值
+> - **分支前缀**：功能分支前缀（如 feature/）。填 \`—\` 表示使用公共默认值
+> - **备注**：额外说明
+
+---
+
+> 📌 **使用说明**：
+> 1. 复制本示例内容到 \`CONSTITUTION.md\`，根据实际项目修改
+> 2. 修改后运行 \`speccore update\` 自动同步到 PROJECT.yaml
+> 3. 子任务目录下的 \`.meta/git-config\` 可覆盖全局配置（见目录结构说明）
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'CONSTITUTION-EXAMPLE.md'), constitutionExample);
+    // PROJECT.yaml 完整示例（多工程）
+    const projectExample = `# PROJECT.yaml — 项目配置（由 CLI 自动生成，不建议手动编辑）
+# 如需修改，请编辑 CONSTITUTION.md 后运行 speccore update
+# ─────────────────────────────────────────────────────────────────────────────
+
+schema_version: 1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 项目基本信息
+# ─────────────────────────────────────────────────────────────────────────────
+project:
+  # 项目名称（全局标识）
+  name: my-project
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 端列表（每个端 = 一个独立工程）
+# ─────────────────────────────────────────────────────────────────────────────
+# 工程标识：全小写、无空格、短横线分隔，全局唯一
+# 工程类型：AI 据此生成针对性内容（Java服务/H5移动端/Web管理后台等）
+# code_path：相对于项目根目录的源码位置
+# project_name：给人和 AI 看的业务名称
+# project_desc：工程的详细说明
+# requirement_unit：需求文档名称/标识，仅作 AI 参考，不做校验
+# notes：额外信息
+# ─────────────────────────────────────────────────────────────────────────────
+platforms:
+  - name: admin-web
+    type: Web管理后台
+    description: 后台管理
+    code_path: ./packages/admin
+    project_name: 运营后台
+    project_desc: 运营人员使用的后台管理系统
+    requirement_unit: 后台管理端需求文档
+    notes: 核心系统
+
+  - name: h5-mobile
+    type: H5移动端
+    description: H5商城
+    code_path: ./packages/h5
+    project_name: 移动商城
+    project_desc: 用户端H5购物页面
+    requirement_unit: 移动端需求文档
+    notes: 高优先级
+
+  - name: miniapp
+    type: 微信小程序
+    description: 小程序
+    code_path: ./packages/miniapp
+    project_name: 微信小程序
+    project_desc: 微信内嵌小程序商城
+    requirement_unit: 小程序端需求文档
+    notes: 待上架
+
+  - name: backend-api
+    type: Java服务
+    description: 订单服务
+    code_path: ./packages/backend
+    project_name: 订单与支付
+    project_desc: 订单创建、支付、退款核心服务
+    requirement_unit: 订单系统PRD
+    notes: 核心业务
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Git 配置
+# ─────────────────────────────────────────────────────────────────────────────
+# default_base：默认基础分支（PR 合并目标）
+# branch_prefix：功能分支前缀
+# protected_branches：受保护分支（禁止直接 push，只能通过 PR 合并）
+# branch_types：分支类型定义
+#   - 类型名自带前缀（如 hotfix/、feature/）
+#   - prefix：任务名前的前缀（可选），如 api-、backend-
+#   - suffix：任务名后的后缀（可选），如 urgent、review
+#   - source：创建源分支，如 develop、main
+# ─────────────────────────────────────────────────────────────────────────────
+git:
+  # 默认基础分支（PR 合并目标）
+  default_base: main
+  # 功能分支前缀
+  branch_prefix: feature/
+  # 受保护分支（禁止直接 push，只能通过 PR 合并）
+  protected_branches:
+    - main
+    - master
+  # 分支类型定义。prefix=任务前前缀, suffix=任务后后缀, 均可选
+  branch_types:
+    feature:
+      source: develop
+    bugfix:
+      source: develop
+    release:
+      source: develop
+    hotfix:
+      source: main
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 代码扫描范围
+# ─────────────────────────────────────────────────────────────────────────────
+# AI 全局分析时扫描的源码目录
+# ─────────────────────────────────────────────────────────────────────────────
+code_scope:
+  - src/
+
+# ─────────────────────────────────────────────────────────────────────────────
+# 端级 Git 覆盖示例（如需为某个端单独配置）
+# ─────────────────────────────────────────────────────────────────────────────
+# 在 platforms 对应端下增加以下字段：
+#   default_branch: develop    # 覆盖全局 git.default_base
+#   branch_prefix: hotfix/     # 覆盖全局 git.branch_prefix
+#   protected_branches:        # 覆盖全局 git.protected_branches
+#     - main
+#   branch_types:              # 覆盖/扩展全局 git.branch_types
+#     hotfix:
+#       prefix: api-
+#       suffix: urgent
+#       source: main
+# ─────────────────────────────────────────────────────────────────────────────
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'PROJECT-EXAMPLE.yaml'), projectExample);
+    // 子任务 git-config 示例
+    const gitConfigExample = `# 子任务级 Git 配置示例（.meta/git-config）
+# ─────────────────────────────────────────────────────────────────────────────
+# 配置优先级：子任务 > 迭代级 > 全局 CONSTITUTION.md > 默认值
+# 未配置的字段自动从上级继承
+# ─────────────────────────────────────────────────────────────────────────────
+
+# 分支类型：覆盖默认 feature（如 hotfix、bugfix、release）
+分支类型: hotfix
+
+# 前缀：任务名前的前缀（可选），如 api-、backend-
+前缀: api-
+
+# 后缀：任务名后的后缀（可选），如 urgent、review
+后缀: urgent
+
+# 源分支：从哪个分支创建（如 main、develop）
+源分支: main
+
+# 分支格式：自定义分支名模板（可选，一般不配置）
+# 支持变量: {type} {prefix} {taskId} {name} {date} {hash4}
+# 分支格式: {type}/{prefix}{taskId}
+
+# 自动拉取：创建分支前是否自动 git pull（true/false）
+自动拉取: false
+
+# 远程名称：远程仓库名称（默认 origin）
+远程名称: origin
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'GIT-CONFIG-EXAMPLE.txt'), gitConfigExample);
+    // v8.3.122+: 复制部署和测试示例配置文件
+    const templateDir = (0, path_1.join)(__dirname, '..', '..', 'templates');
+    const deployExampleSrc = (0, path_1.join)(templateDir, 'deploy-examples.yaml');
+    const verifyExampleSrc = (0, path_1.join)(templateDir, 'verify-spec-example.yaml');
+    try {
+        if (await (0, fs_extra_1.pathExists)(deployExampleSrc)) {
+            const deployContent = await (0, fs_extra_1.readFile)(deployExampleSrc, 'utf-8');
+            await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'DEPLOY-EXAMPLE.yaml'), deployContent);
+        }
+        if (await (0, fs_extra_1.pathExists)(verifyExampleSrc)) {
+            const verifyContent = await (0, fs_extra_1.readFile)(verifyExampleSrc, 'utf-8');
+            await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'VERIFY-EXAMPLE.yaml'), verifyContent);
+        }
+    }
+    catch { /* 模板文件可选 */ }
+    logger_1.logger.info('   📋 已生成示例配置: .speccore/examples/');
+}
 //# sourceMappingURL=init.js.map