spec-agent

需求文档拆解与 Agent-ready 任务规划 CLI 工具。

安装后完整使用指引

如果你是通过 npm 公网安装并希望从零开始跑通，建议先阅读：

• USAGE.md（可执行手册：命令用途/输入输出/复制即用示例）
• IMPLEMENTATION.md

在 Cursor 中使用

建议启用以下通用规则/技能：

• .cursor/rules/spec-agent/spec-agent-assistant.mdc
• .cursor/rules/frontend-standard/vue3-antdv-standard.mdc
• .cursor/skills/spec-agent-product-dev-agent/SKILL.md
• .cursor/skills/standard-frontend-vue3-antdv/SKILL.md

推荐启动语句：

请按 spec-agent-product-dev-agent 流程启动，并按 standard-frontend-vue3-antdv 规范推进一轮开发。

慢网安装建议（强烈推荐）：

• 镜像优先：https://registry.npmmirror.com，失败再切 https://registry.npmjs.org。
• 默认可自动执行脚手架/安装/验证命令；若出现连续重试或超时，再切手动单步并按命令输出证据推进。

零人工确认推荐命令：

spec-agent pipeline --input ./docs --output ./output
spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4 --continuous --theme-color "#1677ff"

说明：

• 不加 --manual-feedback 时，默认自动回填与自动调度。
• --continuous 会循环推进直到 DONE 或 PARTIAL_FAILED。

1. 配置环境变量

在 Cursor 的终端中设置 API Key：

# 推荐：统一使用 LLM_*（适配 OpenAI 及各类兼容服务）
export LLM_API_KEY=your_key_here
export LLM_BASE_URL=https://api.your-provider.com/v1
export LLM_MODEL=gpt-4o-mini
export LLM_TIMEOUT_MS=60000
export LLM_RETRIES=2
export LLM_RETRY_DELAY_MS=1200

# 兼容别名（可选）
# export OPENAI_API_KEY=your_key_here
# export OPENAI_BASE_URL=https://api.openai.com/v1

Windows PowerShell:

$env:LLM_API_KEY="your_key_here"
$env:LLM_BASE_URL="https://api.your-provider.com/v1"
$env:LLM_MODEL="gpt-4o-mini"

2. 快速开始

# 1. 扫描文档，生成分片清单
spec-agent scan --input ./docs --output ./output/manifest.json

# 2. 并行分析文档（需要配置 API Key）
spec-agent analyze --manifest ./output/manifest.json --output ./output/summaries

# 3. 合并分析结果
spec-agent merge --summaries ./output/summaries --output ./output/spec_summary.json

# 4. 生成任务计划（标准 Vue3 + AntDV）
spec-agent plan --spec ./output/spec_summary.json --output ./output/task_plan.json

# 5. 分配任务给不同 Agent
spec-agent dispatch --plan ./output/task_plan.json --output ./output/dispatch_plan.json

# 6. 生成可投喂编码工具的 handoff 包（v2 beta 起点）
spec-agent handoff --workspace ./output --target cursor --include-summaries --theme-color "#1677ff"

# 或者一键执行全部
spec-agent pipeline --input ./docs --output ./output

3. 命令详解

scan - 文档扫描

spec-agent scan --input <path> --output <manifest.json> [options]

Options:
  --chunk-size <size>    分片大小 (默认: 200kb)
  --min-chunk-size <size> 小分片合并阈值 (默认: 10kb)
  --no-llm-chunking      关闭 LLM 智能切分，改为规则切分
  --strict-llm           LLM 切分失败时直接报错（不回退）
  --format <type>        文档格式: auto, md, pdf, docx, html
  --dry-run             预览分片计划

说明：

• scan 默认启用 LLM 结构分析（按语义和行号切分），更适合复杂文档。
• 当 LLM 调用临时失败时，会自动退回到“按大小强制切分”，避免使用脆弱的标题正则切分。
• scan 现在会提取文档中的嵌入图片（如 docx 内截图）并保留图片引用，不再直接丢弃图片信息。
• 在已配置 LLM 且模型支持多模态时，scan 会为图片生成简要语义摘要并写入 chunk 文本。

analyze - 并行分析

spec-agent analyze --manifest <path> --output <dir> [options]

Options:
  --agents <count>      并行 Agent 数量 (默认: auto)
  --chunks <indices>    指定分析的 chunk，如: 0,1,2
  --focus <type>        分析重点: full, features, data-model, api, pages
  --retries <count>     单个 chunk 失败后的重试次数 (默认: 1)
  --dry-run            预览分析计划

