# 本机交付与权限验收

## 交付模型

每位用户在自己的电脑运行 MCP，并通过 NocoBase 原生 OAuth 登录本人业务身份：

```text
本机 AI 客户端 → 本机 TypeScript MCP → https://justconn.top/api → 本人 ACL
```

项目不保存共享业务账号，也不需要多人共用的远程 MCP 服务。个人 Authorize Key 仅作为显式备用认证方式。

## 最新 Commit 安装与更新

默认安装和更新都不等待 Release。用户可以每次发送同一个 INSTALL 链接；Agent 先检查现有 MCP 条目、安装入口和 `install-receipt.json`，再读取 Gitea `main` 的最新完整 Commit SHA，并把这次任务固定在该 SHA。需要首次安装、更新或修复时：

- 从带 SHA 的不可变 URL 重新读取 `INSTALL.md`；
- 下载同一 SHA 的源码归档；
- 在临时目录执行锁定依赖安装、检查、测试、bundle 和 npm pack；
- 首次安装到用户级隔离前缀，更新则沿用原前缀并保留配置、凭据和读写模式；
- 报告完整 Commit SHA 和本地 tarball SHA-256。

若有效安装记录已经是同一最新 SHA，并且二进制、帮助和 MCP 入口均完整，Agent 直接执行配置核对与 `crm_health`，不重复下载、构建或要求重新登录。解析 SHA 后，即使 `main` 在任务期间更新，也不混入新文件；下一次安装或更新才采用更新后的提交。任何检查或构建失败都停止，不回退旧 Release。正式 Release 可以继续用于归档和人工回滚，但不是默认安装来源。

Gitea 仓库访问受限时，用户或 Agent 必须具有源码和 Commit 归档读取权限。受限仓库链接本身不能成为任意用户可访问的一键安装链接，也不得通过聊天传递访问令牌。

## 用户电脑上的内容

- Node.js 20.11+（唯一系统运行时）；
- 用户应用数据目录中的打包 MCP；
- CRM 映射配置；
- 当前 OS 用户的私有凭证文件；
- MCP 客户端配置和备份。

不需要 Git、Python、uv、`nb CLI` 或持久源码 checkout。npm 在临时目录安装锁定的构建依赖并生成 bundle，随后只在隔离前缀安装本地 tarball；运行时没有额外 npm 依赖。临时源码和构建依赖不属于持久安装内容。

## 权限验收

至少使用两个权限不同的真实测试账号：

1. 分别在隔离的 OS 用户/凭证路径注册 MCP，调用 `nocobase_login`，再使用两个账号在 NocoBase 网页授权。
2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups`、`list_projects`。
3. 确认返回范围与各自在 NocoBase UI 中的 ACL 一致。
4. 无项目写权限账号在 `--enable-writes` 下调用 `create_project`，确认 NocoBase 拒绝。
5. 有权限账号创建和更新测试项目，确认审计身份属于该用户。
6. 让其中一个账号的 OAuth 会话失效，确认 MCP 自动刷新失败后返回 `nocobase_auth_failed`，且不会降级使用其他凭证。
7. 检查错误与日志，确认没有访问令牌、刷新令牌、Authorization header、Key 或业务原始行泄漏。

## 更新与回滚

更新时，Agent 重新解析 `main` 的最新 Commit；SHA 变化或现有入口不完整时，在新临时目录完成全部检查和构建，再对同一隔离前缀运行 `npm install --prefix ... --omit=dev <locally-built-tarball>`。更新前备份 MCP 客户端配置和非秘密 CRM 配置，并记录更新前后的完整 Commit SHA；沿用现有 `--enable-writes` 状态，除非用户明确要求改变。

MCP 重载后先调用 `crm_health`。已有 OAuth 登录仍有效时直接完成更新；只有明确返回认证失败时才启动浏览器授权。成功后原子写入不含秘密的 `install-receipt.json`，供下次准确判断是否已经是同一 Commit。

回滚是唯一允许选择旧提交的安装操作：使用上次记录的完整 Commit SHA 重建并安装该快照，不通过移动分支名猜测版本。凭证文件与 CRM 配置位于包目录之外，更新和回滚不应复制、覆盖或删除个人 OAuth 凭据。

## 常见故障

- `nocobase_auth_failed`：调用 `nocobase_login({"force": true})`，让用户在 NocoBase 网页重新授权。
- 浏览器无法启动：把 `nocobase_login` 返回的链接和确认码交给用户手动打开；CLI 的 `setup --no-browser` 仅作备用。
- OAuth 服务暂时不可用：先报告服务状态；只有管理员明确要求时才使用 `setup --manual-key`。
- `nocobase_request_timeout`：检查 NocoBase 可用性或缩小查询。
- `nocobase_request_failed` / `NO_PERMISSIONS`：检查该用户 ACL 和字段/行级权限。
- 凭证文件权限错误：POSIX 下修复为 `0600`，父目录为 `0700`，不要放宽为共享可读。
- OAuth 来源校验错误：检查 `https://justconn.top/api` 的反向代理与发现元数据；不要放宽固定来源保护。