MaaEvidenceKit

面向 MaaFramework 的确定性证据提取与诊断辅助工具包。

A deterministic evidence extraction and diagnostic toolkit for MaaFramework.

MaaEvidenceKit(MEK)从 MaaFramework 日志和 Maa 项目中提取可定位的运行时与静态事实, 供 Codex、Claude Code 等外部 harness 按需使用。MEK 不包含模型、诊断 agent 或自动修复逻辑。

能力边界

安装

需要 Node.js 22.17+。发布版用户先安装 CLI:

npm install --global maa-evidence-kit@latest
maa-evidence --version

如果要让 Codex、Claude Code 等 agent 使用 MEK,再从 GitHub 安装用户级 Skill。不要自行 拼接 agent 的 Skill 目录;skills CLI 会检测或询问目标 agent,并维护各 agent 所需的路径:

npx skills add https://github.com/Windsland52/MaaEvidenceKit `
  --skill maa-evidence `
  --global

交互安装时优先使用默认的符号链接方式,使多个 agent 指向同一个受管副本。Skill 和 CLI 仍是两个 独立的分发物,安装 Skill 不会自动安装 npm 包;Skill 需从 GitHub 地址安装以保留远端来源,本地路径 安装只适合开发,无法被 skills update 跟踪远端版本。

发布版 CLI 在分析命令和 --version 启动时自动维护 CLI 与受管 Skill 的版本。只有交互式终端 (或显式设置 MAA_EVIDENCE_AUTO_UPDATE=1)才会做更新工作:非交互调用、agent、管道输出都不再为 它付出 npm exec 的秒级开销,也不会被 npm 的 notice 行污染 stderr。检查至多每 24 小时一次, 发现更高稳定版就让本次命令由该精确版本执行;探测与命令交接都以 maa-evidence-probe 别名 运行,装着旧全局版的机器上同名 shim 不再冒充目标版本。接力的实际执行者由子进程写下的 marker 文件核验:版本不符或 marker 缺失按无法交付处理,同样给出落后提示——npm 的名字解析是未受控 变量,机制正确性不依赖它。更新无法交付时(探测失败会记住该版本 并在 24 小时内不再重试),stderr 至多每 24 小时给出一行落后提示与确切的升级命令,随后沿用当前 版本。MAA_EVIDENCE_AUTO_UPDATE=0 完全关闭更新,CI 默认关闭,SDK import 不执行更新。机制与 updates.json 的说明见 docs/cli.md,网络与本地状态见 PRIVACY.md。

Skill 与 CLI 分开分发,可能版本不一致。Skill 正文不写版本号(写死就得每次发版改,而且对从 仓库安装的副本仍是错的):用 maa-evidence skill --check <skill-dir> 逐文件比对已安装副本与当前 CLI 自带的那份(same/different/missing),用 maa-evidence skill --print --format json 取 包版本与逐文件 sha256,用 maa-evidence skill --install <dir> 从包内离线写入一份字节精确的副本。 <skill-dir> 两种写法等价:skills 根目录(如 ~/.agents/skills),或已安装的那份 Skill 目录本身 (如 ~/.agents/skills/maa-evidence);后者按副本本身判定,--install 就地刷新而不是再套一层。 副本本身是符号链接时 --check 跟随链接判定,--install 会拒绝写入并退出 1——那种形态由 skills CLI 更新。 受管安装仍由 skills CLI 维护。

开发本仓库时使用本地构建:

$env:MAA_EVIDENCE_AUTO_UPDATE = "0"
pnpm install
pnpm build
node dist/cli/main.js --help

Skill 的目录、安装方式和本地开发说明见 skills/README.md。

快速开始

调用方负责先解压 ZIP,再将完整文件夹交给 MEK。完整命令参考见 docs/cli.md。

# 自动选择可用适配器
maa-evidence inspect C:\path\to\materials --format json --output inspection.json

# 只检查 MaaFramework 日志,可按时间缩小证据范围
maa-evidence mla inspect C:\path\to\materials --from 2026-09-01T20:12:00 --to 2026-09-01T20:22:00 `
  --format json --output inspection.json

# 先看覆盖再决定是否支付解析:清单只有 artifact 清单,不跑抽取
maa-evidence mla inspect C:\path\to\materials --format manifest

# 先读摘要:artifacts / warnings / statistics 和各 evidence kind 的数量
maa-evidence mla inspect C:\path\to\materials --summary --format text

# 要完整 JSON 又不想几 MB:按预算整条删,并在 reduction 里记录删了什么
maa-evidence mla inspect C:\path\to\materials --max-report-bytes 4194304 --output inspection.json

# 只检查指定项目任务
maa-evidence mse inspect C:\path\to\project --task StartUp --format text

# 清点 issue-time checkout 里的 AGENTS.md 与 Skill 结构(确定性,不解释内容)
maa-evidence repo-docs C:\path\to\issue-checkout --format json

# 从已有结果中读取某条证据及其来源上下文
maa-evidence view --input inspection.json --evidence-id evidence-abc123 --format text
maa-evidence window --input inspection.json --evidence-id evidence-abc123

# 事后复核:从已存报告出同一份清单,零语料访问
maa-evidence view --input inspection.json --format manifest

