开发者指南 · Zikaron

命令行

zikaron 提供与窗口相同的账本操作，一个动作一个子命令。它面向脚本：输出是单个 JSON 值，结论体现在退出码里。完整的输出形状、退出码、拒绝原因与参数，见源码里的 CLI-SCHEMA.md；zikaron contract 也把这份契约由代码里的同一张表输出成一个值。唯一的例外是 zikaron mcp：它在标准输入输出上按模型上下文协议一行一条消息，见下文AI 应用。

在哪里

用 dmg 安装的: /Applications/ZIKARON.app/Contents/MacOS/zikaron。在应用「设置 › 命令行与 AI 控制」的「终端」里打开「启用 zikaron 命令」，它在 /usr/local/bin/zikaron 放一个链接，需要时 macOS 弹出管理员口令框；这个开关要在拖进「应用程序」之后的应用里打开。
用 pkg 安装的: /usr/local/bin/zikaron，装完即可用；「启用 zikaron 命令」显示「被其他安装占用」，保持原样即可。
用 deb 安装的: /usr/bin/zikaron；「启用 zikaron 命令」显示「已由安装包提供」。用 AppImage 时，要用命令行请装 .deb，开关显示「此安装方式不支持」。「接入 AI 应用」的「复制配置」在 AppImage 与从磁盘映像里直接打开的应用里同样灰着。
Windows: 解压出的文件夹里的 zikaron.exe，在终端里运行，双击它只会一闪而过。「启用 zikaron 命令」把这个文件夹写进本用户的 Path，之后新开的终端才认得 zikaron。
从源码构建的: target/release/zikaron；「启用 zikaron 命令」在 macOS 上链到 /usr/local/bin，在 Linux 上链到 ~/.local/bin，这个文件夹要在 PATH 里。

三条约定

标准输出是单个规范 JSON 值: 每次调用输出一个值，以值的最后一个字符结束。字节格式依法 §3.4：紧凑书写，成员按字节序排列。
误用时标准输出为空: 参数有误、路径读取失败时，退出码为 2，标准输出零字节，标准错误的第一行写作 <原因> <对象>。对象只用命令行自己的名字：参数表里的旗写作 --名字，其余的值与路径只写它在参数里排第几、有多长，如 E_UNREADABLE #3 (15 bytes)，所以私钥、带访问密钥的节点地址都留在你自己手里，终端与日志里只有位置和长度。第二行是给人看的说明，按系统语言（LC_ALL、LC_MESSAGES、LANG、LANGUAGE 中第一个设了的）是中文时用中文，否则用英文，不属约定。调用方凭标准输出是否为空，即可分清答案与误用。
状态词原样传出: GREEN、PARTIAL、FAIL、COMPLETE、GAPS 等由核写出，命令行原样传出。

写条目被法拒收时（E_ENTRY，其 token 为 E_BODY_FIELD，退出码 1），标准错误另有一行人话，点名是哪一项、由哪个参数给，例如 statement_md: 缺或不成形,由 --statement 给；这一行同样随系统语言，属于给人看的说明，标准输出与退出码与它无关。

写文件只有一种方式：--out 先在旁边写完整个临时文件、落盘，再改名到位；同名文件已经存在时，这次写入作罢，原文件一个字节都保持原样。kit-verify --originals-to 取出原件也只有一种方式：先在所选文件夹里的暂存文件夹排好、逐份核过指纹，再逐个就位、绝不替换；所选文件夹里已有同名即整批不取，一个字节不写。

退出码

