unfoldingword/bp-assistant

BP Assistant — Zulip机器人

Zulip机器人，用于协调AI辅助创建unfoldingWord Book Packages。监控Zulip频道和私信，通过正则表达式+NLU fallback匹配消息路由，并调度至Claude SDK管道生成圣经翻译内容。

配套仓库： https://github.com/unfoldingWord/bp-assistant-skills — 驱动翻译管道的Claude Code技能和参考数据。

前提条件

• Docker及Docker Compose
• 拥有机器人账号的Zulip组织
• Door43/Gitea账号及API令牌
• Anthropic API密钥（用于Haiku NLU意图分类器）
• Claude Code CLI认证（用于Agent SDK管道）

快速开始

Docker（推荐）

bash
# 1. 并排克隆两个仓库：
#    /srv/bot/app/        （本仓库）
#    /srv/bot/workspace/  （bp-assistant-skills）
#    /srv/bot/config/     （密钥+环境变量，见下文）

# 2. 创建配置目录和密钥
mkdir -p /srv/bot/config/secrets
cp .env.example /srv/bot/config/.env
# 编辑.env并填充所有值

# 创建密钥文件（每个文件一个值，无尾随换行）：
echo -n "你的令牌" > /srv/bot/config/secrets/door43_token
echo -n "你的用户名" > /srv/bot/config/secrets/door43_username
echo -n "你的密钥" > /srv/bot/config/secrets/zulip_api_key
echo -n "你的邮箱" > /srv/bot/config/secrets/zulip_email

# 3. 创建外部Docker资源
docker volume create bot_claude-config
docker network create work-net   # 若未存在则创建

# 4. 构建并运行
docker compose up -d
docker logs zulip-bot --tail 30 -f

主机Cron自动化

主机端自动化现在位于独立的bp-assistant-auto-issue-handler仓库。本应用仓库不再管理cron脚本或主机cron配置。

本地开发

bash
cp .env.example .env
# 填写凭证
npm install
npm start

你应看到：

[bot] 以user@org.org身份认证（id: ...）
[bot] 注册流队列"CONTENT - UR"
[bot] 注册私信队列
[bot] 监控主题：Psalms BP、AI Work、Workflow、...
[bot] 监听消息中...

监控内容

在config.json中配置：

• 频道： CONTENT - UR
• 主题： Psalms BP、AI Work、Workflow、BP Proofreading、Proofreading Queue、Jeremiah BP、Habakkuk BP、Bot testing
• 私信： 仅管理员（在config.local.json中配置）

其他频道/主题的消息将被忽略。发送给自己的消息始终被忽略（避免回声循环）。

授权

• config.local.json（git忽略）包含adminUserId和authorizedUserIds
• 未授权用户在流中@提及将收到固定回复
• 仅管理员可私信机器人
• 所有流命令需@提及+确认后执行

路由工作原理

当有人在监控主题发布消息（或私信你）时，机器人从上到下检查config.json路由，第一个正则匹配生效。若无匹配，Haiku NLU fallback（intent-classifier.js）将自然语言请求分类为generate / notes / editor-review / editor-note / unknown，Unknown发送帮助消息。

当前路由

确认流程

所有流命令执行前会显示带令牌/时间估计的确认消息：

我将为PSA 79生成初始内容（ULT & UST、问题草稿）。是否确认？（yes/no）

用户需回复yes（或y、yep、go ahead等变体）继续，no取消。

多轮交互会话

管理员私信和editor-review频道命令通过session-store.js（文件存储于data/sessions/）维护跨消息的会话状态：

• /reset或reset conversation清除会话
• switch to sonnet/haiku/opus中途切换模型
• 消息前缀O:、S:或H:表示回复模型
• 流会话在maxExchanges后自动清除（editor-review默认6次）

管道类型

sdk（generate-content）

使用Claude Agent SDK query()运行/workspace中的技能。generate-pipeline.js模块：

1. 为每章运行initial-pipeline --lite（ULT + issues + UST）
2. 运行align-all-parallel对齐ULT和UST
3. 通过确定性JS代码（door43-push.js）推送至Door43
4. 通过Gitea API验证推送（repo-verify.js）

notes（write-notes）

notes-pipeline.js模块为每章运行技能链：

1. post-edit-review或deep-issue-id（协调/发现问题）
2. 问题归一化（并行限制、去重）via issue-normalizer.js
3. Node.js机械预处理（准备笔记、填充希伯来语orig_quotes、解析GL quotes、标记窄引号）— 在tn-writer前运行，避免Claude重复工具调用
4. tn-writer（从问题生成笔记）
5. Node.js质量机械预处理（修复尾随换行、运行所有机械质量检查）— 在tn-quality-check前运行，让Claude读取预运行结果
6. tn-quality-check（语义审查+一次修复）
7. Door43推送+验证

editor-note

向data/editor-notes/BOOK.md追加观察，通过note-pipeline.js完成简单文件追加操作。

interactive-dm

通过SDK resume实现多轮Claude会话，用于editor-review和管理员私信，详见上文“多轮交互会话”。

Door43集成

内容通过确定性JS代码推送至Door43/Gitea仓库 — Claude不参与推送本身：

• door43-push.js/door43-push-cli.js — Git操作+Gitea API PR创建
• repo-verify.js — 查询Gitea API确认PR合并至master
• door43-users.json（git忽略）— 映射***至Door43用户名
• 需要DOOR43_TOKEN（或GITEA_TOKEN）环境变量用于Gitea API访问，以及DOOR43_USERNAME（或GITEA_USERNAME）用于提交归因

