spec-agent 2.0.6 → 2.0.7

package/{spec-agent-implementation.md → IMPLEMENTATION.md}

@@ -1,814 +1,814 @@
-# SpecAgent CLI — 实现对齐版设计方案
-
-## 一、项目概述
-
-**目标**：解决几百 MB 需求文档难以稳定理解的问题，先完成“需求拆解 + Agent-ready 任务规划”，再演进到多 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           # 学习积累模式
-│   │   ├── handoff.ts         # 生成多 Agent 执行交接包（v2 beta）
-│   │   ├── execute.ts         # v2 beta 执行状态机（run_state/report）
-│   │   ├── 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`
-
----
-
-### 3.12 handoff — 生成执行交接包（v2 beta 起点）
-
-```bash
-spec-agent handoff --workspace ./workspace --target cursor --include-summaries
-```
-
-**功能**：
-
-- 从 `task_plan.json + dispatch_plan.json` 生成机器可读与人可读交接包
-- 输出每个 Agent 的任务队列（`agents/*.md`）
-- 输出每个任务的可执行提示词模板（`tasks/*.md`）
-- 产出 `handoff_bundle.json`，便于后续接入 execute/collect/review
-
----
-
-### 3.13 execute — 执行状态机（v2 beta）
-
-```bash
-# 初始化并调度首批任务
-spec-agent execute --workspace ./workspace --max-parallel 4
-
-# 回填成功
-spec-agent execute --workspace ./workspace --complete T001,T002
-
-# 回填失败（按 retry 策略进入 pending 或 failed）
-spec-agent execute --workspace ./workspace --fail T003 --error "build failed"
-```
-
-**功能**：
-
-- 从 `handoff_bundle.json` 初始化 `execution/run_state.json`
-- 按依赖与并行度调度任务进入 `running`
-- 支持手动回填任务 `succeeded/failed`
-- 产出 `execution/execution_report.json` 供实验评估
-
----
-
-### 3.14 orchestrate — 产物驱动决策（v2 beta）
-
-```bash
-spec-agent orchestrate --workspace ./workspace --input ./docs --target cursor --max-parallel 4
-```
-
-**功能**：
-
-- 读取 `manifest/spec/task_plan/dispatch/handoff/run_state/report` 等产物
-- 输出统一决策上下文 `orchestrator_context.json`
-- 基于当前产物状态给出下一条建议命令
-- 支持 `--format json` 供上层 Agent/Skill 程序化消费
-
----
-
-## 四、核心类型定义
-
-```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/
-```
-
----
-
-## 七、实施里程碑与验收清单
-
-发布节奏：
-
-- `v1.x`：拆解 + 规划
-- `v2.x`：多 Agent 执行（Beta）
-- `v3.x`：多 Agent 闭环（执行 + 回填 + 验收）
-
-### 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 LLM_API_KEY=your_key_here
-
-# 可选 - 自定义配置
-export LLM_BASE_URL=https://api.your-provider.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                    # 首次重试等待（毫秒，指数退避）
-
-# 兼容别名（可选）
-# export OPENAI_API_KEY=your_openai_key_here
-# export OPENAI_BASE_URL=https://api.openai.com/v1
-```
-
-Windows PowerShell:
-
-```powershell
-$env:LLM_API_KEY="your_key_here"
-$env:LLM_BASE_URL="https://api.your-provider.com/v1"
-$env:LLM_MODEL="gpt-4o-mini"
-```
-
-### 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（实现对齐修订）*
+# SpecAgent CLI — 实现对齐版设计方案
+
+## 一、项目概述
+
+**目标**：解决几百 MB 需求文档难以稳定理解的问题，先完成“需求拆解 + Agent-ready 任务规划”，再演进到多 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           # 学习积累模式
+│   │   ├── handoff.ts         # 生成多 Agent 执行交接包（v2 beta）
+│   │   ├── execute.ts         # v2 beta 执行状态机（run_state/report）
+│   │   ├── 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`
+
+---
+
+### 3.12 handoff — 生成执行交接包（v2 beta 起点）
+
+```bash
+spec-agent handoff --workspace ./workspace --target cursor --include-summaries
+```
+
+**功能**：
+
+- 从 `task_plan.json + dispatch_plan.json` 生成机器可读与人可读交接包
+- 输出每个 Agent 的任务队列（`agents/*.md`）
+- 输出每个任务的可执行提示词模板（`tasks/*.md`）
+- 产出 `handoff_bundle.json`，便于后续接入 execute/collect/review
+
+---
+
+### 3.13 execute — 执行状态机（v2 beta）
+
+```bash
+# 初始化并调度首批任务
+spec-agent execute --workspace ./workspace --max-parallel 4
+
+# 回填成功
+spec-agent execute --workspace ./workspace --complete T001,T002
+
+# 回填失败（按 retry 策略进入 pending 或 failed）
+spec-agent execute --workspace ./workspace --fail T003 --error "build failed"
+```
+
+**功能**：
+
+- 从 `handoff_bundle.json` 初始化 `execution/run_state.json`
+- 按依赖与并行度调度任务进入 `running`
+- 支持手动回填任务 `succeeded/failed`
+- 产出 `execution/execution_report.json` 供实验评估
+
+---
+
+### 3.14 orchestrate — 产物驱动决策（v2 beta）
+
+```bash
+spec-agent orchestrate --workspace ./workspace --input ./docs --target cursor --max-parallel 4
+```
+
+**功能**：
+
+- 读取 `manifest/spec/task_plan/dispatch/handoff/run_state/report` 等产物
+- 输出统一决策上下文 `orchestrator_context.json`
+- 基于当前产物状态给出下一条建议命令
+- 支持 `--format json` 供上层 Agent/Skill 程序化消费
+
+---
+
+## 四、核心类型定义
+
+```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/
+```
+
+---
+
+## 七、实施里程碑与验收清单
+
+发布节奏：
+
+- `v1.x`：拆解 + 规划
+- `v2.x`：多 Agent 执行（Beta）
+- `v3.x`：多 Agent 闭环（执行 + 回填 + 验收）
+
+### 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 LLM_API_KEY=your_key_here
+
+# 可选 - 自定义配置
+export LLM_BASE_URL=https://api.your-provider.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                    # 首次重试等待（毫秒，指数退避）
+
+# 兼容别名（可选）
+# export OPENAI_API_KEY=your_openai_key_here
+# export OPENAI_BASE_URL=https://api.openai.com/v1
+```
+
+Windows PowerShell:
+
+```powershell
+$env:LLM_API_KEY="your_key_here"
+$env:LLM_BASE_URL="https://api.your-provider.com/v1"
+$env:LLM_MODEL="gpt-4o-mini"
+```
+
+### 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（实现对齐修订）*