AMI — Audit Material Indexer（审计资料目录核对工具）

🌐 语言 / Language: 中文 | English

把「收到的一堆审计资料」，变成「一条可核对、可点击、可追溯、可直接被 AI 消费的目录底稿」。

一句话：收到被审计方发来的一堆文件/压缩包后，一条命令自动帮你列出一份带超链接、能打印、能打勾核对的目录表，还能自动对出「对方承诺给的清单 vs 实际交了什么」的缺漏。

状态: v2.2 稳定版 · 许可证: MIT · 作者: Roleyking

ℹ️ 别搞混：这里的 AMI = Audit Material Indexer（审计资料索引器），与 AWS / 云计算的 EC2 AMI（Amazon Machine Image）无关。此工具完全离线，不连任何云。

• 30 秒看懂它干什么
• 它解决什么问题
• 谁适合用
• 需要先装什么
• 快速上手：一个完整例子（照着做）
• 常用命令速查
• 常用参数（带例子）
• 三个输出文件，分别是谁在用
• 常见问题（FAQ）
• 安全与离线
• 给 AI / 系统集成方
• 架构（了解即可，日常用不上）
• 路线图（产品视角）
• 文档 / 相关
• 遇到问题？
• 版本历史

两条命令，两件事：

ami scan — 一键出目录索引	ami diff — 承诺清单缺项核对
12 个文件 · 7 个目录 · ZIP 套 ZIP 已穿透 · 每行文件名都是可点击的 file:// 超链接	拿对方给的 PBC.xlsx 一比，缺项 1 条（付款凭证.xlsx）立刻现形

以上画面均取自仓库内的 examples/demo-project/ —— 全部为人工构造的演示数据，不含任何真实审计资料。你可以自己跑一遍复现（见文档 / 相关）。

每次收到被审计方资料包，这几件耗时、易错、靠人肉的事，AMI 一条命令就做完：

• 审计师 / 内审 / 尽调人员 — 收到资料包，要快速出目录索引底稿（working paper）、核对 PBC 缺项、可追溯。
• 合规与内控岗位 — 需要 compliance 留痕：每份资料一个全局编号、SHA256、来源、置信度，任何时候都能回答"这份证据是什么时候、从哪里、以什么状态进入底稿的"。
• AI 审计平台构建者 — 需要一个上游"基础事实层"：先把"收到的一堆资料"变成可核对的事实清单，再喂给 AI 做分析。

不用会写代码。命令基本就一条，复制粘贴就能跑。下面每一步都给你看"你会看到什么"。

定位核心是审计，但这套"穿透索引"能力并不挑场景。任何"一个乱得不知道里面到底有啥、还层层套着压缩包"的文件夹，它都能一张表给你盘清楚。两个最值钱的点：

• 穿透压缩包：不解压，直接列出 .zip / .rar 内部结构（ZIP 套 ZIP 也会递归展开，中文文件名不乱码）。
• 点击直达：目录表每一行文件名都是可点的 file:// 超链接，点击直接跳到那个文件——哪怕是埋在 3 层子目录里、zip 包内部最深处的一个文件。

例子：一个交接/归档盘 D:\旧项目打包（archive 场景），几十个 zip，zip 里还套 zip。ami scan D:\旧项目打包 之后，Excel 里直接是 200 行、每行一个无可争议的最终文件；点其中一行，立刻打开那个藏在 web.zip\static\assets\... 最深处的文件——不用先一层层解压再按名找人。

对审计师，这是目录底稿；对普通整理/交接场景，这是含压缩包内部的全景清单。同一个内核，两种用途。

只有基础功能（列目录 + Excel + 缺项核对）的话，只需两样：

可选（不装也能跑，只是少几个高级能力）：

不确定就复制下面这一整条命令，粘贴到 cmd / 终端回车即可：

pip install -e .[archive,validate]

只想要基础功能、不想装可选组件，就:

pip install -e .

⚠️ Windows 用户：装 Python 时务必勾选 "Add Python to PATH"，否则找不到命令（见 FAQ）。装好后若 ami 没识别，改用 ami.bat（在仓库根目录）。

场景设定：你审计赵钱孙公司，对方发来一个压缩包 2026年报资料.zip，你解压后得到一个文件夹 D:\审计\赵钱孙-2026年报\被审计方材料。里面长什么样你完全不清楚。

打开 cmd（Windows）或 终端（macOS/Linux），输入：

cd D:\审计\赵钱孙-2026年报
ami scan 被审计方材料

