SuperAPI AI 工具集

adding-skill-program

编程与开发

查看项目

更新于 10-16 03:46

技能介绍

用途:为 PostHog wizard 新增“技能型程序”(skill-based program)。这类程序会安装一个 context-mill 技能,并让智能体针对该技能运行。代码库中的示例包括 audit 程序(干净的工厂调用)与 revenue-analytics 程序(工厂 + 自定义引导界面 + 检测步骤)。阅读前应先看 wizard-development/SKILL.md 了解架构背景,尤其是“新能力是新程序,而非新分支”这一原则。

架构:wizard 的运行管线是固定的,程序之间的差异由 ProgramRun 配置对象控制,它决定技能 ID、提示词、成功消息、中止情形与运行后钩子。ProgramConfig 把 CLI 命令、步骤列表和 ProgramRun 绑在一起;程序注册表从单个数组推导出所有下游接线(CLI 子命令、TUI 程序、路由)。新增程序属于配置而非编码。

常见做法:对只需安装技能并让智能体运行的程序,使用 agent-skill/index.ts 中的 createSkillProgram 工厂,传入 skillId、command、flowKey、description、integrationLabel、successMessage、reportFile、docsUrl、spinnerMessage、estimatedDurationMinutes,以及可选的 requires(需先运行的前置程序)。随后只需在 src/lib/programs/program-registry.ts 的 PROGRAM_REGISTRY 数组中登记。bin.ts、store、agent runner、router 与界面序列(src/ui/tui/screen-sequences.ts)都会自动推导接线,无需添加 yargs 命令或 runner 函数,ProgramId 联合类型也会自动更新。

定制智能体运行:createSkillProgram 支持可选字段 customPrompt(追加提示)、buildOutroData(覆盖默认结尾)、abortCases(匹配技能发出的 [ABORT] 信号)、requires。若需更复杂的运行后工作(上传环境变量、创建仪表盘等),可放弃工厂直接构建 ProgramConfig 以设置 ProgramRun.postRun,参考 posthog-integration。

动态运行配置:若需在构建运行配置前检查会话(读取框架上下文、在磁盘上播种状态、设置按会话的提示片段),可把异步函数作为程序的 run 传入。audit 程序用此模式在智能体运行前于磁盘播种检查台账。

自定义界面:技能型程序默认使用 agent-skill/steps.ts 的通用步骤列表(intro → auth → run → outro → keep-skills)。要使用程序专属界面,可覆盖相应步骤的 screen 字段,把界面 ID 加入 src/ui/tui/screen-sequences.ts 的 ScreenId 枚举,在 src/ui/tui/screens/ 下创建 React 组件,并在 src/ui/tui/screen-registry.tsx 注册。界面通过 useWizardStore 读取 store,在存在 frameworkContext.detectError 时渲染错误状态,用户前进时调用 store.completeSetup() 或等价方法。路由根据会话状态解析当前界面。切勿在 TUI 内调用 console.error 或命令式导航。

检测与前置检查:若程序需在显示引导界面前验证前置条件,可在程序顶部添加无界面的 detect 步骤并使用 onReady 钩子(不要用 onInit,它在 store 构造期间触发、session 尚未赋值,无法读取 installDir)。成功时调用 ctx.setFrameworkContext('skillPath', ...),失败时设置 detectError。自定义引导界面据此渲染错误视图(含退出选项)或欢迎视图。revenue-analytics 是此模式的典型示例。

验证:运行 pnpm build、pnpm test、pnpm fix,然后用真实测试应用端到端运行 pnpm try --install-dir=<path> <your-command>,并测试失败情形(缺少前置条件、错误的安装目录、技能下载时的网络错误)。wizard 应渲染结构化的错误结尾,而非堆栈跟踪。

代码库中的典型示例:src/lib/programs/audit/(干净的 createSkillProgram 调用,含中止情形、自定义界面与用于按会话播种的动态 run 函数)、src/lib/programs/revenue-analytics/(工厂 + 自定义引导界面 + 带前置检查的 detect 步骤)、src/lib/programs/agent-skill/(工厂本身 createSkillProgram 与通用步骤列表 AGENT_SKILL_STEPS)。不确定时,阅读与你所构建内容最相似的程序目录。