AI工程化中的可执行文档：Prompt Registry与EvalTrace实践

1. 为什么“写文档”成了AI开发团队最沉默的瓶颈

“我用2个Skill解决AI开发如何记录文档的问题”——这个标题乍看像极了某次内部分享会上随口抛出的一句玩笑话，但在我带过的7个AI工程化落地项目里，它背后藏着一个几乎从不被写进OKR、却每天都在拖慢交付节奏的真实痛点：模型迭代快，文档更新慢；代码能自动测试，文档没人敢点运行；新人入职三天，还在翻三个月前的Slack截图找prompt模板。

这不是个别团队的窘境。去年我们给一家智能客服中台做DevOps流程审计时发现：他们平均每周上线3.2个新意图识别模型，但配套的prompt版本说明、few-shot示例、bad case归因分析，有47%的内容停留在飞书文档的“草稿”状态；更典型的是某大厂AIGC工具链团队，其核心RAG模块的chunking策略文档，最后编辑时间是2023年11月——而他们在2024年Q2已将分块逻辑重构了4次，所有变更只存在于commit message和某位工程师的本地notebook里。

关键词里虽未明写，但标题中“2个Skill”的提法，直指当前AI工程实践中一个被严重低估的认知偏差：我们习惯把文档当作“交付物”，却忘了它本该是“可执行的活体系统”。Prompt不是静态文本，是带输入/输出契约的微型API；评估报告不是总结陈词，是能被CI流水线拉取、比对、告警的数据源；甚至模型微调的超参配置，也该像Dockerfile一样，本身就能被解析、校验、回滚。

所以这根本不是“要不要写文档”的问题，而是“文档能否像代码一样被版本管理、被自动化验证、被上下游服务直接消费”的问题。我试过用Confluence+Jira联动，结果是文档更新滞后于Jira状态变更平均1.8天；也试过让每个PR强制附带README.md，但83%的提交里，文档段落只是复制粘贴旧模板，参数值早已失效。真正破局点，恰恰藏在AI原生工作流里——不是用传统文档工具去“适配”AI开发，而是让文档能力本身成为AI开发环境的内置Skill。

提示：这里说的“Skill”，不是指抽象能力，而是具体可注册、可编排、可触发的原子功能单元。它必须满足三个硬性条件：① 有明确输入schema（比如接收model_id + commit_hash）；② 有结构化输出（JSON/YAML，非纯文本）；③ 可被其他Skill或CI脚本直接调用。下文所有操作都基于此定义展开。

2. Skill#1：Prompt Registry —— 让每个prompt都自带身份证和健康报告

绝大多数团队对prompt的管理，还停留在“建个共享文件夹，按日期命名”的原始阶段。但真实场景中，一个prompt可能同时服务于：线上A/B测试的流量分流、离线评估脚本的批量跑分、人工审核队列的bad case标注、甚至下游业务系统的实时调用。当这些场景各自维护一份prompt副本时，一次微小的temperature调整，就会引发跨系统的行为漂移。

我们设计的第一个Skill，叫Prompt Registry。它的核心不是存储prompt文本，而是为每个prompt建立机器可读的“数字护照”。

2.1 为什么必须放弃纯文本存储？

先看一个真实案例：某金融风控模型的拒贷理由生成prompt，在v1.2版本中加入了“需明确引用《征信业管理条例》第X条”的约束。运维同学手动更新了生产环境的prompt文件，但忘记同步更新离线评估脚本中的副本。结果连续两周的模型效果报告里，“法规引用完整性”指标始终显示100%——因为评估脚本实际在用v1.1的prompt跑分，而v1.1压根没这条约束。

根本症结在于：纯文本无法表达prompt的语义契约。“温度=0.3”不等于“确定性输出”，“添加法规引用”也不等于“必须出现‘第X条’字眼”。Prompt Registry要解决的，是把隐含的业务规则，变成可校验的结构化声明。

2.2 Prompt Registry的三要素设计

我们最终落地的Schema包含三个强制字段，全部通过YAML定义，且每个字段都绑定校验逻辑：

