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 扩展承载，改一处不生效，必须同时改两个文件：

默认 IDE 路径：/Applications/CodeBuddy CN.app。同目录还有 anydev、eop、lighthouse 三个集成，别改错。

加载与启动契约：

// 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 才能解析：

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

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 环境后，认证、存储、权限、迁移四项全部改道：

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. 「三选一」式的并列列表，若各分支会改变后续多项决策，应改写成「两条主线」各自自包含。

改完提示词用这个脚本量化配重，别靠感觉：

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）

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. 验证

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. 回滚

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。

铁律：改动这种大打包产物后，必须对整文件做真实编译：

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

白名单可以放心多留位（源码实证）

((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 加载后用户真的能用。重启后逐项跑：

验证时的两个坑：

• 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：

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 交给外部团队）。