mythings · Things

一个 local-first 的「个人事实库」，Web 界面，本机运行：

• 内容：项目、待办、笔记、书签、想法、人、阅读
• 身份：身份（真人 / 虚拟人）→ 邮箱 / 手机号 → 服务账号 → 凭证（API Key / PAT / SSH …）
• 运行：机器 → 运行时 → agent → 会话

标签横向切（AND / OR、共现标签），类型纵向切；任何场景（列表、视图、条目）都能挂一页 Plus 笔记（Markdown）。

运行

npx mythings

mythings [options]
  --port, -p <n>       端口（默认 4717）
  --data-dir, -d <dir> 数据目录（默认 ~/.mythings，或环境变量 MYTHINGS_DIR）
  --host <addr>        监听地址（默认 127.0.0.1；改成 0.0.0.0 会暴露给局域网，没有鉴权）
  --no-open            启动后不自动打开浏览器

数据：目录即数据库

~/.mythings/
  meta.json                  schemaVersion
  things/<type>/<id>.json    每条 thing 一个文件，只存事实字段
  pages/<id>.md              Plus 页面 —— frontmatter(title / bind / stash) + Markdown 正文
  notes/<id>.md              条目自由笔记
  views.json                 保存的视图（跨设备有意义）
  ui.json                    本机界面状态：左栏顺序、隐藏项、列、区块布局（可删，会重建）
  history/<id>/<时间>-r<n>.json   每次覆盖前的旧版本，每条最多 20 份
  trash/<id>.json            删除的条目，可恢复（⌘Z）
  legacy/                    v1 单文件 db.json 迁移后的原件
  demo/                      demo 模式的独立库，同样结构，与你的数据完全隔离

设计原则：

1. 只存事实，不存缓存。宿主机名、归属身份名、链条上的祖先等一律运行时推导（shared/domain/entities.ts 的 enrichAll），父项改名子项自动正确。
2. 事实与视图分离。things/ pages/ notes/ views.json 是你的东西；ui.json 是「这台机器上我怎么看」。
3. 一条一个文件。可 git、可放同步盘，冲突落在单条；正文是 .md，用别的编辑器也能改。
4. 写入前校验。所有写入过 normalizeThing：丢未知字段、补默认值、按类型校验；文件里没有一堆 null。
5. 乐观锁 + 实时同步。每条带 rev，过期写入返回 409；服务端通过 SSE 把变更推给所有标签页。

首次启动若发现旧版单文件 db.json，自动迁移为上述结构并把原件移到 legacy/。

API

服务端零依赖（Node http），所有接口以 /api 开头，加 ?demo=1 操作 demo 库。

| 方法 | 路径 | 说明 | | --- | --- | --- | | GET | /snapshot | 首屏：全部 things / pages / notes / views / ui | | GET | /events | SSE，推送 { origin, events[] }；请求头 x-client-id 用于过滤回声 | | PUT | /things/:id | body { thing, rev }；rev 不符 → 409 并返回当前版本 | | POST | /things | 批量 [{ thing, rev }]，任一冲突整批不写 | | POST | /things/batch-delete | { ids } → 移入 trash，引用置空 | | POST | /things/:id/restore | 从 trash 恢复 | | GET | /things/:id/history | 历史版本 | | PUT / DELETE | /pages/:id | body { page, rev } | | PUT | /notes/:id | { md }，空正文即删除 | | PUT | /views /ui | 整体替换 | | POST | /demo/reset | 仅 demo 库 |

快捷键

N 新建 · / 搜索（支持 type:todo status:进行中 tag:AI）· G 实体地图 · ⌘Z 撤销 · Esc 关闭弹层 · 双击标题改名 · 点状态 / 优先级直接切换 · 左栏右键隐藏、拖动排序

代码结构

bin/mythings.js        CLI 入口
shared/
  types.ts             领域类型（按 type 的判别联合）、Page / Note / UiState
  model.ts             类型元数据、状态集、颜色、关系词表
  domain/entities.ts   normalizeThing 校验 · enrichAll 推导 · chainOf · detachReferences
  domain/query.ts      范围 / 搜索 / 标签过滤 / 排序 / 分组
  domain/edges.ts      关系索引（显式 links + 结构隐含）
  domain/scene.ts      场景键
  domain/markdown.ts   Plus 页 Markdown 与 frontmatter
server/
  repo.ts              仓储：目录读写、rev、history、trash、事件
  api.ts               路由 + SSE
  migrate.ts           v1 → v2
  demo.ts              示例数据
web/src/
  app/store.ts         极简外部 store（selector 订阅）
  app/data.ts          数据镜像 + 命令层（乐观更新、409 处理、撤销栈、SSE）
  app/ui.ts            瞬时界面状态
  app/select.ts        跨组件共享的查询结果（记忆化）
  app/view.ts          展示层派生：列、树表、规格字段、默认区块、实体地图
  ui/                  主题 token、Dialog、Toast
  components/          界面组件
tests/                 vitest：领域层 + 仓储（含迁移）

开发

npm install
npm run dev        # tsx watch 后端(4717) + vite(5173)
npm run check      # 类型检查 + 测试
npm run build      # dist/web + dist/server

发布

npm version patch && npm publish   # prepublishOnly 自动 build；包内只含 bin/ 与 dist/