# @cogito\.ai/cli 中文文档

规范地址：https://npmcn.com/package/%40cogito.ai/cli/

版本：0\.32\.7
npm 元数据更新时间：2026-11-08T09:45:00.954Z
中文译文更新时间：2026-11-10T10:58:48.753Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cogito.ai/cli
原文对照：https://npmcn.com/package/%40cogito.ai/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：15.4 MB，1152 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：6 个
- 首次发布：2026-06-03T03:29:10.487Z
- 最新版本发布：2026-11-08T09:45:00.758Z
- 近 30 天下载量：3209（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

AgentDock CLI – 人类和AI特工的脚手架项目

## 安装

```sh
npm install @cogito.ai/cli
```

也可以使用：`pnpm add @cogito.ai/cli`、`yarn add @cogito.ai/cli`、`bun add @cogito.ai/cli`

## README

# 探员Dock CLI

**`@cogito.ai/cli`** ——"脚手架"制作准备的人工智能编码代理项目为人类,CI管道,人工智能代理.

[![npm version](https://img.shields.io/npm/v/@cogito.ai/cli)](https://www.npmjs.com/package/@cogito.ai/cli)

* * *

## 快速启动

```bash
# Interactive mode (for humans)
npx @cogito.ai/cli init

# Headless mode (for CI / AI agents)
npx @cogito.ai/cli init --name my-app --template web-nextjs --pm pnpm --json

# Workspace-member mode (existing pnpm workspace)
npx @cogito.ai/cli init --name my-app --template web-tanstackstart --dir apps/my-app --mode workspace --json

# Start MCP Stdio server (for AI agents via Model Context Protocol)
npx @cogito.ai/cli mcp
```

## 安装

```bash
# Run without installing (recommended)
npx @cogito.ai/cli <command>

# Global install
npm install -g @cogito.ai/cli
pnpm add -g @cogito.ai/cli
```

* * *

## 图标

### `agentdock init`

脚手架从模板中复制出一个新项目. 自动检测环境 :

-   **类型** + 交互式提示( 人模式)
-   **非TTY 类型 / `--silent` 编号 : `--json`** − 无头处决(代理/CI模式)

| 旗帜 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `--name` | 字符串 | 所需经费 | 项目名称和目标目录名称 |
| `--template` | 字符串 | 所需经费 | 模板ID( 如. `web-nextjs`(中文(简体) ) |
| `--pm` | 字符串 | `pnpm` | 软件包管理器 : `pnpm` 编号 : `npm` 编号 : `yarn` 编号 : `bun` |
| `--dir` | 字符串 | `./<name>` | 目标目录(绝对或相对 cwd) |
| `--mode` | 字符串 | `auto` | 放置模式 : `auto` 编号 : `workspace` 编号 : `standalone` |
| `--integrations` | 字符串 | 空 | 可选集成ID; 重复或逗号分隔. 当前支持 `mastra` |
| `--json` | 布尔 | `false` | 输出 NDJSON 结果是 stdout |
| `--silent` | 布尔 | `false` | 禁止所有输出 |

`--mode auto` 检测最近的 pnpm 工作空间,并检查目标是否与其匹配 `packages` glo. 工作空间成员产出不复制 `pnpm-workspace.yaml`, (中文(简体) ), `pnpm-lock.yaml`,或 `.npmrc`成员 `packageManager` 编号 : `engines.pnpm` 字段。 根号 `allowBuilds` 更改在 `requiredRootChanges`; CLI 不修改根配置.

**JSON 输出( 成功) :**

```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": []
}
```

**JSON 输出( 失败) :**

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

**错误代码 :** `MISSING_ARG` • 妇女 `TEMPLATE_NOT_FOUND` • 妇女 `TARGET_DIR_EXISTS` • 妇女 `CLI_VERSION_OUTDATED` • 妇女 `SCAFFOLD_FAILED` • 妇女 `INVALID_MODE` • 妇女 `WORKSPACE_MODE_UNSUPPORTED` • 妇女 `WORKSPACE_NOT_MATCHED` • 妇女 `WORKSPACE_STANDALONE_CONFLICT` • 妇女 `WORKSPACE_CONFIG_INVALID` • 妇女 `WORKSPACE_PACKAGE_MANAGER_INCOMPATIBLE` • 妇女 `WORKSPACE_NODE_INCOMPATIBLE` • 妇女 `INVALID_INTEGRATION` • 妇女 `INTEGRATION_NOT_SUPPORTED` • 妇女 `INTEGRATION_CONFLICT`

* * *

### `agentdock mcp`

启动 MCP( 模式背景协议) Stdio 服务器 。 曝光CLI能力作为AI代理直接调用的工具.

```bash
agentdock mcp
```

**可用工具 :**

| 工具 | 说明 |
| --- | --- |
| `list_templates` | 列出项目模板和支持的集成ID |
| `scaffold_project` | 脚手架,与无头入门相同的输入 |

**VS 代码副驾驶 MCP 配置`.vscode/mcp.json`:**

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

* * *

## 可用的模板

| 模板 ID | 说明 |
| --- | --- |
| `web-nextjs` | Next.js 16 + Supabase + next-intl + Tailwind CSS v4 + Veste + Fumadocs – 全高单曲启动器 |

* * *

## 建筑

CLI使用一个 **适应器模式** 单一执行器核心服务于三个消费者表面:

```
agentdock init
      │
      ├── TTY detected ──→ Human Adapter  (Clack interactive UI)
      └── Non-TTY / flags ──→ Agent Adapter (structured JSON output)

agentdock mcp ──→ MCP Adapter (MCP Stdio Server)

All adapters share the same Core Executor (scaffold + registry)
```

**设计原则:**

1.  **无头第一** ——执行器核心没有TTY的依赖性;人类UI是上层的薄壳.
2.  **结构化输出为协议** —— 说 `--json` 模式生成稳定的机器可分解的NDJSON,而不是自然语言.
3.  **一个能力,三个表面** —— 说 `scaffold_project` 被执行一次并自动投放到 CLI 旗帜、 JSON 模式和 MCP 工具上.

**技术堆栈 :**

| 构成部分 | 作用 |
| --- | --- |
| [阿宝](https://github.com/oven-sh/bun) | 构建: 单文件 Node.js 可执行文件 |
| [齐蒂](https://github.com/unjs/citty) | 命令建模:子命令、旗帜图案、懒惰装入 |
| [阴道](https://github.com/bombshell-dev/clack) | 人类互动: TTY 提示 |
| [MCP 类型脚本 SDK](https://github.com/modelcontextprotocol/typescript-sdk) | 代理协议: MCP Stdio 服务器 |
| [更改](https://github.com/changesets/changesets) | 发布治理:语义版本+更改日志 |

* * *

## 发展

```bash
# Install dependencies
pnpm install

# Regenerate template registry
pnpm --filter @cogito.ai/cli generate-registry

# Run from source (no build needed)
npx tsx packages/cli/bin/agentdock.ts init

# Run tests
pnpm --filter @cogito.ai/cli test

# Build
pnpm --filter @cogito.ai/cli build
```

### 添加模板

1.  创建 `templates/<id>/` 具有完整的项目结构.
2.  添加 `package.json` 与 `"agentdock": { "minCliVersion": "x.y.z" }`。 。 。 .
3.  运行 `pnpm --filter @cogito.ai/cli generate-registry`。 。 。 .
4.  发布一个新的CLI版本——模板被捆绑在npm包内.

支持嵌入 pnpm 工作空间的单包模板可以添加 `agentdock.workspaceMember.rootAllowBuilds`。Monorepo模板应保持单独.

支持不精确 pnpm 范围的模板 `packageManager` 针可以设置 `agentdock.packageManagerEnforced: true` 并宣布 `engines.pnpm`。这只保留 pnpm ,同时避免自动软件包管理切换.

### 出版新版本

```bash
pnpm changeset          # describe the change
pnpm changeset version  # bump version + update CHANGELOG
pnpm --filter @cogito.ai/cli build
pnpm --filter @cogito.ai/cli publish
```

* * *

## 许可证

麻省理工学院

* * *

[中文文档](https://npmcn.com/package/%40cogito.ai/cli/README-zh.md)

## 常见问题

### @cogito\.ai/cli 是什么？

AgentDock CLI – 人类和AI特工的脚手架项目

### 如何安装 @cogito\.ai/cli？

在项目目录运行 npm install @cogito\.ai/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agentdock，可以用 npx agentdock 直接运行。

### @cogito\.ai/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cogito\.ai\_\_cli 是否存在。

### @cogito\.ai/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cogito\.ai/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cogito\.ai/cli 可以商用吗？

@cogito\.ai/cli 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cogito\.ai/cli 的下载量有多少？

根据 npm 官方下载统计，@cogito\.ai/cli 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,209 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cogito\.ai/cli 还在维护吗？

最新版本 0\.32\.7 发布于 2026/11/08（2 天前）；至今共发布 63 个版本，其中过去 12 个月发布了 63 个；首次发布于 2026/06/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。