ziyuan-cli 1.15.0

紫垣 ZiYuan:用中国古代朝廷角色组织多智能体协作的命令行工具,改动须用户审阅批准才写入文件。
ziyuan-cli-1.15.0 is not a library.

紫垣 ZiYuan

CI Release

你下诏安排任务,官员协作办理;回奏后由你审阅,准奏后才把改动写入文件。紫垣用中国古代朝廷的称呼组织这套流程,也可以用来逐块翻译和审校小说。

本源码版本 1.15.0:原文追加和修订可以选 Markdown、DOCX、EPUB;终端可以写人工译稿;译文记忆可以查以前定过稿的译法。远程嵌入要先按项目授权,默认不联网。

版本变化见 CHANGELOG,验证范围见 1.15.0 验收记录,已公开的下载包以 GitHub Releases 为准。翻译仍按初译、双路审校、朱批、修订、御览逐块办理,由你决定何时继续;测试通过不代表译文已达到文学或出版质量。

  • 先试用,不必先配置模型:未设置 ZIYUAN_LLM_MODEL 时只演示派工,不会真的分析或修改文件。
  • 接入模型后才执行真实工作:支持 OpenAI 兼容接口,已有 DeepSeek 实测。默认只能读取项目;修改文件和运行测试要另行授权。
  • 模型提出改动,你决定是否写入:任务完成不等于文件已修改,要审阅后执行 apply。
  • 逐块翻译小说:导入日文或英文原文后,按块下诏初译、请只读审校、逐段朱批、修订并御览定稿;初译和修订稿须准奏后才写入正式译文,译文质量仍须人审。另可记下自己的认可译法(御笔札记),不必先建朝廷。
  • 找回定稿译法:设置 ZIYUAN_MEMORY_PROVIDER=local 后,用 ziyuan text memory status|build|search,或在网页译书卡片的「译文记忆」里查看、建库、查询。deterministic 是另一套只在本机计算的固定算法。text tm suggest 用同一份记忆给出参考,不写入本地记忆。命令行要查其他项目,须逐个写 --project;网页只查当前项目。这些方法按字面找相近句子,不理解意思。远程嵌入要先 text memory authorize。建库时发送已授权项目里已定稿段落的原文,每次查询只发送这一次的查询文字;没授权就不联网。查到的内容不会自动写进译稿,也不会自动批准。

原文预览与注音:TXT/Markdown 导入前先检查章序、正文、注音与警告,再确认导入;旧的纯 TXT 命令不变。见导入指南。当前新建的文本项目采用新版格式,1.3 及更早版本无法读取,请先升级紫垣。

成稿导出:text export-originals 取回归档原件,text export-finished 将有效定稿与校验清单打包为 TAR。CLI 默认预览,Web 确认后下载;缺块或失效整批拒绝,不改变审批、不覆盖文件。Markdown 行内代码无法定位回填时明确拒绝,见导出指南。

选用参考译法:从译文记忆中主动选择参考,先预览完整参考外发文本,再确认初译或修订。默认不选;预览不发送,下诏只入队。Web 仅当前项目;所选原译文保存在事件簿,分享前须核对隐私与权利。详见选择、确认与重试及兼容边界。

术语表与双语检索:ziyuan text termbase export/import <项目ID> <文件.csv> 与 export-tbx/import-tbx 导出或合并本地术语与人物;CSV/TBX 都保存类别、范围、可用起点、读音、证据、关联术语、声线与称谓规则,旧八列 CSV 仍可读。ziyuan text concordance <项目ID> <原文片段> 按原文字面相似度查找本项目已有原译文对。

译稿版本与格式回填:保存草稿、准奏与定稿时自动写快照;ziyuan text version list|save|compare|compare-draft|prune 与 Web「译稿版本」面板可查看、对比现行译稿或人工草稿,并清理旧快照。ziyuan text import-docx/import-epub 会保留原件,export-docx/export-epub 按已定稿译稿回填文字,保留粗体、斜体、表格与图片。快照只是本地辅助材料,不批准、不外发。边界见文本项目指南。

