一篇文档可以有很多个版本。jdu push 是发布；带 --id 是给同一篇追加新版本。
第一次发布
jdu push notes/index.md
过程：
stderr 是进度（收集了几个文件、新上传几个 blob），stdout 只有最终 URL。
常用选项：
jdu push notes/index.md \
--title "今天的笔记" \
--visibility private \
--tag 日记 --tag 工作
| 选项 | 缺省 | 说明 |
|---|---|---|
--title | 首个 # 标题，再退到文件名 | 列表页和阅读页顶上的标题 |
--visibility | 新文档 private | private / public（official 档走 --official，需管理员） |
--tag | 不传则不动已有标签 | 可重复；更新时传了就整组替换 |
--id | 新建一篇 | 复用已有文档 id，发新版本 |
--official | 不上架 | 上架到官方知识库（需管理员；official 是独立档位——公开可读，只进官方库列表）。不传则保持原值 |
更新已有文档时，不传 --visibility / --title / --tag / --official 会保持原值。不要在更新脚本里写死 --visibility private，否则会把已经公开的文档悄悄改回去。
上架到官方知识库
官方库按档位查（visibility=official），不是「管理员的公开文档」。公开一篇不会自动进官方库；反过来也一样。
npx @monoedge/jdu-cli push notes/index.md --id abc123 --official
npx @monoedge/jdu-cli official add abc123
npx @monoedge/jdu-cli official list
npx @monoedge/jdu-cli official rm abc123
--official / official add 需要管理员身份。CLI 所用 token 的归属 owner 或显示名对上 adminOwner 任一即可。普通 push --id 只更新正文，不会把已上架的文档拿下来。
official rm 下架后文档回落到 private（不留「下架前的可见性」记忆）——想公开就再 jdu share --visibility public，想彻底清掉就 jdu delete <id> --hard。
更新同一篇
从 URL 里取出文档 id。https://docs.mszhou.com/d/abc123 的 id 是 abc123。
jdu push notes/index.md --id abc123
jdu versions abc123
versions 列出序号、时间、源 hash。每次成功的 push 都会加一行，序号从 1 递增。
列表确认一下：
jdu list
jdu list --all # 含已归档
回滚
回滚不会删掉之后的版本，只是把「当前显示」指回指定序号，并按那一版重新预渲染。
jdu rollback abc123 2
回滚后再 push，新版本接着最大序号往下加，不会覆盖历史。
归档、删除、清空
这三档破坏性递增：
| 命令 | 文档还在吗 | 还能恢复吗 |
|---|---|---|
jdu archive <id> | 在，默认列表里看不到 | jdu archive <id> --undo |
jdu delete <id> | 默认等同归档 | 同上 |
jdu delete <id> --hard | 物理删除 | 不能 |
jdu reset <id> | 文档壳还在，版本和产物清空 | 不能 |
--hard 和 reset 没有确认提示，脚本里慎用。
强制重渲染
正常情况用不到。内核升级时缓存 key 会自己失效，读者下次打开会重渲。你改的是 Widget 实现、而文档 md 没变时，可以刷一篇：
jdu rerender abc123
只刷这一篇的渲染缓存并预热。没有「全站重渲」这条 CLI。
预渲染失败时
push 返回错误且不会写下这一版。库里不会留半截版本，上一版（如果有）继续对外服务。把 md 修好再 push。
常见原因：入口文件不存在、JSON Widget 大面积不合法且触发渲染预算。单块 Widget 名字写错或 JSON 校验失败，不会让整篇 push 失败，那一块会降级成代码块。