spec-agent 1.0.3

package/spec-agent-implementation.md

@@ -0,0 +1,750 @@
+# SpecAgent CLI — 实现对齐版设计方案
+
+## 一、项目概述
+
+**目标**：解决几百 MB 需求文档单 Agent 无法完整理解的问题，通过多 Agent 协作完成需求拆解 → 理解 → 分解。
+
+**设计原则**：
+
+- 按 cli-for-agents 规范设计 CLI 接口
+- 借鉴 gstack 角色化分工思想
+- 第一阶段聚焦需求拆解，编码阶段后续实现
+
+**文档范围说明（重要）**：
+
+- 本文档同时包含「当前已实现」与「后续规划」两部分，避免将规划能力误认为已落地能力。
+- 凡是命令参数与默认值，以 `src/index.ts` 中的定义为准。
+
+---
+
+## 二、核心架构
+
+### 2.1 五阶段流水线
+
+```text
+文档 → scan(Scanner) → analyze(Analyst×N) → merge(Architect) → plan(Planner) → dispatch(Dispatcher)
+```
+
+| 阶段 | 角色 | 职责 | 输出 |
+| ------ | ------ | ------ | ------ |
+| scan | Scanner | 文档扫描、识别结构、按大小分片 | manifest.json |
+| analyze | Analyst × N | 并行读取分片，提取结构化信息 | chunk_N_summary.json |
+| merge | Architect | 合并摘要、去重、建依赖图 | spec_summary.json |
+| plan | Planner | 拆分为可执行任务、标注依赖 | task_plan.json |
+| dispatch | Dispatcher | 按类型分配给不同 Agent | dispatch_plan.json |
+
+### 2.2 目录结构（当前已实现）
+
+```text
+spec-agent/
+├── bin/
+│   └── spec-agent.js          # CLI 入口
+├── src/
+│   ├── index.ts               # 命令注册
+│   ├── types.ts               # 核心类型定义
+│   ├── commands/
+│   │   ├── scan.ts            # Phase 1: 扫描分片
+│   │   ├── analyze.ts         # Phase 2: 并行分析
+│   │   ├── merge.ts           # Phase 3: 合并去重
+│   │   ├── plan.ts            # Phase 4: 任务规划
+│   │   ├── dispatch.ts        # Phase 5: 任务分配
+│   │   ├── learn.ts           # 学习积累模式
+│   │   ├── pipeline.ts        # 一键执行全流程
+│   │   ├── status.ts          # 查看工作状态
+│   │   └── clean.ts           # 清理中间文件
+│   ├── services/
+│   │   ├── llm.ts             # LLM 调用与结构分析
+│   │   └── document-parser.ts # 文档解析（md/pdf/docx/html/txt）
+│   └── utils/
+│       ├── logger.ts          # 日志工具
+│       └── file.ts            # 文件操作
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## 三、命令详解
+
+### 3.1 scan — 文档扫描
+
+```bash
+spec-agent scan --input ./requirements/ --output ./workspace/manifest.json
+```
+
+**功能**：
+
+- 递归扫描输入目录，识别所有支持格式的文档
+- 默认启用 LLM 结构分析（语义切分 + 行号定位）进行分片
+- 当 LLM 调用临时失败时，回退到“按大小强制切分”（而非标题正则切分）
+- 生成分片清单，记录每个分片的源文件和大小
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--input` | 输入文件或目录 | 必填（或 `--stdin`） |
+| `--stdin` | 从 stdin 读取文件路径 | false |
+| `--output` | manifest.json 输出路径 | manifest.json |
+| `--chunk-size` | 最大分片大小 | 200kb |
+| `--min-chunk-size` | 最小分片合并阈值 | 10kb |
+| `--no-llm-chunking` | 关闭 LLM 结构分析，使用规则切分 | false |
+| `--strict-llm` | LLM 切分失败时直接报错（不回退） | false |
+| `--format` | 输入格式提示 | auto |
+| `--dry-run` | 预览分片方案 | false |
+| `--yes` | 跳过确认 | false |
+
+**输出示例**：
+
+```json
+{
+  "status": "success",
+  "totalFiles": 12,
+  "totalSize": "340mb",
+  "chunks": 130,
+  "chunkSize": "200kb",
+  "manifestPath": "./workspace/manifest.json"
+}
+```
+
+---
+
+### 3.2 analyze — 并行分析
+
+```bash
+spec-agent analyze --manifest ./workspace/manifest.json --output ./workspace/summaries/
+```
+
+**功能**：
+
+- 基于 manifest 并行分析所有分片
+- 每个 Analyst Agent 提取：功能点、数据模型、API、页面、业务规则
+- 支持指定分析焦点（features/data-model/api/pages）
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--manifest` | manifest.json 路径 | manifest.json |
+| `--output` | 摘要输出目录 | summaries |
+| `--agents` | 并行 Agent 数量 | auto |
+| `--chunks` | 指定分析的分片索引 | all |
+| `--focus` | 分析焦点 | full |
+| `--apply-learned` | 应用学习到的模式 | false |
+| `--retries` | 单个 chunk 失败重试次数 | 1 |
+| `--dry-run` | 预览分析计划 | false |
+| `--yes` | 跳过确认 | false |
+
+补充：
+
+- 若 analyze 过程中存在失败 chunk，会输出 `analyze_failures.json`（包含 chunkId、错误原因、重试次数）。
+
+**输出示例**：
+
+```json
+{
+  "status": "success",
+  "chunksAnalyzed": 8,
+  "totalFeatures": 42,
+  "totalDataModels": 15,
+  "totalPages": 12,
+  "totalApis": 28,
+  "outputDir": "./workspace/summaries/"
+}
+```
+
+**chunk_N_summary.json 结构**：
+
+```json
+{
+  "chunkId": 0,
+  "sourceFiles": ["./prd/chapter1.md", "./prd/chapter2.md"],
+  "size": "182kb",
+  "features": [
+    {
+      "id": "F001",
+      "name": "用户登录",
+      "description": "支持手机号+验证码、账号密码两种登录方式",
+      "priority": "P0",
+      "dependencies": [],
+      "sourceChunk": 0
+    }
+  ],
+  "dataModels": [...],
+  "pages": [...],
+  "apis": [...],
+  "businessRules": [...],
+  "extractedAt": "2026-04-01T10:30:00Z"
+}
+```
+
+---
+
+### 3.3 merge — 合并摘要
+
+```bash
+spec-agent merge --summaries ./workspace/summaries/ --output ./workspace/spec_summary.json
+```
+
+**功能**：
+
+- 合并所有分片摘要为统一 spec
+- 去重（conservative/aggressive 策略）
+- 建立依赖关系图
+- 识别跨分片冲突
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--summaries` | 摘要目录 | summaries |
+| `--output` | 输出路径 | spec_summary.json |
+| `--strategy` | 合并策略 | conservative |
+| `--dry-run` | 预览合并计划 | false |
+| `--yes` | 跳过确认 | false |
+
+**spec_summary.json 结构**：
+
+```json
+{
+  "version": "1.0.0",
+  "createdAt": "2026-04-01T10:35:00Z",
+  "sourceChunks": 8,
+  "deduplicatedFeatures": 42,
+  "features": [...],
+  "dataModels": [...],
+  "pages": [...],
+  "apis": [...],
+  "businessRules": [...],
+  "dependencyGraph": {
+    "F005": ["F001", "F003"],
+    "F010": ["F005"]
+  },
+  "conflicts": []
+}
+```
+
+---
+
+### 3.4 plan — 任务规划
+
+```bash
+spec-agent plan --spec ./workspace/spec_summary.json --output ./workspace/task_plan.json
+```
+
+**功能**：
+
+- 将 spec 拆为可执行子任务
+- 按依赖关系分组（并行组）
+- 标注优先级、预估工作量
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--spec` | spec_summary.json 路径 | spec_summary.json |
+| `--output` | 输出路径 | task_plan.json |
+| `--type` | 输出类型 | prototype |
+| `--framework` | 目标框架 | vue3 |
+| `--parallel` | 最大并行任务数 | 3 |
+| `--dry-run` | 预览任务计划 | false |
+| `--yes` | 跳过确认 | false |
+
+**task_plan.json 结构**：
+
+```json
+{
+  "version": "1.0.0",
+  "createdAt": "2026-04-01T10:40:00Z",
+  "totalTasks": 12,
+  "parallelGroups": [
+    {
+      "group": 1,
+      "tasks": [
+        {"id": "T001", "name": "项目基础架构", "type": "setup", "dependencies": [], "priority": "P0", "status": "pending"},
+        {"id": "T002", "name": "登录页", "type": "page", "dependencies": ["T001"], "priority": "P0", "status": "pending"}
+      ]
+    }
+  ],
+  "outputDir": "./workspace/build/",
+  "framework": "vue3",
+  "type": "prototype"
+}
+```
+
+---
+
+### 3.5 dispatch — 任务分配
+
+```bash
+spec-agent dispatch --plan ./workspace/task_plan.json --output ./workspace/dispatch_plan.json
+```
+
+**功能**：
+
+- 按任务类型分配给不同 Agent（frontend/backend/qa 等）
+- 支持多种分配策略（balanced/skill-first/load-first）
+- 输出供后续 build 阶段使用的分配方案
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--plan` | task_plan.json 路径 | task_plan.json |
+| `--output` | 输出路径 | dispatch_plan.json |
+| `--agents` | Agent 类型映射 | auto |
+| `--strategy` | 分配策略 | balanced |
+| `--dry-run` | 预览分配方案 | false |
+| `--yes` | 跳过确认 | false |
+
+**dispatch_plan.json 结构**：
+
+```json
+{
+  "version": "1.0.0",
+  "createdAt": "2026-04-01T10:45:00Z",
+  "totalTasks": 12,
+  "agentPools": {
+    "frontend": [
+      {"agentId": "FE-1", "type": "frontend", "assignedTasks": ["T002", "T003"], "workload": "8h"}
+    ],
+    "backend": [
+      {"agentId": "BE-1", "type": "backend", "assignedTasks": ["T007", "T008"], "workload": "7h"}
+    ]
+  },
+  "unassigned": [],
+  "dispatchPlanPath": "./workspace/dispatch_plan.json"
+}
+```
+
+---
+
+### 3.6 learn — 学习积累
+
+```bash
+# 从已完成的分析中学习
+spec-agent learn --workspace ./workspace/ --from summaries
+
+# 学习特定规则
+spec-agent learn --workspace ./workspace/ --pattern "API 规范" --rule "/api/v{version}/{resource}"
+
+# 查看已学习的模式
+spec-agent learn --workspace ./workspace/ --list
+```
+
+**功能**：
+
+- 从分析结果中自动提取项目特定模式
+- 支持手动添加规则
+- 下次 analyze 时自动应用已学习模式
+
+---
+
+### 3.7 pipeline — 一键执行
+
+```bash
+# 完整流程
+spec-agent pipeline --input ./requirements/ --output ./workspace/
+
+# 只执行到 plan 阶段
+spec-agent pipeline --input ./requirements/ --output ./workspace/ --stop-at plan
+
+# 从 merge 阶段恢复
+spec-agent pipeline --input ./requirements/ --output ./workspace/ --from merge
+```
+
+**选项**：
+
+| 选项 | 说明 | 默认值 |
+| ------ | ------ | ------ |
+| `--input` | 输入路径 | 必填 |
+| `--output` | 输出目录 | workspace |
+| `--agents` | 最大并行 Agent | auto |
+| `--chunk-size` | 分片大小 | 200kb |
+| `--min-chunk-size` | 最小分片合并阈值 | 10kb |
+| `--analyze-retries` | analyze 阶段单 chunk 重试次数 | 1 |
+| `--strict-llm` | LLM 切分失败时直接报错（不回退） | false |
+| `--framework` | 目标框架 | vue3 |
+| `--stop-at` | 执行到指定阶段后停止 | dispatch |
+| `--from` | 从指定阶段恢复 | scan |
+| `--dry-run` | 预览全流程 | false |
+| `--yes` | 跳过所有确认 | false |
+
+---
+
+### 3.8 status — 查看状态
+
+```bash
+spec-agent status --workspace ./workspace/
+```
+
+**输出示例**：
+
+```text
+Workspace: ./workspace/
+
+Phases:
+  ✔ scan      - manifest.json
+  ✔ analyze   - 8/8 chunks analyzed
+  ✔ merge     - spec_summary.json
+  ✔ plan      - task_plan.json (12 tasks)
+  ⏳ dispatch  - pending
+
+Can resume from: dispatch
+```
+
+---
+
+### 3.9 clean — 清理
+
+```bash
+spec-agent clean --workspace ./workspace/ --dry-run
+spec-agent clean --workspace ./workspace/ --yes
+```
+
+---
+
+### 3.10 doctor — 环境自检
+
+```bash
+# 基础检查（Node、工作目录、LLM 配置）
+spec-agent doctor --workspace ./workspace/
+
+# 增加真实 LLM 连通性检查
+spec-agent doctor --workspace ./workspace/ --check-llm
+```
+
+**功能**：
+
+- 检查 Node 版本是否满足运行要求
+- 检查工作目录可访问性与写权限
+- 检查 LLM 环境变量是否配置完整
+- 可选执行真实 LLM 连通性探测
+
+---
+
+### 3.11 退出码约定（自动化友好）
+
+- `scan`：`1` 输入错误，`2` 配置错误，`3` 严格 LLM 失败，`10` 运行时错误
+- `analyze`：`1` 输入错误，`2` 配置错误，`3` 部分失败（含 `analyze_failures.json`），`10` 运行时错误
+- `doctor`：`2` 检查未通过，`1` 命令运行失败
+- `pipeline`：`2` 任一阶段失败，并写入 `pipeline_summary.json`
+
+---
+
+## 四、核心类型定义
+
+```typescript
+// 分片
+interface Chunk {
+  id: number;
+  sourceFiles: string[];
+  size: number;
+}
+
+// 清单
+interface Manifest {
+  version: string;
+  createdAt: string;
+  totalFiles: number;
+  totalSize: number;
+  chunkSize: number;
+  chunks: Chunk[];
+}
+
+// 功能点
+interface Feature {
+  id: string;
+  name: string;
+  description: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  dependencies: string[];
+  sourceChunk: number;
+}
+
+// 分片摘要
+interface ChunkSummary {
+  chunkId: number;
+  sourceFiles: string[];
+  size: string;
+  features: Feature[];
+  dataModels: DataModel[];
+  pages: Page[];
+  apis: Api[];
+  businessRules: string[];
+  extractedAt: string;
+}
+
+// 合并后的规格
+interface SpecSummary {
+  version: string;
+  createdAt: string;
+  sourceChunks: number;
+  deduplicatedFeatures: number;
+  features: Feature[];
+  dataModels: DataModel[];
+  pages: Page[];
+  apis: Api[];
+  businessRules: string[];
+  dependencyGraph: { [id: string]: string[] };
+  conflicts?: string[];
+}
+
+// 任务
+interface Task {
+  id: string;
+  name: string;
+  type: 'setup' | 'page' | 'component' | 'api' | 'feature' | 'test' | 'doc';
+  dependencies: string[];
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  estimatedHours?: number;
+  status: 'pending' | 'in_progress' | 'completed' | 'failed';
+}
+
+// 任务计划
+interface TaskPlan {
+  version: string;
+  createdAt: string;
+  totalTasks: number;
+  parallelGroups: Array<{
+    group: number;
+    tasks: Task[];
+  }>;
+  outputDir: string;
+  framework: string;
+  type: string;
+}
+
+// 分配计划
+interface DispatchPlan {
+  version: string;
+  createdAt: string;
+  totalTasks: number;
+  agentPools: {
+    [type: string]: Array<{
+      agentId: string;
+      type: string;
+      assignedTasks: string[];
+      workload: string;
+    }>;
+  };
+  unassigned: string[];
+  dispatchPlanPath: string;
+}
+```
+
+---
+
+## 五、关键设计决策
+
+### 5.1 分片策略
+
+- 默认使用 LLM 做文档结构分析（支持无标准标题文档）
+- 采用“行号窗口 + 重叠去重”策略定位章节，避免长文档截断失真
+- 单分片不超过 `--chunk-size`（默认 200kb）
+- 小分片会按 `--min-chunk-size`（默认 10kb）自动合并，降低调度开销
+
+### 5.2 并行分析
+
+- 默认并行度 = min(4, 分片数)
+- 可通过 `--agents` 手动指定
+- 每个 Analyst 独立处理一个分片，无状态依赖
+
+### 5.3 去重策略
+
+- **conservative**（默认）：仅去除完全重复项，保留疑似重复供人工确认
+- **aggressive**：使用相似度匹配自动合并，适合高质量文档
+
+### 5.4 幂等性保证
+
+- 每个阶段检查输出文件存在性，已完成的自动跳过
+- 当前版本未提供 `--force` 参数（规划中）
+- 当前版本未提供中间产物 hash 校验（规划中）
+
+### 5.5 断点恢复
+
+- 每个阶段完成后写入 `.phase_done` 标记
+- `pipeline --from <phase>` 从指定阶段恢复
+- `status` 命令显示可恢复位置
+
+### 5.6 学习机制
+
+- 自动从 analyze 结果中提取模式（命名规范、API 风格等）
+- 存储在 `.patterns.json` 中
+- 下次 analyze 时通过 `--apply-learned` 自动应用
+
+### 5.7 scan 质量指标（建议纳入验收）
+
+- **章节召回率**：人工抽样章节中，被成功切分覆盖的比例
+- **跨块断裂率**：同一语义章节被切到多个 chunk 的比例（越低越好）
+- **平均 chunk 大小**：按 token/字符统计，控制在模型稳定输入区间
+- **回退率**：LLM 切分失败后触发 size-split 的比例（用于监控稳定性）
+- **结构一致性**：多次扫描同一文档时，分片边界偏移程度
+
+---
+
+## 六、安装与使用
+
+### 安装
+
+```bash
+# 克隆仓库
+git clone <repo-url>
+cd spec-agent
+
+# 安装依赖
+npm install
+
+# 编译
+npm run build
+
+# 链接到全局（可选）
+npm link
+```
+
+### 快速开始
+
+```bash
+# 1. 扫描文档
+spec-agent scan --input ./requirements/ --output ./workspace/manifest.json
+
+# 2. 并行分析
+spec-agent analyze --manifest ./workspace/manifest.json --output ./workspace/summaries/
+
+# 3. 合并摘要
+spec-agent merge --summaries ./workspace/summaries/ --output ./workspace/spec_summary.json
+
+# 4. 任务规划
+spec-agent plan --spec ./workspace/spec_summary.json --output ./workspace/task_plan.json
+
+# 5. 任务分配
+spec-agent dispatch --plan ./workspace/task_plan.json --output ./workspace/dispatch_plan.json
+
+# 或者一键执行
+spec-agent pipeline --input ./requirements/ --output ./workspace/
+```
+
+---
+
+## 七、实施里程碑与验收清单
+
+### M1：scan 稳定化（进行中）
+
+- 范围：复杂文档 LLM 结构切分、回退策略、分片质量监控
+- 交付：
+  - `scan` 默认 LLM 结构分析
+  - LLM 调用失败时回退 size split
+  - 关键指标：章节召回率、跨块断裂率、回退率
+- 验收：
+  - 50 页以上复杂文档可稳定输出 manifest
+  - 同一输入重复执行，chunk 数波动在可控范围
+  - 回退率可观测，异常时可快速定位
+
+### M2：analyze/merge 质量提升
+
+- 范围：并行分析鲁棒性、跨 chunk 去重与冲突识别
+- 交付：
+  - 分析失败重试与错误分级
+  - 去重策略对比报告（conservative vs aggressive）
+  - 冲突输出结构化（可追溯 sourceChunk）
+- 验收：
+  - 并行分析中单 chunk 失败不拖垮全局
+  - merge 结果可解释（为何合并/为何冲突）
+
+### M3：plan/dispatch 可执行性增强
+
+- 范围：任务依赖正确性、分配策略可解释性
+- 交付：
+  - 任务图拓扑校验
+  - dispatch 负载均衡与技能匹配报告
+- 验收：
+  - task plan 无循环依赖
+  - dispatch 后 `unassigned` 可控且有原因
+
+### M4：二阶段扩展（规划）
+
+- 范围：build/review/test/ship 命令原型
+- 交付：`dispatch_plan.json` -> 代码生成与验证链路
+- 验收：最小端到端样例可从文档走到可运行项目骨架
+
+---
+
+## 八、后续扩展
+
+第一阶段完成后，dispatch_plan.json 可作为第二阶段输入：
+
+```bash
+# 第二阶段：并行构建（未来实现）
+spec-agent build --dispatch ./workspace/dispatch_plan.json --output ./build/
+```
+
+可扩展的命令：
+
+- `build` — 按分配方案并行生成代码
+- `review` — 自动代码审查
+- `test` — 生成并运行测试
+- `ship` — 打包发布
+
+---
+
+## 九、技术栈
+
+| 组件 | 选型 |
+| ------ | ------ |
+| 运行时 | Node.js 18+ |
+| 语言 | TypeScript 5.0+ |
+| CLI 框架 | Commander.js |
+| 文档解析 | mammoth (docx), pdf-parse, cheerio (html), remark (md) |
+| 工具库 | fs-extra, glob, chalk, ora |
+
+---
+
+## 十、LLM 接入说明
+
+### 10.1 环境变量配置
+
+```bash
+# 必需 - 设置 API Key
+export OPENAI_API_KEY=your_openai_key_here
+# 或
+export LLM_API_KEY=your_key_here
+
+# 可选 - 自定义配置
+export OPENAI_BASE_URL=https://api.openai.com/v1  # 自定义 API 端点
+export LLM_MODEL=gpt-4o-mini                      # 模型选择
+export LLM_MAX_TOKENS=4000                        # 最大 token
+export LLM_TEMPERATURE=0.3                        # 温度参数
+export LLM_TIMEOUT_MS=60000                       # 单次请求超时（毫秒）
+export LLM_RETRIES=2                              # 失败重试次数
+export LLM_RETRY_DELAY_MS=1200                    # 首次重试等待（毫秒，指数退避）
+```
+
+Windows PowerShell:
+
+```powershell
+$env:OPENAI_API_KEY="your_key_here"
+```
+
+### 10.2 支持的模型
+
+- **OpenAI**: gpt-4o, gpt-4o-mini, gpt-4-turbo
+- **兼容 OpenAI API 的服务**: Claude, Gemini, 国内大模型等
+
+### 10.3 在 Cursor 中使用
+
+1. 在 Cursor 终端设置环境变量
+2. 运行 `spec-agent analyze` 命令
+3. 工具会自动调用 LLM 分析文档并提取结构化信息
+
+### 10.4 实现细节
+
+- LLM 服务模块: `src/services/llm.ts`
+- 文档解析模块: `src/services/document-parser.ts`
+- 支持格式: Markdown, PDF, DOCX, HTML, TXT
+- 分析提示词模板可根据 focus 参数调整
+
+---
+
+*文档版本: 1.1.0*
+*最后更新: 2026-04-01（实现对齐修订）*