码	含义	示例
0	已答，答案肯定	`GREEN`、`COMPLETE`
1	已答，答案否定	条目被拒，写入会把账本写断（`E_WOULD_BREAK`），节点以关乎这一笔的理由拒绝估 gas 或估数超过 200,000（`E_GAS_REFUSED`），交易入块而执行失败（`E_TX_STATUS`），先前发出的那一笔已作废（`E_TX_VOID`），授权文件拆不开（`E_GRANT_FILE`），链上已有这把钥对所给哈希的锚（`E_ON_CHAIN`），记录包不成立（`E_KIT`）或包里的原件对不上（`E_RECORDS`），取不出原件（`E_EXTRACT`，所选文件夹一个字节不写），加密记录包打不开、坏了或接收方地址在链上没有锚（`E_ADDRESSED`），经桌面的 `attest` 与 `succeed`（`E_ON_DESKTOP`），桌面拒绝这一动作（`E_DESKTOP_REFUSED`）或在发出之前拒绝上链（`E_SEND_REFUSED`），网络方面的除外，凭据缺、过期或不成形（`E_CREDENTIAL_MISSING`、`E_CREDENTIAL_EXPIRED`、`E_CREDENTIAL_SHAPE`），桌面此刻正在写这个数据目录（`E_HOME_HELD`），写者标是别台机器（`E_HOME_OTHER_MACHINE`），原目录已由桌面收编（`E_ADOPTED`），数据目录只读或账本断了链（`E_READ_ONLY`），账本已交出（`E_HANDED_OFF`），交接件不收（`E_HANDOFF`），或结论为 `FAIL`、`BROKEN_CHAIN`、`NO_LABEL`
2	误用	参数有误、路径读取失败、`--key` 与 `--key-file` 同给、密钥文件他人可读、`--form registry` 缺 `--registry`、给 `--home` 的动词或旗不收它、桌面数据目录的 `--ledger` 同给 `--key` 或 `--key-file`、`anchor --ledger` 同给 `--endpoint` 等它不收的八个旗、`--ledger` 指向数据目录之外的封存文件夹、`--to` 与 `--to-key` 同给或任一与 `--as folder` 同给、地址或公钥不成形、打开加密包而没给钥匙（`E_ARGS --key --ledger --home`）、`kit-verify` 的 `--key` 与 `--ledger` 同给、`mcp` 带任何旗；标准输出为空
3	已答，介于两者之间	`PARTIAL`、`GAPS`、`UNAVAILABLE`；经桌面或经凭据的 `anchor` 只入了队（`E_QUEUED`）；记录包里有存证没上链、链没读成或原件缺（`E_RECORDS`）
4	答案缺席	节点失联、多个节点读数相左、扫描被拒、取不到随机数、节点出于自身缘由拒绝估 gas（`E_UNREACHABLE`）、桌面没有答（`E_DESKTOP`）、桌面因网络拒绝（`E_DESKTOP_REFUSED`）、上链在发出之前因网络被拒（`E_SEND_REFUSED`）、找接收方公钥时没找到而有网络没读成（`E_ADDRESSED`，`token` 为 `ADDRESS_CHAIN_UNREAD`；经桌面为 `E_DESKTOP_REFUSED` 带同一码）

3 与 4 各占一个码，是这张表的分量所在。把「尚未上链」并入 0，买方会把尚待锚定的授权当作放行；并入 1，一次「暂不可知」会被读成「伪造」。把「节点不通」并入 1，一次网络故障会被读成「这条链是假的」。扫描失败是答案缺席，调用方应重试或换节点。

二十六个子命令

