one cli

AI Native monorepo workspace orchestrator. 一个命令把工作区从零搭起来——人类用 prompt，AI agent 用 JSON 接口。

本工具发布在 npm 上的包名是 qzkpwoxtl（故意取了一个无意义名字以避免被外部用户偶然发现，仅供团队内部使用）。命令行入口仍然是 one。

这是什么

one cli 不是又一个 monorepo 工具，它的设计前提是 AI agent 是主要使用者：

• 结构化 JSON 输出：所有命令默认 JSON 格式（非 TTY 自动启用），agent 不用解析人类文本
• 结构化错误：每个错误都带 code + context + remediation[]，agent 能直接读取恢复方案
• 统一初始化：one create 一个命令完成 workspace + 子项目 + AI guides + skills + install
• 5 个 workflow skills：随包附带 Claude Code skills，agent 加载后用自然语言驱动整个流程
• per-template 工程规范：每个模板自带 100+ 行的工程契约，agent 写代码时自动遵守

安装

pnpm add -g qzkpwoxtl
# 或 npm install -g qzkpwoxtl
# 或 yarn global add qzkpwoxtl

one --help

一次性使用：

pnpm dlx qzkpwoxtl --help

30 秒上手

# 创建一个新工作区，附带 NestJS 后端 + AI guides + skills + 自动 install
one create my-app --add api-nest:user-api

# 查看当前工作区的全量状态（agent 友好）
cd my-app && one inspect --json

# 检查并自动修复
one doctor --fix

# 添加另一个子项目
one add web-csr-react --name dashboard

命令一览

one --help 默认只显示 7 个核心命令：

核心命令
  create        创建新工作区
  add           添加子项目
  remove        移除子项目
  list          查看可用模板

工作区维护
  init          初始化或扩展可选模块
  inspect       查看工作区全量状态（agent 友好）
  install       安装所有子项目依赖
  doctor        检查并修复配置（含 --fix）

one --help-all 还会展示这 7 个高级命令：upgrade、report、manifest、template、auth、ai、secrets。

每个命令的详细帮助：one <command> --help。

关键概念

one create = 一站式起步

旧的 4-命令 dance（create + ai init + secrets init + add）已经合并成单个 one create：

# 交互式：multiselect 选模块
one create my-app

# Agent 模式：显式 flag
one create my-app \
  --no-interactive --yes \
  --docker \
  --add api-nest:user-api \
  --modules ai-guides,skills,install,secrets

可用模块（默认 enabled 的标 ✅）：

| 模块 | 默认 | 作用 | |---|---|---| | first-subproject | ✅ | 添加首个子项目（template + name） | | ai-guides | ✅ | 生成 AGENTS.md / CLAUDE.md | | skills | ✅ | 安装 5 个 skill 到 ~/.claude/skills/ | | install | ✅ | 跑 pnpm install | | secrets | ⚠️ | SOPS + age（仅当本机有 sops + age） |

跳过初始化阶段（只生成骨架）：--minimal。

one inspect = agent 的"看世界"入口

$ one inspect --json
{
  "schema": "one-cli/inspect/v1",
  "workspace": { "is_one_project": true, "node_version": "...", ... },
  "subprojects": [
    {
      "name": "user-api",
      "template_id": "api-nest",
      "scripts": ["dev", "build", "test"],
      "manifest_tracked": true,
      "infra": { "dockerfile": true, "compose_service": true, ... }
    }
  ],
  "issues": [],
  "available_actions": [
    {
      "action": "add-subproject",
      "command": "one add <template-id> --name <name>",
      "reason": "workspace is healthy; ready to add more subprojects"
    }
  ]
}

available_actions[] 是 AI Native 的核心 — agent 不用记/不用猜，直接读这一栏决定下一步。

结构化错误

$ one add nonexistent --name x --json

{
  "schema": "one-cli/error/v1",
  "error": {
    "code": "TEMPLATE_NOT_FOUND",
    "message": "模版 \"nonexistent\" 不存在",
    "context": {
      "requested_template": "nonexistent",
      "available_templates": ["api-nest", "web-csr-react", ...]
    },
    "remediation": [
      { "action": "list-templates", "command": "one list --json", ... },
      { "action": "use-different-template", "hint": "..." }
    ]
  }
}

agent 拿到这个错误根本不需要再调一次 list——available_templates 已经在 context 里了。直接挑一个重试。

完整错误码表见 docs/error-codes.md。

JSON 模式触发优先级

1. --json flag           → 强制 JSON
2. ONE_OUTPUT=json env   → 强制 JSON
3. ONE_OUTPUT=tty env    → 强制 TTY
4. process.stdout.isTTY  → 默认（终端 → TTY，pipe → JSON）

所以 agent 调 one list 自动走 JSON，人类终端打 one list 自动走彩色 UI。

AI Native：Skills

5 个 workflow skill 随 npm 包一起分发：

| Skill | 触发场景 | |---|---| | one-bootstrap | "建一个新项目"、"scaffold"、"from scratch" | | one-add-feature | "加一个后端"、"add a service" | | one-fix | "项目坏了"、"检查"、"fix" | | one-upgrade | "升级依赖"、"upgrade deps" | | one-reference | 命令 / JSON schema / error code 参考 |

在 Claude Code 中使用

