sillyspec 3.9.1 → 3.10.0

package/.sillyspec/changes/archive/2026-04-08-derive-state/design.md

@@ -1,97 +0,0 @@
-# deriveState 状态推导
-
-author: qinyi
-created_at: 2026-04-08 07:10:00
-
-## 背景
-
-当前 sillyspec 的状态管理依赖 `progress.json` 作为唯一数据源。如果 AI 崩溃或异常中断，progress.json 可能与实际产出不一致（如 artifacts 文件已生成但步骤未标记完成）。
-
-借鉴 GSD v2 的 deriveState 架构，从文件系统反推状态，与 progress.json 交叉校验。
-
-## 需求
-
-1. `--done` 完成步骤时轻量校验当前步骤
-2. `doctor` 自检时全量扫描所有阶段
-3. `progress validate --deep` 支持手动触发全量校验
-4. 安全修复策略：明显正确的情况自动修复，有歧义的不动
-
-## 设计
-
-### 新增文件：`src/derive.js`
-
-纯函数模块，零外部依赖（仅 fs/path）。
-
-```js
-export function deriveState(cwd, options = {}) {
-  // options.mode: 'light' | 'full'（默认 light）
-  // options.fix: boolean（默认 false，只报告不修复）
-  // 返回 { issues: [{type, severity, step, artifact, suggestion}], fixed: number }
-}
-```
-
-#### 扫描逻辑
-
-1. 读取 progress.json，获取所有阶段步骤状态
-2. 扫描 `.sillyspec/.runtime/artifacts/` 目录
-3. 文件名格式：`{stage}-step{N}-{timestamp}.txt`
-4. 解析文件名提取 stage、stepIndex 信息
-5. 对比规则：
-
-| 情况 | 严重度 | 自动修复 |
-|------|--------|----------|
-| artifacts 有文件但 progress 标记未完成 | issue | ✅ 标记为 done |
-| progress 标记已完成但 artifacts 无文件 | warning | ❌ 可能被手动清理 |
-| artifacts 有 step5 但 progress 只到 step3 | issue | ✅ 补齐中间步骤 |
-
-#### 模式
-
-- **light**：只检查 currentStage 的当前步骤和前一步
-- **full**：检查所有阶段所有步骤
-
-### 集成方式
-
-#### 1. run.js — `--done` 轻量校验
-
-在 `completeStep` 末尾：
-```js
-import { deriveState } from './derive.js';
-const result = deriveState(cwd, { mode: 'light', fix: true });
-if (result.fixed > 0) {
-  console.log(`⚠️ 状态修复：${result.fixed} 个步骤已从 artifacts 恢复`);
-}
-```
-
-#### 2. doctor.js — 全量扫描
-
-第一步（SillySpec 内部检查）调用：
-```js
-const result = deriveState(cwd, { mode: 'full', fix: false });
-// 将 issues 加入自检报告
-```
-
-#### 3. progress.js — `validate --deep`
-
-validate 方法支持 deep 参数：
-```js
-validate(cwd, deep = false) {
-  // ...现有校验逻辑...
-  if (deep) {
-    const result = deriveState(cwd, { mode: 'full', fix: true });
-    // 输出校验结果
-  }
-}
-```
-
-CLI：`sillyspec progress validate --deep`
-
-## 改动范围
-
-- 新增：`src/derive.js`（~80 行）
-- 修改：`src/run.js`（2 行）、`src/stages/doctor.js`（3 行）、`src/progress.js`（5 行）、`src/index.js`（parse --deep）
-
-## 不做的事
-
-- 不引入 SQLite 或其他新依赖
-- 不改变 progress.json 的数据结构
-- 不自动删除 progress 中有但 artifacts 无的步骤（可能被手动清理）

package/.sillyspec/changes/archive/2026-04-08-derive-state/plan.md

