sandtable 0.3.1 → 1.0.1

package/README.md

@@ -1,40 +1,175 @@
-# 沙盘 Sandtable
+# Sandtable 沙盘 v0.4.0
 
-AI 编程项目的可视化指挥面板工具包。
+> AI 编程可视化指挥面板 — 让你在 AI coding 中看清项目全貌，不再盲飞
+
+[![npm version](https://img.shields.io/npm/v/sandtable)](https://www.npmjs.com/package/sandtable)
+[![node](https://img.shields.io/node/v/sandtable)](https://nodejs.org/)
+
+---
+
+## 痛点
+
+用 AI 写代码超过一周，你会发现：
+
+- **"现在做到哪了？"** — roadmap 在脑里、进度在对话里、决策散落在 20 个 .md 里
+- **"已经改了什么？"** — git log 太细碎，看不出业务层面的变更脉络
+- **"约定是什么？"** — 缩写、术语、编码规范，AI 忘了你也要翻半天
+- **"AI 花了多少？"** — token 消耗不可见，月底账单吓一跳
+
+Sandtable 把这些信息**自动聚合、可视化**，一个命令就能在浏览器里看到。
 
 ## 一句话
 
-帮你在 AI coding 时，实时看到项目 roadmap、进度、日志、约定简称对照——
-打开 `dashboard/dashboard.html`，刷新即看。
+```bash
+npm install -g sandtable
+cd your-project/
+sandtable init --apply    # 一行初始化
+sandtable build           # 一行生成数据
+sandtable serve            # 一行启动仪表盘 → http://localhost:5199
+```
 
-## 安装
+左看结构（doc 树），右看动态（事件流），项目全貌一目了然。
 
-1. 将 `sandtable/` 目录放入项目根目录
-2. （可选）将 `harness/summary-hook.md` 中的 hook 配置加入 `.claude/settings.local.json`
+## 快速开始
 
-## 使用
+**前置条件**：Node.js >= 18.0.0
 
 ```bash
-# 扫描文档目录
-node src/cli/sandtable.js scan
+# 1. 全局安装
+npm install -g sandtable
+
+# 2. 进入项目根目录
+cd your-project/
+
+# 3. 初始化（先 dry-run 预览）
+sandtable init
 
-# 生成 data/*.json
-node src/cli/sandtable.js build
+# 4. 确认后写入
+sandtable init --apply
 
-# 打开指挥面板
-# 浏览器打开 dashboard/dashboard.html
+# 5. 构建数据
+sandtable build
+
+# 6. 启动仪表盘
+sandtable serve
+# 浏览器自动打开 → http://localhost:5199
 ```
 
-## 让 AI 帮你
+## 命令速览
+
+| 命令 | 功能 |
+|------|------|
+| `sandtable init [--apply]` | 扫描 IDE 环境 + 生成规则文件 |
+| `sandtable build` | 扫描 docs + git log → 生成 data/*.json |
+| `sandtable serve [port] [--watch]` | 启动仪表盘 HTTP 服务（默认 127.0.0.1:5199） |
+| `sandtable event-log --type <slug> --title "..."` | 手动记录事件 |
+| `sandtable token-log <skill> <in> <out>` | 记录 token 消耗 |
+| `sandtable scan` | 扫描文档目录（JSON 输出） |
+| `sandtable summarize` | 列出缺 SUMMARY 块的文件 |
+| `sandtable uninstall [--apply]` | 清理 sandtable 创建的文件 |
+| `sandtable version` | 查看版本 |
+
+## 仪表盘双视图
+
+```
+┌──────────────────────────────────────────┐
+│           sandtable dashboard             │
+│                                            │
+│       静态 doc 树            动态事件流      │
+│      （8 大分类）           （7 大类型）      │
+│    ┌──────────────┐     ┌──────────────┐   │
+│    │ 1.路线图/进度│     │ 1.对齐与拍板 │   │
+│    │ 2.待办清单  │     │ 2.规格演进   │   │
+│    │ 3.决策记录  │     │ 3.代码变更   │   │
+│    │ 4.业务规格  │     │ 4.测试与质量 │   │
+│    │ 5.协作纪律  │     │ 5.审批与交接 │   │
+│    │ 6.运维与基建│     │ 6.运维与基建 │   │
+│    │ 7.历史档案  │     │ 7.教训沉淀   │   │
+│    │ 8.工具模板  │     │              │   │
+│    └──────────────┘     └──────────────┘   │
+│                                            │
+│      数据源: git log + docs/*.md + JSONL    │
+└──────────────────────────────────────────┘
+```
+
+**左面板** — 静态 doc 树：自动分类展示你的项目文档结构，每个节点带状态徽标。点击联动右侧事件流。
+
+**右面板** — 动态事件流：按时间轴展示项目关键事件（决策/编码/测试/审批/教训），线程分组，标签筛选。
+
+## 安全边界
+
+- **只读** `docs/`、`.git/`、`.sandtable/`，不修改你的项目文件
+- **不联网**：无遥测、无分析追踪，所有数据都在本地
+- **默认 127.0.0.1**：serve 仅本机可访问，暴露公网需 token 认证
+- `.gitignore` 自动追加：`init --apply` 自动标记不提交的生成文件
+
+## 兼容环境
+
+| IDE | 规则位置 |
+|-----|---------|
+| Cursor | `.cursor/rules/sandtable-event-log.mdc` |
+| Claude Code | `.claude/skills/sandtable-event-log/SKILL.md` |
+| Trae | `.trae/rules/sandtable-event-log.md` |
+| Cline | `.clinerules/sandtable-event-log.md` |
+| GitHub Copilot | `.github/instructions/sandtable-event-log.instructions.md` |
+| 通用 | `.sandtable/rules.md` |
+
+详细文档见 [INSTALL.md](./INSTALL.md)。
+
+---
+
+## English
+
+### What is Sandtable?
+
+A visual command-center toolkit for AI-assisted software projects. It scans your project docs and git history to generate a dual-view dashboard — doc tree on the left, event timeline on the right.
+
+### Pain Points It Solves
+
+- **"Where are we now?"** — roadmap in your head, progress in chat history, decisions scattered across 20 .md files
+- **"What changed?"** — git log is too granular, you need business-level event tracing
+- **"What's the convention?"** — abbreviations, naming rules, coding standards — the AI forgets, you re-explain
+- **"How much did AI cost?"** — token consumption invisible until the monthly bill arrives
+
+### Quick Start
+
+```bash
+npm install -g sandtable
+cd your-project/
+sandtable init --apply
+sandtable build
+sandtable serve        # → http://localhost:5199
+```
+
+### Key Features
+
+- **Dual-view dashboard**: Static doc tree (8 categories) + Dynamic event stream (7 event types)
+- **Multi-source fusion**: git log + docs/*.md SUMMARY blocks + manual events via CLI
+- **Event logging**: Record decisions, code changes, tests, approvals, lessons — with threads and tags
+- **Token tracking**: Per-skill, per-date token consumption summary
+- **Safe by default**: Serves on 127.0.0.1, requires token for public exposure, zero telemetry
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `sandtable init [--apply]` | Detect IDE environment, create rule files |
+| `sandtable build` | Generate `data/*.json` from docs + git log |
+| `sandtable serve [port] [--watch]` | Start dashboard HTTP server |
+| `sandtable event-log --type <slug> --title "..."` | Record a development event |
+| `sandtable token-log <skill> <in> <out>` | Log token consumption |
+| `sandtable uninstall [--apply]` | Clean up sandtable files |
 
-在 Claude Code 对话中：
-- `/sandtable scan` — AI 扫描项目文档
-- `/sandtable build` — AI 生成 JSON 数据
+### Security
 
-## 项目结构
+- **Read-only**: Only reads `docs/`, `.git/`, `.sandtable/` — never modifies your source
+- **No telemetry**: Zero external network calls, all data stays local
+- **127.0.0.1 by default**: Dashboard only accessible from localhost; `--host 0.0.0.0` requires token auth
+- **Gitignore aware**: `init --apply` auto-appends generated files to `.gitignore`
 
-见 `docs/scaffold.md`。
+See [INSTALL.md](./INSTALL.md) for full documentation.
 
-## 版本
+---
 
-v0.1 MVP — 脚手架 + scanner/builder + dashboard 渲染
+**npm**: [https://www.npmjs.com/package/sandtable](https://www.npmjs.com/package/sandtable)
+**GitHub**: [https://github.com/beimingju-dafu/Sandtable](https://github.com/beimingju-dafu/Sandtable)