@tensorix/metahub 0.1.2

package/README.md

@@ -0,0 +1,162 @@
+# metahub
+
+给 AI 用的本地知识库 CLI：在 `~/.metahub/` 下用 SQLite 管理 notion 风格的**类型化数据库（表 + 行）**和 **markdown 文档**，单机可用，也能通过简单的 C-S 服务端在多机之间用 **CRDT 最终一致**同步。库 + CLI + 独立二进制三合一。
+
+> 运行时依赖 **Bun**（使用 `bun:sqlite` / `Bun.serve`）。用 `bunx`、全局安装后的 `metahub`，或下载独立二进制。
+
+## 数据存储
+
+```text
+~/.metahub/
+  metahub.db   # SQLite：数据库/属性/记录/文档 + CRDT oplog
+  cache/       # 内容寻址 blob（附件）
+```
+
+可用 `METAHUB_HOME` 环境变量覆盖目录（便于多实例 / 测试）。
+
+## 快速开始
+
+```bash
+bunx @tensorix/metahub init                      # 创建 ~/.metahub
+mh db create "Tasks"                             # 建一张表 -> 返回 id 如 db_tasks-k3f9c1
+mh use tasks                                     # 设为「当前库」,之后 record/prop 免带库参数
+mh prop add Title  --type text                   # 作用于当前库
+mh prop add Status --type select --options "todo,doing,done"
+mh record create --data '{"Title":"写设计稿","Status":"todo"}'
+mh record update fix-login --data '{"Status":"doing"}'   # 用唯一前缀/名字,不必粘完整 id
+mh doc create --title "架构说明" --body @arch.md  # @file / @- / 直接字符串
+mh search "架构"
+mh get tasks                                     # 通用查找:按 id/前缀/名字,自动判类型
+mh edit <ref>                                    # 在 $EDITOR 里改文档正文 / 记录字段(给人用)
+
+# 给 AI 用的非交互增量编辑(对标 Read / Edit / Write):
+mh doc read <ref>                                # 读正文 + version(改前先读)
+mh doc edit <ref> --old "旧文本" --new "新文本"  # 锚定查找替换,只传增量
+mh doc append <ref> --body "追加段落"            # 也有 prepend
+```
+
+输出按受众自动切换：终端（人）显示表格 / markdown，被管道或子进程调用（AI）输出 **JSON**；`--json` / `--pretty` 可强制。
+
+### ID 与引用
+
+每个实体 id = `类型_名字slug-随机后缀`（如 `db_tasks-k3f9c1`、`rec_fix-login-bug-7j02an`）。类型前缀让 id 自解释（一眼区分 db/rec/doc/prop），随机后缀保证多机离线创建几乎不撞。
+
+凡接受 id 的地方（`get`/`update`/`delete`/`--db`/`--parent`/`--target` 等）都接受**引用**，按以下顺序解析，省去粘贴完整 id：
+
+- **完整 id**（永远可用，跨库亦可）
+- **唯一前缀**（git 短 SHA 风格，`rec_fix-log` 或裸 slug `fix-log`）
+- **名字/标题**（db 名、doc 标题、prop 名，大小写不敏感）
+
+歧义时报错并列出候选；用 `mh use <db>` 设当前库后，record/prop 的引用与列举自动限定在该库内。Tab 补全见 `mh completion`。
+
+### 属性类型
+
+`text · number · checkbox · select · multi_select · date · relation · url`
+（select/multi_select 用 `--options a,b,c`；relation 用 `--target <db引用>`）
+
+relation 字段的**值**也接受引用：`--data '{"assignee":"Alice Chen"}'` 会在目标库里按名字/前缀解析成记录 id（数组逐个解析）；歧义或找不到会报错，完整 `rec_…` id 始终直通。
+
+## 多机同步（CRDT）
+
+每次写入都进 oplog（Hybrid Logical Clock + 按字段 Last-Write-Wins），合并可交换、幂等、最终一致。
+
+文档正文按**块（block）**切分(段落级,fenced code 整块),每块是独立 register、用分数索引(fractional index)排序。所以两台机器改同一篇文档的**不同段落**能干净合并、互不覆盖；`mh doc edit` 的锚定替换通常只改命中那一块。`documents.body` 是由块重算的物化缓存。
+
+```bash
+# A 机：启动同步服务端（服务端也是一个 metahub 节点）
+mh --server --port 7777
+
+# B 机：与服务端推/拉一轮
+mh sync http://a-host:7777
+
+# 同一条 sync 命令也能在「单个文档/数据表」与「本地文件」间导出/导入，
+# 方向按参数自动判别：哪一侧能解析成库内实体，另一侧就是文件路径。
+# 格式按实体类型固定——文档↔markdown、数据表↔CSV。
+mh sync architecture arch.md   # 导出：文档 → markdown
+mh sync tasks tasks.csv        # 导出：数据表 → CSV（表头=属性名，CSV 含 id 列）
+mh sync arch.md architecture   # 导入：markdown → 文档（更新已存在的文档）
+mh sync tasks.csv tasks        # 导入：CSV → 数据表（有 id 列则按 id upsert）
+```
+
+服务端在根路径 `/` 还内置一个**浏览器 WebUI**（Preact）：左侧列出数据库与文档，可浏览/行内编辑数据表、用块级所见即所得编辑 markdown 文档（含嵌套列表、代码语言名与常用 Markdown 快捷输入）、全文搜索；编辑走与 CLI 同一套 core 写入路径，进 CRDT oplog 后随 `mh sync` 复制。同时暴露一组 `/api/*` REST 接口与自动生成的 OpenAPI 文档（`/docs`）。WebUI 资源（含 Preact）单独打包为 `dist/webui.js`，仅在浏览器首次访问 `/` 时懒加载，**不进入 CLI 启动路径，对命令行性能零影响**。设计见 [docs/impl-context/07-webui/design.md](docs/impl-context/07-webui/design.md)。
+
+## Agent 托管静态站点
+
+AI agent 用 CLI 把生成好的 HTML/CSS/JS **发布**成一个命名「站点」，`mh --server` 把它在 `/sites/<name>/` serve 出去；页面同源调用上面的 `/api/*` 即可读取本库的数据表与文档——等于一个本地 mini-Supabase（静态托管 + 数据 API）。
+
+```bash
+# agent 把生成的文件写到一个目录,再整目录发布(站点不存在则自动创建)
+mh site publish blog ./dist
+mh site files blog                 # 查看清单
+mh site put blog index.html --content @-   # 也可单文件上传(--from <file> / --content @file|@-)
+
+# serve 出去
+mh --server --port 7777            # 浏览器打开 http://localhost:7777/sites/blog/
+```
+
+站点与文件**和其它数据一样进 CRDT oplog**，随 `mh sync` 跨机复制：文本与小二进制内联存储；超过阈值的大二进制走内容寻址 blob（`cache/`，其字节暂为本机、不随 oplog 复制，清单照常同步）。
+
+**鉴权**：`--debug` 全开（无鉴权）；否则单 token 守护**每个请求**。token **默认持久化在 `~/.metahub`**（重启复用，`mh token` 查看），带有效期（默认 30 天），**到期或 `mh token refresh` 时才轮换**；轮换后旧 token 在宽限期内（默认 7 天）仍可换到新 token，浏览器**无感续期**。`--token` / `METAHUB_TOKEN` 则固定一个不持久化、不过期的 token（脚本/CI 用）。浏览器首次访问会弹**解锁页**输入 token，存入 `localStorage`+cookie 后刷新；之后注入的 fetch 套壳自动给同源 `/api/*` 调用带上 `Authorization: Bearer`，并在轮换后透明地用 `GET /auth/token` 换新 token 重试，所以 agent 写的页面无需把 token 写进源码。token 可经 `Authorization: Bearer`、Cookie `mh_token` 或 `?token=` 任一方式携带；有效期/宽限期可经 `METAHUB_TOKEN_TTL` / `METAHUB_TOKEN_GRACE` 调整。服务端默认只绑 `127.0.0.1`，`--host 0.0.0.0` 才对外。设计见 [docs/impl-context/08-agent-sites/design.md](docs/impl-context/08-agent-sites/design.md)、[docs/impl-context/10-persistent-token/design.md](docs/impl-context/10-persistent-token/design.md)。
+
+## 三种用法
+
+```bash
+# 1) 作为库（Bun）
+import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
+
+# 2) 作为 CLI
+npm i -g @tensorix/metahub   # 然后用 metahub / mh
+bunx @tensorix/metahub <cmd> # 免安装
+
+# 3) 独立二进制（免运行时）
+chmod +x metahub-darwin-arm64 && ./metahub-darwin-arm64 init
+```
+
+支持平台：`darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64`。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `mh init` | 创建 `~/.metahub` |
+| `mh db create\|list\|get\|delete` | 管理数据库（表） |
+| `mh use [<db>] [--clear]` | 设置/显示「当前库」（record/prop 默认作用于它） |
+| `mh get <ref>` | 通用查找：按 id/前缀/名字解析，自动判别类型 |
+| `mh prop add\|list\|update\|remove` | 管理属性（列）；`add` 用 `--db` 指定库（默认当前库） |
+| `mh record create\|list\|get\|update\|delete` | 管理记录（行） |
+| `mh doc create\|list\|get\|update\|delete` | 管理 markdown 文档 |
+| `mh doc read <id>` | 读正文 + version token（AI 改前先读） |
+| `mh doc edit <id> --old --new` | 锚定查找替换（`--replace-all` / `--if-match`） |
+| `mh doc append\|prepend <id> --body` | 在文档首/尾追加块 |
+| `mh edit <id>` | 在 `$EDITOR` 中交互式编辑文档/记录（给人用） |
+| `mh search <query>` | 全文检索（文档 + 记录） |
+| `mh site create\|put\|publish\|list\|files\|rm\|delete` | 托管 agent 生成的静态站点（HTML/CSS/JS），由 `--server` 在 `/sites/<name>/` serve 出去 |
+| `mh token [show\|refresh]` | 查看 / 轮换持久化的服务器鉴权 token（存于 `~/.metahub`，默认 30 天到期轮换） |
+| `mh completion <bash\|zsh\|fish>` | 打印补全脚本：`eval "$(mh completion zsh)"` |
+| `mh sync <url>` | 与服务端同步一轮（CRDT 推/拉） |
+| `mh sync <src> <dst>` | 单个文档/数据表与文件互导：文档↔markdown、数据表↔CSV；方向按参数判别（哪侧是库内实体），格式按实体类型固定 |
+| `mh --server [--port] [--host] [--debug] [--token]` | 启动服务端：`/sync` + 根路径 WebUI + `/api/*` REST + `/docs`（OpenAPI）+ 静态站点 `/sites/<name>/` + token 交换 `/auth/token`；非 `--debug` 时每个请求需带 token |
+
+## 开发
+
+```bash
+bun install
+bun run dev init                  # 热重载运行 CLI
+bun test                          # 跑测试（含 CRDT 收敛测试）
+bun run build                     # 产出 dist/（库 + CLI + 类型声明）
+bun run build:binaries            # 产出 binaries/ 五平台二进制
+```
+
+## 目录结构
+
+```text
+src/
+  core/        # 业务逻辑（库和 CLI 共享）；含 sites.ts（静态站点模型，进 CRDT）、csv.ts（文件导入导出用）
+    sync/      # CRDT 同步协议 + 服务端 + 客户端 + WebUI/REST 路由 + 静态站点托管与鉴权
+               #   （routes/webui-routes/openapi/webui/sites-routes/sites-serve/auth）
+               #   files.ts：单文档/数据表与文件互导（markdown/CSV）
+  cli/         # citty 子命令（含 site）
+  webui/       # 浏览器 WebUI（Preact，独立打包为 dist/webui.js）
+  index.ts     # 库入口
+scripts/       # 构建脚本（含 webui 打包入口）
+```