@@ -1,51 +0,0 @@
-# deriveState 状态推导 — 实现计划
-
-author: qinyi
-created_at: 2026-04-08 07:12:00
-
-## Wave 1（核心，无依赖）
-
-- [ ] 实现 derive.js 核心函数
-  - 新增: `src/derive.js`
-  - 步骤:
-    1. 实现 `deriveState(cwd, options)` 纯函数
-    2. 实现 artifacts 文件名解析（`{stage}-step{N}-{timestamp}.txt`）
-    3. 实现 light/full 模式扫描逻辑
-    4. 实现安全修复策略（issues 分类 + fix 逻辑）
-    5. 验证: 在 sillyspec 项目上手动创建测试 artifacts，运行 `node -e "import('./src/derive.js').then(m => console.log(m.deriveState(process.cwd(), {mode:'full'})))"` 确认输出
-
-## Wave 2（集成，依赖 Wave 1）
-
-- [ ] 集成 run.js --done 轻量校验
-  - 修改: `src/run.js`
-  - 参考: `completeStep` 函数末尾
-  - 步骤:
-    1. 在 completeStep 末尾 import 并调用 deriveState(cwd, {mode:'light', fix:true})
-    2. 有修复时输出警告信息
-    3. 验证: 运行 brainstorm 完成 --done，确认无报错
-
-- [ ] 扩展 validate 支持 --deep
-  - 修改: `src/progress.js`
-  - 参考: `validate()` 方法
-  - 步骤:
-    1. validate 方法加 deep 参数
-    2. deep=true 时调用 deriveState(cwd, {mode:'full', fix:true})
-    3. 验证: `sillyspec progress validate --deep` 确认输出校验结果
-
-- [ ] CLI parse --deep 参数
-  - 修改: `src/index.js`
-  - 参考: progress 子命令的参数解析
-  - 步骤:
-    1. 在 progress validate 命令中解析 --deep flag
-    2. 传递给 validate 方法
-    3. 验证: `sillyspec progress validate --deep` 确认 flag 生效
-
-## Wave 3（集成，依赖 Wave 1）
-
-- [ ] 集成 doctor.js 全量扫描
-  - 修改: `src/stages/doctor.js`
-  - 参考: doctor 第一步（SillySpec 内部检查）的 prompt
-  - 步骤:
-    1. 在第一步 prompt 中加入 deriveState 全量扫描指令
-    2. 将 issues 列表纳入自检报告
-    3. 验证: `sillyspec run doctor` 确认第一步输出包含状态一致性检查

package/.sillyspec/changes/archive/2026-04-08-derive-state/proposal.md

@@ -1,29 +0,0 @@
-# deriveState 状态推导 — 提案
-
-author: qinyi
-created_at: 2026-04-08 07:11:00
-
-## 动机
-
-当前 progress.json 是 sillyspec 唯一的状态数据源。AI 崩溃或异常中断时，progress.json 可能与实际产出不一致（artifacts 已生成但步骤未标记完成）。需要从文件系统反推状态，交叉校验。
-
-## 变更范围
-
-- 新增 `src/derive.js`（状态推导纯函数）
-- 修改 `src/run.js`（--done 轻量校验）
-- 修改 `src/stages/doctor.js`（全量扫描）
-- 修改 `src/progress.js`（validate --deep）
-- 修改 `src/index.js`（parse --deep 参数）
-
-## 不在范围内
-
-- 不改 progress.json 数据结构
-- 不引入新依赖
-- 不自动删除 progress 中有但 artifacts 无的步骤
-
-## 成功标准
-
-1. `--done` 完成步骤时自动校验并修复当前步骤
-2. `doctor` 输出全量状态一致性报告
-3. `sillyspec progress validate --deep` 可手动触发全量校验
-4. 所有校验通过现有测试

package/.sillyspec/changes/archive/2026-04-08-derive-state/requirements.md

@@ -1,34 +0,0 @@
-# deriveState 状态推导 — 需求
-
-author: qinyi
-created_at: 2026-04-08 07:11:00
-
-## 功能需求
-
-### FR1: deriveState 核心函数
-- 从 artifacts 目录扫描文件，解析 `{stage}-step{N}-{timestamp}.txt` 格式
-- 与 progress.json 步骤状态对比
-- 返回 issues 列表和修复计数
-
-### FR2: 轻量模式（light）
-- 只检查 currentStage 的当前步骤和前一步
-- 用于 `--done` 完成时
-
-### FR3: 全量模式（full）
-- 检查所有阶段所有步骤
-- 用于 doctor 和 validate --deep
-
-### FR4: 安全修复策略
-- artifacts 有但 progress 漏记 → 自动修复为 done
-- artifacts 有 step5 但 progress 只到 step3 → 自动补齐
-- progress 有但 artifacts 无 → 只警告，不修复
-
-### FR5: CLI 集成
-- `--done` 时静默调用轻量校验，有修复才输出
-- `doctor` 第一步输出全量报告
-- `sillyspec progress validate --deep` 手动触发
-
-## 非功能需求
-- 零外部依赖（仅 fs/path）
-- 纯函数，易于测试
-- 不改变现有 API 行为

package/.sillyspec/changes/archive/2026-04-08-derive-state/tasks.md