翻译记忆、评论与字幕:ziyuan text tm ... 可按项目维护本地原译文记忆,text comment ... 记录审校评论;两者都不自动改稿、不批准。text import-srt/export-srt 导入或导出字幕文字,时间轴存于 srt.json。详见文本项目指南。

向导式新建:在资料面板点「向导式新建」,选择术语或人物,填好名称、译法或别名后添加;「临时关联」的人物和对象可多选,选中的标签可随时移除。

确定性检查:ziyuan text qa <项目ID> <块ID> 或 Web「确定性检查」只查空译、段号、数字、重复、术语/人物名等确定性问题;不调用模型,也不代表语义正确。

连续翻译与本地交付(1.14):完整译书工作区备份、原文追加/修订、跨章待查、连续通读、全文检索与草稿替换、纯文本 TMX 交换,以及保留注音/着重/叠加样式的 HTML 成稿入口见连续翻译指南。保存、采纳、问题处置与准奏定稿仍分别记录。

第一次启动(不用命令行)

  • Windows:解压发布包,双击 start-ziyuan.bat。
  • macOS / Linux:在解压目录运行 ./start-ziyuan.sh。
  • 脚本会初始化工作区、启动本地 Web、把登录令牌复制到剪贴板并打开浏览器;在登录框粘贴即可。
  • 关闭服务窗口(或结束 ziyuan serve 进程)即停止;数据保存在当前目录。

第一次建立译书项目(不用命令行)

  1. 打开译书页,点左侧「新建文本项目」。
  2. 填标题、原文语言、来源与权利声明;作者、版本、日期与使用范围可选。
  3. 建立后在同一页的「导入原文」选择 TXT/Markdown,调整章序,先预览,再确认导入。

来源与权利只是你的自述,软件不作核验;一个项目只能导入一次。

第一次使用本地资料(不用命令行)

  1. 打开译书页,点「读取本地资料」。
  2. 点「新增术语」或「新增人物」,填名称与译法;不确定的字段可以留空。
  3. 点「保存草稿」——保存不等于批准。
  4. 点「校验」,通过后点「准备生产资料」。
  5. 批准在译书操作区点「批准上下文」,或运行 ziyuan text context approve;准备本身不是批准。

本地资料与段旁提示

  • 译书页可保存独立的人物/术语资料草稿;未批准,不进入生产译文。
  • 在「临时关联」填写本段人物、称呼对象与说话人,点「刷新段旁提示」;段旁提示按当前关联显示术语、人物与称谓条件。
  • 「对比草稿与生产」只读列出新增/删除/改动;保存草稿不等于批准;「准备生产资料」将资料整理到 context/glossary.json,供翻译使用前仍需 ziyuan text context approve。
  • 复核可带关联:ziyuan text verification show <项目ID> <块ID> --associations <关联.json>。
  • 详见 N0 第 26 节。

词证与逐段勘校:词证是词义核对的出处和说明。CLI 和 Web 可按言行归属、事理正反、数目分寸、前后次第、称谓名分、谐趣留白六事逐段记录,保留历史;材料变化后须重新核对。结构通过、意见已处理、人工复核和御览定稿不能互相替代。说明与短例见勘校指南。

逐阶段用量账本:ziyuan text usage <项目ID> [--json] 只读查看初译、双路审校和修订的已报告用量。未报告就是未知,分币种估价不是账单。请求中省去较早的相同文件读取副本,保留最新全文,不改原始历史;词义核对、朱批与人工分批不削减。见账本与精简边界。没有新增付费小说复验,不承诺节费收益。

人工译稿(命令行、网页与终端):不调用模型,自己写译文,经保存、送审、准奏(同时落入正式译稿)、定稿后导出。网页可以逐段改译文,也能改注音、着重、粗体和斜体。终端「人工译稿」可以改段落文字;改过的那一段会去掉注音、着重、粗体和斜体。送审、准奏和定稿都要再按 y。用法见人工译稿。

本文中的“皇帝”指用户,“官员”指执行任务的智能体,“诏令”就是任务,“准奏”是批准写入文件。命令名称保持这些约定,不需要先熟悉官制才能使用。