子命令	作用
`keygen`	生成一把密钥，输出地址与私钥
`init` ✦	在空账本上写创建账本条目
`history` ✦	追加一条存证（`--file` 按应用的约定记一份文件）
`grant` ✦	签一份授权并写入账本
`revoke` ✦	签一份撤销并写入账本（裁决文件摘要可选）
`adopt` ✦	写一条导入条目；连署只给了两半之一的即拒
`attest` ✦	用外部密钥出一份连署
`succeed` ✦	写一条换密钥或移交条目
`annotate` ✦	写一条注记
`retract` ✦	写一条删除条目（目标须是本账本里一条现存的存证）
`anchor` ✦	把哈希锚定上链：调用登记合约，或自转账裸锚；签名之前先问链上已有没有，再估 gas，重跑先问；`--ledger` 指向桌面数据目录里的账本时，经凭据发它的待上链队列
`scan`	按链设置扫描锚（`--endpoint` 收 http 与 https；`--ledger` 代替 `--basis` 时，扫描范围取自那个数据目录的设置与账本；不给 `--endpoint` 时，经凭据用那个数据目录设置里的节点）
`audit`	用扫描结果加账本做审计，输出报告与结论（`--ledger` 收账本目录、桌面数据目录里的账本（经凭据）、账本镜像或记录包（`.zkit` 文件或文件夹）；`--out` 另存这一趟的审计输入；加密记录包以 `E_ADDRESSED`（`ADDRESSED_ELSEWHERE`）拒，打开它用 `kit-verify`）
`check-grant`	六项核验一份授权（`--grant` 收授权条目文件或 `.zkgrant` 授权文件；读桌面数据目录里的账本时读到签发方整本账，撤没撤销答得出）
`chain-check`	逐跳核验转授权链（`--hop <授权文件>[=<审计输入文件>]`，可重复）
`depth`	一件记录的深度读数
`fpm-sign`	签指纹清单
`ack-sign`	签收执
`badge`	编码或解码凭证（`--encode` 与 `--decode` 二选一）
`kit-export` ✦	导出记录包，自验通过才写出；缺省写成一个文件，`--as folder` 写成文件夹；`--to <地址>` 或 `--to-key <公钥>` 把这一个文件加密给一个接收方
`kit-verify` ✦	逐条核验一份记录包（`--kit` 收 `.zkit` 文件或文件夹）：原件对不对、上没上链，与桌面「核验记录」同一判法；`--fragment` 给扫描结果，不给即每条都是 `unread`；`--originals-to` 把对得上的原件取到一个已有的文件夹；加密包用 `--ledger <家>/ledger`（经凭据以本机各身份）、`--key` 或 `--key-file` 打开
`hand-over`	把整本账写成一份交接件（`--out`），这一处随即停写
`take-over`	收一份顺接的交接件（`--handoff`），这一处随即复写
`show`	显示一条条目的作者、ID、类型、上一条、序号与内容
`mcp`	经模型上下文协议供 AI 应用调用命令行（标准输入输出，一行一条消息），见下文AI 应用
`contract`	输出命令行自己的契约：动词、各动词的参数（带 `--home` 时的另一张）、退出码与拒因

标 ✦ 的十二个收 --home：其中十一个交给桌面去做，succeed 带 --home 一律答 E_ON_DESKTOP，见下文经桌面。子命令之外的第一个词按误用处理，退出码为 2。

参数

六十二个参数一律是长参数，且每个都带一个值；每个子命令有自己的一张参数表，表外参数按误用处理。条目正文中法所要求的成员，在命令行上都可以省略；省略后由核依法拒收，命令行只检查它自己做事所必需的几项。这样判断规则只在核里存在一份。

--key-file: 从文件读私钥，代替 --key，两者择一；文件须只本人可读。凡收 --key 的子命令都收它。
--originals-to: kit-verify 收：一个已有的文件夹，把包里与记录对得上的原件全部取进去，要么全取，要么一个字节不写（E_EXTRACT）；签过的文件夹整个取出；取出时答里多 taken（名字）与 path。
--originals: kit-export 从桌面托管的数据目录导出时收（经凭据的 --ledger，或经桌面的 --home）：只认 none，所选存证的原件一件也不带。不给即照桌面导出页的同一取法带上，答里列出 originals 与 leftOut。普通账本文件夹给了即按误用拒，它的原件以 --file 逐个给。
--to、--to-key: kit-export 收，二者择一：--to 是接收方地址，命令行在链上找这个地址自己签过的上链交易、由签名恢复出公钥；--to-key 是 0x 加 66 或 130 位十六进制的公钥，须在曲线上。只加密单个文件，与 --as folder 同给即误用。直接对明文账本目录用 --to 时要给 --endpoint（链号须在内置部署表里）；对桌面数据目录的账本，用那个数据目录的网络与这台机器的只读网络，不收 --endpoint。
--key（kit-verify）: 打开加密记录包的那把钥；普通包不要钥。与 --ledger 同给即误用。
--proxy: anchor、scan 与带 --to 的 kit-export 收：system（默认）、none，或一处代理地址 协议://[用户名[:口令]@]主机:端口，协议为 http、https、socks5（或 socks5h）、socks4（或 socks4a，只带用户 ID）；用户名与口令按百分号编码，各至多 255 字节，写在命令行上的口令在命令运行期间本机其他进程看得到。本机节点一律直连；给了代理地址时，私网、链路本地与 .local 的节点也直连。system 先读终端的代理变量：https_proxy、http_proxy、all_proxy（大小写两写）设了任一个即照它们走，连同 no_proxy，三个系统一样；都没设才读系统的代理设置：先是系统指定的自动配置脚本，再是手填的代理（macOS 读网络设置，Windows 读系统答的当前设置，Linux 读 KDE 或 GSettings 存在盘上的设置，读不到再看环境变量）；系统的「自动探测代理」不读。经凭据走数据目录的几条路（anchor --ledger、不给 --endpoint 的 scan --ledger、kit-export --to --ledger）不给 --proxy 时用这台机器设置里的代理，设为跟随系统时只读系统的代理设置，终端的代理变量一概不读；anchor --ledger 不收 --proxy。
--home: 交给正在运行的桌面应用代做，见下文。

