开发者指南 · Zikaron

接入

让你的应用读取 Zikaron 的记录：核验授权、读取记录包、请用户的桌面应用代写条目，或在业务流程中提示用户留证。

接入方式

接入有三条路。多数应用是读者：读者拿到的是用户导出的成品，授权码、授权文件、记录包。要在业务流程里替用户留证的应用，可以经桌面写入：以 --home 调用 zikaron，由用户正在运行的 Zikaron 在它的数据目录里代写条目或上链，见经桌面写入；用户打开「经凭据操作」后，也可以经凭据直接写，见经凭据写入。无论哪条路，一本账本任何时候只有一处在写，密钥都留在用户的钥库里。AI 应用可以经 MCP 走后两条路，见AI 应用经 MCP 接入。

用命令行核验

最简便的接入方式是以子进程调用 zikaron，读取其退出码与标准输出。

zikaron check-grant --grant grant.entry --ledger ./issuer-ledger \
  --fragment fragment.json --now $(date +%s)

退出码	应用的处理
0	放行
1	拒绝。核验失败时列出失败的项；授权文件拆不开（`E_GRANT_FILE`）、账本或输入有误时显示原因
3	暂缓。告知用户哪一项尚待结果，稍后重试
4	答案缺席：节点不通、各节点答得不一致、扫描被拒，或取不到随机数；经桌面时桌面缺席，或上链在发出之前因网络被拒。重试，或更换节点
2	调用有误，请检查参数。标准输出为空；标准错误的第一行是 `<原因> <对象>`，只认这一行，第二行起是给人看的话，随系统语言显示中文或英文

--grant 收一个授权条目文件，也收用户导出的授权文件 .zkgrant：命令行按应用的同一读法拆开，核的是这份文件为之而立的那一跳。授权码的每一段是条目字节的 base64url 编码（省去填充），解码后存为文件即可；多段的授权码（转授权链）用 chain-check --hop 逐跳核验。--ledger 可以直接指向用户导出的账本镜像或记录包（.zkit 文件或文件夹），用户开着「经凭据操作」时也可以指向数据目录里的 ledger，见命令行。节点地址可以是 http:// 或 https://；连节点的 scan、anchor 与带 --to 的 kit-export 收 --proxy（system、none 或一个代理地址），缺省先照终端的代理变量，都没设再跟随系统的代理设置；经凭据走数据目录的路不给 --proxy 时用这台机器设置里的代理；本机上的节点一律直连。

要核对你的调用与所装版本是否对得上，跑 zikaron contract：它把动词、参数、退出码与拒因输出成一个 JSON 值，由代码里的同一张表生成。

请把 3 作为独立的一档处理：「暂无结果」「通过」「失败」是三种状态，界面上也以三种样式呈现。

经桌面写入

给 --home <桌面的数据目录> 时，十一个动词（init、history、grant、revoke、adopt、attest、annotate、retract、anchor、kit-export、kit-verify）交给正在运行、已解锁、并以写者打开这个数据目录的 Zikaron 去做：条目以用户的身份写进用户的账本，窗口里随即可见。私钥与口令都留在桌面里。succeed 带 --home 一律答 E_ON_DESKTOP。

zikaron history --home "$DESK_HOME" --file ./delivery.pdf --note "交付第一版"

答复	应用的处理
0	写成。输出带 `entryId` 与 `seq`，存下编号以便日后指向这条记录
`E_DESKTOP`（4）	此刻没有桌面通道：桌面已退出、已锁定、开着别的数据目录，或「经桌面 App 操作」关着。请用户打开并解锁 Zikaron 后重试；`detail` 为 `ALONE` 时，用户开着「经凭据操作」，去掉 `--home` 改走经凭据写入
`E_QUEUED`（3）	`anchor` 时用户把「命令行上链」设成了「仅加入队列」：条目已排进队列，等用户在桌面上发出
`E_DESKTOP_REFUSED`（1 或 4）	`anchor` 以外的动词被桌面具名拒绝，`token` 是它的代码（`kit-verify` 取不出原件时为 `EXTRACT_…`，加密包为 `E_ADDRESSED` 的各码）；网络方面的拒绝与 `ADDRESS_CHAIN_UNREAD` 为 4
`E_SEND_REFUSED`（1 或 4）	`anchor` 在发出之前被拒，`token` 是桌面的码（如 `QUEUE_EMPTY`、`INSUFFICIENT_FUNDS`），网络方面为 4
`E_ON_CHAIN`（1）	链上已有这些哈希的锚，一笔未发；`names` 列出已有的
`E_ON_DESKTOP`（1）	`attest` 要口令，`succeed` 是把账本移交给另一把钥，都只能在桌面上做