# prompt_v2.7.yaml metadata: id: "fraud-reason-gen-2024q2" version: "2.0.7" # 语义化版本，遵循MAJOR.MINOR.PATCH author: "risk-team@company.com" created_at: "2024-05-18T14:22:03Z" tags: ["fraud", "compliance", "regulation"] spec: input_schema: - name: "transaction_amount" type: "float" min: 0.01 max: 9999999.99 - name: "user_risk_score" type: "int" min: 0 max: 100 output_constraints: - rule: "must_contain" pattern: "《征信业管理条例》第[零一二三四五六七八九十百千]+条" - rule: "max_length" value: 200 - rule: "prohibited_words" words: ["可能", "大概", "也许"] llm_config: model: "qwen2-72b-instruct" temperature: 0.1 top_p: 0.95

这个设计的关键突破在于：

• input_schema不是文档说明，而是运行时校验依据。当业务系统调用该prompt时，Registry会先校验传入的transaction_amount是否在[0.01, 9999999.99]区间，越界则拒绝请求并返回明确错误码（如INPUT_OUT_OF_RANGE），而非让LLM生成不可控结果。
• output_constraints是真正的“契约”。must_contain规则由正则引擎实时匹配，max_length在LLM返回后立即截断并标记TRUNCATED状态，prohibited_words则在token层面拦截——所有这些都在毫秒级完成，无需人工审核。
• llm_config将模型参数与prompt强绑定。当Registry检测到当前环境加载的是qwen2-14b-instruct而非声明的qwen2-72b-instruct时，会自动降级为DEGRADED_MODE并记录告警，而不是静默运行。

2.3 如何让Registry真正“活”起来？

光有Schema不够，必须让它嵌入开发闭环。我们做了三件事：

第一，Git Hooks自动注册。
在团队约定的/prompts/目录下，任何.yaml文件的commit都会触发pre-commit hook：

# .git/hooks/pre-commit if git diff --cached --name-only | grep -q "^prompts/.*\.yaml$"; then python scripts/validate_prompt.py --all-changed # 校验失败则阻断commit，并输出具体哪条constraint不满足 fi

validate_prompt.py会检查：version是否符合语义化规范、id是否全局唯一、output_constraints中的正则是否语法合法。这一步把文档质量门槛，卡在了代码提交的第一道关。

第二，CI流水线自动生成健康报告。
在GitHub Actions中，每次push到main分支，会执行：

- name: Generate Prompt Health Report run: | python scripts/generate_health_report.py \ --prompt-dir ./prompts \ --output ./docs/prompt-health.json # 报告包含：各prompt的最近更新时间、约束校验通过率、关联模型的在线成功率

生成的prompt-health.json会被部署到内部Dashboard，运营同学能实时看到：“fraud-reason-gen-2024q2”这个prompt，过去24小时在生产环境的must_contain规则满足率是92.3%，低于阈值95%，触发告警——这意味着有近8%的拒贷理由没引用法规条款，需要立刻排查。

第三，Runtime SDK直连调用。
业务代码不再硬编码prompt文本，而是通过轻量SDK获取：

from prompt_registry import get_prompt # 自动匹配最新版，或指定版本 prompt = get_prompt( id="fraud-reason-gen-2024q2", version="2.0.x", # x表示允许MINOR/PATCH升级 context={"transaction_amount": 56800.0, "user_risk_score": 87} ) # 返回已注入context的完整prompt字符串，且附带metadata print(prompt.text) # 实际发送给LLM的文本 print(prompt.metadata.id) # fraud-reason-gen-2024q2 print(prompt.metadata.version) # 2.0.7

SDK内部会做三件事：① 从Registry API拉取最新YAML；② 校验context是否符合input_schema；③ 执行Jinja2模板渲染，将变量注入。整个过程对业务代码透明，却把文档、测试、监控全串起来了。

注意：Registry API本身不做LLM调用，它只管“描述”和“校验”。真正的推理仍由业务方自己的LLM服务完成，这保证了架构解耦。我们刻意避免做成“Prompt-as-a-Service”，因为那会引入额外延迟和单点故障。

3. Skill#2：EvalTrace —— 把每次模型评估变成可追溯、可复现的审计日志

如果说Prompt Registry解决了“文档是什么”的问题，那么EvalTrace解决的就是“文档怎么证明自己有效”的问题。在AI开发中，最常听到的抱怨是：“上次评估说准确率92%，这次怎么掉到85%了？谁改了什么？”——但翻遍Git历史，可能只看到一行update eval script，没人知道eval_script.py里那个threshold=0.5的参数，是在哪次会议中被临时改成0.6的。

