# studio 的每个操作都是一个接口

> source: 想法/草稿/studio的每个操作都是一个接口.md

## 想做什么

- 编辑页的每个按钮背后是一个有名字的操作：`article new`、`article rm`、`article mv`、`article meta`、`publish`、`unpublish`、`note save`、`idea capture`、`idea promote`（想法升级成文章）、`media upload`……
- 点按钮和在终端里打这条命令是同一件事；点的时候终端里出现一行 `$ article publish vim-language`，转圈，然后 ✓ / ✗ 和耗时，和网站页头的 `#trun` 一样。
- 人、网页、AI agent 都只通过这一套操作改内容。

## 现在的样子（2026-11-05）

`site/src/lib/studio/api.ts` 已经是一组 `/studio/api/<action>` 接口（登录用 TOTP，每次保存是一个 git commit，只提交碰到的那个文件），但它们是给页面用的零散端点：没有删除，没有统一的名字和参数规格，没有操作记录，agent 不走它，直接改文件。

## 数据库还是文件

想要的其实是三件事：一个入口、行为有约束、所有人用同一套操作。这三件事都不需要把正文搬进数据库。

正文留在 markdown + git 的理由：

- 每次保存已经是一个 commit：历史、对比、回滚都现成，删除也能找回。
- 构建逐字校验、扫密钥、数值核对，部署是 git 同步到树莓派，全都建立在文件上。
- agent 读文件、grep 最顺手；放进数据库以后，它们看内容也得走接口，调试反而难。
- 数据库能约束的（字段、类型），用操作的参数规格加 frontmatter 校验一样能约束。

数据库适合放的东西：操作记录（谁、从哪儿、做了什么、结果）、搜索索引、登录会话。这些可以从文件重建，放 SQLite 里。

约束靠两层：

1. 操作表：每个操作声明参数规格、会碰哪些路径、提交信息怎么写。路径由操作决定，调用方给不了任意路径。
2. 守门：内容仓库加一个检查（测试和 pre-commit），根目录和各形态文件夹下出现不认识的文件就拒绝。这样 agent 就算绕过接口直接写文件，也提交不进去。

## 定下来的（2026-11-05）

作者看完上面的比较说「那这么看不要数据库」。做出来的样子：

- 一张表 `site/src/lib/studio/ops-spec.ts`：看的操作（`ls cat search context health ideas books articles practice images sync history show`）和改的操作（`new save rm mv capture "article new" "problem new" chapter goal meta publish unpublish mature`），每个操作写参数顺序、哪些可选、哪些是长文本。名字最后用了动词在前、平的形式（`rm`、`mv`），不是一开始想的 `article rm`；文章是不是整个文件夹由路径决定。
- 一行和一次调用是同一个东西：`toLine` 把调用写成一行（正文显示成 `‹N 字›`），`parseLine` 把敲的一行变回调用。
- 三个入口：页面上每个按钮 `POST /studio/api/op/<名字>`；页面底部的终端（点的时候出现 `$ 那一行`、转圈、✓/✗ 和耗时，也能直接敲，`:` 或 ⌘J 跳过去）；agent 的命令行 `npm run op -- <一行>`。
- 操作记录就是 git log：提交说明是 `studio: <那一行>` 或 `agent: <那一行>`，没有另外的日志表。
- 删除答案：`git rm`，一次提交，历史里能找回；文章删整个文件夹并顺手取消公开。`site/config.json` 里点名公开的文章拒绝删和移。
- 守门：`shape.ts` 写清每种形态的文件放哪，操作写之前查一遍；`npm run content:guard` 查整个仓库（当时 332 个文件都对），`--staged` 可以做成 pre-commit 钩子，还没装。

## 还没想通的

- 给 agent 的入口现在是命令行；要不要再包一层 MCP 服务，等真有 agent 不方便跑 shell 时再说。
- pre-commit 钩子要不要装上：装了以后手写的文件放错也提交不进去，但每次提交多跑一次检查。
- 操作记录要不要公开一部分到网站的 `/log`？
