one add

工作区已启用 hk 时，one add 会同步更新语言检查：Go 加入格式检查，JS/TS 根据项目工具加入 lint 和格式检查。用户的 hk.pkl 保留不变。旧工作区可先通过 one configure hooks 启用，详见 one hk。

one add 选择技术栈，生成一个可本地开发的项目并登记到 manifest。CI 和部署默认都保持未配置。

有两条入口：

人类第一次用：直接跑 one add，在交互式选择器里选模板分类、模板，并输入项目名。
脚本 / 已知模板：先跑 one templates 看模板 ID，再执行 one add <template-id> --name <project-name>。

template-id 是模板 ID，例如 nestjs-api / nextjs-app / ts-library，不是项目名；项目名由 --name 决定。

用法

one add [template-id] --name <project-name> [--deploy-provider <backend>] [options]

参数

参数	说明
`template-id`	模板 ID（如 `nestjs-api`）；不传走交互式选择
`-n, --name`	项目名（必填，非交互模式）
`-y, --yes`	非交互模式
`--deploy-provider <backend>`	显式选择 deploy 后端（必须在模板的 compat 列表里）
`-o, --output <fmt>`	`json` / `yaml` / `text`

首次添加 JS/TS 项目时初始化 Node monorepo，新工作区默认使用 pnpm；已有 Node 工作区沿用其包管理器。首次添加 Go 模块时初始化根 go.work，从第一个模块开始维护 use 成员。Go 与 Node 配置可以共存，后续添加只增量登记。已有 go.work 的注释、replace、toolchain 和外部成员会保留；配置冲突会在写入前报告。

交互模式

直接运行 one add 会依次询问：想添加什么（应用、服务或共享库）、选择技术栈、输入项目名。三类与生成目录 apps/、services/、packages/ 对应；文档站属于应用，显示在第一类中。不会询问部署目标。

非交互场景要显式传模板 ID 和项目名：

one add nestjs-api --name api --yes

输出

{
  "schema": "one-cli/add/v1",
  "subproject_name": "user-api",
  "target_path": "/abs/path/my-app/services/user-api",
  "template_id": "nestjs-api",
  "toolchain": "node",
  "package_manager": "pnpm"
}

warnings[] 存在时表示模板兼容性或后置同步有非阻断提示；项目仍然加成功。

示例

交互（人类）

cd my-app
one add

这个流程会依次询问：

项目类型（应用 / 服务 / 共享库）
技术栈（比如 nestjs-api）
项目名（比如 api）

不确定模板 ID 时，用这一种最稳。

先看模板，再显式添加

one templates
one add nestjs-api --name api

one templates 列出的 id 就是 one add 后面的第一个参数。

非交互（CI / agent）

one add nestjs-api      --name user-api --yes
one add nextjs-app  --name web      --yes
one add ts-library    --name shared   --yes

Agent 调用（拿 JSON）

one add nestjs-api --name user-api --yes -o json | jq

加完会自动做的事

把项目登记到 one.manifest.json#projects[]
写入项目的本地开发命令
持续集成保持未配置
部署和镜像配置保持为空，首次部署时再生成

非阻断同步问题通过 warnings[] 返回，项目仍然加成功。

错误恢复

错误码	处理
`TEMPLATE_NOT_FOUND`	模板 ID 错；context 里有 `available_templates`，挑一个用
`TEMPLATE_REQUIRED`	非交互场景没传 template-id；显式传一个
`INVALID_NAME`	`--name` 不符合 `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`
`SUBPROJECT_NAME_REQUIRED`	非交互模式必须传 `--name`
`TARGET_EXISTS`	项目目录已存在；换 `--name`
`NOT_ONE_PROJECT`	cwd 不是工作区；先 `one create <dir>`，或 `cd` 到已有工作区
`REGISTRY_FETCH_FAILED`	网络问题；查 context 里的 registry url

完整码表：错误码大全。

模板选择

不知道选哪个？看模板决策树。

加完之后

检查 one.manifest.json#projects[] 确认项目登记
Agent 文档和本地开发配置会由 one add 同步
下一步运行 one dev <project>；需要部署时再运行 one deploy <project>
如需持续集成，单独运行 one ci enable <project> 生成 GitHub Actions 工作流
one add 只生成项目和工作区配置；one dev 会自动准备工具与应用依赖。JS/TS 在根目录统一安装，Go 按当前模块或 go.work 构建图准备依赖。修改 imports 或模块声明需要修复时，显式运行 one run <project> -- go mod tidy。