ppt-master Prompt Audit：面向 Agent 文档语料的 Token 预算与治理 Lint 体系全解

ppt-master Prompt Audit：面向 Agent 文档语料的 Token 预算与治理 Lint 体系全解

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master

本文围绕 prompt_audit.md 展开，完整讲解 ppt-master 仓库中这套维护者专用、只读的“提示词预算与治理审计”工具：它如何精确计量 Agent 可读 Markdown 语料的 token 消耗、如何强制每个文档都归属某个加载场景、如何用指纹裁决跨文件重复与 schema 字段的多处定义漂移。读完后，你能理解该仓库如何把“上下文预算”变成可验证、可审计的工程指标，并掌握运行、排错与 manifest 维护的完整流程。

定位：为什么 ppt-master 需要一个 Prompt Audit

ppt-master 的核心工作方式，是让 AI Agent 按路由规则按需读取 SKILL.md、各 role/workflow 文档以及模板目录中的说明文件。文档一旦膨胀，Agent 的上下文窗口就会被稀释，关键指令可能被挤出注意力范围。为此仓库提供了一套审计工具：

• 工具本体：prompt_audit.py（约 2400 行的单文件实现）；
• 审计夹具：prompt_audit_manifest.json（约 2400 行，人工转录 SKILL.md 与 role/workflow 文档中的读取规则）；
• 使用文档：prompt_audit.md，即本文的主体。

原文明确了三条边界约束：

1. 仅维护者使用、严格只读——审计过程不修改任何被审计文档；
2. 故意不接入 CI 或 pre-commit 钩子——它不是构建门禁，而是人工治理工具；
3. 生成角色永远不加载这份文档、这个工具或它的 manifest——manifest 中标记audit_only: true、runtime_consumed: false，它只是 lint 夹具，绝不是提示词上下文。

这条“审计元数据与运行时上下文隔离”的设计，是理解整套体系的前提：它保证审计配置永远不会反过来占用它要守护的 token 预算。

运行方式与依赖

文档给出的运行命令：

python3 skills/ppt-master/scripts/prompt_audit.py # 文本摘要 python3 skills/ppt-master/scripts/prompt_audit.py --json # 稳定 JSON 报告

依赖tiktoken（不属于 requirements.txt——终端用户永远不需要它）：

pip install 'tiktoken>=0.7.0'

退出码约定：出现任何确定性 error 时退出码为1。未被裁决（adjudicated）的精确重复或 schema 投影属于可行动的 warning；启发式的近重复候选只是报告信息，不进入findings。加--json后，连环境/配置类失败也会输出稳定的AUDIT_SETUP_ERRORJSON 信封，而不是 traceback 或纯文本错误。

结合 prompt_audit.py 中build_parser()的实现，完整 CLI 实际还支持两个文档未列出的参数：

main()的收尾逻辑（prompt_audit.py）证实了文档的退出码约定：run_audit()抛出的AuditError统一返回 1；否则只要report["summary"]["errors"]非零就返回 1。而run_audit()的编排（prompt_audit.py）按固定顺序串联了语料发现、token 计数、文件预算、注册表、加载集、覆盖、重复、引用图、权限边、注册表断言、schema 语法共十一个阶段，最后按严重度排序输出 findings——这解释了为什么报告结构是稳定的、可被脚本消费的。

审计对象：语料定义与精确 token 计数

manifest 的documents区块决定了“什么属于被审计语料”（prompt_audit_manifest.json）：

"documents": { "include": [ "AGENTS.md", "skills/ppt-master/**/*.md", "skills/ppt-master/templates/charts/charts_index.json", "skills/ppt-master/templates/tables/tables_index.json", "skills/ppt-master/templates/schemas/*.json" ], "exclude": [], "max_tokens": 555000 }

也就是说，语料是“全部 Agent 可读文档 + 两份机器注册表 + 两份校验 schema”，语料级预算上限为 555000 token。加载器load_manifest()（prompt_audit.py）会对 manifest 做严格校验：schema_version必须为 1、audit_only必须为true、runtime_consumed必须为false、budget_policy必须保持fixed_upper_bound、encoding必须保持o200k_base——任何一条不满足都直接AuditError。