各子命令的参数表与环境变量（每一问的总期限 ZKA_TIMEOUT_SECS，默认 30 秒；应答上限 ZKA_MAX_ANSWER_BYTES，默认 64 MiB 等）都写在 CLI-SCHEMA.md 里。

示例

生成密钥、创建账本、存证一份文件、上链、审计：

zikaron keygen
# {"address":"0x…","ok":true,"privkey":"0x…"}

zikaron init --ledger ./ledger --key-file ./key.txt --statement "作品存证"

zikaron history --ledger ./ledger --key-file ./key.txt --file 手稿.pdf
# {"entryId":"0x…","ledger":"…","ok":true,"seq":1,"written":true}

zikaron anchor --key-file ./key.txt --endpoint <链号>=<节点> \
  --form registry --registry <合约地址> --hash <entryId>

zikaron scan --endpoint <链号>=<节点一> --endpoint <链号>=<节点二> \
  --basis basis.json > fragment.json

zikaron audit --ledger ./ledger --fragment fragment.json
echo $?

history --file 按应用记录文件的同一约定填：content 是这份文件字节的 SHA-256，mode 是 {"mark":"bytes-sha256/1","toolchain":<"bytes-sha256/1" 这串字的 SHA-256>}；同一份文件，命令行与应用记下的这两项逐字相同。也可以不用 --file，自己给 --content、--mark、--toolchain 三项，两种写法不能同给。

节点地址可以是 http:// 或 https://，大小写都认，IPv6 写成方括号形；https 用编进程序的根证书校验证书链与主机名，与应用同一个连法。每一问有一个 30 秒的总期限，一个地址解析出几个 IP 时逐个试，读类的问在连接中途断开时换新连接再问一次，交易只广播一次；地址里带的访问密钥在一切输出里都隐去。

anchor 恰好收一个 --endpoint：它读这个节点的基础费与最近 20 块的成交小费，按应用的同一条规则定费（取中位数大于零的块，块块为零时取零），再请节点按这一笔交易估一次 gas，所带额度是估数的 1.5 倍（向上取整），最多 200,000。节点以关乎这一笔的理由拒绝估（会回滚），或估数超过 200,000，即拒 E_GAS_REFUSED；节点出于自身缘由拒绝（限流、不支持这一问、要凭据、链不符等），或没答，报 E_UNREACHABLE；两种情形都在广播之前停下。发出之后，它按间隔一轮轮问收据，直到 --wait-secs 用完。

链上已有即不发。--form registry 带 --hash 时，签名之前先问这个节点：登记合约里是否已有这把钥对这几个哈希的锚（照扫链的读法读 Anchored 日志，从合约部署块读到链头）。有一条即答 E_ON_CHAIN，names 列出已有的，tx 与 blockNumber 是最早那一笔，一笔不发；节点答不出即 E_UNREACHABLE，也不发。--form bare 与 --calldata 照常发。