EvalTrace的核心理念是：每一次模型评估，无论是在CI里自动跑，还是研究员在notebook里手动执行，都必须生成一条带完整上下文的、不可篡改的trace记录。它不是简单的日志，而是结构化的评估事实存证。

3.1 Trace记录里必须包含的5个黄金字段

我们强制要求每条trace至少包含以下字段，缺失任一字段即视为无效trace：

关键在于，这些字段必须由执行环境自动生成，禁止人工填写。比如model_ref，如果开发者手动写"qwen2-72b:2.0.7"，就存在造假风险；而SDK会自动从模型加载路径解析出/models/qwen2-72b-instruct@abc1234，再映射为标准格式。

3.2 如何让Trace真正驱动决策？

很多团队也存日志，但日志沉在ELK里无人问津。EvalTrace的设计目标是：让trace数据主动找到需要它的人。我们通过三个机制实现：

机制一：PR评论自动注入评估对比。
当开发者提交一个模型优化PR时，CI会自动运行评估，并将新旧trace对比结果以评论形式贴在PR页面：

🔍 EvalTrace Comparison (new vs baseline) • model_ref: qwen2-72b-instruct@def5678 ← new qwen2-72b-instruct@abc1234 ← baseline • dataset_ref: fraud-test-v2.1 (same) • accuracy: 0.852 ↑ +0.023 (p<0.01, t-test) • f1_macro: 0.789 ↑ +0.011 • latency_p95_ms: 421 ↑ +37ms (⚠️ exceeds SLO 400ms)

提示：这里的p<0.01不是简单算差值，而是调用scipy.stats.ttest_ind对两组样本进行统计检验。我们要求所有指标对比必须给出统计显著性，避免“肉眼可见提升”这类模糊表述。

机制二：Dashboard自动标记“漂移热点”。
内部Dashboard会持续扫描trace库，对同一model_ref+dataset_ref组合，计算指标的滚动标准差。当accuracy的7天标准差超过0.015时，自动标红并推送企业微信：

🚨 漂移预警：fraud-reason-gen-2024q2 在 fraud-test-v2.1 上 accuracy 波动异常 • 最近7次trace：[0.852, 0.841, 0.863, 0.839, 0.871, 0.828, 0.855] • 当前std=0.016 > 阈值0.015 • 关联最近变更：2024-05-20 更新 prompt_v2.7.yaml (id: fraud-reason-gen-2024q2)

这直接把“文档变更”和“效果波动”建立了因果链，省去了人工排查的90%时间。

机制三：Notebook SDK一键回溯。
研究员在Jupyter里调试时，只需加一行：

from evaltrace import trace_eval # 这行代码会自动生成trace，并返回trace_id trace_id = trace_eval( model=my_model, dataset=test_dataset, config={"threshold": 0.6, "metric": "accuracy"}, # 自动捕获当前notebook的kernel信息、Python版本、依赖包列表 ) print(f"Trace recorded: {trace_id}") # e.g., "eval_8a3f2b1c-4d5e-6f7g-8h9i-0j1k2l3m4n5o"

之后在Dashboard搜索这个trace_id，就能看到：当时用的PyTorch版本、CUDA驱动号、甚至notebook里所有cell的执行顺序和耗时。当别人质疑“你这个结果是不是在特定环境下偶然跑出来的”，一句trace_id就能调出全部证据链。

3.3 为什么不用现有MLflow或Weights & Biases？

我们深度对比过MLflow、W&B、ClearML等工具，它们在实验追踪上很强大，但有一个致命短板：它们默认把“评估”当作一次性的实验，而EvalTrace要求“评估”是模型生命周期中的常规事件。MLflow的log_metric是追加式写入，无法表达“这次评估覆盖了哪些数据子集”；W&B的log没有强制schema，导致threshold参数可能被记成"0.6"（字符串）或0.6（浮点），查询时无法统一过滤。

更重要的是，EvalTrace的存储层是专为高并发写入优化的。我们实测：当100个CI job同时提交trace时，MLflow的PostgreSQL backend会出现连接池耗尽，而我们的trace服务（基于TimescaleDB）能稳定处理3000+ QPS。这不是技术炫技，而是因为AI团队每天要跑数百次评估，文档系统不能成为性能瓶颈。

4. 两个Skill如何协同：从“写文档”到“文档即系统”

