rebar

rebar

为 Agent 集群打造的事件溯源、由 git 支持的工单存储库与 Jira 协调器——一个存储库，可通过 Python 库、CLI 和 MCP 服务使用。

• 三个入口，一个存储库——可通过 CLI（rebar）、Python 库（import rebar）或 MCP 服务（rebar-mcp）使用 rebar。
• 跟踪器就在仓库中——工单以仅追加的事件日志形式存储在 tickets git 分支上；无需数据库或守护进程，并且会随每次克隆一同带走。
• 为并行 Agent 打造——原子化认领、收敛式合并和溯源链接，让多个 Agent 和会话可以同时写入，避免工作丢失。
• 可选的大模型关卡——在开始工作前审查工单的计划，在关闭工单前审查其完成情况，并在合并前审查其代码。
• 双向 Jira 同步——电平触发的协调器使工单与 Jira 保持同步，让团队成员及时了解进展。
• 经过两道独立关卡的实际验证——对 rebar 自身 main 分支的每项更改，都必须在 Gerrit 上通过大模型代码审查和 CI，才能合并。

安装

pipx install nava-rebar          # the `rebar` CLI (add [mcp] / [agents] for those extras)
brew install navapbc/rebar/rebar # or via Homebrew

快速入门

使用 CLI 或 Python 库端到端处理一个工单；JSON 代码块是 MCP 服务配置，Agent 可通过 MCP 执行相同的循环。rebar --help（以及 rebar <command> --help）是权威的命令参考。

# CLI: one ticket through init -> create -> ready -> claim -> close
rebar init
tid=$(rebar create task "Add a login page" -o json | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')
rebar ready                                              # lists it as ready to work
rebar claim "$tid"                                       # open -> in_progress
rebar transition "$tid" in_progress closed              # in_progress -> closed

import rebar                                            # the same loop via the Python library
tid = rebar.create_ticket("task", "Add a login page")
rebar.claim(tid)
rebar.transition(tid, "in_progress", "closed")

{ "mcpServers": { "rebar": { "command": "uvx", "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"] } } }

整个循环就是这样——init → create → ready → claim → close。CLI 和 Python 代码块各自端到端处理一个工单（每一步都使用同一个 ID，不使用硬编码 ID）；JSON 是 MCP 服务配置——将其添加到客户端，Agent 就能通过 MCP 工具执行相同的循环。状态通过仓库共享，因此多个 Agent（以及通过 Jira 协作的团队成员）可以协调工作，互不干扰。

工作原理

rebar 将工单存储为专用 tickets git 孤儿分支上的仅追加事件日志（工作树位于 .tickets-tracker/）；工单状态通过重放事件计算得出，每次写入都会自动提交并推送，因此存储内容会立即共享。电平触发的协调器会双向同步工单与 Jira。分支名称和工作树目录可配置（tracker.branch / tracker.dir——请参阅配置）。数千个工单规模下，读取耗时仍不到一秒；测量数据和 git 增长预期请参阅docs/scale-envelope.md。

文档位于docs/下——可从文档索引（按受众分类：用户 / 运维人员 / 贡献者 / Agent）或日常使用的用户指南开始。

为什么选择 rebar

如果你用编码 Agent 处理代码仓库，迟早会想同时运行多个 Agent——而一旦这么做，就需要一个共享空间来协调。大多数跟踪工具都不是为此设计的：

• 它们很笨重。 需要看管守护进程或持续运行本地数据库，依赖项也多到常规升级都可能导致你在不同机器上的工作跟踪出问题。
• 它们无法随代码一起迁移。 状态存储在代码仓库之外，因此新克隆的仓库不包含对应的工单。
• 它们会干扰 Git 历史。 会写入工作分支的跟踪工具，会把工单变更混入源代码提交。
• 它们没有并发处理方案。 没有任何机制能阻止两个 Agent 认领同一项工作或覆盖彼此的状态，并发编辑还会产生只能手动解决——或直接丢失——的合并冲突。
• 它们难以扩展。 工单超过几百条后，速度和易用性都会下降。

rebar 的解决方案是让跟踪工具成为代码仓库的一部分。 工单是专用 tickets 孤立分支上的只追加事件日志（通过被 git 忽略的工作树关联）；当前状态则由该日志快速、确定性地重放得出。仅这一项设计就带来了诸多好处：

