one add

工作区已启用 hk 时，one add 会同步更新语言检查：Go 加入格式检查，JS/TS 根据项目工具加入 lint 和格式检查。检查配置直接保存在 .config/hk.pkl，用户修改和注释会保留。工作区和项目任务统一登记在根 mise.toml，子项目继续使用自己的原生命令文件。旧工作区可先通过 one init 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 决定。

创建工作区和添加项目时会准备 mise，并自动信任完全由 One 生成的 mise.toml，进入新目录无需再单独执行信任命令。已有自定义配置保留 mise 原有的信任检查。本机没有兼容版本时，One 可能下载托管的 mise 程序；项目工具和依赖仍按需安装。信任失败会保留生成文件并给出恢复命令。

用法

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

参数

参数	说明
`template-id`	模板 ID（如 `nestjs-api`）；不传走交互式选择
`-n, --name`	项目名（必填，非交互模式）
`-y, --yes`	非交互模式
`-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

创建空项目

在已有工作区中，可以先创建目录并登记项目，之后再选择语言或框架：

one add empty-app --name web --yes
one add empty-service --name api --yes
one add empty-library --name shared --yes

三个模板分别创建 apps/web/、services/api/、packages/shared/，仅包含用于 Git 跟踪目录的 .gitkeep。它们以 toolchain: "none" 登记，不生成 package.json、go.mod、依赖或启动任务。交互式 one add 和 Dashboard 的新建项目选择器也提供这三个选项。

如果使用 Node 或 Go，在 one.manifest.json 中将项目的 toolchain 改为 node 或 go；Node 项目使用 packageManager: "pnpm"，并补齐根工作区的包成员配置，Go 项目则将模块加入根 go.work。在 package.json / Taskfile.yml 中定义任务，或设置项目的 dev.command，然后运行 one init mise 更新任务配置。使用其他语言时，可以保留 toolchain: "none"，在根 mise.toml 中自行定义工具和任务，或设置 dev.command。配置好命令后再使用 one dev / one build。

输出

{
  "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 -p <project> 开发，使用 one build -p <project> 构建
one add 只生成项目和工作区配置；one dev 会自动准备工具与应用依赖。JS/TS 在根目录统一安装，Go 按当前模块或 go.work 构建图准备依赖。修改 imports 或模块声明需要修复时，显式运行 one exec <project> -- go mod tidy。