feat: migrate MCP runtime to TypeScript

docs/LOCAL_DELIVERY.md

@@ -1,164 +1,56 @@
-# 本机交付与登录手册
+# 本机交付与权限验收
 
 ## 交付模型
 
-每位用户在自己的电脑运行 MCP，并使用绑定本人普通业务身份/角色的个人 API Key 登录 `nb` CLI：
+每位用户在自己的电脑运行 MCP，并使用绑定本人业务身份的个人 Authorize Key：
 
 ```text
-本机 AI 客户端 → 本机 NocoBase CRM MCP → 本机 nb CLI 登录态 → 远程 NocoBase ACL
+本机 AI 客户端 → 本机 TypeScript MCP → 远程 NocoBase API → 本人 ACL
 ```
 
-MCP 不保存公共业务账号，也不需要部署一个多人共用的远程 MCP 服务。NocoBase 仍是最终权限裁决者；同一个工具由不同用户调用时，只能返回或修改其账号 ACL 允许的数据。
+项目不保存共享业务账号，也不需要多人共用的远程 MCP 服务。
 
-## 环境要求
+## Release 发布物
 
-- Python 3.12 或更高版本
-- Git（仅安装、版本校验和更新）
-- `uv`
-- NocoBase `nb` CLI 2.1 或更高版本
-- Node.js/npm（仅在尚未安装 `nb` 时用于安装官方 CLI）
-- 可通过浏览器访问目标 NocoBase
-- 管理员已为用户配置所需的 NocoBase 角色与数据权限
+Release workflow 会在带版本 Tag 时执行锁定安装、类型/格式检查、测试、bundle、npm pack 和生产依赖审计，并上传：
 
-## 推荐：链接驱动的 Agent 安装
+- npm tarball；
+- `SHA256SUMS`。
 
-正式发布后，优先把对应 Release Tag 下的 [`INSTALL.md`](../INSTALL.md) 不可变链接交给用户。该入口不是 Codex 专用插件：任何能够读取链接、执行本机终端并结构化修改 MCP 客户端配置的 Agent，都可以按协议完成安装。确定性工作由 `scripts/agent_install.py` 处理；Agent 负责识别操作系统与客户端、解释变更、备份并合并客户端配置；用户只在 NocoBase 获取个人 Key，并把它粘贴到本机隐藏提示。
+源码仓库保持 Private 时，外部用户必须具有 Release 下载权限，或通过另一个经过身份认证的分发渠道取得相同资产。Private GitHub 链接本身不能成为任意用户可访问的一键安装链接。
 
-发布方必须保证安装 Agent 能读取链接和相同版本的代码。当前仓库为 private 时，用户需要已经连接有仓库权限的 GitHub 账号；面向普通外部用户的一条链接安装，则必须公开该版本的 `INSTALL.md` 与发布物，或放到用户 Agent 可认证访问的分发渠道。不要把开发分支链接当作交付链接。
+## 用户电脑上的内容
 
-这个通用流程默认使用 stdio，因此不需要后台服务或本机 MCP Bearer Token。Linux systemd/HTTP 方式只用于确有附件上传需求的高级场景。
+- Node.js 20.11+（唯一系统运行时）；
+- 用户应用数据目录中的打包 MCP；
+- CRM 映射配置；
+- 当前 OS 用户的私有凭证文件；
+- MCP 客户端配置和备份。
 