你会看到： 屏幕刷出一份清单，结束后，被审计方材料 文件夹里多了 3 个文件：

被审计方材料\
├─ 里面的真实文件（原封不动）
├─ DIRECTORY_INDEX.xlsx   ← 主力：好打勾的目录表，用 Excel 打开
├─ DIRECTORY_INDEX.md     ← 屏幕版：用 VS Code / Typora 打开，链接能点
└─ DIRECTORY_INDEX.json   ← 系统版：给 AI / 自动化用，平时可忽略

打开 DIRECTORY_INDEX.xlsx： 每一行 = 一个文件。第 1 列是全局编号，点「文件名」那列的蓝色链接直接打开原文件，最后两列「核对状态 / 备注」留给你人工打勾和写批注。打印成 A4 就是一张工作底稿。

把对方发来的 PBC 清单（一张 Excel 表格，第一列是"文件应该长这样"的清单）放到任意位置，比如 D:\审计\赵钱孙-2026年报\PBC清单.xlsx。核对：

cd D:\审计\赵钱孙-2026年报
ami diff PBC清单.xlsx --root 被审计方材料

你会看到： 屏幕直接报数，并生成一份 PBC_DIFF.md：

PBC 清单共 120 项
  已收 115 项
  缺  5 项   ← 对方承诺了但没交的，这几项就是你要去催的
  多  7 项   ← 实交不在清单里的，可作参考

缺的那 5 项是谁，PBC_DIFF.md 里列得清清楚楚，直接照着去催话。

ami diff 对 PBC 清单的要求：一张 .xlsx，默认取第 1 个工作表的 A 列，每格一个条目（相对路径或只文件名都行）。清单不在 A 列 → 用 --column C；在别的 sheet → 用 --sheet 2。核对按相对路径优先、文件名兜底：能对齐路径最严谨（同名文件在不同子目录不会混），--match-by name 则只按文件名。

导出：默认生成 PBC_DIFF.md；加 --xlsx 得到缺项 Excel（催件/交上级更常用），加 --json 得到结构化 JSON。

ami validate D:\审计\赵钱孙-2026年报\被审计方材料\DIRECTORY_INDEX.json

返回 VALID 就说明数据完整合规，可以直接给下游系统。

💡 Windows：如果命令 ami 没识别（没加入 PATH），改用 ami.bat，如 ami.bat scan 被审计方材料。macOS/Linux 装好即用 ami。

大多数情况下上面那条 ami scan 就够了。下面这些参数按需加。

性能参考：实测可处理数千文件 + 多层 ZIP 嵌套。默认 >100MB 的文件跳过 SHA256（加 --hash-all 强制），超大目录可用 --no-hash 全程加速。

打开后一列一个意思：

折叠：Excel 左侧有 1 2 3 4 按钮，点 1 折叠到一级目录，点 2 展开二级……目录层级靠它体现。 打印：已设好 A4 横向 + 重复表头 + 页码，直接 Ctrl+P 就是工作底稿。

• Windows：装 Python 时没勾 "Add Python to PATH"，或没执行 pip install -e .。补救：每次在 AMI 仓库根目录用 ami.bat，双击或 cmd 里 ami.bat scan ...。
• macOS/Linux：确认执行过 pip install -e .；或 Python 版本 < 3.11。

ami.bat 已内置 chcp 65001 + PYTHONUTF8=1。若还乱码，先在 cmd 里手动 chcp 65001 再跑。

能。装好 rarfile + 7-Zip 后，.rar 会被当作文件夹展开（列结构，不解压）。没装就跳过 RAR。

默认自动识别（UTF-8 → GBK → CP437）。绝大多数情况不用管。个别还乱就显式指定： ami scan <资料> --zip-encoding=gbk（可选：auto / utf-8 / gbk / cp437）。

已内置公式注入防护——文件名/单元格以 = + - @ 开头会自动加 ' 转义，不会执行恶意公式。

在 Windows 上用 ami.bat 生成的一定是 Windows 路径（file:///C:/...），可点。若是在 WSL 里的路径（/mnt/...）换到 Windows 打不开，就用 Windows 原生生成。

按上面"需要先装什么"确认 Python 装好并勾了 Add PATH。多数是装时没勾。

会正常列出并标记（加密的标 [加密]/ZIP_ENCRYPTED，损坏的标异常），不会崩溃，也不影响其它文件正常扫描。

