BizGuard: бизнес-шлюз безопасности для ИИ-ассистентов программирования

BizGuard — это экспериментальный проект с открытым исходным кодом: перед тем как ИИ-ассистент программирования вносит изменения в код, он проверяет, не нарушают ли изменения важные, но легко упускаемые бизнес-правила системы.

Он работает вместе с программирующими ассистентами, такими как Claude Code, Codex: ассистент пишет код, а BizGuard выдаёт отслеживаемое заключение о блокировке, когда нарушаются критические правила. Это не production-grade продукт безопасности и не замена человеческой оценке.

Какую проблему он решает?

ИИ хорошо умеет менять код по требованиям, но не обязательно знает, какие правила в вашей системе «трогать нельзя». Ещё сложнее то, что эти правила часто не записаны в комментариях: например, один купон можно использовать только один раз, состояние главной книги должно быть согласовано, а поля данных, возвращаемые наружу, нельзя произвольно удалять.

Например: когда ИИ изменяет логику использования купона, он удаляет проверку идемпотентного ключа, чтобы «упростить код». Идемпотентный ключ можно понимать как «уникальный номер этого запроса»; с ним повторные клики или сетевые повторы не приведут к повторному использованию одного и того же купона. Код, возможно, по-прежнему компилируется, обычные тесты, вероятно, проходят, но при повторной отправке пользователем может произойти повторное использование купона.

Традиционное ревью кода на основе LLM больше похоже на то, чтобы задним числом попросить другого ИИ угадать, «есть ли здесь риск»: это полезно, но результат вероятностный. BizGuard же до перехода изменения на следующий шаг превращает явные бизнес-правила в исполняемые Policy (политики) и с помощью проверки синтаксического дерева (AST, структуры программы, а не просто текста) и фиксированных правил получает детерминированное заключение: один и тот же вход можно воспроизвести офлайн, и заключение не зависит от импровизации модели.

Related MCP server: Architect-to-Product (A2P)

Зачем этот проект?

В сложных бизнес-системах скрыто множество бизнес-инвариантов — то есть ограничений, которые «должны выполняться всегда, независимо от изменений», например:

• Идемпотентность: повторные запросы не должны приводить к повторному списанию средств, повторному использованию купона или повторной отгрузке;

• Согласованность главной книги: состояние транзакций и записи главной книги не должны противоречить друг другу;

• Совместимость DTO: DTO — это структура данных, передаваемая между сервисами; нельзя незаметно ломать вызывающую сторону изменением внешних полей.

Эти знания часто разбросаны по историческим инцидентам, контрактам API, командной документации и множеству сервисов. Существующие решения, такие как CodeRabbit, в основном полагаются на последующее LLM-ревью: они хороши для обнаружения зацепок, но не гарантируют, что скрытые инварианты будут выявлены каждый раз.

Подход BizGuard — собрать важные инварианты в Policy и поддерживать решения с помощью AST-проверки, анализа влияния и цепочки доказательств. Он соблюдает три принципа:

• Детерминированность: заключение можно воспроизвести офлайн;

• Цепочка доказательств: каждый BLOCK можно проследить до правила, изменения и соответствующих доказательств;

• Не выдавать неизвестное за безопасное: при неполной информации возвращается CHECK_INCOMPLETE или REQUIRE_APPROVAL, а не безосновательный ALLOW.

Техническая архитектура

Проект строится поэтапно с P0 до P5; здесь «P» — это номер этапа, а не требование выполнять шаги вручную по порядку.

flowchart LR
    P0[P0：3 个 Java 脱敏 fixture 仓库\n语义 catalog] --> P1[P1：领域契约\n黄金基准]
    P1 --> P2[P2：知识 Hub\n混合检索]
    P2 --> P3[P3：跨服务影响图谱\n8 类节点 · 真 BFS]
    P3 --> P4[P4：Context Compiler\n8 个 MCP Tool]
    P4 --> P5[P5：四态决策 · 审批 · CI\n5 组消融]
    P5 --> D[带证据的安全结论]

• P0: предоставляет три обезличенных фикстурных репозитория Java — coupon-core, coupon-contract, merchant-service, а также семантический каталог с описанием бизнес-возможностей, правил и ответственных.

• P1: фиксирует доменные контракты как проверяемый золотой эталон, чтобы правила не дрейфовали вместе с реализацией.

• P2: Knowledge Hub собирает управляемые знания команды; гибридный поиск сочетает семантические векторы и результаты по ключевым словам. Замороженный Recall@5=1.0 на оценочном наборе означает лишь, что в этом фиксированном небольшом множестве первые 5 результатов покрывают целевую запись, а не является общей полнотой поиска в продакшене.

• P3: строит межсервисный граф влияния, включающий 8 типов узлов: организацию, развёртывание, код, интерфейсы, данные, сообщения, рантайм и бизнес; использует настоящий BFS (поиск в ширину) для поиска кратчайшего пути влияния и возвращает доказательства вместе с путём. Если динамические границы не удаётся подтвердить, они явно помечаются как неизвестные.

• P4: Context Compiler компилирует задачу, репозитории, базовую версию, правила, влияние и обязательные тесты в контекстный пакет только для чтения; пакет доступен агенту через 8 MCP-инструментов.

• P5: агрегирует результат в решение из четырёх состояний, интегрируется с рабочим процессом утверждения и повторной проверкой CI, а также предоставляет 5 групп воспроизводимых офлайн абляционных сравнений: Naive Baseline, Rules Only, RAG Only, Context, Full.

