spec-agent 2.0.6 → 2.0.7

package/USAGE_FROM_NPM.md

@@ -1,286 +0,0 @@
-# spec-agent 公网安装与使用完整指引
-
-本文档用于从零开始指导你：
-
-- 从 npm 公网安装 `spec-agent`
-- 配置 LLM 环境
-- 跑通完整流程（scan/analyze/merge/plan/dispatch 或 pipeline）
-- 生成可直接投喂 Cursor/QCoder/CodeBuddy 的 handoff 任务包
-- 处理私有源与公网源切换
-- 查看 `--help` 与常见问题排查
-
----
-
-## 1. 前置条件
-
-- Node.js >= 18（推荐 20/22）
-- 已有可用 LLM API（例如阿里云百炼兼容 OpenAI 的接口）
-- 准备好输入文档目录（支持 `md/pdf/docx/html/txt`）
-
-可选检查：
-
-```bash
-node -v
-npm -v
-```
-
----
-
-## 2. 从公网 npm 安装
-
-如果你的默认 npm 源是公司私有源，请显式指定公网安装：
-
-```bash
-npm install -g spec-agent@latest --registry=https://registry.npmjs.org/
-```
-
-安装完成后检查：
-
-```bash
-spec-agent --version
-spec-agent --help
-```
-
-短命令别名也可用：
-
-```bash
-sa --help
-```
-
----
-
-## 3. 创建工作目录
-
-建议每个项目单独一个工作目录：
-
-```bash
-mkdir my-spec-work
-cd my-spec-work
-mkdir docs output
-```
-
-- 把要分析的文档放进 `docs`
-- 产物默认输出到 `output`
-
----
-
-## 4. 配置 LLM（PowerShell 示例）
-
-在当前终端设置（快速验证）：
-
-```powershell
-$env:LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
-$env:LLM_API_KEY="你的APIKey"
-$env:LLM_MODEL="qwen-vl-plus"
-```
-
-可选控成本参数：
-
-```powershell
-$env:MAX_ANALYZE_TOKENS="120000"
-$env:LLM_IMAGE_MAX_PER_DOC="8"
-$env:LLM_IMAGE_MAX_BYTES="4000000"
-```
-
----
-
-## 5. 先做环境自检
-
-```bash
-spec-agent doctor --workspace ./output --check-llm
-```
-
-如果这里失败，先修复配置再继续跑 pipeline。
-
----
-
-## 6. 一键执行全流程（推荐）
-
-```bash
-spec-agent pipeline --input ./docs --output ./output
-```
-
-常用增强参数：
-
-```bash
-spec-agent pipeline --input ./docs --output ./output --strict-llm --analyze-retries 2 --analyze-budget-tokens 120000
-```
-
-说明：
-
-- `--strict-llm`：LLM 失败时不降级，直接报错，适合质量优先场景
-- `--analyze-retries`：analyze 阶段失败重试次数
-- `--analyze-budget-tokens`：analyze 阶段 token 预算
-
----
-
-## 7. 分步执行（可调试）
-
-```bash
-spec-agent scan --input ./docs --output ./output/manifest.json
-spec-agent analyze --manifest ./output/manifest.json --output ./output/summaries
-spec-agent merge --summaries ./output/summaries --output ./output/spec_summary.json
-spec-agent plan --spec ./output/spec_summary.json --output ./output/task_plan.json
-spec-agent dispatch --plan ./output/task_plan.json --output ./output/dispatch_plan.json
-```
-
----
-
-## 8. 常用运维命令
-
-查看当前工作区状态：
-
-```bash
-spec-agent status --workspace ./output
-```
-
-从某阶段恢复继续跑：
-
-```bash
-spec-agent pipeline --input ./docs --output ./output --from analyze
-```
-
-清理中间产物：
-
-```bash
-spec-agent clean --workspace ./output
-```
-
-生成多 Agent 执行交接包（v2 beta 起点）：
-
-```bash
-spec-agent handoff --workspace ./output --target cursor --include-summaries
-```
-
-执行状态机（v2 beta，先做实验）：
-
-```bash
-# 第一次执行：初始化 run_state 并调度首批任务
-spec-agent execute --workspace ./output --max-parallel 4
-
-# 回填执行结果：将已完成任务标记为 succeeded
-spec-agent execute --workspace ./output --complete T001,T002
-
-# 回填失败并触发重试/最终失败
-spec-agent execute --workspace ./output --fail T003 --error "compile failed"
-
-# 生成下一步决策与上下文（orchestrator）
-spec-agent orchestrate --workspace ./output --input ./docs
-
-# 一轮自动推进（会自动选择 pipeline / handoff / execute）
-spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
-
-# 一条命令完成“回填 + 下一轮推进”
-spec-agent round --workspace ./output --input ./docs --complete T001,T002 --fail T003 --error "compile failed"
-```
-
----
-
-## 9. `--help` 使用方式
-
-总帮助：
-
-```bash
-spec-agent --help
-```
-
-子命令帮助：
-
-```bash
-spec-agent scan --help
-spec-agent analyze --help
-spec-agent merge --help
-spec-agent plan --help
-spec-agent dispatch --help
-spec-agent pipeline --help
-spec-agent doctor --help
-spec-agent status --help
-spec-agent clean --help
-```
-
----
-
-## 10. 常见问题
-
-### Q1: 安装时报 404，找不到包
-
-大概率是走了私有源。请显式指定公网：
-
-```bash
-npm install -g spec-agent --registry=https://registry.npmjs.org/
-```
-
-并检查当前 registry：
-
-```bash
-npm config get registry
-```
-
-### Q2: 发布时报 `ENEEDAUTH`
-
-说明没登录公网 npm。执行：
-
-```bash
-npm login --registry=https://registry.npmjs.org/
-```
-
-### Q3: 发布时报 `E403`，提示 2FA 或 token 权限不足
-
-按 npm 安全策略，需要：
-
-- 开启账号 2FA（Auth and Writes），或
-- 使用带 publish 权限且允许 bypass 2FA 的 token
-
-### Q4: 命令存在但分析失败
-
-先跑：
-
-```bash
-spec-agent doctor --workspace ./output --check-llm
-```
-
-再确认：
-
-- `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL` 是否正确
-- 网络可访问模型接口
-- 输入文档是否可读
-
----
-
-## 11. 私有源与公网源切换参考
-
-切到公网：
-
-```bash
-npm config set registry https://registry.npmjs.org/
-```
-
-切回私有源（示例）：
-
-```bash
-npm config set registry https://nexus.cyberway.com.cn/repository/npmGroup/
-```
-
-只想单次使用公网，不改全局配置：
-
-```bash
-npm install -g spec-agent --registry=https://registry.npmjs.org/
-```
-
----
-
-## 12. 推荐首次执行顺序
-
-```bash
-spec-agent --version
-spec-agent --help
-spec-agent doctor --workspace ./output --check-llm
-spec-agent pipeline --input ./docs --output ./output
-spec-agent status --workspace ./output
-```
-
-执行完成后，核心结果通常在：
-
-- `output/spec_summary.json`
-- `output/task_plan.json`
-- `output/dispatch_plan.json`

