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