feat: install latest main commit snapshots

2026-08-18 17:32:56 +00:00
parent 4c53f90947
commit c7e62d1d6d
7 changed files with 128 additions and 50 deletions
@@ -6,7 +6,7 @@

 ## 完成标准

- 下载本文件所在的同一固定 Release，不使用默认分支；
+- 从 Gitea `main` 解析安装开始时的最新完整 Commit SHA，并将本次安装的文档、源码和构建全部固定到该 Commit；
 - 只连接固定的 NocoBase API `https://justconn.top/api`；
 - MCP 在用户本机以 stdio 运行，默认只读；
 - 通过 NocoBase 原生 OAuth 2.1 认证当前用户，权限仍跟随本人的业务角色；
@@ -20,28 +20,39 @@
 - OAuth Token 不得进入聊天、命令参数、环境变量、CRM 配置、剪贴板日志或 MCP 客户端配置。
 - 不使用 `sudo`，不执行 `curl | sh` 或 `wget | sh`。
 - 不静默安装 Git、Node.js、包管理器或其他系统工具。
+- 解析 `main` 后只使用带完整 Commit SHA 的不可变 URL；一次安装中不得再次读取移动中的 `main` 文件。
+- 最新 Commit 无法下载、检查、测试或构建时必须停止，不得静默退回旧 Release、旧 Commit 或其他来源。
 - 修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
 - 默认不启用写入、原始数据、后台服务或网络监听。
 - 不询问或接受其他 NocoBase URL，也不允许通过参数、配置或凭证文件覆盖固定 API 地址。

 ## 安装流程

-### 1. 确认本机位置与 Release 权限
+### 1. 解析并固定最新 Commit

 确定当前 Agent/MCP 客户端及其配置路径，以及普通用户应用数据目录。NocoBase API 已固定为 `https://justconn.top/api`，不需要向用户询问地址。

-从本文件 URL 解析固定 Release Tag。读取同一 Release 的资产列表，只接受：
+安装源固定为：

- `donaldttt-nocobase-crm-mcp-<version>.tgz`；
- `SHA256SUMS`。
+- 仓库：`https://git.justconn.top/gitea-admin/nocobase-mcp`
+- 分支：`main`
+- 分支 API：`https://git.justconn.top/api/v1/repos/gitea-admin/nocobase-mcp/branches/main`

-仓库访问受限时，必须使用当前用户已经授权的代码托管平台连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户的访问令牌到聊天。
+通过当前用户已经授权的 Gitea API/连接读取分支 API，只解析一次 `commit.id`，并验证它是 40 位十六进制完整 SHA。记录为 `<commit-sha>` 后，本次安装即使发现 `main` 又有新提交，也继续完成这个已固定快照；下一次安装才重新解析最新提交。
+
+立即从以下不可变地址重新读取安装协议，后续不再依赖最初的 `main` 页面内容：
+
+```text
+https://git.justconn.top/gitea-admin/nocobase-mcp/raw/commit/<commit-sha>/INSTALL.md
+```
+
+仓库访问受限时必须使用当前用户已有的授权连接；无权访问时停止，不得索取或接收用户在聊天中发送的 Gitea 访问令牌。

 ### 2. 一次性说明本机变更

 检查 `node --version` 和 `npm --version`。要求 Node.js `>=20.11`。

-如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。
+如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。还需确认 npm 能读取锁定依赖；不得改用未锁定的依赖版本。

 正常安装只会留下：

@@ -50,25 +61,46 @@
 - 权限受限的本机凭证文件；
 - MCP 客户端配置及其备份。

-不会安装 Git、Python、uv、`nb CLI`、后台服务或本机监听端口。
+源码快照、构建期 `node_modules` 和本地 tarball 只放在新建的临时目录，安装完成后不作为持久文件保留。不会安装 Git、Python、uv、`nb CLI`、后台服务或本机监听端口。

-### 3. 下载并验证固定发布物
+### 3. 下载、验证并构建固定 Commit

