prd-workflow-cli 1.1.25

package/commands/index.js

@@ -0,0 +1,365 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * 生成或更新 P1 迭代索引
+ * 自动从文档元信息汇总生成索引
+ */
+module.exports = async function () {
+    const configPath = path.join(process.cwd(), '.prd-config.json');
+
+    if (!await fs.pathExists(configPath)) {
+        console.log(chalk.red('✗ 当前目录不是一个 PRD 项目'));
+        return;
+    }
+
+    const config = await fs.readJSON(configPath);
+
+    console.log(chalk.blue('正在生成迭代索引...'));
+
+    // 扫描所有迭代目录
+    const iterationBaseDir = path.join(process.cwd(), '02_迭代记录');
+    const iterations = [];
+
+    if (await fs.pathExists(iterationBaseDir)) {
+        const dirs = await fs.readdir(iterationBaseDir);
+
+        for (const dir of dirs) {
+            const iterationDir = path.join(iterationBaseDir, dir);
+            const stat = await fs.stat(iterationDir);
+
+            if (stat.isDirectory() && dir.match(/第\d+轮迭代/)) {
+                const iterationData = await extractIterationInfo(iterationDir, dir);
+                iterations.push(iterationData);
+            }
+        }
+    }
+
+    // 生成 P1 索引文档
+    const p1Content = generateP1Index(iterations, config);
+    const p1Path = path.join(process.cwd(), '00_项目总览/P1_迭代索引.md');
+
+    await fs.writeFile(p1Path, p1Content);
+
+    console.log(chalk.green('✓ P1 迭代索引已生成'));
+    console.log(chalk.cyan(`文件位置: ${p1Path}\n`));
+};
+
+/**
+ * 提取单个迭代的信息
+ */
+async function extractIterationInfo(iterationDir, dirName) {
+    const iterationNumber = dirName.match(/第(\d+)轮迭代/)[1];
+
+    const iteration = {
+        number: parseInt(iterationNumber),
+        name: dirName,
+        documents: {
+            R1: null,
+            B1: null,
+            B2: null,
+            B3: null,
+            R2: null,
+            C0: null,
+            C1: null,
+            C2: null,
+            C3: null
+        },
+        status: 'unknown',
+        createdAt: null,
+        frozenAt: null
+    };
+
+    // 扫描文档
+    const files = await fs.readdir(iterationDir);
+
+    for (const file of files) {
+        const filePath = path.join(iterationDir, file);
+
+        if (file.includes('R1_')) iteration.documents.R1 = file;
+        if (file.includes('B1_')) iteration.documents.B1 = file;
+        if (file.includes('B2_')) iteration.documents.B2 = file;
+        if (file.includes('B3_')) {
+            iteration.documents.B3 = file;
+            // 读取冻结时间
+            const content = await fs.readFile(filePath, 'utf-8');
+            const match = content.match(/冻结时间[:\s]*([^\n]+)/);
+            if (match) iteration.frozenAt = match[1].trim();
+        }
+        if (file.includes('R2_')) iteration.documents.R2 = file;
+        if (file.includes('C0_')) iteration.documents.C0 = file;
+        if (file.includes('C1_')) iteration.documents.C1 = file;
+        if (file.includes('C2_')) iteration.documents.C2 = file;
+        if (file.includes('C3_')) {
+            iteration.documents.C3 = file;
+            if (!iteration.frozenAt) {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const match = content.match(/冻结时间[:\s]*([^\n]+)/);
+                if (match) iteration.frozenAt = match[1].trim();
+            }
+        }
+    }
+
+    // 判断状态
+    iteration.status = determineIterationStatus(iteration.documents);
+
+    return iteration;
+}
+
+/**
+ * 判断迭代状态
+ */
+function determineIterationStatus(docs) {
+    if (docs.C3) return '✅ 已完成';
+    if (docs.C1 || docs.C0) return '🔄 版本阶段';
+    if (docs.B3) return '📋 规划已冻结';
+    if (docs.B2 || docs.B1) return '💡 规划中';
+    return '🆕 刚启动';
+}
+
+/**
+ * 生成 P1 索引内容
+ */
+function generateP1Index(iterations, config) {
+    const now = new Date().toLocaleString('zh-CN');
+
+    let content = `# P1_迭代索引
+
+**生成时间**: ${now}
+**项目名称**: ${config.projectName}
+**当前迭代**: 第 ${config.currentIteration} 轮
+
+---
+
+## 📋 索引说明
+
+本文档自动生成，提供所有迭代的快速导航。
+
+**作用**:
+- 快速了解项目迭代历史
+- 查看每轮迭代的文档完整性
+- 追踪冻结点和版本关系
+
+---
+
+## 🔄 迭代总览
+
+**总迭代数**: ${iterations.length} 轮
+**已完成**: ${iterations.filter(i => i.status === '✅ 已完成').length} 轮
+**进行中**: ${iterations.filter(i => i.status !== '✅ 已完成').length} 轮
+
+---
+
+## 📊 迭代清单
+
+`;
+
+    // 为每个迭代生成条目
+    for (const iter of iterations.sort((a, b) => a.number - b.number)) {
+        content += generateIterationEntry(iter);
+    }
+
+    content += `\n---
+
+## 🔍 文档完整性检查
+
+`;
+
+    // 文档完整性统计
+    content += generateCompletenessCheck(iterations);
+
+    content += `\n---
+
+## ⚠️ 违规检查
+
+`;
+
+    // 违规链路检查
+    content += generateViolationCheck(iterations);
+
+    content += `\n---
+
+## 📝 下一步
+
+`;
+
+    if (config.currentIteration === 0) {
+        content += `- 创建基线文档（A0/A1/A2）\n`;
+        content += `- 执行 R0 基线审视\n`;
+        content += `- 开始第一轮迭代：\`prd iteration new\`\n`;
+    } else {
+        const current = iterations.find(i => i.number === config.currentIteration);
+        if (current) {
+            content += generateNextSteps(current);
+        }
+    }
+
+    content += `\n---
+
+**此文档由 AI 自动生成，请勿手动编辑索引部分。**
+**如需更新，运行：\`prd status\` 或 \`prd index update\`**
+`;
+
+    return content;
+}
+
+/**
+ * 生成单个迭代条目
+ */
+function generateIterationEntry(iter) {
+    let entry = `### 第 ${iter.number} 轮迭代 ${iter.status}\n\n`;
+
+    if (iter.frozenAt) {
+        entry += `**冻结时间**: ${iter.frozenAt}\n\n`;
+    }
+
+    entry += `**文档清单**:\n\n`;
+    entry += `| 阶段 | 文档 | 状态 |\n`;
+    entry += `|-----|-----|-----|\n`;
+
+    const stages = [
+        { key: 'R1', name: 'R1 规划审视' },
+        { key: 'B1', name: 'B1 规划草案' },
+        { key: 'B2', name: 'B2 规划拆解' },
+        { key: 'B3', name: 'B3 规划冻结' },
+        { key: 'R2', name: 'R2 版本审视' },
+        { key: 'C0', name: 'C0 版本范围' },
+        { key: 'C1', name: 'C1 版本需求' },
+        { key: 'C2', name: 'C2 版本变更' },
+        { key: 'C3', name: 'C3 版本冻结' }
+    ];
+
+    for (const stage of stages) {
+        const exists = iter.documents[stage.key];
+        entry += `| ${stage.name} | ${exists || '-'} | ${exists ? '✅' : '○'} |\n`;
+    }
+
+    entry += `\n**关系映射**:\n`;
+    if (iter.documents.B3) {
+        entry += `- B3（规划）`;
+        if (iter.documents.C0 || iter.documents.C1) {
+            entry += ` → C0/C1（版本）`;
+        }
+        if (iter.documents.C3) {
+            entry += ` → C3（冻结）`;
+        }
+        entry += `\n`;
+    }
+
+    entry += `\n**文档位置**: \`02_迭代记录/${iter.name}/\`\n\n`;
+    entry += `---\n\n`;
+
+    return entry;
+}
+
+/**
+ * 文档完整性检查
+ */
+function generateCompletenessCheck(iterations) {
+    let check = ``;
+
+    for (const iter of iterations) {
+        const issues = [];
+
+        // 检查 B3 → C 的链路
+        if (iter.documents.B3 && !(iter.documents.C0 || iter.documents.C1)) {
+            issues.push('⚠️ 有 B3 但缺少 C0/C1');
+        }
+
+        // 检查 C1 → C3 的链路
+        if (iter.documents.C1 && !iter.documents.C3) {
+            issues.push('⚠️ 有 C1 但未冻结为 C3');
+        }
+
+        // 检查 R1
+        if ((iter.documents.B1 || iter.documents.B2) && !iter.documents.R1) {
+            issues.push('💡 提示：建议执行 R1 审视');
+        }
+
+        // 检查 R2
+        if (iter.documents.C1 && !iter.documents.R2) {
+            issues.push('💡 提示：建议执行 R2 审视');
+        }
+
+        if (issues.length > 0) {
+            check += `**第 ${iter.number} 轮迭代**:\n`;
+            for (const issue of issues) {
+                check += `- ${issue}\n`;
+            }
+            check += `\n`;
+        }
+    }
+
+    if (check === '') {
+        check = `✅ 所有迭代文档完整，无缺失。\n`;
+    }
+
+    return check;
+}
+
+/**
+ * 违规检查
+ */
+function generateViolationCheck(iterations) {
+    let violations = ``;
+
+    for (const iter of iterations) {
+        const issues = [];
+
+        // 检查"未冻结却进入下游"
+        if (!iter.documents.B3 && (iter.documents.C0 || iter.documents.C1)) {
+            issues.push('🔴 违规：没有 B3 但创建了 C0/C1（违反规范）');
+        }
+
+        if (!iter.documents.C3 && iter.number < Math.max(...iterations.map(i => i.number))) {
+            // 不是最新迭代但没有 C3
+            issues.push('⚠️ 注意：迭代未完成就启动了新轮次');
+        }
+
+        if (issues.length > 0) {
+            violations += `**第 ${iter.number} 轮迭代**:\n`;
+            for (const issue of issues) {
+                violations += `- ${issue}\n`;
+            }
+            violations += `\n`;
+        }
+    }
+
+    if (violations === '') {
+        violations = `✅ 未发现违规链路。\n`;
+    }
+
+    return violations;
+}
+
+/**
+ * 生成下一步建议
+ */
+function generateNextSteps(current) {
+    let steps = `**当前迭代（第 ${current.number} 轮）下一步**:\n\n`;
+
+    if (current.status === '✅ 已完成') {
+        steps += `- 当前迭代已完成\n`;
+        steps += `- 如需新迭代：\`prd iteration new\`\n`;
+    } else if (current.status === '📋 规划已冻结') {
+        steps += `- 创建版本范围：\`prd version create C0\`\n`;
+        steps += `- 创建版本需求：\`prd version create C1\`\n`;
+    } else if (current.status === '💡 规划中') {
+        if (!current.documents.R1) {
+            steps += `- 执行 R1 审视：\`prd review r1\`\n`;
+        }
+        if (current.documents.B2 && !current.documents.B3) {
+            steps += `- 冻结规划：\`prd plan freeze\`\n`;
+        }
+    } else if (current.status === '🔄 版本阶段') {
+        if (!current.documents.R2) {
+            steps += `- 执行 R2 审视：\`prd review r2\`\n`;
+        }
+        if (current.documents.R2 && !current.documents.C3) {
+            steps += `- 冻结版本：\`prd version freeze\`\n`;
+        }
+    }
+
+    return steps;
+}