• 无需基础设施，完全可移植。 无需数据库或守护进程——只需 Git 和轻量级 Python 安装。克隆代码仓库，跟踪工具也会随之而来。
• 不干扰提交。 工单事件保存在独立分支上，不会触及源代码历史。每次写入都会自动提交并推送，因此活动可以实时共享。
• 并发处理是设计的一部分。 每个事件都有全局唯一的文件名，因此并行写入可以干净地合并为并集；偶尔出现的冲突分叉也会以确定性方式解决——所有克隆最终都会收敛，不会丢失数据。claim 是一种原子性的乐观并发控制原语：Agent 可以认领工作而不会互相干扰。
• 专为扩展而构建。 随着工单增多，事件日志与缓存重放仍能保持快速。

在此基础上，rebar 还提供了并行 Agent 工作实际需要的功能：

• Jira 双向同步——Agent 在 rebar 中工作，团队成员在 Jira 中工作，由一个电平触发的协调器让双方保持同步。要在 CI 中自动运行，请参阅 docs/jira-sync-setup.md（GitHub Actions reconcile-bridge + heartbeat-canary 设置）。
• 感知冲突的调度——工单会记录其影响的文件，因此 next-batch 会为并行 Agent 分配不会在同一文件上发生冲突的工作。
• 临时空间——每个工单都有一个不可见的专用频道，供子 Agent 互相传递备注。
• 结构化质量门禁——清晰度、验收标准、分派就绪度以及整个代码仓库的健康检查，确保工作达到可分派状态。
• 大模型审查门禁（可选）。在工作开始前审查 Agent 的计划，在工单关闭前审查其完成情况，并在代码合并前审查代码。计划审查和代码审查共用一个包含四个阶段的内核。一个查找器会引用证据，另一个独立验证器会通过原子化的是或否问题检验每项主张，而确定性策略则决定哪些内容会阻止流程继续。计划或完成情况审查通过后，会将操作证书记录为 DSSE 信封。该信封包含对其 PAE 字节的 SSHSIG 签名，由签名环境的 Ed25519 密钥生成。证书会将该环境标记为其主体。这会为经过审查的工作生成一份机器可验证的流程记录。
• 溯源链接——discovered_from 将新出现的工作关联回发现该工作的工单。
• 一个存储，三种接口——可通过 CLI、Python 库或 MCP 服务驱动。

要求

系统前提条件：

• Python ≥ 3.11
• git 是运行时前提条件，因为存储使用 Git 孤儿分支和工作树。运行时引擎使用进程内 Python，不需要 bash 或 jq。
• 开发、测试和 CI 需要 Git 2.38 或更高版本。最低版本在 .github/git-version-floor.txt 中声明。Git 低于该最低版本时，测试套件和 CI 会失败。
• 使用可选 S3 修复路径的部署需要 Git 2.38 或更高版本，因为该路径会调用 git merge-tree --write-tree。
• 不需要外部锁二进制文件。 写入序列化使用完全基于 Python 标准库构建的双窗口锁——fcntl.flock(LOCK_EX) 咨询锁加上原子 mkdir 锁（src/rebar/_store/lock.py）——因此不依赖 util-linux 的 flock 二进制文件（或任何其他外部工具）。即使在 fcntl.flock 不可靠的环境（例如某些网络文件系统）中，mkdir 窗口也能维持互斥。
• acli（Atlassian CLI）——Jira Cloud 对账／桥接路径必需的外部二进制文件：每次 bridge／reconcile Cloud 变更都会通过 shell 调用它，因此必须将其安装在 PATH 中（安装说明：docs/jira-sync-setup.md）。[jira-datacenter] Data Center 路径不需要它——该路径使用 jira Python 库。

Python 依赖项。 基础安装（pip install nava-rebar）提供 rebar CLI、import rebar 库和精简工作流引擎。它会安装 pyyaml>=6（用于工作流 DSL 加载器）、jsonschema>=4.18（用于架构注册表以及工作流输入和输出验证）和 referencing>=0.30（用于解析 JSON Schema $ref）。引擎核心和对账器的其他部分均使用 Python 标准库。其他所有依赖项都是可选扩展，并采用延迟导入，以保持基础安装轻量。CI 会验证这一边界。

