OpenCLI convention-audit 指南：用 7 条规则守住 Agent 原生适配器约定的 CI 防线

开发工具CLI人工智能AI 应用浏览器控制GUI 自动化【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址https://gitcode.com/gh_mirrors/ope/OpenCLI点击查看免费下载opencli convention-audit是 OpenCLI 内置的适配器约定审计命令它同时扫描适配器元数据cli-manifest.json与clis/下的源码文件自动检出表格输出丢列、静默失败回退、缺少读写配对等 7 类常见约定违规。读完本文你将掌握该命令的全部用法与三种输出格式理解每条规则的判定逻辑与启发式边界并能把--strict、基线模式与npm run check:*门禁接入自己的 CI 流水线。设计哲学Report-first先给 Agent 一份共同事实底座在 OpenCLI 中每个站点适配器如clis/twitter/、clis/pixiv/都以 manifest 条目 JS 源码的形式存在输出到表格或 JSON 给 Agent 消费。适配器一旦出现行数据里多出几个键、columns却没声明这类问题Agent 拿到的表格就会悄悄丢列一旦出现return []、?? unknown这类静默回退抓取失败就会被伪装成正常空结果。convention-audit的定位是report-first先报告它默认不做拦截只输出一份分组的人类可读报告作为 Agent 在发起 sweep PR批量修复 PR之前的共享事实底座--strict留给 CI 阶段使用。这一设计在 命令注册处 体现得很清楚--strict默认false只有显式开启后report.ok false时才会设置非零退出码process.exitCode EXIT_CODES.GENERIC_ERROR。另外值得注意的是 src/main.ts当argv[0] convention-audit时启动流程会跳过用户 CLI 发现skipUserDiscovery只加载内置 CLI。这意味着审计始终以仓库内置的 manifest 与源码为基准不会被本地用户适配器干扰保证报告可复现。命令用法与输出格式基本用法opencli convention-audit # 全量审计 opencli convention-audit --site twitter # 只审计 twitter 站点 opencli convention-audit twitter/search # 只审计 twitter/search 这一个命令 opencli convention-audit --site pixiv -f yaml # 站点过滤 YAML 输出 opencli convention-audit --strict # 发现违规即以非零码退出位置参数[target]支持两种粒度见 matchesTarget含/时按完整命令匹配如twitter/search等价于${site}/${name}精确相等不含/时按站点匹配如twitter命中所有entry.site twitter的条目。三种输出格式格式命令适用场景table默认-f table分组的人类可读报告适合本地人工排查yaml-f yaml推荐的 Agent 消费格式结构稳定、易解析json-f json更严格的机器消费者适合脚本化处理格式切换逻辑在 cli.ts 的 action 内json/yaml/yml走renderOutput(report, { fmt })其余一律走 renderConventionAuditText 输出文本报告。文本报告的骨架大致如下由renderConventionAuditText生成Convention Audit Report Scanned N command(s) across M site(s), K source file(s). Violations: X silent-column-drop: 2 - twitter/search (clis/twitter/search.js:42) twitter/search row emits key(s) not present in columns: url emitted_keys: id, title, url | columns: id, title | missing: url ... OK - no convention violations found. # 仅当 report.ok 为 true 时输出每条违规会附带命令名、相对文件路径与行号、规则消息以及details字段如missing、column、expected_any_of、text方便直接定位修复。报告结构YAML/JSON机器格式对应 ConventionAuditReport 类型顶层有ok布尔值、summarycommands/sites/files_scanned/violations计数以及按规则分组的categories数组每项含rule、count、violations。Agent 可以先读summary.violations判断整体健康度再按categories[].rule分拣修复任务。七条审计规则详解当前版本报告的规则固定为 7 类RULES 常量1. silent-column-drop行数据键不在 columns 中manifest 中每个命令声明了columns而源码里rows.push({...})等位置实际发出的对象若包含未声明键表格输出时该键会被静默丢弃。扫描实现见 auditColumnDrop它是启发式最强的一条通过 4 类触发点定位疑似行对象.push({、return {、 ({、map: {后者用于 pipeline 声明式 map 块忽略ok/error两个诊断键COLUMN_DROP_IGNORED_KEYS跳过ok: false的失败诊断对象isFailureDiagnosticObject避免把错误详情误报为丢列跳过形如{site, description|access|strategy}的命令元数据对象looksLikeCommandMetadata对Raw/Class后缀的中间键做了白名单如果某个列的值来自xxxRaw且最终有 mapper 把xxxRaw转成列则不报findTransformedIntermediateKeys对应测试见 此处但若 raw 键被直接发射而没有最终 mapper仍会报告对应用例。2. camelCase-in-columns列名应为稳定 snake_case对每个columns条目用正则/[a-z][A-Z]/检测驼峰拼写判定点。Agent 依赖稳定的列名做下游解析snake_case如user_name、created_at比userName更不易在大小写重命名时破坏契约。3. missing-access-metadata每个命令必须声明读写属性如果 manifest 条目没有access: read | write或取值非法直接报告违规判定点。这是所有 Agent 决策的基础——Agent 需要知道调用某个命令是否会改变站点状态从而决定是否请求用户确认。4. silent-clampMath.min 静默截断用户输入源码中出现Math.min(...limit...)会被标记判定点例如const limit Math.min(kwargs.limit, 100)。这种写法会把用户传的limit: 500悄悄变成100而不是抛出ArgumentError。约定的做法是校验并抛出类型化错误让 Agent 明确知道参数被拒绝而不是拿到一个被悄悄改过的结果。5. silent-empty-fallbackcatch 块里的return []只对catch 块内部的return [];报违规判定点。实现先用 findCatchBlockRanges 找出所有catch {...}的括号范围再判断空数组返回语句是否落在这个范围内。测试明确验证了守卫式return []不在 catch 中不报、catch 内的return []必报src/convention-audit.test.ts#L238-L251。理由很直接抓取或解析失败时返回空数组Agent 无法区分真的没有数据和请求挂了于是可能基于残缺数据做出错误决策。6. silent-sentinel?? unknown/|| N/A式哨兵回退匹配(?? 或 ||) 后跟字符串字面量且字面量命中unknown|Unknown|UNKNOWN|N/A|n/a|NA|未知|-判定点。这类回退会把缺失数据变成假数据——Agent 可能把title: unknown当真值使用。规则建议要么直接丢弃该字段要么抛类型化错误。一个重要的豁免单行throw new X(...)内的哨兵回退不报isThrowMessageLine因为那只是错误消息的兜底文案不是伪造数据测试见 src/convention-audit.test.ts#L253-L275。但多行 throw 表达式中的类行哨兵仍保持可见。7. write-without-delete-pair写命令缺少撤销/删除配对写命令access: write如果名字匹配 like / follow / subscribe / bookmark / save / create / post 等动词却没有同站点的撤销命令就会报告auditWriteDeletePair。配对规则定义在 WRITE_PAIR_RULES匹配动词期望存在的配对命令任一即可likeunlikefollowunfollowsubscribeunsubscribebookmarkunbookmarksaveunsave、delete、remove、rmcreatedelete、remove、rmpostdelete、remove、rm例如demo/like存在而demo/unlike不存在时报告expected_any_of: [unlike]。Agent 在站点支持撤销操作时应当有配套的 undo 命令避免点赞后无法取消这类不可逆操作。从启发式到 CI 门禁基线模式的两条 npm 命令文档强调扫描器是启发式的默认把报告当作优先级化的人工审阅输入只有在你完全理解当前违规与豁免后才把某条规则升级为 strict CI 门禁。仓库为此提供了两条基线模式门禁silent-column-drop 门禁npm run check:silent-column-drop对应 scripts/check-silent-column-drop.mjs。它直接复用runConventionAudit扫描全仓库然后与基线文件 scripts/silent-column-drop-baseline.json 对比。基线文件当前记录了仓库中已知的约 900 余条违规签名如1688/assets的detail_images、item_url等缺失键因此门禁的断言是不允许出现超出基线的新违规签名。每个违规记录按command file missing 键列表生成唯一签名signature 函数。运行结果有三类new0通过输出OK - no new silent-column-drop violations.added0打印新违规清单退出码 1resolved0提示有基线条目已被修复建议收缩基线说明有人做了正确的 sweep 清理。typed-error 静默失败门禁npm run check:typed-error-lint对应 scripts/check-typed-error-lint.mjs把silent-clamp、silent-empty-fallback、silent-sentinel三条静默失败规则合并为一个门禁基线在 scripts/typed-error-lint-baseline.json。为了区分同一文件里多处相同文本的违规它会为每条记录附加出现序号addOccurrenceIndexes签名由rule command file text occurrence构成。更新基线sweep 后的标准操作当一次 sweep PR 修复了既有违规后按文档给出的流程更新基线两条门禁同理npm run build node scripts/check-silent-column-drop.mjs --update-baselinenpm run build node scripts/check-typed-error-lint.mjs --update-baseline先npm run build是因为门禁脚本会从dist/src/convention-audit.js动态导入审计实现两脚本都检查dist/src/convention-audit.js是否存在不存在会直接报错退出。--update-baseline会把当前扫描结果按签名排序后整体写回基线 JSON。这套基线 只堵新增的机制让仓库可以在第一天就立起不变量同时把存量违规留给后续独立的 sweep PR 分批清理——这正是 report-first 设计在工程落地上的自然延伸。实现骨架速览从 manifest 到报告的调用链如果你想深入源码可以沿着这条调用链阅读命令入口src/cli.ts#L947-L968 —— 定义convention-audit子命令的参数与格式分发--strict在此决定退出码审计核心src/convention-audit.ts#L128-L188 的runConventionAudit—— 读取cli-manifest.json默认projectRoot/cli-manifest.json按 target/site 过滤逐条检查 access、columns 驼峰然后解析sourceFile ?? modulePath源码路径解析见 resolveSourcePath统一位于clis/目录下并扫描列丢失与类型化错误模式最后做写/删配对检查数据源cli-manifest.json —— 顶层数组每条含site、name、access、columns、modulePath、sourceFile、args、strategy等字段是审计与 Agent 发现命令的共同事实源文本渲染renderConventionAuditText —— 生成默认 table 报告测试佐证src/convention-audit.test.ts —— 覆盖了七条规则、target/site 过滤、pipeline map 块扫描、ok:false豁免、raw 中间键豁免、catch 范围判定、throw 消息豁免等全部边界行为是理解哪些算违规、哪些不算的最可靠参考。一个值得留意的细节auditColumnDrop的行号定位用lineForIndex对源码做换行计数而平衡括号解析readBalancedBlock/findBalancedBlockEnd能正确处理字符串与模板字符串中的{}避免把字面量误判成对象块——这也是它能在 pipeline 声明式 map 块上工作的原因。典型工作流Agent 驱动的约定维护结合 report-first 的定位推荐的实际工作流是人工/CI 触发全量审计opencli convention-audit本地或npm run check:*CI拿到按规则分组的违规清单Agent 依据 YAML 报告拆分修复任务opencli convention-audit --site twitter -f yaml得到该站点的机器可读结果按categories[].rule分派——先修missing-access-metadata契约级再修silent-column-drop丢列随后处理三类静默失败最后补write-without-delete-pairsweep PR 修复 收缩基线修复既有违规后执行npm run build node scripts/check-*.mjs --update-baseline更新基线门禁随之收紧每修掉一批resolved提示会引导你持续收缩基线直至清零对已彻底理解的规则开启 strict在 CI 中对--strict或基线门禁设置只堵新增作为仓库的长期不变量。整个过程强调的是先理解、再约束启发式扫描难免有误报例如Math.min用于防御性上限而非截断用户输入时所以文档明确建议——默认把报告当审阅输入只有等你完全摸清当前违规与豁免之后再把具体规则升级为严格 CI 门禁。赞分享开发工具CLI人工智能AI 应用浏览器控制GUI 自动化【免费下载链接】OpenCLIMake Any Website into CLI Use your logged-in browser by AI agent.项目地址https://gitcode.com/gh_mirrors/ope/OpenCLI点击查看免费下载相关推荐code2prompt Python 绑定验证指南用 verify-python Skill 守住薄适配器边界code2prompt Python 绑定验证指南用 verify python Skill 守住薄适配器边界 本文围绕 code2prompt 仓库中面向开发工具AI 应用Kronos金融时序模型如何通过层次化Token化解决高频预测的维度诅咒Kronos金融时序模型如何通过层次化Token化解决高频预测的维度诅咒 在传统量化交易领域LSTM和GRU等循环神经网络长期主导着时序预测任务但当面对5人工智能大模型基础模型预训练金融科技iOS 平台设计规范参考用 Impeccable 为原生 Apple 应用守住 HIG 底线iOS 平台设计规范参考用 Impeccable 为原生 Apple 应用守住 HIG 底线 关联文档 .trae/skills/impeccable/reAI 技能前端CLIdsh-plugin上一篇终极PyTorch版本选择指南确保VGGT深度学习框架完美兼容性下一篇AutoHotkey进程管理终极指南掌握程序启动与监控的10个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考