BibleSkill

把希伯来文旧约和希腊文新约译成中文的 AI 工作流：一组可公开的 skill，加一个基于开放数据（STEPBible、Macula、UBS 中文词典）的 MCP server。模型先做子句分析，再逐子句翻译，并检查用词统一；按需标出经文异文与解经争议（默认关闭，省 token）。译文贴近原文形式还是偏重意义分 5 档（逐字、直译、平衡、意义对等、意译），按工作目录设定，默认直译。同一份 skill 可在 Claude Code、Gemini CLI、agy（Google Antigravity CLI）、Codex 中使用，因此可以选用 Claude、Gemini、GPT 等模型。

工作流分四步，另有一个从修改历史学习的步骤：

1. analyze：把经文切分为子句并确定从属关系。Macula 句法树作为第二意见，不当作标准答案。

2. translate：按设定的档位逐子句翻译，同时给出实词的译法对照，并检查用词统一。

3. consistency：汇总一词多译、多词一译，把判定结果固化进术语表。

4. review：按当前子句分析与术语表复查已写入的译文，列出需要整节改译的范围和需要人工复核的子句。

5. learn：汇总人工修改历史，整理成术语偏好、个人风格和项目规则，经用户确认后写入；可以批量替换不一致的译词。

结果用脚本画成原文结构图（单文件交互 HTML）：主句、从句与修饰关系，附译文。

English summary. BibleSkill is an open-source AI workflow for translating the Hebrew Bible (Old Testament) and the Greek New Testament into Chinese. It ships agent skills (bible-analyze, bible-translate, bible-consistency, bible-review, bible-learn) and a Model Context Protocol (MCP) server built only from openly licensed data: STEPBible TAHOT/TAGNT, Clear Bible's Macula Hebrew/Greek syntax trees, and the UBS Chinese Hebrew and Greek dictionaries. The model first segments each passage into clauses, then translates clause by clause at one of five literalness levels (word-for-word, literal, balanced, dynamic equivalence, paraphrase), records a rendering for every content word, enforces a shared glossary, and, on request (off by default to save tokens), flags textual variants (NA28/UBS base text for the New Testament, Leningrad Codex with Qere for the Old Testament) and interpretive disputes with alternative renderings. The same skills run in Claude Code, Gemini CLI, Google Antigravity CLI (agy), and OpenAI Codex. Results are rendered by a script as an interactive source-text structure diagram (standalone HTML). MIT licensed.

数据来源

只使用开放许可的数据：

数据库由本地数据构建，不随仓库分发。署名见 NOTICE.md。

主干选择

• 新约：以最新的 NA/UBS 为主要参考，主干是 TAGNT 中版本列含 NA28 的词，共 137,954 词（UBS5 正文与 NA28 相同）；词行本身不属 NA28、NA28 的读法只记在异文列的 64 处（如徒 8:31 ὁδηγήσῃ），取 NA28 读法顶替进主干，词行本身的读法进异文表。NA28 双括号 [[ ]] 内的经文（可 16:8 短结尾和 16:9-20 长结尾、路 22:43-44、路 23:34a、约 7:53–8:11）在主干内，并带有标记；译文用 〚 〛 标出，开启争议时另列为异文争议。数据里的标点来自 THGNT，断句以 NA28/UBS 为准。

• 旧约：TAHOT 的 L（列宁格勒抄本）、Q（读型，Qere）、R（恢复文本）。写型（Ketiv）、LXX 补入文本（X）以及插入的补文进异文表。

• 分段（可选）：新约可以按 UBS5 等原文版本分段、加小标题，见下文“新约分段与小标题”。没有分段数据时，分段与小标题由模型自拟。

• 节号：用英文（NRSV）节号体系，与和合本基本一致。原文节号保留在 ref 列，用于对齐 Macula。

• 词 id：定宽格式。旧约为 o + 书(2) 章(3) 节(3) 词(3) 语素(1)，新约为 n + 书(2) 章(3) 节(3) 词(3)，字典序即词序。格式与 Macula 相同，但编号不同；Macula 的 id 只出现在映射表里。

Related MCP server: bible-translation-mcp

安装

需要 Node ≥ 22.13（使用内置 node:sqlite）和 pnpm。