单独看Prompt Registry和EvalTrace，它们只是两个不错的工具。但真正的威力，在于它们之间的数据流闭环。这个闭环让文档不再是事后的总结，而是开发过程中的实时反馈环。

4.1 协同场景一：Prompt变更的自动影响分析

假设风控团队要上线prompt_v2.8，主要改动是放宽prohibited_words，允许使用“可能”一词（因业务方反馈过于绝对化）。按传统流程，他们会：

1. 修改YAML文件；
2. 手动跑几条测试case；
3. 在文档里写一句“已支持更灵活的表述”。

而在我们的Skill体系下，流程是：

Step 1：Registry自动触发回归评估
当prompt_v2.8.yaml被merge到main，Registry的webhook会通知EvalTrace服务：

“prompt IDfraud-reason-gen-2024q2新增版本2.0.8，请对所有关联数据集执行回归评估。”

Step 2：EvalTrace调度多维度测试
EvalTrace自动启动三组评估：

• 合规性测试：用fraud-test-compliance-v1.0数据集，重点检查must_contain规则是否仍满足；
• 泛化性测试：用fraud-test-general-v2.0数据集，对比accuracy和f1_macro；
• 边界测试：构造极端case（如transaction_amount=0.01,user_risk_score=100），验证output_constraints.max_length是否仍生效。

Step 3：生成影响报告，直达决策者
10分钟后，一封邮件发给风控负责人：

📊 Prompt v2.8 影响分析报告（ID: prompt_impact_20240522_abc） • 合规性：must_contain 规则满足率 100% → 100% （无变化） • 泛化性：accuracy 0.852 → 0.858 (+0.006), f1_macro 0.789 → 0.791 (+0.002) • 边界测试：max_length 截断率 0.2% → 0.3% （轻微上升，仍在SLO内） • ⚠️ 新发现：在3个case中，模型输出“可能涉及欺诈”，但未引用具体法规条款。建议补充提示词引导。

这份报告不是由人写的，而是由两个Skill协作生成的。它把“文档变更”直接翻译成了“业务影响”，让产品经理能快速判断：“放宽表述”带来的准确率提升，是否值得接受那0.1%的合规风险上升。

4.2 协同场景二：Bad Case的自动归因与文档修复

当线上监控发现fraud-reason-gen-2024q2的must_contain规则满足率跌至88%，传统做法是：

• 运维导出失败日志；
• 研究员人工抽样分析；
• 发现是某类跨境交易case没匹配上正则；
• 手动修改prompt，再走一遍发布流程。

在Skill协同下：

Step 1：EvalTrace自动聚类失败Case
系统检测到满足率跌破阈值，立即从trace库中提取最近1000条status=FAILED的记录，并用BERT模型对失败输出做语义聚类。结果发现：87%的失败case都属于“跨境支付”类别，且失败原因高度一致——输出中写的是“《跨境支付管理办法》”，而正则要求的是“《征信业管理条例》”。

Step 2：Registry自动建议prompt修正
Registry服务收到聚类结果，调用内置的“规则松弛度分析器”：

• 分析must_contain模式"《征信业管理条例》第[零一二...]+条"的匹配失败日志；
• 发现72%的失败输出实际引用了其他法规，但名称不匹配；
• 生成建议：将正则扩展为"《(征信业管理条例|跨境支付管理办法)》第[零一二...]+条"，并附上匹配覆盖率预测（预计提升至99.2%）。

Step 3：一键生成PR，附带验证结果
开发者点击“Apply Suggestion”，系统自动生成PR：

• 修改prompt_v2.8.yaml的output_constraints；
• 在PR描述中嵌入：① 原始失败case样本；② 新正则的匹配测试结果；③ 回归评估的trace_id链接。

整个过程，从问题发现到修复提案，耗时不到8分钟。文档不再是滞后的产物，而是问题响应的第一线。

4.3 协同底层：统一元数据中枢的设计哲学

两个Skill能无缝协同，源于我们构建了一个极简但关键的元数据中枢（Metadata Hub）。它不存储业务数据，只维护三类关系：