Смысл четырёх состояний очевиден: ALLOW (можно продолжать), ALLOW_WITH_TESTS (можно продолжать после добавления указанных тестов), REQUIRE_APPROVAL (требуется подтверждение человека) и BLOCK (обнаружено критическое нарушение, блокировка). Если в существующем конвейере проверок возникает случай, который невозможно проверить, явно возвращается CHECK_INCOMPLETE, а затем это отображается в результат «не пропускать автоматически».

Структура проекта

biz-guard/
├── src/bizguard/        # 核心：规则、决策、图谱、检索、CLI 与 CI
├── agents_mcp/          # MCP 协议适配层，供 AI 编程助手调用
├── fixtures/            # 三个脱敏 Java 微服务 fixture 与辅助编译脚本
├── sample/              # Python 示例代码与可复现的 diff
├── policy/              # 业务不变量与策略注册表
├── registry/            # 领域契约登记数据
├── knowledge/           # 已发布知识、ADR 与检索素材
├── bench/               # 黄金基准、决策 fixture、五组消融任务
├── tests/               # 自动化测试
├── scripts/             # Demo、安装验证和 benchmark 脚本
└── docs/                # 架构决策记录

Демонстрация: одно изменение — два результата

Запустите в корневом каталоге проекта:

./scripts/demo.sh

Скрипт демонстрирует, что «контрольная группа нативного Coding Agent» (офлайн, детерминированная scripted-имитация базовой линии) считает изменение на вид разумным и пропускает его; затем BizGuard проверяет тот же diff и возвращает BLOCK. Это не измерение возможностей реального Claude Code или Codex; реальный агент запускается только в режиме --live бенчмарка и при настройке команд реального агента.

Также можно напрямую посмотреть пример нарушения:

bizguard check --diff sample/diffs/diff_violation_1.diff

Этот diff удаляет IdempotencyStore.check(idempotency_key). BizGuard выведет BLOCK и вернёт «удалённую проверку идемпотентности» как finding/evidence; поэтому вы сможете проследить, «почему это заблокировано», а не просто получить из чёрного ящика результат «не пройдено».

Быстрый старт

Требования к окружению

• Python 3.12+

• Java 17 (для компиляции/проверки Java-фикстур)

git clone https://github.com/PureBlueFrank/biz-guard.git
cd biz-guard

# 常规安装
pip install -e .

# 运行当前工作区的全部测试（当前可收集 259 个）
pytest

В офлайн-среде сначала подготовьте зависимость для сборки hatchling в виртуальном окружении или во внутреннем источнике пакетов, затем используйте:

pip install --no-build-isolation -e .

pip install -e . по умолчанию создаёт изолированную среду сборки; в офлайне он может попытаться загрузить hatchling.

Часто используемые команды CLI

Следующие команды предполагают, что текущий каталог — корень проекта. prepare требует указать задачу, затрагиваемые репозитории и базовую версию; impact возвращает пути и доказательства на основе реального графа фикстур.

# 编译 Agent 可读的上下文包
bizguard prepare --task "检查优惠券状态字段变更" \
  --repos coupon-core coupon-contract \
  --base-revisions bench/fixtures/phase3-revisions.yaml --json

# 检查 unified diff 是否违反 Policy
bizguard check --diff sample/diffs/diff_violation_1.diff

# 分析跨服务影响
bizguard impact analyze \
  --diff bench/fixtures/phase3/dto-status.diff \
  --repos fixtures/java-microservices \
  --revision-set bench/fixtures/phase3-revisions.yaml --format json

# 搜索受治理的团队知识
bizguard knowledge search --query "优惠券核销必须使用幂等键" \
  --scope coupon_redemption --revision semantic-seed-v1 \
  --roles engineering --json

8 MCP-инструментов

MCP (Model Context Protocol) — это стандартный интерфейс, позволяющий ИИ-ассистентам вызывать внешние возможности. BizGuard предоставляет следующие 8 инструментов:

1. prepare_change: компилирует read-only Context Pack;

2. search_team_knowledge: выполняет поиск по командным знаниям, к которым есть доступ;

3. explain_symbol: объясняет проиндексированные символы и их доказательства в графе;

4. analyze_impact: анализирует пути влияния, неизвестные границы и обязательные тесты;

5. validate_patch: детерминированно проверяет unified diff;

6. get_required_tests: определяет тесты, которые следует запустить, согласно Policy;

7. request_approval: пока предоставляет только схему утверждения и не создаёт записи об утверждении;

8. get_change_decision: возвращает агрегированное решение из четырёх состояний, доказательства, тесты и утверждающего.

Проверка установки по замкнутому циклу

./scripts/verify_install.sh --offline

Этот скрипт проверяет локальную диагностику и медленную повторную проверку CI; по умолчанию используется фикстура изменения DTO между сервисами.

Честное заявление и ограничения

• BizGuard — это экспериментальный проект с открытым исходным кодом, а не проверенная система, которую можно использовать для блокирования в продакшене.

• Поддержка Java охватывает только три обезличенных фикстурных репозитория, а не полный анализатор экосистемы Java.

• Трек агента в офлайн-бенчмарке — это scripted/эвристическая базовая линия; реальный агент запускается только при передаче --live и настройке команд реального агента.

• Целевая модель embedding для поиска — Zhipu embedding-3; в офлайне происходит понижение до локального лексического поиска с явной пометкой о понижении. Такие результаты подходят для разработки и демонстрации и не могут считаться производственной приёмкой, эквивалентной настоящим embedding.

• Diff, на который распространяется Policy, перед AST-проверкой применяется в памяти к текущей фикстурной базе; рабочее пространство не изменяется. Если diff не применяется или не покрывается правилами, система не будет предполагать, что это безопасно.

Участие и обратная связь

Приглашаем ознакомиться с руководством по внесению вклада и обсудить новые бизнес-инварианты, фикстуры и воспроизводимые примеры через issue или PR.