MCP服务器

机器人在3001端口运行MCP（Model Context Protocol）服务器，向Claude管道执行期间暴露圣经翻译参考数据和USFM处理工具。关键工具包括：

• 参考数据： Strong's concordance、术语表、问题类型、已发布翻译
• USFM处理： create_aligned_usfm（JSON→对齐USFM）、merge_aligned_usfm（合并N个部分文件为一章）、read_usfm_chapter、curly_quotes、check_ust_passives
• TN处理： prepare_notes、fill_orig_quotes、resolve_gl_quotes、flag_narrow_quotes、fill_tsv_ids、assemble_notes、fix_trailing_newlines
• 质量： validate_tn_tsv、check_tn_quality
• 索引构建： build_strongs_index、build_tn_index、build_ust_index

服务器随机器人自动启动，工具实现位于src/workspace-tools/。

用法跟踪

每个SDK调用写入data/metrics/usage.jsonl。预检结合ccusage（CLI/桌面用法）与机器人JSONL日志，估算5小时令牌窗口的剩余空间：

• 遇到速率限制时自动校准预算
• 基于章节的超时缩放：章节数 x 操作数 x 5min/操作，限制10-60分钟
• 章节数来自verse-counts.js

引导成本估算（来自101+次观察运行）位于src/usage-tracker.js（BOOTSTRAP_DEFAULTS），estimateTokens()函数随数据积累融合引导值与观察中位数。

环境变量与密钥

Docker中，凭证从Docker密钥（挂载于/run/secrets/的文件）加载，.env提供非密钥配置。

.env（非密钥配置）

Docker密钥

本地开发无Docker时，直接在.env中设置这些值（见.env.example）。

文件结构

.env.example                <- 本地开发模板
config.json                 <- 频道、主题、路由、用法跟踪配置
config.local.json           <- 管理员/授权用户ID（git忽略）
door43-users.json           <- 邮箱到Door43用户名映射（git忽略）
Dockerfile                  <- 多阶段：node:22-slim构建 → Chainguard distroless运行时
docker-compose.yml          <- 挂载workspace、config、data；使用Docker密钥
package.json                <- 依赖：claude-agent-sdk、anthropic、zulip-js

src/
  index.js                  <- 事件循环：认证、轮询Zulip事件、过滤、调用路由
  router.js                 <- 路由匹配、确认流程、待合并项、Haiku fallback
  config.js                 <- 合并config.json + config.local.json
  secrets.js                <- Docker密钥加载器（读取/run/secrets/*文件）
  pipeline-runner.js        <- 调度器：sdk / notes / editor-note / interactive-dm
  pipeline-context.js       <- 共享管道上下文（书籍、章节、配置）
  pipeline-checkpoints.js   <- 管道恢复的检查点保存/恢复
  issue-normalizer.js       <- 问题TSV的并行限制和去重
  check-ult-edits.js        <- 检测人工ULT编辑（用于post-edit-review gate）
  claude-runner.js          <- SDK query()包装器，含超时、中止、 metrics钩子
  generate-pipeline.js      <- ULT+UST生成 + 对齐 + Door43推送
  notes-pipeline.js         <- TN技能链（issue-id → tn-writer → quality-check）+ Door43推送
  note-pipeline.js          <- 编辑笔记归档（追加至data/editor-notes/BOOK.md）
  interactive-dm-pipeline.js <- 多轮Claude会话（管理员私信+流会话）
  insertion-resume.js       <- 恢复中断的repo-insert操作
  intent-classifier.js      <- 自然语言命令的Haiku NLU fallback
  mcp-server.js             <- 暴露圣经翻译数据的MCP服务器（3001端口）
  usage-tracker.js          <- JSONL metrics、令牌估算、预检、ccusage
  door43-push.js            <- 确定性Git+Gitea API推送（isomorphic-git）
  door43-push-cli.js        <- door43-push的CLI包装器
  repo-verify.js            <- Gitea API验证PR合并至master
  session-store.js          <- 文件存储的Claude会话持久化
  auth-refresh.js           <- 主动OAuth令牌刷新（8小时令牌，30分钟余量）
  pending-merges.js         <- 文件存储的待合并状态
  zulip-client.js           <- Zulip API包装器（发送、私信、反应、文件上传）
  pipeline-utils.js         <- 书籍名称归一化、输出文件解析、超时
  verse-counts.js           <- 超时/估算计算的章节数查询

data/
  metrics/usage.jsonl       <- 令牌使用日志（自动创建）
  sessions/                 <- 多轮会话状态（自动创建）
  editor-notes/             <- 归档的编辑观察（自动创建）

配置参考

jsonc
{
  "adminUserId": null,            // 在config.local.json中设置
  "authorizedUserIds": [],        // 在config.local.json中设置
  "channel": "CONTENT - UR",      // 监控的流
  "topics": ["Topic A", ...],     // 仅这些主题（精确匹配）
  "watchDMs": true,               // 监控私信（仅管理员）
  "routes": [                     // 从上到下检查，第一个匹配生效
    {
      "name": "route-name",       // 日志标签
      "match": "/regex/i",        // 触发模式
      "type": "sdk|notes|editor-note|interactive-dm",
      "reply": true,              // 是否回帖至Zulip？
      "confirmMessage": "...",    // 执行前显示（支持$1、$2捕获）
      "operations": 3,            // 超时计算用（章节数