• 可选运行时功能——按需安装：
  • [mcp] 安装 rebar-mcp 服务，包含 mcp>=1.28.1,<2 和 pyjwt[crypto]>=2.10,<3。
  • [agents]——大模型 Agent 运维框架及 Agent 工作流步骤（rebar review-plan、code_review 工作流）：提供与模型提供商无关的 pydantic-ai 运行时（pydantic-ai-slim[anthropic]），以及 json-repair。
• 开发与编写扩展——运行或提供 rebar 服务不需要这些扩展：
  • [tracing]——用于诊断的 OpenTelemetry OTLP 跟踪接收器（仅写入；绝不会读回并用于 rebar 决策）。
  • [dev]——测试／lint／类型检查工具（pytest、ruff、mypy、hatchling）。pip install -e '.[dev]' 也会自引用 [agents]，使验证测试能够运行而不是跳过；并且运行完整测试套件需要此扩展（接口一致性测试会导入 MCP 服务，因此没有 mcp 时会报错，而不是跳过）。

请参阅安装和测试。

安装

rebar 通过一个 Python 包发布——PyPI 发行包 nava-rebar（导入包和命令仍为 rebar／rebar-mcp）。请选择适合的渠道。（所有情况下的系统前提条件：git（开发／测试 rebar 需要 ≥ 2.38；请参阅要求）和 python3（≥ 3.11）；写入序列化使用内置的 fcntl.flock + mkdir 锁，无需外部二进制文件；Jira Cloud 对账／桥接路径要求 acli 位于 PATH 中（请参阅 docs/jira-sync-setup.md），而 [jira-datacenter] Data Center 路径不需要它。）

Homebrew（CLI）

brew install navapbc/rebar/rebar
# or: brew tap navapbc/rebar && brew install rebar

安装 rebar CLI（以及公式的 venv 中的 rebar 库）。若要通过 Homebrew 使用 MCP 服务，请使用下方的 pipx/uvx 安装 [mcp] extra。

PyPI — pipx / pip

运行时（生产环境）— 安装你将要运行的内容：

pipx install nava-rebar              # isolated CLI on PATH: rebar (+ lean workflow engine)
pip  install nava-rebar              # library: import rebar  (runtime deps: pyyaml, jsonschema, referencing)
pip  install 'nava-rebar[mcp]'       # + MCP server: rebar-mcp
pip  install 'nava-rebar[agents]'    # + LLM agent ops + agentic workflow steps (rebar.llm)
pip  install 'nava-rebar[tracing]'   # + OTLP trace sink (write-only)
pip  install 'nava-rebar[agents,tracing]'        # the union, if you want it all

基础安装无需额外依赖即可运行脚本式工作流（rebar workflow new/validate/show/run）；Agent 式工作流步骤和 rebar review-plan 需要 [agents]。若要了解引擎的用途——何时编写工作流而非定制操作、YAML DSL、三轮审查模式，以及提示词库和评估衔接点——请参阅 docs/workflow-engine.md。

[agents] extra 会添加可选的 LLM Agent 操作框架（rebar.llm）。它提供可通过库、CLI 和 MCP 接口审查工单和代码的工具调用型 Agent。模型类可在 [tool.rebar.llm.model_classes] 中配置，也可通过 REBAR_LLM_<CLASS>_MODEL、REBAR_LLM_MODEL_PROVIDER 和 REBAR_LLM_BASE_URL 配置。单个 REBAR_LLM_MODEL 变量已弃用。请参阅 docs/llm-framework.md。

[agents] extra 会安装用于 Claude 的 Anthropic 提供程序。Bedrock 需要 nava-rebar[agents,bedrock]。ChatGPT 和兼容 OpenAI 的端点需要 [agents]，并且需要 pydantic-ai-slim[openai]。Gemini 需要 [agents]，并且需要 pydantic-ai-slim[google]。除非使用 Agent 操作，否则核心 rebar 不需要也不会导入 LLM 技术栈。

MCP 服务 — 来自 MCP Registry

在 MCP Registry 中登记为 io.github.navapbc/rebar。支持 Registry 的 MCP 客户端可按该名称添加；也可直接在客户端配置中注册（通过 uvx 无需预先安装）：