# 安装 skills 到 Claude Code 全局目录
cp -r $(npm root -g)/qzkpwoxtl/skills/* ~/.claude/skills/

# 或者通过 agent-skills CLI
one ai skills add caorushizi/qzkpwoxtl

之后在 Claude Code 里说自然语言：

"帮我建一个 saas-platform，包含 nestjs 后端 user-api 和 react 前端 dashboard，启用 docker"

Claude 会自动：

1. 加载 one-bootstrap skill
2. 调用 one inspect --json 看当前状态
3. 调用 one list --json 拿模板列表
4. 调用 one create saas-platform --json --yes --no-interactive --docker --add api-nest:user-api
5. 调用 one add web-csr-react --name dashboard --json --yes --no-interactive
6. 调用 one inspect --json 验证健康
7. 报告结果

整个过程你只说一句话，无需操作终端。

per-Template 工程规范

每个模板带一份 ai/common.md（100-150 行）的工程契约：

| 模板 | 主要内容 | |---|---| | api-nest | Controller/Service/Repository、DTO + class-validator、BusinessException、pino | | web-csr-react | Hooks 顶层规则、design tokens、zustand store、SWR | | web-ssr-next | Server vs Client Component 边界、Server Actions、next/image | | web-ssg-astro | static-first、client:* 节制、content collection schema | | web-docs-starlight | 内置组件优先、CSS variable override | | mobile-rn-expo | NativeWind className、expo-secure-store、file-based routing | | library-ts | semver 严格、JSDoc on public、no any in public types |

one ai init 会把这些聚合到工作区根的 AGENTS.md / CLAUDE.md。Agent 在某个子项目里写代码时会自动按这个 stack 的规范来——团队工程文化用 markdown 固化，零培训成本。

完整命令参考

创建 / 添加 / 移除

one create [project-name] [options]   # 创建工作区（含 init 模块）
one add <template-id> --name <name>   # 添加子项目
one remove <name> [--force] [--dry-run]
one list                              # 查看可用模板

create 的 flag：

• -d, --dir <parent>：父目录
• -y, --yes：跳过 prompt 用默认值
• --docker / --k8s：启用 infra
• --overwrite / --ignore：处理已存在的目录
• --no-interactive：强制非交互
• --modules <a,b,c>：init 阶段要启用的模块
• --add <template>:<name>：首个子项目
• --all：启用所有模块
• --minimal：跳过 init 阶段
• --json：强制 JSON 输出

工作区维护

one inspect [--json]                  # 查看全量状态
one init [--modules a,b,c]            # 在已有 workspace 加模块
one install                           # 跑 pnpm install
one doctor [--fix] [--json]           # 健康检查 + 自动修复

高级（默认隐藏，--help-all 可见）

one upgrade [target] [--latest] [--test] [--build] [--dry-run]
one report [--json]
one manifest show / rebuild
one template check [--id <id>] [--strict]
one auth [--clear]
one ai init [--ai codex,claude-code] [--force]
one ai skills [skills-command...]
one secrets <subcommand>              # 见下

Secrets

one secrets init                      # 初始化（先装 sops + age）
one secrets edit [env]                # 用 $EDITOR 编辑
one secrets set <KEY> [VALUE] [--env <env>] [--yes]
one secrets list [--env <env>]        # 列 envs + key 名（不显示值）
one secrets get <KEY> [--env <env>]   # 读单个值
one secrets unset <KEY> [--env <env>] # 删一个 key
one secrets import-key [--from <path>]
one secrets export-key [--to <path>]
one secrets materialize [env] [--force]
one secrets doctor

重要安全特性：materialize 按 .env.example 过滤 —— 每个子项目只接收它在自己 .env.example 里声明的变量。前端子项目无法意外接收后端 secrets，不会被打进 client bundle。详见 docs/error-codes.md 的 SECRETS_* 章节。

本地开发

pnpm install
pnpm one --help            # 等价于 pnpm tsx src/index.ts --help
pnpm test                  # 全量测试（166+）
pnpm typecheck
pnpm build                 # 输出 dist/index.mjs

将本地源码 link 为全局 one：

pnpm install
pnpm build
pnpm link --global
one --help

模板维护

• 模板列表见 registry.json
• 每个模板根目录直接是模板内容（不要 template/ 子目录）
• 模板根目录不应该包含：.github、.vscode、.husky、.changeset、commitlint.*、docker-compose.yml、Dockerfile、nginx、k8s（这些是项目级的，由 one create / one add 生成）
• 模板不应该包含 lockfile（one template check 会 warning）
• 必需脚本：lint、format、check
• 至少一个可运行脚本：dev / start / preview / web
• lint 必须用 oxlint，format 必须用 oxfmt
• 每个模板的 ai/common.md 是该模板的工程规范，会被 one ai init 聚合到 workspace 根的 AGENTS.md / CLAUDE.md

校验：one template check [--id <template-id>] [--strict]

注册表

• 默认使用仓库内置并随 npm 包一起分发的 registry.json
• 可通过 ONE_REGISTRY_URL 指向自定义注册表（HTTP(S) 地址或本地 JSON）

私有模板权限

one add 通过 giget 调 GitHub API 下载模板 tarball，不是 git clone。本机 gh auth login 后 CLI 不会自动复用 git 凭据，私有仓库可能 404。

one auth        # 自动从 gh auth token 取并保存到 ~/.one-cli/auth.json
one auth --clear

认证优先级：

1. GIGET_AUTH 环境变量
2. 本地认证文件（one auth 保存）
3. 匿名访问

文档

• CHANGELOG.md — 版本历史
• docs/architecture.md — 架构设计
• docs/tech-stack.md — 技术栈说明
• docs/error-codes.md — 错误码 + remediation 参考
• skills/one-reference/SKILL.md — agent 视角的命令手册
• website/ — Starlight 文档站源码（pnpm docs:dev 启动）