dev-playbooks-cn 1.0.3 → 1.0.5

package/bin/devbooks.js

@@ -8,9 +8,13 @@
  * 用法：
  *   dev-playbooks-cn init [path] [options]
  *   dev-playbooks-cn update [path]
+ *   dev-playbooks-cn migrate --from <framework> [options]
  *
  * 选项：
  *   --tools <tools>    非交互式指定 AI 工具：all, none, 或逗号分隔的列表
+ *   --from <framework> 迁移来源框架：openspec, speckit
+ *   --dry-run          模拟运行，不实际修改文件
+ *   --keep-old         迁移后保留原目录
  *   --help             显示帮助信息
  */
 
@@ -18,6 +22,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
 import { checkbox, confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import ora from 'ora';
@@ -887,6 +892,82 @@ async function updateCommand(projectDir) {
   console.log(chalk.green('✓') + ' 更新完成！');
 }
 
+// ============================================================================
+// Migrate 命令
+// ============================================================================
+
+async function migrateCommand(projectDir, options) {
+  console.log();
+  console.log(chalk.bold('DevBooks 迁移工具'));
+  console.log();
+
+  const { from, dryRun, keepOld, force } = options;
+
+  if (!from) {
+    console.log(chalk.red('✗') + ' 请指定迁移来源框架：--from openspec 或 --from speckit');
+    console.log();
+    console.log(chalk.cyan('示例:'));
+    console.log(`  ${CLI_COMMAND} migrate --from openspec`);
+    console.log(`  ${CLI_COMMAND} migrate --from speckit`);
+    console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run`);
+    process.exit(1);
+  }
+
+  const validFrameworks = ['openspec', 'speckit'];
+  if (!validFrameworks.includes(from)) {
+    console.log(chalk.red('✗') + ` 不支持的框架: ${from}`);
+    console.log(chalk.gray(`  支持的框架: ${validFrameworks.join(', ')}`));
+    process.exit(1);
+  }
+
+  // 确定脚本路径
+  const scriptName = from === 'openspec' ? 'migrate-from-openspec.sh' : 'migrate-from-speckit.sh';
+  const scriptPath = path.join(__dirname, '..', 'scripts', scriptName);
+
+  if (!fs.existsSync(scriptPath)) {
+    console.log(chalk.red('✗') + ` 迁移脚本不存在: ${scriptPath}`);
+    process.exit(1);
+  }
+
+  // 构建参数
+  const args = ['--project-root', projectDir];
+  if (dryRun) args.push('--dry-run');
+  if (keepOld) args.push('--keep-old');
+  if (force) args.push('--force');
+
+  console.log(chalk.blue('ℹ') + ` 迁移来源: ${from}`);
+  console.log(chalk.blue('ℹ') + ` 项目目录: ${projectDir}`);
+  if (dryRun) console.log(chalk.yellow('ℹ') + ' 模式: DRY-RUN（模拟运行）');
+  console.log();
+
+  // 执行脚本
+  return new Promise((resolve, reject) => {
+    const child = spawn('bash', [scriptPath, ...args], {
+      stdio: 'inherit',
+      cwd: projectDir
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        console.log();
+        if (!dryRun) {
+          console.log(chalk.green('✓') + ' 迁移完成！');
+          console.log();
+          console.log(chalk.bold('下一步：'));
+          console.log(`  运行 ${chalk.cyan(`${CLI_COMMAND} init`)} 安装 DevBooks Skills`);
+        }
+        resolve();
+      } else {
+        reject(new Error(`迁移脚本退出码: ${code}`));
+      }
+    });
+
+    child.on('error', (err) => {
+      reject(new Error(`执行迁移脚本失败: ${err.message}`));
+    });
+  });
+}
+
 // ============================================================================
 // 帮助信息
 // ============================================================================
@@ -896,12 +977,17 @@ function showHelp() {
   console.log(chalk.bold('DevBooks') + ' - AI-agnostic spec-driven development workflow');
   console.log();
   console.log(chalk.cyan('用法:'));
-  console.log(`  ${CLI_COMMAND} init [path] [options]    初始化 DevBooks`);
-  console.log(`  ${CLI_COMMAND} update [path]            更新已配置的工具`);
+  console.log(`  ${CLI_COMMAND} init [path] [options]              初始化 DevBooks`);
+  console.log(`  ${CLI_COMMAND} update [path]                      更新已配置的工具`);
+  console.log(`  ${CLI_COMMAND} migrate --from <framework> [opts]  从其他框架迁移`);
   console.log();
   console.log(chalk.cyan('选项:'));
   console.log('  --tools <tools>    非交互式指定 AI 工具');
   console.log('                     可用值: all, none, 或逗号分隔的工具 ID');
+  console.log('  --from <framework> 迁移来源框架 (openspec, speckit)');
+  console.log('  --dry-run          模拟运行，不实际修改文件');
+  console.log('  --keep-old         迁移后保留原目录');
+  console.log('  --force            强制重新执行所有步骤');
   console.log('  -h, --help         显示此帮助信息');
   console.log();
   console.log(chalk.cyan('支持的 AI 工具:'));
@@ -943,6 +1029,9 @@ function showHelp() {
   console.log(`  ${CLI_COMMAND} init my-project             # 在 my-project 目录初始化`);
   console.log(`  ${CLI_COMMAND} init --tools claude,cursor  # 非交互式`);
   console.log(`  ${CLI_COMMAND} update                      # 更新已配置的工具`);
+  console.log(`  ${CLI_COMMAND} migrate --from openspec     # 从 OpenSpec 迁移`);
+  console.log(`  ${CLI_COMMAND} migrate --from speckit      # 从 spec-kit 迁移`);
+  console.log(`  ${CLI_COMMAND} migrate --from openspec --dry-run  # 模拟迁移`);
 }
 
 // ============================================================================
@@ -965,6 +1054,14 @@ async function main() {
       process.exit(0);
     } else if (arg === '--tools') {
       options.tools = args[++i];
+    } else if (arg === '--from') {
+      options.from = args[++i];
+    } else if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg === '--keep-old') {
+      options.keepOld = true;
+    } else if (arg === '--force') {
+      options.force = true;
     } else if (!arg.startsWith('-')) {
       if (!command) {
         command = arg;
@@ -983,6 +1080,8 @@ async function main() {
       await initCommand(projectDir, options);
     } else if (command === 'update') {
       await updateCommand(projectDir);
+    } else if (command === 'migrate') {
+      await migrateCommand(projectDir, options);
     } else {
       console.log(chalk.red(`未知命令: ${command}`));
       showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/skills/devbooks-brownfield-bootstrap/SKILL.md

@@ -21,18 +21,75 @@ tools:
 
 - `<truth-root>`：当前真理目录根
 - `<change-root>`：变更包目录根
+- `<devbooks-root>`：DevBooks 管理目录（通常是 `dev-playbooks/`）
 
 执行前**必须**按以下顺序查找配置（找到后停止）：
 1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
 2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
 4. `project.md`（如存在）→ template 协议，使用默认映射
-5. 若仍无法确定 → **停止并询问用户**
+5. 若仍无法确定 → **创建 DevBooks 目录结构并初始化基础配置**
 
 **关键约束**：
 - 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
 - 禁止猜测目录根
 - 禁止跳过规则文档阅读
 
+---
+
+## 核心职责
+
+存量项目初始化包含以下职责：
+
+### 1. 基础配置文件初始化（新增）
+
+在 `<devbooks-root>/`（通常是 `dev-playbooks/`）下检查并创建：
+
+| 文件 | 用途 | 创建条件 |
+|------|------|----------|
+| `constitution.md` | 项目宪法（GIP 原则） | 文件不存在时 |
+| `project.md` | 项目上下文（技术栈/约定） | 文件不存在时 |
+
+**创建方式**：
+- **不是简单复制模板**，而是根据代码分析结果定制内容
+- `constitution.md`：基于默认 GIP 原则，可根据项目特性调整
+- `project.md`：根据代码分析结果填充：
+  - 技术栈（语言/框架/数据库）
+  - 开发约定（代码风格/测试策略/Git 工作流）
+  - 领域上下文（核心概念/角色定义）
+  - 目录根映射
+
+### 2. 项目画像与元数据
+
+在 `<truth-root>/_meta/` 下生成：
+
+| 产物 | 路径 | 说明 |
+|------|------|------|
+| 项目画像 | `_meta/project-profile.md` | 三层架构的详细技术画像 |
+| 术语表 | `_meta/glossary.md` | 统一语言表（可选但推荐） |
+| 领域概念 | `_meta/key-concepts.md` | CKB 提取的概念（增强模式） |
+
+### 3. 架构分析产物
+
+在 `<truth-root>/architecture/` 下生成：
+
+| 产物 | 路径 | 数据来源 |
+|------|------|----------|
+| 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
+| 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
+
+### 4. 基线变更包
+
+在 `<change-root>/<baseline-id>/` 下生成：
+
+| 产物 | 说明 |
+|------|------|
+| `proposal.md` | 基线范围、In/Out、风险 |
+| `design.md` | 现状盘点（capability inventory） |
+| `specs/<cap>/spec.md` | 基线 spec deltas（ADDED 为主） |
+| `verification.md` | 最小验证锚点计划 |
+
+---
+
 ## COD 模型生成（Code Overview & Dependencies）
 
 在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
@@ -101,15 +158,19 @@ tools:
 
 ### 检测流程
 
-1. 检测 `<truth-root>/` 是否为空或基本为空
-2. 检测 CKB 索引是否可用
-3. 检测项目规模和语言栈
+1. 检测 `<devbooks-root>/constitution.md` 是否存在
+2. 检测 `<devbooks-root>/project.md` 是否存在
+3. 检测 `<truth-root>/` 是否为空或基本为空
+4. 检测 CKB 索引是否可用
+5. 检测项目规模和语言栈
 
 ### 本 Skill 支持的模式
 
 | 模式 | 触发条件 | 行为 |
 |------|----------|------|
-| **完整初始化** | truth-root 为空 | 生成所有基础产物 |
+| **全新初始化** | devbooks-root 不存在或为空 | 创建完整目录结构 + constitution + project + 画像 |
+| **补充配置** | constitution/project 缺失 | 只补充缺失的配置文件 |
+| **完整初始化** | truth-root 为空 | 生成所有基础产物（画像/基线/验证） |
 | **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
 | **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
 | **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
@@ -118,10 +179,13 @@ tools:
 
 ```
 检测结果：
+- devbooks-root：存在
+- constitution.md：不存在 → 将创建
+- project.md：不存在 → 将创建
 - truth-root：为空
 - CKB 索引：可用
 - 项目规模：中型（~50K LOC）
-- 运行模式：完整初始化 + 增强模式
+- 运行模式：补充配置 + 完整初始化 + 增强模式
 ```
 
 ---

package/skills/devbooks-brownfield-bootstrap/references//345/255/230/351/207/217/351/241/271/347/233/256/345/210/235/345/247/213/345/214/226/346/217/220/347/244/272/350/257/215.md

@@ -6,18 +6,20 @@
 - 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
 
 目录根（强制）：
-- 在写任何文件前，必须先确定 `<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
-- 若存在 `dev-playbooks/project.md`（或目录 `dev-playbooks/`）：视为 DevBooks 项目，默认：
+- 在写任何文件前，必须先确定 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
+- 若存在 `dev-playbooks/` 目录：视为 DevBooks 项目，默认：
+  - `<devbooks-root>` = `dev-playbooks/`
   - `<truth-root>` = `dev-playbooks/specs`
   - `<change-root>` = `dev-playbooks/changes`
-  - 必须先阅读 `dev-playbooks/project.md`（如存在）并遵循其中说明。
-- 否则：必须先询问用户确认 `<truth-root>` 与 `<change-root>`；用户未确认不得落盘。
+  - 如存在 `dev-playbooks/project.md`：必须先阅读并遵循其中说明。
+- 否则：必须先询问用户确认目录根；用户未确认不得落盘。
 
-你是“存量项目初始化负责人（Brownfield Bootstrapper）”。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
-1) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
-2) 现状规格基线（baseline specs，以 ADDED 为主）
+你是"存量项目初始化负责人（Brownfield Bootstrapper）"。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
+1) **基础配置文件**（constitution.md、project.md）
+2) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
+3) 现状规格基线（baseline specs，以 ADDED 为主）
 
-最终效果：后续任何变更都能像“项目从一开始就按规格化流程开发”一样，有稳定真理源、稳定落点与可验证锚点。
+最终效果：后续任何变更都能像"项目从一开始就按规格化流程开发"一样，有稳定真理源、稳定落点与可验证锚点。
 
 输入材料（由我提供）：
 - 代码库（只读分析，允许运行只读命令）
@@ -26,6 +28,9 @@
 - 我指定的基线范围（对外契约优先/关键链路优先/模块边界优先）
 
 产物目标（目录约定，协议无关）：
+- **基础配置文件**（如缺失则创建）：
+  - `<devbooks-root>/constitution.md`：项目宪法（GIP 原则）
+  - `<devbooks-root>/project.md`：项目上下文（技术栈/约定/领域）
 - 项目画像（当前真理的一部分）：
   - `<truth-root>/_meta/project-profile.md`
 - 统一语言表（可选但推荐）：
@@ -33,21 +38,83 @@
 - 变更包：`<change-root>/<baseline-id>/`
   - `proposal.md`：基线范围、为什么先做基线、In/Out、风险与未知
   - `design.md`（可选但推荐）：现状盘点（capability inventory）与边界/依赖方向
-  - `<truth-root>/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
+  - `specs/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
   - `verification.md`：最小验证锚点计划 + 追溯矩阵 + MANUAL-*
-- 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续“归档/合并”动作把基线变更合并进去）
+- 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续"归档/合并"动作把基线变更合并进去）
 
 硬约束（必须遵守）：
 1) **只写现状，不做重构**：本次初始化不引入行为变化建议，不输出实现计划。
 2) **基线 delta 以 ADDED 为主**：当 `<truth-root>/` 为空时，优先只写 ADDED，避免 MODIFIED/RENAMED/REMOVED（这些通常要求已有当前真理）。
 3) **delta 格式必须匹配项目所用协议的校验器**：
-   - 先在仓库里查找“delta 标题/场景标题”的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
+   - 先在仓库里查找"delta 标题/场景标题"的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
    - 若仍不确定：不要臆测；在 `<truth-root>/_meta/project-profile.md` 标注 `TBD` 并给出验证动作（例如运行协议的 validate 命令）
 4) **证据优先**：任何不确定的地方必须标注 `TBD`，并在 `verification.md` 写清验证动作；禁止臆测补齐。
 5) **MECE 聚类**：capability 控制在 3–8 个；每个 capability 的 Requirements 控制在 3–15 条（先薄后厚）。
 6) **每条 Requirement 至少 1 个 Scenario**，并尽量在 Scenario 末尾补一行 Evidence（指向代码入口/测试/命令/日志关键字）。
 7) **遗留安全网优先**：若后续计划涉及重构/迁移，`verification.md` 中优先加入 Snapshot/Golden Master 测试策略。
 
+---
+
+## `constitution.md` 创建要求
+
+当 `<devbooks-root>/constitution.md` 不存在时，必须创建。
+
+**内容要求**：
+1) 包含 Part Zero（强制指令）
+2) 包含 GIP-01 到 GIP-04（角色隔离/测试不可篡改/设计优先/真理源唯一）
+3) 包含逃生舱口（紧急修复/原型验证/人工裁决）
+4) 可根据项目特性新增项目特有的 GIP（如 GIP-05），但不得删除核心 GIP
+
+**推荐结构**：
+```markdown
+# 项目宪法 (Project Constitution)
+
+## Part Zero: 强制指令
+## 全局不可违背原则 (Global Inviolable Principles)
+### GIP-01: 角色隔离原则
+### GIP-02: 测试不可篡改原则
+### GIP-03: 设计优先原则
+### GIP-04: 真理源唯一原则
+### GIP-05: [项目特有原则，可选]
+## 逃生舱口 (Escape Hatches)
+## 宪法变更流程
+```
+
+---
+
+## `project.md` 创建要求
+
+当 `<devbooks-root>/project.md` 不存在时，必须创建。
+
+**内容要求**（根据代码分析结果填充）：
+1) 目的：项目的核心目标
+2) 技术栈：从 package.json/go.mod/pom.xml/requirements.txt 等推断
+3) 项目约定：代码风格/架构模式/测试策略/Git 工作流
+4) 领域上下文：核心概念/角色定义
+5) 重要约束：角色隔离等
+6) 目录根映射：truth-root/change-root 的路径
+
+**推荐结构**：
+```markdown
+# 项目上下文 (Project Context)
+
+## 目的
+## 技术栈
+## 项目约定
+### 代码风格
+### 架构模式
+### 测试策略
+### Git 工作流
+## 领域上下文
+### 核心概念
+### 角色定义
+## 重要约束
+## 外部依赖
+## 目录根映射
+```
+
+---
+
 `<truth-root>/_meta/project-profile.md` 写作要求（必须遵守）：
 1) 只写你能从仓库证据推导出的结论；不确定必须标注 `TBD` 并给出验证动作（命令/文件路径/下一步）。
 2) 不改业务代码、不改 tests、不引入依赖；你只产出文档。
@@ -99,17 +166,19 @@
 
 输出要求（按顺序）：
 1) 先输出你将创建/更新的文件路径清单（只列路径）
-2) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
-2.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
-3) 输出 `proposal.md` 内容（Markdown）
-4) 输出 `design.md` 内容（若你认为必要；否则输出“不需要”的理由）
-5) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
-6) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
-7) 最后给出一个“合并建议”：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
+2) 若 `<devbooks-root>/constitution.md` 不存在：输出其内容（Markdown）
+3) 若 `<devbooks-root>/project.md` 不存在：输出其内容（Markdown），根据代码分析结果填充
+4) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
+4.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
+5) 输出 `proposal.md` 内容（Markdown）
+6) 输出 `design.md` 内容（若你认为必要；否则输出"不需要"的理由）
+7) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
+8) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
+9) 最后给出一个"合并建议"：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
 
 现在开始执行，不要输出额外解释。
 
 注意事项：
-- 本文档中的 `<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
-- DevBooks 项目默认取值：`dev-playbooks/specs` 与 `dev-playbooks/changes`。
+- 本文档中的 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
+- DevBooks 项目默认取值：`dev-playbooks/`、`dev-playbooks/specs` 与 `dev-playbooks/changes`。
 - 只有在用户明确确认时才允许使用默认 `specs/` 与 `changes/`。

package/templates/dev-playbooks/README.md

@@ -447,12 +447,14 @@ DevBooks provides migration scripts to help you transition from other spec-drive
 If you're currently using [OpenSpec](https://github.com/Fission-AI/OpenSpec) with an `openspec/` directory:
 
 ```bash
-# Download and run the migration script
-curl -sL https://raw.githubusercontent.com/ozbombor/dev-playbooks-cn/master/scripts/migrate-from-openspec.sh | bash
+# Using CLI (recommended)
+dev-playbooks-cn migrate --from openspec
 
-# Or run with options
-./scripts/migrate-from-openspec.sh --project-root . --dry-run  # Preview changes
-./scripts/migrate-from-openspec.sh --project-root . --keep-old # Keep original directory
+# Preview changes first
+dev-playbooks-cn migrate --from openspec --dry-run
+
+# Keep original directory after migration
+dev-playbooks-cn migrate --from openspec --keep-old
 ```
 
 **What gets migrated:**
@@ -460,18 +462,21 @@ curl -sL https://raw.githubusercontent.com/ozbombor/dev-playbooks-cn/master/scri
 - `openspec/changes/` → `dev-playbooks/changes/`
 - `openspec/project.md` → `dev-playbooks/project.md`
 - All path references are automatically updated
+- AI tool command directories are cleaned up (`.claude/commands/openspec/`, etc.)
 
 ### Migrate from GitHub spec-kit
 
 If you're using [GitHub spec-kit](https://github.com/github/spec-kit) with `specs/` and `memory/` directories:
 
 ```bash
-# Download and run the migration script
-curl -sL https://raw.githubusercontent.com/ozbombor/dev-playbooks-cn/master/scripts/migrate-from-speckit.sh | bash
+# Using CLI (recommended)
+dev-playbooks-cn migrate --from speckit
+
+# Preview changes first
+dev-playbooks-cn migrate --from speckit --dry-run
 
-# Or run with options
-./scripts/migrate-from-speckit.sh --project-root . --dry-run  # Preview changes
-./scripts/migrate-from-speckit.sh --project-root . --keep-old # Keep original directories
+# Keep original directories after migration
+dev-playbooks-cn migrate --from speckit --keep-old
 ```
 
 **Mapping rules:**