这条路只通本机本用户：通道是机器目录里只本人可读写的套接字文件，或只本用户可连的命名管道，两端各自向系统核对对方是谁。桌面锁定、关闭数据目录或退出，通道即关；「经凭据操作」开着时通道也关着。各动词带 --home 时收哪些参数，见命令行 · 经桌面。

经凭据写入

用户在 Zikaron 的「设置 › 命令行与 AI 控制」打开「经凭据操作」（输口令，定一分钟到一年或不过期的有效期）之后，同一台机器上的程序与 AI 代理可以不开桌面直接调用 zikaron：把 --ledger 指向用户数据目录里的 ledger 文件夹，history、grant 等写条目，audit、check-grant 等照读，anchor --ledger 发这个数据目录的待上链队列（「命令行上链」为「仅加入队列」时答 E_QUEUED，等用户在桌面上发）。签名用钥库里这个身份的钥，命令行不收 --key 与口令；写进来的条目随即出现在桌面的窗口里。kit-verify --ledger <家>/ledger 用本机各身份打开加密记录包；scan --ledger 不给 --endpoint 时用这个数据目录的节点。

除上表之外，请处理这几种答复（退出码都为 1，一个字节未写）：E_CREDENTIAL_MISSING、E_CREDENTIAL_EXPIRED、E_CREDENTIAL_SHAPE（请用户到「设置 › 命令行与 AI 控制」打开或重开「经凭据操作」）、E_HOME_HELD（桌面此刻在写，稍后重试）、E_HOME_OTHER_MACHINE（这份数据由另一台机器写）、E_READ_ONLY（数据目录只读或账本断了链，token 写明哪一种）、E_HANDED_OFF（账本已交到别处）。

在另一台机器上工作的 AI 代理，可以接手一本账：用户在本机经凭据 hand-over 出一份交接件，AI 代理在远程机上 take-over 进它的账本目录后写条目、自己上链；写完 hand-over 交回，用户在本机 take-over 收下。任何时刻只一处在写。anchor 签名之前先问链上已有没有，所以本机上过链的条目在远程机上答 E_ON_CHAIN，一笔不发；桌面下一趟账本检查从链上现读，远程机上过链的不会再排进队列。见命令行 · 交接账本。

AI 应用经 MCP 接入

用户在 Zikaron 的「设置 › 命令行与 AI 控制」「终端」一组里按「接入 AI 应用」的「复制配置」，贴进 AI 应用的 MCP 设置：

{"mcpServers":{"zikaron":{"args":["mcp"],"command":"<本机 zikaron 的完整路径>"}}}

写入的工具有 history、grant、revoke、adopt、annotate、retract、kit-export（含 to、to-key；originals 给 none 即不带原件）、anchor、kit-verify，参数是各动词带 --home 时收的那几项加上 home（kit-verify 另收 fragment、unavailable，home 可以不给）；照开关经凭据或经桌面走，anchor 照「命令行上链」，「自动发送」时花这个身份的 gas。只读的有 show、audit、scan（只收 home）、check-grant、chain-check、depth、badge（只解码）、contract。生成密钥、凡带私钥的路、succeed、交接与加价重发都不给，任何工具都不收私钥。

