sandtable 0.3.0

package/skills/build-json.md

@@ -0,0 +1,36 @@
+# build-json — 生成 data/*.json (v2)
+
+## 用途
+读取扫描结果，生成 dashboard 所需的 JSON 数据文件。
+
+## v2 数据文件
+
+### 主输出
+| 文件 | 说明 |
+|------|------|
+| `data/timeline.json` | 统一时间线（主线 + 次要元素 + 过滤类型清单） |
+| `data/conventions.json` | 约定简称（默认 `configured: false`，手动配置） |
+| `data/agents.json` | 角色分工（保留，暂不渲染） |
+| `data/brief.json` | 200 字简报 |
+
+### 兼容输出 (v1 格式)
+| 文件 | 说明 |
+|------|------|
+| `data/roadmap.json` | v1 Roadmap 格式（由 timeline 转换） |
+| `data/journal-index.json` | v1 瀑布流格式（由 timeline 转换） |
+
+## 时间分群
+元素按 `timeGroup` 分三类：
+- **past**（过去历史）：completed / cancelled 状态
+- **current**（现阶段）：in_progress / pending 状态（默认 tab）
+- **future**（未来计划）：规则由 `.sandtable.json` timeRules 控制
+
+## 调用方式
+```bash
+node src/cli/sandtable.js build [projectRoot]
+```
+
+## 渲染约定
+- primary 元素始终展示，secondary 元素经 checkbox 勾选后展示
+- conventions 默认显示"待配置"占位，用户手动编辑 data/conventions.json 后，设 `configured: true` 即正常渲染
+- dashboard 优先加载 timeline.json，若不存在则用 roadmap.json + journal-index.json 回退合并

package/skills/scan-docs.md

@@ -0,0 +1,38 @@
+# scan-docs — 扫描项目文档目录 (v2)
+
+## 用途
+遍历项目的 `docs/` 目录，识别所有 .md 文件，按 **主线/次要** 归类，提取摘要块和时间信息。
+
+## v2 核心概念
+
+### 主线元素 (primary)
+所有项目通用的结构元素，默认展示：
+- phase（阶段）、milestone（里程碑）、task（任务）、subtask（子任务）
+- conclusion（结论/复盘）、decision（设计决策）、agent（角色定义）
+
+### 次要元素 (secondary)
+项目特有的内容元素，默认隐藏可勾选：
+- journal（日志）、convention（约定）、prompt（提示词）、template（模板）、intent（意图）
+
+### 时间信息提取
+- 优先级：文件名日期 > 内容首个日期 > 文件修改时间
+
+### 配置文件
+可选 `.sandtable.json`：
+- `paths`：覆盖目录到类别的映射
+- `timeRules`：时间分群规则（按状态/按日期）
+- `display`：显示偏好
+
+## 调用方式
+```bash
+node src/cli/sandtable.js scan [projectRoot]
+```
+
+## 输出
+JSON 格式的扫描结果，v2 新增字段：
+- `primaryCount` / `secondaryCount`：主线/次要文件数量
+- `elementTypes`：所有发现的元素类型
+- 每个文件新增：`kind`（primary/secondary）、`elementType`、`date`、`dateSource`
+
+## 下一步
+运行 `build-json` skill 将扫描结果转为 data/*.json

package/skills/summarize.md

@@ -0,0 +1,66 @@
+<!-- SUMMARY
+{
+  "type": "convention",
+  "status": "completed",
+  "tags": ["skill", "summarize", "v0.2"],
+  "summary": "AI skill：读取 scan.json 找出无摘要块文件，阅读内容后生成 SUMMARY 块并插入文件头部"
+}
+-->
+# summarize — AI 总结无摘要块文件 (v2)
+
+## 用途
+读取 `data/scan.json`，找出所有 `hasSummary: false` 的文件，逐个阅读内容后生成符合模板规范的 `<!-- SUMMARY {...} -->` 块，插入文件头部。
+
+## 前置条件
+- `data/scan.json` 已存在（需先运行 `node src/cli/sandtable.js scan`）
+- 摘要块模板参考：`templates/summary-block.md`
+
+## 执行步骤
+
+### 第 1 步：列出待总结文件
+```bash
+node src/cli/sandtable.js summarize [projectRoot]
+```
+或直接读取 `data/scan.json`，过滤 `files` 数组中 `hasSummary: false` 的条目。
+
+### 第 2 步：逐个阅读并分析
+对每个无摘要块的文件：
+1. 用 Read 工具读取文件内容
+2. 根据内容判断：
+   - **type**：`decision | journal | milestone | spec | convention | phase | conclusion`
+   - **status**：`completed | in_progress | pending | blocked | cancelled`
+   - **tags**：1-3 个关键词标签
+   - **summary**：一句话中文摘要（≤50 字）
+   - **kind**：`primary`（主线）或 `secondary`（次要）
+3. 参考自动分类规则：
+   - type 为 milestone / roadmap / phase / task / decision / agent → `kind: "primary"`
+   - type 为 journal / convention / spec / template / intent → `kind: "secondary"`
+
+### 第 3 步：生成并插入 SUMMARY 块
+用 Edit 工具在文件开头（`#` 标题之前）插入：
+```html
+<!-- SUMMARY
+{
+  "type": "实际类型",
+  "status": "实际状态",
+  "tags": ["tag1", "tag2"],
+  "summary": "一句话中文摘要"
+}
+-->
+```
+
+### 第 4 步：验证
+重新运行 `node src/cli/sandtable.js build`，确认 `data/scan.json` 中该文件 `hasSummary` 变为 `true`。
+
+## 摘要块格式要求
+
+- 必须是合法的 JSON，放在 `<!-- SUMMARY` 和 `-->` 之间
+- `type`、`status`、`tags`、`summary` 为必填字段
+- `kind` 为可选字段，仅在需要覆盖自动分类时使用
+- summary 使用中文，简洁准确，≤50 字
+
+## 批量处理建议
+
+- 每次处理 3-5 个文件，处理完一批后 build 验证
+- 优先处理 `docs/plan/` 和 `docs/agents/` 下的文件（主线元素）
+- 模板文件（templates/）和 harness 可跳过或标记为 `type: "template"`