# maa-evidence-kit 中文文档

规范地址：https://npmcn.com/package/maa-evidence-kit/

版本：0\.12\.0
npm 元数据更新时间：2026-11-04T01:06:16.657Z
中文译文更新时间：2026-11-04T02:51:11.778Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/maa-evidence-kit
原文对照：https://npmcn.com/package/maa-evidence-kit/?lang=original
项目主页：https://github.com/Windsland52/MaaEvidenceKit#readme
源码仓库：https://github.com/Windsland52/MaaEvidenceKit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.3 MB，247 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.17\.0
- 运行依赖：5 个
- 首次发布：2026-08-07T02:10:16.165Z
- 最新版本发布：2026-11-04T01:06:16.269Z
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

maframework的确定性证据提取和诊断工具包

## 安装

```sh
npm install maa-evidence-kit
```

也可以使用：`pnpm add maa-evidence-kit`、`yarn add maa-evidence-kit`、`bun add maa-evidence-kit`

## README

# MaaEvidenceKit

[![npm](https://img.shields.io/npm/v/maa-evidence-kit)](https://www.npmjs.com/package/maa-evidence-kit) [![CI](https://github.com/Windsland52/MaaEvidenceKit/actions/workflows/ci.yml/badge.svg)](https://github.com/Windsland52/MaaEvidenceKit/actions/workflows/ci.yml) [![license](https://img.shields.io/github/license/Windsland52/MaaEvidenceKit)](https://npmcn.com/package/maa-evidence-kit/LICENSE) ![node](https://img.shields.io/badge/node-%3E%3D22.17-green)

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

A deterministic evidence extraction and diagnostic toolkit for MaaFramework.

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

## 能力边界

| MEK 负责 | MEK 不负责 |
| --- | --- |
| 从完整材料目录中发现受支持的 MaaFramework 日志和 Maa 项目 | 理解 GitHub Issue、GUI/自定义日志、Sentry 数据或业务结果 |
| 通过 MaaLogAnalyzer(MLA)提取会话、任务、故障、结果与运行信号 | 输出根因结论 |
| 通过 MSE 公共包提取 Interface、资源、静态诊断、任务定义和节点引用 | 模型、诊断 agent 或自动修复逻辑 |
| 显式清点 issue-time checkout 中受界的 `AGENTS.md` 文本和 Skill 文件结构 | 解析、激活或遵循 checkout 中的 Skill |
| 生成稳定 evidence ID,以及文件、行号、时间、任务和节点定位 |  |
| 输出 JSON、纯文本和可选 Mermaid |  |
| 按需在你指定的本地路径写 `feedback` JSON 包(不上传,不复制附件字节) |  |

## 安装

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

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

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

```powershell
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`](https://npmcn.com/package/maa-evidence-kit/docs/cli.md),网络与本地状态见 [`PRIVACY.md`](https://npmcn.com/package/maa-evidence-kit/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 维护。

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

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

Skill 的目录、安装方式和本地开发说明见 [`skills/README.md`](https://npmcn.com/package/maa-evidence-kit/skills/README.md)。

## 快速开始

调用方负责先解压 ZIP,再将完整文件夹交给 MEK。完整命令参考见 [`docs/cli.md`](https://npmcn.com/package/maa-evidence-kit/docs/cli.md)。

```powershell
# 自动选择可用适配器
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

```ts
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`](https://npmcn.com/package/maa-evidence-kit/docs/sdk.md)。

## 输出模型

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

三条契约级保证,字段与截断语义细节见 [`docs/evidence-model.md`](https://npmcn.com/package/maa-evidence-kit/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`](https://npmcn.com/package/maa-evidence-kit/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`](https://npmcn.com/package/maa-evidence-kit/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`](https://npmcn.com/package/maa-evidence-kit/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`](https://npmcn.com/package/maa-evidence-kit/docs/cli.md)(CLI 参考)、[`docs/sdk.md`](https://npmcn.com/package/maa-evidence-kit/docs/sdk.md)(SDK 参考)、 [`docs/evidence-model.md`](https://npmcn.com/package/maa-evidence-kit/docs/evidence-model.md)(输出模型)、[`CHANGELOG.md`](https://npmcn.com/package/maa-evidence-kit/CHANGELOG.md) (变更记录)、[`RELEASING.md`](https://npmcn.com/package/maa-evidence-kit/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 附件、日志、截图和本地上游仓库只用于本地验收,不得提交。

## 常见问题

### maa-evidence-kit 是什么？

maframework的确定性证据提取和诊断工具包

### 如何安装 maa-evidence-kit？

在项目目录运行 npm install maa-evidence-kit，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 maa-evidence、maa-evidence-probe，可以用 npx maa-evidence 直接运行。

### maa-evidence-kit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### maa-evidence-kit 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### maa-evidence-kit 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.17\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### maa-evidence-kit 可以商用吗？

maa-evidence-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### maa-evidence-kit 还在维护吗？

最新版本 0\.12\.0 发布于 2026/11/04（1 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。