说明：

• 若有失败 chunk，会在输出目录生成 analyze_failures.json，便于后续重跑或排查。

merge - 合并结果

spec-agent merge --summaries <dir> --output <spec.json> [options]

Options:
  --strategy <type>     去重策略: conservative, aggressive

plan - 生成任务计划

spec-agent plan --spec <path> --output <plan.json> [options]

Options:
  --framework <name>    目标框架（默认 vue3-antd）
  --type <type>         输出类型: prototype, code, docs

dispatch - 任务分配

spec-agent dispatch --plan <path> --output <plan.json> [options]

Options:
  --pool <agents>       Agent 池配置，如: frontend:2,backend:1

pipeline - 一键执行

spec-agent pipeline --input <path> --output <dir> [options]

Options:
  --chunk-size <size>   分片大小 (默认: 200kb)
  --min-chunk-size <size> 小分片合并阈值 (默认: 10kb)
  --analyze-retries <count> analyze 阶段单 chunk 重试次数 (默认: 1)
  --analyze-budget-tokens <count> analyze 阶段 token 预算上限 (默认: 0=不限制)
  --strict-llm          LLM 切分失败时直接报错（不回退）
  --from <phase>        从指定阶段恢复: scan, analyze, merge, plan, dispatch
  --stop-at <phase>     执行到指定阶段停止

doctor - 环境自检

spec-agent doctor --workspace <dir> [--check-llm] [--check-frontend-baseline <projectDir>]

handoff - 生成执行交接包

spec-agent handoff --workspace <dir> [options]

Options:
  --output <dir>        handoff 输出目录 (默认: handoff)
  --target <name>       目标工具: cursor, qcoder, codebuddy, generic
  --theme-color <hex>   手工指定主题主色（如 #1677ff，优先于原型提取）
  --include-summaries   将 summaries 目录作为必需证据输入
  --dry-run             预览交接包生成计划

execute - v2 beta 执行状态机

spec-agent execute --workspace <dir> [options]

Options:
  --max-parallel <count> 最大并行运行任务数 (默认: 4)
  --retry <count>        单任务失败后重试次数 (默认: 1)
  --complete <ids>       标记任务完成，如: T001,T002
  --fail <ids>           标记任务失败，如: T003
  --error <message>      配合 --fail 写入失败原因
  --reset                重置 run_state 后重新初始化
  --dry-run              仅预览状态迁移，不写文件

orchestrate - 产物驱动决策（v2 beta）

spec-agent orchestrate --workspace <dir> [options]

Options:
  --input <path>         pipeline 输入目录（用于下一步建议）(默认: ./docs)
  --target <name>        执行目标: cursor, qcoder, codebuddy, generic
  --max-parallel <count> execute 推荐并行度 (默认: 4)
  --format <format>      输出格式: text, json (默认: text)
  --dry-run              仅预览决策，不写 orchestrator_context.json

round - 单轮自动推进（v2 beta）

spec-agent round --workspace <dir> [options]

Options:
  --input <path>         pipeline 输入目录（默认: ./docs）
  --target <name>        执行目标: cursor, qcoder, codebuddy, generic
  --max-parallel <count> execute 并行度 (默认: 4)
  --retry <count>        单任务失败重试次数 (默认: 1)
  --theme-color <hex>    指定主题主色并透传给 handoff（如 #1677ff）
  --continuous           持续循环执行 round，直到 DONE/PARTIAL_FAILED
  --interval-seconds <n> 连续轮询间隔秒数 (默认: 1)
  --max-rounds <n>       连续模式最大轮次保护 (默认: 200)
  --manual-feedback      开启手动反馈闸门（关闭默认自动推进）
  --complete <ids>       回填成功任务，如: T001,T002
  --fail <ids>           回填失败任务，如: T003
  --error <message>      配合 --fail 写入失败原因
  --dry-run              仅预览，不执行实际命令

退出码约定（用于脚本/CI）

• scan:
  • 1 输入错误（路径/参数）
  • 2 配置错误（LLM API Key 缺失）
  • 3 严格 LLM 模式失败（--strict-llm）
  • 10 其他运行时错误
• analyze:
  • 1 输入错误（manifest/chunk 索引）
  • 2 配置错误（LLM 配置）
  • 3 部分 chunk 失败（会生成 analyze_failures.json）
  • 10 其他运行时错误