# 1. 取得数据（放在任意位置）
git clone https://github.com/STEPBible/STEPBible-Data
git clone https://github.com/Clear-Bible/macula-hebrew
git clone https://github.com/Clear-Bible/macula-greek
git clone https://github.com/ubsicap/ubs-open-license

# 2. 构建
pnpm install
pnpm build
pnpm data:build --step ../STEPBible-Data --macula-hebrew ../macula-hebrew \
  --macula-greek ../macula-greek --ubs ../ubs-open-license
# 约 30 秒；输出各约映射率与 build_report 统计
# 可选：--critical-text data/critical-text.json（见“扩展 MCP”）、--paragraphs data/paragraphs.json（见“新约分段与小标题”）
# 数据库表结构升级后，旧库会被拒绝打开，重新运行这一步即可

# 3. 安装到一个翻译工作目录
./scripts/install.sh ~/圣经翻译

install.sh 写入以下内容：

个人风格与术语偏好：install.sh --style <style.md> --terms <terms.yaml> 拷进工作目录。不传时，如果 ~/.config/bibleskill/style.md、~/.config/bibleskill/terms.yaml 存在、而工作目录里还没有，就自动拷入；工作目录里已有的不覆盖。

agy 无头模式（agy -p）不能弹出权限确认。需要在 ~/.gemini/antigravity-cli/settings.json 的 permissions.allow 里加入 mcp(bibleskill/<工具名>)，工具名见下表。

翻译档位

在工作目录的 style.md 里用 frontmatter 选项 literalness 设定档位（不写时为 2）：

---
literalness: 4   # 1 逐字 / 2 直译 / 3 平衡 / 4 意义对等 / 5 意译
---
（下面是个人风格正文，可以不写）

各档通用：依据原文、不照搬其他译本、开启争议时争议必须标出、每个实词都要给 rendering（第 4、5 档可以用 首-末 区间对应整个短语）、locked 术语必须照用。各档的细则见 prompts/literalness.md。briefing 的 approach 把当前档位告诉模型。

一个工作目录用一个档位。想要另一档的译本，另开一个工作目录。中途换档位时，已译的经文不会被改写：每条译文记下写入时的档位（literalness），审校按各自的档位复查，并在 otherLevel 里列出与当前档位不同的节。clauseOrder（后置状语从句合并前置还是保留原文语序）只在第 2、3 档起作用；第 1 档固定保留原文语序，第 4、5 档固定按中文语序。

使用

在工作目录里启动任一 CLI：

/bible-analyze 创 1:1-5
/bible-translate 创 1:1-5
/bible-consistency 创世记
/bible-review 创世记
/bible-learn 创世记

查看结果（原文结构图）：

pnpm run view 徒 7:17-18 --workdir ~/圣经翻译 --diagram ~/圣经翻译/图示/徒7-17-18.html

原文结构图

pnpm run view <范围> --workdir <目录> --diagram <文件>.html 按子句分析画一张可交互的结构图（单文件 HTML，惯例写到工作目录的 图示/；各图共用旁边的 diagram.css、diagram.js，每次生成都重写，已有的图刷新即用新版）：

• 层级：每个子句一行，按原文先后自上而下，缩进表示从属；框头标子句编号，「详情」在框的右上角，下面一行是译文。只有一个说话动词的引语框架（εἰπόντες、λέγων、לֵאמֹר）不单占一行，放在母句那一行的行尾（旧约在左侧）；只有一个 הָיָה 的过渡句（וַיְהִי、וְהָיָה）引出的第一个从句，也排在它那一行的行尾。

• 连线：从从句出发，走在缩进留出的沟槽里，箭头伸进母句框，指到被修饰的词（加下划线）；逻辑关系与句法不同时另画虚线。

• 嵌入：夹在一个子句中间的从句（分析里范围落在外层子句之内）单独成框，外层只列自己的词，嵌入处显示占位符（如 ⟨38b⟩），连线指到占位符；点占位符跳到那个子句。

