sillyspec 3.9.1 → 3.10.0

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

@@ -1,199 +0,0 @@
-# 统一文档管理 + Dashboard 文档浏览
-
-## 动机
-
-### 现状问题
-1. 文档散落在各子项目的 `.sillyspec/` 里，没有统一视角
-2. Dashboard 只能发现项目，看不到文档内容
-3. 扫描的 `codebase/` 文档只在子项目里，主项目看不到
-4. 归档后文档沉入 `knowledge/`，跨项目复用不方便
-5. 单项目模式和工作区模式两套逻辑，维护成本高
-
-### 目标
-- 文档只写一份，集中管理
-- 默认工作区模式，去掉模式切换
-- Dashboard 支持文档浏览
-- 子项目保持干净（只有源代码）
-
-## 方案
-
-### 核心原则
-- **文档只写一份**，在哪执行就写在哪
-- **默认工作区模式**，每个项目天生就是"主项目"
-- **子项目不生成文档**，文档全部在主项目的 `.sillyspec/docs/<project>/` 下
-
-### 目录结构
-
-```
-my-project/.sillyspec/
-├── STATE.md                        # 主项目状态（含当前操作的项目）
-├── projects/                       # 子项目注册表
-│   ├── my-project.yaml             # 默认注册自己
-│   ├── frontend.yaml               # { name, path, status }
-│   └── backend.yaml
-│
-├── docs/                           # 统一文档中心
-│   └── my-project/                 # 按子项目分目录
-│       ├── scan/                   # scan 产出
-│       │   ├── ARCHITECTURE.md
-│       │   └── CONVENTIONS.md
-│       ├── brainstorm/             # brainstorm 设计文档
-│       │   └── 2026-04-05-user-auth.md
-│       ├── plan/                   # plan 产出
-│       │   └── 2026-04-05-user-auth.md
-│       ├── changes/                # 当前变更（WIP）
-│       │   └── user-auth/
-│       │       ├── design.md
-│       │       └── tasks.md
-│       ├── archive/                # 归档
-│       │   └── 2026-03-20-db-redesign.md
-│       └── quicklog/               # quick 操作记录
-│           └── 2026-04-05-fix-login.md
-│
-├── knowledge/                      # 跨项目共享知识库（不变）
-└── .runtime/
-    └── progress.json               # 运行时数据（含子项目维度）
-```
-
-### 子项目保持干净
-
-```
-frontend/                          # 只有源代码
-├── src/
-├── package.json
-└── .gitignore
-```
-
-子项目不再有 `.sillyspec/` 目录。
-
-## 命令变更
-
-### --project 参数
-
-所有产生文档的命令支持 `--project <name>` 参数：
-
-```bash
-/sillyspec:scan --project frontend
-/sillyspec:brainstorm "用户认证" --project frontend
-/sillyspec:plan --project frontend
-/sillyspec:execute --project frontend
-/sillyspec:archive --project frontend
-/sillyspec:quick --project frontend --change "修复登录bug"
-```
-
-不指定 `--project` 时，默认使用 `STATE.md` 中记录的当前项目。
-
-### 文档输出路径映射
-
-| 命令 | 输出路径 |
-|------|---------|
-| scan | `.sillyspec/docs/<project>/scan/` |
-| brainstorm | `.sillyspec/docs/<project>/brainstorm/<name>.md` |
-| propose | `.sillyspec/docs/<project>/brainstorm/<name>.md` |
-| plan | `.sillyspec/docs/<project>/plan/<name>.md` |
-| execute | `.sillyspec/docs/<project>/changes/<name>/` (WIP) |
-| archive | `.sillyspec/docs/<project>/archive/<name>.md` |
-| quick | `.sillyspec/docs/<project>/quicklog/<name>.md` |
-
-### init 变更
-
-- `sillyspec init` 初始化时，`projects/` 默认注册当前目录自己
-- 去掉 `--workspace` 参数（默认就是工作区模式）
-- 去掉 `--interactive` 参数（默认零交互）
-
-### STATE.md 变更
-
-```markdown
-# 项目状态
-
-## 当前项目
-- 名称：frontend
-- 路径：./frontend
-
-## 当前变更
-- 名称：user-auth
-- 当前阶段：execute ⏳
-- 下一步：执行任务 3/8
-```
-
-### progress.json 变更
-
-增加子项目维度：
-
-```json
-{
-  "_version": 1,
-  "schemaVersion": "1.0",
-  "currentProject": "frontend",
-  "currentStage": "execute",
-  "stages": {
-    "brainstorm": { "status": "completed", "steps": [...] },
-    "plan": { "status": "completed", "steps": [...] },
-    "execute": { "status": "in-progress", "steps": [...] },
-    "verify": { "status": "pending", "steps": [] }
-  }
-}
-```
-
-## Dashboard 文档浏览
-
-### 新增文档 Tab
-
-选中项目后，中间区域顶部增加 Tab 切换：
-
-```
-[ 流水线 ] [ 文档 ]
-```
-
-### 文档 Tab 内容
-
-左侧：文档树（按类型分组）
-
-```
-📋 设计文档
-  📄 用户认证功能设计
-
-📐 实现计划
-  📄 用户认证功能计划
-
-⚙️ 当前变更
-  📄 design.md
-  📄 tasks.md
-
-📦 已归档
-  📄 数据库重设计
-
-🔍 架构文档
-  📄 ARCHITECTURE.md
-  📄 CONVENTIONS.md
-
-⚡ 快速修复
-  📄 修复登录bug
-```
-
-右侧：文档预览（Markdown 渲染）
-
-点击左侧文档，右侧显示内容。
-
-### 后端新增 API
-
-```
-GET /api/projects/:path/docs          # 获取项目文档树
-GET /api/projects/:path/docs/:filePath # 获取文档内容
-```
-
-## 兼容性
-
-- 旧项目 `.sillyspec/codebase/`、`.sillyspec/specs/` 不受影响，只是新文档不再往那写
-- 可加 `sillyspec docs migrate` 命令把旧文档迁移到新结构
-- Dashboard 的项目发现逻辑不变（扫描 `.sillyspec` 目录）
-
-## 验收标准
-
-1. `sillyspec init` 生成 `projects/` 和 `docs/` 结构
-2. `--project` 参数在所有命令中生效
-3. 文档输出到 `.sillyspec/docs/<project>/` 对应子目录
-4. 子项目目录不生成任何 `.sillyspec` 文件
-5. Dashboard 文档 Tab 能展示文档树和预览内容
-6. 旧项目不受影响
-7. `sillyspec docs migrate` 能迁移旧文档

