152 lines
9.2 KiB
Markdown
152 lines
9.2 KiB
Markdown
# Agent 安装入口：NocoBase CRM MCP
|
||
|
||
这是一份供任意终端型 Agent 执行、也供用户审阅的安装协议。它不依赖 Codex、Claude Code、Cursor、OpenCode 或其他单一产品的插件格式。MCP 是可移植的功能层；Agent 只需把最后生成的 stdio 启动配置转换成自己客户端支持的格式。
|
||
|
||
如果你是收到本链接的 Agent：请完整阅读本文后再执行命令，按顺序持续工作到“完成条件”全部满足。不要把本文当成需要原样转发给用户的普通说明；你应根据操作系统、Shell、已有软件和当前 Agent 客户端自适应执行，并向用户报告关键检查点。
|
||
|
||
## 不可变安全规则
|
||
|
||
1. 只安装 [`install-manifest.json`](install-manifest.json) 指定的仓库和 `releaseRef`，不得默认安装 `master`、`main`、开发分支或其他未固定版本。
|
||
2. 不使用 `curl | sh`、`wget | sh` 或同类远程脚本管道。缺少全局依赖时，先说明来源、版本、影响范围并取得用户同意，再采用该工具的官方安装方式。
|
||
3. 不使用 `sudo`，不删除或覆盖未知目录，不丢弃已有 Git 改动。目标目录已存在时先识别它；不是本项目或工作区不干净时停止覆盖并向用户说明。
|
||
4. 认证默认使用用户自己的个人 API Key（Authorize Key），不使用账号密码。Agent 可以引导用户在 NocoBase 页面创建 Key，但不得要求用户把 Key 发到聊天；Key 只能由用户粘贴到本机、用户可控、隐藏回显的安全输入提示中。
|
||
5. 默认只读。除非用户明确要求且管理员已确认 NocoBase ACL，否则不得启用 `--enable-writes`、附件上传或原始数据输出。
|
||
6. 写入 Agent/MCP 客户端配置前，显示目标文件和将新增的 server 名称，创建可恢复备份，并只合并 `nocobase-crm` 条目；不得覆盖其他 MCP 配置。
|
||
7. 不把本机 MCP 端口暴露到局域网或公网。通用安装默认使用 stdio，不创建后台服务，也不生成共享业务凭证。
|
||
|
||
## 安装输入
|
||
|
||
从用户或当前上下文确定以下内容；已有明确答案时不要重复提问：
|
||
|
||
- NocoBase 应用 URL，例如 `https://nocobase.example`。安装器会规范化为以 `/api` 结尾；远程环境必须使用 HTTPS。
|
||
- 安装目录。使用该操作系统的普通用户应用/数据目录作为默认值，并在写入前告知用户；不要默认放在系统目录。
|
||
- 当前 Agent/MCP 客户端的名称及其本机 MCP 配置位置。
|
||
- 功能模式。未明确选择时必须使用“只读”。
|
||
|
||
不要要求用户在 Agent 对话中提供 NocoBase Key、密码、Token、Cookie 或 `~/.nocobase` 目录。Key 只进入 `nb` CLI 自己的本机隐藏提示。
|
||
|
||
## 执行协议
|
||
|
||
### 1. 读取并锁定发布版本
|
||
|
||
读取同版本的 `install-manifest.json`。本版本的预期来源是：
|
||
|
||
```text
|
||
repository: https://github.com/Donaldttt/nocobase-mcp.git
|
||
releaseRef: v0.2.0
|
||
```
|
||
|
||
若 `v0.2.0` 尚不存在，或 Agent 无权读取私有仓库，停止安装并清楚报告“发布物/访问权限尚未就绪”，不得退回开发分支。面向普通外部用户发布时，安装方必须能匿名读取本页和发布物；私有分发则需要用户已连接有权访问该仓库的 GitHub 账号。
|
||
|
||
首次安装使用等效于以下语义的 Git 命令，并根据当前 Shell 正确转义路径：
|
||
|
||
```bash
|
||
git clone --branch v0.2.0 --depth 1 https://github.com/Donaldttt/nocobase-mcp.git <install-dir>
|
||
git -C <install-dir> describe --tags --exact-match HEAD
|
||
```
|
||
|
||
第二条必须精确输出 `v0.2.0`。已有安装的更新不得直接 `git pull` 开发分支；先保存当前版本和 `config.json`，确认工作区干净，再获取并切换到用户指定的新 Release Tag。
|
||
|
||
### 2. 环境检查与确定性准备
|
||
|
||
需要：Git、`uv`、Python 3.12+、NocoBase `nb` CLI 2.1+。先运行只读检查：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> inspect --json
|
||
```
|
||
|
||
若 `uv` 或 `nb` 不存在，先取得用户同意再安装。NocoBase CLI 当前官方包入口是 `npm install -g @nocobase/cli`；安装后必须重新运行检查，不要通过修改 PATH 输出伪造成功。
|
||
|
||
然后运行幂等准备步骤：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> prepare --json
|
||
```
|
||
|
||
该脚本只会校验项目文件、在缺失时从示例创建 `config.json`，并执行锁定依赖同步。已有 `config.json` 会被保留，依赖必须来自 `uv.lock`。
|
||
|
||
### 3. 连接用户自己的 NocoBase 账号
|
||
|
||
先引导用户在目标 NocoBase 网页中打开头像或个人设置，寻找当前版本中名为 `API Keys`、`Access Tokens`、`访问令牌` 或类似名称的入口。让用户创建一个：
|
||
|
||
- 绑定用户本人，而不是共享服务账号；
|
||
- 只使用其正常业务角色，不选择管理员/root 角色；
|
||
- 有合理过期时间、可单独撤销；
|
||
- 仅用于这台电脑上的 MCP。
|
||
|
||
如果用户看不到个人 Key 功能，Agent 应提示联系 NocoBase 管理员开通或代为签发绑定该用户普通业务角色的 Key；不得改用账号密码或共享管理员 Key。
|
||
|
||
取得 Key 后，Agent 必须在**用户能直接控制输入的本机终端**中启动以下流程，而不是把命令交给用户手动尝试：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py \
|
||
--project-root <install-dir> connect-key \
|
||
--api-base-url <nocobase-url> --env-name nb-mcp --json
|
||
```
|
||
|
||
安装器会自动：
|
||
|
||
1. 规范化并验证 HTTPS URL；
|
||
2. 脱敏检查已有环境，拒绝覆盖指向其他服务器的同名环境；
|
||
3. 调用 `nb env add/auth --auth-type token`，但故意不传 `--access-token`，让 `nb` 在 TTY 内隐藏提示；
|
||
4. 由用户本人把 Key 粘贴到这个本机提示中，Agent 不读取输入；
|
||
5. 自动执行环境读回、把选定环境写入 `config.json`，并在修改前保存 `config.json.pre-agent-install.bak`。
|
||
|
||
若环境名冲突，安装器会给出新名称建议；Agent 使用建议名称重启同一流程，不覆盖旧环境。若当前 Agent 无法提供用户可直接输入的本机 TTY，必须停止并报告“缺少安全 Key 输入通道”；不得要求用户把 Key 粘到聊天、命令参数、环境变量或临时文件中，也不得把 `nb` 命令交给用户反复尝试。
|
||
|
||
Key 过期或撤销后，Agent 重新启动 `connect-key`，用户在新的隐私提示中输入新 Key。不得退回共享凭证。
|
||
|
||
### 4. 注册到当前 Agent/MCP 客户端
|
||
|
||
生成不含 NocoBase Token 的通用配置：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> client-config
|
||
```
|
||
|
||
输出采用常见的 `mcpServers` JSON 形状，包含绝对的项目、`uv` 和 `nb` 路径。Agent 应查明自己客户端当前版本支持的 MCP 配置格式，将其中的 `command`、`args`、`env` 等价映射过去。
|
||
|
||
写入前：
|
||
|
||
1. 向用户显示目标客户端配置文件路径和新增的 `nocobase-crm` 条目。
|
||
2. 备份原文件；解析后做结构化合并，不能用字符串替换或整文件覆盖。
|
||
3. 保留所有其他 server、设置和注释（客户端格式允许时）。
|
||
4. 按客户端要求重载 MCP 配置或提醒用户重启客户端。
|
||
|
||
只有用户明确要求项目创建/更新，且其管理员确认对应角色 ACL 后，才可重新生成含写工具的配置：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> client-config --enable-writes
|
||
```
|
||
|
||
这仍不启用上传、删除或原始数据。附件上传属于单独的 Linux 本机 HTTP 高级部署，不是通用安装流程的一部分。
|
||
|
||
### 5. 验证
|
||
|
||
先检查本机安装，不读取 NocoBase 秘密：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> doctor --json
|
||
```
|
||
|
||
然后通过已注册的 MCP 调用 `crm_health`。只有同时满足以下条件才可向用户报告安装完成：
|
||
|
||
- `doctor` 返回 `ok: true`；
|
||
- `connect-key` 返回 `ok: true`、`authType: token`，且目标 URL 正确；
|
||
- 客户端已发现 `nocobase-crm`；
|
||
- `crm_health` 返回 `ok: true`，不是 `nb_auth_failed`、`NO_PERMISSIONS` 或其他结构化错误；
|
||
- 默认状态仍是只读、uploads disabled、raw data disabled。
|
||
|
||
最后报告安装目录、Release Tag、NocoBase 环境名、客户端配置备份位置、启用的能力以及一条最小使用示例。不要报告或回显任何 Token。
|
||
|
||
## 给用户的最短用法
|
||
|
||
普通情况下，用户只需把当前**不可变 Release 版本**的 `INSTALL.md` 链接发给具备本机终端和文件权限的 Agent，并说：
|
||
|
||
```text
|
||
请完整阅读这个安装协议，根据我的系统和当前 Agent 客户端自适应安装。默认只读；认证使用我本人的个人 API Key，不使用账号密码。请引导我在 NocoBase 获取 Key，并只让我在本机隐藏提示中粘贴；不要让我把 Key 发到聊天，也不要让我手动尝试 nb 命令。安装后必须通过 doctor 和 crm_health：
|
||
<version-pinned INSTALL.md URL>
|
||
```
|
||
|
||
如果 Agent 只能聊天、不能执行本机命令或写 MCP 配置，它应说明能力限制并按本文生成逐步人工安装指令，而不能声称已经安装。
|