• 成分：每个句子成分一块。主语、谓语取自分析的 subjectRange、verbRange，句首连词按词法认出；其余的词照 Macula 短语树分成宾语、间接宾语、状语、表语等（子句切分仍以分析为准）。块太长时折行，排得下就不断；要断时同一级的断点一起断。旧约只看停顿重音（atnach ＞ zaqef ＞ tipcha ＞ revia ＞ pashta 等，按整个重音单位算，maqqef 后不断），不用分析里的 br，希伯来文的介词短语按状语显示；新约按短语树，并列的 καί 前最先断，其次是嵌入的分词短语、关系从句（连同冠词）前后，断开的嵌入部分缩进。

• 格与时态（新约）：主格加粗，宾格蓝、属格绿、与格紫、呼格橙；动词按时态加框（不定过去黑、现在蓝、未完成紫红、将来绿、完成红），按语气加底色（直说米色、祈使红、虚拟紫、祈愿绿）。

• 主线：旧约方框边框按谓语动词形式着色（wayyiqtol 等）；新约方框不着色，框头标出谓语的时态与语气。旧约叙事与新约叙事书卷（福音书、使徒行传、启示录）的顶层主句用最外侧的竖线串起来，不是主线形式的（旧约不用 wayyiqtol，新约不用不定过去式直说语气）标「离线」，不接到主线竖线上；同一说话动词下的各句汇成一条主干，是会话序列。书信暂不画主线。

• 交互：点框头展开逐词词义与“分析与翻译记录”（分析备注、另一种分析、译注、其他译法、异文，自动列出）；点词弹出词卡（词法、本处译法、UBS 中文词典、STEPBible 简明词典）；可切换词法、英文、成分名（只留色条）、明暗。

子句功能按挂接关系取默认值：顶层为“主句”、修饰名词的为“定语从句”，连线标“修饰“…””，框头的大意取该子句的译文。

按设定的模型跑分析与翻译

子句分析和翻译可以交给不同的模型。默认分析用 agy 的 Gemini 4 Argon（找争议最全），翻译用 Claude Code 的 Opus（译文最好）：

pnpm passage 创 30:32-33 --workdir ~/圣经翻译                      # 先分析再翻译
pnpm passage 创 30:32-33 --workdir ~/圣经翻译 --step translate     # 只翻译
pnpm passage 创 30:32-33 --workdir ~/圣经翻译 --translate claude:opus@high   # 本次临时换模型

模型写在工作目录 config.json 的 models 里，写法 claude:<模型>[@思考级别] 或 agy:<模型>（agy 的思考级别含在模型名里，见 agy models）：

{ "models": { "analyze": "agy:gemini-4-argon-medium", "translate": "claude:opus" } }

安装时用 install.sh --analyze-model <写法> --translate-model <写法> 设定；不给时沿用已有设定，或取 ~/.config/bibleskill/models.json，再没有就用上面的默认。agy 默认带 --dangerously-skip-permissions 运行（无头模式不能弹权限确认）；已在 agy 设置里放行 bibleskill 工具的，可加 --no-skip-permissions。

在 CLI 里直接 /bible-translate 而经文还没有分析时，模型会说明设定的分析模型和命令，问你是去跑那个模型，还是由它直接分析。

在 agy 下跑端到端测试

cd ~/圣经翻译
printf '%s' '/bible-analyze 创 1:1-3' > /tmp/p.txt
AGY_MODEL="Gemini 3.8 Flash (Medium)" AGY_PROMPT_FILE=/tmp/p.txt AGY_IDLE=120 AGY_HARD=900 \
  python3 /path/to/BibleSkill/scripts/agy-pty.py

agy -p 在管道下不输出、在 pty 里也不会自己退出，所以用 scripts/agy-pty.py 包装。

MCP 工具

入参都用 range（如 创 1:1-5、John 3），schema 写得宽松，校验在工具内部进行：校验失败作为工具错误返回，模型能照着改。

存储

只读数据库 data/bible.sqlite

表结构见 packages/core/src/db-schema.ts：

工作目录

config.json                        数据库路径
glossary.json                      术语表 {strong, senseKey, lemma, zh, level: locked|preferred, note, scope}
rules.json                         分析/翻译规则 {id, task, pattern, resolution, examples}（手工维护，或由 bible-learn 写入）
style.md                           翻译档位与个人风格：Markdown，可带 frontmatter 选项（literalness: 1-5，clauseOrder: fluent|source，disputes: off|on）
terms.yaml                         术语偏好 [{lemma, strong?, senseKey?, zh, avoid?, note?}]，可写注释
<中文书名>/chNN/clause_entities.json  子句分析
<中文书名>/chNN/clauses.json          译文
图示/                               结构图 HTML
<中文书名>/chNN/history.jsonl         译文修改历史 {bcv, sub, at, origin: ai|human|replace|import, before, after}