package/orchestrator-v2-design.md

@@ -1,193 +0,0 @@
-# Spec-Agent Orchestrator v2 设计方案
-
-## 1. 目标与范围
-
-本方案用于将 `spec-agent` 从“产物生成工具”升级为“可持续推进执行的智能体编排器”。
-
-核心目标：
-
-- 自动调用 `spec-agent` CLI（pipeline/handoff/execute）
-- 基于产物做决策，不依赖人工记忆当前状态
-- 支持失败重试与中断恢复
-- 输出明确下一步动作，降低人工操作成本
-
-非目标（v2 不做）：
-
-- 自动提交 PR / 自动合并代码
-- 跨仓库复杂编排
-- 无约束的自动改代码
-
----
-
-## 2. 总体架构
-
-建议采用 4 个职责清晰的 Agent 角色：
-
-- **Onboarding Agent**：检查安装与环境，确保首次可运行
-- **Pipeline Agent**：负责 scan -> analyze -> merge -> plan -> dispatch
-- **Execution Orchestrator Agent**：负责 handoff + execute 循环推进
-- **Failure Triage Agent**：负责错误分流、修复建议与重试策略
-
-说明：v2 初版可由一个主 Agent 执行上述职责；v2.1 后再拆分为多 Agent 角色。
-
----
-
-## 3. 输入与输出契约
-
-### 3.1 关键输入产物
-
-- `output/manifest.json`
-- `output/spec_summary.json`
-- `output/task_plan.json`
-- `output/dispatch_plan.json`
-- `output/handoff/handoff_bundle.json`
-- `output/execution/run_state.json`
-- `output/execution/execution_report.json`
-- `output/execution/inbox/*.md`
-
-### 3.2 Orchestrator 统一上下文文件
-
-新增文件：
-
-- `output/orchestrator_context.json`
-
-用途：
-
-- 记录当前阶段、上次动作、最近错误、下一步建议
-- 为 Agent 提供单一事实源（single source of truth）
-
-建议结构：
-
-```json
-{
-  "version": "2.0.0-beta",
-  "updatedAt": "2026-04-02T10:00:00Z",
-  "workspace": "./output",
-  "state": "EXECUTION_RUNNING",
-  "lastAction": "spec-agent execute --workspace ./output --max-parallel 4",
-  "lastError": null,
-  "nextAction": "等待回填：--complete/--fail",
-  "metrics": {
-    "pending": 120,
-    "running": 4,
-    "succeeded": 33,
-    "failed": 2,
-    "blocked": 1
-  }
-}
-```
-
----
-
-## 4. 状态机设计
-
-状态定义：
-
-- `INIT`
-- `READY`
-- `PIPELINE_RUNNING`
-- `PIPELINE_READY`
-- `EXECUTION_RUNNING`
-- `WAITING_FEEDBACK`
-- `PARTIAL_FAILED`
-- `DONE`
-
-状态转移规则（简化）：
-
-1. `INIT -> READY`：安装与环境检查通过
-2. `READY -> PIPELINE_RUNNING`：触发 pipeline
-3. `PIPELINE_RUNNING -> PIPELINE_READY`：产物齐全（task_plan + dispatch_plan）
-4. `PIPELINE_READY -> EXECUTION_RUNNING`：生成 handoff 并首次 execute
-5. `EXECUTION_RUNNING -> WAITING_FEEDBACK`：存在 running 任务，等待回填
-6. `WAITING_FEEDBACK -> EXECUTION_RUNNING`：回填完成，继续调度
-7. 任意状态 -> `PARTIAL_FAILED`：关键错误出现且不可自动恢复
-8. `EXECUTION_RUNNING -> DONE`：pending/running/blocked 归零
-
----
-
-## 5. 决策规则（执行引擎）
-
-按优先级从上到下判断：
-
-1. 若 `spec-agent --version` 失败：
-   - 提示安装：`npm install -g spec-agent --registry=https://registry.npmjs.org/`
-2. 若 `dispatch_plan.json` 不存在：
-   - 执行 `spec-agent pipeline --input ./docs --output ./output`
-3. 若 `handoff_bundle.json` 不存在：
-   - 执行 `spec-agent handoff --workspace ./output --target cursor --include-summaries`
-4. 若 `run_state.json` 不存在：
-   - 执行 `spec-agent execute --workspace ./output --max-parallel 4`
-5. 若 `run_state` 中有 `running`：
-   - 进入等待反馈，不重复调度
-6. 若 `pending > 0` 且 `running = 0`：
-   - 再次执行 `execute` 调度
-7. 若 `failed` 增长：
-   - 调用故障分流策略，给出重试或人工介入建议
-
----
-
-## 6. MVP 边界（先做可实验）
-
-v2 初版仅包含：
-
-- 安装检查与首轮 pipeline 引导
-- handoff + execute 调度闭环
-- `--complete / --fail` 回填推进
-- `orchestrator_context.json` 最小写入
-
-v2 初版不包含：
-
-- 自动代码生成与自动代码回填
-- 自动 PR 流程
-- 高级冲突自动修复
-
----
-
-## 7. 失败分流策略
-
-错误类别与处理：
-
-- **安装类**（command not found）
-  - 给出安装命令与版本校验命令
-- **认证类**（npm ENEEDAUTH / E403）
-  - 给出登录或 2FA/token 指引
-- **配置类**（LLM key/base_url/model 缺失）
-  - 给出 `doctor --check-llm` 与变量模板
-- **执行类**（task failed）
-  - 记录 error，按 `--retry` 重试，超限标记 failed
-
----
-
-## 8. 实施计划
-
-### Milestone A（1-2 天）
-
-- 落地 `orchestrator_context.json`
-- 实现决策函数（只读产物 -> 推荐命令）
-
-### Milestone B（2-3 天）
-
-- 将决策函数接入现有 Skill（onboarding + execution）
-- 支持一键“执行一轮”指令
-
-### Milestone C（2-3 天）
-
-- 加入失败分流模板（安装、认证、LLM、执行）
-- 增加轮次摘要输出（可复盘）
-
----
-
-## 9. 验收标准
-
-- 新环境可从未安装状态引导至 `pipeline` 完成
-- 可连续推进至少 3 轮 execute，不丢失状态
-- 中断重开后可依据 `run_state` 和 `orchestrator_context` 恢复
-- 每轮输出明确下一步命令，不要求用户自行推断
-
----
-
-## 10. 版本节奏对齐
-
-- `v1.x`：拆解 + 规划
-- `v2.x`：多 Agent 执行（Beta）
-- `v3.x`：多 Agent 闭环（执行 + 回填 + 验收）