sipyourdrink-ltd/bernstein · 上手攻略

仓库：sipyourdrink-ltd/bernstein
链接：https://github.com/sipyourdrink-ltd/bernstein
分类：agent-orchestration · governance · compliance
作者：Tom
更新：2026-09-20

是什么

Bernstein 是 AI Agent 的治理与编排框架（Governance & Orchestration framework），核心特点：把策略写成代码，Bernstein 执行并产出可离线验证的完整运行记录。调度层完全由确定性 Python 组成——协调环路中无 LLM，所以每次运行可复现、可 replay、可事后审计。Apache-2.0 开源。

一句话定义：Bernstein = 政策即代码（Policy-as-Code）+确定性调度器+工作隔离+完整溯源日志。

解决什么问题

当前 Agent 运行的问题： 1. 不可复现：同一任务跑两次结果可能不同，LLM 的随机性让调试困难。 2. 无治理层：没有角色权限、审批门、隔离工作区，Agent 自由度过高难以合规。 3. 事后无法审计：运行记录散落，审计人员无法重建完整决策链。 4. 多 Agent 协作缺乏确定性：CrewAI/AutoGen 等用 LLM 编排，"调度"本身不可信。

Bernstein 的设计目标：让 Agent 工作负载可验证、可 replay、有审计证据——特别是受监管行业（金融、医疗、政府 IT）。

快速安装

方式 A：uv（推荐，隔离工具环境）

# 先安装 uv（若未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
irm https://astral.sh/uv/install.ps1 | iex         # Windows PowerShell

uv tool install bernstein

方式 B：pipx

pipx install bernstein

方式 C：pip

pip install bernstein

方式 D：Homebrew

brew install chernistry/tap/bernstein

方式 E：Docker

docker run -v "$(pwd)":/workspace -v "$(pwd)/.sdd":/workspace/.sdd \
  -p 8052:8052 ghcr.io/sipyourdrink-ltd/bernstein \
  -g "your goal"

⚠️ Docker 方式需显式挂载 .sdd 卷（旧版镜像无此会报 Permission denied，镜像 3.14.159+ 已修复）。

方式 F：源码编译

git clone https://github.com/sipyourdrink-ltd/bernstein
cd bernstein
uv venv && uv pip install -e .
source .venv/bin/activate
bernstein --version

⚠️ 环境要求：Python 3.12+、Git（用于 git worktree 隔离），支持 macOS / Linux / Windows。

核心用法

初始化与诊断

bernstein init           # 初始化项目配置
bernstein doctor         # 检查 CLI agent 是否安装并认证

单任务运行（Goal 模式）

bernstein -g "fix the failing test in tests/test_foo.py"

声明式工作流（YAML）

一个完整的审计证据包工作流示例（来自仓库 .bernstein/workflows/audit-evidence-pack.yaml）：

name: audit-evidence-pack
version: "1.0.0"

phases:
  - name: scope
    allowed_roles: [manager, architect]
  - name: collect
  - name: validate
    allowed_roles: [qa, security]
  - name: deliver
    allowed_roles: [security, manager]

nodes:
  define-control-inventory:
    phase: scope
    role: architect

  collect-audit-logs:
    phase: collect
    role: security
    depends_on: [define-control-inventory]

  assemble-pack:
    phase: validate
    role: docs
    depends_on:
      - collect-audit-logs
      - collect-sboms-and-attestations
      - collect-runbooks-and-policies
      - collect-eval-results

  mock-auditor-pass:
    phase: validate
    role: qa
    depends_on: [assemble-pack]

  remediate-findings:
    phase: collect
    role: docs
    depends_on:
      - source: mock-auditor-pass
        condition: "status == 'failed'"
    retry:
      max_attempts: 3
      until: "status == 'done'"

  sign-and-deliver:
    phase: deliver
    role: security
    depends_on:
      - source: mock-auditor-pass
        condition: "status == 'done'"

运行该工作流：

bernstein run .bernstein/workflows/audit-evidence-pack.yaml

离线验证运行记录

bernstein verify receipt docs/assets/demo-run/run-receipt.json \
  --public-key docs/assets/demo-run/run-receipt.pub.pem

仓库的 docs/assets/demo-run/ 目录包含 demo 运行的原始 cast、签名收据和公钥，可离线验证。

