feat: migrate MCP runtime to TypeScript

INSTALL.md

@@ -1,97 +1,117 @@
 # 安装 NocoBase CRM MCP
 
-这是一份供终端型 AI Agent 执行的通用安装协议，不依赖 Codex、Claude Code、Cursor、OpenCode 或其他特定产品。用户只需要提供本链接、确认一次本机变更，并在隐藏提示中输入自己的 NocoBase API Key。
+这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在隐藏提示中输入自己的 NocoBase Authorize Key。
 
-如果你是安装 Agent，请直接完成下面的流程，不要把命令转交给用户逐条尝试。只有在需要用户确认安装内容、提供 NocoBase 地址或在隐藏提示中粘贴 Key 时才打断用户。
+如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更、取得 NocoBase URL、要求用户创建 Key，或让用户在隐藏提示中粘贴 Key 时才中断用户。
 
-## 完成目标
+## 完成标准
 
-安装完成时必须同时满足：
-
-- 使用固定 Release `v0.2.0`，不是开发分支；
+- 下载本文件所在的同一固定 Release，不使用默认分支；
 - MCP 在用户本机以 stdio 运行，默认只读；
-- NocoBase 认证属于当前用户自己的个人 Key 和业务角色；
+- 认证属于当前用户自己的个人 Authorize Key 和业务角色；
 - 当前 MCP 客户端已注册 `nocobase-crm`；
 - `crm_health` 返回 `ok=true`。
 
-## 不可违反的安全规则
+## 安全规则
 
 - 不索取账号密码，不使用共享服务账号或管理员 Key。
-- 不让用户把 Key 发到聊天、命令参数、环境变量或临时文件。
-- Key 只能由用户粘贴到 `nb` CLI 的本机隐藏 TTY 提示。
-- 不使用 `sudo`，不执行 `curl | sh` / `wget | sh`。
-- 写 MCP 客户端配置前必须展示目标路径、创建备份并结构化合并，不能覆盖其他 server。
-- 除非用户明确要求且管理员已确认 ACL，否则不启用写入、上传或原始数据。
-- 默认不创建后台服务、不监听端口、不暴露到局域网或公网。
+- 不让用户把 Key 发到聊天、命令参数、环境变量、剪贴板日志或 MCP 配置。
+- Key 只能由用户输入到安装程序的本机隐藏 TTY 提示。
+- 不使用 `sudo`，不执行 `curl | sh` 或 `wget | sh`。
+- 不静默安装 Git、Node.js、包管理器或其他系统工具。
+- 修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
+- 默认不启用写入、原始数据、后台服务或网络监听。
 
-## 一次安装流程
+## 安装流程
 
-### 1. 确认输入和访问权限
+### 1. 确认输入与 Release 权限
 
-从用户或上下文取得：
+取得：
 
 - NocoBase 应用 URL，例如 `https://nocobase.example`；
-- 普通用户安装目录；
-- 当前 Agent/MCP 客户端及其配置路径。
+- 当前 Agent/MCP 客户端及其配置路径；
+- 普通用户应用数据目录。
 
-本项目暂时通过 Private GitHub 仓库分发。当前 Agent 必须已经连接一个对 `Donaldttt/nocobase-mcp` 有只读权限的 GitHub 账号；无权读取时停止，不得退回 `master`。
+从本文件 URL 解析固定 Release Tag。读取同一 Release 的资产列表，只接受：
+
+- `donaldttt-nocobase-crm-mcp-<version>.tgz`；
+- `SHA256SUMS`。
+
+仓库为 Private 时，必须使用当前用户已经授权的 GitHub 连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户 GitHub Token 到聊天。
 
 ### 2. 一次性说明本机变更
 
-检查 Git、uv、Python 3.12+ 和 NocoBase `nb` CLI 2.1+。若缺失，向用户一次性说明将安装的工具、官方来源和位置，并取得一次确认后再处理。只有缺少 `nb` 时才可能额外需要 Node.js/npm；官方 CLI 包为 `@nocobase/cli`。
+检查 `node --version` 和 `npm --version`。要求 Node.js `>=20.11`。
 
-用户安装会留下：固定版本仓库副本、项目 `.venv`、不含 Key 的 `config.json`、`nb` CLI 用户登录环境、MCP 客户端配置和配置备份。不会默认创建 systemd 服务或 HTTP Token。
+如果 Node.js 缺失或版本过低，向用户说明需要安装或升级 Node.js、官方来源、目标位置和影响，取得明确同意后再使用操作系统的正规安装方式。不能因为 npm 不存在就直接尝试全局安装。
 
-### 3. 取得固定版本
+正常安装只会留下：
 
-安全克隆并验证 Release：
+- 应用数据目录中的 npm 包；
+- 不含 Key 的 CRM `config.json`；
+- 权限受限的本机凭证文件；
+- MCP 客户端配置及其备份。
+
+不会安装 Git、Python、uv、`nb CLI`、后台服务或本机监听端口。
+
+### 3. 下载并验证固定发布物
+
+通过已授权的 GitHub API/连接下载两个 Release 资产到新建的临时目录。验证 tarball 的 SHA-256 与 `SHA256SUMS` 完全一致；不一致立即停止并删除未使用的下载文件。
+
+选择用户级安装前缀，例如：
+
+- Windows：`%LOCALAPPDATA%\NocoBaseMCP\app`
+- macOS：`~/Library/Application Support/NocoBaseMCP/app`
+- Linux：`${XDG_DATA_HOME:-~/.local/share}/nocobase-crm-mcp/app`
+
+执行隔离安装，不使用全局目录：
 
 ```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
+npm install --prefix <install-prefix> --omit=dev <verified-release.tgz>
 ```
 
