AI Native 工作模式

理念

one cli 不是又一个 monorepo 工具。它的设计前提是：

AI agent 是主要使用者，人类是监督者。

这意味着：

• 命令默认输出结构化 JSON（非 TTY 自动启用），agent 不用解析人类文本
• 错误带 code + context + remediation[]，agent 能直接读取恢复方案
• 4 个 workflow skill 描述完整流程，agent 加载后用自然语言驱动整个流程
• per-template 工程规范让 agent 写代码时自动遵守团队风格

端到端示例

人类：

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

Claude Code 自动：

# 1. 看当前状态
one status --json
# → workspace.is_one_project: false
# → available_actions[0]: "create-workspace"

# 2. 拿模板列表（确认 IDs）
one templates --json
# → templates[]: api-nest, web-csr-react, ...

# 3. 创建工作区
one create saas-platform --yes --docker

# 4. 添加首个子项目（自动刷新 AI guides）
cd saas-platform
one add api-nest --name user-api --yes --json

# 5. 加第二个子项目
one add web-csr-react --name dashboard --yes --json

# 6. 安装依赖并验证
pnpm install
one status --json
# → subprojects has 2 entries, issues empty

整个过程人类只说一句话。

4 个层次让这成为可能

1. 结构化 JSON 输出

每个命令都有版本化 schema：

命令	Schema
one templates --json	one-cli/templates/v1
one status --json	one-cli/status/v1
one create --json	one-cli/create/v1
one add --json	one-cli/add/v1
one doctor --json	one-cli/doctor/v1
one secrets pull --json	one-cli/secrets-pull/v1
错误	one-cli/error/v1

字段统一snake_case 英文，方便 agent 用 jq / Python 等解析。

2. 结构化错误

{
  "schema": "one-cli/error/v1",
  "error": {
    "code": "TEMPLATE_NOT_FOUND",
    "message": "模板 \"vue\" 不存在",
    "context": {
      "requested_template": "vue",
      "available_templates": ["api-nest", "web-csr-react", "web-ssr-next", ...]
    },
    "remediation": [
      {
        "action": "use-different-template",
        "hint": "从 available_templates 里挑一个",
        "command": null
      },
      {
        "action": "list-templates",
        "hint": "查看所有可用模板",
        "command": "one templates --json"
      }
    ]
  }
}

agent 拿到错误后不需要再调一次 list——available_templates 已经在 context 里了。直接挑一个重试。这是 AI Native 错误设计的核心：错误 里包含恢复所需的所有数据。

3. one status：agent 的”看世界”入口

调用 one status --json 拿到工作区的全量状态 + ranked 的下一步建议：

{
  "available_actions": [
    {
      "action": "fix-issues",
      "command": "one doctor --fix",
      "reason": "3 workspace issue(s) detected",
      "priority": 70
    },
    {
      "action": "rebuild-manifest",
      "command": "one doctor --fix",
      "reason": "1 subproject(s) not tracked in manifest",
      "priority": 60
    }
  ]
}

agent 不需要记忆 / 不需要猜下一步——直接读 available_actions[0].command 执行就行。

4. 4 个 workflow skills

随 npm 包一起分发的 Claude Code skills：

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

每个 skill 包含：

• frontmatter（name + description with triggers）
• numbered workflow with copy-pasteable commands
• error recovery table by error code
• 3+ example dialogues

安装 skills

one create 会把随包分发的 workflow skills 安装到 Claude Code 全局目录。

之后在 Claude Code 里说自然语言即可，Claude 会自动加载相应的 skill。

per-Template 工程规范

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

模板	主要内容
api-nest	Controller/Service/Repository、DTO + class-validator、BusinessException、pino
api-go	Go project-layout、Gin、Gorm、Viper、Zap、go-task
web-csr-react	Hooks 顶层规则、design tokens、zustand store
web-ssr-next	Server vs Client Component 边界、Server Actions、next/image
web-ssg-astro	static-first、client:* 节制
mobile-rn-expo	NativeWind className、expo-secure-store、file-based routing
library-ts	semver 严格、JSDoc on public、no any in public types

one add 会把这些规范聚合到工作区根的 AGENTS.md / CLAUDE.md，one doctor --fix 可以补齐缺失的 AI 指南。 当 Claude 在某个子项目里写代码时，会自动按那个 stack 的规范来——团 队工程文化用 markdown 固化，零培训成本。

给 agent 开发者的建议

如果你正在写一个 agent / skill 用 one cli：

1. 永远先 one status --json——读 available_actions[0]
2. 错误用 error.code 路由，永远不解析 error.message
3. 读 error.context 拿已经获取的数据，不要重复调用
4. error.remediation[] 已经按推荐度排序，挑第一个非 destructive 的
5. 不要在同一个 args 上重试同一个失败的命令——失败 → 读 context → 改 args 或换策略
6. one-cli/<command>/v1 schema 字段名是契约——snake_case 英文，向后兼容
7. 多个 sub-command 输出 NDJSON——读最后一行的 schema 知道整体结果

进一步阅读

• CLI 概览 — 命令面 + 输出模式
• one status reference — 全量状态查询
• Error codes — 完整错误码表 + 恢复模式
• one secrets — 含安全 decrypt 契约