@@ -1,13 +0,0 @@
-# deriveState 状态推导 — 任务
-
-author: qinyi
-created_at: 2026-04-08 07:11:00
-
-## 任务列表
-
-- [x] 实现 derive.js 核心函数 — `src/derive.js`
-- [x] 集成 run.js --done 轻量校验 — `src/run.js`
-- [x] 集成 doctor.js 全量扫描 — `src/stages/doctor.js`
-- [x] 扩展 validate 支持 --deep — `src/progress.js`
-- [x] CLI parse --deep 参数 — `src/index.js`
-- [ ] 测试验证

package/.sillyspec/changes/archive/2026-04-08-derive-state/verify-result.md

@@ -1,43 +0,0 @@
-# derive-state 验证报告
-
-author: qinyi
-created_at: 2026-04-08 07:21:00
-
-## 结论：✅ PASS
-
-## 检查结果
-
-### 1. 规范文件加载
-- ✅ design.md
-- ✅ proposal.md
-- ✅ requirements.md
-- ✅ tasks.md
-- ✅ plan.md
-
-### 2. 任务完成度：5/6 (83%)
-- ✅ 实现 derive.js 核心函数
-- ✅ 集成 run.js --done 轻量校验
-- ✅ 集成 doctor.js 全量扫描
-- ✅ 扩展 validate 支持 --deep
-- ✅ CLI parse --deep 参数
-- ⬜ 测试验证（本项目无自动化测试套件，通过手动验证替代）
-
-### 3. 设计一致性
-- ✅ derive.js 纯函数模块，零外部依赖（仅 fs/path）
-- ✅ light/full 模式
-- ✅ fix 参数 + 安全修复策略
-- ✅ run.js --done 轻量校验集成
-- ✅ doctor.js 全量扫描集成
-- ✅ progress.js validate --deep 支持
-- ✅ index.js CLI --deep 参数
-- ✅ 改动文件范围与 design.md 一致
-
-### 4. 测试和质量
-- ✅ derive.js 模块导入正常
-- ✅ sillyspec progress validate --deep 通过
-- ✅ 无 TODO/FIXME/HACK/XXX 技术债务
-- ✅ sillyspec run quick --status 正常
-- ✅ sillyspec run doctor --status 正常
-
-## 下一步
-sillyspec run archive

package/.sillyspec/changes/auto-mode/design.md

@@ -1,50 +0,0 @@
-# auto mode — 设计文档
-
-author: qinyi
-created_at: 2026-04-08 07:28:00
-
-## 背景
-
-当前 sillyspec 的每个阶段（brainstorm → plan → execute → verify）需要用户手动执行 `sillyspec run <stage>` 和 `sillyspec run <stage> --done`。用户希望一个自动模式，从 brainstorm 一路推进到 verify 完成。
-
-## 需求
-
-1. 用户启动一次，AI 自动循环所有阶段和步骤
-2. 步骤内部的用户确认点保留不变
-3. 不修改 CLI 代码，纯 skill 文件实现
-
-## 设计
-
-### 新增文件：`.claude/skills/sillyspec-auto/SKILL.md`
-
-**核心逻辑：**
-
-1. 读 `$ARGUMENTS` 作为用户需求
-2. 阶段循环（brainstorm → plan → execute → verify）
-3. 每个阶段内步骤循环：
-   - `sillyspec run <stage> --input "需求"` → 读 step prompt
-   - 执行 prompt 中的操作
-   - 需要用户确认的步骤 → 暂停等回复
-   - 完成后自动 `sillyspec run <stage> --done --output "摘要"`
-   - 读下一步 prompt，继续
-4. 当前阶段全部完成 → 自动进入下一阶段
-5. verify 完成 → 输出总结，停止
-6. 命令失败 → 暂停，等用户介入
-
-**确认点保留规则：**
-- prompt 中有"请用户选择""等待用户回答""展示给用户"等字样 → 暂停
-- prompt 中有"自审""检查"等纯内部操作 → 自动完成
-
-### 同步到 npm 包
-
-init.js 已有逻辑复制 `sillyspec-*` skills 到项目 `.claude/skills/`，新 skill 自动生效。
-
-## 改动范围
-
-- 新增：`.claude/skills/sillyspec-auto/SKILL.md`（~60 行）
-
-## 不做的事
-
-- 不修改任何 JS 源码
-- 不改变现有阶段流程
-- 不自动 commit 或发布

package/.sillyspec/changes/auto-mode/proposal.md