重跑先问。自持私钥运行的 anchor 把它为同一次锚定（同一条链、同一把钥、同一个去处、同一段数据）签过的每一笔交易的 nonce 与哈希，在广播之前记进机器目录的 cli-sent/，只记这两项。同一条命令再跑时，先按哈希问节点：已入块即照答；还在节点池里就接着等收据；都不在而 nonce 没被用掉，按同一个 nonce 重签再发，至多一笔能入块；nonce 已被别的交易用掉即答 E_TX_VOID 并停下，再跑一次即重新发起。所以成功之后把同一条命令再跑一遍，答的是先前那一笔，一次锚定只付一次费。

scan 的每一问都带上扫描范围里的发送者，只取这些地址的日志；节点拒答时原样再问，连拒三次才把范围拆小。basis.json 写明扫描范围：哪些链、哪些登记合约、哪些发送地址、起止区块，格式见法 §9.4。命令行不记已核对的事实，每次扫描都问遍每一条日志。

写之前先审

每个写条目的子命令（含 init 与 retract）都过同一道门：条目签好之后，核把「这个账本加上这一条」离线审一遍，会新添一条法 §8.3 的链上发现（换钥之后旧钥再写、跳号、同一位置写第二条、接错上一条）即拒 E_WOULD_BREAK，names 写明是哪几种，一个字节也不写。手给 --seq、--prev 也一样过这一道。账本有两个根而没给 --root 时，写入一律拒 E_TIP_FORKED。

经桌面

给 --home <桌面的数据目录> 时，init、history、grant、revoke、adopt、attest、annotate、retract、anchor、kit-export、kit-verify 十一个子命令交给正在运行、已解锁、并以写者打开这个数据目录的 ZIKARON Desk 去做：条目以桌面的身份写进桌面的账本，窗口里随即可见；kit-verify 由桌面在自己的网络上核验，加密给它某个身份的包先由那个身份打开；私钥与口令都留在桌面里，写入全由桌面完成。

「设置 › 命令行与 AI 控制」的「经桌面 App 操作」开着、桌面开着这个数据目录时，为它开一条本机通道：macOS 与 Linux 上是机器目录里一个只本人可读写的套接字文件，Windows 上是只本用户够得着的命名管道。连上之后两端各问系统对方以谁的身份运行，不是同一用户即拒。锁定、关掉或换掉数据目录、退出应用，通道随即关闭；「经凭据操作」开着时，桌面不开通道。
参数照常先判误用；带 --home 时各子命令另有一张参数表，账本、密钥与序号由桌面自己定（如 history 收 --file 与 --note，anchor 只收 --home），表外的参数算误用。请求按到达的次序逐个做，在桌面里走与点按同一条动作路径。
anchor 照「设置 › 命令行与 AI 控制」「上链操作」里的「命令行上链」：「自动发送」照队列页的「全部上链」发出，答与 anchor --ledger 同形；「仅加入队列」只入队，答 E_QUEUED（退出码 3）。
attest 与 succeed 一律答 E_ON_DESKTOP：连署要口令，口令只在桌面上输；把账本移交给另一把钥只在桌面上亲手做，succeed 不去问桌面。kit-export 收 --entry、--note、--out、--as（缺省一个文件）、--to、--to-key、--originals，所选存证的原件照桌面导出页带上（--originals none 即不带），别的附件与证明包在桌面上选，--to 的公钥在桌面的网络与只读网络上找。kit-verify 收 --kit 与 --originals-to。
桌面锁着、没开这个数据目录或已退出时答 E_DESKTOP（退出码 4）；「经凭据操作」开着时 detail 为 ALONE，去掉 --home 直写即可。anchor 在发出之前被拒答 E_SEND_REFUSED，链上已有答 E_ON_CHAIN；别的动词被桌面拒绝答 E_DESKTOP_REFUSED，token 是桌面自己的代码；网络方面的拒绝退出码为 4，其余为 1。kit-verify 取不出原件或打不开加密包时，token 是桌面的码（EXTRACT_EXISTS、EXTRACT_LINK 等，或 E_ADDRESSED 的各码）；ADDRESS_CHAIN_UNREAD 退出码为 4。

带 --home 的命令行按桌面同一个规则找机器目录。各子命令带 --home 时收哪些参数，见 CLI-SCHEMA.md 第 11 节。

经凭据

