japan1988/multi-agent-mediation

# 📘 Maestro Orchestrator — 编排框架（故障闭环 + HITL） [](https://github.com/japan1988/multi-agent-mediation/stargazers)  [](https://github.com/japan1988/multi-agent-mediation/actions/workflows/python-app.yml) [](https://github.com/japan1988/multi-agent-mediation/actions/workflows/tasukeru-analysis.yml) ## ⚠️ 目的与免责声明（研究与教育） **这是一个研究/教育参考实现（原型）。** 请勿使用它执行或协助有害行为（例如：利用漏洞、入侵、监视、冒充、破坏或数据盗窃），或违反任何适用的条款/政策、法律，或您的服务及执行环境的内部规则。 本项目专注于**教育/研究**和**防御性验证**（例如：日志增长缓解以及验证故障闭环 + HITL 行为）。 其目的**并非**发布利用策略或助长不当行为。 ### 风险 / 保证 / 责任 - **使用风险自负：** 请核实相关条款/政策。 - **优先使用隔离环境：** 从本地冒烟测试开始（无外部网络；无真实系统/数据）。 - **按原样提供 / 无保证：** 提供时不附带任何形式的保证。 - **责任限制：** 在适用法律允许的最大范围内，作者对因使用代码、文档或生成的制品（包括第三方的误用）而产生的损害不承担任何责任。 ### 代码本免责声明 包含的代码本是一个**演示/参考制品**。请**勿**在实际部署中按原样使用；请根据您的要求、威胁模型和适用的政策/条款创建您自己的代码本。 代码本用于日志字段的紧凑编码/解码，**并非加密**（无保密性）。 ### 测试与结果免责声明 冒烟测试和压力运行仅验证在特定运行条件下执行的情景。 它们**不**保证实际部署中的正确性、安全性、适用性或适销性。结果可能因操作系统/Python 版本、硬件、配置和操作使用而异。 🇯🇵 **日语版本：** [README.ja.md](README.ja.md) ## ⚡ 太长不看 - **故障闭环 + HITL** 门控工作台，用于谈判/调解风格的工作流（研究/教育）。 - **可重现性优先**：种子运行 + `pytest` 契约检查（词汇表/不变量）。 - **审计就绪**：最小化 ARL 日志；可选的仅事件 ARL 索引（`INC#...`）以避免日志膨胀。 ## 概述 Maestro Orchestrator 是一个研究/教育编排框架，其优先级如下： - **故障闭环** 如果不确定、不稳定或有风险 → 不要静默继续。 - **HITL（Human-in-the-Loop，人在回路）** 需要人工判断的决策将被显式上报。 - **可追溯性** 决策流通过最小化 ARL 日志实现审计就绪且可重现。 本仓库包含实现参考（文档编排器）以及用于谈判、调解、治理风格工作流和门控行为的模拟工作台。 ## 最新更新（本仓库的变更内容） 本次更新添加了紧急契约模拟器的打包 zip 包。 - 新增：`docs/mediation_emergency_contract_sim_pkg.zip`（v5.1.2 便捷包） - 原因：可快速下载/运行以进行可重现的冒烟/压力测试（种子化），无需更改入口点 - 权威事实来源（权威逻辑）： - `mediation_emergency_contract_sim_v5_1_2.py` - `pytest -q tests/test_v5_1_codebook_consistency.py` - CI 影响：无（docs 制品；非入口点） - 注意：zip 包是**生成/便捷制品**（可审查的证据，非权威逻辑）。使用前请审查。 ### 本次更新中的修复（旧草稿 → 当前） 本次更新修复了在之前的 v5.1.2 草稿中发现的两个规模问题： - **仅事件持久化不匹配** - 问题：某些非事件事件被强制持久化为 FULL ARL 行（例如，评估/奖励），这可能导致即使在正常运行中日志也会膨胀。 - 修复：评估/奖励事件现在作为 **SUMMARY** 发出（无强制持久化）。ARL 持久化保持**仅事件**。 - **唯一 `run_id` 下的预上下文候选项增长** - 问题：当 `full_context_n > 0` 且每次运行使用唯一的 `run_id` 时，内存中的候选项缓冲区可能会在大型运行中累积。 - 修复：每次运行结束时显式丢弃每次运行的候选项缓冲区（`drop_candidates_for_run(run_id)`）。 ## 快速开始（推荐路径） 推荐使用 v5.1.x 进行可重现性 + 契约检查；v4.x 保留为旧版稳定工作台。 从一个脚本开始，确认行为和日志，然后扩展。 ### 1) 运行推荐的紧急契约模拟器（v5.1.2） 可选包：`docs/mediation_emergency_contract_sim_pkg.zip`（仅供参考） ``` python mediation_emergency_contract_sim_v5_1_2.py --runs 100 ``` ### 2) 运行契约测试（v5.1.x：模拟器 + 代码本一致性） ``` pytest -q tests/test_v5_1_codebook_consistency.py ``` ### 3) 检查 / 锁定演示代码本（v5.1-demo.1） * `log_codebook_v5_1_demo_1.json`（演示代码本；交换制品时锁定版本） * 注意：代码本**不是加密**（无保密性）。 ### 4) 可选：运行旧版稳定工作台（v4.8） ``` python mediation_emergency_contract_sim_v4_8.py pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py ``` ### 5) 可选：检查证据包（v4.8 生成的制品） * `docs/artifacts/v4_8_artifacts_bundle.zip` 证据包是测试/运行生成的制品。 权威事实来源是生成器脚本 + 测试。 ## 压力测试（默认安全） v5.1.2 旨在默认避免内存膨胀： * 仅聚合模式（默认 `keep_runs=False`）：不在内存中保留完整的每次运行结果。 * 可选：仅在异常运行时保存 ARL（带有 `INC#...` 的事件索引）。 ### A) 轻量级冒烟测试 → 中等压力（推荐坡度） ``` # 1) Smoke python mediation_emergency_contract_sim_v5_1_2.py --runs 200 # 2) 中等压力（仍为仅聚合模式） python mediation_emergency_contract_sim_v5_1_2.py --runs 10000 --seed 42 ``` ### B) 强制事件（示例：200 次运行中 10% 伪造率） 这应能可靠地创建一些异常运行，并在启用时生成 `INC#` 文件： ``` python mediation_emergency_contract_sim_v5_1_2.py \ --runs 200 \ --fabricate-rate 0.1 \ --seed 42 \ --save-arl-on-abnormal \ --arl-out-dir arl_out \ --max-arl-files 1000 ``` 输出（当发生异常运行时）： * `arl_out/INC#000001__SIM#B000xx.arl.jsonl`（事件 ARL） * `arl_out/incident_index.jsonl`（每个事件一行） * `arl_out/incident_counter.txt`（持久化计数器） 提示：保持 `--max-arl-files` 以限制磁盘增长。 ## 图表与文档 在此浏览所有图表和包：**[docs/README.md](docs/README.md)** 关键图表： * 紧急契约概览（v5.1.2）：[docs/architecture_v5_1_2_emergency_contract_overview.png](docs/architecture_v5_1_2_emergency_contract_overview.png) * 架构（代码对齐）：[docs/architecture_code_aligned.png](docs/architecture_code_aligned.png) * 未知进度 + HITL 图：[docs/architecture_unknown_progress.png](docs/architecture_unknown_progress.png) * 多智能体层级：[docs/multi_agent_hierarchy_architecture.png](docs/multi_agent_hierarchy_architecture.png) * 情感上下文流：[docs/sentiment_context_flow.png](docs/sentiment_context_flow.png) ## 架构（高层） 审计就绪且故障闭环的控制流： ``` agents → mediator (risk / pattern / fact) → evidence verification → HITL (pause / reset / ban) → audit logs (ARL) ``` ### 架构（概览，v5.1.2） 仅文档。无逻辑更改。