clause_entities.json（ClauseEntity）与 clauses.json（ClauseText）的字段保持稳定，新功能只追加字段：

• 子句：status（accepted / ambiguous / needs-review）、alternatives（其他切法与依据）、seedDiff、sources、note

• 译文：renderings（每条可带 at：译词在本行译文中的位置，存盘时自动定位）、alternatives（其他译法 {text, kind, basis}）、sources、literalness（写入时的档位，旧数据没有，按 2 算）

• formatted 是 TranslationSegment[]（{text, styleName?, note?}）的 JSON 字符串。补出的词单独成段，styleName: "added"，text 不带括号，note 是补词的说明；主译的取舍理由在最后一个普通段的 note 上。模型提交时仍在 text 里写 [ ]、用 supplied: [{text, note}] 写补词说明，由系统拆成段；briefing、文本视图里再拼回 [ ]。renderings 的 zh、at 按不带括号的纯文本计算。HTML 视图和结构图里补词加点状下划线（不带括号），悬停可看补词说明。

  旧版本把 [ ] 直接写在正文里。转换成补词段（文字不变，对齐位置随之调整，不记修改历史）：

  pnpm migrate:segments --workdir ~/圣经翻译 [--dry-run]

  review_report 会在 legacy 里列出还没转换的节。

两个文件都有 version 字段，按节整体替换，写入是原子的（先写临时文件再 rename）。

用词统一

• 归并键：senseKey = 扩展 Strong + Macula 义项（旧约 SDBH，新约 Louw-Nida）。扩展 Strong 已经区分同形词和专名个体。

• 译法对照：提交译文时，每个实词（名词、动词、形容词）都要给出 renderings。这些对照构成译法记忆，不另外落盘，扫描工作目录实时汇总。它们同时就是词级对齐：zh 在译文里出现不止一处、或落在别的译词里（「地」在「大地」里）时，存盘时按「给定的 at → 长词优先 → 词序」定到具体位置，视图据此做原文与译文的双向高亮。

• 提交检查：

  • 违反 locked 术语 → 拒绝该节。

  • 偏离 preferred 术语或既有主导译法、又没写 note → 拒绝该节，并列出既有译法（第 4、5 档只列出，不拒绝）。

  • 写了理由 → 放行。

• 用词审校：consistency_report 列出一词多译和多词一译，供 bible-consistency skill 判定后写入术语表。

审校

提交时的检查只在提交那一刻生效。之后术语表改了，或者重新做了子句分析，已写入的译文不会自动复查。review_report 会把已存的译文还原成提交格式，按当前数据重跑提交检查：

报告给出两份清单：retranslate 把需要改译的节合并成连续范围（如 创世记 1:3-5），可以直接交给 bible-translate；humanReview 列出 needs-review 子句（开启争议时另有 ambiguous），交人工复核。bible-review skill 按这份报告逐段重译，最后再跑一次确认清零。upsert_glossary 返回时会提示跑审校；重新分析已有译文的节时，submit_clause_analysis 会在 translatedVerses 里提醒。

个人风格、术语偏好与修改历史

• 个人风格（style.md）进入 analyze、translate briefing 和审校报告的 style 字段。它是偏好级：原文两种译法都成立时才采用，与当前档位的原则、术语表冲突时以原则为准（档位 literalness 本身不是偏好，必须遵守）；审校不会因为风格不符要求重译。frontmatter 的 clauseOrder 控制后置状语从句是合并前置（fluent，默认）还是保留原文语序（source）。

• 术语偏好（terms.yaml）在 translate briefing 的 terms[].preference 里提示，只对还没有术语表条目的词生效；consistency_report 的 preferenceConflicts 列出与偏好不同的现有译法。要强制统一，把它写成术语表的 preferred。

