日常工作知识库

Appearance

AI Skill 双维隔离设计范式、自动升级机制与 skill-auditor 架构复盘 ​

在 AI Agent（如 OpenClaw、Hermes、Claude Code 等）的技能开发实践中，传统的技能编写往往容易落入 “把一切说明、运维提示与调试长文全塞进 SKILL.md” 的误区。这不仅导致技能包体积臃肿，还会引发大模型注意力稀释（Context Dilution），降低指令遵循率。

本文档深度总结梳理 双维隔离原则 (Dual-Aspect Isolation)、自动检查更新能力 (auto-update) 的工程解耦，以及 skill-auditor 通用合规审计助手 的架构实现与门禁约束，供后续产研团队学习与复盘。

一、 双维隔离原则 (Dual-Aspect Isolation) 深度拆解 ​

生产级 AI Skill 必须实现物理代码与语义指令的彻底解耦：

text
┌─────────────────────────────────────────────────────────────┐
│                 AI Skill 生产级双维隔离架构                  │
├──────────────────────────────┬──────────────────────────────┤
│ 维 1：物理执行体 (*.py 脚本)  │ 维 2：控制 Prompt (SKILL.md) │
│ - 承担 HTTP 网络交互与 API 逻辑│ - 面向 LLM 大模型，仅保留核心指令 │
│ - 自动检查更新与静默升级     │ - 参数格式强校验 (如简称拦截) │
│ - 算术精确加减与尾差比对     │ - 格式约束 (Table-First 渲染)│
│ - 容错降级与多环境兼容 (Cron)│ - 按需引用导引 (References)   │
└──────────────────────────────┴──────────────────────────────┘

1. 维 1：物理执行体 (*.py 脚本) ​

  • 职责：作为黑盒工具，承担所有网络请求、数据归一化算术、算法精度计算、mis_auth 动态 Token 刷新、分页切片降级与底层自动检查更新 (auto-update)。
  • 原则：具有确定性的物理逻辑绝不交由 LLM 推理；内部增加顶层全包裹防护，保证即使出现未捕获异常也优雅吐出 JSON，避免上层 Agent 抛出 Shell 崩溃发红。

2. 维 2：控制 Prompt (SKILL.md) ​

  • 职责：面向大模型（LLM）的极简操作与约束指南。正文严格控制在 < 150 行 / < 4.5KB。
  • 原则：只保留意图识别、参数强校验（例如拒绝“天津赶集”简称，引导用户输入全称“天津赶集信息技术有限公司”）、多字样 OR 语义及全量 Markdown 表格渲染约束。
  • 消噪：彻底清除大模型不需要关心的“底层脚本如何向 skill-market 检查版本”、“抓包对比日志”、“curl 报错堆栈”等运维噪声，避免 Context Window 被无谓污染。

二、 自动检查更新能力 (Auto-Update) 架构设计 ​

在 v0.3.x 版本的升级复盘中，针对“为何在 SKILL.md 中移除了自动更新检查文案，而功能依然存在”的问题，其解耦机制如下：

解耦原则 ​

  1. 运行期物理静默检查：物理 Python 脚本在 main() 启动时隐式触发 check_market_update()，全过程对 LLM 保持透明，不占用 LLM 任何推理 Token。
  2. 面向人类的运维说明沉淀：版本的更新机制、CLI 校验命令及发布规范，统一剥离并归位至面向人类工程师的 README.md 与 references/publishing.md 中，方便离线查阅。

三、 skill-auditor 通用合规审计助手架构实现 ​

为防止规范流于口头约定，我们抽象并独立发布了通用型 AI Skill 合规审计助手 skill-auditor (v0.1.0)。

1. 6 大合规审计维度 (100 分制) ​

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

2. 预检查门禁卡口 (pre-publish-check.sh) ​

在业务技能（如 wuba-invoice-followup）的发布前预检脚本中集成了 skill-auditor：

bash
echo "=== 3. 运行 skill-auditor 深度静态审计与打分 ==="
AUDITOR_PATH="../skill-auditor/skill_auditor.py"
if [[ -f "$AUDITOR_PATH" ]]; then
  python3 "$AUDITOR_PATH" '{"skillPath": "."}'
else
  echo "  ⚠️ 未找到本地 skill-auditor，跳过深度审计"
fi
  • 预检门禁：版本对齐且 skill-auditor 得分 ≥ 70 (PASS/WARN) 时才允许执行 wubahub publish，实现发布离线卡点与优雅降级。

四、 产研复盘 Checklist ​

  • [ ] 物理与语义分离：SKILL.md 保持极简高浓缩（< 150 行），底层 check_market_update 等逻辑写在 .py 中。
  • [ ] References 按需引用：抓包、排障指南与 API 设计长文剥离至 references/，在 SKILL.md 底部建立索引。
  • [ ] 5 文件版本一致：发布前确认 SKILL.md / *.py / CHANGELOG.md / README.md / _meta.json 版本号全量一致。
  • [ ] 预检测与 --self-test：发布前运行 ./scripts/pre-publish-check.sh <version> 与 --self-test 自动化单元测试。
  • [ ] 发布 CLI 参数铁律：wubahub publish 必须显式携带 --slug 与 --name 参数。