{
  "mcpServers": {
    "rebar": {
      "command": "uvx",
      "args": ["--from", "nava-rebar[mcp]", "rebar-mcp"],
      "env": { "REBAR_ROOT": "/path/to/your/repo" }
    }
  }
}

（已通过 pip/pipx 安装 nava-rebar[mcp]？请改用 "command": "rebar-mcp"。）服务标志：REBAR_MCP_READONLY=1 仅开放只读工具；修改桥接工具（bridge_run、bridge_sync、bridge_pause 和 bridge_resume）需要 REBAR_MCP_ALLOW_JIRA_SYNC=1。两个标志均接受任何不区分大小写的真值——1、true 或 yes（允许前后空格）；其他任何值（包括未设置）均视为关闭。

私有仓库获取凭据（代码读取门控）

LLM 代码读取门控 review_plan、verify_completion、review_code 和 scan_spec 默认采用证明模式。它们会从 origin 获取所选引用，并读取固定 SHA 对应的不可变快照。因此，REBAR_ROOT 指向私有仓库的服务需要通过 Git 凭据助手、部署密钥或服务克隆中的令牌提供读取凭据。没有凭据时，证明模式会以失败关闭，并显示补救提示，同时通过 GIT_TERMINAL_PROMPT=0 禁用终端提示。source=local 会读取当前检出内容，不会获取代码，也不会为结果签名。快照指南说明了这些语义、操作证书信任模型（适用于携带 SSHSIG 签名的 DSSE 信封，其签名覆盖 PAE 字节；每个签名均由环境的 Ed25519 密钥生成，并归属于该环境），以及临时存储、磁盘空间阈值和 EFS 或 NFS 锁定的设置。

来自源码

git clone https://github.com/navapbc/rebar && cd rebar
pip install .              # library + CLI (runtime deps: pyyaml, jsonschema, referencing)
pip install '.[mcp]'      # + MCP server (FastMCP)
# Developing rebar itself — the full dev environment (test/lint/type tooling +
# the agents stack so the LLM validation tests RUN, not skip), installed through
# the committed uv.lock (or `make install`, which adds the pre-commit gate):
uv sync --extra dev

通过 pipx 从源码安装以及旧版 uv。 如果运行 pipx install "<path>[agents]" 时，在安装 rebar 之前就因 pipx needs uv>=0.9.17 而停止，说明它选用了较旧的主机 uv。 请使用 pipx 的 pip 后端重试同一条源码安装命令：

pipx install --backend pip "<path>[agents]"

这是主机 pipx/uv 工具链不匹配，而非 rebar 打包缺陷。

要贡献更改？ GitHub 是只读镜像——main 只会在 Gerrit 的双票门槛（LLM-Review + Verified/CI）通过后前进。新贡献者请从这份友好的入门指南开始：docs/your-first-change.md；完整参考请见 CONTRIBUTING.md（从 Gerrit 克隆，推送到 refs/for/main，待两项投票通过后，在 Gerrit 中直接点击提交即可——main 使用 Rebase-If-Necessary，因此 Gerrit 会变基到最新提交，并在服务器端提交）。

打包说明——为什么 rebar 会以解包的形式安装到磁盘。 库、CLI、MCP 服务以及整个读写核心都在 Python 进程内运行。唯一作为子进程运行的组件是 Jira 协调器流程（python -m rebar.reconciler）；jira-capability-probe.py 脚本和别名词表作为包数据随包发布于 src/rebar/_engine/ 下，并从文件系统中的实际磁盘文件启动和读取，因此必须将包解包安装到实际目录中，且不支持 zipimport / zip-safe 捆绑包（zipapp、shiv、PEX、Lambda zip）。所有标准安装都满足此要求：pip/pipx wheel（hatchling 会构建解包后的文件）、可编辑安装以及 Homebrew 都会将实际文件安装到磁盘。首次调用协调器时，engine_dir() 会断言引擎目录确实存在于磁盘上，否则会明确报错。