-## 首次安装与统一引导
-
-```bash
-git clone --branch v0.2.0 --depth 1 https://github.com/Donaldttt/nocobase-mcp.git
-cd nocobase-mcp
-```
-
-正式终端用户不应手动尝试依赖同步或 `nb env add/auth`。安装 Agent 在用户可直接控制的本机终端中只运行统一安装命令：
-
-```bash
-uv run --no-project --python 3.12 python scripts/agent_install.py \
-  --project-root . install --api-base-url https://nocobase.example --env-name nb-mcp --json
-```
-
-该命令依次准备运行环境、连接个人 Key、运行 doctor，并返回通用 `clientConfig`。Agent 先引导用户在 NocoBase 个人设置中创建可撤销、有合理有效期、绑定本人普通业务角色的 API Key。用户只把 Key 粘贴到 `nb` CLI 的隐藏 TTY 提示；脚本不接收或回显 Key，也不会把它放入命令参数、聊天、环境变量、临时文件或 MCP 配置。不要分发共享管理员 Key，也不要复制其他人的 `nb` 配置目录。
-
-先进行健康检查：
-
-```bash
-.venv/bin/python -m nocobase_crm_mcp.server --config config.json
-```
-
-然后让 MCP 客户端调用 `crm_health`。如果返回 `nb_auth_failed`，由 Agent 重新启动 `connect-key`，用户在新的本机隐藏提示中输入新 Key；不要让用户手动尝试 `nb` 命令。
-
-## MCP 客户端配置
-
-推荐使用 stdio。把绝对路径替换成用户电脑上的实际安装目录：
-
-```json
-{
-  "mcpServers": {
-    "nocobase-crm": {
-      "command": "/absolute/path/to/nocobase-mcp/.venv/bin/python",
-      "args": [
-        "-m",
-        "nocobase_crm_mcp.server",
-        "--config",
-        "/absolute/path/to/nocobase-mcp/config.json"
-      ],
-      "env": {
-        "NOCOBASE_MCP_NB_BIN": "/absolute/path/to/nb"
-      }
-    }
-  }
-}
-```
-
-不要手写猜测虚拟环境路径；优先使用统一 `install` 结果中的 `clientConfig`。上例是 POSIX 路径，Windows 输出会自动使用 `.venv\\Scripts\\python.exe`。`inspect`、`prepare`、`connect-key`、`client-config` 和 `doctor` 子命令仅为排障和旧流程兼容保留，不应让普通用户逐条运行。
-
-默认只读。如需项目创建和更新，在参数末尾加入 `--enable-writes`。这些写工具只允许预先定义的项目字段，不提供删除或任意资源访问能力。
-
-附件上传需要可选的本机 HTTP 模式。HTTP 服务默认只监听 `127.0.0.1:10087`；上传路由本身也默认关闭，不得暴露到局域网或公网：
-
-```bash
-NOCOBASE_MCP_TOKEN='<随机长字符串>' \
-NOCOBASE_MCP_ENABLE_UPLOADS=0 \
-  uv run nocobase-crm-mcp --transport streamable-http --config config.json
-```
-
-Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级 systemd 服务。
-
-只有管理员确认该用户角色拥有 `t_projects` 的 create 或 update 后，才能在 `.runtime/nocobase-crm-mcp.env` 中设置 `NOCOBASE_MCP_ENABLE_UPLOADS=1` 并重新执行 `bash scripts/mcp_service.sh start`。即使已显式启用，MCP 仍会在每次上传前调用当前账号的 `roles:check`；无项目写权限时返回 `403 / nb_upload_forbidden`，不会调用 `attachments:create`。
+不需要 Git、Python、uv、`nb CLI` 或项目源码 checkout。npm 只在隔离前缀安装一个已经 bundle 的包，运行时没有额外 npm 依赖。
 
 ## 权限验收
 
-交付前至少使用两个权限不同的测试账号验证：
+至少使用两个权限不同的真实测试账号：
 
-1. 两台电脑或两个隔离的操作系统账号分别通过 Agent 的 `connect-key` 流程录入各自个人 Key。
-2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups` 和 `list_projects`。
-3. 确认各自只能看到 NocoBase UI 中本人有权查看的数据。
-4. 对无项目写权限的账号调用 `create_project`，确认 NocoBase 拒绝。
-5. 显式启用上传后，对无项目写权限的账号上传一个小文件，确认返回 `nb_upload_forbidden`，并用管理员确认附件记录数没有增加。
-6. 对有写权限的账号创建测试项目并完成上传、关联和移除，确认审计字段记录的是该用户，而不是共享服务账号。
-7. 退出或使 Token 过期后，确认 MCP 返回 `nb_auth_failed`，且不会降级使用其他凭证。
+1. 分别签发个人 Key，并在隔离的 OS 用户/凭证路径运行 setup。
+2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups`、`list_projects`。
+3. 确认返回范围与各自在 NocoBase UI 中的 ACL 一致。
+4. 无项目写权限账号在 `--enable-writes` 下调用 `create_project`，确认 NocoBase 拒绝。
+5. 有权限账号创建和更新测试项目，确认审计身份属于该用户。
+6. 撤销 Key 后确认 MCP 返回 `nocobase_auth_failed`，且不会降级使用其他凭证。
+7. 检查错误与日志，确认没有 Key、Authorization header 或业务原始行泄漏。
 
-修改测试账号角色后，如果 `roles:check` 仍返回旧角色，先由管理员清理服务端角色缓存，再由 Agent 使用新签发的个人 Key 重新运行 `connect-key`。不应通过共享 Token 绕过。
+## 更新与回滚
 
-## 凭证安全
+Agent 下载新的固定 Release tarball并验证 SHA-256，再对同一隔离前缀运行 `npm install --prefix ... --omit=dev <tarball>`。安装前备份 MCP 客户端配置和非秘密 CRM 配置。
 
