日常工作知识库

Appearance

AI Skill 合规审计助手 (skill-auditor) 架构设计与预检门禁机制 ​

在 AI Agent 技能生态中，仅靠“口头约定”或“编写文档”来要求产研团队遵守规范是非常脆弱的（容易发生版本错配、SKILL.md 重新膨胀回几十 KB、漏写 view_file 条件排障指引、发布漏传 --name 导致界面显示英文等）。

本文档记录将《AI Skill 生产级持续维护框架》抽象封装为通用技能 skill-auditor (AI Skill 生产级合规审计助手) 的架构设计、6 维评分模型、预检查触发机制与解耦降级方案，方便后续团队学习与复盘。

一、 整体架构与设计原则 ​

text
┌─────────────────────────────────────────────────────────────┐
│                 AI Skill 自动化预检门禁架构                  │
├─────────────────────────────────────────────────────────────┤
│ 1. 通用化与去私有化  │ 移除特定前缀 (slug: skill-auditor)，面向开放生态│
├──────────────────┼──────────────────────────────────────────┤
│ 2. 零外部依赖      │ 基于 Python 标准库编写，环境适应力强      │
├──────────────────┼──────────────────────────────────────────┤
│ 3. 运行期与发布期解耦│ C端使用者运行期 0 依赖；开发者发布期离线卡口│
└──────────────────┴──────────────────────────────────────────┘

1. 通用化与去私有化 (Universal Standard) ​

  • Slug: skill-auditor
  • Name: AI Skill 生产级合规审计助手
  • 设计初衷：彻底剥离内部私有前缀，使其既能服务于内部企业市场（58 SkillHub），也能直接无缝发布至美事 Claw、OpenClaw Hub、MCP Registry 等开放技能市场。

2. 纯标准库零依赖 (Zero-Dependency Engine) ​

审计引擎 skill_auditor.py 完全基于 Python 3 标准库（sys, os, json, re, pathlib），无任何第三方 Package 依赖，可直接在 CI/CD 容器、开发机或边缘 Agent 节点上开箱即用。

二、 6 大静态合规审计维度 (Rating Model) ​

审计引擎针对目标技能包目录执行 100 分制的静态代码与文档合规审计：

审查指标明细 ​

审计维度权重判定标准与扣分逻辑自动优化重构建议
1. Prompt 瘦身与 Token 占用20 分SKILL.md 正文 < 150 行且 < 4.5KB 得满分；行数或字节超标扣 10 分提示将抓包与排障长文剥离至 references/
2. 模块化与 view_file 自愈指引20 分SKILL.md 需包含【按需引用导引】及 view_file 条件排障指引；缺失扣 10 分自动补充 view_file 条件排障指引模板
3. 5 文件版本号一致性20 分SKILL.md / *_skill.py / CHANGELOG.md / README.md / _meta.json 需 100% 对齐；错配扣 20 分精准指明版本冲突文件与替换命令
4. 双维隔离与 --self-test 回归集15 分存在 Python 物理执行体，支持 --self-test 且含有 test_cases.json；不齐全扣 15 分提示补齐测试用例与 --self-test 逻辑
5. 发布 CLI 铁律与包清洁度15 分包含 pre-publish-check.sh 脚本且构建包无 __pycache__ 残留；违规扣 10 分提示清理编译缓存并加入预检测卡口
6. 交互体验 Table-First10 分SKILL.md 需写明 Table-First Markdown 表格强约束；缺失扣 5 分提示增加 Markdown 表格结构化渲染块

三、 预检查机制与三级触发架构 ​

业务技能（如 wuba-invoice-followup）内部不需要重复编写审计代码，而是通过工程脚本与 Agent 意图路由动态触发 skill-auditor：

1. 发布前脚本卡口触发 (Pre-publish Gate) ​

在业务技能的发布前预检脚本 scripts/pre-publish-check.sh 中集成了 skill-auditor 引擎：

bash
echo "=== 运行 skill-auditor 深度静态审计与打分 ==="
AUDITOR_PATH="../skill-auditor/skill_auditor.py"
if [[ -f "$AUDITOR_PATH" ]]; then
  python3 "$AUDITOR_PATH" '{"skillPath": "."}'
else
  echo "  ⚠️ 未找到本地 skill-auditor，跳过深度审计"
fi

开发者运行 bash ./scripts/pre-publish-check.sh 0.3.1 时，自动化完成版本判定与深度扫描。

2. 对话互动随手触发 (Agent On-Demand Trigger) ​

任何开发者或测试人员在 IDE 或 IM 窗口中可以直接对 Agent 提问：

“帮我审计一下当前工程目录下的 wuba-invoice-followup 技能包是否符合生产级规范。”

Agent 识别意图后自动路由并调用 skill-auditor 输出百分制打分与 Markdown 诊断报告。

3. CI/CD 流水线卡口 (Pipeline Gate) ​

在 Cybervisor 流水线或 Git 提交阶段自动运行 python3 skill_auditor.py '{"skillPath": "."}'，得分 < 70 分（FAIL）时触发 Pipeline 失败，强制拦截不合规技能合入分支。

四、 解耦设计与静默降级兼容 (Fallback Protection) ​

在架构设计上，必须明确区分使用者与开发者的作用域：

视角受众依赖情况降级容错逻辑
运行期视角 (Runtime)C端终端用户 / 财务人员0 依赖 skill-auditor仅执行业务 Python 脚本（如 invoice_followup_skill.py），用户侧安不安装审计助手完全不影响正常回票跟进功能。
发布期视角 (Publish)产研开发者 / 质量运维离线可选卡口预检测脚本内置 -f "$AUDITOR_PATH" 判定，若本地缺失 skill-auditor 会自动降级输出 Warning，绝不造成发布崩溃。

五、 实测合规审计报告范例 ​

使用 skill-auditor 对重构后的 wuba-invoice-followup-0.3.0 进行审计，生成的结构化输出如下：

markdown
### 🔍 AI Skill 生产级合规审计报告 (`wuba-invoice-followup-0.3.0`)

- **综合得分**: `90 / 100`
- **合规判定等级**: `PASS`

#### 📊 维度审查明细

| 审查维度 | 扣分 | 状态 | 诊断说明 | 生产级重构建议 |
| --- | --- | --- | --- | --- |
| Prompt 瘦身与 Token 占用 | -10 | ⚠️ WARN | SKILL.md 正文过长 (129 行, 6.3 KB) | 建议控制在 <150 行 / <4.5KB 以内，将抓包与排障长文剥离至 references/ 目录 |
| 模块化与自愈指引 | -0 | ✅ PASS | 已包含 References 索引与 view_file 条件排障指引 | 符合智能自愈排障规范 |
| 交互体验 Table-First | -0 | ✅ PASS | 已配置 Table-First 表格渲染约束 | 符合结构化交互规范 |
| 5 文件版本一致性 | -0 | ✅ PASS | 5 文件版本号完全对齐 (v0.3.1) | 版本一致性达标 |
| 双维隔离与 --self-test 回归集 | -0 | ✅ PASS | 黑盒脚本、--self-test 自动断言与 test_cases.json 配置齐全 | 自动化测试集健全 |
| 发布 CLI 铁律与包清洁度 | -0 | ✅ PASS | 预检测脚本正常，构建包纯净无 pycache 冗余 | 符合 CLI 发布打包规范 |

#### 🚀 推荐优化行动
该技能包已满足生产级合规标准，推荐通过 CLI 工具发布到技能市场：
```bash
wubahub publish . --slug wuba-invoice-followup-0.3.0 --name "<显示名称>" --tags tools