高级（可选）——使用可自托管的代码审查门禁提交。 标准 rebar 使用无需此设置。如果你希望每次提交到 main 前都自动经过 LLM 审查，可以在 AWS 上自托管 Gerrit 和 rebar review-bot（该机器人会导入 MCP 服务所公开的同一 rebar.llm 审查内核），并将 GitHub 降级为只读镜像，仅在 LLM-Review 投票通过后通过 Gerrit 推进。服务器设置请参见 docs/gerrit-aws-setup.md。（此仓库正是使用这套设置——请参见上方的贡献者说明和 CONTRIBUTING.md。）

CLI

所有子命令的完整且始终保持最新的命令参考见 docs/cli-reference.md。该参考由 CLI 自带的帮助数据生成。基本流程是 rebar init → rebar create <type> "<title>" → rebar ready → rebar claim <id> → rebar transition <id> <current> <target>。

运行 rebar help、rebar --help 或 rebar -h 查看子命令概览。运行 rebar <subcommand> --help 或 rebar help <subcommand> 查看特定子命令的帮助。对于叶子命令，在 -- 之前的任意位置传入精确的 --help 或 -h 标记，都会打印用法而不执行命令。嵌套命令系列会保留对子命令的路由。前置帮助标记会打印命令系列的帮助，而 rebar bridge preview --help 和 rebar audit show --help 这类形式会打印子命令的帮助。

仓库根目录从 REBAR_ROOT 解析；若未设置，则回退到工作目录的 git 顶层目录。

结构化输出。 每个返回数据的命令都会通过规范的 --output json 标记输出机器可读的 JSON（简写为 -o json；--output llm 会为 show/list/ready 提供精简令牌的格式）。每种不同的 JSON 格式都有对应的 JSON Schema 文档，并在 CI 中针对 CLI、库和 MCP 进行验证。各命令的契约和 Schema 的事实来源见 docs/output-schemas.md。

认领工作。 rebar claim <id> 会以原子方式将一个未关闭的工单转为 in_progress。省略 --assignee 时，claim 会使用 ticket.default_assignee。显式指定的 --assignee 会覆盖该设置，且必须是 Jira 可解析的邮箱或 accountId。

使用 validate 检查整个仓库的健康状况。 rebar validate 不接受工单 ID——它会扫描整个存储库，并打印整体跟踪器健康评分（1-5，退出码 0-4），将发现的问题归类为严重／主要／次要／警告（--output json、--terse、--verbose）。传入工单 ID 会报错。（rebar 还提供针对单个工单的结构门禁；这些门禁都接受 <id>，并验证工单是否具备可派发工作的结构——每种类型都需要一个 ## Acceptance Criteria 检查清单。请参阅 docs/plan-review-criteria-guide.md 中的工单模板和门禁参考。）

关闭工作。 rebar transition <id> in_progress closed 可关闭任务、缺陷、故事或史诗。关闭缺陷还需要 --class。完成验证为可选项，默认禁用。将 verify.require_completion_verification_for_close = true 设为启用后，每次关闭常规工作工单时，都会在记录状态变更前执行完成验证。

链接。 rebar link <id1> <id2> <relation> 要求使用七种关系之一：blocks、depends_on、relates_to、duplicates、supersedes、discovered_from 和 caused_by。rebar unlink <source> <target> [relation] 中的关系参数为可选项。未指定关系时，它会移除该有序端点对中最近创建的有效链接。指定关系时，它会仅移除该关系，并保留该端点对之间的其他关系。创建阻塞链接时，链接可能会沿父级层级向上提升，因此 unlink 必须以提升后的祖先端点为目标。

计划审查或完成验证通过后，会记录一份操作证书。该证书是一个 DSSE 信封，其中包含使用签名环境的 Ed25519 密钥，对其 PAE 字节生成的 SSHSIG 签名。其主体标识该环境。代码审查门禁通过审查系统报告其判定，不会创建此工单证书。rebar sign 命令和库接口也可以在这两种门禁之外附加清单证书。请参阅 docs/manifest-signing.md。

阻塞链接的层级提升

仅对于阻塞依赖（blocks、depends_on），rebar 会沿父级层级向上提升链接端点，使依赖位于级别相当的工单之间（史诗↔史诗、故事↔故事、任务/缺陷↔任务/缺陷）。执行提升时，它会输出一条 REDIRECT: A→B promoted to … 注记。非阻塞关系（relates_to、duplicates、supersedes、discovered_from、caused_by）则会完全按照给定内容链接，不会进行提升。

