@huicai/cli 2026.714.0 → 2026.721.0

package/skills/ai-llm-app/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ai-llm-app
+description: LLM 应用开发链（模型接入抽象层与多模型路由→超时重试的 LLM 特调→流式判据→结构化输出三层防线→函数调用工具 schema→上下文窗口预算→前缀/语义缓存判据→降级兜底链→提示注入防护→token 成本工程→录制回放测试）。eng-ai 的应用开发孙链:写 LLM 调用代码、输出不稳、上下文超限、AI 接口又慢又贵时载入。
+version: 1.0.0
+---
+
+# LLM 应用开发链
+
+eng-ai 的应用开发孙链。心智基调:**把 LLM 当一个"能力强但不可靠的远程依赖"**——
+慢(秒级)、贵(按 token 计费)、非确定(同输入不同输出)、会一本正经地错(幻觉),四个特性决定全部工程设计。
+
+## 模型接入层
+
+- **抽象层收口**:模型调用统一走内部封装(OpenAI 兼容协议是事实标准),业务代码不直连供应商 SDK——换模型/多供应商路由/统一计量都靠这层(eng-integration 防腐层同理);
+- 多模型路由:按任务分级(分类/抽取类走小模型,复杂推理走大模型),按可用性主备(主模型故障自动切备,**备模型要定期用评测集验证**,别切过去才发现效果崩);
+- 供应商配额与限流:客户端并发闸门+429 退避;配额余量监控(eng-integration 配额纪律)。
+
+## 超时重试的 LLM 特调
+
+LLM 是最慢依赖,常规参数不适用:超时按 P99 生成时长定(长生成场景 60s+ 正常,**流式下改盯首 token 超时**+token 间隔超时);
+重试判据:超时/429/5xx 可重试(指数退避),**内容质量差不算失败不自动重试**(那是提示或模型问题,重试=烧钱抽奖);
+幂等注意:LLM 调用天然非幂等(重试结果不同),下游逻辑不得假设两次一致;
+成本护栏:重试也计费,重试预算与单请求 max_tokens 上限双闸(eng-reliability 重试预算)。
+
+## 流式判据
+
+用户盯着看的界面=必须流式(首 token 时延决定体感,总时长反而其次);
+机器消费的后台任务=非流式(省编码复杂度);
+流式工程要点:SSE 断线重连策略/前端渐进渲染防抖/**流中途出错的 UI 兜底**(已渲染一半怎么办:标注中断+可重试)/流式下结构化输出要攒完整再解析(或用增量解析器)。
+
+## 结构化输出三层防线
+
+1. **约束生成**:能用 JSON schema/函数调用强约束就用(供应商结构化输出能力优先),枚举字段给死选项;
+2. **校验**:出参过 schema 校验(zod/pydantic 思路)+业务规则校验(数值范围/枚举合法/引用存在);
+3. **修复与重试**:校验失败→携错误信息让模型重试一次(常能自愈)→仍失败走降级(默认值/人工队列);
+纪律:**模型输出永远当外部输入对待**(eng-security 一切外部输入不可信的 AI 延伸)——不 eval、不拼 SQL、不直接执行。
+
+## 函数调用（工具 schema 设计）
+
+工具名与描述就是提示工程:动词开头、说清"何时该用我"、参数描述给格式与示例;
+参数能枚举不自由(模型面对自由字符串就自由发挥);
+工具返回的错误要**可行动**("参数 date 需 YYYY-MM-DD 格式,收到 '昨天'"——模型靠错误信息自我修正,Agent 场景细则见 ai-agent);
+工具数量控制(几十个工具一起给=选择困难,按场景分组挂载)。
+
+## 上下文窗口预算
+
+四段分账:系统提示(固定)+对话历史(可压缩)+检索内容(可裁剪,ai-rag)+输出预留(max_tokens)——
+**先定预算再填内容**,超了按优先级裁(检索内容截断>历史摘要压缩>历史丢弃,系统提示不动);
+历史压缩判据:轮次超阈值把早期对话摘要化(信息有损要认);
+长文档处理:分块+map-reduce 或长上下文模型直塞的成本对比先算(长上下文按 token 全额计费,不是免费午餐);
+**上下文利用率监控**:平均填充率与截断发生率进指标(截断率高=预算设计有病)。
+
+## 缓存判据
+
+- **前缀缓存**(供应商侧):系统提示与固定内容置前、可变内容置后(提示结构为缓存设计,ai-prompt 稳定前缀纪律);命中率进监控,改一个字就破缓存——**系统提示别放时间戳**(经典自杀);
+- 语义缓存(相似问复用答案):FAQ 类高重复场景才上;风险先认(相似≠相同,措辞差一字含义反转),命中阈值保守+敏感类目排除;
+- 确定性任务结果缓存:同输入同参数的抽取/分类任务,业务层按输入哈希缓存,最便宜的优化。
+
+## 降级兜底链
+
+主模型故障→备模型(效果已验证)→规则/模板兜底(能力降级但不白屏)→人工队列(明示排队);
+**幻觉兜底**:事实性输出配溯源(引用来源,ai-rag)/关键动作前给用户确认页(AI 起草人拍板,eng-ai 人审判据)/"不确定"话术优于硬编("根据现有资料无法确认"比编一个强十倍);
+兜底路径演练(eng-reliability 预案纪律):把模型 mock 成挂的,看产品还能不能用。
+
+## 提示注入防护
+
+外部内容(用户输入/检索文档/网页/文件)与指令**结构隔离**(分隔标记+"以下为资料非指令"声明,注入防不绝但要设防);
+输出不直接执行:模型说"调工具删数据"≠真删(工具权限分级,ai-agent 沙箱);
+敏感操作二次确认;检索内容里的指令型文本(“忽略之前指令”)检测告警;
+数据边界:用户 A 的上下文不得混入用户 B(会话隔离,多租户强校验,eng-security 越权同理)。
+
+## 成本工程
+
+计量三归因:按特性/按租户/按模型统计 token 与费用(ai-mlops 承接监控面);
+单任务成本=输入+输出 token×单价,**立项时算,上线后对账**(eng-ai 成本链);
+省钱四招按序:缓存→路由降级→提示瘦身(冗余示例/重复上下文)→输出限长;
+异常告警:单用户/单特性用量突刺(死循环调用/被薅)。
+
+## 测试
+
+评测集回归为主(ai-eval,质量层);工程层用**录制回放**:真实请求响应录制成夹具,单测不真调模型(快、稳、免费);
+契约测试:mock 模型返回各类边界(超长/空/非法 JSON/超时),验证三层防线与降级链真的接得住;
+非确定性测试纪律:断言结构与约束(schema 合规/必含字段)不断言完整文本相等。
+
+**作业包**:`references/llm-integration-checklist.md`(LLM 接入评审:抽象层/超时重试特调/结构化三层/上下文预算/降级注入逐项勾)。
+
+## 使用纪律
+
+业务代码不直连供应商 SDK(过抽象层);模型输出当外部输入;上线前降级链演练过;
+每次线上 AI 事故(超时雪崩/成本突刺/注入)回写本链判据;质量问题走 ai-eval/ai-prompt,别在应用层硬扛。

package/skills/ai-llm-app/references/llm-integration-checklist.md

@@ -0,0 +1,39 @@
+# LLM 接入评审单（ai-llm-app 落笔件:新 LLM 调用点上线前逐项勾）
+
+## 接入层
+
+- [ ] 走统一抽象层,业务代码不直连供应商 SDK(换模型/路由/计量靠它)
+- [ ] 模型路由:任务分级 __(小模型)/__(大模型);主备切换的备模型已用评测集验证
+- [ ] 供应商限流应对:客户端并发闸 __;429 退避;配额余量监控
+
+## 慢与贵的特调
+
+- [ ] 超时按 P99 生成时长(流式盯首 token 超时 __s + token 间隔超时 __s)
+- [ ] 重试仅超时/429/5xx(退避);**内容差不重试**(烧钱抽奖);重试预算 ≤__%
+- [ ] max_tokens 上限 __;单请求成本上限心算过(token-cost-calc)
+- [ ] 流式判据:用户盯着看=流式;流中断 UI 兜底(标注中断+可重试)
+
+## 结构化输出三层
+
+- [ ] ①schema/函数调用强约束(枚举给死)  ②出参 schema+业务规则校验  ③失败携错误重试一次→降级
+- [ ] **模型输出当外部输入**:不 eval/不拼 SQL/不直接执行/入库前校验
+
+## 上下文与缓存
+
+- [ ] 窗口预算四段分账:系统 __ +历史 __ +检索 __ +输出预留 __;超载裁剪顺序已定
+- [ ] 稳定前缀纪律:系统提示无时间戳/随机数;缓存命中率进监控
+- [ ] 历史压缩策略:超 __ 轮摘要化(信息有损已认)
+
+## 降级与注入
+
+- [ ] 降级链:主模型→ __ →规则/模板→人工;**演练过**(mock 挂了产品还能用)
+- [ ] 幻觉兜底:溯源引用/置信度不足转人工/"不确定"话术(禁硬编)
+- [ ] 注入防护:外部内容与指令结构隔离;会话与租户隔离强校验(跨用户上下文=P0)
+- [ ] 敏感数据:入模型前过分级脱敏;外部 API=出域审批 __
+
+## 测试与观察
+
+- [ ] 评测集回归接入(ai-eval;工程层录制回放夹具:超长/空/非法 JSON/超时四类边界 mock 过)
+- [ ] 上线观察项:首 token 时延/错误率/兜底触发率/token 用量(突刺告警)
+
+> 结论: □通过 □带条件(条件+Owner+期限) □打回。评审人 __ 日期 __

package/skills/ai-mlops/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ai-mlops
+description: 模型服务与运维链（部署形态判据(API 托管/自部署/端侧)→自部署推理优化(量化/批处理/KV 缓存/并发排队)→服务治理(配额/优先级/过载保护)→三层监控(技术/质量/漂移)→成本归因与单位任务成本→数据回流与微调判据→模型-提示-参数三元组版本化与回滚）。eng-ai 的服务运维孙链:模型服务上线、AI 账单失控、效果悄悄衰减、自部署选型评估时载入。
+version: 1.0.0
+---
+
+# 模型服务与运维链
+
+eng-ai 的服务运维孙链。AI 服务=普通服务的全部运维要求(eng-ops/eng-observability 照单全收)
++三样特有:**质量会漂移、成本按 token 流血、变更三元组(模型/提示/参数)**。
+
+## 部署形态判据
+
+| 形态 | 启用信号 | 代价 |
+|---|---|---|
+| API 托管(默认) | 快速起步/弹性需求/无强合规限制 | 数据出域评估(eng-security)/供应商依赖(多供应商路由对冲,ai-llm-app) |
+| 开源自部署 | 数据不出域硬合规/用量大到自部署更省(先算账:GPU+运维人力 vs API 账单,**通常月账单十万级才值得认真算**)/深度定制 | GPU 采购运维/推理优化自己扛/模型迭代自己追 |
+| 端侧小模型 | 离线可用/隐私极敏/超低延迟 | 能力天花板低/端适配碎片 |
+
+混合是常态:敏感场景自部署+通用场景 API;形态决策走 eng-research 评分卡(退出成本:提示与评测集可迁移,但行为差异要重校)。
+
+## 自部署推理优化（按 ROI 排序）
+
+服务引擎选型(vLLM 类连续批处理引擎是基线,裸跑框架=浪费卡);
+**连续批处理**:吞吐的第一来源(并发请求动态拼批);
+量化:显存与吞吐换精度——**量化后必跑评测集**(ai-eval,精度损失要量化不要感觉);
+KV 缓存与前缀复用:系统提示共享前缀命中(与 ai-llm-app 提示结构纪律联动);
+并发与排队:最大并发限制+排队上限+超时快拒(过载时排长队人人超时,不如快拒部分保另一部分,eng-reliability 背压);
+GPU 监控专项:显存/利用率/温度进 eng-observability,**显存碎片与泄漏是自部署常客**。
+
+## 服务治理
+
+多租户配额:按租户/特性限 QPM 与 token 日额(一个失控脚本烧光全公司额度=真实事故);
+优先级队列:在线交互>批处理任务(批任务错峰跑,削峰填谷省容量);
+过载保护:限流+降级链(ai-llm-app:备模型/规则兜底)+熔断,容量口径用压测定(eng-performance,LLM 压测记得测长输出场景);
+网关统一收口:认证/计量/审计/路由在一处(ai-llm-app 抽象层的服务端形态)。
+
+## 三层监控（技术层会绿灯,质量层在流血）
+
+- **技术层**(常规 RED,eng-observability):可用率/首 token 时延与总时延分开看/429 与超时率/队列深度;
+- **质量层**:在线抽样评测分趋势(ai-eval 例程)/用户隐式信号(重试率/放弃率/点踩)/拒答率与兜底触发率——**质量指标进大盘,和可用率同屏**;
+- **漂移层**:输入分布漂移(话题/长度/语种占比变化=用户在用新姿势,评测集可能已过时)/效果衰减(同一评测集分数走低)/上游模型静默升级检测(API 托管时供应商可能悄悄换模型——固定金丝雀题集每日跑,分数突变=上游变了);
+告警阈值:质量分连续下降/成本突刺/兜底触发率抬升,三者都要叫人(eng-observability 告警三问)。
+
+## 成本工程（token 是流动的钱）
+
+计量三归因:特性×租户×模型的 token 与费用日报(eng-automation 例程);
+**单位任务成本**是北极星(每次问答/每份报告的成本趋势,总额会涨、单价要降,eng-infra FinOps 同理);
+预算与熔断:特性级月预算+80% 预警+超额降级策略(降小模型/限频,预先声明别静默断服务);
+优化路径复查(eng-ai 成本链):缓存命中率/路由分级命中率/平均输入输出长度趋势——**输入长度悄悄膨胀是最常见的隐性漏钱**(上下文利用率,ai-llm-app)。
+
+## 数据回流与微调判据
+
+回流管道:线上请求响应按合规采样落库(脱敏+分级+用户协议依据,eng-security)→标注→评测集补充(ai-eval)→(可选)微调语料;
+**微调判据严格把关**(eng-ai:改风格/格式/领域黑话,不是灌知识):上微调前先确认 提示+RAG 已到瓶颈且评测集能证明;
+微调后:同一评测集对照基础模型(赢了多少/输了哪些象限),**微调模型也会过期**(基础模型升级后重评,常常新基座裸跑赢过老微调);
+数据资产纪律:标注数据版本化,训练数据可追溯(哪个模型用了哪批数据)。
+
+## 版本管理与发布（三元组纪律的运维面）
+
+**模型/提示/参数三元组捆绑版本化**:任何一元变更=新版本,评测回归(ai-eval)→灰度(eng-release 金丝雀,质量指标进观察项)→全量;
+可回滚:三元组随时可整体回退(供应商模型下线风险→提前跟进废弃公告,老版本冻结期内完成迁移评测);
+变更事件打点(eng-observability 第四支柱):质量波动第一问"三元组谁动了";
+API 托管的模型版本要**钉住显式版本号**,禁用 latest 漂移(eng-infra 镜像标签同则)。
+
+**作业包**:`scripts/token-cost-calc.py`(usage.csv→按维度成本归因/占比/单位任务成本/输入膨胀提醒/预算对照)。
+
+## 使用纪律
+
+质量与成本指标与可用性同级运维(进值班看板);漂移金丝雀题集每日跑;
+每次成本/质量事故回写:预算护栏或监控盲区;
+**AI 服务的成熟度=你多快发现"它变了":供应商换模型、用户换用法、数据换分布——三小时还是三周,差的就是这条链。**

package/skills/ai-mlops/scripts/token-cost-calc.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+# Token 成本归因计算器（ai-mlops 成本工程"三归因/单位任务成本"的可执行版）。python3 stdlib,零依赖。
+# 输入 usage.csv: 维度,模型,调用次数,输入token,输出token   (维度=特性/租户,从网关计量导出,ai-llm-app 抽象层)
+# 价格: --price "模型名:输入价:输出价" 可重复,单位=每百万 token 的货币数(元/美元自定,输出跟着口径走)
+# 用法:
+#   python3 token-cost-calc.py usage.csv --price "big-model:12:36" --price "small-model:1:2" [--budget 5000]
+#   python3 token-cost-calc.py --selftest
+# 退出码: 0=预算内 1=超预算(接月度巡检例程) 2=输入错。
+import csv
+import sys
+
+
+def load(path):
+    rows = []
+    with open(path, encoding="utf-8") as f:
+        for ln in csv.reader(f):
+            if not ln or ln[0].startswith("#") or ln[0] in ("维度", "feature", "dim"):
+                continue
+            if len(ln) < 5:
+                continue
+            rows.append((ln[0].strip(), ln[1].strip(), int(ln[2]), int(ln[3]), int(ln[4])))
+    return rows
+
+
+def report(rows, prices, budget):
+    if not rows:
+        print("[错误] usage.csv 无有效行(维度,模型,调用次数,输入token,输出token)")
+        return 2
+    agg = {}
+    unknown = set()
+    total = 0.0
+    for dim, model, calls, tin, tout in rows:
+        if model not in prices:
+            unknown.add(model)
+            continue
+        pin, pout = prices[model]
+        cost = tin / 1e6 * pin + tout / 1e6 * pout
+        a = agg.setdefault(dim, {"cost": 0.0, "calls": 0, "tin": 0, "tout": 0})
+        a["cost"] += cost
+        a["calls"] += calls
+        a["tin"] += tin
+        a["tout"] += tout
+        total += cost
+    if unknown:
+        print(f"[警告] 无价格的模型被跳过: {', '.join(sorted(unknown))} (补 --price)")
+    if not agg:
+        return 2
+    print(f"== Token 成本归因(合计 {total:,.2f}) ==")
+    print(f"{'维度':<16}{'成本':>10}{'占比':>7}{'调用':>10}{'单位任务成本':>12}{'平均输入tok':>12}")
+    for dim, a in sorted(agg.items(), key=lambda x: -x[1]["cost"]):
+        unit = a["cost"] / a["calls"] if a["calls"] else 0
+        avg_in = a["tin"] / a["calls"] if a["calls"] else 0
+        share = a["cost"] * 100 / total if total else 0
+        hot = "  <== 头部,优化路径按序:缓存→路由降级→提示瘦身(eng-ai 成本链)" if share > 40 else ""
+        print(f"{dim:<16}{a['cost']:>10,.2f}{share:>6.0f}%{a['calls']:>10,}{unit:>12,.4f}{avg_in:>12,.0f}{hot}")
+    big_in = [d for d, a in agg.items() if a["calls"] and a["tin"] / a["calls"] > 8000]
+    if big_in:
+        print(f"[黄] 平均输入 >8K token 的维度: {', '.join(big_in)} —— 上下文膨胀是最常见隐性漏钱(检查检索 topK/历史压缩,ai-llm-app 预算)")
+    if budget is not None:
+        pct_ = total * 100 / budget if budget else 0
+        print(f"预算对照: {total:,.2f} / {budget:,.2f} ({pct_:.0f}%)")
+        if total > budget:
+            print("判定: [红] 超预算 —— 触发降级策略(预先声明的降小模型/限频,禁静默断服)")
+            return 1
+        if pct_ > 80:
+            print("判定: [黄] 达预算 80% 预警线")
+    print("纪律: 单位任务成本是北极星(总额会涨,单价要降);月度归因例程化(eng-automation)。")
+    return 0
+
+
+def parse_prices(argv):
+    out = {}
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--price" and i + 1 < len(argv):
+            parts = argv[i + 1].split(":")
+            if len(parts) == 3:
+                out[parts[0]] = (float(parts[1]), float(parts[2]))
+            i += 2
+        else:
+            i += 1
+    return out
+
+
+def selftest():
+    import tempfile, os
+    with tempfile.TemporaryDirectory() as d:
+        f = os.path.join(d, "u.csv")
+        open(f, "w", encoding="utf-8").write(
+            "维度,模型,调用次数,输入token,输出token\n"
+            "合同问答,big-model,1200,42000000,2400000\n"
+            "票据识别,small-model,90000,180000000,9000000\n"
+            "会议纪要,big-model,300,9000000,3000000\n")
+        rc = report(load(f), {"big-model": (12, 36), "small-model": (1, 2)}, 1000)
+        assert rc in (0, 1)
+    print("\nselftest ok")
+    return 0
+
+
+if __name__ == "__main__":
+    a = sys.argv[1:]
+    if "--selftest" in a:
+        sys.exit(selftest())
+    if not a:
+        print("用法: token-cost-calc.py usage.csv --price '模型:输入价:输出价' [--price ...] [--budget N] | --selftest")
+        sys.exit(2)
+    budget = float(a[a.index("--budget") + 1]) if "--budget" in a else None
+    sys.exit(report(load(a[0]), parse_prices(a), budget))

package/skills/ai-multimodal/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: ai-multimodal
+description: 多模态应用链（场景判据(文档解析/表格/图表/图像生成/语音)→文档解析管道式 vs VLM 端到端判据→OCR 工程(预处理/置信度分级转人工/关键字段规则校验)→表格专项(合并单元格/跨页)→图表读数低信任纪律→图像生成合规(肖像/版权/AI 标识)→语音转写与热词→多模态评测集分层→分辨率分级成本工程）。eng-ai 的多模态孙链:发票合同识别、扫描件处理、图表问答、会议转写、图像生成功能设计时载入。
+version: 1.0.0
+---
+
+# 多模态应用链
+
+eng-ai 的多模态孙链,办公平台的主场景(票据/合同/报表/会议)。总纪律与 ai-* 各链同源:
+**评测集先行(ai-eval)、置信度不足转人工(eng-ai 人审)、关键数字可溯源**——多模态里"看错"比"想错"更隐蔽。
+
+## 场景判据表
+
+| 场景 | 技术形态 | 要点 |
+|---|---|---|
+| 票据/证照识别 | OCR+结构化抽取 | 字段级准确率是唯一口径,规则校验兜底(见 OCR 节) |
+| 合同/长文档 | 版式解析+分块(ai-rag 管道前段) | 表格与条款结构保真是难点 |
+| 报表/图表理解 | VLM 读图 | **读数低信任**(见图表节) |
+| 图像生成 | 文生图 | 办公配图/海报(brand-design 衔接);合规见生成节 |
+| 语音会议 | ASR+说话人分离 | meeting-minutes 衔接;热词定制 |
+| 拍照办公 | 手机拍摄件处理 | 预处理决定成败(dev-mobile 端上拍摄引导) |
+
+## 文档解析:管道式 vs VLM 端到端
+
+- **管道式**(版式检测→OCR→结构还原→抽取):可控、可溯源、错误可定位到环节(坏例三分类思想,ai-rag 同构)、成本低——**默认起点,金额类字段必须走可溯源路径**;
+- VLM 端到端(整页图直问模型):简单、对复杂版式鲁棒,但**幻觉风险**(没看清也答得流畅)+错误不可定位——适合低风险场景(摘要/分类)与管道兜底(版式怪异件);
+- 混合常态:管道为主+VLM 处理管道失败件+VLM 校验管道结果(双通道对比,不一致转人工);
+- 判据一句话:**输出要进账本/合同/审批的,用管道+校验;输出给人看着参考的,VLM 可**。
+
+## OCR 工程
+
+- 预处理决定上限:纠偏/去噪/二值化判据/分辨率下限(低于阈值提示重拍而不是硬识,拍摄引导做在端上);
+- 分类分治:印刷体/手写体/表格/印章分开对待(手写与印章单独评测,准确率预期要对业务讲清);
+- **置信度分级**:高置信自动通过/中置信人工复核队列/低置信直接人工——阈值用评测集标定(ai-eval 校准思想),**复核队列的人机界面要好用**(逐字段对照原图,eng-ux);
+- **关键字段规则校验**(便宜且必做):金额(大小写互验/合计=明细和)/日期合法性/证件号校验位/发票号规则/税率枚举——OCR 说"识别成功"不算数,**规则过了才算数**;
+- 多要素勾稽:票面字段互验(金额×税率≈税额),不平即标记(anomaly 思想)。
+
+## 表格专项（办公场景的硬骨头）
+
+难点分层建测试集(ai-eval 样本分层):规则表格→合并单元格→无线表格→跨页表格→嵌套表格;
+结构还原口径:单元格内容准确率与**结构还原率**(行列关系对不对)分开测——内容全对结构错位=数字张冠李戴,比识别错更危险;
+跨页表格:表头继承与断行合并策略;
+输出格式:结构化(JSON/markdown 表)带单元格坐标(溯源到原图位置,复核界面靠它)。
+
+## 图表理解（读数低信任纪律）
+
+**图表读数默认低信任**:VLM 从柱状图/折线图"读"出的数值是估计不是读取——
+关键数据回原始数(图表问答场景优先要底表,没有底表则输出标注"图上估读");
+适合的任务:趋势描述/结构理解/异常点指认(定性);不适合:精确数值抽取进报表(定量)——**定性可托,定量要源**;
+评测:图表理解单独评测集(定性判断准确率+读数误差分布)。
+
+## 图像生成（合规先行）
+
+办公场景判据:配图/示意图/海报初稿(brand-design 规范约束:品牌色与字体后期把控);
+**合规红线**:真人肖像生成与深度合成的标识义务(按属地法规:AI 生成内容显式标识)/版权风险(风格模仿的边界)/敏感内容过滤(生成前提示词过滤+生成后内容审核双层);
+可用性纪律:生成结果人选后用(不直出),企业素材库沉淀(好结果入库复用,省成本);
+提示词资产化(ai-prompt 版本化同则)。
+
+## 语音转写
+
+会议场景链:ASR 转写→说话人分离→**热词定制**(人名/产品名/行业术语表,不定制=专名全错)→纪要生成(meeting-minutes 结构);
+质量分层:录音质量检测前置(提示改善拾音,预处理同 OCR 思想);
+转写稿标注置信度低的片段(纪要引用原话时人工核对该片段);
+合规:录音告知与同意(会议录制提示,legal 属地要求)。
+
+## 评测（ai-eval 方法+多模态特有）
+
+评测集分层:按难度(清晰扫描/手机拍摄/低质)×按类型(票据/表格/手写)——**线上分布对齐**(评测全是清晰件,线上全是手机拍=虚高);
+指标:字段级准确率(按字段报,金额字段单列)/结构还原率/端到端通过率(全字段对才算过);
+坏例回流:复核队列的人工修正=天然标注数据(回流评测集与优化,ai-eval 生命线);
+版本回归:OCR 引擎/VLM/提示变更跑全量评测(eng-ai 三元组纪律)。
+
+## 成本工程（多模态 token 贵）
+
+图片 token 与分辨率挂钩:**分辨率分级**(缩略图初判→高清重识低置信件,两级调用省大头);
+页数预算:长文档先版式过滤(空白页/无关页不进模型);
+批量错峰(非实时票据夜间批处理,ai-mlops 优先级队列);
+成本归因按场景(票据/合同/会议分开算单件成本,ai-mlops 单位任务成本)。
+
+**作业包**:`scripts/field-validate.py`(身份证与统一社会信用代码校验位、金额数字↔大写互验、日期合法性、批量模式——规则过了才算识别成功)。
+
+## 使用纪律
+
+关键字段规则校验必配;置信度分级转人工;图表定量不直采;生成内容合规标识;
+评测集与线上分布对齐,坏例周回流;
+每次识别事故回写:样本入难度层+规则校验补一条——**多模态的信用=复核队列越来越短,而不是模型吹得越来越神**。

package/skills/ai-multimodal/scripts/field-validate.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# 关键字段规则校验器（ai-multimodal"OCR 说成功不算数,规则过了才算数"的可执行版）。stdlib,零依赖。
+# 支持: 身份证 18 位校验位 / 统一社会信用代码 / 金额数字↔中文大写互验 / 日期合法性 / 手机号。
+# 用法:
+#   python3 field-validate.py idcard 11010519491231002X
+#   python3 field-validate.py uscc 91350100M000100Y43
+#   python3 field-validate.py amount 1234.56 壹仟贰佰叁拾肆元伍角陆分
+#   python3 field-validate.py date 2026-02-30
+#   python3 field-validate.py batch fields.csv        # CSV: 类型,值[,辅助值] → 全量报告
+#   python3 field-validate.py --selftest
+# 退出码: 0=全过 1=有不过(进人工复核队列) 2=输入错。OCR 管道里低置信+规则不过=必转人工。
+import re
+import sys
+from datetime import datetime
+
+
+def check_idcard(v, _extra=""):
+    v = v.strip().upper()
+    if not re.fullmatch(r"\d{17}[\dX]", v):
+        return False, "格式错(须 17 位数字+校验位)"
+    w = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2]
+    m = "10X98765432"
+    s = sum(int(v[i]) * w[i] for i in range(17))
+    if m[s % 11] != v[17]:
+        return False, f"校验位错(应为 {m[s % 11]})——OCR 高发混淆: 0/O、1/7、5/S"
+    try:
+        datetime.strptime(v[6:14], "%Y%m%d")
+    except ValueError:
+        return False, "出生日期段非法"
+    return True, "通过"
+
+
+def check_uscc(v, _extra=""):
+    v = v.strip().upper()
+    chars = "0123456789ABCDEFGHJKLMNPQRTUWXY"
+    if len(v) != 18 or any(c not in chars for c in v):
+        return False, "格式错(18 位,不含 I/O/Z/S/V)"
+    w = [1, 3, 9, 27, 19, 26, 16, 17, 20, 29, 25, 13, 8, 24, 10, 30, 28]
+    s = sum(chars.index(v[i]) * w[i] for i in range(17))
+    cd = chars[(31 - s % 31) % 31]
+    if cd != v[17]:
+        return False, f"校验位错(应为 {cd})"
+    return True, "通过"
+
+
+_DIG = "零壹贰叁肆伍陆柒捌玖"
+_UNIT4 = ["", "拾", "佰", "仟"]
+
+
+def _four(n):  # 0-9999 → 中文
+    if n == 0:
+        return ""
+    out, zero = "", False
+    for i in range(3, -1, -1):
+        d = n // (10 ** i) % 10
+        if d:
+            if zero:
+                out += "零"
+            out += _DIG[d] + _UNIT4[i]
+            zero = False
+        elif out:
+            zero = True
+    return out
+
+
+def amount_to_cn(x):
+    fen = int(round(float(x) * 100))
+    if fen == 0:
+        return "零元整"
+    yuan, jf = divmod(fen, 100)
+    jiao, f = divmod(jf, 10)
+    parts = []
+    yi, rest = divmod(yuan, 10 ** 8)
+    wan, ge = divmod(rest, 10 ** 4)
+    if yi:
+        parts.append(_four(yi) + "亿")
+    if wan:
+        if yi and wan < 1000:
+            parts.append("零")
+        parts.append(_four(wan) + "万")
+    if ge:
+        if (yi or wan) and ge < 1000:
+            parts.append("零")
+        parts.append(_four(ge))
+    cn = "".join(parts) + "元" if yuan else ""
+    if jiao == 0 and f == 0:
+        return cn + "整"
+    if not yuan:
+        cn = ""
+    if jiao:
+        cn += _DIG[jiao] + "角"
+    elif yuan and f:
+        cn += "零"
+    if f:
+        cn += _DIG[f] + "分"
+    return cn
+
+
+def check_amount(v, cn=""):
+    try:
+        expect = amount_to_cn(v)
+    except (ValueError, TypeError):
+        return False, "数字金额非法"
+    if not cn:
+        return True, f"大写应为: {expect}"
+    got = cn.strip().replace("人民币", "").replace("圆", "元")
+    if got == expect:
+        return True, "数字与大写互验通过"
+    return False, f"互验不过: 大写按数字应为「{expect}」,OCR 读到「{cn}」——两处必有一错,转人工(票面多要素勾稽)"
+
+
+def check_date(v, _extra=""):
+    v = v.strip().replace("/", "-").replace(".", "-").replace("年", "-").replace("月", "-").replace("日", "")
+    try:
+        d = datetime.strptime(v, "%Y-%m-%d")
+    except ValueError:
+        return False, "日期非法(2 月 30 日类=OCR 误读)"
+    if not (1990 <= d.year <= 2100):
+        return False, f"年份 {d.year} 超合理范围(OCR 年份位错读嫌疑)"
+    return True, "通过"
+
+
+def check_mobile(v, _extra=""):
+    v = re.sub(r"[ -]", "", v.strip())
+    if re.fullmatch(r"1[3-9]\d{9}", v):
+        return True, "通过"
+    return False, "手机号格式错"
+
+
+CHECKS = {"idcard": check_idcard, "uscc": check_uscc, "amount": check_amount, "date": check_date, "mobile": check_mobile}
+
+
+def batch(path):
+    import csv as _csv
+    bad = 0
+    with open(path, encoding="utf-8") as f:
+        for i, ln in enumerate(_csv.reader(f), 1):
+            if not ln or ln[0].startswith("#") or ln[0] in ("类型", "type"):
+                continue
+            t = ln[0].strip().lower()
+            if t not in CHECKS:
+                print(f"  行{i} [跳过] 未知类型 {t}")
+                continue
+            ok, msg = CHECKS[t](ln[1] if len(ln) > 1 else "", ln[2] if len(ln) > 2 else "")
+            if not ok:
+                bad += 1
+            print(f"  行{i} [{'过' if ok else '不过'}] {t} {ln[1][:24] if len(ln) > 1 else ''}: {msg}")
+    print(f"---- 批量结果: 不过 {bad} 条 → 进人工复核队列 ----")
+    return 1 if bad else 0
+
+
+def selftest():
+    assert check_idcard("11010519491231002X")[0]
+    assert not check_idcard("110105194912310021")[0]
+    assert check_uscc("91350100M000100Y43")[0]
+    assert not check_uscc("91350100M000100Y44")[0]
+    assert amount_to_cn(1234.56) == "壹仟贰佰叁拾肆元伍角陆分"
+    assert amount_to_cn(100000001.05) == "壹亿零壹元零伍分"
+    assert amount_to_cn(200) == "贰佰元整"
+    assert check_amount("1234.56", "壹仟贰佰叁拾肆元伍角陆分")[0]
+    assert not check_amount("1234.56", "壹仟贰佰叁拾肆元整")[0]
+    assert not check_date("2026-02-30")[0]
+    assert check_mobile("13812345678")[0]
+    print("selftest ok: 身份证/信用代码/金额互验/日期/手机号全部正常")
+    return 0
+
+
+if __name__ == "__main__":
+    a = sys.argv[1:]
+    if "--selftest" in a:
+        sys.exit(selftest())
+    if not a:
+        print("用法: field-validate.py idcard|uscc|amount|date|mobile <值> [辅助值] | batch fields.csv | --selftest")
+        sys.exit(2)
+    if a[0] == "batch" and len(a) > 1:
+        sys.exit(batch(a[1]))
+    if a[0] in CHECKS and len(a) > 1:
+        ok, msg = CHECKS[a[0]](a[1], a[2] if len(a) > 2 else "")
+        print(("[过] " if ok else "[不过] ") + msg)
+        sys.exit(0 if ok else 1)
+    print("参数错;--selftest 看示例")
+    sys.exit(2)

package/skills/ai-prompt/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ai-prompt
+description: 提示工程链（六段式提示结构与稳定前缀→技法判据表(zero/few-shot/CoT/分步拆链)→反模式清单(否定指令/矛盾/堆砌)→一次一变量迭代纪律→提示资产版本化与回归→提示解决不了的问题分诊）。eng-ai 的提示工程孙链:写系统提示、输出不稳定调优、提示越写越长失控、"多加一句就好了"魔咒时载入。
+version: 1.0.0
+---
+
+# 提示工程链
+
+eng-ai 的提示工程孙链。基调:提示工程是**工程**——有结构、有版本、有评测对照;
+凭感觉改提示=凭感觉改生产代码。
+
+## 六段式提示结构（默认骨架,顺序即缓存设计）
+
+1. **角色与目标**:一句话人设+任务使命(具体胜于华丽:"你是报销制度问答助手,只依据提供的制度条文回答");
+2. **规则约束**:行为边界(什么必须做/什么不许做),按重要性排序,**条数控制在 10 条内**(规则越多单条权重越稀);
+3. **输出格式**:结构说明+能上 schema 就上 schema(格式靠约束不靠恳求,ai-llm-app 结构化三层);
+4. **示例**(按需):输入输出对,见技法判据;
+5. **动态上下文**:检索内容/用户资料(与指令结构隔离,注入防护标记,ai-rag);
+6. **本次输入**:用户问题放最后(近因效应+缓存友好)。
+**稳定内容前置、可变内容后置**——前缀缓存命中率是这么来的(ai-llm-app 缓存判据);系统提示里禁时间戳/随机数。
+
+## 技法判据表
+
+| 技法 | 启用信号 | 要点与代价 |
+|---|---|---|
+| zero-shot | 默认起点 | 指令写清就够,别一上来堆示例 |
+| few-shot | 格式模仿/风格对齐/分类边界模糊 | 2–5 个覆盖边界的示例(含"该拒答的例");示例是最强的隐性指令,**示例与规则冲突时模型信示例** |
+| CoT 分步思考 | 推理/计算/多条件判断 | "先分析再结论";推理型模型自带思考,再叫嚷 CoT 反而冗余,按模型调 |
+| 任务拆链 | 单提示揉不下(先抽取再校验再生成) | 拆成多次调用各司其职,可测可缓存;代价是时延与编排(工作流化,ai-agent 判据) |
+| 自检后缀 | 高错误代价输出 | "输出前检查:引用是否都在原文中"——便宜有效的最后一道 |
+
+## 反模式清单（改提示先对照这里）
+
+- **否定指令弱**:"不要长篇大论"不如"控制在 3 句内";"不要编造"不如"仅依据资料回答,资料未涵盖则回答'未找到'"(给出路,不只堵路);
+- 矛盾指令:"详细全面"+"简明扼要"并存=模型随机选边;规则间冲突要裁决出优先级;
+- 万字堆砌:每次出错加一句补丁,提示滚成裹脚布——**定期重构提示**(合并/删除/重排,同代码重构,refactor-safely 精神);补丁式提示的规则相互稀释;
+- 示例污染:示例里的偶然特征被模型当规律(示例全是北京的地址→模型以为只服务北京);
+- 拟人恳求与威胁("这对我很重要"):不稳定的魔法,用结构化约束替代;
+- 把知识塞提示:大量事实性内容进系统提示=贵且难更新,该走 RAG(ai-rag 判据)。
+
+## 迭代纪律（一次一变量）
+
+改前有基线:评测集跑分(ai-eval,20 条冒烟起步)——**没有评测集的提示调优是掷骰子**;
+一次只改一处(改了三处变好了=不知道哪处有效,下次复制不了经验,eng-performance 同则);
+坏例驱动:从失败案例归纳模式(格式错?理解偏?越界?)针对性改,不做"感觉性全文重写";
+过拟合警惕:为一个坏例加的规则,跑全量评测确认没伤其他案例(修一个坏三个是常态);
+显著性心智:LLM 非确定性下,单次对比无意义,同题多跑或大样本对比(ai-eval 方法)。
+
+## 提示资产管理（提示=代码）
+
+版本化入库:提示文件与代码同仓同评审(diff 可见,eng-docs docs-as-code);
+**变更走评测回归**:提示改动=行为变更,评测集全跑+劣化阻断(eng-ai 三元组纪律);
+模板参数化:动态段用模板变量(检索内容/用户名),模板引擎统一(拼字符串散装=注入与转义隐患);
+多模型适配:同一任务在不同模型上的提示变体分开维护并分别评测(换模型≠提示白嫖通用);
+提示注释:关键规则旁注"为什么有这条"(哪次坏例加的)——防后人误删,也防补丁堆积无人敢动。
+
+## 提示解决不了的问题（分诊,别死磕）
+
+| 症状 | 真病因 | 转诊 |
+|---|---|---|
+| 缺知识/答陈旧 | 模型不知道 | RAG(ai-rag),别在提示里塞百科 |
+| 复杂任务步步错 | 单次调用超能力上限 | 拆链/上 Agent(ai-agent)或换更强模型 |
+| 格式老不稳 | 恳求无用 | 结构化约束(ai-llm-app 三层防线) |
+| 风格顽固不改 | 提示带不动 | 微调判据(eng-ai:改风格是微调正当理由) |
+| 快但要更准/准但要更快 | 模型层级不匹配 | 路由分级(ai-llm-app),不是提示的锅 |
+
+**提示是杠杆不是魔法**:撬得动的尽快撬,撬不动的认账转诊——在提示上耗一周常常不如换个方案半天。
+
+**作业包**:`references/prompt-template.md`(六段式骨架(缓存友好)/迭代记录表(一次一变量)/补丁注释规范/分诊速查)。
+
+## 使用纪律
+
+系统提示改动走评审+评测回归;稳定前缀纪律守住缓存命中;
+每个生效的"补丁规则"标注来源坏例;季度重构一次提示(熵减);
+**提示工程的复利在评测集与坏例注释,不在收藏一百个"神奇咒语"**。