RFC: 让 utoo-pm 对 AI 更友好 / Make utoo-pm AI-friendly

[elrrrrrrr]

RFC：让 utoo-pm 对 AI 更友好 / Make utoo-pm AI-friendly

• 状态 / Status：Draft
• 范围 / Scope：utoo / ut package manager CLI

摘要

通过两项能力，让 utoo-pm 能被人和 AI Agent 稳定调用：

1. 统一机器可读的输出与错误契约；
2. 随 CLI 分发官方 Agent Skill。

终端默认仍使用人类可读输出。除非显式请求机器模式，否则保持现有命令兼容。

动机

utoo-pm 已在非 TTY 环境关闭进度条，并支持 --yes、--dry-run 等自动化参数，但命令仍各自打印结果，且多数失败共用退出码 1。Agent 因而需要解析自然语言，也无法可靠判断应该重试、修正输入、登录还是停止。

提案

统一调用与输出

增加全局参数：

• --json：在 stdout 输出单个 JSON 结果；
• --quiet：隐藏非必要诊断信息；
• --no-color：关闭 ANSI 样式，并继续支持 NO_COLOR。

stdin 不是 TTY 时，不得打开 utoo 自身的 prompt 或 selector。缺少必要输入时返回用法错误；Agent 应显式传入 init --yes、run <script> 等参数。

输出遵循以下契约：

• stdout 只包含最终结果或被执行脚本自身的输出；
• stderr 包含进度、日志、警告、prompt 和错误；
• --json 输出一个紧凑 JSON 文档，并以换行结尾；
• 命令先生成类型化结果，再渲染为人类文本或 JSON；
• JSON 包含 schemaVersion: 1，使契约能独立于 CLI 版本演进。

{"schemaVersion":1,"command":"install","changed":true,"added":12,"removed":1,"updated":3,"lockfileChanged":true}

首批支持 view、whoami、config get/list 和 pack --dry-run。共享输出层稳定后，再覆盖 install、list 和 publish。

错误契约

在 CLI 边界引入错误类型，包含分类、消息、可选建议和源错误：

退出码	分类
1	临时网络或 registry 错误
2	用法错误或非交互模式缺少输入
3	鉴权失败
4	package、workspace、script 或 key 不存在
5	请求被限流
6	用户取消
7	前置条件不满足
11	本地或内部错误

JSON 模式下，stderr 同时输出结构化错误：

{"error":{"category":"not_found","code":4,"message":"script 'buid' was not found","suggestion":"build"}}

依赖解析错误应保留结构化 requiredBy 链；package script 失败继续透传脚本退出码。

Agent 集成

随 CLI 提供官方 utoo Agent Skill，简要说明能力与版本探测、机器输出、退出码和重试策略，以及 install、workspace、pack、publish 的安全工作流。

ut skill setup --target codex --yes
ut skill setup --target all --yes

Skill 以 ut <command> --help 作为运行时契约，不复制完整用户手册。

实施顺序

1. 分离 stdout/stderr，并统一非交互和颜色策略。
2. 添加共享输出层、JSON 结果、错误分类及首批契约测试。
3. 将结构化输出扩展至 install/publish。
4. 添加并分发 Agent Skill。

非目标

• 替换面向人的终端输出；
• stdout 重定向时自动启用 JSON；
• 增加字段投影、内置 jq、MCP 或通用插件系统；
• 改变依赖解析或安装语义。

验收标准

• Agent 无需解析颜色、表格、spinner 或日志来获取结果。
• 非交互调用不会阻塞在 utoo 自身的 prompt 或 selector。
• 机器输出和退出码有 CLI 集成测试覆盖。
• 官方 Skill 无需手工复制仓库文件即可安装。

---

English summary

This RFC proposes making utoo-pm reliable for both humans and AI agents through two additions:

1. a unified machine-readable output and error contract;
2. an official Agent Skill distributed with the CLI.

Human-readable terminal output remains the default. Machine mode is explicit and backward-compatible.

Contract

• Add global --json, --quiet, and --no-color flags.
• Keep final results on stdout; send progress, logs, warnings, prompts, and errors to stderr.
• Emit exactly one compact JSON document with schemaVersion: 1 in JSON mode.
• Never open utoo-owned prompts or selectors when stdin is not a TTY; require explicit arguments such as init --yes and run <script>.
• Introduce stable error categories and exit codes for transient, usage, auth, not-found, rate-limit, cancellation, precondition, and local failures.
• Preserve structured dependency requiredBy chains and package-script exit codes.

The first JSON-enabled commands should be view, whoami, config get/list, and pack --dry-run, followed by install, list, and publish.

Agent Skill

Ship an official utoo Skill covering capability detection, structured output, retry policy, and safe package-manager workflows. Install it through ut skill setup, while treating ut <command> --help as the runtime contract.

Non-goals

This RFC does not replace human terminal output, auto-enable JSON for redirected stdout, add field projection/embedded jq/MCP, or change dependency resolution semantics.