让 AI 编程助手调用写匠
给 Claude Code、Codex 一段说明，让它们用 aiwriter 读写你的卡片
Claude Code、Codex 这类 AI 编程助手会在终端里敲命令。把写匠的命令行交给它们， 就能让它们替你做批量的活：把一堆笔记拆成卡片、按大纲排好、导出成稿、统计全书。
先按命令行把 aiwriter 装进终端。
它们要知道的几件事
一律加 --json。 这样输出的就是 JSON，程序读得懂：
aiwriter ls --json
回一个数组，每张卡有 id、title、kind（file 是卡、folder 是文件夹）、parent_id、depth，
以及 path（相对项目根的路径，比如 卷1/篇1/readme.md——文件名重复的卡靠它分得开）。
要正文就加 --with-body，每张卡多一个 body；书大的时候整本正文很大，只看一张就用 aiwriter show <编号> --json。
出错时退出码不是 0，输出是 {"error":{"code":…,"message":…}}。写盘、建项目这类失败，原因认得出时多一格 human，是一句给人看的话；message 仍是完整原文。
命令本身写错了（没这条命令、少了参数、多了不认识的旗标）时例外：退出码是 2，stdout 是空的，原因在 stderr。
判成没成，只看退出码（0 是成了，非 0 一律是失败；失败的细分见下面「失败时看哪个码」）。
show、refs、link、stitch、work show 等按编号找不到卡时同样算出错，code 是 card.not_found——多半是编号抄错了或抄短了。
用 --project 说是哪一本，或者先 cd 进那个 <书名>.aiw 文件夹。
先列、再按编号动。 用 ls --json 拿到编号，再 show、edit、rm。
改正文走标准输入，不用把整段正文塞进命令行：
aiwriter edit <编号> --stdin < 新正文.md
标准输入一个字节都没有（管道上游出错时就会这样），edit 不写，报 input.empty；真要清空一张卡，用 --body ""。
--body 与 --stdin 只能给一样，两样都给算命令写错（退出码 2）。
版本历史默认开着，edit 会先把改之前那一版留进历史，改坏了回得去。
加 --json 时看 kept_before：true 是留住了；false 有两种——作者关掉了历史（正常，那是作者的选择），
或者开着却没写进去。分不清时先跑 aiwriter version status。
删除是可逆的，彻底删不是。 aiwriter rm 把卡放进回收站，还原得回来；
aiwriter trash purge（清空回收站）和 aiwriter trash rm（彻底删一项）都不可恢复，要让它先问过你。
编号照抄，别截短。 aiwriter ls 每行前面印的是短号（aiw 开头的那串），show、edit、rm 都认；
ls --json 里每张卡既有完整的 id，也有短号 short，用哪个都行。自己截 id 的前几位就认不出了。
建项目要先登录。 aiwriter new、aiwriter init 没登录时报 project.need_login，
请作者先在写匠里登录，或在终端跑 aiwriter auth login。读写已有项目里的卡不用登录。
填编号的地方也可以写路径。 相对这本书根目录的路径（比如 _cards/卷1/卷1.md）和编号一样认：
aiwriter show _cards/卷1/卷1.md --json、aiwriter style set _cards/卷1/卷1.md <版式卡> 都行。
给的字先当编号认，认不出再当路径；两样都对不上，照样报 card.not_found。
目录卡里的链接用相对路径。 卡片编号记在 .aiwriter/ 里、不进 git：换一台机器 clone，
或者别的分支里新建的卡合进来，编号链接就失效。给目录卡生成链接时加 --relative --for <目录卡>，
链接写成相对那张目录卡所在文件夹的路径，成品照样认：
aiwriter link --list --relative --for <目录卡编号> <卡1> <卡2> … --json
要层级（篇下面挂章），把清单从标准输入给，行首每两个空格缩一级；每行一张卡，编号或路径都行：
aiwriter link --list --stdin --relative --for <目录卡> --json < 清单.txt
清单里篇那一行顶格，章那几行比它多缩两个空格。写匠不按文件夹或名字猜谁是篇谁是章——层级由你写出来。
写版式卡之前先跑 aiwriter style guide。 它印出写匠交进来的输入（书名、作者、要不要封面与目录……）、
工具箱里能直接用的钩子，以及随写匠带的 Typst 包。想照某一款内置版式改，用 aiwriter prefs show style <款> 看它的源。
失败时看哪个码
失败对象里的 code 是给程序分支用的。下面这些是写匠保证不改的；表外的码不在保证之列，拿不准就看 human 或 message。
退出码也按类分：3 找不到（核对编号、名字、路径后重来）、4 冲突、过期或占用（占用类等一会儿原样再试，其余重读现状后再试）、5 要作家先动手（登录、升级、开启某项设置……别重试，转告作家）、1 其余失败；命令本身写错仍是 2。非 0 一律算失败，3、4、5 只是更细的分类，只判非 0 的脚本照旧管用。
| 码 | 退出码 | 什么情形 | 该怎么办 |
|---|---|---|---|
card.not_found | 3 | 编号不认得；或 --parent、--after、--to 给的编号不存在 | 回 ls --json 核编号，别截短 |
card.gone | 3 | 编号认得，文件刚才还在、现在不见了 | 和 card.not_found 同样处理：卡已不在 |
card.not_folder | 1 | --parent、--to 指向的是一张卡，不是文件夹 | 换成文件夹的编号 |
card.changed | 4 | 这张卡在别处改过了，这次没写 | 先重读，再决定还改不改 |
card.busy | 4 | 这张卡正被另一处保存，这次没写 | 等一会儿，原样再试 |
project.busy | 4 | 写匠桌面端开着这本书正在改，删、改名、挪没动盘 | 等一会儿，原样再试 |
project.changed | 4 | 命令开始之后这本书的结构在别处改过，没动盘 | 先 ls --json 重读，再决定 |
layout.unknown | 3 | layout set 给的版面这本书认不得（版式卡里没有、写匠也没内置），没标 | 报错里列了这本书版式卡里的那几种；写匠内置的与每种怎么写看 layout list |
trash.not_found | 3 | 回收站里没有这个名字（写错了，或已还原过） | 用 trash ls --json 核名字 |
input.empty | 1 | --stdin 读到的是空的，没写 | 管道上游多半出错了；真要清空用 --body "" |
input.not_utf8 | 1 | 标准输入不是 UTF-8，什么都没动 | 把正文存成 UTF-8 再给 |
input.bad_receipt | 1 | --undo 喂进来的不是那条命令交出的回执 | replace --undo 喂上一次回执里的 receipt 那一格；mv --undo 喂上一次的整份 --json 输出 |
project.not_found | 3 | 这个位置不是写匠项目 | 核 --project 的路径 |
project.need_login | 5 | 没登录就建、开、删、还原项目 | 请作者登录，别绕 |
version.off | 5 | 作者关了版本历史 | 不是出错，别替作者打开 |
version.repo_busy | 4 | 历史仓正忙，这一次没记上 | 等一会儿再试，不必处理 |
给它的一段说明
把下面这段放进项目里的 CLAUDE.md（Claude Code）或 AGENTS.md（Codex）：
这是一本用写匠写的书。读写卡片一律用命令行 aiwriter，不要直接改 .aiw 文件夹里的文件：
- 所有命令加 --json；先用 `aiwriter ls --json` 拿到卡片编号，再按编号操作。
- 判成没成只看退出码：0 是成了，非 0 一律是失败；命令本身写错时退出码是 2、stdout 是空的；3 找不到、4 冲突、过期或占用、5 要作家先动手，是失败里更细的分类。
- 看正文：`aiwriter show <编号> --json`
- 改正文：把新正文写进一个文件，再跑 `aiwriter edit <编号> --stdin --json`，正文从标准输入给（`< 那个文件`）。kept_before 为 false 不一定是出事：这本书可能本来就没开历史（`aiwriter version status` 看得到）。
- 新建：`aiwriter add --title <标题> --body <正文> --json`；放进某个文件夹加 --parent <文件夹编号>。回执里的 title、path 是实际落成的（重名会加 -2，过长会截短）。
- 编号照抄 ls --json 里的 id 或 short（ls 每行前面印的 aiw 开头那串就是 short），别截短；也可以直接写相对书根的路径，比如 _cards/卷1/卷1.md。
- 建项目（`aiwriter new`、`aiwriter init`）要先登录；报 project.need_login 时请我登录，别自己绕。
- 删除用 `aiwriter rm <编号>`（进回收站，可恢复）。不要运行 `aiwriter trash purge` 或 `aiwriter trash rm`（彻底删除），除非我明确同意。
- 不确定某条命令怎么用，先跑 aiwriter <命令> --help。
为什么不让它直接改文件：写匠在 .aiwriter 里记着大纲顺序、状态和历史，直接改文件它也认，
但走命令行，每一步都会留历史、进回收站，出了错你回得去。