package/commands/init.js

@@ -0,0 +1,357 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+module.exports = async function (projectName) {
+    const projectPath = path.join(process.cwd(), projectName);
+
+    try {
+        // 检查目录是否已存在
+        if (await fs.pathExists(projectPath)) {
+            console.log(chalk.red(`✗ 目录 ${projectName} 已存在`));
+            return;
+        }
+
+        console.log(chalk.blue(`正在创建项目: ${projectName}...`));
+
+        // 创建项目目录结构
+        const directories = [
+            '00_项目总览',
+            '01_产品基线',
+            '02_迭代记录',
+            '98_对话归档',
+            '99_归档区/历史参考与废弃文档',
+            '.agent/workflows'
+        ];
+
+        for (const dir of directories) {
+            await fs.ensureDir(path.join(projectPath, dir));
+        }
+
+        // 创建项目配置文件
+        const config = {
+            projectName,
+            createdAt: new Date().toISOString(),
+            currentIteration: 0,
+            workflow: 'A → R → B → C',
+            stages: {
+                baseline: { completed: false, documents: [] },
+                planning: { completed: false, documents: [] },
+                version: { completed: false, documents: [] }
+            }
+        };
+
+        await fs.writeJSON(
+            path.join(projectPath, '.prd-config.json'),
+            config,
+            { spaces: 2 }
+        );
+
+        // 创建 package.json（让其他用户可以通过 npm install 安装 CLI）
+        const packageJson = {
+            name: projectName.toLowerCase().replace(/[^a-z0-9]/g, '-'),
+            version: '1.0.0',
+            description: `${projectName} - PRD 需求管理项目`,
+            private: true,
+            scripts: {
+                prd: 'prd',
+                status: 'prd status',
+                help: 'prd --help'
+            },
+            dependencies: {
+                'prd-workflow-cli': '^1.1.12'
+            }
+        };
+
+        await fs.writeJSON(
+            path.join(projectPath, 'package.json'),
+            packageJson,
+            { spaces: 2 }
+        );
+
+        // 创建 P0 项目基本信息模板
+        const p0Template = `# P0_项目基本信息
+
+**创建时间**: ${new Date().toLocaleString('zh-CN')}
+**项目名称**: ${projectName}
+**文档状态**: 草案
+
+---
+
+## 文档说明
+
+**目的**: 
+- 明确项目是否应该存在
+- 确认项目目标是否成立
+- 识别关键干系人
+
+**填写要求**:
+- 只填写事实，不填愿景
+- 目标要可检验
+- 干系人要具体到人
+
+---
+
+## 1. 项目基本信息
+
+### 1.1 项目定位
+
+**项目全称**: ${projectName}
+
+**项目简述**:
+<!-- 一句话说明这个项目是什么 -->
+
+**所属产品线**: 
+<!-- 例如：核心业务系统、辅助工具、创新试点 -->
+
+**项目级别**: 
+- [ ] 战略级（公司级重点）
+- [ ] 业务级（部门级重点）
+- [ ] 支撑级（基础能力）
+
+---
+
+## 2. 项目目标
+
+### 2.1 核心目标
+
+**要解决的主要问题**:
+<!-- 不超过 3 个核心问题 -->
+1. 
+2. 
+3. 
+
+**成功标准**:
+<!-- 如何判断项目成功？用可衡量的指标 -->
+- 指标 1: ______
+- 指标 2: ______
+- 指标 3: ______
+
+### 2.2 目标合理性确认
+
+**为什么现在做这个项目？**
+<!-- 时机/背景/触发因素 -->
+
+**不做会怎样？**
+<!-- 说明紧迫性 -->
+
+---
+
+## 3. 干系人
+
+### 3.1 核心干系人
+
+**PM（产品负责人）**:
+- 姓名: ____________
+- 职责: 项目最终决策
+- 联系方式: ____________
+
+**技术负责人**:
+- 姓名: ____________
+- 职责: 技术可行性把关
+- 联系方式: ____________
+
+**业务方**:
+- 部门: ____________
+- 联系人: ____________
+- 职责: 业务需求确认
+
+### 3.2 相关方
+
+**可能受影响的团队/系统**:
+<!-- 列出会受此项目影响的其他团队或系统 -->
+
+---
+
+## 4. 项目约束
+
+### 4.1 时间约束
+
+**期望启动时间**: ____________
+**期望交付时间**: ____________
+
+### 4.2 资源约束
+
+**已知的资源限制**:
+<!-- 人力/预算/技术限制 -->
+
+### 4.3 依赖条件
+
+**项目依赖**:
+<!-- 需要其他项目/系统先完成什么？ -->
+
+---
+
+## 5. 项目状态
+
+**当前状态**: 初始化
+**当前迭代**: 0 轮
+**下一步**: 创建 A 类基线文档
+
+---
+
+## 6. PM 确认
+
+- [ ] 项目目标已明确且合理
+- [ ] 干系人已确认
+- [ ] 约束条件已记录
+- [ ] 可以开始基线建立
+
+**PM 签字**: _____________
+**日期**: _____________
+
+---
+
+## 备注
+
+<!-- 其他需要说明的重要信息 -->
+`;
+
+        await fs.writeFile(
+            path.join(projectPath, '00_项目总览/P0_项目基本信息.md'),
+            p0Template
+        );
+
+        // 复制工作流模板
+        const workflowsDir = path.join(__dirname, '../.agent/workflows');
+        if (await fs.pathExists(workflowsDir)) {
+            await fs.copy(
+                workflowsDir,
+                path.join(projectPath, '.agent/workflows')
+            );
+        }
+
+        // 复制对话归档模板
+        const dialogTemplateSource = path.join(__dirname, '../templates/dialog-template.md');
+        if (await fs.pathExists(dialogTemplateSource)) {
+            await fs.copy(
+                dialogTemplateSource,
+                path.join(projectPath, '98_对话归档/AI_对话归档模板.md')
+            );
+        }
+
+        // 复制 AI 规则文件
+        // .cursorrules (Cursor IDE)
+        const cursorrules = path.join(__dirname, '../.cursorrules');
+        if (await fs.pathExists(cursorrules)) {
+            await fs.copy(
+                cursorrules,
+                path.join(projectPath, '.cursorrules')
+            );
+        }
+
+        // .antigravity/rules.md (Antigravity)
+        const antigravityDir = path.join(__dirname, '../.antigravity');
+        if (await fs.pathExists(antigravityDir)) {
+            await fs.copy(
+                antigravityDir,
+                path.join(projectPath, '.antigravity')
+            );
+        }
+
+        // AI-GUIDE.md (通用 AI 指引)
+        const aiGuide = path.join(__dirname, '../AI-GUIDE.md');
+        if (await fs.pathExists(aiGuide)) {
+            await fs.copy(
+                aiGuide,
+                path.join(projectPath, 'AI-GUIDE.md')
+            );
+        }
+
+        // 创建 README
+        const readme = `# ${projectName}
+
+本项目采用规范化的产品需求管理流程
+
+## 📁 目录结构
+
+\`\`\`
+${projectName}/
+├── 00_项目总览/          # 项目基本信息
+├── 01_产品基线/          # A 类文档：现状基线
+├── 02_迭代记录/          # 各轮迭代的 B、C 类文档
+│   ├── 第01轮迭代/
+│   ├── 第02轮迭代/
+│   └── ...
+└── 99_归档区/            # 历史文档归档
+\`\`\`
+
+## 🔄 工作流程
+
+1. **A 类 - 建立基线** (01_产品基线/)
+   - A0: 产品基础与范围说明
+   - A1: 已上线功能与流程清单
+   - A2: 存量反馈与数据汇总
+   - R0: 基线审视报告
+
+2. **B 类 - 需求规划** (02_迭代记录/第N轮迭代/)
+   - R1: 规划前审视（启动条件检查）
+   - B1: 需求规划草案
+   - B2: 规划拆解与范围界定
+   - R1: 规划审视（冻结前审查）
+   - B3: 规划冻结归档
+
+3. **C 类 - 版本需求** (02_迭代记录/第N轮迭代/)
+   - R2: 版本审视
+   - C0: 版本范围声明
+   - C1: 版本需求清单
+   - C3: 版本冻结归档
+
+## 🛠️ 使用 CLI 工具
+
+\`\`\`bash
+# 查看项目状态
+prd status
+
+# 创建基线文档
+prd baseline create A0
+
+# 开始新迭代
+prd iteration new
+
+# 创建规划文档
+prd plan create B1
+
+# 执行 R1 审视
+prd review r1
+
+# 冻结规划
+prd plan freeze
+\`\`\`
+
+## 📝 关键原则
+
+- **R1 是启动闸门**: 必须满足三个条件才能开始规划
+- **B3 是决策冻结**: 规划一旦冻结不可随意更改
+- **C 类不讨论方向**: 只执行已冻结的规划
+- **审视是强制的**: R1/R2 必须通过才能进入下一阶段
+
+---
+创建时间: ${new Date().toLocaleString('zh-CN')}
+`;
+
+        await fs.writeFile(
+            path.join(projectPath, 'README.md'),
+            readme
+        );
+
+        console.log(chalk.green('✓ 项目创建成功!'));
+        console.log('');
+        console.log(chalk.bold('📋 下一步操作（请按顺序执行）:'));
+        console.log('');
+        console.log(chalk.cyan('第 1 步: 进入项目目录'));
+        console.log(`  cd ${projectName}`);
+        console.log('');
+        console.log(chalk.cyan('第 2 步: 完善 P0_项目基本信息.md'));
+        console.log(chalk.gray('  文件位置: 00_项目总览/P0_项目基本信息.md'));
+        console.log(chalk.gray('  填写内容: 项目目标、干系人、约束条件等'));
+        console.log(chalk.yellow('  ⚠️  必须完成 P0 填写后才能开始创建 A 类基线文档'));
+        console.log('');
+        console.log(chalk.cyan('第 3 步: 创建 A0 基线文档'));
+        console.log('  prd baseline create A0  # P0 填写完成后执行');
+        console.log('');
+
+    } catch (error) {
+        console.log(chalk.red('✗ 创建项目失败:'), error.message);
+    }
+};