@@ -1,19 +0,0 @@
-# auto mode — 提案
-
-author: qinyi
-created_at: 2026-04-08 07:29:00
-
-## 动机
-用户希望一次启动就自动完成 brainstorm → plan → execute → verify 全流程，不需要手动输入 `sillyspec run <stage>` 和 `--done`。
-
-## 变更范围
-新增 `.claude/skills/sillyspec-auto/SKILL.md`
-
-## 不在范围内
-- 不修改 JS 源码
-- 不改变阶段流程
-
-## 成功标准
-1. `/sillyspec:auto "需求"` 能自动推进全流程
-2. 步骤内部确认点正常暂停
-3. 异常时暂停等用户介入

package/.sillyspec/changes/auto-mode/requirements.md

@@ -1,21 +0,0 @@
-# auto mode — 需求
-
-author: qinyi
-created_at: 2026-04-08 07:29:00
-
-## 功能需求
-
-### FR1: 阶段自动推进
-- 按 brainstorm → plan → execute → verify 顺序自动执行
-- 当前阶段完成后自动进入下一阶段
-
-### FR2: 步骤自动循环
-- 每个步骤：读 prompt → 执行 → 自动 --done → 读下一步
-- 不需要用户手动触发 --done
-
-### FR3: 确认点保留
-- prompt 中有用户确认要求时暂停等回复
-- 纯内部操作步骤自动完成
-
-### FR4: 异常处理
-- 命令失败时暂停，展示错误，等用户介入

package/.sillyspec/changes/auto-mode/tasks.md

@@ -1,7 +0,0 @@
-# auto mode — 任务
-
-author: qinyi
-created_at: 2026-04-08 07:29:00
-
-- [x] 编写 sillyspec-auto SKILL.md — `.claude/skills/sillyspec-auto/SKILL.md`
-- [x] 同步到 agents skills — `~/.agents/skills/sillyspec-auto/SKILL.md`

package/.sillyspec/changes/brainstorm-archive/2026-04-05-dashboard-design.md

