🥮 mooncakes.io

    moonagentcheck

    agent
    contract
    testing
    moonbit
    Download zip
    Version
    0.3.0
    License
    Apache-2.0
    Repository
    Last updated
    15 days ago
    Downloads
    71

    No dependencies

    #moonagentcheck

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

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

    #十月材料入口

    项目申报书 · PDF 副本 · 验收指南 · 验收矩阵。申报正文说明范围；验收指南列出运行步骤、负例预期和当前发布状态。

    #环境与安装

    当前开发线使用 MoonBit 编译器 0.10.16+b1a0e846e 验证，CI 的三个 job 使用同一固定版本。可用 moon version --all 查看当前版本；安装和升级方式见 MoonBit 官方工具链文档。Python 3.12 用于运行接入 fixture，MoonBit 核心和无参演示不依赖 Python。

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

    moon add 2515050242/moonagentcheck

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

    moon add 2515050242/moonagentcheck@0.3.0

    仓库 master 与 october-review 的 moon.mod 与 Mooncakes 0.3.0 发布版本对齐。此版包含 AGC018、Responses 混合输出和真实 MoonBit JSON 入口；旧版 0.2.0 不包含全部十月新增行为。安装和版本核对见发布说明与版本说明。

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

    仓库的 MoonBit 示例入口还可以接收一段 JSON 字符串并输出结构化报告：

    moon run main '[{"type":"function_call","response_id":"resp-1","operation_id":"ticket-1","call_id":"call-1","name":"read_ticket"},{"type":"function_call_output","call_id":"call-1","status":"completed","outcome":true}]'

    这条命令走 MoonBit Responses 适配器和核心评估器。没有参数时运行内置重复写入演示；输入无法解析或含有未支持的输出类型时，报告会标记失败。JSON 入口包含在 0.3.0 源码包中；上述命令在克隆后的仓库根目录运行。消费方使用 moon add 后通过 @src 的公开 API 接入，不会在消费项目中自动创建同名 main 目录。

    #先跑起来

    moon version --all
moon fmt --check src main
moon build
moon check
moon test
moon run main
python -X utf8 examples/python_data_agent.py
python -X utf8 examples/python_repository_agent.py
python -X utf8 examples/python_ticket_agent.py
python -X utf8 examples/python_adapter.py
python -X utf8 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。已观察到但 ok 未知的 result 还会单独产生 unknown-result（AGC018），因此该轨迹不能被报告为通过。violation_code(violation)（或按规则名调用 rule_code(rule)）将内置规则映射为稳定的机器代码（AGC001 到 AGC018），未知规则返回 unknown，方便适配器做筛选和聚合。5 个 Python fixture 都通过子进程调用 MoonBit CLI，解析并断言其报告；Python 不独立评估行为规则。 重复 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 不读写文件；仓库中的 main 示例入口接收 JSON 字符串参数并将报告写到标准输出，不提供文件读写或网络功能。

    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 报告；仓库另有用于离线演示的 MoonBit JSON 示例入口；
    • 事件格式和规则会先跟着真实场景长出来，再考虑更大的适配层。

    #仓库里的几条线

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

    #当前进度

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

    公开发布包为 0.3.0。截至 2026-10-21，源码有 96 个 MoonBit 测试；独立消费方另有 2 项测试，验证发布包的正常结果与未知结果拒绝。数量随有效回归增加，以 CI 实际结果为准。规模数字本身不代表验收结论，仍需看功能是否真实可运行、边界是否清楚以及材料是否与仓库一致。

    #许可

    Apache-2.0，见 LICENSE。

    Powered by MoonBit

    Site sourceReport issueModulesSkillsCLIBuild queueStatistics

    © 2026 mooncakes.io