跳到主要内容

审查现有技能

什么时候读：用户给了一个技能目录/文件，要求「检查是否符合规范」「帮我过一遍」「上线前审一下」。

流程​

  1. 跑静态检查：python3 scripts/check_skill.py <skill_dir>。ERROR 是硬约束违反，WARN 需人工确认，INFO 是提示。 脚本退出码非 0 表示有 ERROR。加 --json 可得结构化结果。
  2. 定形态：看脚本第二行的「形态判定」。据此只读对应的 type-*.md，再对照脚本每条 [§x.y] 标注去翻原文。
  3. 人工过脚本测不到的：脚本末尾列了「必须人工/真库验证」。逐条问用户是否验过，没验过的写进报告。
  4. 按段核 checklist：checklist.md 只核适用段（不碰数据表跳过数据表段）。
  5. 出报告。

报告格式​

## 审查：<skill_name>
形态：<handler(python) / CLI / skill_md / ...>

### 必须改（上线会静默出错或被平台拒绝）
- [§2.3] 入口第二参数有默认值 → ctx 丢失。改法：去掉 `=None`。
- ...

### 建议改
- [§6.1] ...

### 未验证（脚本测不到，需真跑）
- [ ] ...

### 符合
<一行带过，不逐条列>

每条写：规范条号、现象、后果、改法。不写「已按规范」这种无法核验的结论。

脚本覆盖范围​

能查：安装预检镜像（handler.py 里有 execute、参数名 input_data / runtime_context、async def；name 规则与目录名一致—— 这些 create_skill / edit_skill 会直接拒，报 ERROR）；frontmatter 必填与长度、YAML「冒号+空格」未加引号、category 白名单、 cost-tier 取值、平台字段只写在 metadata 下、有无 env 声明；schema 形状、required 一致性、身份字段、凭证子串、x-actions 不生效提示； 入口函数名/参数默认值/async； CLI 与进程内形态误判；emp_no / input_data 身份字段；代填空值分支；部门路径匹配；凭证常量名与硬编码； 失败无 error、transient 标 non_retriable、指令式「下一步」；动作型缺 need_param / 无归一 / 自补确认； JSONB、PRIMARY KEY、自建连接（create_engine）、SQL 冒号占位、无 WHERE、information_schema； 直连库读 ctx["db"]（新技能应改 db_factory 现开现还，WARN）、写无 commit、裸 SQL 建表； call_skill 前无 commit、未判返回、收件人取 actor_*；跨技能 import；长循环不看 abort_signal；references 超 40000； 工作区回退 os.getcwd()、自拼下载链接；attachments 读 att_type；display_only 不生效提示； 文档型目录里有 openapi.* / endpoints_whitelist.*（会被判成 API 型）； 面板：ui 入口合法与存在、未声明却有 panel.html/ui.html/index.html、无 handler、schema 缺 action.enum、站点根路径 / /api 引用、 CSS url() 与 JS 相对 import、localStorage、fetch/XHR、缺 skill_panel + ready 握手、入口目录树里的可公开读取文件、外部面板却带本地文件。

不能查：真库行为、行级过滤实际效果、allow_sql 注入状态、description 触发效果、部分成功的计数是否真实、 产物是否真落盘。这些在「必须人工验证」里。

常见误报​

  • 常量名含 auth / key（如 AUTHOR、KEYWORDS）：平台确实按子串匹配，改名是对的，不算误报。
  • .get("actor_xxx", "")：INFO 级，不算错，只是多余。
  • 动作型的「未见归一」：用了别的命名（如 CANON）时会误报，看一眼代码即可。
  • user_message 里「请联系管理员配置」且 error_type=config：合理，不触发。
  • 读 ctx["db"]：新技能应改 db_factory 现开现还（spec §7A / code-facts §3.7），报 WARN 非 ERROR——ctx["db"] 仍对老技能注入、读了能跑，是迁移项（pending-issues ISSUE-3），别按硬错拦上线。注释与文档字符串里提到 ctx["db"] 不算。
  • 入口 / name 类 ERROR 对「只走 zip 安装的老技能」是警告级（zip 安装不拦），但只要会经 create_skill / edit_skill 改动就会被拒，仍按 ERROR 改。
  • 面板「入口目录树里的 .json 可公开读取」：入口放根目录时 schema.json 也会被点到——这是真实暴露面（schema 本身无害），按建议把面板挪进 ui/ 子目录即消失。