被审计方多层嵌套 + 长文件名最容易撞 Windows 的 MAX_PATH 上限。开启系统长路径支持：注册表 HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled 设为 1（或系统设置里启用长路径）。极端嵌套也可用 --max-depth 限制层级。

macOS 版 Excel 因沙盒限制，file:// 链接可能无法点击。Mac 用户建议以 DIRECTORY_INDEX.md 为主力（VS Code / Typora / Obsidian 里链接可点）。

能。.xlsx 是标准格式，WPS 正常打开，折叠按钮、核对下拉框、超链接、打印均与 Excel 基本一致。

默认是按相对路径核对（最严谨，同名文件在不同子目录不会混）。仅当你明确 --match-by name（只按文件名）或路径没对上走了"文件名兜底"时，不同目录的同名文件可能被合并计为一项。严谨场景建议用默认路径模式。

• 完全离线：不联网，资料包不出本地，适合涉密审计。
• 只读扫描：只读资料，不解压、不改写原始文件。
• 内置防护：Excel 公式注入（CWE-1236）、zip-slip 逃逸阻断、symlink 防穿透、损坏/加密/乱码 ZIP 都标记不崩溃。
• 依赖降级不炸：缺 rarfile 就跳过 RAR、缺 jsonschema 就跳过校验，核心功能照跑。

• 标准契约：flat_index 每条含 source（文件系统/ZIP 内）、confidence（FACT/INFERENCE/HYPOTHESIS/SPECULATE 四档）、check_status（核对态）、sha256，全部 schema 校验。想看结构：ami inspect。
• 消费场景：后续 policy-audit（内控文档定位）、a-stock-hv-desk（横向纵向分析）都以此为上游。
• 下一步：MCP server 入口（ami mcp）已规划，让 AI agent 直接调用 scan / diff。

ami (CLI, 可 pip 安装)
  ├─ scan      → scanner (ScanResult 双轨: tree + flat_index)
  │                └─ json_writer / md_writer / excel_writer
  ├─ diff      → differ (PBC 缺项核对)
  ├─ validate  → schema 校验
  └─ schema — 全模块共享的单一数据契约（唯一权威定义）

每个模块自带自包含 smoke test（共 60 项 / 6 模块），从仓库根运行：

python -m ami_lib.schema        # 15 项
python -m ami_lib.scanner       # 17 项
python -m ami_lib.json_writer   # 6 项
python -m ami_lib.md_writer     # 5 项
python -m ami_lib.excel_writer  # 8 项
python -m ami_lib.differ        # 9 项

• README-en.md — English version
• examples/demo-project — 可复现演示包：ami scan examples/demo-project/provided-materials + ami diff examples/demo-project/PBC.xlsx --root examples/demo-project/provided-materials，一次看懂扫描（含 ZIP 套 ZIP 穿透）与缺项核对
• examples/sample-data — 自带极简样本，ami scan examples/sample-data 可先跑通一遍
• examples/rar-fixtures — 公开 RAR fixture，配 scripts/e2e-rar.py 做 RAR 回归
• examples/media — README 里的截图与 GIF；由 python scripts/build-demo-media.py 一键重新生成（纯 PIL 渲染，离线可复现）。想换成自己的录屏：直接覆盖同名文件（ami-demo.gif / ami-scan-demo.png / ami-diff-demo.png）即可，README 无需改动；脚本靠哈希识别出手工录屏并自动保护，不会覆盖（--status 查看，--force 才强制重画）
• CONTRIBUTING.md — 贡献指南（含 60 项 smoke test 说明）
• LICENSE — MIT

隐私声明：本仓库 examples/ 下所有示例（演示数据、RAR fixture 等）均为人工构造的公开演示数据，不含任何真实审计或客户端资料。真实需求是真的、演示数据是假的。AMI 不上传任何数据，资料全程不出本地。

• 提 bug
• 提 feature

• v2.2.0 (2026-08-19) — ami diff PBC 缺项核对 + pip install -e . 打包 + 3 个 P0 安全修复（目录行公式注入 / zip-slip 前缀边界 / GBK 自测）
• v2.1.0 (2026-08-19) — --zip-encoding 参数（ZIP 文件名编码自动识别）
• v2.0.0 (2026-08-18) — 完整重构：ZIP 递归、方案 C 双路径、RAR 支持、安全加固、3 轮独立审查 27 问题修复
• v1.0.0 — 原始 dir-tree-index.py（md + Excel 双输出）

AMI v2.2.0 | 2026-08-20 | by Roleyking