Sandtable 沙盘 v0.4.0

AI 编程可视化指挥面板 — 让你在 AI coding 中看清项目全貌，不再盲飞

痛点

用 AI 写代码超过一周，你会发现：

• "现在做到哪了？" — roadmap 在脑里、进度在对话里、决策散落在 20 个 .md 里
• "已经改了什么？" — git log 太细碎，看不出业务层面的变更脉络
• "约定是什么？" — 缩写、术语、编码规范，AI 忘了你也要翻半天
• "AI 花了多少？" — token 消耗不可见，月底账单吓一跳

Sandtable 把这些信息自动聚合、可视化，一个命令就能在浏览器里看到。

一句话

npm install -g sandtable
cd your-project/
sandtable init --apply    # 一行初始化
sandtable build           # 一行生成数据
sandtable serve            # 一行启动仪表盘 → http://localhost:5199

左看结构（doc 树），右看动态（事件流），项目全貌一目了然。

快速开始

前置条件：Node.js >= 18.0.0

# 1. 全局安装
npm install -g sandtable

# 2. 进入项目根目录
cd your-project/

# 3. 初始化（先 dry-run 预览）
sandtable init

# 4. 确认后写入
sandtable init --apply

# 5. 构建数据
sandtable build

# 6. 启动仪表盘
sandtable serve
# 浏览器自动打开 → http://localhost:5199

命令速览

| 命令 | 功能 | |------|------| | 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。

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

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 |

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

See INSTALL.md for full documentation.

npm: https://www.npmjs.com/package/sandtable GitHub: https://github.com/beimingju-dafu/Sandtable