参数都是字符串，可重复的是字符串列表；路径参数只收绝对路径。结果的文本是那条命令的标准输出，structuredContent 为 {"answer":…,"exit":…}；退出码 0、1、3、4 都是答案，标作错误（isError）的只有误用（2）与 mcp 在起命令之前自己拒收的参数；子进程崩溃或起不来时没有 structuredContent。一次做一件，按到达先后；取消时只读的即停，写入的做完照答。答里的账本文字照原样给，是数据。

直接调用核

Rust 项目可依赖 zikaron 与 zikaron-kit 两个 crate。它们只做判断：链由你的代码去读，再把字节交给核；记录包目录可以交给 zikaron_kit::kitdir::verify_kit 直接从盘上读取核验；.zkit 文件先按容器格式拆开（见文件与格式），再把各项交给 zikaron_kit::kitdir::verify_enumeration；以 zikaron-kit-addressed 加换行开头的 .zkit 是加密记录包，核读不了它，要由接收方先打开（核验页或 kit-verify），格式见加密记录包。其他语言请依据法文自行实现，并用一致性套件验收，见测试一份实现。

读取用户导出的记录包

同一台机器上的应用可以列出用户已导出的记录包，供用户选择递交。机器目录按应用自己的顺序找：

用户在你的应用设置中手动指定的目录。
指针文件中写明的路径：macOS 与 Linux 上是 ~/.zikaron-desk，Windows 上是 %LOCALAPPDATA%\ZIKARON\.zikaron-desk（环境变量 USERPROFILE 指向别的文件夹时，改为它下面的 AppData\Local\ZIKARON\.zikaron-desk）。指针存在时以它为准：目标读取失败，请明确告知用户「Zikaron 的数据已迁移」，并请其重新指定。
指针缺席时：默认位置，macOS 与 Linux 上 ~/.zikaron-desk.d/，Windows 上 %LOCALAPPDATA%\ZIKARON\.zikaron-desk.d\。

「有效」的唯一标准：该处的 kits/index.json 可读，且格式名为 zikaron.kits-index/1。

索引行的 anchoredOn 写明这个包锚在哪条链（链号、登记合约、起始区块）。用户在 Zikaron 里核验过的记录包，机器目录的 kits/verified/<包编号>.json 里有一份核验结果档：包成不成立、每件记录最早计入的锚、这一次读成与没读成的网络，格式见核验结果档。只读这份档、自己不读链的应用，由它得知记录包锚在哪条链、成不成立。

你的应用对 Zikaron 数据的权限限于读取：机器目录里的 kits/index.json 与 kits/verified/，以及索引行 path 指向的记录包（.zkit 文件或文件夹，它们在各数据目录的 kits/ 下）。拿到记录包后先自行核验，再使用其中的文件。索引里带 oneTimeKey 的行是加密记录包：其余各项读自加密前的明文包，path 指向的文件只有接收方打得开；行里一律不记接收方。

让记录指向你的交易

用户为你应用中的一笔交易留证时，可在「为谁留证（可选）」中填写你的应用名、对方身份、对方编号，以及可选的对方角色，这些内容原样写入条目的 for 成员（角色存为 seat）；对方身份须为 0x 加 40 位十六进制。日后读到这条记录的人，据此对应到具体交易。

请在界面中列出这几个值，便于用户照抄：应用名用固定的短字符串，编号用你系统中该笔交易的编号。

在关键时刻提醒

事前留下的记录分量最重。请在流程中找出这些时刻并提醒用户留证：交付文件时、确认收货时、双方就条款达成一致时。

签名请求

需要用户签名时，请让用户使用交易密钥。身份密钥专用于账本；Zikaron 的界面也照此设计，签名只发生在用户自己发起的写入中。

约定新的条目类型

条目类型是开放的。你可以约定一种新类型，写明类型名、正文成员与读法，并公开这份约定。其他读者遇到它时列入「无法识别的类型」，法的检查结论照旧；ZIKARON Desk 的账本状态行会把它算作问题。

类型名选用带项目前缀的字面量，与现有类型区分开。
正文引用其他条目时，使用条目编号。
读法写成对全部输入都有定义的规则：格式相符时如何读，格式有误时如何显示。
把约定登记在仓库的讨论区，便于其他实现采纳。