-第二条必须精确输出 `v0.2.0`。目标目录已存在但不是本项目、包含未提交修改或版本不明确时停止覆盖。
+定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。
 
-### 4. 只运行一个安装命令
+### 4. 个人 Key 设置
 
-先引导用户在 NocoBase 个人设置中创建一个可撤销、有合理有效期、绑定本人普通业务角色的个人 API Key。不要让用户把 Key 发给你。
+先引导用户在 NocoBase 个人设置中创建可撤销、有合理有效期、绑定本人普通业务角色的个人 Authorize Key。不要让用户把 Key 发给 Agent。
 
-然后在用户可直接控制输入的本机终端中运行：
+在用户可直接控制的本机终端运行：
 
 ```bash
-uv run --no-project --python 3.12 python <install-dir>/scripts/agent_install.py \
-  --project-root <install-dir> install \
-  --api-base-url <nocobase-url> --env-name nb-mcp --json
+<installed-command> setup --api-base-url <nocobase-url> --json
 ```
 
-这个命令会一次完成运行环境准备、隐藏 Key 登录、配置写入、doctor 检查和通用 MCP 客户端配置生成。用户只在 `nb` 的隐藏提示出现时粘贴 Key；Agent 不读取输入。
+安装程序会先验证安全 TTY，再显示隐藏 Key 提示；没有安全 TTY 时会在写文件前停止。Key 通过 `roles:check` 验证成功后才保存，并立即执行 `crm_health`。Key 不会出现在返回 JSON、命令参数、MCP 配置或日志中。
 
-若终端不支持用户私密输入，命令会在写入前停止。此时报告缺少安全 TTY，不得让用户改为在聊天中发送 Key。
+POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当前用户应用数据目录。不要复制其他用户的凭证文件；每个操作系统用户都必须单独设置自己的 Key。
 
-### 5. 自动完成客户端注册和验证
+### 5. 注册并验证 MCP
 
-读取命令返回的 `clientConfig`：
+读取 setup 返回的 `clientConfig`：
 
-1. 展示当前客户端配置文件路径和将新增的 `nocobase-crm` 条目；
+1. 展示客户端配置路径和新增的 `nocobase-crm` 条目；
 2. 创建可恢复备份；
 3. 结构化合并该 server，保留所有其他配置；
-4. 按客户端能力重载配置或重启客户端；
+4. 重载或重启 MCP 客户端；
 5. 调用 `crm_health`，要求 `ok=true`。
 
-只有完成以上验证后才能向用户报告成功。最终只报告安装目录、Release、NocoBase 环境名、客户端配置备份位置和启用模式，不显示任何 Token。
+最终只报告 Release、安装目录、配置备份位置和只读/写入模式，不显示任何 Key。
 
-## 默认模式与可选写入
+## 可选写入
 
-未明确选择时必须保持只读。只有用户明确要求项目创建/更新，且管理员确认该用户角色具有相应 NocoBase ACL 时，才在同一个安装命令末尾加 `--enable-writes`。这仍不会启用附件上传、删除或原始数据。
+未明确选择时保持只读。只有用户明确要求项目创建/更新，并且管理员确认该用户角色具有对应 NocoBase ACL 时，才在 setup 以及生成的启动参数中加入 `--enable-writes`。这只增加 `create_project` 和 `update_project`；不增加删除、任意集合访问或附件文件上传接口。
 
 ## 故障处理
 
-不要让普通用户手动尝试 `nb` 或拆分安装子命令。由 Agent 根据结构化错误处理；需要详细恢复、更新或高级 HTTP 部署时，阅读同版本的 [`docs/LOCAL_DELIVERY.md`](docs/LOCAL_DELIVERY.md)。Key 过期或撤销时，重新运行同一个 `install` 命令，让用户在新的隐藏提示中输入新 Key。
+- `nocobase_auth_failed`：让用户撤销失效 Key，重新运行同一个 setup 命令并在隐藏提示输入新 Key。
+- `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限 Key。
+- Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
+- Private Release 无权访问：报告分发权限问题，不退回 clone 默认分支。
 
 ## 用户可发送给 Agent 的最短指令
 
 ```text
-请按这个协议帮我完成本机安装。默认只读，使用我自己的 NocoBase API Key；只让我在本机隐藏提示中输入 Key，不要让我手动执行安装或 nb 命令。安装完成前必须验证 crm_health：
-<固定版本 INSTALL.md 链接>
+请按这个固定 Release 的协议帮我完成本机安装。默认只读，使用我自己的 NocoBase Authorize Key；只让我在本机隐藏提示中输入 Key，不要静默安装系统工具。完成前必须验证 crm_health：
+<固定 Release 的 INSTALL.md 链接>
 ```