sandtable 0.4.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +157 -22
- package/dashboard/dashboard.html +1318 -834
- package/package.json +1 -1
- package/server.js +10 -1
- package/src/builder/build.js +121 -230
- package/src/check/check.js +137 -0
- package/src/cli/sandtable.js +36 -0
- package/src/contract/default-contract.json +21 -0
- package/src/contract/loader.js +203 -0
- package/src/progress/parser.js +302 -0
- package/src/scanner/scan.js +47 -251
- package/src/scanner/scan.js.v0.4.bak +415 -0
- package/templates/.sandtable.template.json +24 -26
package/README.md
CHANGED
|
@@ -1,40 +1,175 @@
|
|
|
1
|
-
# 沙盘
|
|
1
|
+
# Sandtable 沙盘 v0.4.0
|
|
2
2
|
|
|
3
|
-
AI
|
|
3
|
+
> AI 编程可视化指挥面板 — 让你在 AI coding 中看清项目全貌，不再盲飞
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/sandtable)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 痛点
|
|
11
|
+
|
|
12
|
+
用 AI 写代码超过一周，你会发现：
|
|
13
|
+
|
|
14
|
+
- **"现在做到哪了？"** — roadmap 在脑里、进度在对话里、决策散落在 20 个 .md 里
|
|
15
|
+
- **"已经改了什么？"** — git log 太细碎，看不出业务层面的变更脉络
|
|
16
|
+
- **"约定是什么？"** — 缩写、术语、编码规范，AI 忘了你也要翻半天
|
|
17
|
+
- **"AI 花了多少？"** — token 消耗不可见，月底账单吓一跳
|
|
18
|
+
|
|
19
|
+
Sandtable 把这些信息**自动聚合、可视化**，一个命令就能在浏览器里看到。
|
|
4
20
|
|
|
5
21
|
## 一句话
|
|
6
22
|
|
|
7
|
-
|
|
8
|
-
|
|
23
|
+
```bash
|
|
24
|
+
npm install -g sandtable
|
|
25
|
+
cd your-project/
|
|
26
|
+
sandtable init --apply # 一行初始化
|
|
27
|
+
sandtable build # 一行生成数据
|
|
28
|
+
sandtable serve # 一行启动仪表盘 → http://localhost:5199
|
|
29
|
+
```
|
|
9
30
|
|
|
10
|
-
|
|
31
|
+
左看结构（doc 树），右看动态（事件流），项目全貌一目了然。
|
|
11
32
|
|
|
12
|
-
|
|
13
|
-
2. （可选）将 `harness/summary-hook.md` 中的 hook 配置加入 `.claude/settings.local.json`
|
|
33
|
+
## 快速开始
|
|
14
34
|
|
|
15
|
-
|
|
35
|
+
**前置条件**：Node.js >= 18.0.0
|
|
16
36
|
|
|
17
37
|
```bash
|
|
18
|
-
#
|
|
19
|
-
|
|
38
|
+
# 1. 全局安装
|
|
39
|
+
npm install -g sandtable
|
|
40
|
+
|
|
41
|
+
# 2. 进入项目根目录
|
|
42
|
+
cd your-project/
|
|
43
|
+
|
|
44
|
+
# 3. 初始化（先 dry-run 预览）
|
|
45
|
+
sandtable init
|
|
20
46
|
|
|
21
|
-
#
|
|
22
|
-
|
|
47
|
+
# 4. 确认后写入
|
|
48
|
+
sandtable init --apply
|
|
23
49
|
|
|
24
|
-
#
|
|
25
|
-
|
|
50
|
+
# 5. 构建数据
|
|
51
|
+
sandtable build
|
|
52
|
+
|
|
53
|
+
# 6. 启动仪表盘
|
|
54
|
+
sandtable serve
|
|
55
|
+
# 浏览器自动打开 → http://localhost:5199
|
|
26
56
|
```
|
|
27
57
|
|
|
28
|
-
##
|
|
58
|
+
## 命令速览
|
|
59
|
+
|
|
60
|
+
| 命令 | 功能 |
|
|
61
|
+
|------|------|
|
|
62
|
+
| `sandtable init [--apply]` | 扫描 IDE 环境 + 生成规则文件 |
|
|
63
|
+
| `sandtable build` | 扫描 docs + git log → 生成 data/*.json |
|
|
64
|
+
| `sandtable serve [port] [--watch]` | 启动仪表盘 HTTP 服务（默认 127.0.0.1:5199） |
|
|
65
|
+
| `sandtable event-log --type <slug> --title "..."` | 手动记录事件 |
|
|
66
|
+
| `sandtable token-log <skill> <in> <out>` | 记录 token 消耗 |
|
|
67
|
+
| `sandtable scan` | 扫描文档目录（JSON 输出） |
|
|
68
|
+
| `sandtable summarize` | 列出缺 SUMMARY 块的文件 |
|
|
69
|
+
| `sandtable uninstall [--apply]` | 清理 sandtable 创建的文件 |
|
|
70
|
+
| `sandtable version` | 查看版本 |
|
|
71
|
+
|
|
72
|
+
## 仪表盘双视图
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
┌──────────────────────────────────────────┐
|
|
76
|
+
│ sandtable dashboard │
|
|
77
|
+
│ │
|
|
78
|
+
│ 静态 doc 树 动态事件流 │
|
|
79
|
+
│ （8 大分类） （7 大类型） │
|
|
80
|
+
│ ┌──────────────┐ ┌──────────────┐ │
|
|
81
|
+
│ │ 1.路线图/进度│ │ 1.对齐与拍板 │ │
|
|
82
|
+
│ │ 2.待办清单 │ │ 2.规格演进 │ │
|
|
83
|
+
│ │ 3.决策记录 │ │ 3.代码变更 │ │
|
|
84
|
+
│ │ 4.业务规格 │ │ 4.测试与质量 │ │
|
|
85
|
+
│ │ 5.协作纪律 │ │ 5.审批与交接 │ │
|
|
86
|
+
│ │ 6.运维与基建│ │ 6.运维与基建 │ │
|
|
87
|
+
│ │ 7.历史档案 │ │ 7.教训沉淀 │ │
|
|
88
|
+
│ │ 8.工具模板 │ │ │ │
|
|
89
|
+
│ └──────────────┘ └──────────────┘ │
|
|
90
|
+
│ │
|
|
91
|
+
│ 数据源: git log + docs/*.md + JSONL │
|
|
92
|
+
└──────────────────────────────────────────┘
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**左面板** — 静态 doc 树：自动分类展示你的项目文档结构，每个节点带状态徽标。点击联动右侧事件流。
|
|
96
|
+
|
|
97
|
+
**右面板** — 动态事件流：按时间轴展示项目关键事件（决策/编码/测试/审批/教训），线程分组，标签筛选。
|
|
98
|
+
|
|
99
|
+
## 安全边界
|
|
100
|
+
|
|
101
|
+
- **只读** `docs/`、`.git/`、`.sandtable/`，不修改你的项目文件
|
|
102
|
+
- **不联网**：无遥测、无分析追踪，所有数据都在本地
|
|
103
|
+
- **默认 127.0.0.1**：serve 仅本机可访问，暴露公网需 token 认证
|
|
104
|
+
- `.gitignore` 自动追加：`init --apply` 自动标记不提交的生成文件
|
|
105
|
+
|
|
106
|
+
## 兼容环境
|
|
107
|
+
|
|
108
|
+
| IDE | 规则位置 |
|
|
109
|
+
|-----|---------|
|
|
110
|
+
| Cursor | `.cursor/rules/sandtable-event-log.mdc` |
|
|
111
|
+
| Claude Code | `.claude/skills/sandtable-event-log/SKILL.md` |
|
|
112
|
+
| Trae | `.trae/rules/sandtable-event-log.md` |
|
|
113
|
+
| Cline | `.clinerules/sandtable-event-log.md` |
|
|
114
|
+
| GitHub Copilot | `.github/instructions/sandtable-event-log.instructions.md` |
|
|
115
|
+
| 通用 | `.sandtable/rules.md` |
|
|
116
|
+
|
|
117
|
+
详细文档见 [INSTALL.md](./INSTALL.md)。
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## English
|
|
122
|
+
|
|
123
|
+
### What is Sandtable?
|
|
124
|
+
|
|
125
|
+
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.
|
|
126
|
+
|
|
127
|
+
### Pain Points It Solves
|
|
128
|
+
|
|
129
|
+
- **"Where are we now?"** — roadmap in your head, progress in chat history, decisions scattered across 20 .md files
|
|
130
|
+
- **"What changed?"** — git log is too granular, you need business-level event tracing
|
|
131
|
+
- **"What's the convention?"** — abbreviations, naming rules, coding standards — the AI forgets, you re-explain
|
|
132
|
+
- **"How much did AI cost?"** — token consumption invisible until the monthly bill arrives
|
|
133
|
+
|
|
134
|
+
### Quick Start
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
npm install -g sandtable
|
|
138
|
+
cd your-project/
|
|
139
|
+
sandtable init --apply
|
|
140
|
+
sandtable build
|
|
141
|
+
sandtable serve # → http://localhost:5199
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Key Features
|
|
145
|
+
|
|
146
|
+
- **Dual-view dashboard**: Static doc tree (8 categories) + Dynamic event stream (7 event types)
|
|
147
|
+
- **Multi-source fusion**: git log + docs/*.md SUMMARY blocks + manual events via CLI
|
|
148
|
+
- **Event logging**: Record decisions, code changes, tests, approvals, lessons — with threads and tags
|
|
149
|
+
- **Token tracking**: Per-skill, per-date token consumption summary
|
|
150
|
+
- **Safe by default**: Serves on 127.0.0.1, requires token for public exposure, zero telemetry
|
|
151
|
+
|
|
152
|
+
### Commands
|
|
153
|
+
|
|
154
|
+
| Command | Description |
|
|
155
|
+
|---------|-------------|
|
|
156
|
+
| `sandtable init [--apply]` | Detect IDE environment, create rule files |
|
|
157
|
+
| `sandtable build` | Generate `data/*.json` from docs + git log |
|
|
158
|
+
| `sandtable serve [port] [--watch]` | Start dashboard HTTP server |
|
|
159
|
+
| `sandtable event-log --type <slug> --title "..."` | Record a development event |
|
|
160
|
+
| `sandtable token-log <skill> <in> <out>` | Log token consumption |
|
|
161
|
+
| `sandtable uninstall [--apply]` | Clean up sandtable files |
|
|
29
162
|
|
|
30
|
-
|
|
31
|
-
- `/sandtable scan` — AI 扫描项目文档
|
|
32
|
-
- `/sandtable build` — AI 生成 JSON 数据
|
|
163
|
+
### Security
|
|
33
164
|
|
|
34
|
-
|
|
165
|
+
- **Read-only**: Only reads `docs/`, `.git/`, `.sandtable/` — never modifies your source
|
|
166
|
+
- **No telemetry**: Zero external network calls, all data stays local
|
|
167
|
+
- **127.0.0.1 by default**: Dashboard only accessible from localhost; `--host 0.0.0.0` requires token auth
|
|
168
|
+
- **Gitignore aware**: `init --apply` auto-appends generated files to `.gitignore`
|
|
35
169
|
|
|
36
|
-
|
|
170
|
+
See [INSTALL.md](./INSTALL.md) for full documentation.
|
|
37
171
|
|
|
38
|
-
|
|
172
|
+
---
|
|
39
173
|
|
|
40
|
-
|
|
174
|
+
**npm**: [https://www.npmjs.com/package/sandtable](https://www.npmjs.com/package/sandtable)
|
|
175
|
+
**GitHub**: [https://github.com/beimingju-dafu/Sandtable](https://github.com/beimingju-dafu/Sandtable)
|