Agent 应用构建器

要解决的问题

给 AI agent 写 CLI，最常见的失败是交付物停在「示例代码 + 文档」：能跑，但参数校验靠手写、错误语义和后端不一致、输出格式 agent 无法可靠解析。这个技能把交付标准收紧为可构建、可测试、可独立安装，并且输出契约稳定到 agent 能直接消费。

核心工作方式

先建立事实基线

• 读取 AGENTS.md、package.json、现有 CLI 入口与相邻包惯例，确认框架版本、defineCli.name、命令域和已有脚本。
• 从 OpenAPI、类型、真实响应或测试中确认 base URL、请求方法、响应字段、分页和错误约定；不猜字段、鉴权方式或分页协议。
• 保留用户已有修改，只问上下文无法确定、且会改变实现的事实。缺失的事实用明确的 TODO 标记，不写多套猜测兼容逻辑。

最小设计加约束式实现

• 按场景查表决策：公开 API 不加鉴权插件；OAuth、Bearer、API key 优先 defineAuth；HMAC 或 mTLS 走自定义 plugin；只有多个无关业务域才用 namespaces。
• 业务命令按域放入 src/commands/，args.schema 直接放 Zod 4 object；重载荷用 type: "json"，一个命令只能是 argv 或 JSON，不能共存。
• HTTP 调用统一走 ctx.get/post/...，跨命令一致的语义交给 errorOnStatus，业务特有错误抛 errs.*。

可信边界与验证

• 敏感信息不进源码、日志、测试快照和命令行参数；安装、全局写入、写操作前说明影响并取得授权；写命令通过 policy 声明预览、确认与幂等。
• 验证按风险分层：format / lint / typecheck / build，再用 createTestCtx 和 app.run(argv) 覆盖参数、空结果、错误、写策略和退出码，然后跑真实 --json 样例、Skill 校验与 dry-run 打包。

适用边界

• 依赖仓库已有的包管理器、TypeScript、lint 和测试配置，不适合给空仓库从零搭脚手架。
• 只读操作和单一业务域是最贴合的适用场景；超出最小权限的鉴权需要先拿到服务契约。
• build 通过不等于生产可用：安全扫描、网络连通性和真实 API 行为若未验证，交付中必须明确列为未验证项。