• doctor:
  • 2 存在失败检查项
  • 1 命令本身运行失败
• pipeline:
  • 2 任一阶段失败（同时输出 pipeline_summary.json 与 run_report.json）

status - 查看状态

spec-agent status --workspace <dir>

clean - 清理文件

spec-agent clean --workspace <dir> [--all]

4. 环境变量配置

| 变量 | 说明 | 默认值 | | ---- | ---- | ---- | | LLM_API_KEY | 通用 LLM API Key（推荐） | - | | OPENAI_API_KEY | OpenAI API Key（兼容别名） | - | | LLM_BASE_URL / OPENAI_BASE_URL | API 基础 URL | https://api.openai.com/v1 | | LLM_MODEL | 模型名称 | gpt-4o-mini | | LLM_MAX_TOKENS | 最大 token 数 | 4000 | | LLM_TEMPERATURE | 温度参数 | 0.3 | | LLM_TIMEOUT_MS | 单次请求超时（毫秒） | 60000 | | LLM_RETRIES | 请求失败重试次数 | 2 | | LLM_RETRY_DELAY_MS | 首次重试等待毫秒（指数退避） | 1200 | | LLM_IMAGE_MAX_PER_DOC | 每个文档最多做语义理解的图片数 | 12 | | LLM_IMAGE_MAX_BYTES | 单张图片最大请求字节（超出跳过） | 2097152 | | PDF_IMAGE_PAGE_LIMIT | PDF 最多抽取多少页做图片语义理解 | 8 | | MAX_ANALYZE_TOKENS | analyze 阶段总 token 预算（0=不限制） | 0 |

说明：

• PDF 图片页抽取依赖系统命令 pdftoppm（Poppler）。若环境中不存在该命令，流程会自动降级为仅文本解析，不会中断。

阿里百炼（DashScope）配置示例

PowerShell（当前终端生效）：

$env:LLM_API_KEY="你的百炼API-KEY"
$env:LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:LLM_MODEL="qwen-vl-plus"
$env:MAX_ANALYZE_TOKENS="250000"

PowerShell（持久化到用户环境变量）：

setx LLM_API_KEY "你的百炼API-KEY"
setx LLM_BASE_URL "https://dashscope.aliyuncs.com/compatible-mode/v1"
setx LLM_MODEL "qwen-vl-plus"
setx MAX_ANALYZE_TOKENS "250000"

可用以下命令验证配置是否生效：

node dist/index.js doctor --workspace . --check-llm --format json

5. 工作流程

┌─────────┐    ┌──────────┐    ┌────────┐    ┌────────┐    ┌──────────┐
│  Scan   │ → │ Analyze  │ → │ Merge  │ → │  Plan  │ → │ Dispatch │
│ (Scanner)│    │(Analyst×N)│    │(Architect)│    │(Planner)│    │(Dispatcher)│
└─────────┘    └──────────┘    └────────┘    └────────┘    └──────────┘
     │              │              │            │              │
     ▼              ▼              ▼            ▼              ▼
 manifest.json  chunk_*.json   spec.json   task_plan.json  dispatch.json

原型图相关产物（当需求文档含图片时）：

• output/prototypes/*：抽取后的原型图文件
• output/prototype_index.json：原型图索引（ID、路径、来源、摘要、sourceChunks）
• output/prototype_index.md：便于人工查看的原型总览
• output/handoff/tasks/*.md：任务提示词内自动附带匹配到的原型引用

6. 支持的文档格式

• .md - Markdown
• .txt - 纯文本
• .html / .htm - HTML
• .pdf - PDF (需要安装依赖)
• .docx - Word 文档 (需要安装依赖)

7. 断点恢复

如果流程中断，可以从任意阶段恢复：

# 查看当前状态
spec-agent status --workspace ./output

# 从指定阶段恢复
spec-agent pipeline --input ./docs --output ./output --from analyze

版本节奏

• v1.x：需求拆解 + 任务规划（scan/analyze/merge/plan/dispatch）
• v2.x：多 Agent 执行（Beta）——先通过 handoff 打通“可执行任务包”
• v3.x：多 Agent 闭环（执行 + 回填 + 验收）

开发

# 安装依赖
npm install

# 编译
npm run build

# 开发模式
npm run dev

Cursor 智能体分发

如果你要把本工具作为“可直接调用的 Cursor 智能体”交付给其他人，请看：

• USAGE.md