# 有互动和富文本的文章，源文件还是 markdown 吗

> source: 想法/草稿/有互动的文章怎么写.md

## 先看现在是怎么做的

Vim 那篇（`文章/vim-language/index.md`）其实还是一个 markdown 文件。互动部分是带名字的代码块：

````
```vim-try
@title 加一个逗号
@keys ea,<Esc>
@goal Hello, world
Hello world
```
````

网站读到 `vim-try` / `vim-play` / `vim-grid`，就把这一块换成一个能按键的小 Vim（`site/src/live/vim-practice.ts`）。`echarts`（图表）、`math`（公式）、`mermaid`（流程图）也是这样做的（`site/src/live/rich.ts`）。`test/vim-engine.test.mjs` 还会把每个 `vim-try` 的按键真的跑一遍，看结果是不是等于 `@goal`。

所以答案已经在仓库里了：**正文是 markdown，互动是「块」**。块里只放数据（几行 `@键 值` 加一段正文），不放代码；块长什么样、怎么动，由网站仓库里的组件决定。

## 为什么不让文章直接写 HTML / JS（或者 MDX）

- 文章是数据，组件是代码。代码只放在 `site/` 里，有测试、有设计检查；内容仓库里只有文字，公开前的密钥扫描和逐字校验才查得过来。
- 一种块写好了，所有文章都能用，样式和模式色也自动一致。
- AI 和 agent 写一个块，只是写几行 `@键 值`，出错的余地很小；构建还能检查每个块对不对。
- 文章搬家、网站重做，块的数据不变，只换渲染的组件。

## 具体流程

### 1. 有一张「块」的表，和操作表同一个思路

`site/src/live/blocks.ts`（新）里每种块登记一次：

- 名字：`vim-try`。
- 一句话说明。
- 字段：`@title`（可选）、`@keys`（必填）、`@goal`（必填）、正文。
- 一个最小的示例。
- 渲染函数（现在散在 `rich.ts` 和 `vim-practice.ts` 里）。
- 检查函数：比如 vim-try 跑一遍按键，看结果是不是等于 goal。

构建时逐块检查，有一块不过就停，和题库的数值核对一样。现在只有测试会查 vim-try，这一步把它挪进构建。

### 2. 写的时候：在正文里插块，不填表单

- studio 编辑器里输入 `/`（或者点「插入」），弹出这张表里的块；选一个，插入带示例的模板，光标停在第一个要改的地方。
- 右栏预览改用网站的同一个渲染器（`rich.ts`），不再用 `marked`。这样写的时候看到的小 Vim 就能按，和读者看到的一样。现在预览把块显示成代码，这是最大的缺口。
- 块写错了（缺 `@goal`、按键跑不到目标），预览在那一块上直接标红，并说出原因。

作者要管的仍然只有内容：文字，加上几块「这里放一个练习」。

### 3. 需要一种还没有的互动时

比如想要「拖动滑块看最小二乘的直线怎么变」：

1. 先在文章里写一个占位块，比如 ` ```todo-block ` 后面一段话描述想要什么。构建和预览把它显示成「这里要一个互动：……」，文章照样能存，只是在 todo-block 消失之前不能公开。
2. 这件事变成网站仓库的一个任务：写组件、在块表里登记字段和检查、加一个示例。可以由 AI/agent 来做，走网站仓库的测试和设计检查。
3. 组件上线后，把占位块换成真的块（只填数据）。

只用一次的互动也照这个流程做。登记一次的成本不高，换来的是能检查、样式统一、以后还能用。

### 4. 富文本的边界

加粗、表格、引用、脚注、公式、代码，都是 markdown 或者现有的块。少数还缺的排版（比如提示框、左右对照）也做成块，不在正文里写 HTML。

## 和「只写内容」怎么接

- 新建：点「写」，空白页，第一次保存时生成文件；id、date 自动生成，title 取第一个 `#`（见 [写文章只写内容](/doc/d6f5ab9)）。
- 插块：`/` 菜单。
- 补字段：先不接 AI。缺的 topic、deck 在公开前由右栏提示补；以后再交给 AI。

## AI 以后接在哪

服务器上的 opencode 配的是 DeepSeek，有两种接法：

- **直接调 DeepSeek 的 API**（OpenAI 兼容），用 opencode 配置里的同一个 key。适合补字段、改一段这类一问一答，快，也好控制。
- **把 opencode 当 agent 跑**（`opencode run "…"`），让它通过 `npm run op` 改内容，提交说明写 `ai: …`。适合起草一篇、写一个新块的组件这类多步的活。

还没上服务器确认过 opencode 的配置和 key 放在哪。

## 做出来的（2026-11-05）

- 块表在 `site/src/live/blocks.ts`：vim-try、vim-play、vim-grid、echarts、math、mermaid、todo-block，每种有说明、字段、示例和检查。渲染函数还留在 `rich.ts` 和 `vim-practice.ts`，没有搬进表里：表管「是什么、对不对」，渲染管「长什么样」。
- 构建对每篇公开文章逐块检查，一块不过就停。现有的 22 个块全部通过。
- studio 右栏的预览换成了网站的渲染器：小 Vim 能直接按，图表、公式照常画；没过检查的块标红，并写出原因。「公开」一栏列出有问题的块，点一下跳到那一行。流程图在 studio 里还只显示源码，因为后台的安全策略不让加载外部脚本。
- 编辑器里在行首输入 `/`，或者点「块」，会弹出这张表，可以用名字或中文筛选。选一个就插入示例，示例的第一行处于选中状态，直接改就行。
- todo-block 能存，预览里显示「这里还要一个互动：……」；公开时构建会拒绝。

还没做：「写」入口（空白页直接写，id、日期自动生成，标题取第一个 `#`）。

## 还没想通的

- 块的检查能不能都做成「可执行」的？vim-try 能跑按键，图表能检查数据格式，但「讲解动画」这种怎么检查？
- `/` 菜单里除了块，要不要也放「插入一张图」「链到知识库的一条」？
- todo-block 要不要列进网站的 `/open`，当作公开的待办？