# 只要结构化结果里的几个字段,不必自己写脚本解析整份 JSON
maa-evidence view --input inspection.json --fields statistics --format json
maa-evidence search --input inspection.json --kind mla.failure `
  --fields totalMatches,returned,evidence.id --format json

# 每任务的“时间 事件 节点名”压缩时间线,可用 --task 过滤
maa-evidence timeline --input inspection.json --task Combat --format text

# 确认正在读的 Skill 与正在跑的 CLI 是否为同一份(逐文件 same/different/missing)
maa-evidence skill --check ~/.agents/skills

每个命令都有自己的 --help(maa-evidence mla inspect --help),列出该命令真正接受的选项、 默认值与上限;inspect(MLA+MSE 组合)与 mla inspect(仅运行时)是两条不同代价的路径,不要 混用。

SDK

import {
  inspect,
  inspectMla,
  inspectMse,
  inspectRepositoryDocs,
  searchEvidence,
  selectFields,
  view,
} from "maa-evidence-kit";

const runtime = await inspectMla("C:/debug", {
  timeRange: { from: "2026-07-19 10:00:00", to: "2026-07-19 10:10:00" },
});
const project = await inspectMse("C:/project", { tasks: ["StartUp"] });
const combined = await inspect("C:/materials");
const repositoryDocs = await inspectRepositoryDocs("C:/issue-checkout");
const text = view(combined, { format: "text" });
const matches = searchEvidence(combined, {
  kinds: ["mla.recognition_detail"],
  nodes: ["DailyProtocolMissionsPick"],
  limit: 20,
});
// 只取需要的字段:路径不存在会报错,不会静默得到 undefined
const counters = selectFields(combined, ["statistics.failures"]);

完整 API、选项语义与后续追问建议见 docs/sdk.md。

输出模型

核心输出使用 maa-evidence/v1,包含 artifacts、evidence、missingEvidence、warnings、 statistics 和 details。每条 evidence 都有稳定 ID 与来源定位;截断、缺失和上游限制都会作为 显式的 warning / missingEvidence 输出,不会静默丢失。

三条契约级保证,字段与截断语义细节见 docs/evidence-model.md:

• 不越界登记:未支持文件、repo-docs 与图片只做有界登记——未支持文件给路径、大小与修改时间, AGENTS.md 给受界文本,SKILL.md 只登记路径与结构,图片按扩展名或文件签名登记格式;不推断 语义,范围、固定上限与截断状态都在输出中公开,是否读原件由 harness 决定。
• 摘要只是等值事实:被失败引用的图片带 sha256: 内容摘要,可按捕获画面分组失败,但不证明是 同一次观测,记录与 evidence ID 也不会因此合并;没有摘要即“未判定”。
• 不伪造最终配置:pipeline override 保留日志中可解析的原始 patch 序列,仅在唯一 Context-to-task 映射时标记 task 关联,不做 JSON 深合并;作用域不明、截断和解析不完整显式暴露。

Harness Skill

skills/maa-evidence/SKILL.md 指导外部 agent 按需选择 MLA、MSE、 repo-docs、证据窗口和文本视图,而不是对每个问题都运行完整检查。核心约定:

• 从回答问题所需的最小操作开始;通用 GUI/自定义日志由 harness 自行解析,MEK 只清点不解释。
• Issue 调查走分阶段快路径:日志就绪即运行聚焦 MLA,确需节点定义、配置阈值或静态执行关系时才 获取 issue-time 源码并运行聚焦 MSE,用 --git-ref 固定 issue 时点而不是当前工作树。
• 结论引用稳定 evidence ID 与文件/行/时间/任务/节点定位,并区分症状、机制与疑似诱因。
• Sentry 调查由 harness 直接使用 Sentry MCP/CLI 完成;MEK 不接收 Sentry 凭据也不查询应用项目。 把 Issue 与 Sentry 事件认定为同一次发生,需要共享 event_id/run_id 之类的关联证据,不能只凭 时间与版本;详细规则见 skills/maa-evidence/references/sentry.md。
• 进阶语义按需阅读 references/:full-guide.md 覆盖 override 检索、镜像日志、字节相同副本、 目录回退与三层缓存等规则,reporting.md 对接最终报告产出,maa-llm-wiki.md 查框架字段与 API 语义。

反馈与隐私

核心检查离线运行,没有遥测:MEK 没有分析端点、不打包 Sentry 客户端、没有安装标识,也没有任何 上传检查结果的代码路径。唯一的网络访问是自动更新,MAA_EVIDENCE_AUTO_UPDATE=0 可完全离线。

maa-evidence feedback --message TEXT --out FILE 只在你指定的路径写一份本地 JSON 包:消息、类别、 组件,以及每个附件的路径/大小/sha256。附件字节不会进包,也不会被 MEK 发送——包交给什么渠道由你 决定;--preview 只打印不写文件。完整口径见 PRIVACY.md。

架构

单包 TypeScript 项目,src/ 下按域划分:evidence/(事实、来源、稳定 ID、原文窗口)、mla/(日志发现与 MLA 集成)、mse/(MSE 集成与静态关系图)、repo-docs/(仓库说明与 Skill 文件结构清点)、 views/(JSON、文本、Mermaid)、feedback/(本地反馈包)、cli/(命令行入口), 外加 profiling.ts(本地旁路阶段计时)、inspect.ts(可选组合)与 index.ts(SDK 公共入口)。

依赖固定为精确版本,并只使用 MSE 的公开包。项目没有 Python、LangGraph、MCP 或内置模型。

文档与开发

文档:docs/cli.md(CLI 参考)、docs/sdk.md(SDK 参考)、 docs/evidence-model.md(输出模型)、CHANGELOG.md (变更记录)、RELEASING.md(发布步骤与手工验收清单)。

发布前运行 pnpm release:check(= pnpm lint + pnpm typecheck + pnpm test + pnpm build, 再打包 tarball,在临时消费项目中安装并验证 SDK import 和 CLI 入口)。推送与包版本一致的 v<version> tag 后,GitHub Actions 通过 npm trusted publishing(OIDC)自动发布到 npm,不需要 长期 token。

真实 Issue 附件、日志、截图和本地上游仓库只用于本地验收,不得提交。