存储会自动提交并推送每次写入

每次 rebar 写入（create、edit、transition、claim、link……）都会自动将事件提交到 tickets 分支，并且只要存在 origin 远程仓库，就会自动将该分支推送到 origin/tickets。因此，本地工单活动会立即与远程共享，包括测试/临时工单，因此在使用共享的 tickets 远程仓库时请谨慎操作。推送采用尽力而为策略：没有 origin 远程仓库时不会推送；推送失败（例如无法自动合并的非快进更新或网络不可用）不会导致写入失败——本地提交会保留，分支则会出现分叉。rebar store fsck 会在本地 tickets 分支领先于 origin/tickets 时报告 PUSH_PENDING，因此可以查看尚未推送的活动。有关推送/合并重试算法，请参阅 docs/concurrency.md。

本地运行、离线运行或只读运行。 如果不希望存储与远程仓库通信，可以配置此自动同步功能（完整的配置项和环境变量名称请参阅 docs/config.md）：

• sync.push（环境变量 REBAR_SYNC_PUSH）——always（默认值）会在每次写入时同步推送；async 会在后台推送，避免每次写入的网络延迟导致批处理串行执行；off 会将提交保留在本地，永不推送（fsck 仍会报告 PUSH_PENDING）。
• sync.pull（环境变量 REBAR_SYNC_PULL）——on（默认值）允许读取时从远程仓库获取数据（见下文的新鲜度策略）；off 则执行纯本地重放（适用于离线工作、紧密循环，或刚完成同步的写入之后）。可对单个读取子命令传入 --no-pull，以达到相同效果（例如 rebar list --no-pull）。
• mcp.readonly（环境变量 REBAR_MCP_READONLY=1）——通过 MCP 仅提供读取工具，因此完全不会发生写入，也就不会产生提交或推送。

规模能有多大？即使工单数量达到数千，读取仍能在 1 秒内完成；写入速度则受每个事件一次 git 提交的限制（约 25–30 次/秒）。有关具有代表性的实测数据、git 增长预期以及压缩/维护命令，请参阅 docs/scale-envelope.md；有关批量 NDJSON 导出/导入，请参阅 docs/import-export.md。

CLI、库和 MCP 的读取共用同一新鲜度策略

每次读取——show、list、ready、search、deps——都会先执行一次受限流的（≤1 次/分钟）、尽力而为的 git fetch，并使本地 tickets 分支与 origin/tickets 重新汇合，因此读取结果至多延迟一分钟即可反映协作者的推送。三个接口共用同一约定：CLI、库（rebar.list_tickets() 等）以及 MCP 读取工具都会通过同一个读取实现解析。（此前只有 CLI 读取会同步，导致 MCP——主要的 Agent 接口——读取到的内容最陈旧；如今这种差异已消除。）若要跳过此次获取并进行纯本地重放，请设置 sync.pull=off 或传入 --no-pull——参阅上文的本地运行、离线运行或只读运行。受影响的只有网络获取/合并；本地归约/缓存路径保持不变。请参阅 docs/concurrency.md。

磁盘上的存储内容并非面向人类阅读——请用 rebar 读取

tickets 分支是 rebar 的内部存储格式，并非供人阅读的文档。 每个工单都是一个目录，其中包含只追加的 JSON 事件文件（${hlc}-${uuid}-${TYPE}.json）；工单的当前状态是通过重放这些事件并经过 reducer 得到的。由此可知：

• 文件的排列顺序并无意义。 事件文件以混合逻辑时钟（Hybrid Logical Clock）和 UUID 命名，并以并集的形式在克隆之间合并，因此同一个工单的文件并不是从上到下的叙事，而是只有经过 reducer 排序并折叠后才有意义的无序集合。单独查看一个 EDIT/STATUS/TAG_DELTA 文件，只能看到一项变更，而不是整个工单。
• 当前状态是计算得出的，从不存储。 除了本地可重建的 .cache.json（已被 git 忽略），分支上并没有保存编译后的“当前”工单。手动读取原始文件会造成误解——后续事件可能取代较早的事件，SNAPSHOT 可能将多个事件折叠起来，而并发分支则按一条你必须自行应用的确定性规则解决。

