#moonagentcheck

给 agent 的工具调用做一遍离线体检。

MoonBit 核心库接收一串工具事件，按确定性的规则找出“调用没有结果”“结果找不到调用”“重试太多次”“失败或未确认的调用之后仍然写入”“同一个写操作完成了两遍”这类问题。它不连接模型，也不替你做沙箱；它只检查已经观察到的事件。

#环境与安装

需要 MoonBit 工具链，且 moonc 版本不低于 0.10.14。可用 moon version --all 查看当前版本；安装和升级方式见 MoonBit 官方工具链文档。Python 3.12 只用于运行下面的离线对照 fixture，MoonBit 核心和演示不依赖 Python。

在其他 MoonBit 项目中添加已发布的 Mooncakes 包：

moon add 2515050242/moonagentcheck

当前包版本为 0.2.0，可通过 Mooncakes 安装：

moon add 2515050242/moonagentcheck@0.2.0

需要验证 GitHub 开发线时，克隆本仓库并运行 moon run main，或按下方命令执行完整回归。

#先跑起来

moon version --all
moon fmt --check src main
moon check
moon test
moon run main
python examples/python_data_agent.py
python examples/python_repository_agent.py
python examples/python_ticket_agent.py
python examples/python_adapter.py
python examples/python_openai_responses_fixture.py

moon run main 是可直接运行的 MoonBit 验收演示：它构造一个读取后写入的事件轨迹，故意重复完成同一写操作，并输出稳定的场景报告与工具指标。演示会断言重复副作用产生 AGC004，因此若核心行为回归，命令会以失败退出；GitHub Actions 也会运行此演示。

Event::new(...) 用来构造观察记录，evaluate(events, max_retries) 返回 Violation 数组，并继续保持不限制工具的兼容行为。需要配置策略时，使用 EvaluationPolicy::new(max_retries, tool_allowlist) 和 evaluate_with_policy(events, policy)：None 表示不限制工具，Some([]) 表示拒绝所有工具；allowlist 以外的调用报告 tool-not-allowed（AGC012），并继续检查其他规则。要在一次回归中检查多条独立轨迹，可用 Scenario::new(name, events) 和 evaluate_scenarios(scenarios, max_retries)；需要同时执行工具策略时改用 evaluate_scenarios_with_policy(scenarios, policy)。结果按输入顺序保留场景名称、通过状态和违规明细，每条轨迹单独评估。ScenarioCatalog::evaluate_with_policy、evaluate_tag_with_policy、evaluate_catalog_with_policy、QualityGate::check_catalog_with_policy 以及 SuiteRunner 也会传递完整策略，因此套件运行不会悄悄放宽 allowlist。工具 result 必须与同一 call_id 的 call 在工具名和 operation_id 上一致；不一致会产生 AGC011，且不能使调用成为成功。写入完成也必须在工具名和 operation_id 上关联同一调用；错配会产生 AGC016，不能借用其他工具或业务操作的成功结果。写入完成必须关联到返回明确成功结果的调用；失败或状态未知会产生 AGC010。violation_code(violation)（或按规则名调用 rule_code(rule)）将内置规则映射为稳定的机器代码（AGC001 到 AGC016），未知规则返回 unknown，方便适配器做筛选和聚合。Python 文件是离线对照 fixture，不是第二套核心实现。重复 call_id 固定以首个 call 的工具和业务操作为准，后续记录不能改写该身份；因此 result 和写入仍需匹配已建立的原始调用。

适配器也可以使用 Trace::new()、trace.call(...)、trace.result(...) 和 trace.write_complete(...) 逐步构造可回放事件流；trace_stats(...) 提供事件、调用、结果、写入以及成功/失败/未知结果的统计。summarize_violations(...) 和 summarize_scenarios(...) 可将逐事件证据聚合到规则与套件层。输入预检会报告空 call_id、空工具名、未知事件类型和负重试策略（AGC013–AGC015）。

在更完整的接入场景中，TraceQuery 负责按工具、调用、业务操作和事件窗口检索；Replay 支持逐步回放、暂停、检查点和前缀验证；diff_events 比较期望轨迹与实际轨迹；collect_metrics 汇总工具和业务操作风险；ScenarioCatalog、SuiteRunner 和 QualityGate 则提供带标签回归、运行历史和 CI 门禁。

#JSON 报告

scenario_results_json(results) 将 evaluate_scenarios 的结果转成紧凑、稳定的 JSON 数组。场景和违规项均保留输入/评估顺序；每个违规项固定包含 code、rule、event_index 与 message，适合 CI 采集和后续聚合。

let results = evaluate_scenarios(scenarios, 2)
let report = scenario_results_json(results)
// [{"name":"read-ok","passed":true,"violations":[]}]

受限回归可直接复用单一策略：

let policy = EvaluationPolicy::new(1, Some(["read_file"]))
let results = evaluate_scenarios_with_policy(scenarios, policy)
// 每个 write_file call 都会保留 AGC012 违规证据。

报告使用 MoonBit 标准库 JSON 编码器，因此引号、反斜线、换行、控制字符和中文字符串都会被正确表示；API 不读写文件，也不引入 CLI。

suite_summary_json(summarize_scenarios(results)) 输出场景通过数、失败数、违规总数和按规则聚合的稳定编码，适合作为 CI 门禁的单条汇总结果。

#策略来源报告

受限策略应由接入配置显式提供，而不能从待检查的事件里读取。PolicyContext 将策略与可读来源名绑定；evaluate_with_context 在保留既有规则的同时拒绝空来源（AGC017），evaluation_report_json 则输出可归档的来源、策略和违规报告。

let context = PolicyContext::new(
  "ci/read-only-policy",
  EvaluationPolicy::new(1, Some(["read_file"])),
)
let report = evaluation_report_json(events, context)
// {"policy_source":"ci/read-only-policy", ...}

来源只是接入方配置的标识，不是授权凭证；事件自身不能声明或扩大 allowlist。旧的 evaluate / evaluate_with_policy API 仍可用于不需要这份审计证据的调用。

#现在的边界

检查是确定性的，不访问网络、真实服务或真实文件系统；
call_id 标识一次工具调用，operation_id 标识一次可能重试的逻辑操作；
当前结果提供结构化数组、稳定规则代码和稳定 JSON 报告；不提供 CLI；
事件格式和规则会先跟着真实场景长出来，再考虑更大的适配层。

#仓库里的几条线

代码在 src/，可运行的离线样例在 examples/。docs/ 里留着选题、验收和决策记录——它们是开发过程的旁证，不是使用手册。想看整体关系，可以从架构说明、行为契约和开发记录开始。

#当前进度

当前开发线已经扩展为四层证据链：事件模型与规则评估、Trace/输入预检工具、场景与规则汇总、Python 记录适配器。策略上下文还会将实际 allowlist 与接入配置来源一并归档，避免离线报告失去权限判断的来处。Python 侧保留三类业务场景，并增加通用 adapter 与 Responses function-call fixture，共 5 个可运行 fixture；MoonBit 测试覆盖核心规则和工具层。项目仍然不重新实现 Agent 框架；扩大的是可复用的验证边界，而不是堆叠与核心职责无关的组件。每个小步都应该有能运行的测试；如果实现和假设冲突，先修正假设。

当前版本为 0.2.0：src/ 中 MoonBit 非测试源码约 4,600 行，测试源码约 1,500 行，共有 85 个 MoonBit 测试。行数只是规模审计数据，是否通过仍取决于代码是否真实可运行、功能边界是否清楚以及材料是否与仓库一致。

#许可

Apache-2.0，见 LICENSE。

Site source Report issue Packages Build queue Skills Statistics