「设置 › 命令行与 AI 控制」的「自动控制等级」有两个开关，任何时候只开着一条命令行路径。「经桌面 App 操作」开着时走 --home。「经凭据操作」开着时，「经桌面 App 操作」变灰，桌面关上通道；命令行不带 --home，凭机器目录里一份只本人可读写的凭据，直接读写桌面数据目录里封存的账本、发它的待上链队列，桌面开着、锁着或没开都行。打开「经凭据操作」要输口令并填有效期：天、小时、分钟三格合计一分钟到一年，或「不过期」。

写：history、grant、revoke、adopt、succeed、annotate、retract 的 --ledger 指向数据目录里的 ledger 文件夹时，经凭据写进封存的账本，签名用桌面钥库里为这个身份与角色存的那把钥，不收 --key、--key-file。条目照样先审（E_WOULD_BREAK），写进去之后照桌面的样子排进待上链队列；history --file 的那份文件记进本机签入索引，导出记录包时随包带上原件。init 不收，答 E_NOT_EMPTY。
读：audit、check-grant、chain-check、depth、show --entry、kit-export 照同一开法读那本账，读不拿写者锁。kit-export 照桌面带上原件、条款文件与 anchored-on: 那一行，给 --originals none 即不带原件；scan --ledger 的扫描范围取自这个数据目录的设置与账本，末块是所用节点报的链头；不给 --endpoint 时节点也取这个数据目录的设置。kit-export --to 在这个数据目录的网络与这台机器的只读网络上找接收方公钥。kit-verify --ledger 用同一份凭据取本机每个身份每种角色的钥匙，去打开加密记录包。
发：anchor --ledger 经凭据发这个数据目录的队列：链号、登记合约与节点取这个数据目录的设置，代理取这台机器的设置；不收 --key、--key-file、--endpoint、--form、--registry、--hash、--calldata、--proxy，--wait-secs 缺省 90 秒。「命令行上链」为「自动发送」时发出队里能发的全部、等收据、结清；为「仅加入队列」时答 E_QUEUED。队里没有可发的而有一批在途时，按交易哈希接着问那一批；那一批已不在任何节点池里而 nonce 仍空着，「自动发送」即在原 nonce 上照原样重签再发；都没有即答 E_SEND_REFUSED，token 为 QUEUE_EMPTY。「加价重发」只在桌面上按。
轮流拿锁：命令行每写一笔拿这个数据目录的写者锁，写完即放；这时桌面也一样，拿到锁时若命令行写过先重读。发送在备好与签发两段拿着锁，等收据时放开，结清时再拿；六十秒内拿不回即答 E_HOME_HELD，那一批留在途。
写闸：写条目、发送与交出之前先查。数据目录落着只读标记（LEDGER_NOT_FETCHED、NEWER_ELSEWHERE）或账本断了链（BROKEN），写条目与交出答 E_READ_ONLY，发送答 E_SEND_REFUSED，token 为那一码；账本已交出，写条目答 E_HANDED_OFF，发送答 E_SEND_REFUSED（HANDED_OFF）。
拒因，退出码都是 1，一个字节不写：E_CREDENTIAL_MISSING（开关关着）、E_CREDENTIAL_EXPIRED（过期，凭据随即删掉）、E_CREDENTIAL_SHAPE（读不出、打不开，或属于换主钥之前）、E_HOME_HELD（桌面此刻在写，稍后再试）、E_HOME_OTHER_MACHINE（写者标是别台机器）。读的动词遇凭据三种与 E_HOME_OTHER_MACHINE 同样拒。
收编之后的原目录：命令行自建的明文账本经桌面「导入密钥」与「收编已有账本目录」之后，命令行写原目录（含 hand-over、take-over）一律答 E_ADOPTED，「经凭据操作」开着关着都一样，原目录一个字节不动；要从命令行接着写，打开「经凭据操作」，改给数据目录里的 ledger。

取出原件与加密记录包

kit-verify --kit <包> --originals-to <文件夹> 先照常逐条核验，再把与记录对得上的原件取进那个文件夹，原名照还；签过的文件夹按它签时的路径整个取出。原件从包里重读，先排进所选文件夹里的暂存文件夹、逐份核过指纹，再逐个就位、绝不替换；同名已有、遇到链接、两份撞名或任何一步失败，都答 E_EXTRACT，已放下的撤回，所选文件夹保持原样。普通包不要家、不要钥。

