sillyspec 3.8.4 → 3.8.6

package/docs/sillyspec/commands.md

@@ -0,0 +1,218 @@
+# 命令参考
+
+## 核心流程
+
+### init — 绿地项目初始化
+
+**用途：** 深度提问、调研、生成需求文档和路线图。
+
+```bash
+sillyspec init
+```
+
+适用于空目录或新项目。会通过一系列问题挖掘需求，生成项目路线图。
+
+---
+
+### scan — 代码库扫描
+
+**用途：** 交互式引导扫描已有代码库，生成代码库文档。
+
+```bash
+sillyspec run scan
+```
+
+支持快速扫描和深度扫描两阶段。深度扫描会提取代码风格、注解、返回值等信息。
+
+---
+
+### brainstorm — 需求探索
+
+**用途：** 结构化头脑风暴，直接产出 design.md + proposal.md + requirements.md + tasks.md。
+
+```bash
+sillyspec run brainstorm
+```
+
+创建性工作前的必用命令。合并了 propose 功能，一次性生成所有规范文件。包含批量/半批量模式检测。
+
+---
+
+### plan — 实现计划
+
+**用途：** 编写实现计划，plan.md 总览 + tasks/task-N.md 独立蓝图。
+
+```bash
+sillyspec run plan
+```
+
+按 Wave 分组任务，每个任务产出独立的 task-N.md 蓝图（接口定义、数据结构、边界处理、TDD 步骤、验收标准）。plan.md 只放总览，不写实现细节。
+
+---
+
+### execute — 执行实现
+
+**用途：** 波次执行，按 task 蓝图搬砖，禁止发散思维。
+
+```bash
+sillyspec run execute
+```
+
+CLI 自动注入 task-N.md 内容到 prompt。上下文分层加载（热/温/冷）。不频繁编译，只在必要时运行。
+
+**铁律：**
+- task-N.md 是唯一执行蓝图，只做蓝图里写的事，不增不减不改
+- 发现问题停下来反馈，不要自己改方案
+- Reverse Sync：发现 Bug 先检查文档是否有遗漏
+
+---
+
+### verify — 验证（可选）
+
+**用途：** 对照文档检查 + 测试套件 + 代码审查 + 任务蓝图验收。
+
+```bash
+sillyspec run verify
+```
+
+分层验证：逐项检查任务 → 对照 design.md → 任务蓝图验收 → 运行测试 → 代码质量扫描。支持批量模式分层验证（L1 自动化 / L2 AI 抽查 / L3 模式性 bug 检测）。
+
+---
+
+### archive — 归档
+
+**用途：** 规范沉淀到 knowledge/，可追溯。
+
+```bash
+sillyspec run archive
+```
+
+五道门禁：文件完整性、任务完成度、spec 沉淀、防覆盖。
+
+---
+
+### doctor — 项目自检
+
+**用途：** 4 步自检，检查配置、构建环境和外部依赖。
+
+```bash
+sillyspec run doctor
+```
+
+步骤：SillySpec 内部检查 → 构建与测试检查 → 外部依赖检查 → 生成诊断报告。包含 deriveState 全量扫描。
+
+---
+
+### auto — 全流程自动推进
+
+**用途：** 自动执行 brainstorm → plan → execute → verify。
+
+```bash
+sillyspec run auto "需求描述"
+sillyspec run auto --input "需求" --done --output "摘要"  # 推进下一步
+```
+
+自动模式，AI 按步骤自动推进。支持阶段审核门控——brainstorm/plan 完成后可选多角度子代理审查。
+
+---
+
+## 辅助工具
+
+### quick — 快速模式
+
+```bash
+sillyspec run quick "任务描述"
+```
+
+跳过完整流程，直接做。3 步完成：理解任务 → 实现并验证 → 暂存和记录。支持 `--change xxx` 追加到变更 tasks.md。
+
+---
+
+### explore — 自由思考
+
+```bash
+sillyspec run explore "想法"
+```
+
+讨论、画图、调研，不写代码。
+
+---
+
+### commit — 智能提交
+
+```bash
+/sillyspec:commit
+```
+
+自动收集变更信息（QUICKLOG/tasks.md/阶段产出），生成 commit message。
+
+---
+
+### status / state — 查看进度
+
+```bash
+sillyspec progress show    # 查看进度（含批量进度条）
+/sillyspec:state           # 显示 progress.json 内容
+```
+
+---
+
+### resume / continue — 恢复工作
+
+```bash
+/sillyspec:resume          # 从中断处继续
+/sillyspec:continue        # 自动判断下一步
+```
+
+---
+
+### export — 导出模板
+
+```bash
+/sillyspec:export
+```
+
+导出成功方案为可复用模板。
+
+---
+
+### progress — 进度管理
+
+```bash
+sillyspec progress show      # 查看进度
+sillyspec progress reset     # 重置进度
+sillyspec progress validate  # 校验修复
+sillyspec progress batch --total 100 --completed 73  # 更新批量进度
+sillyspec progress batch --status                   # 查看批量进度
+```
+
+### run — 步骤驱动流程引擎
+
+**用途：** CLI 控制的阶段流程，AI 通过此命令驱动每个阶段。
+
+```bash
+sillyspec run <stage>           # 进入指定阶段
+sillyspec run <stage> --status  # 查看阶段进度
+sillyspec run <stage> --done    # 标记当前步骤完成
+sillyspec run <stage> --done --output "摘要"  # 标记完成 + 记录输出
+sillyspec run <stage> --skip    # 跳过可选步骤
+sillyspec run <stage> --reset   # 重置阶段
+```
+
+支持的阶段：`scan`、`brainstorm`、`plan`、`execute`、`verify`、`doctor`。
+
+## 其他 CLI 命令
+
+### dashboard — 启动面板
+
+```bash
+sillyspec dashboard              # 默认端口 3456
+sillyspec dashboard --port 8080  # 指定端口
+```
+
+### setup — MCP 工具安装
+
+```bash
+sillyspec setup          # 安装推荐 MCP 工具
+sillyspec setup --list   # 查看状态
+```

