让 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":…}}。
命令本身写错了（没这条命令、少了参数、多了不认识的旗标）时例外：退出码是 2，stdout 是空的，原因在 stderr。
判成没成，只看退出码。
show、refs、link、stitch、work show 等按编号找不到卡时同样算出错，code 是 card.not_found——多半是编号抄错了或抄短了。
用 --project 说是哪一本，或者先 cd 进那个 <书名>.aiw 文件夹。
先列、再按编号动。 用 ls --json 拿到编号，再 show、edit、rm。
改正文走标准输入，不用把整段正文塞进命令行：
aiwriter edit <编号> --stdin < 新正文.md
版本历史默认开着，edit 会先把改之前那一版留进历史，改坏了回得去。
加 --json 时看 kept_before：true 是留住了；false 有两种——作者关掉了历史（正常，那是作者的选择），
或者开着却没写进去。分不清时先跑 aiwriter version status。
删除是可逆的，彻底删不是。 aiwriter rm 把卡放进回收站，还原得回来；
aiwriter trash purge（清空回收站）和 aiwriter trash rm（彻底删一项）都不可恢复，要让它先问过你。
编号要用完整的那个。 aiwriter ls 每行前面只印编号的前 8 位，show、edit、rm 认不出它——
一律从 ls --json 里取 id。
填编号的地方也可以写路径。 相对这本书根目录的路径（比如 _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
清单里篇那一行顶格，章那几行比它多缩两个空格。写匠不按文件夹或名字猜谁是篇谁是章——层级由你写出来。
给它的一段说明
把下面这段放进项目里的 CLAUDE.md（Claude Code）或 AGENTS.md（Codex）：
这是一本用写匠写的书。读写卡片一律用命令行 aiwriter，不要直接改 .aiw 文件夹里的文件：
- 所有命令加 --json；先用 aiwriter ls --json 拿到卡片编号，再按编号操作。
- 判成没成只看退出码：0 是成了；命令本身写错时退出码是 2、stdout 是空的。
- 看正文：aiwriter show <编号> --json
- 改正文：把新正文写进一个文件，再 aiwriter edit <编号> --stdin < 那个文件。kept_before 为 false 不一定是出事：这本书可能本来就没开历史（aiwriter version status 看得到）。
- 新建：aiwriter add --title <标题> --body <正文> --json；放进某个文件夹加 --parent <文件夹编号>。
- 编号一律用 ls --json 里完整的 id（ls 不带 --json 时只印前 8 位，别的命令不认）；也可以直接写相对书根的路径，比如 _cards/卷1/卷1.md。
- 删除用 aiwriter rm <编号>（进回收站，可恢复）。不要运行 aiwriter trash purge 或 aiwriter trash rm（彻底删除），除非我明确同意。
- 不确定某条命令怎么用，先跑 aiwriter <命令> --help。
为什么不让它直接改文件：写匠在 .aiwriter 里记着大纲顺序、状态和历史，直接改文件它也认，
但走命令行，每一步都会留历史、进回收站，出了错你回得去。