SuperAPI AI 工具集

jarvus-axi

编程与开发

查看项目

更新于 11-16 04:02

技能介绍

Jarvus AXI 是 Jarvus Innovations 为其 *-axi 系列命令行工具制定的内部风格指南。这些工具基于 axi-sdk-js 构建,面向智能体使用。该技能与上游 axi 技能(阐述优秀智能体 CLI 的十项原则)和 axi-skills 技能(说明如何将 CLI 作为技能包发布)互补但不重叠:jarvus-axi 专注于上游未明确或留待选择之处,记录团队的具体决策和 npm 发布工具的配方。

用途:为开发新的 AXI 工具或审查现有工具提供一套经过实践检验的约定,确保工具输出对智能体而言清晰、可靠,避免智能体因误导性输出而犯错。

主要能力(规则概要):

  • 标志严格校验:每个命令声明其标志和位置参数数量,任何多余、重复、矛盾或未知值都在执行前被拒绝,并列出有效标志。重命名或智能体习惯猜测的标志会给出针对性提示。退役命令保留为重定向。
  • 机器输出写入文件:stdout 始终为 TOON 视图,不提供 --json。需要数据的脚本使用 --json-out[=path](或 --csv-out 等),完整数据写入文件,stdout 显示写入行、列和可运行的 jq 提示。仅在存在脚本用途的命令上提供。
  • 统一输出词汇:默认列数上限为四列;列表明确显示“N of M”且不静默部分显示;时间输入人性化并回显解析后的窗口(含年份和时区);提示统一为“Run <tool> … to <purpose>”并原样执行;重复已为真的操作显示“(no-op)”并以 0 退出;主页以标准 --help 发现行结尾。
  • 读取失败封闭:失败、部分或无法解析的读取视为错误或未知(<CODE>: …),绝不渲染为空、0、none、无操作或成功。错误码为大写蛇形命名。formatError 将用法类错误导向退出码 2,其余导向退出码 1,并将意外抛出转为 INTERNAL_ERROR 并附 doctor 提示,不显示堆栈。
  • 变更操作证明结果:变更仅在回读结果后报告成功;无法确定结果时使用独立错误码并提示智能体重试前先检查。门控遵循阶梯:常规操作无门控;特定成本或损失使用以其命名的标志(如 --accept-fee);销毁命名对象或放宽保护需 --confirm;绝不使用提示或通用 --force。
  • 账户显式:读取可使用默认账户;存储两个及以上账户后,变更操作需在命令行指定账户或由环境固定。每个输出注明所操作的账户。机密信息不进入 argv 或输出。
  • 主页永不失败:无参数视图永不报错、永不非零退出,也不执行随账户增长的工作。实时读取失败显示为不可用(<CODE>: …)并附 doctor 提示。钩子仅由 setup hooks 安装,遵循上游参考工具,并带有 --scope 扩展。
  • 仓库遵循 npm 配方:多数工具为 npm 包而非技能包:bin/ 加 src/ 用 tsc 构建,reference.ts 提供帮助并生成 SKILL.md,规格和计划用 specops 管理,封闭测试,CI 中无凭据冒烟测试,可信发布且版本取自发布标签。
  • 目录提交前自审:上游目录仅在固定源审查后接纳工具,审查者会阻止开放失败行为。先运行自己的审查并修复问题。
  • 从规范源复制:共享模块(标志解析器、错误格式化器、导出写入器、渲染器)在仓库间复制而非打包,应从 references/canonical-sources.md 指定的仓库复制,而非最近的工具。

使用方式:

  • 启动新工具时:先读上游 axi 技能,再读本文件;决定分发方式(npm 包默认、技能包或两者);从当前参考工具脚手架,带上解析器、formatError、渲染器和测试助手;先写 specs/principles.md 记录权衡及原因;设计命令面并为每个变更操作记录门控及理由;尽早构建主页视图和 doctor;首次发布前运行目录清单。
  • 审查现有工具时,优先检查已知缺陷:未知标志或多余位置参数被静默丢弃;失败读取渲染为空列表、零或“无事可做”;变更操作根据发送的请求而非服务器存储结果打印成功;变更超时报告为普通失败;钩子安装器写入失败却打印警告并以 0 退出;默认表格五列及以上且无书面理由;主页视图在网络断开时挂起或抛出;stdout 上的 --json。

适用场景:AXI 工具的开发、审查和维护;需要为智能体提供可靠 CLI 输出的场景。

限制:本技能为内部风格指南,并非可执行工具或库;部分引用的参考文档(如 references/flags.md)未在提供资料中展开;规则可能与旧工具存在差异,以本技能为准,但需单独修复旧工具。