agentdock init 与 agentdock mcp 命令的完整使用说明，涵盖交互模式、无头模式与 MCP 接入。

使用指南

安装

# 推荐：每次使用最新版
npx @cogito.ai/cli <command>

# 全局安装
npm install -g @cogito.ai/cli
# 或
pnpm add -g @cogito.ai/cli

安装完成后可直接使用 agentdock 命令：

agentdock --version
agentdock --help

`agentdock init`

从模板创建一个新项目。自动检测运行环境并切换模式：

TTY 环境（终端直接运行）→ 交互模式
非 TTY 环境（CI / 管道）或显式传入 --silent / --json → 无头模式

交互模式（人类开发者）

直接运行，按提示输入：

npx @cogito.ai/cli init

交互流程：

输入项目名称（小写字母、数字、连字符）
选择模板（方向键选择）
选择包管理器（pnpm 推荐）
选择数据层与包管理器（模板相关）
选择 domain-packages 时继续输入首个 domain package id 与 intent
确认创建

创建完成后输出：

◆ Project created at ./my-app

  cd my-app
  pnpm install
  pnpm run dev

无头模式（CI / Agent）

所有参数通过 flag 传入，不会出现任何交互提示：

agentdock init \
  --name my-app \
  --template web-nextjs \
  --pm pnpm \
  --json

Flag 说明

Flag	类型	默认值	说明
`--name`	string	必填	项目名称，也是目标目录名
`--template`	string	必填	模板 ID，如 `web-nextjs`
`--pm`	string	`pnpm`	包管理器：`pnpm` / `npm` / `yarn` / `bun`
`--dir`	string	`./<name>`	目标目录（绝对路径或相对于 cwd）
`--mode`	string	`auto`	放置模式：`auto` / `workspace` / `standalone`
`--integrations`	string	空	可选 integration ID，可重复或用逗号分隔；当前支持 `mastra`
`--domain-package-id`	string	空	`domain-packages` 模板：首个 package id；必须与 `--domain-package-intent` 成对出现
`--domain-package-intent`	string	空	`domain-packages` 模板：一句话领域意图；必须与 `--domain-package-id` 成对出现
`--domain-package-display-name`	string	从 id 推导	`domain-packages` 模板：可选显示名
`--domain-package-owner`	string	`@product-team`	`domain-packages` 模板：可选 owner
`--domain-package-spec`	string	空	`domain-packages` 模板：非交互 `package-spec.json` 路径；不能与显式 package 字段混用
`--json`	boolean	`false`	以 NDJSON 格式输出结果
`--silent`	boolean	`false`	抑制所有输出（无声模式）

Workspace 放置模式

--mode auto 会从目标目录向上寻找最近的 pnpm workspace，并按 pnpm-workspace.yaml#packages 判断目标是否为成员：

匹配 workspace glob：生成 workspace member，不复制子级 pnpm-workspace.yaml、pnpm-lock.yaml、.npmrc，并移除子包 packageManager / engines.pnpm。
不在 workspace 中：生成完整 standalone 项目。
目标被父 workspace 匹配但指定 standalone：初始化失败。子级 workspace 文件不能阻止父 workspace 把它识别为成员；应将项目放到 workspace 外或先添加负 glob。

workspace member 生成示例：

npx @cogito.ai/cli init \
  --name my-internal-app \
  --template web-tanstackstart \
  --dir apps/my-internal-app \
  --mode workspace \
  --json

根 workspace 的 allowBuilds 默认不会被自动修改。结果中的 requiredRootChanges 是需要人工或 Agent 审核后合并的条目；rootConfigConflicts 表示根配置已有 false 或无效值，CLI 不会覆盖。

JSON 输出格式

成功时输出到 stdout（单行 JSON）：

{
  "ok": true,
  "targetDir": "/path/to/my-app",
  "name": "my-app",
  "template": "web-nextjs",
  "mode": "standalone",
  "integrations": ["mastra"],
  "lockfileOwner": "/path/to/my-app/pnpm-lock.yaml",
  "requiredRootChanges": [],
  "rootConfigConflicts": []
}

如果 domain-packages 初始化提供了 package 参数，成功结果还会包含 domainPackage：

{
  "domainPackage": {
    "ok": true,
    "id": "example-domain",
    "packagePath": "/path/to/my-domain-packages/apps/example-domain",
    "webPath": "/path/to/my-domain-packages/apps/web"
  }
}