-- 个人 API Key 由 `nb` CLI 保存，不能写入 `config.json`、MCP 客户端配置、聊天、Shell 历史或命令参数。
-- MCP 获取附件请求凭证时，Token 只存在于进程内存，不进入子进程参数和错误日志。
-- `.runtime/` 只保存本机 HTTP MCP 的独立 Bearer Token，并已被 Git 忽略。
-- 不要共享操作系统账号运行 MCP；本机权限隔离依赖每位用户拥有独立的 `nb` 登录存储。
-- `NOCOBASE_MCP_API_TOKEN` 只为旧部署兼容保留，不用于终端用户交付。
-- `include_raw=true` 默认被 MCP 拒绝。只有在管理员审核 `config.json` 字段和 AI 数据使用政策后，才可在该用户本机设置 `NOCOBASE_MCP_ENABLE_RAW_DATA=1`。
-- `POST /uploads` 默认不存在。只有在管理员完成角色验收后才设置 `NOCOBASE_MCP_ENABLE_UPLOADS=1`；MCP 的项目写权限门禁是纵深防御，NocoBase ACL 仍是最终权限边界。
-
-## 更新、回滚与恢复
-
-更新前记录当前版本，更新后重新同步锁定依赖并运行测试：
-
-```bash
-git rev-parse HEAD
-git pull --ff-only
-uv sync --locked --no-dev
-.venv/bin/python -m unittest discover -s tests
-```
-
-使用 systemd 本机 HTTP 服务时，再执行：
-
-```bash
-bash scripts/mcp_service.sh start
-bash scripts/mcp_service.sh status
-journalctl --user -u nocobase-crm-mcp.service -n 200 --no-pager
-```
-
-如果新版本验收失败，切回上一步记录的已发布 Tag 或 Commit，然后重新同步并启动：
-
-```bash
-git switch --detach <previous-release-tag-or-commit>
-uv sync --locked --no-dev
-bash scripts/mcp_service.sh start
-```
-
-发布交付必须来自工作区干净、CI 全绿的带注释 Git Tag；不要从开发分支任意提交直接打包给用户。
-
-需要备份的业务配置是 `config.json`。它不应包含 Token，可以进入受控版本库或企业配置备份。`.runtime/nocobase-crm-mcp.env` 只包含本机 HTTP Token 和运行参数；丢失后运行 `bash scripts/mcp_service.sh new-token` 重新生成即可。不要备份、复制或分发用户的个人 Key；恢复电脑后重新签发 Key，并由 Agent 运行 `connect-key`。
-
-建议监控：
-
-- MCP 客户端定期调用 `crm_health`。
-- 本机 HTTP 用户执行 `bash scripts/mcp_service.sh status`，确认 systemd active 且 HTTP probe reachable。
-- 日志只检查错误码和命令退出状态；发现业务原始数据或 Token 时立即停止交付并按安全事件处理。
+回滚时重新安装上一固定 Release 的已验证 tarball。凭证文件与 CRM 配置位于包目录之外，更新和回滚不应复制、覆盖或删除个人 Key。
 
 ## 常见故障
 
-常见故障：
-
-- `nb_not_found`：确认 `nb` 在 PATH 中，或设置 `NOCOBASE_MCP_NB_BIN` 为绝对路径。
-- `nb_auth_failed`：由 Agent 重启 `connect-key`，用户只在本机隐藏提示中输入新 Key。
-- `NO_PERMISSIONS`：由 NocoBase 管理员调整该用户的角色、字段或行级数据权限。
-- 附件返回 `nb_upload_unauthorized`：重新登录后重试；不要把其他用户的 Token 写入环境变量。
-- 附件返回 `nb_upload_forbidden`：当前角色没有项目 create/update；不要为了绕过门禁而改用共享高权限账号。
-- 环境连接错误：执行 `nb env info nb-mcp`，确认 `apiBaseUrl` 指向目标环境的 `/api`。
+- `nocobase_auth_failed`：重新运行 setup，让用户在隐藏提示输入新签发 Key。
+- `nocobase_request_timeout`：检查 NocoBase 可用性或缩小查询。
+- `nocobase_request_failed` / `NO_PERMISSIONS`：检查该用户 ACL 和字段/行级权限。
+- 凭证文件权限错误：POSIX 下修复为 `0600`，父目录为 `0700`，不要放宽为共享可读。
+- 跨源重定向错误：修正 NocoBase API URL或代理配置；不要关闭同源保护。