kit-export --to <地址> 或 --to-key <公钥> 导出只有接收方打得开的单个 .zkit；答与普通包相同。kit-verify 打开它：经凭据给 --ledger <家>/ledger 用本机各身份，直接用时给 --key 或 --key-file，经桌面由桌面的身份打开；打开的明文放在系统临时目录里专用的文件夹，命令结束即删。没有钥匙打得开答 ADDRESSED_NOT_RECIPIENT，有一段核不过答 ADDRESSED_BROKEN，文件头读不成答 ADDRESSED_HEAD。格式见文件与格式。

交接账本

一本账可以在两处之间来回交，例如远程机上命令行的账本目录与本机桌面的数据目录，任何时候只一处在写。hand-over --ledger <这一处> --out <文件> 把整本账写成一份交接件（.zkhand），这一处随即停写，写条目即答 E_HANDED_OFF；交出去的那一份丢了，再跑一次写出同一份。take-over --ledger <这一处> --handoff <文件> 只收顺接的交接件：这一处的每一条都在里面，里面的账是一条线，才按序号写进这一处没有的条目，这一处随即复写；交出过的这一处只收交回来的那一份。不收时答 E_HANDOFF，token 为 NOT_BACK、AHEAD、NOT_ONE_LINE、E_HANDOFF_NOTE 或文件格式的码。本机那一侧经凭据读写，桌面锁着也行，桌面开着时随即见到新条目。上链状态不随交接件走：桌面下一趟账本检查从链上现读，只把链上没有的排进待上链。

AI 应用

zikaron mcp 让 AI 应用经模型上下文协议（MCP）调用命令行：AI 应用把它当子进程起，标准输入输出上每行一条 JSON-RPC 2.0 消息，每行是一个规范 JSON 值；不开端口、不开本机通道、不写文件；输入关上即退出，退出码 0。它不带旗，也不另有权限：每一次工具调用都另起一个本程序，照人在终端里敲的样子跑那个动词，答的字节与退出码与那条命令相同。写入的工具每次调用时看这台机器有没有凭据：有即走 --ledger <家>/ledger，没有即走 --home <家>。协议版本认 2025-11-25 与 2025-06-18；完整约定见 CLI-SCHEMA.md 第 13 节，接入方法见接入。

时间由调用方注入

期限与时段只按链上时间和 --now 注入的时刻判断；省略 --now 即只用链上时间。时刻都由调用方给出，所以同一输入始终得到同一结论。

读应用自己的账本

ZIKARON Desk 数据目录里的账本是加密的（文件以 zikaron-local/2 开头），命令行不持口令。「设置 › 命令行与 AI 控制」的「经凭据操作」开着时，命令行凭那份凭据读写桌面数据目录里的账本，见上文经凭据。从数据目录里单拷出来的 ledger 文件夹读不了，按误用拒绝，退出码为 2：

E_UNREADABLE #3 (40 bytes)
已锁定:这是 ZIKARON Desk 封存的本机数据;命令行只凭凭据读桌面所管之家的账本

要往应用自己的账本里写，打开「经凭据操作」后把 --ledger 指向数据目录里的 ledger 文件夹，或用 --home 交给桌面代做。要交给别处的命令行读，先在应用里导出「账本镜像」或「记录包」：audit（以及经它的 check-grant、chain-check、depth）和 show --entry 的 --ledger 可以直接指向镜像文件夹（含 mirror.json 的那一层）或记录包（.zkit 文件或文件夹）；记录包先按记录包的法核一遍，不成立即拒 E_KIT；加密记录包以 E_ADDRESSED（ADDRESSED_ELSEWHERE）拒，打开它用 kit-verify。写条目的子命令收账本目录与桌面数据目录里的账本，init 只收账本目录；要在两处之间轮流写一本账，用 hand-over 与 take-over，见上文交接账本。

上一页仓库结构与分层下一页法文与一致性套件