Rajioba1/pebra

# PEBRA **针对编程 Agent 的预编辑收益-风险分析。** PEBRA 运行于编程 Agent 提议的补丁与你的工作树之间。它使用 CodeGraph 作为其标准的仓库结构引擎，通过结构性证据计算出可审计的 `expected_loss`（预期损失）/ `expected_utility`（预期效用）/ 风险调整后的 `RAU` 决策。它会在编辑写入*之前*返回一个绑定候选者的决定，并可通过 `apply-candidate` 应用确切批准的候选补丁，随后根据批准的信封范围验证**实际的**编辑后 diff，记录结果，并仅将经过校准和度量的事实提升回未来的评估中。如果缺失或存在陈旧的图证据，系统会予以报告，绝不会将其解读为编辑安全的证明。如果安装了宿主 hook，该决策可以在宿主写入之前拦截不受支持或高风险的编辑；如果没有 hook，`assess` 则充当一个咨询性质的控制器。 [](https://github.com/Rajioba1/pebra/actions/workflows/ci.yml) [](https://github.com/Rajioba1/pebra/actions/workflows/security.yml)    -informational) ## 代码库图 只读仪表板将你的仓库渲染为一张**中心节点图（god-node map）**：热点文件变为矩形中心枢纽，它们中被依赖最多的 symbol 变为根据入度（inbound fan-in）确定大小的圆形，`file → symbol` 辐条采用虚线表示，而实际的 `symbol → symbol` CodeGraph 连接采用实线。选中某个评估时，会将其风险决策叠加到它触及的确切 symbol 上（枢纽保持中立）。  同样的账本也可以通过终端 Observatory（`pebra tui`）访问：  ## 为什么选择 PEBRA - **专为编程 Agent 设计。** 预期的操作者是一个受信任的编程 Agent（Claude Code、Codex 或其他宿主），它能够检查仓库、提议精确的补丁，并在编辑前消费确定性的风险/收益数据包。 - **编辑前而非事后。** 它会在应用提议的补丁*之前*进行评估——而不是在造成损害之后查看 diff。 - **确定性的数学计算，而非直觉检验。** 每个决策都是 `expected_loss`、`expected_utility` 和风险调整后的 `RAU` 边界的可复现函数——相同的输入始终得出相同的结果。 - **结构性证据，而非凭空猜测。** PEBRA 经过新鲜度检查的 CodeGraph 索引提供了跨调用者/实现者的 fan-in 和爆炸半径（blast radius）；图侧的契约元数据增强了 AST/变更分类器。如果索引不可用或已过时，PEBRA 会报告这种证据缺失，并降低受影响决策的权重，而不是将缺失的 fan-in 视为安全。 - **验证实际发生的情况。** `verify` 会根据批准的信封范围检查真实的编辑后 diff：HEAD 新鲜度、安全范围、变更严重程度、契约表面漂移以及所需的检查。 - **保守学习。** 结果会被记录，但一个学到的事实只有在经过度量的校准和受控的提升之后，才会影响未来的评估。 - **只读可观测性。** 本地浏览器仪表板和终端 TUI 展示相同的账本——评估历史、校准、学习到的事实以及代码库图——而无需写入源文件；使用 `--read-only` 可在不初始化仓库状态的情况下处理复制或现有的数据库。 ## 这有什么不同？ PEBRA 不是另一个图查看器、记忆存储或领域引擎。它是将仓库知识、历史教训和确切候选字节转化为可审计的预编辑结论的决策层。 | 系统 | 仓库图 | 记忆 / 学习 | 编辑前风险/收益数学 | 绑定候选者的执行 | 最适合场景 | |---|---:|---:|---:|---:|---| | **PEBRA** | 是：经过新鲜度检查的 CodeGraph 证据 | 经过审计的 `learning_context` + 提升的事实 | 是：`expected_loss`、收益、效用、不确定性、RAU | 是，基于确切的 `apply-candidate` 和健康的已配置 hook 路径：仓库 + HEAD + 文件 + 候选字节 + 批准状态 | 决定编程 Agent 的编辑在改变仓库前是否应该继续执行。 | | **CodeGraph** | 是：symbol、调用、依赖项、fan-in、受影响的测试 | 无 PEBRA 结果循环 | 否 | 否 | 提供当前的结构化仓库事实。 | | **Graphify** | 可视化知识图谱模式 | 可选的叠加模式 | 否 | 否 | 探索和展示图结构。 | | **AgentMemory** | 默认无源码图 | 通用 Agent 记忆 | 否 | 否 | 记住跨会话的 Agent 观察结果。 | - CodeGraph 为 PEBRA 提供当前的仓库结构；PEBRA 决定该结构对特定提议的补丁意味着什么。 - Graphify 为 PEBRA 的仪表板风格提供参考；PEBRA 保持风险叠加层与新鲜的图证据和经过验证的教训紧密相连。 - AgentMemory 是广泛的回忆；PEBRA 的回忆范围较窄但可审计。回忆到的描述性文本仅作参考之用；只有经过审查的已发布先验和单独提升的数值事实才能影响未来的评估。 ## 安装 PEBRA 支持 Windows、Linux 和 macOS 上的 Python 3.11–3.13。安装已发布的 CLI： ``` python -m pip install --upgrade pip python -m pip install pebra pebra --version ``` 对于隔离的 CLI 安装： ``` pipx install pebra pebra --version ``` PEBRA 会在诸如 `pebra --version`、`pebra help`、`pebra dashboard` 和 `pebra tui` 等面向人类的命令中 opportunistic 地（适时）检查 PyPI。结果会在仓库外缓存 24 小时；机器 JSON 接口、gate hook、MCP、核心评估和可编辑的 checkout 不会执行后台网络检查。当有新版本可用时，运行： ``` pebra update ``` `pebra update` 默认会打印出确切的升级命令。当你希望 PEBRA 在交互式确认后执行检测到的 `pip`/`pipx` 升级命令时，请使用 `pebra update --run`，或者使用 `pebra update --yes` 进行无人值守的升级命令。设置 `PEBRA_NO_UPDATE_CHECK=1` 以禁用自动和显式的更新检查。 CodeGraph 是 PEBRA 的标准结构化引擎；RCA（可选）用于度量多语言的可维护性收益。使用以下命令准备 CodeGraph 并报告 RCA 就绪状态（它不会执行 Cargo）： ``` pebra setup-engines --repo-root . pebra doctor --repo-root . pebra agent-init --target claude --repo-root . --with-hook pebra agent-init --target claude --repo-root . --check --json ``` `setup-engines` 退出状态为 `0` 表示 CodeGraph 受信任且 RCA 已被接受。退出状态为 `1` 且 `assess_ready=true` 表示引擎不完整（通常是预估的收益），而不是 PEBRA 损坏了。该命令仅检查 Cargo 是否可用以便打印有用的指导信息；它从不安装 Cargo 或运行 RCA 安装命令。在出现提示时，使用 [rustup](https://rustup.rs/) 安装 Rust/Cargo，然后运行 PEBRA 显示的确切指定版本的命令。 高级的仅针对 CodeGraph 的选项保留在 `pebra setup-graph` 中；贡献者设置和引擎测试详情请见 [CONTRIBUTING](CONTRIBUTING.md)。 对于 Codex 使用 `--target codex`。当存在受支持的宿主标记时，`--target auto` 仅安装检测到的 projections： ``` pebra agent-init --target auto --repo-root . --with-hook pebra agent-init --target auto --repo-root . --check --json ``` 在 Windows PowerShell 上进行可编辑开发： ``` python -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -e . ``` 在 Linux 或 macOS 上： ``` python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip .venv/bin/python -m pip install -e . ``` PEBRA 命令本身与终端无关；只有虚拟环境路径和激活语法因 shell 而异。请参阅 [命令参考](docs/PEBRA_COMMAND_REFERENCE.md#shell-compatibility) 获取 PowerShell、命令提示符、Bash 和 zsh 的等效命令。 `codegraph.json` 是操作者拥有的分析范围：`extensions` 和 `includeIgnored` 会影响分析范围；`exclude` 会被报告，但会被指定的 CodeGraph 1.1.1 忽略。PEBRA 绝不会在 `assess` 期间隐式安装或更新引擎；引擎更改需要上面的显式设置命令。当 `pebra doctor --repo-root .` 报告图表健康，且 `pebra agent-init --target --repo-root . --check --json` 报告预期的执行模式时，安装即告完成。请继续阅读下文的产品模型和基本工作流。 ## 产品模型 PEBRA 遵循“先思考后行动”的生命周期。仓库知识先于候选设计；风险/收益数学计算和闸门检查在候选方案确切之后进行。 CodeGraph 是仓库事实的当前结构化适配器；PEBRA 拥有的 `learning_context` 记录提供可审计的召回。 ``` flowchart TB A([Interpret
maintainer request]) B[Understand
current repository] X[[pebra explore]] R[/Recall learning_context
verified lessons + risk/benefit history/] Cg[/Retrieve CodeGraph context
source + calls + dependents + tests/] U[/Understand receipt
sections + provenance/] D[Design exact candidate
files + ops + patch + verification] As[Assess exact candidate] S1[Trusted structural evidence] S2[Promoted PEBRA facts] S3[Math
loss + benefit + utility + uncertainty + RAU] S4[Ordered decision gates] E{Decide} O[/proceed | inspect_first | test_first
revise_safer | ask_human | reject/] F[Enforce before mutation
repo + HEAD + files
candidate bytes + assessment/sanction] G[Apply exact candidate] H[Verify and record outcome] I([Learn]) A --> B --> X X --> R --> U X --> Cg --> U U --> D --> As As --> S1 --> E As --> S2 --> E As --> S3 --> E As --> S4 --> E E --> O --> F --> G --> H --> I ``` 简而言之： ``` Interpret → Understand current repository → Design exact candidate → Assess exact candidate → Decide → Enforce before mutation → Apply exact candidate → Verify and record outcome → Learn ``` `assess` 按顺序计算——并且生成的 Agent 指令要求*消费*这些值，绝不重新推导或覆盖它们： ``` disutility_j = max(input_or_prior_j, criticality_value) # for consequence-bearing events expected_loss = Σ_j p_event_j · disutility_j expected_utility = p_success · benefit − expected_loss − review_cost utility_sd = √(Σ variance contribution terms) RAU = expected_utility − 1.28 · utility_sd ``` 有序的**决策闸门**会评估这些值以及经过新鲜度检查的 CodeGraph fan-in / 爆炸半径、AST/变更契约表面信号、置信度、图表新鲜度和策略义务。缺失的图表证据是显式的，绝不会被视为零风险度量。单独的**执行闸门**随后会在 `apply-candidate` 和受支持的已配置 hook 路径上检查确切的绑定候选字节。`reject` 意味着*拒绝此候选方案*，而不是拒绝维护者的目标——Agent 会展示记录在案的原因和风险/收益证据。召回为“理解”提供信息；只有经过审查的已发布先验和单独提升的数值事实才能影响未来的 `assess`。 ## 内部包含什么 - **`assess` / `verify`** —— 编辑前的决策 + 数学数据包，以及根据批准的信封范围和所需检查进行的编辑后验证。 - **绑定候选者的执行** —— 在确切应用或健康的已配置 hook 路径上，一个影响重大的编辑必须重现与评估的补丁相同的规范化内容；相同的仓库 / HEAD / 路径是不够的。 - **CodeGraph 支持的证据** —— 每个符号经过新鲜度检查的 fan-in、DELETE 文件的 fan-in 汇总、跨调用者/引用/实现者/子类的 MODIFY 爆炸半径、图侧的契约元数据以及容器层级汇总。Python 契约表面分类还使用了 AST/变更证据。请参阅 [图证据及注意事项](docs/PEBRA_COMMAND_REFERENCE.md)。 - **学习循环** —— 结果记录、影子学习、受校准控制的提升、记分卡以及学习到的事实重新应用。 - **只读可观测性** —— 一个以图为中心的浏览器仪表板，包含中心节点图、评估活动、校准诊断和学习到的事实，以及基于相同账本的 Textual 终端 Observatory。 - **提供商中立的 `pebra explore`** —— 首先召回有界 PEBRA 历史，然后从现有的图表索引中检索当前的仓库上下文。 - **收益信号** —— 通过 [`rust-code-analysis`](https://github.com/mozilla/rust-code-analysis) 提供可选的多语言复杂度 + 可维护性指数；当缺失时，它会安全降级为*预估的*收益，并且绝不会影响风险。`pebra setup-engines` 会在 RCA 缺失时打印确切的指定版本 Cargo 安装命令（它从不自行运行 Cargo）。`PEBRA_RCA_BIN` 可以指向受信任的启动器或 bin 目录；`PEBRA_RCA_SHA256` 可以精确指定操作者提供的二进制文件。 ## 基本工作流 ``` # 1. 了解当前 repository：回顾已验证的 PEBRA lessons，然后查询 CodeGraph。 pebra explore "change login validation" --repo-root . # 2. 在 PEBRA 之外设计确切的 candidate，然后提交该确切的 request。 # request.json 包括 task、files、operations、patch、expected_files 和 verification plan。 pebra assess request.json --json ``` 遵循返回的决策，而不是将评估视为自动许可： ``` inspect_first ──→ inspect → reassess test_first ─────→ test → reassess revise_safer ───→ revise → reassess ask_human ──────→ trusted operator runs pebra accept-risk --apply reject ─────────→ new route or eligible override → reassess proceed ├─ requires_confirmation=true → trusted operator runs pebra accept-risk --apply │ (it reassesses and applies; do not apply again) └─ requires_confirmation=false → pebra apply-candidate --assessment-id ``` 在普通的继续路径上： ``` pebra apply-candidate --assessment-id pebra verify --assessment-id --json ``` 在 `pebra accept-risk --apply` 成功之后，使用其返回的 `reassessment_id` 进行验证和记录，而不是最初保留的 ID。批准命令已经应用了候选方案，因此绝不要在其后使用 `pebra apply-candidate`。 记录生命周期结果： ``` pebra record-outcome --assessment-id --status completed ``` `record-outcome` 会关闭已验证的操作生命周期，并可能创建有界的召回上下文；它本身不度量或提升校准事实。MCP 提交的标签仍然属于 Agent 来源。受信任的宿主可以单独度量并根据宿主产生的证据运行受控的提升： | Claude Code PreToolUse hook (可选) | `configured_enforcing` | 观察到确切的已启用 hook 配置、匹配的闸门能力握手、图表和 Git HEAD。绑定候选者的检查会在受支持的结构化编辑之前拒绝不受支持的候选方案；这并不能证明宿主调用了每一个事件。 | | Codex 托管块 + skill | `advisory_only` | 现有的 `AGENTS.md` 内容围绕托管的协议块予以保留，并且详细的 skill 与 Claude 的逐字节相同，但此模式不会拦截写入操作。 | | Codex 仓库本地 hook (可选) | `best_effort` | 绑定候选者的闸门逻辑已安装，但仓库本地 hook 的加载仍然取决于宿主。 | | MCP 工具 | `advisory_only` | 评估/验证工具可用，但仅靠 MCP 不会拦截另一个宿主的写入。 | 如果图表或 Git HEAD 证据不可用，已安装的闸门仍将**根据策略保持故障开放（fail-open）**（`degraded_fail_open`）。这些是可观察的配置状态，并不能证明宿主调用了每一个事件，而且 `trusted_actor_required` 是一个协议边界，而不是操作系统级别的身份验证——在同一操作系统账户下具有 shell 访问权限的进程仍然可以调用本地的受信任宿主表面。当需要抵御对抗性 Agent 时，请使用单独具有特权的宿主或操作者账户。完整的威胁边界和多文件候选规则在 [命令参考](docs/PEBRA_COMMAND_REFERENCE.md) 中。 ## 命令映射 ``` pebra --version # 'installed' wheel vs editable checkout + source revision pebra --help # root help pebra help tui # command help pebra help --all # complete, parser-checked command inventory ``` 当前命令表面： | 阶段 | 命令 | |---|---| | 理解 + 图表证据 | `setup-engines`, `setup-graph`, `doctor`, `graph-stats`, `dependents`, `explore` | | 候选构建 + 评估 | `candidate-patch`, `assess` | | 执行 + 应用 | `gate-check`, `gate-hook`, `apply-candidate`, `accept-risk` | | 验证 + 学习 | `verify`, `record-outcome`, `finalize-outcome`, `learn`, `promote`, `scorecard` | | 可观测性 + 宿主设置 | `dashboard`, `tui`, `agent-init`, `capabilities`, `help`, `--help`, `help --all`, `--version` | | 包维护 | `update`, `update-check` | 详尽的、经过解析器检查的语法在 [命令参考](docs/PEBRA_COMMAND_REFERENCE.md) 中。 从已安装或可编辑的 checkout 启动终端 Observatory： ``` pebra tui --repo-root . ``` 从此仓库的 Windows 虚拟环境中，独立于 PATH 的等效命令是： ``` .\.venv\Scripts\python.exe -m pebra tui --repo-root . ``` 仪表板路由是只读的。正常的绑定仓库启动可能会初始化 `.pebra/` 状态，以便它可以打开账本；`--read-only` 在不初始化仓库状态的情况下打开现有数据库。在环回绑定上，它默认无 token 以方便本地使用；任何非环回绑定都需要 bearer token（`--auth token`）。 ## 验证 ``` .\.venv\Scripts\nox.exe -s tests lint e2e-fast ``` CI 运行测试矩阵（Ubuntu / Windows / macOS）、lint、import-linter 架构契约、已安装 wheel 的验证以及 Playwright 仪表板通道。有关完整的会话清单，请参阅 [CONTRIBUTING](CONTRIBUTING.md)。 ## 文档 - [详尽的命令参考](docs/PEBRA_COMMAND_REFERENCE.md) - [贡献与开发设置](CONTRIBUTING.md) - [安全策略](SECURITY.md) ## 许可证 PEBRA 的自身代码采用 Apache-2.0 授权。捆绑的第三方资产在 [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt) 中保留了它们各自的通知。

标签：AI编程助手, Blue Team, Python, SOC Prime, 开发工具, 无后门, 逆向工具