• 修改历史：每次写入译文，变化了的子句都把改前改后追加到该章的 history.jsonl，origin 区分 AI 提交（ai）、视图里的人工编辑（human）、批量替换（replace）和导入（import）。别处的修改历史可以导入：

  pnpm revisions import 历史.jsonl --workdir ~/圣经翻译
  # 每行 {"ref": "撒上 5:8", "before": "改前文本", "after": "改后文本"}，也可以用 bcv、sub、time

  revision_report 对工具写入的历史按原文义项列出“从 A 改成 B”，对导入的纯文本历史按字符 diff 归并替换片段；bible-learn skill 据此分类，经用户确认后写入 terms.yaml、style.md、rules.json。

• 批量替换：replace_rendering 按 strong 或 senseKey 把某个译法换成另一个，同时改写译文文本与对齐位置；默认只预览。

争议处理

异文与解经争议默认不处理，省 token：briefing 不带异文与歧义线索，模型不标 ambiguous、不列争议读法，提交和审校也不查。需要时有两种开法：

• 单次：在请求里说要标出异文或争议（如“翻译 约 1:1-5，带争议”），skill 会给 briefing、提交和审校都传 disputes: true；pnpm passage 用 --disputes。

• 持久：在 style.md 的 frontmatter 写 disputes: on。

开启后，争议尽量标出，主译之外并列其他译法，各自写依据（规则见 prompts/disputes.md）：

• 系统已知的争议会出现在 briefing 的 disputes 里，必须处理：

  • 影响翻译的经文异文：STEPBible 用大写标出，如 TAGNT 的 T= 异文、TAHOT 中意义不同的 Ketiv/Qere，以及只见于其他版本的整段（如约一 5:7）。处理方式是给出 kind: textual 的其他译法，或在 note 里说明为何不影响译文。

  • 子句分析里标为 ambiguous 的结构争议：必须给出其他译法，并在 note 里写明主译为什么这样取舍。

• 其他争议由模型主动标出，分为断句、句法、词义几类，规则文档里给了常见例子。

• 主语检查：以 Macula 句法树的主语标注为证据，漏标主语、把表语当成主语、把主语切到别的子句里，都会被拒绝。模型可以写理由推翻 Macula 的判断，但该子句会被标为 needs-review，交人工复核。

• 视图：结构图点开子句，在“分析与翻译记录”里列出其他译法、各自的依据和主译的取舍理由。

扩展 MCP

skill 不依赖任何私有数据。私有扩展用 install.sh --ext <ext.json> 安装（不传时自动读取 ~/.config/bibleskill/ext.json），格式同 .mcp.json。每个扩展分到隔离目录 <workdir>/.ext/<名字>/，配置里的 ${EXT_DIR} 会替换成这个目录：如果扩展自带写工作文件的工具，就让它写到这里。

新约断句以 NA28/UBS 为准。ext.json 里可以用顶层字段 "criticalText": {"server", "tool", "args"} 声明哪个扩展工具能取 NA28 原文。声明后，新约 briefing 会点名让模型调用这个工具，按 NA28 断句；开启争议时还把校勘符号（⸀ ⸂⸃ ⸋⸌ ˸ 等）当作争议线索。没有扩展的用户不受影响：模型按自己对 NA28/UBS 断句的了解判断。

声明了 criticalText 时，数据库的新约正文也可以按 NA28 挑词。TAGNT 版本列里的“NA28”并不总是 NA28：马可福音、使徒行传等卷跟的是 ECM（徒 9:8 οὐδένα、可 1:2 ἐγώ），NA28 单括号里的词也常不算（徒 9:12 [ἐν ὁράματι]）。先用 node scripts/fetch-critical-text.mjs 逐章取 NA28 原文，存到 data/critical-text.json（受版权保护，已在 .gitignore 里，只留在本机），再在 pnpm data:build 后面加 --critical-text data/critical-text.json。构建时逐节拿 NA28 对 TAGNT 的词行（本行读法或异文列里的读法），改挑对得上的行进主干；NA28 原文本身不写进数据库。本节有词对不上，或者 NA28 把八个版本都有的词算在邻节（分节不同）时，这一节照 TAGNT。改了哪些节记在 build_report（nt-critical-text、nt-critical-unmatched）。扩展里用不到的工具（写入、校验、扩展自己的工作流）可以列在 "hideTools": {"<服务器>": [工具名…]} 里，不放进模型上下文，省 token：agy 写成 disabledTools，Gemini 写成 excludeTools，pnpm passage 调 Claude Code 时转成 --disallowedTools。--no-ext 可以跳过自动读取扩展配置。如果环境里有其他 MCP 工具提供学术词典、注释书、交叉引用、引语层级、语法书检索等能力，skill 会用它们辅助判断，并在 sources 中记为 ext:<能力>。工作文件里只写结论，不写入受版权保护的原文。