token 计数在count_documents()中完成（prompt_audit.py）：使用tiktoken的o200k_base编码对全文调用encoder.encode(text, disallowed_special=())，得到的是精确的 tokenizer 单位，而不是字符数估算。这是整套“预算”概念可信的根基：审计比对的双方（文档声称的加载规则与实际 token 量）都基于同一把“尺子”。

What It Checks：检查面总览

文档给出的检查面表格如下，本文后续小节逐一展开：

预算体系：三级上限与 fixed_upper_bound 政策

三级预算

• 语料级documents.max_tokens（555000）：所有语料文件 token 总和，超预算报BUDGET_CORPUS（prompt_audit.py）；
• 热文件级file_budgets：manifest 为 60 多个核心文件逐一设定上限（prompt_audit_manifest.json），例如AGENTS.md: 3250、skills/ppt-master/SKILL.md: 2500、skills/ppt-master/references/executor-base.md: 12000、skills/ppt-master/workflows/generate-pptx.md: 11000。超限报BUDGET_FILE（prompt_audit.py）；
• 场景级load_sets.*.max_tokens：每个“路由/阶段”声明的场景有独立预算，超限时maximum计算值超预算报BUDGET_LOAD_SET（prompt_audit.py）。

load set 的 min / typical / max 计算

audit_load_sets()（prompt_audit.py）把每个场景解析为两类成员：

• 固定文件（files中的字符串路径）：token 全额计入；
• 选择器（files中的{glob, exclude, select, registry, load_event}对象）：审计时对 glob 展开后的候选按 token 排序，取最轻select个得到min_tokens、最重select个得到max_tokens、均值×select 得到typical_tokens（prompt_audit.py）。场景判定以max为准：maximum <= budget则 pass，否则 fail。

选择器还携带治理语义：

• registry：声明该 glob 的候选 id 集合必须与某个注册表完全一致，否则报选择器/注册表漂移（drift）错误（prompt_audit.py）；
• allow_repeat：允许与固定文件或其他选择器重叠，但必须命名load_event说明重复加载的业务触发点（prompt_audit.py）；
• include：场景可以递归组合其他场景，resolve_entries()做了去重与环检测（Load-set include cycle）。

manifest 中可以看到这套组合的实际形态：bootstrap.routing（AGENTS.md + SKILL.md + routing.md，预算 8000）是根场景，route.generate.planning在其之上叠 13 个固定文件加 3 个注册表选择器（modes 选 5、visual-styles 选 18、image-renderings 选 20），预算 130000（prompt_audit_manifest.json）；更重的route.generate.flat-ai-two-types预算 230000，route.generate.quick-generate.video-design预算 180000。

fixed_upper_bound：预算是“固定上限”，不是“当前值+余量”

这是文档最有治理思想的一条规则，budget_policy: fixed_upper_bound：预算是稳定、刻意取整的限额，而不是对当前 token 数的镜像。源码_validate_fixed_budget()（prompt_audit.py）强制执行取整规则：

• 小于 10k：必须为 250 的整数倍；
• 小于 100k：必须为 1k 的整数倍；
• 100k 及以上：必须为 5k 的整数倍；

不满足直接AuditError，所以任何人无法把预算偷偷改成“当前值+1”这种贴地数值。

文档规定的调整流程：

1. 设立：预留约 10% 工作余量，向上取整到上述步进；
2. 不许随意动：一旦通过，既不上调也不下调（包括“提示词涨了、把预算抬回去恢复余量”也不允许）；
3. 唯一上调触发：当前审计针对该上限报了BUDGET_CORPUS/BUDGET_FILE/BUDGET_LOAD_SET，然后选一个余量相当的下一档整数，并在同一次变更中记录触发溢出的范围，之后保持不动直到下一次真实溢出。