workspace member 输出还会包含 workspaceRoot：

{
  "ok": true,
  "targetDir": "/repo/apps/my-app",
  "name": "my-app",
  "template": "web-tanstackstart",
  "mode": "workspace",
  "workspaceRoot": "/repo",
  "lockfileOwner": "/repo/pnpm-lock.yaml",
  "requiredRootChanges": [
    {
      "file": "pnpm-workspace.yaml",
      "operation": "mergeAllowBuilds",
      "entries": { "better-sqlite3": false }
    }
  ],
  "rootConfigConflicts": []
}

失败时输出到 stdout（非 TTY 模式下），同时以非零退出码退出：

{
  "ok": false,
  "error": "TARGET_DIR_EXISTS",
  "message": "Directory already exists: /path/to/my-app"
}

错误码

error	含义
`MISSING_ARG`	必填参数缺失（`field` 字段指明哪个参数）
`TEMPLATE_NOT_FOUND`	模板 ID 不存在
`TARGET_DIR_EXISTS`	目标目录已存在
`CLI_VERSION_OUTDATED`	CLI 版本低于模板的 `minCliVersion` 要求
`SCAFFOLD_FAILED`	文件复制/写入失败
`INVALID_MODE`	传入的 placement mode 不是 `auto`、`workspace` 或 `standalone`
`WORKSPACE_MODE_UNSUPPORTED`	模板未声明 workspace-member 能力
`WORKSPACE_NOT_MATCHED`	强制 workspace mode，但父 workspace glob 未匹配目标
`WORKSPACE_STANDALONE_CONFLICT`	强制 standalone，但目标已被父 workspace glob 匹配
`WORKSPACE_CONFIG_INVALID`	无法解析父 workspace 的必要配置
`WORKSPACE_PACKAGE_MANAGER_INCOMPATIBLE`	根 pnpm 版本不满足模板要求
`WORKSPACE_NODE_INCOMPATIBLE`	当前 Node 版本不满足模板要求
`INVALID_INTEGRATION`	请求的 integration ID 不存在
`INTEGRATION_NOT_SUPPORTED`	所选模板不支持该 integration
`INTEGRATION_CONFLICT`	integration 会覆盖生成文件或与现有配置冲突

`agentdock mcp`

启动一个 MCP Stdio 服务器，将 CLI 能力投影为 AI Agent 可直接调用的工具接口。

agentdock mcp

服务器通过 stdio 通信，遵循 Model Context Protocol 规范。

暴露的工具

工具名	说明
`list_templates`	列出模板及兼容的 integration ID
`scaffold_project`	使用与 headless init 相同的输入生成项目

`list_templates` 调用示例

输入：{} （无参数）

输出：

{
  "templates": [
    {
      "id": "web-nextjs",
      "name": "web-nextjs",
      "description": "Full-stack Next.js 16 monorepo starter with Supabase, next-intl, Tailwind CSS, Vitest and built-in Fumadocs docs site",
      "minCliVersion": "0.1.0",
      "workspaceMember": false,
      "integrations": []
    }
  ]
}

`scaffold_project` 调用示例

输入：

{
  "name": "my-app",
  "template": "web-nextjs",
  "targetDir": "/Users/me/projects/my-app",
  "packageManager": "pnpm",
  "mode": "auto",
  "dataLayer": "sqlite",
  "displayName": "My App",
  "integrations": ["mastra"]
}

成功输出：

{
  "ok": true,
  "targetDir": "/Users/me/projects/my-app",
  "name": "my-app",
  "template": "web-nextjs",
  "mode": "standalone",
  "lockfileOwner": "/Users/me/projects/my-app/pnpm-lock.yaml",
  "requiredRootChanges": [],
  "rootConfigConflicts": []
}

在 MCP 客户端中配置

以 VS Code Copilot 为例，在 .vscode/mcp.json 中：

{
  "servers": {
    "agentdock": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cogito.ai/cli", "mcp"]
    }
  }
}

可用模板

模板 ID	说明
`web-nextjs`	Next.js 16 + Supabase + next-intl + Tailwind CSS v4 + Vitest + Fumadocs 的全栈 monorepo 模板

查看完整模板列表：

# 通过 MCP 工具列出
agentdock mcp  # 然后调用 list_templates

# 或查看仓库
ls templates/

使用指南

On this page