新约分段与小标题

译文的段落与小标题记在段首子句的 paraTitle 上（null 不是段首，"[]" 是段首但没有小标题），段首可以在一节中间。结构图的页首原文与译文按段落排，带小标题；结构图里段首子句的方框上方也显示小标题。

构建时加 --paragraphs <文件>，新约就按文件里的分段（如 UBS5）定段首。文件受版权保护的话只留在本机（data/paragraphs.json 已在 .gitignore 里），需自备，格式：

{ "source": "UBS5",
  "breaks": [
    { "book": 44, "chapter": 8, "verse": 1, "letters": 0 },
    { "book": 44, "chapter": 8, "verse": 1, "letters": 36, "heading": "Saul Persecutes the Church" } ] }

book 是新教 66 卷序号，chapter、verse 用原文节号；letters 是本节在分段处之前的字母数（NFD 分解后只数字母，不计重音、标点、空格），0 即节首；heading 是段前的小标题，没有就省略。构建时按字母数落到主干词上，对不上的记进 build_report（paragraph-unmatched）。

有分段数据时：

• 分析 briefing 的 paragraphStarts 列出节中的段首词，段首词必须开新子句，否则该节被退回。

• 翻译 briefing 里段首子句带 paragraph（含英文小标题）。模型把小标题译成中文写进 paraTitle，专名、术语照本段译文；段首由系统设定，模型不能增删。

• 审校列出分段、小标题与数据不符的节，以及段首词落在子句中间、需要重做分析的节。

没有分段数据（旧约，或构建时没给 --paragraphs）时，paraTitle 照旧可选，由模型在自然段开头给出。两种情况都要求：段首前一子句的译文以句末标点收住，段首不并进前一子句。

常见问题

BibleSkill 是什么？ 一个开源的圣经原文中文翻译工作流。它让 AI 模型按“子句分析 → 逐子句翻译 → 用词统一 → 审校”的步骤，把希伯来文旧约和希腊文新约译成中文，每一步的结果都写进工作目录，可以人工复核和修改。

用的是什么原文底本？ 新约以 NA28/UBS5 为准（取 STEPBible TAGNT 中 NA28 的词），旧约用列宁格勒抄本（TAHOT 的 L，并按读型 Qere 读）。异文另存，开启争议时影响翻译的会作为争议列出。详见“主干选择”。

支持哪些 AI 模型和工具？ 同一份 skill 可在 Claude Code、Gemini CLI、agy（Google Antigravity CLI）和 Codex 中使用，因此可以选用 Claude、Gemini、GPT 等模型；子句分析和翻译还可以分别交给不同的模型。

是不是照抄和合本或其他现成译本？ 不是。原则是依据原文翻译、不照搬其他译本；节号沿用英文（NRSV）体系，与和合本基本一致，只为方便对照。

直译还是意译？ 可以选。档位分 5 级：逐字、直译、平衡、意义对等、意译，默认直译。一个工作目录用一个档位。

原文数据从哪里来，能否商用？ 只用开放许可的数据：STEPBible-Data 与 Macula 为 CC BY 4.0，UBS 中文词典为 CC BY-SA 4.0。数据库在本地构建，不随仓库分发；使用时请保留 NOTICE.md 中的署名。代码为 MIT 许可。

需要联网或付费数据吗？ MCP server 和数据库都在本地运行，不依赖任何私有或付费数据。翻译时调用的模型取决于你使用的 CLI。

开发

pnpm build && pnpm test        # 单元测试（校验器、档位、补词分段、审校、迁移、引用解析、句型换算、对齐定位、结构图）
pnpm verify:passage            # 用真实 MCP client 在临时目录走一遍完整流程

二期

• 新约引用旧约的译法对照