AAS 技能内容评审实践指南：以 lint-and-validate 与 sql-optimization-patterns 的定向复核为例

AAS 技能内容评审实践指南以 lint-and-validate 与 sql-optimization-patterns 的定向复核为例【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文基于 agentic-awesome-skillsAAS仓库中的评审记录 docs/contributors/content-review-followup-2026-09-05.md完整拆解一次有边界、可复现、可验证的技能内容复核流程它以日常维护中高频使用的lint-and-validate与sql-optimization-patterns两个技能树为样本围绕检查未运行不得误报为通过注解统计不得重复计数SQL 示例必须可执行且语义严谨三类问题展开修复并配套 6 个真实可运行的回归用例。读完本文你将掌握如何为技能文档设计可执行的工作示例worked example、如何用 AST 与子进程做行为验证、如何用 SQLite 内存库校验发布出的 SQL 代码以及如何以不越界、不夸大的方式撰写评审证据与局限性声明。一、评审背景为什么需要一次有边界的定向复核在 AAS 仓库中技能Skill是供 Agent 直接调用的可执行指导文档位于 skills 目录每份技能由SKILL.md与其附带脚本、资源共同组成。仓库此前已有一份 docs/contributors/content-review-2026-09-05.md覆盖了 20 个高优先级技能与 8 组同体技能属于全量抽查性质。而本次关联文档记录的是第二次、刻意收敛范围的复核follow-up它有两个鲜明特征范围明确仅完整覆盖lint-and-validate与sql-optimization-patterns两棵技能树不构成对整个目录的认证not a whole-catalog certification证据优先评审不采集流行度或使用量数据所有结论都来自源码阅读、脚本执行与测试用例。选择这两个技能的理由也很实在——它们分别提供可执行的校验validation示例和SQL 示例属于日常维护中被反复引用的内容最值得用可运行代码去证明文档所言非虚。二、修复一Lint 运行器——未检查绝不能被误报为通过2.1 修复前的问题评审发现旧的lint_runner.py存在一个对 Agent 极其危险的缺陷当项目没有配置任何检查时运行器之前会返回passed: true并退出码 0。这等于告诉 Agent校验全部通过而实际上什么检查都没有跑。本次修复确立了三条行为契约lint_runner.py未配置检查 → 明确报告not-checked退出码 2在 lint_runner.py#L127-L139当检测不到任何 linter 时输出 JSON 中的status字段为not-checkedpassed为false并以退出码 2 终止与失败exit 1区分开——失败说明检查跑了但没过not-checked说明检查根本没跑。无效的项目元数据是显式失败若package.json无法解析如 JSON 语法错误detect_project_type 会抛出ValueErrormain 捕获后同样以退出码 2 终止并输出错误信息而不是静默跳过。Node 回退检查器必须解析本地已安装的二进制当package.json声明了eslint/typescript依赖但没有对应lint脚本时命令路径会指向项目的node_modules/.bin/eslintWindows 下为eslint.cmd或node_modules/.bin/tsc见 lint_runner.py#L47-L52。绝不允许npx在运行期悄悄下载一个检查器——这既是安全检查避免执行来路不明的代码也是诚实性问题检查器不存在时应当报告未运行而不是现场安装后佯装通过。运行器的其余设计同样值得记录检测逻辑以package.jsonNode与pyproject.toml/requirements.txtPython为判定依据Python 侧会生成ruff check .与mypy .候选命令单个 linter 通过subprocess.run以 120 秒超时执行stdout 截断到 2000 字符、stderr 截断到 500 字符见 lint_runner.py#L71-L102。最终汇总输出一段 JSON包含script、project、type、checks与passed字段供 Agent 直接消费。2.2 对应的回归测试上述三条契约不是评审口头的承诺而是被 tools/scripts/tests/test_skill_worked_examples.py 中的真实子进程测试锁定的test_no_checks_and_invalid_metadata_are_not_success在空临时目录中运行lint_runner.py断言退出码为 2 且 stdout 含passed: false再写入一个内容为{的非法package.json断言同样退出码 2。test_node_fallback_never_downloads_a_checker构造一个仅声明typescript与eslint依赖的临时项目断言检测出的两个命令路径都包含node_modules且运行run_linter返回passed False因为本地并没有真正的二进制。2.3 手动复现在仓库根目录执行python3 tools/scripts/tests/test_skill_worked_examples.py需要强调的是该套件使用 Python 标准库与 SQLite不连接真实数据库、不运行外部 linter、不测量查询速度Python 与 Node 的项目检测本质上是启发式的实际使用时应先查看项目说明并遵循仓库自身的检查契约详见 SKILL.md 中的 Limitations 一节。三、修复二注解盘点——AST 计数、确定性抽样与诚实的作用域声明3.1 修复前的问题type_coverage.py文件名沿用了兼容性旧称实际职责是有界注解盘点修复前有两个问题重复计数旧实现基于正则统计函数一个同时带参数注解和返回注解的函数会被计两次夸大样本源码抽样可能声称所有被发现的文件都被分析过而实际受 30 文件上限约束。3.2 修复后的实现新版 type_coverage.py 确立了如下行为AST 计数每个函数只计一次Python 侧用ast.parse后遍历ast.FunctionDef/ast.AsyncFunctionDef节点统计函数总数以及返回值有注解且全部参数含posonlyargs、args、kwonlyargs、vararg、kwarg均有注解的完全注解函数数见 type_coverage.py#L44-L52。确定性抽样且如实报告source_files按字典序遍历每语言最多抽样 30 个文件MAX_FILES 30跳过.git、node_modules、venv、__pycache__、dist、build等目录不跟随符号链接读取上限MAX_BYTES 1_000_000。当达到 30 文件上限时输出中truncated: true并且实际成功分析的文件数、截断状态、解析/读取错误都会被如实写入errors数组见 type_coverage.py#L16-L59。TypeScript 观察明确为词法层面TS 侧仅统计正则:\s*any\b的文本命中次数这会包含注释与字符串字面量中的: any也会漏掉推断出的或别名的any。因此输出中明确声明这不是类型覆盖TypeScript 计数是词法的请运行真正的类型检查器见 type_coverage.py#L53-L56 与 type_coverage.py#L76。退出码语义无适用文件时退出码 2存在解析/读取错误时退出码 1正常则退出码 0。不再输出任何类型安全度百分比或通过/失败阈值——这类推断此前被明确移除。3.3 对应的回归测试test_inventory_does_not_double_count_or_claim_unread_files生成 31 个各含一个完全注解函数的 Python 文件断言结果恰好files 30、truncated True、stats {functions: 30, fully_annotated_functions: 30}验证 30 文件上限与一函数一计数随后把一个文件改成非法语法断言errors长度为 1验证解析错误被如实上报而非宣称全部文件已分析。四、修复三SQL 批量加载——IN 列表绑定、空输入与注入式字符串4.1 修复前的问题技能文档中原先使用驱动语义模糊的IN (?)列表绑定写法。问题在于大多数驱动中的单个?占位符并不会把一个 Python 列表自动展开成多个值这会导致查询参数不匹配甚至执行错误。4.2 修复后的可执行示例修复后implementation-playbook.md 中的 Pattern 1: Eliminate N1 Queries 提供了完整的、可运行的 SQLite 批量加载函数# batch-loading-example def load_orders(connection, user_ids): if not user_ids: return [] if len(user_ids) 500: raise ValueError(Batch limit is 500 IDs; split larger inputs) placeholders ,.join(? for _ in user_ids) return connection.execute( fSELECT id, user_id, total FROM orders WHERE user_id IN ({placeholders}) ORDER BY id, tuple(user_ids), ).fetchall()该示例的关键设计每个值单独绑定为每个 ID 生成一个?占位符并以元组传入杜绝字符串插值空输入安全返回user_ids为空时直接返回[]避免生成非法的IN ()上限保护超过 500 个 ID 抛ValueError防止单条查询过大可移植性提示不同驱动的占位符语法不同?是 SQLite 风格迁移到其他数据库驱动时需要相应调整。测试test_published_batch_loading_preserves_values_and_empty_case直接从 playbook 中提取发布出的 Python 代码块并执行在:memory:SQLite 库中建表并插入三行数据断言load_orders(connection, [1])返回正确的两行、空列表返回空、以及注入式字符串1) OR 11 --被当作普通数据安全处理返回空结果而非注入生效500 个以上 ID 抛ValueError。五、修复四结果保留优先——先验证结果集再谈性能本次复核在 SQL 领域确立了一个贯穿始终的第一原则implementation-playbook.md#L7在评估性能之前先保留并验证查询结果Preserve the query result before assessing performance。这意味着任何改写、加索引、调参都必须先确认新旧查询返回相同的结果集而EXPLAIN ANALYZE会真正执行语句可能触发函数副作用、触发器与 DDL 行为因此只应在经过授权的代表性数据上使用且不能假设事务回滚能撤销一切副作用。围绕这一原则复核针对 playbook 中的三类经典模式做了行为验证与语义澄清5.1 游标分页处理时间戳并列tie单列游标WHERE created_at ...仅在created_at唯一且非空时才正确。对于时间戳并列的场景playbook 给出复合游标SELECT * FROM users WHERE (created_at, id) (2024-01-15 10:30:00, 12345) ORDER BY created_at DESC, id DESC LIMIT 20;并配套索引建议CREATE INDEX idx_users_cursor ON users(created_at DESC, id DESC)。测试test_published_cursor_handles_equal_timestamps构造了三条相同时间戳、不同 id 的记录与一条更早记录从 playbook 提取发布的查询并断言结果只包含id 12344与id 1两条——证明复合游标在并列时间戳下不会漏掉或重复行。5.2 相关子查询与 LEFT JOIN 聚合父行零/一/多子行相关子查询(SELECT COUNT(*) FROM orders o WHERE o.user_id u.id)与LEFT JOIN ... GROUP BY聚合在语义上应等价但必须验证尤其是**没有订单的用户父行零子行**这类边界。playbook 的 Pattern 4: Subquery Optimization 给出了两种写法测试test_published_join_aggregation_preserves_zero_and_multiple_orders从 playbook 提取两种 SQL在内存库中对比其排序后的结果集完全一致并断言(C, c, 0)这样的零订单行在 JOIN 聚合结果中确实存在。5.3 聚合与统计近似数不是精确数复核同时澄清了几个容易误用的点implementation-playbook.md#L222-L261pg_class.reltuples给出的只是近似估算不等价于精确的COUNT(*)筛选已完成订单再计数WHERE status completed是不同的需求不是等价改写不能当作同一查询的优化仅改变 JOIN 的书写方式逗号连接 vs 显式JOIN通常不会保证产生新的执行计划显式 JOIN 提升的是可读性而非必然的执行速度。六、修复五PostgreSQL 18 相关指引的勘误复核对 playbook 中的 PostgreSQL 18 特定内容做了逐项勘误见 implementation-playbook.md 全文语句统计列名pg_stat_statements查询使用total_exec_time/mean_exec_time等当前时间列并明确该扩展需预先配置、且查询文本可能包含敏感值不得未经许可导出索引统计命名pg_stat_user_indexes与pg_stat_user_tables中的列名按 PostgreSQL 18 文档校正物化视图并发刷新前置条件REFRESH MATERIALIZED VIEW CONCURRENTLY要求视图已填充且存在一个建在普通列上的非部分 UNIQUE 索引playbook 中示例为CREATE UNIQUE INDEX idx_user_summary_id ON user_order_summary(id);implementation-playbook.md#L371-L373半开时间区间分区示例FOR VALUES FROM (2024-01-01) TO (2024-04-01)的区间语义含下界、不含上界得到澄清移除不存在的捆绑引用原先指向未随包分发的本地指南与脚本的链接被删除改为引用 PostgreSQL 18 官方文档显式声明变更风险EXPLAIN ANALYZE会执行语句、USE INDEX不强制索引扫描、SET enable_nestloop OFF只是诊断手段而非绝对禁用等均在文中标注implementation-playbook.md#L407-L421。需要强调PostgreSQL 特定的修正依据 PostgreSQL 18 官方文档核查并未在本仓库内运行真实的 PostgreSQL 服务器未验证扩展安装、DDL 锁行为或生产环境供应商行为——这些都需要在使用者自己的环境中单独验证。七、证据链与内容来源provenance评审文档对证据本身也做了严格管理社区来源声明两个技能都声明source: community见 lint-and-validate/SKILL.md 与 sql-optimization-patterns/SKILL.md 的 frontmatter复核不推断任何新的上游身份、许可证或背书全文件读取全部 5 个被跟踪文件都被读取两个 Python 助手、两份 SKILL.md、一份 SQL playbook确认无符号链接、非二进制、无可执行模式文件SHA-256 指纹评审为 5 个文件记录了字节级指纹见关联文档的表格并明确说明后续编辑会使这些指纹失效即指纹是特定时点的快照不是长期有效的徽章历史快照区分文档特别说明更早的 content-review-2026-09-05.md 是警告清理之前的历史快照不代表当前警告数量。八、回归验证与已知边界如何复现这 6 个用例从仓库根目录运行python3 tools/scripts/tests/test_skill_worked_examples.py该套件共 6 个用例覆盖空项目与非法package.json的not-checked/ 退出码 2 行为Node 回退检查器指向本地node_modules且缺省时失败而非下载30 文件抽样上限与一函数一计数、解析错误上报发布版批量加载函数的绑定语义、空输入与注入式字符串复合游标在时间戳并列下的正确性相关子查询与 LEFT JOIN 聚合在零/一/多子行场景下的结果等价。测试完全基于 Python 标准库与 SQLite不触网、不连库、不测速。文档同时声明Python 与 Node 的项目检测是启发式的通过 lint不能证明没有运行时或安全缺陷SKILL.md 的 Limitations 一节SQLite 的正确性校验也不代表 PostgreSQL 的性能或生产安全。九、可复用的方法论如何评审一份技能文档从这次定向复核中可以提炼出一套可复用的评审方法论圈定有界范围明确评审了哪些树、没有评审哪些绝不把局部结论上升为全目录认证把文档示例变成可执行测试从文档中提取发布的代码/ SQL 原文而非凭印象重写去执行——test_skill_worked_examples.py用re.findall从 playbook 提取代码块再exec/ 执行确保测试的就是读者将看到的那份代码为边界条件写用例空输入、超限、注入式字符串、时间戳并列、父行零子行——这些正是真实世界最容易翻车的地方诚实报告无法验证的部分哪些检查没跑、哪些是启发式、哪些依赖外部环境全部显式声明保留证据指纹文件清单、SHA-256、测试命令让评审可复现、可追溯。结语这份 follow-up 文档的价值不在于修复了多少行代码而在于它示范了一种对 Agent 生态至关重要的评审纪律让未检查与失败泾渭分明让近似与精确界限清晰让文档中发布的每一段代码都能被测试直接验证。当技能文档成为 Agent 的行为依据时这种纪律本身就是一种安全边界——它保证了 Agent 永远不会把什么都没跑误读为全部通过也保证了 SQL 示例在真实驱动上不会因为占位符语义而静默出错。仓库中的 lint-and-validate 与 sql-optimization-patterns 两个技能树连同 test_skill_worked_examples.py 这套回归套件就是这一纪律的完整可运行样本。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考