manifest 里留痕充分印证了这个纪律：大量 load set 的description写着 "Ceiling raised after BUDGET_LOAD_SET reported 76053 tokens"、"Ceiling raised after BUDGET_LOAD_SET reported 116384 tokens"（prompt_audit_manifest.json）等——每次上调都对应一次真实的审计失败记录，形成可回溯的预算变更史。

覆盖检查：每个文档必须“有户口”

audit_load_coverage()（prompt_audit.py）强制：每个语料文件要么被某个 load set 覆盖，要么在coverage.exempt中有一条带一行理由的豁免，否则逐个文件报LOAD_COVERAGE_GAP。

豁免条目不是随意的 glob 白名单——加载器要求每条豁免都有非空glob和非空单行reason（prompt_audit.py），运行时还会检查三种病态：

• COVERAGE_EXEMPT_STALE：豁免 glob 匹配不到任何语料文件（prompt_audit.py）；
• COVERAGE_EXEMPT_DUPLICATE：两条豁免 glob 重叠命中同一文件；
• COVERAGE_EXEMPT_OVERLAP：豁免 glob 命中了已在 load set 中的文件（豁免和覆盖互斥）。

当前 manifest 的豁免区（prompt_audit_manifest.json）给出了豁免判例：workflows/index.md（维护者清单）、scripts/docs/prompt_audit.md自己（维护者专用文档）、templates/schemas/*.json（机器消费的校验 schema，从不进入模型上下文）、各THIRD_PARTY_NOTICES.md（合规声明）、references/image-palettes/*.md（legacy 墓碑，_index.md明确禁止加载）等。文档给出的豁免准则是：只豁免永远不会进入 role 上下文的物料（legacy 墓碑、生成型维护资产、维护者专用文档、许可声明），而“条件性运行时读取”应该表达为增量 load set，而不是豁免。

重复裁决：精确重复、近重复与 accepted 指纹

段落抽取与归一化

extract_paragraphs()（prompt_audit.py）把 Markdown 按空行/标题/代码围栏切成文本块，剥掉链接语法与格式符、压缩空白并转小写得到normalized，只保留长度 ≥min_chars（manifest 配 100）的块。

精确重复

find_exact_duplicates()（prompt_audit.py）按归一化文本分组，同一归一化文本出现在≥2 个不同文件即构成一个候选组，并计算sha1(排序拼接原文)[:12]指纹（_duplicate_fingerprint，prompt_audit.py）。候选组总数非零时产生一条DUPLICATE_EXACT_CANDIDATESwarning。

近重复（信息级，不产 finding）

find_near_duplicates()（prompt_audit.py）是纯启发式：对词数 ≥min_words（20）的段落提取shingle_words（4）词级 n-gram，经倒排索引 + 频率剪枝（max_shingle_frequency24）粗筛，要求共享 shingle ≥ 3、共享/并集比 ≥ 0.18，最后用SequenceMatcher.ratio()复核，相似度 ≥near_similarity（0.82）才列为候选。这些候选只出现在 JSON 报告的duplicates.near中，从不进入 findings——文档明确它是“heuristic maintenance information”。

accepted：裁决身份是三元组

文档强调：接受一条重复的“身份”是kind+fingerprint+paths三者的组合，因此两个路径对即使散文完全相同也能被独立裁决。加载器对duplicates.accepted的校验（prompt_audit.py）要求kind ∈ {exact, near}、12 位十六进制指纹、唯一非空路径列表、单行 reason，且同一身份不得重复登记。

审计时的对账逻辑：当前重复候选与 accepted 按身份匹配；已接受但匹配不上任何当前重复 → errorDUPLICATE_ACCEPTED_STALE（prompt_audit.py），因为编辑任一原始块都会改变指纹；而--skip-near-duplicates有意不对已接受的 near 对做检查——该扫描根本没跑，跳过是安全的。

当前 manifest 的判例（prompt_audit_manifest.json）很有代表性：品牌预设模板design_spec.md之间共享固定章节样板（如 7 家企业品牌预设共享同一份“专有字体回退契约”段落，reason 为 "Corporate brand presets share the same proprietary-font fallback contract by design."）、三个生成型对比资产 manifest 共享同一 header 等。这类“设计上就该相同”的段落通过 accepted 从 warning 中移除，但仍在 JSON 报告的exact_accepted中可见——裁决本身保持可审计。

注册表断言与声明式词汇投影

audit_registries()（prompt_audit.py）核对“文档声称的目录规模/条目”与真实注册表是否漂移，覆盖四类注册表（_registry_ids()，prompt_audit.py）：

对应的失败类包括：id 重复（REGISTRY_ID_DUPLICATE）、结构化注册表缺号/多号/顺序错乱（REGISTRY_IDS_MISSING/REGISTRY_IDS_EXTRA/REGISTRY_ID_ORDER）、文档正文里声称的条目数与注册表不符（REGISTRY_COUNT_MISMATCH，通过一组“N charts/entries/summaries…”计数短语正则识别）、validate_index_links开启时索引标签/目标/成员三方不一致（REGISTRY_INDEX_*），以及对已删除编号格式的引用（REGISTRY_ID_LEGACY，如#single_1这类旧 id 或纯数字 id 一律报错）。

文档单独强调的声明式投影（projection）机制：为注册表声明projection.source+ 带id命名组的entry_pattern（JSON list 注册表还需id_field），审计要求投影出的 id 与注册表完全相等，拒绝重复、缺失、多余三种漂移（REGISTRY_PROJECTION_ID_DUPLICATE/REGISTRY_PROJECTION_MISMATCH）。实例见 manifest：chart-templates注册表（charts_index.json）投影到 chart-vocabulary.md，条目模式^\|\s*\chart/(?P [a-z0-9_]+)`\s*|；sound-cues（sounds_index.json，id_field: "id"）投影到 [sound-vocabulary.md](https://link.gitcode.com/i/fce429bfcd6503deadd7b71751f4952d)。这保证“给 Agent 看的词汇表”和“给校验器用的机器目录”永远同步——这正是 load set 里registry` 选择器能成立的前提。

Schema 多定义治理：owner 契约与投影指纹

audit_schema_grammars()（prompt_audit.py）解决另一个 Agent 文档语料的顽疾：同一 schema 字段的“文法”散落在多个 Markdown 里，一旦 schema 改了、下游文档没同步，Agent 就会拿着过期契约执行。

owner 必须带“字段局部定义信号”

文档规则：每个配置字段必须在声明的 owner 中有字段局部的定义信号。字段属于不同 artifact 时应拆成不同 owner 条目；长行里泛泛的key/value散文不算语法信号，显式赋值、字段局部文法/格式措辞、field ... one of ...之类的形式才算。实现上由_has_schema_grammar_signal()（prompt_audit.py）判定：字段名后紧跟:/=、上下文出现 grammar/syntax/format/allowed values/one of 等词、as \<...>`占位形式、:模式、writes/records/declares/projects/emits 等写动词等。owner 若是 JSON schema，还会抽取该字段的 definition/rule/membership 片段做指纹（_schema_owner_fragments`， prompt_audit.py）。

accepted 投影：精确裁决而非路径豁免

文档流程：跑--json，把该字段的owner_fingerprint与每个已审查投影的path/fingerprint抄进schema_grammars[]条目；每个投影必须分类为producer/consumer/reference/compatibility四种角色之一（与源码_SCHEMA_PROJECTION_ROLES，prompt_audit.py，一致），并记一行 reason。文档给出的示例：

{ "source": "skills/ppt-master/templates/schemas/spec_lock.schema.json", "fields": ["page_rhythm"], "scan": ["skills/ppt-master/**/*.md"], "accepted": [ { "field": "page_rhythm", "owner_fingerprint": "0123456789ab", "projections": [ { "path": "skills/ppt-master/references/executor-base.md", "role": "consumer", "fingerprint": "abcdef012345", "reason": "Executor needs the selected page-rhythm key and closed values." } ] } ] }