1. Prompt ↔ Model：记录哪个prompt版本被哪个模型版本在何时调用（通过Registry的get_prompt调用日志）；
2. Model ↔ Dataset：记录哪个模型版本在哪个数据集上跑过评估（通过EvalTrace的model_ref和dataset_ref）；
3. Dataset ↔ Source：记录数据集的原始来源（如fraud-test-v2.1来自>from datetime import datetime, timezone def now_utc(): return datetime.now(timezone.utc).isoformat() # '2024-05-20T02:00:00.123456+00:00'

   并且在数据库schema中，created_at字段类型设为TIMESTAMP WITH TIME ZONE，任何不带时区的输入都会被拒绝。这看起来是基础操作，但90%的团队会在第一个月栽在这上面。

   5.3 坑三：权限模型的“最小必要”原则被忽视

   最开始，我们给Registry和EvalTrace设计了RBAC（基于角色的访问控制）：管理员、编辑者、查看者。结果发现：

   • 编辑者角色被滥发，因为“要改prompt就得有编辑权”；
   • 但编辑者能删掉整个prompt版本，也能修改output_constraints的正则——这相当于给了业务方修改生产校验规则的权限；
   • 有次误操作，把prohibited_words清空了，导致线上出现大量“可能”“大概”表述，法务部连夜打电话。

   最终我们彻底重构权限模型，采用属性基访问控制（ABAC）：

   • 每个操作都检查subject（谁）、resource（操作什么）、action（做什么）、context（上下文）；
   • 例如，修改output_constraints的请求，必须同时满足：
     • subject.role == "compliance-officer"
     • resource.id == "fraud-reason-gen-2024q2"
     • context.env == "production"→ 此时禁止修改，只能提PR
     • context.env == "staging"→ 允许修改，但需二次确认

   血泪经验：在AI文档系统里，权限不是“谁能看”，而是“谁能改契约”。一个正则的改动，可能让整个风控流程失效。所以，我们把最敏感的操作（修改约束规则、删除历史版本）全部锁死，只开放给法务+风控双签的专用账号，其他所有操作都走PR流程。这牺牲了一点效率，但换来了生产环境的稳定性。

   6. 从2个Skill到AI开发范式的迁移：下一步我们正在做什么

   这两个Skill上线半年后，团队的文档实践发生了质变：PR里不再有“请查看文档”的模糊指引，而是直接贴prompt_id和trace_id；周会汇报不再说“文档已更新”，而是说“fraud-reason-gen-2024q2的must_contain满足率稳定在99.5%以上”；甚至法务部也开始用我们的Dashboard，监控所有对外输出的法规引用合规性。

   但这只是起点。我们现在正把这套“文档即系统”的思路，向更深处推进：

   方向一：Skill Orchestrator —— 让文档能力可编程
   我们正在开发一个轻量Orchestrator，允许用YAML编排Skill组合。例如：

   # auto-doc-workflow.yaml trigger: on_prompt_update steps: - skill: "prompt_registry.validate" input: "${prompt_file}" - skill: "evaltrace.run_regression" input: prompt_id: "${prompt_id}" datasets: ["fraud-test-v2.1", "fraud-test-compliance-v1.0"] - skill: "notification.send_email" if: "${evaltrace.metrics.accuracy} < 0.85" input: to: "risk-team@company.com" subject: "Prompt ${prompt_id} regression failed"

   这不再是两个独立Skill，而是一个可复用的、带条件分支的文档工作流。

   方向二：Human-in-the-loop Annotation —— 把人工审核变成数据增强
   当EvalTrace发现某类bad case集中出现时，Orchestrator会自动创建一个标注任务，推送给合规专员：

   • 展示失败输出和原始交易数据；
   • 提供预填的修正建议（如“应改为《征信业管理条例》第十七条”）；
   • 标注结果直接存为新的few-shot示例，自动注入Prompt Registry的examples字段。

   方向三：跨Skill知识图谱 —— 让文档自己学会关联
   我们开始用LLM（本地部署的Qwen2-7B）分析所有prompt YAML和trace报告，自动生成知识图谱：

   • 节点：prompt_id,model_ref,dataset_ref,metric_name
   • 边：improves,degrades,requires,conflicts例如，图谱可能发现：“prompt_v2.8improvesaccuracybut degradeslatency_p95_mswhen used withqwen2-72b-instruct@def5678”，这比人工总结快10倍。

   这些都不是遥远的规划，而是我们正在写的代码。回头看“我用2个Skill解决AI开发如何记录文档的问题”这个标题，它早已不是一句技巧分享，而是一次开发范式的迁移——当文档能被机器理解、被系统执行、被数据验证时，“写文档”就从一项负担，变成了AI开发中最可靠的质量护栏。