package/docs/sillyspec/dashboard.md

@@ -0,0 +1,51 @@
+# Dashboard
+
+## 启动
+
+```bash
+sillyspec dashboard              # 默认端口 3456
+sillyspec dashboard --port 8080  # 指定端口
+sillyspec dashboard --no-open    # 不自动打开浏览器
+```
+
+## 功能
+
+### 📂 项目发现
+
+自动扫描当前目录及子目录中的 `.sillyspec/` 项目，显示项目列表和状态。
+
+### 🔄 流水线视图
+
+可视化展示项目的工作流阶段：
+
+```
+scan → brainstorm → plan → execute → verify → archive
+  ✅       ✅        ✅      🔄       ⏳
+```
+
+每个阶段的完成状态一目了然。
+
+### 📄 文档浏览
+
+浏览项目中 `.sillyspec/docs/` 下的所有文档，按类型分组：
+
+- **scan/** — 代码库扫描文档
+- **brainstorm/** — 头脑风暴和设计文档
+- **plan/** — 实现计划
+- **changes/** — 变更记录
+- **archive/** — 归档文档
+- **quicklog/** — 快速任务日志
+
+## 统一文档管理
+
+Dashboard 支持新的统一文档结构，所有项目文档集中管理在 `.sillyspec/docs/<project>/` 下。
+
+### 迁移旧结构
+
+如果你有旧版的 `.sillyspec/` 目录（codebase/、specs/、changes/ 等），可以迁移：
+
+```bash
+sillyspec docs migrate
+```
+
+会自动将旧路径的文档迁移到新的统一结构。

package/docs/sillyspec/file-io.md

@@ -0,0 +1,34 @@
+# 各阶段文件读写一览
+
+| 阶段 | 📥 读取 | 📤 产出 |
+|------|---------|---------|
+| **brainstorm** | CODEBASE-OVERVIEW.md<br>projects/*.yaml<br>local.yaml<br>STRUCTURE.md（棕地）<br>CONVENTIONS.md（棕地）<br>ARCHITECTURE.md（棕地）<br>changes/（进行中）<br>~/.sillyspec/templates/ | design.md<br>proposal.md<br>requirements.md<br>tasks.md |
+| **plan** | CODEBASE-OVERVIEW.md<br>proposal.md<br>design.md<br>requirements.md<br>tasks.md<br>CONVENTIONS.md<br>ARCHITECTURE.md<br>STACK.md<br>local.yaml | plan.md（总览）<br>tasks/task-NN.md（蓝图） |
+| **execute** | design.md<br>plan.md<br>tasks/task-NN.md（CLI 自动注入）<br>CONVENTIONS.md（按需）<br>ARCHITECTURE.md（按需）<br>local.yaml<br>CODEBASE-OVERVIEW.md<br>knowledge/INDEX.md | 代码文件<br>勾选 task-N.md + plan.md checkbox |
+| **verify** | proposal.md<br>design.md<br>tasks.md<br>requirements.md<br>projects/*.yaml<br>local.yaml<br>CONVENTIONS.md<br>tasks/task-NN.md | 验证报告<br>可能更新 design.md（Reverse Sync） |
+| **quick** | projects/*.yaml<br>CONVENTIONS.md<br>local.yaml<br>knowledge/INDEX.md<br>design.md（有 --change） | 代码文件<br>tasks.md（有 --change）<br>QUICKLOG |
+| **scan** | projects/*.yaml<br>已有 scan/*.md<br>package.json / pom.xml 等<br>源文件（grep 搜索） | ARCHITECTURE.md<br>CONVENTIONS.md<br>STRUCTURE.md<br>INTEGRATIONS.md<br>TESTING.md<br>CONCERNS.md<br>PROJECT.md |
+| **archive** | tasks.md<br>changes/<变更名>/ 目录下文件 | archive/YYYY-MM-DD-<变更名>/（移动）<br>更新 progress.json |
+| **doctor** | progress.json<br>projects/*.yaml<br>local.yaml<br>MCP 配置<br>构建文件 | 无（只检查报告） |
+
+## 全局注入（每个 step）
+
+### Persona
+
+| 阶段 | 角色 |
+|------|------|
+| brainstorm | 🎯 资深架构师 |
+| plan | 📋 技术项目经理 |
+| execute | 💻 高级工程师 |
+| verify | 🔍 QA 专家 |
+| quick | 💻 全栈老兵 |
+
+### 铁律
+
+1. 文档是核心资产，代码是文档的产物
+2. 只做本步骤描述的操作，不得自行扩展或跳过
+3. 不要回头修改已完成的步骤
+4. 不要编造不存在的 CLI 子命令
+5. 完成后立即执行 `--done` 命令
+6. 文档类型文件头部必须包含 author 和 created_at
+7. 执行构建/测试前必须先读 local.yaml

package/docs/sillyspec/getting-started.md

@@ -0,0 +1,61 @@
+# 快速上手
+
+## 安装
+
+**推荐全局安装**，直接使用 `sillyspec` 命令：
+
+```bash
+npm i -g sillyspec@latest
+```
+
+> ⚠️ 需要 Node.js >= 18。
+
+## 初始化项目
+
+进入你的项目目录，运行：
+
+```bash
+sillyspec init
+```
+
+零交互，自动检测你用的 AI 工具并安装对应模板。
+
+**指定工具：**
+
+```bash
+sillyspec init --tool claude
+sillyspec init --tool cursor
+sillyspec init --tool openclaw
+```
+
+## 选择入口
+
+根据你的情况，选一个开始：
+
+| 场景 | 命令 | 说明 |
+|------|------|------|
+| 🟢 绿地项目（空目录） | `/sillyspec:init` | 深度提问 → 需求文档 → 路线图 |
+| 🟤 棕地项目（有代码） | `/sillyspec:scan` | 交互式扫描代码库 |
+| 💡 自由思考 | `/sillyspec:explore "想法"` | 讨论、画图、调研，不写代码 |
+| 🧩 大模块 | `/sillyspec:brainstorm` | 直接贴原型图 |
+| 🩺 项目自检 | `sillyspec run doctor` | 4 步自检环境 |
+
+## 基本工作流
+
+```
+绿地：init → brainstorm → plan → execute → [verify] → archive
+棕地：scan → brainstorm → plan → execute → [verify] → archive
+```
+
+AI 通过 `sillyspec run <stage>` 命令驱动流程，每个阶段的进度由 progress.json 自动追踪。
+
+也可以跳过流程：
+
+- 小 bug：`/sillyspec:quick "修复 xxx"`
+- 不确定要做什么：`/sillyspec:explore "想法"`
+- 中断恢复：`/sillyspec:resume`
+- 不知道下一步：`/sillyspec:continue`
+
+## Skills 说明
+
+SillySpec 的 skills 已精简为核心流程，每个 skill 对应一个明确阶段，不再有多余的中间层。

package/docs/sillyspec/install.md

@@ -0,0 +1,51 @@
+# 安装指南
+
+## 系统要求
+
+- **Node.js** >= 18
+- 支持 macOS / Linux / Windows
+
+## 安装
+
+```bash
+npm i -g sillyspec@latest
+```
+
+> 💡 **推荐全局安装**，安装后直接使用 `sillyspec` 命令。
+
+## 升级
+
+```bash
+npm i -g sillyspec@latest
+```
+
+就这么简单，覆盖安装即可。
+
+## 支持的 AI 工具
+
+| 工具 | `--tool` 参数 | 输出目录 | 格式 |
+|------|---------------|----------|------|
+| Claude Code (commands) | `claude` | `.claude/commands/sillyspec/` | slash commands |
+| Claude Code (skills) | `claude_skills` | `.claude/skills/sillyspec-<name>/` | SKILL.md |
+| Cursor | `cursor` | `.cursor/commands/` | custom commands |
+| Codex | `codex` | `~/.agents/skills/sillyspec-<name>/` | SKILL.md |
+| OpenCode | `opencode` | `.opencode/skills/sillyspec-<name>/` | SKILL.md |
+| OpenClaw | `openclaw` | `.openclaw/skills/sillyspec-<name>/` | SKILL.md |
+
+## init 选项
+
+```bash
+sillyspec init                    # 自动检测工具
+sillyspec init --tool claude      # 指定工具
+sillyspec init --interactive      # 交互式引导
+sillyspec init --dir /path/to    # 指定目录
+```
+
+## MCP 增强
+
+安装推荐的 MCP 工具（如 Playwright、文件搜索等）：
+
+```bash
+sillyspec setup          # 安装
+sillyspec setup --list   # 查看已安装状态
+```

package/docs/sillyspec/lifecycle.md

@@ -0,0 +1,146 @@
+# 生命周期
+
+## 核心理念
+
+> **Code is Cheap, Context is Expensive.** 文档是核心资产，代码是文档的产物。没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。
+
+## 工作流
+
+### 🟢 绿地项目（空目录）
+
+```
+init → brainstorm → plan → execute → [verify] → archive
+```
+
+### 🟤 棕地项目（有代码）
+
+```
+scan → brainstorm → plan → execute → [verify] → archive
+```
+
+### 🩺 项目自检
+
+```
+sillyspec run doctor
+```
+
+4 步自检：SillySpec 内部检查 → 构建与测试检查 → 外部依赖检查 → 生成诊断报告。
+
+### 🤖 自动模式
+
+```
+sillyspec run auto "需求描述"
+```
+
+全流程自动推进，支持阶段审核门控（复杂需求可选多角度子代理审查）。
+
+### ⚡ 快速通道
+
+```
+quick "描述" → 直接执行（3 步：理解任务 → 实现并验证 → 暂存和记录）
+explore "想法" → 讨论不写码
+```
+
+## 角色分工
+
+每个阶段有专属 persona，由 CLI 自动注入：
+
+| 阶段 | 角色 | 职责 |
+|------|------|------|
+| brainstorm | 🎯 资深架构师 | 理解业务本质，设计技术方案，决策附理由 |
+| plan | 📋 技术项目经理 | 任务拆解，Wave 分组，依赖关系 |
+| execute | 💻 高级工程师 | 按 task 蓝图搬砖，禁止发散思维 |
+| verify | 🔍 QA 专家 | 对照文档检查，假设所有代码都有 bug |
+| quick | 💻 全栈老兵 | 快速理解需求，直接干，不确定就问 |
+
+**铁律：每个角色只做自己的事，不要越界。** 发现问题反馈而不是自己偷偷改。
+
+## 文档体系
+
+```
+.sillyspec/
+├── changes/<变更名>/
+│   ├── design.md          # 设计文档（brainstorm 产出）
+│   ├── requirements.md    # 需求文档
+│   ├── proposal.md        # 提案
+│   ├── plan.md            # 实现计划总览（PM 视角）
+│   ├── tasks/task-01.md   # 任务蓝图（工程师视角，详细到可直接执行）
+│   ├── tasks/task-02.md
+│   └── ...
+├── docs/<project>/scan/
+│   ├── CONVENTIONS.md     # 代码规范
+│   └── ARCHITECTURE.md    # 架构文档
+├── projects/*.yaml        # 项目配置
+├── local.yaml             # 本地配置（构建/测试命令）
+└── knowledge/             # 项目知识库
+```
+
+### Reverse Sync
+
+发现 Bug 时的处理流程：
+
+```
+发现 Bug → 是代码错了还是文档有遗漏？
+├── 文档遗漏 → 先修文档 → 再修代码
+└── 代码错误 → 直接修代码
+```
+
+## 上下文分层加载
+
+execute 阶段按优先级管理上下文：
+
+- 🔥 **热上下文**：design.md 编码铁律 + 当前 Wave 任务（必须加载）
+- 🌡️ **温上下文**：CONVENTIONS.md + ARCHITECTURE.md（需要时加载）
+- ❄️ **冷上下文**：其他变更的 design.md、历史 plan.md（不主动加载）
+
+## 进度管理
+
+### progress.json（唯一进度数据源）
+
+位于 `.sillyspec/.runtime/progress.json`，由 `sillyspec run` CLI 自动管理：
+
+```json
+{
+  "project": "my-app",
+  "currentStage": "execute",
+  "stages": {
+    "scan": { "status": "completed" },
+    "brainstorm": { "status": "completed" },
+    "plan": { "status": "completed" },
+    "execute": { "status": "in_progress" }
+  }
+}
+```
+
+### 批量进度
+
+批量任务时，额外展示批量进度条：
+
+```
+📊 批量进度: ████████████████░░░░ 73/100 (2 失败, 1 跳过)
+```
+
+```bash
+sillyspec progress batch --total 100 --completed 73
+sillyspec progress batch --status
+```
+
+## Git 规范
+
+- 所有阶段只执行 `git add`，**不自动 commit**
+- 提交由用户通过 `/sillyspec:commit` 或手动完成
+- commit message 语言与用户对话语言一致
+
+## 中断恢复
+
+工作中断时，使用 resume 恢复：
+
+```bash
+/sillyspec:resume
+```
+
+也可以用 continue 自动判断下一步：
+
+```bash
+/sillyspec:continue
+```

package/docs/sillyspec/structure.md

@@ -0,0 +1,62 @@
+# 目录结构
+
+## .sillyspec/ 完整结构
+
+```
+.sillyspec/
+├── changes/              ← 所有变更（design/proposal/tasks/requirements）
+│   └── <change-name>/
+│       ├── design.md          # 设计文档（架构决策、文件变更清单）
+│       ├── proposal.md        # 变更提案（动机、范围、成功标准）
+│       ├── requirements.md    # 需求文档（功能需求、用户场景）
+│       ├── plan.md            # 实现计划总览（PM 视角，任务列表 + Wave 划分）
+│       └── tasks/             # 任务蓝图目录
+│           ├── task-01.md     # 独立任务蓝图（接口定义、边界处理、TDD 步骤、验收标准）
+│           ├── task-02.md
+│           └── ...
+├── docs/                 ← 统一文档中心
+│   └── <project>/
+│       └── scan/         ← 代码扫描结果
+│           ├── CONVENTIONS.md   # 代码规范
+│           └── ARCHITECTURE.md  # 架构文档
+├── knowledge/            ← 知识库（归档沉淀）
+│   ├── INDEX.md          # 知识索引
+│   └── uncategorized.md  # 未分类知识
+├── projects/             ← 子项目注册（*.yaml）
+├── local.yaml            ← 本地配置（构建命令、测试命令、环境变量）
+└── .runtime/             ← 运行时数据
+    ├── progress.json     ← 唯一进度数据源
+    ├── artifacts/        ← 步骤输出完整内容
+    ├── logs/             ← 日志
+    └── history/          ← 历史快照
+```
+
+## 文档层级
+
+| 文档 | 谁写 | 回答什么 | 详细程度 |
+|------|------|---------|---------|
+| design.md | brainstorm（架构师） | 为什么这么设计？架构长什么样？ | 中 |
+| plan.md | plan（项目经理） | 做哪些任务？什么顺序？ | 低（总览） |
+| task-N.md | plan（项目经理） | 这个任务具体怎么做？ | 高（蓝图级） |
+| CONVENTIONS.md | scan | 代码怎么写？风格、命名、模式？ | 高 |
+| local.yaml | 用户 | 构建命令、测试命令、环境变量 | 配置 |
+
+## 产出时机
+
+```
+brainstorm → design.md + proposal.md + requirements.md + tasks.md
+plan       → plan.md + tasks/task-NN.md
+execute    → 代码 + 勾选 task-N.md 验收标准
+verify     → 对照 design.md + 检查 task-N.md 验收 + 测试
+archive    → 沉淀到 knowledge/
+```
+
+## 说明
+
+- **changes/** — 所有变更规范统一存放
+- **tasks/** — 每个任务独立蓝图，execute 子代理只读自己的蓝图就能干活
+- **projects/** — 管理多个子项目
+- **docs/** — 文档中心，主要存放代码扫描结果
+- **knowledge/** — 归档沉淀的可复用知识
+- **local.yaml** — 项目特有的构建/测试命令，所有阶段都会读取
+- **.runtime/** — 运行时数据，progress.json 是唯一进度数据源

package/package.json

@@ -1,13 +1,7 @@
 {
   "name": "sillyspec",
-  "version": "3.8.4",
-  "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
-  "icon": "logo.jpg",
-  "homepage": "https://sillyspec.ppdmq.top/",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/q512426816/sillyspec.git"
-  },
+  "version": "3.8.6",
+  "description": "SillySpec CLI \u2014 \u6d41\u7a0b\u72b6\u6001\u673a\uff0c\u8ba9 AI \u4e25\u683c\u6309\u6b65\u9aa4\u6765",
   "type": "module",
   "bin": {
     "sillyspec": "./bin/sillyspec.js"
@@ -30,5 +24,13 @@
     "open": "^10.1",
     "ora": "^9.3.0",
     "ws": "^8.18"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
   }
-}
+}