CLI 概览

这是什么

one cli 是 AI Native 的 monorepo workspace 工具：

• 主要消费者是 AI agent（Claude Code / Codex / 等等），不是直接打字的人
• 所有命令支持结构化 JSON 输出，非 TTY 自动启用
• 错误带 code + context + remediation[]，agent 能直接读取恢复方案
• one create 建 workspace，one add 加子项目并刷新 AI guides，依赖安装交给 package manager
• 随包附带 4 个 Claude Code workflow skills

产品边界

one-cli 负责的是工作区初始化与治理：

• 创建根骨架
• 添加模板子项目
• 维护 Docker、K8s、GitHub Actions 和 manifest
• 管理 secrets
• 管理内部 AI 指南与 skills 入口
• 做 secrets 和状态观测

它不负责代理每个子项目自己的 dev、build、test。

命令面

默认 one --help 展示的 5 个常用命令

# 核心
one create        # 创建新工作区
one add           # 添加子项目
one templates     # 查看可用模板

# 工作区维护
one status        # 查看工作区全量状态（agent 友好）
one doctor        # 检查并修复配置（含 --fix）

one --help-all 显示的高级命令

one secrets       # Infisical 密钥管理（init / set / get / list / pull）

注意：one init / one inspect / one list / one sync / one report / one remove / one adopt / one manifest / one template / one ai / one install / one upgrade / one auth / one skills 均已从公开命令面删除， 并会被根命令拦截为 UNKNOWN_COMMAND，避免误触发 one create <command-name>。

输出模式

每个命令都有两种输出模式，自动切换：

触发条件	模式
--json flag	JSON
ONE_OUTPUT=json env var	JSON
ONE_OUTPUT=tty env var	TTY
默认（process.stdout.isTTY）	TTY 时彩色 / 否则 JSON

人类在终端跑命令拿到的是彩色 clack UI，agent 通过 npx / pipe 调用拿 到的是结构化 JSON，无需额外配置。

推荐顺序

推荐顺序

# 创建工作区
one create my-app

# 添加首个子项目并刷新 AI guides
cd my-app
one add api-nest --name user-api

# 安装依赖
pnpm install

分步

1. one create — 创建工作区
2. one status --json — 看现状
3. one add <template> — 加子项目
4. one status --json — 验证健康
5. one doctor --fix — 修复任何 drift
6. 如有需要：one secrets init、one status --json

给 agent 的入门指引

如果你正在写一个用 one cli 的 agent，从这里开始：

1. 先调 one status --json 看当前状态
2. 读 available_actions[]，按 priority 排序，挑第一个
3. 错误用 error.code 路由，不要解析 error.message
4. 已经有 4 个 workflow skill 描述完整工作流——不要从零写
5. 完整的错误码 + remediation 表见 error-codes.md