-通过当前 Gitea 实例或经批准分发渠道的已授权 API/连接，将两个 Release 资产下载到新建的临时目录。验证 tarball 的 SHA-256 与 `SHA256SUMS` 完全一致；不一致立即停止并删除未使用的下载文件。
+在新建的临时目录中下载 `<commit-sha>` 的源码归档，不下载 Release 资产，也不从移动的 `main` URL 下载源码。Windows 使用 `.zip`，macOS/Linux 使用 `.tar.gz`；两种归档都必须包含同一个已解析的完整 Commit SHA：
+
+```text
+Windows:     https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.zip
+macOS/Linux: https://git.justconn.top/gitea-admin/nocobase-mcp/archive/<commit-sha>.tar.gz
+```
+
+不要让用户选择版本，也不要因为操作系统不同而改用 Release。每次新的安装任务都重新解析当时 `main` 的最新 Commit，随后只下载并使用该 SHA。
+
+下载后记录归档 SHA-256。解包前拒绝绝对路径、`..` 路径穿越或逃出临时目录的链接；源码根目录必须包含 `package.json`、`package-lock.json`、`install-manifest.json`、`INSTALL.md` 和 `src/`。
+
+确认归档中的 `install-manifest.json` 声明 `distribution.branch` 为 `main`、`distribution.strategy` 为 `resolve-latest-commit-then-pin`。随后只在这个临时源码目录运行：
+
+```bash
+npm ci
+npm run check
+npm test
+npm run build
+npm pack --pack-destination <temporary-output-directory>
+```
+
+任何一步失败都停止并报告 `<commit-sha>` 与失败步骤，不得改装旧 Release。记录本地生成 npm tarball 的 SHA-256；安装结束时只报告哈希，不发送或上传 tarball。

 选择用户级安装前缀，例如：

- Windows：`%LOCALAPPDATA%\NocoBaseMCP\app`
- macOS：`~/Library/Application Support/NocoBaseMCP/app`
+- Windows：`%LOCALAPPDATA%\nocobase-crm-mcp\app`
+- macOS：`~/Library/Application Support/nocobase-crm-mcp/app`
 - Linux：`${XDG_DATA_HOME:-~/.local/share}/nocobase-crm-mcp/app`

 执行隔离安装，不使用全局目录：

 ```bash
-npm install --prefix <install-prefix> --omit=dev <verified-release.tgz>
+npm install --prefix <install-prefix> --omit=dev <locally-built-commit.tgz>
 ```

-定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。
+定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。运行 `--version` 和 `--help`，确认版本等于源码 `package.json`，并且帮助中包含本 Commit 安装协议使用的 `setup --no-browser` 选项；不一致时停止，不得继续注册旧二进制。

 ### 4. 浏览器登录 NocoBase

@@ -88,6 +120,8 @@ npm install --prefix <install-prefix> --omit=dev <verified-release.tgz>

 然后由用户手动打开链接。设备授权约十分钟后失效；密码和浏览器会话始终留在 NocoBase，安装程序不会读取浏览器 Cookie。访问令牌临近过期时会自动使用刷新令牌续期，不影响日常 MCP 调用。

+在 Hermes Agent、OpenClaw 或其他远程无界面环境中，Agent 应在可持续读取输出的后台会话运行 `setup --no-browser --json`，取得授权链接和确认码后立即通过当前消息通道发给用户，同时让进程继续轮询。只能转发 HTTPS 授权链接、用户确认码和有效期，绝不能转发 OAuth Token、设备码或凭据文件内容。一个 MCP 进程只能服务一个受信任的用户身份；多用户必须使用相互隔离的 Agent/MCP 实例和凭据路径。
+
 POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当前用户应用数据目录。凭证文件不保存或接受 API 地址，Token 不会出现在返回 JSON、命令参数、MCP 配置或日志中。不要复制其他用户的凭证文件；每个操作系统用户都必须单独登录。

 只有在 OAuth 暂时不可用、管理员明确要求且用户拥有个人 Authorize Key 时，才使用：
@@ -108,7 +142,7 @@ POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当
 4. 重载或重启 MCP 客户端；
 5. 调用 `crm_health`，要求 `ok=true`。

-最终只报告 Release、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。
+最终只报告完整 Commit SHA、源码版本、本地构建 tarball 的 SHA-256、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。

 ## 可选写入

@@ -121,11 +155,13 @@ POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当
 - `nocobase_auth_failed`：重新运行 `setup` 完成浏览器登录；不要换用共享高权限 Token 或 Key。
 - `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限身份。
 - Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
- 受限 Release 无权访问：报告 Gitea 或分发渠道的权限问题，不退回 clone 默认分支。
+- `main` 或 Commit 归档无权访问：报告 Gitea 权限问题，不索取聊天中的访问令牌，也不退回旧 Release。
+- 最新 Commit 的依赖安装、检查、测试或构建失败：报告 SHA 和原始失败步骤后停止；不得以“先装可用版本”为由降级。
+- 安装过程中 `main` 更新：不影响当前任务，继续完成开始时固定的 SHA；下次安装再取得新 SHA。

 ## 用户可发送给 Agent 的最短指令

 ```text
-请按这个固定 Release 的协议帮我完成本机安装。默认只读；请运行 setup，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
-<固定 Release 的 INSTALL.md 链接>
+请按这个 INSTALL.md 帮我完成安装。每次先解析当前 Gitea 仓库 main 分支的最新完整 Commit SHA，并把本次安装固定在该 Commit；不要退回旧 Release。默认只读；请运行 setup，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
+https://git.justconn.top/gitea-admin/nocobase-mcp/raw/branch/main/INSTALL.md
 ```