开启审计日志（HMAC 链）

BERNSTEIN_AUDIT=1 bernstein -g "your goal"

运行时设置 BERNSTEIN_AUDIT=1 会在运行记录中追加密码学收据，支持离线验证非确定性。

核心架构设计

四个核心差异

无 LLM 协调：调度是纯 Python，每次运行可复现；Replay 昨天的计划得到昨天的任务图。
事后可检查：Replay journal 记录每步操作；BERNSTEIN_AUDIT=1 输出 HMAC 链收据；非确定性在精确步骤以哈希不匹配呈现（非 flaky test 的模糊重跑）。
天然隔离：每个编码任务在独立 git worktree 中运行，背后有 merge gate；artifact 模式任务在 .sdd/workspaces/ 下有独立工作目录；共享状态只有原子声明的任务待办。
广泛兼容：40+ CLI agent 适配器（Claude Code、Codex、Gemini CLI 等），通用 --prompt wrapper，文件状态，无 SaaS 跳板，无第三方数据平面。

角色与门控

Phase（阶段）：定义任务图中的执行顺序和依赖。
Role（角色）：architect / security / qa / manager / docs 等，节点只能在允许的 Phase 内运行。
Approval Gate：YAML 中可声明 allowed_roles，节点执行前自动验证角色是否合规。
Artifact Contract：非代码交付物（报告、数据集、扫描结果）可声明合同，完成条件为签名溯源收据而非 git commit。

典型适用场景

合规审计：金融/医疗/政府 IT，需要完整操作溯源，审计人员可离线验证每一步。
多角色工作流：软件开发流程中，architect 定义范围 → security 收集 SBOM → qa 验证 → manager 审批交付。
Air-gap 隔离环境：内网/离线环境，Bernstein 本地运行，无外部 SaaS 依赖。
多 Agent 隔离开发：避免 Agent 间互相污染工作区，每个任务有独立 worktree。
需要 deterministic replay 的场景：调试、复现 bug、证明合规——LLM 协调的框架无法做到。

坑与注意

⚠️ Beta 状态，单人维护：README 明确说明"beta. Solo-maintained, under active development." minor 版本可能改变接口，生产使用务必 Pin 版本。

⚠️ Windows 符号链接限制：共享 node_modules / .venv 需要开发者模式或管理员权限；无权限时 Agent 回退到 per-worktree 安装模式。

⚠️ Docker 旧版 .sdd 挂载：镜像 ≤3.14.159 版本必须显式挂载 $(pwd)/.sdd:/workspace/.sdd，否则写 root-owned volume 导致 Permission denied；新版已修复。

⚠️ 与数学 Bernstein 多项式同名：搜索时注意区分，仓库域名 bernstein.run。

⚠️ YAML 工作流不是 prompt：YAML 声明的是调度逻辑，不是提示词；模型不参与"下一步做什么"的决策。

⚠️ CLI agent 需自行准备：bernstein doctor 只检查 agent 是否存在，认证和 API key 由用户自行管理。

与同类对比

项目	类型	LLM in 调度	隔离方式	许可证	定位
Bernstein	治理+编排层	❌	git worktree + workspace	Apache 2.0	合规优先
CrewAI	多 Agent 编排	✅	共享工作区	Apache 2.0	快速协作
AutoGen	多 Agent 对话	✅	共享工作区	MIT	研究原型
LangGraph	状态机+工作流	✅	共享工作区	MIT	应用框架
LangChain	应用框架	✅	共享工作区	MIT	快速原型

核心差异：Bernstein 的定位是治理层，不替换 LangChain/CrewAI；你可以在 Bernstein 管理的任务节点中运行 CrewAI Agent——Bernstein 提供审计、隔离和确定性，底层 Agent 逻辑不变。

一句话推荐结论

如果你的 Agent 工作负载需要可验证、可 replay、有角色权限控制，且在受监管环境下运行，Bernstein 是目前开源领域最彻底的"确定性优先"方案；Beta 使用，做好版本 Pin，审计日志开起来——在合规面前，LLM 的不确定性是你最大的敌人。

数据来源：GitHub README、docs/getting-started/install.md（均为 2025 年快照，⚠️ 版本号/兼容性信息请以最新 commit 和 bernstein.run 文档为准）