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 Auditppt-master 的核心工作方式是让 AI Agent 按路由规则按需读取 SKILL.md、各 role/workflow 文档以及模板目录中的说明文件。文档一旦膨胀Agent 的上下文窗口就会被稀释关键指令可能被挤出注意力范围。为此仓库提供了一套审计工具工具本体prompt_audit.py约 2400 行的单文件实现审计夹具prompt_audit_manifest.json约 2400 行人工转录 SKILL.md 与 role/workflow 文档中的读取规则使用文档prompt_audit.md即本文的主体。原文明确了三条边界约束仅维护者使用、严格只读——审计过程不修改任何被审计文档故意不接入 CI 或 pre-commit 钩子——它不是构建门禁而是人工治理工具生成角色永远不加载这份文档、这个工具或它的 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 tiktoken0.7.0退出码约定出现任何确定性 error 时退出码为1。未被裁决adjudicated的精确重复或 schema 投影属于可行动的 warning启发式的近重复候选只是报告信息不进入findings。加--json后连环境/配置类失败也会输出稳定的AUDIT_SETUP_ERRORJSON 信封而不是 traceback 或纯文本错误。结合 prompt_audit.py 中build_parser()的实现完整 CLI 实际还支持两个文档未列出的参数参数作用默认值--root仓库根目录脚本所在目录向上三级即仓库根--manifest审计 manifest 路径与脚本同目录的 prompt_audit_manifest.json--json输出完整 JSON 报告关闭默认输出面向维护者的文本摘要--skip-near-duplicates跳过较慢的启发式近重复扫描关闭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.jsondocuments: { 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检查面总览文档给出的检查面表格如下本文后续小节逐一展开AreaFailure classCorpus and hot-file token ceilingserror on budget overflowDeclared load sets (route/stage scenarios)error on budget overflow, unknown files, selector/registry driftLoad coverageerror when a corpus file is in no load set and has nocoverage.exemptentryRegistry claims and declared vocabulary projectionserror on ID/count/index/projection driftMarkdown references and declared authority edgeserror on broken links or unreferenced edgesCross-file exact duplicateswarning until adjudicated viaduplicates.acceptedCross-file near duplicatesinformational candidates in the report; no findingSchema multi-definitionwarning for each unaccepted owner-field / projection-path pair; accepted projections stay visible in the reportAccepted duplicate/schema drifterror when an accepted source or projection no longer matches预算体系三级上限与 fixed_upper_bound 政策三级预算语料级documents.max_tokens555000所有语料文件 token 总和超预算报BUDGET_CORPUSprompt_audit.py热文件级file_budgetsmanifest 为 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_FILEprompt_audit.py场景级load_sets.*.max_tokens每个“路由/阶段”声明的场景有独立预算超限时maximum计算值超预算报BUDGET_LOAD_SETprompt_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_tokensprompt_audit.py。场景判定以max为准maximum budget则 pass否则 fail。选择器还携带治理语义registry声明该 glob 的候选 id 集合必须与某个注册表完全一致否则报选择器/注册表漂移drift错误prompt_audit.pyallow_repeat允许与固定文件或其他选择器重叠但必须命名load_event说明重复加载的业务触发点prompt_audit.pyinclude场景可以递归组合其他场景resolve_entries()做了去重与环检测Load-set include cycle。manifest 中可以看到这套组合的实际形态bootstrap.routingAGENTS.md SKILL.md routing.md预算 8000是根场景route.generate.planning在其之上叠 13 个固定文件加 3 个注册表选择器modes 选 5、visual-styles 选 18、image-renderings 选 20预算 130000prompt_audit_manifest.json更重的route.generate.flat-ai-two-types预算 230000route.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”这种贴地数值。文档规定的调整流程设立预留约 10% 工作余量向上取整到上述步进不许随意动一旦通过既不上调也不下调包括“提示词涨了、把预算抬回去恢复余量”也不允许唯一上调触发当前审计针对该上限报了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 tokensprompt_audit_manifest.json等——每次上调都对应一次真实的审计失败记录形成可回溯的预算变更史。覆盖检查每个文档必须“有户口”audit_load_coverage()prompt_audit.py强制每个语料文件要么被某个 load set 覆盖要么在coverage.exempt中有一条带一行理由的豁免否则逐个文件报LOAD_COVERAGE_GAP。豁免条目不是随意的 glob 白名单——加载器要求每条豁免都有非空glob和非空单行reasonprompt_audit.py运行时还会检查三种病态COVERAGE_EXEMPT_STALE豁免 glob 匹配不到任何语料文件prompt_audit.pyCOVERAGE_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/*.mdlegacy 墓碑_index.md明确禁止加载等。文档给出的豁免准则是只豁免永远不会进入 role 上下文的物料legacy 墓碑、生成型维护资产、维护者专用文档、许可声明而“条件性运行时读取”应该表达为增量 load set而不是豁免。重复裁决精确重复、近重复与 accepted 指纹段落抽取与归一化extract_paragraphs()prompt_audit.py把 Markdown 按空行/标题/代码围栏切成文本块剥掉链接语法与格式符、压缩空白并转小写得到normalized只保留长度 ≥min_charsmanifest 配 100的块。精确重复find_exact_duplicates()prompt_audit.py按归一化文本分组同一归一化文本出现在≥2 个不同文件即构成一个候选组并计算sha1(排序拼接原文)[:12]指纹_duplicate_fingerprintprompt_audit.py。候选组总数非零时产生一条DUPLICATE_EXACT_CANDIDATESwarning。近重复信息级不产 findingfind_near_duplicates()prompt_audit.py是纯启发式对词数 ≥min_words20的段落提取shingle_words4词级 n-gram经倒排索引 频率剪枝max_shingle_frequency24粗筛要求共享 shingle ≥ 3、共享/并集比 ≥ 0.18最后用SequenceMatcher.ratio()复核相似度 ≥near_similarity0.82才列为候选。这些候选只出现在 JSON 报告的duplicates.near中从不进入 findings——文档明确它是“heuristic maintenance information”。accepted裁决身份是三元组文档强调接受一条重复的“身份”是kindfingerprintpaths三者的组合因此两个路径对即使散文完全相同也能被独立裁决。加载器对duplicates.accepted的校验prompt_audit.py要求kind ∈ {exact, near}、12 位十六进制指纹、唯一非空路径列表、单行 reason且同一身份不得重复登记。审计时的对账逻辑当前重复候选与 accepted 按身份匹配已接受但匹配不上任何当前重复 → errorDUPLICATE_ACCEPTED_STALEprompt_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.pykindid 来源manifest 实例structured_markdownentry_pattern带id命名组image-layout-patternsP/M/A/C 编号序列还配prefix_countssequence_width校验完整编号顺序directoryglob 展开的文件 stem可排除_index.mdmodes、visual-styles、image-renderings、image-type-templatesprompt_audit_manifest.jsonjson_collectionJSON 文件某 key 下的 dict/listlist 可配id_fieldchart-templates、table-templates、sound-cuesprompt_audit_manifest.jsonline_collection文本文件逐行preset-shape-vocabularyshape_type_values.txt对应的失败类包括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_patternJSON list 注册表还需id_field审计要求投影出的 id 与注册表完全相等拒绝重复、缺失、多余三种漂移REGISTRY_PROJECTION_ID_DUPLICATE/REGISTRY_PROJECTION_MISMATCH。实例见 manifestchart-templates注册表charts_index.json投影到 chart-vocabulary.md条目模式^\|\s*\chart/(?P [a-z0-9_])\s*|sound-cuessounds_index.jsonid_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_ROLESprompt_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_CANDIDATEJSON 报告按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_REprompt_audit.py的边标记为authority_candidate。在引用边上跑 Tarjan 强连通分量报告循环引用组。authority_edges则是 manifest 中显式声明的“关注点级权限 DAG”audit_authority_graph()prompt_audit.py逐 concern 做 SCC成环报AUTHORITY_CYCLErun_audit()再校验每条声明边必须真实存在于 Markdown 引用图中否则报AUTHORITY_EDGE_UNREFERENCEDprompt_audit.py——防止声明了文档里根本不存在、或已被删掉的权威关系。Manifest 维护流程文档原节完整继承文档的核心运维章节“Manifest Maintenance”逐条对应源码行为以下是完整继承与补充总原则manifest 是审计专用夹具audit_only: true、runtime_consumed: false人工转录SKILL.md与 role/workflow 文档中陈述的加载规则因此那些文档中任何读取规则的变更必须在同一次变更中更新对应的 load set——覆盖检查只能抓住“未分类的新文件”而“既有文件读取规则变了”只有人能抓住。新增语料文件若无匹配现有类别豁免审计以LOAD_COVERAGE_GAP失败直到你把它加入读取它的 load set、或给出一行理由的豁免。豁免只适用于永不进入 role 上下文的物料legacy 墓碑、生成型维护资产、维护者专用文档、许可声明条件性运行时读取应表达为增量 load set。有意精确重复跑--json把候选的kind、fingerprint、paths连同 reason 抄进duplicates.accepted。接受身份是三者组合故散文相同的不同路径对保持独立可审。编辑任一原始块会改变指纹过期接受报DUPLICATE_ACCEPTED_STALE。近重复duplicates.near只是启发式维护信息不产生 warning维护者仍可把稳定的有意 near 对记入duplicates.accepted但--skip-near-duplicates有意不对已接受的 near 对做检查该扫描未运行。注册表投影声明projection.source 带id命名组的entry_patternJSON list 注册表另需id_field。审计要求投影 id 与注册表完全一致拒绝重复/缺失/多余。Schema owner每个配置字段必须在声明 owner 中有字段局部定义信号分属不同 artifact 的字段应拆成不同 owner 条目长行中泛化的key/value散文不构成语法信号显式赋值、字段局部文法/格式措辞、field ... one of ...形式才算。有意 schema 投影见上文 JSON 示例接受是“精确的”不是路径豁免owner/投影编辑或投影删除报SCHEMA_ACCEPTED_STALE新字段/路径投影报SCHEMA_MULTIDEF_CANDIDATEJSON 报告分离open/accepted/stale三态。预算上限budget_policy: fixed_upper_bound预算是稳定、刻意取整的限额新上限留约 10% 余量并按 25010k/1k100k/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、summaryfiles/tokens/max_tokens/errors/warnings、files按 token 降序、load_sets、coverage、duplicatesexact/exact_accepted/near/near_accepted受max_exact_results/max_near_results均配 100截断、referencesedges/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考