开发者指南 · Zikaron
参与贡献
欢迎修复缺陷、补充测试、改进界面与文档。动手之前，请先确认改动所在的层。
改动的去向
| 改动内容 | 途径 |
|---|---|
| 界面、文案、交互 | 合并请求，修改 crates/app 与 crates/zikaron-ui。 |
| 命令行 | 合并请求。输出格式、参数、退出码或拒因变化时，同步修改 CLI-SCHEMA.md，测试会逐项对照；zikaron contract 由代码里的同一张表生成。经桌面的动词表在三处：CLI-SCHEMA.md 第 11 节、桌面的通道表与命令行的动词表，测试互相对照。mcp 的工具表由动词表读出，测试钉住工具清单，协议写在第 13 节。 |
| 本机数据格式 | 合并请求，同步修改 crates/app/local-data-standard.md；测试向量在 crates/app/tests/local_standard.rs，逐字节核对。 |
| 固定字面量 | 新增或改动文件魔数、格式名、通道名一类字面量时，登记在 crates/app/family-literals.json，测试双向对照每一项与代码里定义它的那一处。 |
| 打包与持续集成 | 合并请求，修改 packaging/、crates/zikaron-pack 或 .github/workflows/。 |
| 核的实现（缺陷、性能） | 合并请求，附一致性比对零分歧的结果。 |
| 新的条目读法 | 先在讨论区确定约定，再实现。 |
| 法文措辞 | 议题。散文可以修订，核的摘要保持不变。 |
| 法的规则 | 议题，其归宿是下一版法。 |
| 冻结核与登记合约 | 议题。它们由摘要与代码哈希钉住。base/ 里其余的工装可以直接提合并请求。 |
流程
- 先开议题，说明要改什么、为什么；小的修正可直接提交合并请求。
- 从主干创建分支，一个请求只做一件事。
- 在本地跑通全部测试。
- 提交说明写清改动内容，以及用户能看到的变化。
提交前检查
- 工具链由
rust-toolchain.toml钉在 Rust 1.97.1。cargo test --workspace --locked --no-fail-fast --release全部通过；合并请求上的持续集成在 macOS、Linux 与 Windows 上以发布构建构建并测试，macOS 与 Linux 两格必须通过，这两格还按发布的方式构建两个程序，并用zikaron-pack no-paths确认二进制里只有中性的路径名。 cargo build --release --locked通过；依赖有增减时，一并提交Cargo.lock，第三方许可清单在构建时随之重生成。- 修改了
zikaron或zikaron-kit：比对器在至少三个种子的语料上零分歧，语料在仓库之外的副本中生成。 - 修改了
zikaron-anchor：全部链面录制回放一致。 - 两部法的摘要与合约代码哈希重算相符。
- 界面新增的每句文字都有中英两个版本。
- 新增的每个控件都接通真实操作，失败时有明确提示。
- 手册中对应段落同步更新，中英文逐句对应。
判断放在核中
编写界面代码时，遇到「这个条目是否合法」「这份授权此刻是否有效」一类问题，请调用核、采用其结论。在界面中另写一遍判断，日后两处必然出现偏差。命令行同理，原样传出核的输出。
测试规范
- 使用临时目录
- 每个测试在自己的临时目录中创建机器目录与数据文件夹，结束时清理。
- 使用测试密钥
- 密钥在测试中现场生成，或取自语料；真实的助记词与私钥留在仓库之外。
- 使用本地链
- 涉及上链的测试针对本地 anvil 或录制运行；公共节点留作手动试用。
- 正反两面都测
- 每条拒绝规则都配一个应被拒绝的输入和一个应被接受的输入。
- 时间由注入给出
- 需要「当前时刻」的测试，把时刻作为参数传入。
界面约定
- 写账本、写链的动作先弹出确认卡，列明写到哪里、写什么、花费多少；真正写入的红色实心键只出现在确认卡上。经桌面（
--home）的请求由命令行一方发起，桌面直接照做，上链照「命令行上链」的设置。打开「经凭据操作」先输口令、定有效期，卡上写明「命令行上链」为「自动发送」时命令行可花这个身份的 gas。 - 每屏至多一个蓝色主按钮。
- 前台使用日常用语；地址、哈希、类型名、判定词收在「详细信息」中。
- 每次失败都说明两件事：发生了什么，下一步怎么做。
- 页面即时响应，耗时操作放到后台，完成时提示一次。
- 界面上的「已生效」「已确认」，背后须有可读取的事实。
文字
界面用语采用成熟应用的简洁写法。手册、Wiki 与本指南只写现行内容，历史留在版本记录中。代码注释用英文，引用法条时写明条号。
保持仓库干净
提交中只放产品源码与文档；本机路径、邮箱、密钥、节点访问令牌、个人测试数据都留在仓库之外。提交前请检查差异。