因此，不要通过 cat 查看 .tickets-tracker/ 工作树来了解工单进展——请使用读取命令，它们会替你运行 reducer：rebar show <id>、rebar list、rebar deps <id>、rebar search <query>（CLI）、对应的库调用（rebar.show_ticket(...)）或 MCP 读取工具。

供参考，docs/sample-ticket-log.jsonl 是一个简短的合成事件日志（每行一个事件），展示底层数据的实际样貌——一个双 Agent Epic 和子工单，涵盖创建、认领、评论、关联、标签、文件影响、签署和状态转换。请注意，其中的行并未按时间戳排序：这正是重点。事件正文结构记录在 docs/event-schema.md 中。

Python 库

import rebar

rebar.init_repo(repo_root="/path/to/repo")
tid = rebar.create_ticket("story", "Add login page", priority=2)
ticket = rebar.show_ticket(tid)                 # TicketState
tickets = rebar.list_tickets(status="open")     # list[TicketState]
try:
    rebar.transition(tid, "open", "in_progress")
except rebar.ConcurrencyError:
    ...                                          # ticket changed since last read

preview = rebar.bridge_preview(only=[tid])       # typed, non-mutating Jira plan
run = rebar.bridge_run(profile="dry-run")         # captured scheduled-run result; prints nothing
sync = rebar.bridge_sync(max_changes=10)         # typed, explicitly mutating sync
status = rebar.bridge_status(max_age_seconds=3600)
# Durable operator controls and the live six-step capability check:
rebar.bridge_pause("maintenance")
rebar.bridge_resume()
access = rebar.bridge_check_access()

# Legacy reconcile(mode=...) is not a Python API; use explicit bridge operations.
audit = rebar.bridge_fsck()                       # offline bridge audit

# Sign a DSSE operation certificate by applying SSHSIG to its PAE bytes with the environment's Ed25519 key and principal.
rebar.sign_manifest(tid, ["unit tests: PASS", "security review: clean"])
verdict = rebar.verify_signature(tid)            # {"verified": True, "verdict": "certified", ...}

# Native, in-process reads (no subprocess):
from rebar import reduce_all_tickets, reduce_ticket

带类型的返回约定。 由 schema 支持的 rebar.* 函数在 rebar.types 中使用 TypedDict 进行类型标注（例如 TicketState、TransitionResult、ClaimResult），因此类型检查器可以知道返回值包含哪些键。这些类型源自规范 JSON Schemas，描述的是保证存在的键——返回值仍是普通 dict，运行时结构是开放的（可能出现额外键），因此这些类型定义的是下限，而非封闭集合。可导入这些类型用于注解和 TypedDict 访问：

from rebar.types import TicketState, TransitionResult

t: TransitionResult = rebar.transition(tid, "open", "in_progress")

稳定的异常接口。 rebar.RebarError（基类）及其子类 rebar.ConcurrencyError 是公开异常。RebarError 包含 .returncode（底层引擎的退出码）和 .stderr；ConcurrencyError（退出码 10）表示依赖状态的操作（transition/claim/reopen）在乐观并发竞争中失败——请重新读取并重试，不要强制执行。捕获 RebarError 即可统一处理任何 rebar 故障。

哪些内容适合稳定依赖。 rebar 的版本为 0.x；各接口的稳定性矩阵（CLI、--output json schemas、rebar.* facade、MCP 工具、事件线格式和配置键），以及每项接口“在 1.0 之前可能变更”的含义，请参阅 docs/api-stability.md。

MCP 服务

rebar-mcp          # stdio transport

将工单操作公开为 MCP 工具。按门控层级（只读 / LLM 门控 / 写入门控）分组的完整工具参考见 docs/mcp-reference.md（由服务自身的注册器生成）。请使用显式的 bridge_preview、bridge_run、bridge_sync、bridge_status、 bridge_pause、bridge_resume、bridge_check_access 和 bridge_fsck 工具。 旧版 MCP reconcile(mode=...) 兼容工具已不再注册。 运行 / 同步 / 暂停 / 恢复操作要求设置 REBAR_MCP_ALLOW_JIRA_SYNC=1； REBAR_MCP_READONLY=1 会阻止所有变更操作。要在 MCP 客户端中注册该服务（注册表名称为 io.github.navapbc/rebar，或使用直接的 uvx 配置），请参阅上文的 安装 → MCP 服务。

