codebuddy-ide-mcp-upgrade

# codebuddy-ide-mcp-upgrade ## When to use - 需要把 CloudBase MCP 新版本推进 CodeBuddy IDE 的内置集成 - 线上反馈「IDE 里集成的 CloudBase 功能不足」（大概率是白名单过期，不是 MCP 能力不够） - 需要修改 IDE 内置的 `toolWhiteList` / `systemPrompt` / `attatchPrompt` - 需要定位「IDE 里的 MCP 到底装的哪个版本、能用哪些工具」 ## 集成结构（先读，别猜） CodeBuddy IDE 的内置 CloudBase MCP 由 **genie 扩展**承载，改一处不生效，**必须同时改两个文件**： | 文件 | 内容 | 等价来源 | | --- | --- | --- | | `Contents/Resources/app/extensions/genie/integration-mcp/tcb/index.cjs` | MCP Server bundle | 仓库 `mcp/dist/cli.cjs` 改名 | | `Contents/Resources/app/extensions/genie/out/extension/index.js` | 内嵌的 tcb 集成配置（webpack module，`ir.exports=JSON.parse('{...}')`） | 无仓库对版，需就地解包 | 默认 IDE 路径：`/Applications/CodeBuddy CN.app`。同目录还有 `anydev`、`eop`、`lighthouse` 三个集成，别改错。 加载与启动契约： ```js // TcbIntegration mcpServer: { path: path.join("integration-mcp", "tcb", "index.cjs"), envMapper: (r) => ({ TENCENTCLOUD_SECRETID: r.tmp_secret_id, TENCENTCLOUD_SECRETKEY: r.tmp_secret_key, TENCENTCLOUD_SESSIONTOKEN: r.token }), toolWhiteList: config.toolWhiteList, } // StdioClientTransport { command: process.execPath, args: [mcpPath], env: { ...envMapper(), INTEGRATION_IDE: "CodeBuddy", ELECTRON_RUN_AS_NODE: "1", WORKSPACE_FOLDER_PATHS } } ``` **不传任何命令行参数**（`--cloud-mode` / `--integration-ide` 都没用），凭据全靠环境变量，MCP 侧 `mcp/src/auth.ts` 直接读 `TENCENTCLOUD_SECRETID/SECRETKEY`。 ## Steps ### 1. 解包拿到线上基线（第一步必做） 配置内嵌在 21MB 的 `out/extension/index.js` 里，用 `JSON.parse('...')` 包着，**必须按 JS 字符串语义 eval 才能解析**： ```js const i = s.indexOf('"id":"tcb"'); const st = s.lastIndexOf("JSON.parse('", i) + 12; let cursor = st, cfg; for (;;) { cursor = s.indexOf("')", cursor + 1); try { cfg = JSON.parse(eval("'" + s.slice(st, cursor) + "'")); break; } catch {} } ``` 拿到后先数一遍白名单，并和仓库 `scripts/tools.json` 比对。**九成问题出在这里**：白名单停留在旧版本，里面全是已被 MCP 改名的死条目。 ### 2. 构建新 bundle ```bash cd <repo>/mcp && npm run build:webpack # 产物 dist/cli.cjs，约 4.6 MiB ``` 只跑 `build:webpack`，不要跑 `npm run build`（会触发 `prebuild` 的 `rm -rf dist`，可能被 safe-delete hook 拦截）。 ### 3. 生成新配置 白名单真源是 `scripts/tools.json`，**不要手写清单**。配置改动落在： - `toolWhiteList` ← `tools.json` 全部工具名（**全量，不要裁剪**，理由见「白名单裁剪的前提已不存在」） - `systemPrompt.login` / `.logout`、`userPrompt.*`、`attatchPrompt.*` ← 提示词 - 其余字段（`id`、`displayName`、`description`、`descriptionMap`、`types`、`ruleZipUrl`、`loginOnlyChinese`、`loginType`、`toolTimeout`）**保持原值** ### 3.1 写提示词前必须知道的两件事 **（1）PG 模式 = Supabase 同构，不是「多了一种数据库」** 判定为 PG 环境后，认证、存储、权限、迁移**四项全部改道**： | 能力层 | Supabase | CloudBase PG 模式 | 工具 | | --- | --- | --- | --- | | 数据库 | Postgres | PostgreSQL | `queryPgDatabase` / `managePgDatabase` | | Schema 变更 | Migration | `applyMigration`（须带 `migrationVersion`） | `managePgDatabase` | | 行级授权 | RLS Policies | RLS | `managePgDatabase` + `rls-patterns.md` | | 存储 | Storage Buckets | **pgstore（与 legacy COS 是两套系统）** | `queryPgStorage`（不是 `queryStorage`） | | 认证 | anon/service key | 应用认证（publishable key / API key） | `queryAppAuth` / `manageAppAuth` | **PG 环境里引导错路径（用 NoSQL/MySQL 工具，或用 `queryStorage` 而非 `queryPgStorage`）是最高频的跑偏方式。** **（2）提示词看配重，不看总长** - **总长不是问题**：`systemPrompt.login` 约 10.6k 字符 ≈ 3.5k token，在 Tool Search + 长上下文下不构成负担。为「看起来短」删引导 = 丢掉关键分叉点的判断质量。 - **要看常量 vs 变量的配比**。实测一次改版的占比： - 静态索引（rule 文件路径清单 + 控制台 URL 清单）占 **28.8%**，但模型随时可查、规则文件里本来就有完整版（提示词自己都写着 "see platform rule for full list"）； - 真正决定走向的分支变量（如 PG 主线）只占 **6.6%**，且散落在互不相邻的章节，需要模型自行拼接 —— 这是「提示词写了但模型没照做」的典型成因。 - **改法**： 1. 下沉常量索引（可省 ~23%），腾出的空间上提变量主线； 2. 分支判定后**紧跟一张「改道表」**，把散落约束收敛成一处； 3. 「三选一」式的并列列表，若各分支会改变后续多项决策，应改写成「两条主线」各自自包含。 改完提示词用这个脚本量化配重，别靠感觉： ```bash node -e ' const s=require("fs").readFileSync("config/prompts/systemPrompt.login.md","utf8"),L=s.split("\n"); let c="(开头)",a={[c]:0},o=[c]; for(const l of L){if(/^## /.test(l)){c=l.slice(3);if(!(c in a)){a[c]=0;o.push(c)}continue} if(/^### /.test(l)){c=l.slice(4);if(!(c in a)){a[c]=0;o.push(c)}continue}a[c]+=l.length+1} for(const k of o)console.log(String(a[k]).padStart(6),(a[k]/s.length*100).toFixed(1).padStart(5)+"% ",k.slice(0,50))' ``` ### 4. 注入 IDE（先 dry-run） ```bash node scripts/apply-to-ide.mjs --dry-run # 只看差异 node scripts/apply-to-ide.mjs # 备份到 backup/<时间戳>/ 后写入 node scripts/patch-tool-timeout.mjs --timeout 300000 # 接通 toolTimeout（见 Pitfalls） ``` 写配置的替换逻辑：生成**紧凑 JSON**（`JSON.stringify(cfg)`，无裸换行），再按 JS 单引号字符串转义（先 `\\` 再 `'`），替换 `JSON.parse('...')` 区间。转义顺序错了会破坏 JS 字符串。 **边界语义（踩过坑，勿改错）**：`start` = raw 起点（`slice(0, start)` 里**已包含** `JSON.parse('`），`end` = `')` 之后。所以替换时**只能拼 escaped raw + `')`，绝不能再拼一次 `JSON.parse('`**。 ### 5. 验证 ```bash node scripts/verify-ide-config.mjs # 从 IDE 回读配置，逐字段比对 node scripts/verify-bundle.mjs # 按 IDE 方式启动 bundle，拉 tools/list ``` `verify-bundle.mjs` 复刻 IDE 的启动参数（stdio + `INTEGRATION_IDE=CodeBuddy` + `ELECTRON_RUN_AS_NODE=1` + 临时密钥占位值），比对三件事：暴露的工具是否全在白名单内、白名单是否有悬空条目、PG 工具是否注册。 ### 6. 回滚 ```bash node scripts/rollback-ide.mjs --latest ``` ## MCP 发版时的强制同步项（防漂移） **白名单漂移是「IDE 里 CloudBase 功能不足」的唯一根因**，不是 MCP 能力问题。线上实测：21 条白名单里 12 条是已被 MCP 删除或改名的死条目，用户实际只能用 9 个。 因此 **MCP 每次发版（工具增删改名）都必须重新生成 IDE 侧白名单**，否则新版本 MCP 发得再勤，IDE 里还是老的。 **发版 checklist：** 1. `scripts/tools.json` 是否已更新（工具清单真源） 2. 用 `scripts/build-config.mjs` 重新生成 IDE 配置，产出新 `toolWhiteList` 3. 检查**新增/改名**的工具是否在提示词里有对应引导 —— 提示词里引用已删除的工具名会导致模型调用不存在的工具 4. 把新配置同步给 IDE 侧（或直接执行本 skill 的 Steps 打进本机 IDE 验证） 5. 在交付文档里记录「本次新增了哪些工具」，便于 IDE 侧理解变更 **建议把这个 checklist 挂到 MCP 发版流程里（release workflow 或发版 checklist 文档），不要靠人工记忆。** 靠人记的后果就是这次的 12 条死条目。 ### 白名单裁剪的前提已不存在 - **CodeBuddy 已支持 Tool Search**：MCP 工具按需检索，不再全量塞进上下文；MCP server 配置层也支持 `defer_loading`。 - **当初给 tcb 加 `toolWhiteList` 的唯一理由就是省上下文，这个前提现在没了。** - 结论：白名单回归「安全边界」单一职责，按 `tools.json` **全量生成**。继续裁剪的唯一后果就是随 MCP 发版漂移成死条目。 - ⚠️ 判断「IDE 是否支持 Tool Search」时**不要 grep genie 的 `out/extension/index.js`** —— 那里搜不到 `ToolSearch` 字符串（实测 0 命中）。Tool Search 属 Agent CLI 内核层，证据在 CLI 进程参数（`--tools` 白名单含 `ToolSearch`）和 mcp-config 的 `defer_loading` 里。 ## Pitfalls - **白名单过滤在 IDE 侧，不在 bundle 内。** 只换 bundle 不换白名单 = 新工具被静默过滤，用户侧零变化。这是最容易踩的坑。 - **写入后必须完全退出并重启 IDE** 才生效，运行中的进程已把旧 bundle 加载进内存。 - 解包时配置字符串里可能含 `')` 序列，必须用「eval + JSON.parse 能否成功」来判断结束位置，不能用第一个 `')`。 - **定位 tcb 块必须用 `"id":"tcb"` 做锚点。** 全文 `toolWhiteList` 出现 13 次，用 `toolWhiteList` 搜会抓到 eop（EdgeOne）的配置块——症状是解出来的 raw 只有 1,015 字符（正常应 ~16,000）。 - 插件类工具（如 `msg-push`）不在 `DEFAULT_PLUGINS` 里，白名单写了也不会注册，需注入 `CLOUDBASE_MCP_PLUGINS_ENABLED=msg-push`。白名单 40 条、实际暴露 38 条是**正常现象**，不是 bug。 ### ⚠️ 头号陷阱：JSON 回读全绿 ≠ 文件可用 曾发生的事故：替换时重复拼接 `JSON.parse('` 前缀，生成 `JSON.parse('JSON.parse('{...}')`，第二个 `'` 提前闭合字符串，整文件 `SyntaxError`。**但 verify 脚本的 JSON 字段比对全部显示 ✅** —— 因为定位用 `lastIndexOf("JSON.parse('")`，恰好命中了第二个前缀，照样能解析出正确 JSON。 **铁律**：改动这种大打包产物后，**必须对整文件做真实编译**： ```js import vm from "node:vm"; try { new vm.Script(source, { filename: "index.js" }); } catch (e) { /* 立即回滚备份 */ } ``` - 写入脚本要内置编译校验 + 失败自动回滚 - verify 脚本的结构/语法检查必须**硬阻断 `exit 1`**，只打印 ❌ 而不改变退出码等于没有检查 - 交付前再独立跑一次 `node --check <file>`，不要只信自己的脚本 - **反向测试**：拿一个已知损坏的备份喂给 verify，确认它真的报失败（否则检测是摆设） ### 已知 IDE 侧缺陷：`toolTimeout` 未接通，实际只有 60 秒 - `TcbIntegration` 的配置对象**没有** `toolTimeout` 字段（`EopIntegration` 传了） - `callTool` 用 `this.config.toolTimeout` → `undefined` - MCP SDK：`const Sn = sn?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC`，而 `DEFAULT_REQUEST_TIMEOUT_MSEC = 6e4` - ⇒ 配置 JSON 里写的 `"toolTimeout":120000` **从未生效**，实际 60 秒就掐断 PG `applyMigration` / CloudRun 部署 修复（`scripts/patch-tool-timeout.mjs`）： - **Patch A**：给 `TcbIntegration` 配置对象补 `toolTimeout:hn.toolTimeout`（锚点 `attatchPrompt:hn.attatchPrompt,loginOnlyChinese:hn.loginOnlyChinese}`，全文唯一 1 处） - **Patch B**：把配置值从 120000 提到 300000 ### 白名单可以放心多留位（源码实证） ```js ((ir?.tools) || []).filter((ir) => this.config.mcpServer.toolWhiteList.includes(ir.name)) ``` 遍历的是 **server 实际返回的 `tools/list`**，白名单只做 `includes` 判定。多出的条目静默跳过、不报错、不产生悬空工具。所以白名单按 `tools.json` 全量下发是安全的，插件后续启用也无需再改配置。 - `mcp/src/server.ts` 用 `ide === "CodeBuddy"` 判定 logging capability，大小写敏感；IDE 传的正是 `"CodeBuddy"`，别改成小写。 - 老版本 bundle 用旧的 MySQL / 云函数 / 存储工具名（`executeReadOnlySQL`、`createFunction`、`uploadFiles`、`writeSecurityRule` 等），新 bundle 里这些名字已全部消失，提示词里如果还在引用就会引导模型调用不存在的工具。 ## Verification 交付前必须同时满足： 1. **独立跑 `node --check "<genie>/out/extension/index.js"` 通过**（最关键，能抓住回读校验掩盖的语法错误） 2. `apply-to-ide.mjs` 输出「语法有效」+「回读校验通过」 3. `verify-ide-config.mjs` 结构完整性三项 ✅ + 七个字段 ✅，`echo $?` 为 0 4. `verify-bundle.mjs` 显示「所有暴露的工具都在白名单内」且 PG 三件套（`queryPgDatabase` / `managePgDatabase` / `queryPgStorage`）已注册 5. `verify-ide-config.mjs` 反向测试：喂已知损坏文件必须 `exit 1` 6. 重启 IDE 后完成下方的人工端到端验收（E1–E10） ### 人工端到端验收用例（自动化证明不了的那一层） 脚本只能证明「bundle 与配置文件本身是对的」，**证明不了 IDE 加载后用户真的能用**。重启后逐项跑： | # | 用例 | 预期 | | --- | --- | --- | | E1 | 完全退出后重启 IDE | 集成面板正常渲染，无 `SyntaxError`、genie 扩展不报错 | | E2 | 集成面板连接 CloudBase | 登录成功，显示环境信息 | | E3 | 让 Agent 列出可用的 CloudBase 工具 | 数量与新白名单一致（不是旧版数量） | | E4 | PG 环境让 Agent 建表 | 走 `managePgDatabase` 的 `applyMigration`，提示词先引导读 `postgresql-development-cloudbase` 规则 | | E5 | 执行一条只读 SQL | 走 `queryMysqlDatabase`（不再是 `executeReadOnlySQL`） | | E6 | 部署一个 Node.js 云函数 | 走 `manageFunctions`（不再是 `createFunction`） | | E7 | PG 模式下访问存储 | 走 `queryPgStorage` 而非 `queryStorage` | | E8 | 查看/修改安全规则 | 走 `queryPermissions` / `managePermissions`（不再是 `writeSecurityRule`） | | E9 | PG 执行耗时 >1 分钟的迁移 | 不中断，5 分钟超时生效（验证 `toolTimeout` 修复） | | E10 | 正常对话观察上下文占用 | 工具全量放开后无明显膨胀（验证 Tool Search 结论） | **验证时的两个坑：** - **tcb 临时密钥会过期**：日志表现为 `Authorization cache loaded for tcb, tempKey expires at: <过去时间>`，必须在集成面板重新登录，MCP 才起来。 - **MCP 进程按需启动**：tcb 的 MCP Server 只有集成面板连上后才拉起，IDE 刚启动时日志里没有 tcb 的 `tools/list` 属正常，**别据此判定 bundle 没生效**。 日志位置：`~/Library/Application Support/CodeBuddy CN/logs/<时间戳>/window1/exthost/Tencent-Cloud.coding-copilot/腾讯云代码助手.log`（搜 `[Integration]` / `tcb`）。 ### MCP 服务端质量的合格基线（顺带可测） 如果要顺带评估 MCP 工具层本身，这几项是实测通过的基线，达不到说明有回归： - **只读承诺**：`queryPgDatabase(action=sql)` 必须拦截 DELETE / UPDATE / DROP / 多语句注入，且返回带 `nextActions` 的可执行建议 - **confirm 闸门**：`managePgDatabase(execute)`、`manageFunctions(deleteFunction)` 缺 `confirm` 时必须拒绝 - **负向路径零崩溃**：不存在的函数名 / 集合 / envId / topic 都返回结构化错误或正常语义，不出裸 stack trace - **能力边界明示**：PG 环境下 `queryPermissions` 应返回「不支持 PostgreSQL 类型环境」，而不是假装成功 首次实操的完整交付物（文档 + 配置 + 脚本）模板在 CloudBase-MCP 仓库的 `specs/cb-ide-mcp-upgrade/`（worktree `chore/cb-ide-mcp-upgrade`）。 ## 交付前的一致性自查（易漏） **凡「改配置 + 再打独立 patch」的两步流程，patch 改的标量必须回流到配置生成脚本**。 实例：本任务里 `toolTimeout` 先从 120000 提到 300000 是靠 `patch-tool-timeout.mjs` 单独 patch 的，而 `build-config.mjs` 生成的 `tcb-config.new.json` 里仍是 120000。交付物自带旧值，IDE 侧直接拿配置去用就会退回两分钟。 自查项： 1. 对比「交付配置 JSON 的标量值」与「IDE 内实际生效值」，逐项相等 2. 白名单条数、各提示词长度、所有标量字段都要对，不能只看回读脚本报绿 3. 文档里的数值表格（变更项、建议项）与配置源保持一致 ## 交付文档的可读性（易被忽略） **Markdown 交付物不要放在点开头的隐藏目录下**。git worktree 常用 `.worktrees/<name>/`，预览器常因安全策略拒绝加载隐藏目录资源，表现是「文件能读到、点击却打不开/报错」。 交付前做两件事： 1. 把文档产物镜像到非隐藏路径（本次用 `~/Projects/cb-ide-mcp-upgrade/`），`present_files` 指向该路径 2. 生成自包含 HTML 版，`present_files` 第一个传它（HTML 会同时开预览面板 + 列 artifact card，最稳） 渲染脚本在本 skill 的 `scripts/render-html.mjs`，依赖 `marked`： ```bash mkdir -p /tmp/mdrender && cd /tmp/mdrender echo '{"name":"mdrender","private":true}' > package.json npm install marked NODE_PATH=/tmp/mdrender/node_modules node <skill>/scripts/render-html.mjs \ "<交付目录>/README.md" "<交付目录>/README.html" "文档标题" ``` 注意：`npm install` 别在 `~/.workbuddy/binaries/node/workspace` 里跑——没有 package.json 时 npm 会向上找到 `~/node_modules` 并因 ENOTEMPTY 失败。装到带 package.json 的临时目录最省事。 产物自带侧边目录导航（从 h2/h3 生成）、表格与代码高亮样式、`@media print` 打印规则（可直接导出 PDF 交给外部团队）。