150 lines
8.2 KiB
Markdown
150 lines
8.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. 用户必须亲自在浏览器完成 NocoBase OAuth 登录。不得索取、复制、打印或保存用户的 Access Token、Refresh Token、Cookie、密码或 `~/.nocobase` 目录；不得执行带 `--show-secrets` 的命令。
|
||
5. 默认只读。除非用户明确要求且管理员已确认 NocoBase ACL，否则不得启用 `--enable-writes`、附件上传或原始数据输出。
|
||
6. 写入 Agent/MCP 客户端配置前，显示目标文件和将新增的 server 名称，创建可恢复备份，并只合并 `nocobase-crm` 条目；不得覆盖其他 MCP 配置。
|
||
7. 不把本机 MCP 端口暴露到局域网或公网。通用安装默认使用 stdio，不创建后台服务，也不生成共享业务凭证。
|
||
|
||
## 安装输入
|
||
|
||
从用户或当前上下文确定以下内容；已有明确答案时不要重复提问：
|
||
|
||
- NocoBase 应用 URL，例如 `https://nocobase.example`。执行 `nb env add` 前规范化为以 `/api` 结尾。
|
||
- 安装目录。使用该操作系统的普通用户应用/数据目录作为默认值，并在写入前告知用户；不要默认放在系统目录。
|
||
- 当前 Agent/MCP 客户端的名称及其本机 MCP 配置位置。
|
||
- 功能模式。未明确选择时必须使用“只读”。
|
||
|
||
不要要求用户提供 NocoBase Token。OAuth 登录之外没有必填秘密输入。
|
||
|
||
## 执行协议
|
||
|
||
### 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 账号
|
||
|
||
先直接执行：
|
||
|
||
```bash
|
||
nb env list
|
||
```
|
||
|
||
如果 `nb-mcp` 不存在，为规范化后的目标 URL 创建 OAuth 环境，并在写操作后读回列表：
|
||
|
||
```bash
|
||
nb env add nb-mcp --api-base-url <normalized-url-ending-in-/api> --auth-type oauth
|
||
nb env list
|
||
```
|
||
|
||
如果 `nb-mcp` 已存在，先用不显示秘密的 `nb env info nb-mcp` 核对 URL。URL 相同则复用；URL 不同则不要覆盖，选择清楚且未占用的新名称（例如 `nb-mcp-example`），创建后同步更新项目配置：
|
||
|
||
```bash
|
||
uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py --project-root <install-dir> set-env <new-env-name> --json
|
||
```
|
||
|
||
此命令修改前会保留 `config.json.pre-agent-install.bak`。然后启动登录：
|
||
|
||
```bash
|
||
nb env auth <configured-env>
|
||
```
|
||
|
||
让用户亲自在浏览器完成登录；Agent 只负责保持命令运行、提示用户返回以及继续读取 CLI 的成功或错误信息。最后执行 `nb env info <configured-env>` 验证，不得附加 `--show-secrets`。如果登录失败或过期，重新运行同一个 `nb env auth`，不得换用共享 Token。
|
||
|
||
### 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`；
|
||
- `nb env info <configured-env>` 成功且目标 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 客户端自适应安装。默认只读；不要索取或显示任何 Token；需要全局安装依赖、写客户端配置或启用写功能前先告诉我。安装后必须通过 doctor 和 crm_health：
|
||
<version-pinned INSTALL.md URL>
|
||
```
|
||
|
||
如果 Agent 只能聊天、不能执行本机命令或写 MCP 配置，它应说明能力限制并按本文生成逐步人工安装指令，而不能声称已经安装。
|