### 架构（代码对齐图） 下图与当前代码词汇表对齐。 仅文档。无逻辑更改。

## v5.0.1 → v5.1.2：变更内容（增量） v5.1.2 增强了模拟器在大规模运行稳定性和仅事件持久化方面的能力。 * **默认索引 + 仅聚合** * 内存中不保留每次运行的结果（防止大型 `--runs` 时的内存膨胀） * 输出侧重于计数器 + HITL 摘要（可选项） * **事件索引（可选）** * 异常运行被分配 `INC#000001...` * 异常 ARL 保存为 `{arl_out_dir}/{incident_id}__{run_id}.arl.jsonl` * 索引附加到 `{arl_out_dir}/incident_index.jsonl` * 持久化计数器存储在 `{arl_out_dir}/incident_counter.txt` 仍然保留： * 仅异常 ARL 持久化（预上下文 + 事件 + 后上下文） * 防篡改 ARL 哈希链（OSS 演示默认使用演示密钥） * 伪造率混合 + 确定性种子（`--fabricate-rate` / `--seed`） 核心不变量： * `sealed` 只能由 `ethics_gate` / `acc_gate` 设置 * `relativity_gate` 永远不会被密封（`PAUSE_FOR_HITL`，`overrideable=True`，`sealed=False`） ## V1 → V4：实际变更内容（概念性） `mediation_emergency_contract_sim_v1.py` 演示了最小可行管道： 一个线性的、事件驱动的工作流，具有故障闭环停止点和最小化审计日志。 `mediation_emergency_contract_sim_v4.py` 通过添加早期拒绝和受控自动化将该管道转变为可重复的治理工作台。 v4 中新增： * 证据门（无效/无关/伪造的证据触发故障闭环停止） * 草稿检查门（仅草稿语义和范围边界） * 信任系统（分数 + 连续记录 + 冷却） * AUTH HITL 自动跳过（通过信任 + 授权安全减少摩擦，附带 ARL 原因） ## V4 → V5：变更内容（概念性） v4 专注于具有冒烟测试和压力运行器的稳定“紧急契约”治理工作台。 v5 将该工作台扩展到制品级可重现性和契约式兼容性检查。 v5 中新增/增强： * 日志代码本（演示）+ 契约测试 通过 pytest 强制执行发出的词汇表（`layer/decision/final_decider/reason_code`）。 * 可重现性表面（锁定关键内容） 锁定模拟器版本、测试版本和代码本版本。 * 更严格的不变量执行 围绕不变量的显式测试/契约减少无声漂移。 未变更的内容（在 v5 中仍然成立）： * 研究 / 教育意图 * 故障闭环 + HITL 语义 * 仅使用合成数据并在隔离环境中运行 * 无安全保证（代码本不是加密；测试不保证实际部署中的安全性） ## 执行示例 文档编排器（参考实现） ``` python ai_doc_orchestrator_kage3_v1_2_4.py ``` 紧急契约（推荐：v5.1.2）+ 契约测试 ``` python mediation_emergency_contract_sim_v5_1_2.py pytest -q tests/test_v5_1_codebook_consistency.py ``` 紧急契约（旧版稳定工作台：v4.8） ``` python mediation_emergency_contract_sim_v4_8.py pytest -q tests/test_mediation_emergency_contract_sim_v4_8_smoke_metrics.py ``` 紧急契约（v4.4 压力） ``` python mediation_emergency_contract_sim_v4_4_stress.py --runs 10000 --out stress_results_v4_4_10000.json ``` ## 项目意图 / 非目标 意图： * 可重现的安全和治理模拟 * 显式 HITL 语义（暂停/重置/禁止） * 审计就绪的决策追踪（最小化 ARL） 非目标： * 生产级自主部署 * 无限界的自主智能体控制 * 超出明确测试范围的安全声明 ## 数据与安全说明 * 仅使用合成/虚拟数据。 * 最好不要提交运行时日志；保持证据制品最小化且可重现。 * 将生成的包视为可审查的证据，而非权威来源。 ## 许可证 Apache License 2.0（见 `LICENSE`）

标签：AI安全, AutoGen, Chat Copilot, Fail-closed, LangChain, LLM应用开发, PE 加载器, PyRIT, Python, 中间件, 人在回路, 仲裁框架, 协作式AI, 可复现性, 多智能体工作流, 多智能体系统, 安全规则引擎, 审计日志, 提示注入防御, 无后门, 时序数据库, 智能体编排, 沙箱测试, 治理机制, 源代码安全, 调解协商, 轻量级, 逆向工具