让 AI 编程助手调用写匠

Claude Code、Codex 这类 AI 编程助手会在终端里敲命令。把写匠的命令行交给它们， 就能让它们替你做批量的活：把一堆笔记拆成卡片、按大纲排好、导出成稿、统计全书。

先按命令行入门把 aiwriter 装进终端。

它们要知道的几件事

一律加 --json。 这样输出的就是 JSON，程序读得懂：

aiwriter ls --json

回一个数组，每张卡有 id、title、body、kind（file 是卡、folder 是文件夹）、parent_id、depth。 出错时退出码不是 0，输出是 {"error":{"code":…,"message":…}}。 命令本身写错了（没这条命令、少了参数、多了不认识的旗标）时例外：退出码是 2，stdout 是空的，原因在 stderr。 判成没成，只看退出码。 按编号查一张不存在的卡，show --json 回的是 null。

用 --project 说是哪一本，或者先 cd 进那个 <书名>.aiw 文件夹。

先列、再按编号动。 用 ls --json 拿到编号，再 show、edit、rm。

改正文走标准输入，不用把整段正文塞进命令行：

aiwriter edit <编号> --stdin < 新正文.md

这本书开着历史（写匠里〔打开历史〕，或 aiwriter version enable）时，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。

给它的一段说明

把下面这段放进项目里的 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 位，别的命令不认）。
- 删除用 aiwriter rm <编号>（进回收站，可恢复）。不要运行 aiwriter trash purge 或 aiwriter trash rm（彻底删除），除非我明确同意。
- 不确定某条命令怎么用，先跑 aiwriter <命令> --help。

为什么不让它直接改文件：写匠在 .aiwriter 里记着大纲顺序、状态和历史，直接改文件它也认， 但走命令行，每一步都会留历史、进回收站，出了错你回得去。