奉天门:紫垣的 Web 界面

安装

可从 GitHub Releases 下载适合系统的压缩包,解压后运行其中的 ziyuan(Windows 为 ziyuan.exe)。Linux 预编译包需要 glibc 2.35 或更新版本。

也可以从源码安装,需要 Rust 1.89 或更新版本:

cargo install --git https://github.com/YuuUehara/Ziyuan ziyuan-cli --locked   # 安装 `ziyuan` 到 ~/.cargo/bin
cargo install --path crates/ziyuan-cli --locked                               # 或在本仓库中

正式发行版会通过标签触发的可信发布流程上传到 crates.io;首次发布须先手工完成,之后由发布作业自动跟进。是否可用、有哪些版本,以 crates.io 上显示的内容为准。若该版本尚未出现在 crates.io,请用上面的 cargo install --git 安装。

平台支持

平台 任务、审阅、GitHub 对接、Web/TUI 测试命令的隔离环境(“号舍”)
Linux 支持 bubblewrap(另装;按域名放行还要 socat)
macOS 支持 系统自带的 Seatbelt
Windows 支持 暂缺,默认拒绝运行需要隔离的命令。设 ZIYUAN_SANDBOX=off 会取消隔离,风险见 ADR-0001

快速开始

安装后,在一个独立目录试用。下面的命令可在 PowerShell 或常见 Linux/macOS shell 中逐行执行;使用已有目录时不要重新运行 mkdir。

mkdir ziyuan-demo
cd ziyuan-demo
ziyuan init
ziyuan court
ziyuan officials
ziyuan edict --dept works "概述当前目录的文件"
ziyuan tasks
ziyuan history

记录保存在当前目录的 .ziyuan/。未配置模型时,结果会注明只是演示;若已配置模型,上述任务会读取授权范围内的文件并产生模型费用。

想用图形界面,执行 ziyuan serve,再打开终端打印的本机地址。不要把带令牌的地址发给他人。终端界面用 ziyuan tui 启动。

接下来可按需要阅读:

  • 接入真实模型:设置模型名称、服务地址和密钥。
  • 让模型修改文件:授权后先看 ziyuan diff <任务ID>,确认后再 ziyuan apply <任务ID>。将占位的任务 ID 替换为实际数字,不要直接输入尖括号。
  • 权限与安全:哪些文件会交给模型,哪些操作需要你批准。

任务如何分配?

三种制度决定任务经过哪些角色。这些规则由程序执行,不是只在提示中要求模型遵守:

制度 仿照 路线 品级(尚书 / 侍郎 / 郎中)
丞相制 chancellor 元·中书省 皇帝 → 中书右丞相(左丞相署理)→ 本部尚书 → 郎中 正三品 / 正四品 / 从五品;右、左丞相正一品
废相亲政 direct 明初·洪武罢中书省 皇帝 → 本部尚书 → 郎中 正二品 / 正三品 / 正五品
内阁制 cabinet 明中后期 皇帝 → 内阁首辅(次辅署理)→ 本部尚书 → 郎中 正二品 / 正三品 / 正五品;首辅、次辅本官正五品
  • 正职空缺时由副职署理(丞相 → 左丞相,首辅 → 次辅,尚书 → 侍郎),路线中注明「署理」;正副俱缺则拒绝派工。
  • 改制会撤销旧制度协调机构(中书省/内阁)的全部官职,防止旧身份在改制后继续自动保有最高权力;六部官员保留,品级随制度变化。新制度需要明确任命协调者。
  • 开国时(#1–#10)设丞相一人,吏部、工部各有尚书与郎中,户、礼、兵、刑四部各有尚书(本部无郎中时尚书亲办),六部诏令都能承接;左都御史不设(设了常朝会自动复核、多花 token)。init 与 court 会列出缺位的官职及其影响(如左都御史空缺则无人复核),并由吏部荐举一位闲居、专长相符、考绩最优的官员;任命仍须皇帝确认(Web 朝堂可一键任命,经确认框)。
  • 官员姓名在开国与 recruit(不给姓名时)随机生成:百余个常见单姓与复姓,配以士大夫取名常用字,单名双名皆有,不与在册官员重名。姓名记入事件簿,重放不变。
  • officials、Web 与 TUI 显示每位官员的官职、品级与所用模型(ZIYUAN_LLM_MODEL;未设置时为演示后端)。

内阁制下诏令须先「票拟」再由皇帝「批红」,丞相制下丞相自行派工;详见内阁、皇权与昏君模式。

使用前需要知道

  1. 你决定权限和任免:模型不能靠一句话把自己变成用户;改制、任免必须通过程序提供的操作入口。
  2. 官员和官职不是一回事:官员换职后编号不变,便于追查同一执行者的记录。
  3. 改制不等于停止任务:改制调整分配路线,执行机制仍然保留;停止或撤销任务要用相应操作。
  4. 权限不能由模型自行扩大:模型可以提出建议,但不能自行授予新的系统权限。
  5. 演示后端不是代码分析:DemoBackend 只验证调度线路,绝不声称已完成真实分析。
  6. 记录保存在本地:.ziyuan/court.log 保存任务和操作记录,多个进程的写入会协调。.ziyuan/huidian 只是加快启动的缓存,损坏时会按记录重建。新版可读旧记录;旧版未必认识新事件,先用 ziyuan migrate 检查最低版本要求。

1.0 起的兼容承诺见稳定性约定。ChatGPT 订阅与 HTTP MCP 仍为实验性;内部 Rust 接口和 Web 页面不在兼容承诺范围内。

支持 recruit 动态扩充官员;同部门多个郎中按任务量均衡派工。择优任用通过 recommend 给出建议,由皇帝决定是否任命。

开发与发布

发布产品由十一个 crate 组成:core 定义任务与角色,governance 执行分配规则,runtime 执行模型与工具调用,llm 和 github 连接外部服务,storage 保存记录,memory 提供本地译文记忆索引与检索,app 提供各界面共用的功能,cli、web、tui 负责交互。工作区另有未发布的 sandbox-windows 独立启动探针,已通过 Server 2025 CI 基线的启动、身份、Job 与句柄检查,尚未完成文件/网络隔离验收,不接入生产;Windows 受保护执行仍失败关闭,见 ADR-0001。其余分层说明见体系结构。

在仓库根目录检查和构建:

cargo fmt --all -- --check
cargo check --workspace --all-targets --all-features
cargo test --workspace
cargo build --workspace
bash scripts/smoke.sh

最后一条需要 Bash 及脚本所需的运行环境。常规 CI 还检查 Rust 1.89、Linux glibc 2.35 基线,并在 macOS 和 Windows 上运行测试;具体流程见 .github/workflows/ci.yml。

推送与 Cargo.toml 版本一致的 v* 标签会触发发布:先建草稿,上传四个平台的包,再在对应平台重新下载验证,全部通过才公开;公开后按依赖顺序发布十一个 crate(含 memory,已存在的版本跳过)。可信发布配置与首次发布准备见发布指南,最终结果须分别核对下载包与 crates.io。说明取 CHANGELOG 中对应版本一节。crates.io 不能删除版本,只能 yank。Linux GNU 包在 Ubuntu 22.04 构建并检查 glibc 2.35 基线,不代表所有 Linux 发行版均经过验证。

文档

许可

本项目采用 MIT OR Apache-2.0 双许可证,你可以任选其一使用:

除非另有明确说明,你有意提交并被本项目接纳的贡献也将按上述双许可证授权。

Web 界面内置的 JetBrains Mono 字体按 SIL Open Font License 1.1 随附,许可证见 crates/ziyuan-web/src/fonts/JetBrainsMono-OFL.txt(发行包中为 JetBrainsMono-OFL.txt)。界面推荐的中文、日文字体也都是 OFL 1.1,不随程序附带,见使用指南 · 字体。

软件的 MIT / Apache-2.0 许可不授权第三方文学原文、译文或书库品牌;模型上传、再分发与商业出版仍须逐项核对权利,见小说翻译版权边界。