指纹语义：owner 指纹覆盖该字段的 owner 契约；投影指纹覆盖该路径下该字段所有当前“类语法行”。于是：

• owner 编辑、投影编辑、投影被删除 → errorSCHEMA_ACCEPTED_STALE；
• 新出现的字段/路径投影 → warningSCHEMA_MULTIDEF_CANDIDATE；
• JSON 报告按schema_grammars[].open / .accepted / .stale三分区输出，让“已裁决的投影”与“漂移”都保持可审计，同时避免把 stale 的 accepted 路径变成重复 warning。

当前 manifest 对 spec_lock.schema.json 配置了 10 个字段的投影审计（font_family、page_rhythm、pptx_masters等，prompt_audit_manifest.json）。例如page_rhythm的 accepted 列表展示了四种角色的真实分工：executor-base.md 是 consumer（执行者需要选定的键与封闭取值）、strategist.md 是 producer（规划时把 owner 字段投影进规划契约）、spec_lock_reference.md 是 reference（镜像 owner 文法边界）、plan-core.md 同样是 reference，但 reason 更具体："the shared planning core states the reading-mode lean of the tag as a bias, not a quota; the grammar stays with the schema"。

引用图与声明式权限边

extract_references()（prompt_audit.py）抽取语料中所有非围栏、非外链（跳过 http/https/mailto/data/javascript、纯锚点、${模板占位）的本地 Markdown 链接：

• 目标不存在 → errorREFERENCE_MISSING；
• 目标逃出仓库根 → errorREFERENCE_OUTSIDE_ROOT；
• 行内含 "authority / source of truth / owns / 权威 / 唯一事实源" 等词（_AUTHORITY_TERMS_RE，prompt_audit.py）的边标记为authority_candidate。

在引用边上跑 Tarjan 强连通分量，报告循环引用组。authority_edges则是 manifest 中显式声明的“关注点级权限 DAG”：audit_authority_graph()（prompt_audit.py）逐 concern 做 SCC，成环报AUTHORITY_CYCLE；run_audit()再校验每条声明边必须真实存在于 Markdown 引用图中，否则报AUTHORITY_EDGE_UNREFERENCED（prompt_audit.py）——防止声明了文档里根本不存在、或已被删掉的权威关系。

Manifest 维护流程（文档原节完整继承）

文档的核心运维章节“Manifest Maintenance”逐条对应源码行为，以下是完整继承与补充：

总原则：manifest 是审计专用夹具（audit_only: true、runtime_consumed: false），人工转录SKILL.md与 role/workflow 文档中陈述的加载规则，因此那些文档中任何读取规则的变更，必须在同一次变更中更新对应的 load set——覆盖检查只能抓住“未分类的新文件”，而“既有文件读取规则变了”只有人能抓住。

1. 新增语料文件：若无匹配现有类别豁免，审计以LOAD_COVERAGE_GAP失败，直到你把它加入读取它的 load set、或给出一行理由的豁免。豁免只适用于永不进入 role 上下文的物料（legacy 墓碑、生成型维护资产、维护者专用文档、许可声明）；条件性运行时读取应表达为增量 load set。
2. 有意精确重复：跑--json，把候选的kind、fingerprint、paths连同 reason 抄进duplicates.accepted。接受身份是三者组合，故散文相同的不同路径对保持独立可审。编辑任一原始块会改变指纹，过期接受报DUPLICATE_ACCEPTED_STALE。
3. 近重复：duplicates.near只是启发式维护信息，不产生 warning；维护者仍可把稳定的有意 near 对记入duplicates.accepted，但--skip-near-duplicates有意不对已接受的 near 对做检查（该扫描未运行）。
4. 注册表投影：声明projection.source+ 带id命名组的entry_pattern；JSON list 注册表另需id_field。审计要求投影 id 与注册表完全一致，拒绝重复/缺失/多余。
5. Schema owner：每个配置字段必须在声明 owner 中有字段局部定义信号；分属不同 artifact 的字段应拆成不同 owner 条目；长行中泛化的key/value散文不构成语法信号，显式赋值、字段局部文法/格式措辞、field ... one of ...形式才算。
6. 有意 schema 投影：见上文 JSON 示例；接受是“精确的”，不是路径豁免；owner/投影编辑或投影删除报SCHEMA_ACCEPTED_STALE，新字段/路径投影报SCHEMA_MULTIDEF_CANDIDATE；JSON 报告分离open/accepted/stale三态。
7. 预算上限（budget_policy: fixed_upper_bound）：预算是稳定、刻意取整的限额；新上限留约 10% 余量并按 250（<10k）/1k（<100k）/5k（≥100k）步进向上取整，manifest 加载器强制步进；设定后不升不降，唯一上调条件是当次审计对该上限报了BUDGET_CORPUS/BUDGET_FILE/BUDGET_LOAD_SET，然后选相近余量的下一档整数、同次变更记录触发溢出的范围，并维持到下一次真实溢出。

阅读输出：文本摘要与 JSON 报告结构

默认文本摘要由render_text()生成（prompt_audit.py），固定版块依次为：

• Manifest 状态行（audit-only / runtime loading disabled / fixed upper bounds）；
• 语料规模：文件数、token 总量、语料预算；
• 覆盖统计：load sets 覆盖数 / 豁免数 / 未覆盖数；
• Findings 计数（error / warning）；
• 每个 load set 一行PASS/FAIL name: min / typical / max <= budget；
• 各注册表条目数与 id 区间；
• 候选概览：精确重复组数 + 已接受数、近重复对数、引用图边数与循环组数、权限候选边与候选环数、schema 投影 open/accepted/stale 计数；前 5 条精确/近重复示例（path:line <-> path:line）；
• 每文件 token 排行；
• 逐条 finding：[SEVERITY CODE] path:line message。

--json报告（run_audit()返回结构，prompt_audit.py）字段包括schema_version、encoding、manifest、summary（files/tokens/max_tokens/errors/warnings）、files（按 token 降序）、load_sets、coverage、duplicates（exact/exact_accepted/near/near_accepted，受max_exact_results/max_near_results（均配 100）截断）、references（edges/cycles/authority_candidates/declared_authority_edges 等）、registries、schema_grammars、findings。near_scanned字段会显式标记近重复扫描是否执行，与--skip-near-duplicates的语义闭环。

适用前提与限制

• 该工具面向维护者，仓库明确说明它不接入 CI/pre-commit，也不属于终端用户依赖（tiktoken不在 requirements 中）；
• token 数精确对应o200k_base编码，换编码需要改 manifest 的encoding并会直接触发加载器拒绝；
• 所有 load set 与 file budget 数值是对当前仓库状态的审计快照，随文档增删而变，引用时应以仓库内 prompt_audit_manifest.json 的实时内容为准；
• 近重复结果是启发式候选，只能作为人工审查线索，不能当作“确定重复”的结论。

小结

scripts/docs/prompt_audit.md 描述的是一套把“提示词工程”当作“软件工程”来治理的完整方法：用精确 tokenizer 计量、用固定取整上限约束增长、用覆盖检查给每个文档上户口、用指纹裁决让“有意重复/有意投影”显式留痕、用注册表断言与 schema 投影防止文档与机器数据漂移、用权限边 DAG 保证“唯一事实源”无环。其工程价值在于：所有裁决都以稳定身份（三元组指纹、12 位十六进制指纹）记录在 manifest 中，任何后续改动都会以明确的 error/warning 代码（LOAD_COVERAGE_GAP、DUPLICATE_ACCEPTED_STALE、SCHEMA_ACCEPTED_STALE、REGISTRY_PROJECTION_MISMATCH等）被再次要求人工确认——治理本身成为可审计的第一等产物。

【免费下载链接】ppt-masterAI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations,>项目地址: https://gitcode.com/GitHub_Trending/ppt/ppt-master