@@ -1,206 +0,0 @@
-# SillySpec Dashboard 设计
-
-## 概述
-
-为 SillySpec CLI 工具添加可视化仪表盘（`sillyspec dashboard`），用户通过浏览器直观查看和管理项目进度、阶段流程、任务详情和实时日志。
-
-## 目标用户
-
-SillySpec 全部用户（官方功能，随 npm 包发布）。
-
-## 分期计划
-
-### 一期（MVP）
-
-可视化仪表盘 + CLI 命令执行 + 实时日志流。
-
-### 二期（进阶）
-
-Web Terminal（xterm.js）+ 自定义命令 + AI 交互（视需求而定）。
-
-## 架构
-
-```
-sillyspec dashboard
-        │
-        ▼
-  Node.js HTTP Server (localhost:3456)
-        │
-        ├─ chokidar: watch .sillyspec/ 目录
-        ├─ WebSocket: 实时推送状态变更
-        └─ REST API: 项目列表、状态、日志、CLI 执行
-        │
-        ▼
-  Vue 3 SPA (浏览器)
-```
-
-### 文件结构
-
-```
-sillyspec/packages/dashboard/
-├── server/
-│   ├── index.js          # HTTP + WebSocket 服务启动
-│   ├── watcher.js        # chokidar 文件监听 + 增量解析
-│   └── api.js            # REST 路由
-├── src/
-│   ├── App.vue
-│   ├── components/
-│   │   ├── ProjectList.vue     # 左栏：项目列表
-│   │   ├── PipelineView.vue    # 中栏：阶段 pipeline
-│   │   ├── StepCard.vue        # 步骤卡片（可展开折叠）
-│   │   ├── DetailPanel.vue     # 右栏：详情 + 日志
-│   │   ├── LogStream.vue       # 终端风格日志流
-│   │   ├── CommandPalette.vue  # Cmd+K 命令面板
-│   │   └── StageBadge.vue      # 阶段状态标签
-│   ├── composables/
-│   │   ├── useWebSocket.js     # WebSocket 连接管理
-│   │   └── useKeyboard.js      # 键盘快捷键
-│   └── styles/
-│       └── theme.css           # 深色主题变量
-├── package.json
-└── vite.config.js
-```
-
-## 核心页面设计
-
-### 三栏布局
-
-```
-┌──────────┬─────────────────────────┬──────────────────┐
-│ 项目列表  │    Pipeline 视图（中）    │   详情+日志（右） │
-│ (200px)  │     (flex-1)            │    (320px,可收起) │
-│          │                         │                  │
-│ 📁 proj1 │  ✅ brainstorm           │  Step 3 详情     │
-│ 📁 proj2 │  ⏳ plan ← 当前          │  结论：选择React  │
-│ 📁 proj3 │  ⬜ execute              │  决策：...       │
-│          │  ⬜ verify               │  📋 实时日志     │
-└──────────┴─────────────────────────┴──────────────────┘
-```
-
-### 信息分层（三级密度）
-
-1. **低密度（默认）**：阶段名 + 状态图标
-2. **中密度（hover）**：步骤摘要（1-2 句话）
-3. **高密度（点击）**：右侧面板展开完整详情 + 日志
-
-### 异常高亮
-
-失败/阻塞/超时步骤自动标红，视觉上突出，不需用户手动查找。
-
-## 数据源与同步
-
-### 数据文件
-
-| 文件 | 用途 |
-|---|---|
-| `STATE.md` | 当前阶段、状态、下一步命令 |
-| `.runtime/progress.json` | 步骤进度、摘要、时间戳 |
-| `.runtime/user-inputs.md` | 用户输入记录 |
-| `specs/*.md` | 设计文档 |
-| `changes/*/design.md` | 技术方案 |
-
-### 同步方案
-
-- **启动时**：全量读取 `.sillyspec/` 目录，构建初始状态
-- **运行时**：chokidar watch 文件变化 → 解析 → WebSocket 增量推送
-- **不轮询，不做 diff**，文件变化直接读取推送
-
-### CLI 命令执行（一期）
-
-后端通过 `child_process.spawn` 执行 CLI 命令：
-- "下一步"按钮 → `sillyspec next`
-- 阶段切换按钮 → `sillyspec plan` / `sillyspec execute` 等
-- 执行结果通过 WebSocket 实时推送到前端日志面板
-
-## 交互设计
-
-### 键盘快捷键
-
-| 快捷键 | 功能 |
-|---|---|
-| `j/k` | 上下切换步骤 |
-| `Enter` | 展开详情 |
-| `Escape` | 收起面板 |
-| `/` | 搜索日志 |
-| `Cmd/Ctrl+K` | 命令面板 |
-
-### 命令面板功能
-
-- 搜索项目名
-- 跳转到指定阶段
-- 切换深色/浅色主题
-
-### CLI 命令
-
-```bash
-sillyspec dashboard              # 启动 + 自动开浏览器
-sillyspec dashboard --port 8080  # 自定义端口
-sillyspec dashboard --no-open    # 不自动打开浏览器
-```
-
-## 视觉设计
-
-### 配色
-
-| 用途 | 色值 |
-|---|---|
-| 背景 | `#0D1117` |
-| 主色（进行中） | `#00D4AA` |
-| 阻塞 | `#F59E0B` |
-| 失败 | `#F87171` |
-| 未开始 | `#6B7280` |
-
-### 动效
-
-- 阶段完成：脉冲光效（CSS animation，200ms）
-- 日志新行：淡入
-- hover 过渡：100ms
-- 进度条：弹性缓动
-
-## 技术选型
-
-| 层 | 技术 |
-|---|---|
-| 前端框架 | Vue 3 |
-| 构建工具 | Vite |
-| CSS | Tailwind CSS |
-| 后端 | Node.js 原生 http + ws |
-| 文件监听 | chokidar |
-| 数据库 | 无，纯文件系统 |
-
-## 约束和假设
-
-- 用户本地已有 Node.js（SillySpec 前置依赖）
-- 仪表盘为本地工具，不考虑多用户并发
-- 前端构建产物嵌入 npm 包，无需额外 build
-- 不引入 Express、数据库等重依赖
-
-## 状态历史时间线
-
-Pipeline 视图下方展示时间线，记录每个步骤的：
-- 开始时间 / 结束时间 / 耗时
-- 状态变化（进行中 → 完成/阻塞/失败）
-- 可按时间排序，快速定位耗时最长或异常步骤
-
-数据来源：`progress.json` 中的 `summaries` 和时间戳。
-
-## 不在范围内（一期）
-
-- 用户认证/权限
-- 多人协作
-- 数据持久化（纯文件系统）
-- AI 对话交互（二期）
-- Web Terminal（二期）
-
-## 验收标准
-
-- [ ] `sillyspec dashboard` 一键启动，自动打开浏览器
-- [ ] 三栏布局正确渲染，响应式适配
-- [ ] 文件变化后前端实时更新（<1s 延迟）
-- [ ] 步骤卡片三级信息分层（默认/hover/点击）
-- [ ] 实时日志流正常显示，可搜索可过滤
-- [ ] 键盘快捷键可用（j/k/Enter/Escape/Cmd+K）
-- [ ] 命令面板可搜索项目名和阶段
-- [ ] CLI 命令执行按钮可用，结果实时显示
-- [ ] 异常步骤自动高亮
-- [ ] 深色/浅色主题切换