package/.sillyspec/changes/dashboard/design.md

@@ -1,219 +0,0 @@
-# SillySpec Dashboard — 技术方案
-
-## 架构决策
-
-| 决策 | 选择 | 理由 |
-|---|---|---|
-| 前端框架 | Vue 3 + Vite | 轻量、打包快、SillySpec 用户已有 Node.js |
-| CSS | Tailwind CSS | 原子化、深色主题变量管理方便 |
-| 后端 | Node.js 原生 http + ws | 不引入 Express，零重依赖 |
-| 文件监听 | chokidar | 跨平台、成熟稳定 |
-| 数据库 | 无 | 纯文件系统，与 SillySpec 哲学一致 |
-| 包结构 | SillySpec 子包 packages/dashboard | 独立 package.json，可单独开发 |
-
-## 文件变更清单
-
-### 新增文件
-
-| 文件 | 说明 |
-|---|---|
-| `packages/dashboard/package.json` | 子包配置，依赖 vue/vite/tailwind/chokidar/ws |
-| `packages/dashboard/vite.config.js` | Vite 构建配置，构建产物输出到 dist/ |
-| `packages/dashboard/server/index.js` | HTTP + WebSocket 服务启动入口 |
-| `packages/dashboard/server/watcher.js` | chokidar 监听 .sillyspec/，解析文件变化，emit 事件 |
-| `packages/dashboard/server/api.js` | REST 路由：GET /api/projects, GET /api/project/:name/status |
-| `packages/dashboard/server/executor.js` | CLI 命令执行器（child_process.spawn + stdout 流式推送） |
-| `packages/dashboard/src/main.js` | Vue 应用入口 |
-| `packages/dashboard/src/App.vue` | 根组件，三栏布局 |
-| `packages/dashboard/src/components/ProjectList.vue` | 左栏项目列表 |
-| `packages/dashboard/src/components/PipelineView.vue` | 中栏阶段 pipeline + 时间线 |
-| `packages/dashboard/src/components/StepCard.vue` | 步骤卡片（三级信息密度） |
-| `packages/dashboard/src/components/DetailPanel.vue` | 右栏详情 + 日志 |
-| `packages/dashboard/src/components/LogStream.vue` | 终端风格日志流（等宽字体、语法高亮、搜索过滤） |
-| `packages/dashboard/src/components/CommandPalette.vue` | Cmd+K 命令面板 |
-| `packages/dashboard/src/components/StageBadge.vue` | 阶段状态标签组件 |
-| `packages/dashboard/src/components/ActionBar.vue` | CLI 操作按钮（下一步、阶段切换） |
-| `packages/dashboard/src/composables/useWebSocket.js` | WebSocket 连接管理（自动重连、心跳） |
-| `packages/dashboard/src/composables/useKeyboard.js` | 全局键盘快捷键 |
-| `packages/dashboard/src/styles/theme.css` | CSS 变量（配色、间距、动效） |
-| `packages/dashboard/index.html` | Vite HTML 入口 |
-| `packages/dashboard/tailwind.config.js` | Tailwind 配置（自定义颜色） |
-
-### 修改文件
-
-| 文件 | 变更 |
-|---|---|
-| `src/index.js` | 新增 `dashboard` 命令分支 |
-| `package.json` | workspace 引用 packages/dashboard |
-
-## 数据模型
-
-### 前端状态（composable/store）
-
-```javascript
-{
-  projects: [
-    {
-      name: 'my-project',
-      path: '/Users/x/my-project',
-      currentStage: 'plan',
-      stages: {
-        brainstorm: { status: 'completed', steps: 10, completedSteps: 10, duration: '25min' },
-        plan: { status: 'in-progress', steps: 5, completedSteps: 2, duration: '8min' },
-        execute: { status: 'pending', steps: 0, completedSteps: 0 },
-        verify: { status: 'pending', steps: 0, completedSteps: 0 }
-      },
-      lastActive: '2026-04-05T14:30:00Z'
-    }
-  ],
-  activeProject: 'my-project',  // 当前选中
-  activeStep: 3,                // 当前选中步骤
-  logs: [],                     // 实时日志行
-  isPanelOpen: true             // 右侧面板是否展开
-}
-```
-
-### WebSocket 消息协议
-
-```javascript
-// 服务端 → 客户端
-{ type: 'project:updated', project: { name, stages, currentStage } }
-{ type: 'step:updated', project: 'name', step: { id, status, summary } }
-{ type: 'log:append', project: 'name', lines: ['> analyzing...', '> done ✅'] }
-{ type: 'cli:output', project: 'name', data: 'stdout/stderr 流' }
-{ type: 'cli:complete', project: 'name', exitCode: 0 }
-
-// 客户端 → 服务端
-{ type: 'cli:execute', project: 'name', command: 'sillyspec next' }
-{ type: 'project:select', name: 'my-project' }
-```
-
-### REST API
-
-```
-GET /api/projects           → 项目列表（扫描用户目录下的 .sillyspec/）
-GET /api/project/:name      → 项目完整状态（STATE.md + progress.json 合并）
-GET /api/project/:name/logs → 最近日志（user-inputs.md）
-```
-
-## 关键组件实现
-
-### StepCard.vue — 三级信息密度
-
-```vue
-<template>
-  <div class="step-card" :class="[statusClass]" 
-       @mouseenter="hovered = true" @mouseleave="hovered = false"
-       @click="select">
-    <!-- 低密度：始终显示 -->
-    <div class="step-header">
-      <span class="step-icon">{{ icon }}</span>
-      <span class="step-title">{{ step.title }}</span>
-    </div>
-    
-    <!-- 中密度：hover 显示 -->
-    <transition name="fade">
-      <div v-if="hovered && step.summary?.conclusion" class="step-summary">
-        {{ step.summary.conclusion }}
-      </div>
-    </transition>
-    
-    <!-- 高密度：点击后在右侧 DetailPanel 展示 -->
-  </div>
-</template>
-```
-
-### LogStream.vue — 终端风格日志
-
-- 等宽字体（JetBrains Mono / monospace）
-- 新行淡入动画（CSS transition opacity）
-- 搜索过滤：顶部搜索框，实时过滤匹配行
-- 自动滚动到底部，用户上翻时暂停自动滚动
-- ANSI 颜色码支持（使用 ansi-to-html）
-
-### CommandPalette.vue
-
-- `Cmd/Ctrl+K` 打开，`Escape` 关闭
-- 模糊搜索项目名、阶段名
-- 选中后跳转视图
-- 参考 shadcn/ui 的 Command 组件风格
-
-## CLI 集成
-
-### src/index.js 新增命令
-
-```javascript
-// 在现有 commander 配置中新增
-program
-  .command('dashboard')
-  .description('启动可视化仪表盘')
-  .option('--port <number>', '端口号', 3456)
-  .option('--no-open', '不自动打开浏览器')
-  .action(async (options) => {
-    const { startServer } = await import('../packages/dashboard/server/index.js');
-    await startServer(options);
-  });
-```
-
-### server/index.js 启动流程
-
-```javascript
-async function startServer({ port = 3456, open = true }) {
-  // 1. 启动 HTTP 服务，serve 前端静态文件
-  const server = http.createServer(handler);
-  
-  // 2. 挂载 WebSocket
-  const wss = new WebSocketServer({ server });
-  
-  // 3. 启动文件监听
-  const watcher = new ProjectWatcher();
-  watcher.on('change', (event) => wss.broadcast(event));
-  
-  // 4. 启动服务
-  server.listen(port, () => {
-    console.log(`🚀 SillySpec Dashboard: http://localhost:${port}`);
-    if (open) openBrowser(`http://localhost:${port}`);
-  });
-}
-```
-
-## 项目发现机制
-
-扫描用户常用项目目录，查找包含 `.sillyspec/` 的目录：
-
-```javascript
-// 优先级：
-// 1. 当前工作目录
-// 2. HOME 目录下第一层子目录
-// 3. 用户可通过设置文件配置额外路径 ~/.sillyspec/dashboard.json
-```
-
-## 构建与发布
-
-### 开发模式
-
-```bash
-cd packages/dashboard
-npm run dev  # Vite dev server + 后端热重载
-```
-
-### 生产构建
-
-```bash
-cd packages/dashboard
-npm run build  # Vite 构建 → dist/
-```
-
-前端构建产物（dist/）嵌入 npm 包，`sillyspec dashboard` 启动时 serve 静态文件。
-
-### 发布
-
-作为 SillySpec 的子包，跟随主包版本一起发布。不需要独立版本号。
-
-## 代码风格参照
-
-- Vue 3 Composition API（`<script setup>`）
-- Tailwind CSS utility-first
-- 组件命名：PascalCase
-- composable 命名：use 前缀
-- 不使用 Vuex/Pinia，composable 管理状态即可（项目规模不需要）

package/.sillyspec/changes/dashboard/design.md.braindraft

@@ -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 命令执行按钮可用，结果实时显示
-- [ ] 异常步骤自动高亮
-- [ ] 深色/浅色主题切换