维护者： 注册表清单位于 server.json； 使用 mcp-publisher CLI 发布 / 更新（参见 docs/releasing.md）。注册表通过此注解验证 PyPI 包的所有权（该注解保留在此 README 中，此文件是 PyPI 的长描述）：

mcp-name: io.github.navapbc/rebar

许可证

Apache-2.0 — 参见 LICENSE。

配置

rebar 从 pyproject.toml 中的 [tool.rebar] 或独立的 rebar.toml（从最近的上级目录向上查找，遇到 .git 即停止）读取 TOML 配置；如果没有，则回退到用户配置 ~/.config/rebar/config.toml（遵循 $XDG_CONFIG_HOME）。优先级从高到低为：rebar -c SECTION.KEY=VALUE / CLI 标志 > REBAR_<SECTION>_<KEY> 环境变量 > 项目配置 > 用户配置 > 内置默认值。 rebar config 会打印解析后的 值及其来源层级。

[tool.rebar]
verify.require_completion_verification_for_close = true  # gate work-ticket close on a PASS
                                           # completion verdict (signed onto the ticket);
                                           # fail-closed. Default false.
ticket.display_mode = "auto"               # auto | canonical | alias | short
compact.threshold   = 10
sync.push = "always"                       # always | async | off
sync.pull = "on"                           # on | off
mcp.readonly = false
scratch.base_dir = ""                      # default <repo>/.rebar/scratch
tracker.dir    = ".tickets-tracker"        # store worktree/symlink dir (env REBAR_TRACKER_DIR)
tracker.branch = "tickets"                 # orphan branch the event log lives on (env REBAR_TRACKER_BRANCH)

完整的键集合、REBAR_<KEY> 环境变量名称及弃用别名见 docs/config.md。

启用关闭门控后，关闭状态转换会针对选定的代码引用运行完成验证器。验证通过后，会记录一个 DSSE 操作证书信封，其中包含使用签名环境的 Ed25519 密钥生成的、对其 PAE 字节进行签名的 SSHSIG 签名。证书主体标识该环境。如果已验证的代码发生变化，请再次运行状态转换。--force=<reason> 会绕过门控且不记录证书。

rebar 会将可写状态保存在仓库根目录下的 .rebar/ 中。scratch 存储默认位于 <repo>/.rebar/scratch/（通过 scratch.base_dir / REBAR_SCRATCH_BASE_DIR 覆盖），一次性迁移标记也会写入 .rebar/。

测试

请在已安装 [dev] 额外依赖的环境中运行测试套件（建议使用 venv）；接口一致性测试会导入 MCP 服务，因此不含 mcp 额外依赖的纯解释器会报错，而不是跳过测试。

uv sync --extra dev && source .venv/bin/activate  # locked install: pytest, mcp, ruff, mypy
pytest -m "not integration"                   # the single entry point (CI runs this)
pytest tests/interfaces                       # interface-parity tier only
pytest tests/scripts                          # engine/reconciler tier only

pytest 是唯一入口。 引擎是纯进程内 Python （bash 引擎及其 .sh 测试套件已在 bash→Python 迁移中移除—— 参见 docs/bash-migration.md）。CI（.github/workflows/test.yml）会在每次推送和 PR 时，在 Ubuntu 和 macOS 上运行 pytest -m "not integration"。默认运行中不包含 integration 层级（实时 Jira / 网络）；请通过 pytest -m integration 并提供凭据，显式运行该层级。

Python 测试套件按关注点细分：

• tests/scripts、tests/unit — 进程内引擎（reducer、graph、reconciler）。
• tests/interfaces — 验证库、CLI 和 MCP接口在同一个由 git 支持的存储上表现一致：
  • test_parity.py 通过三个接口运行每项操作（并检查跨接口一致性：通过一个接口写入，通过其他接口读取）；
  • test_surface.py 固定各接口的能力范围（例如 MCP 没有 init；不存在 classify）；
  • test_library.py / test_cli.py / test_mcp.py 覆盖各接口的特有行为（类型化异常、退出码透传、只读 / 实时门控）。