/codebuddy-ide-mcp-upgrade

name: codebuddy-ide-mcp-upgrade
description: 升级 CodeBuddy IDE（genie 扩展）内置的 CloudBase MCP，以及 MCP 发版时同步 IDE 侧白名单。当用户提到「更新 IDE 里的 MCP」「内置 MCP 版本太老」「IDE 集成的 CloudBase 功能不足」「改工具白名单 toolWhiteList」「把新 bundle 打进 CodeBuddy」「白名单漂移」「MCP 发版要同步什么」时使用。覆盖：解包定位内置 bundle 与内嵌配置、重新构建 mcp bundle、生成新的工具白名单与系统提示词、安全注入 IDE 并备份、用 MCP 协议验证工具清单、人工端到端验收、一键回滚。
description_zh: 升级 CodeBuddy IDE 内置 CloudBase MCP
description_en: Upgrade the CloudBase MCP bundled inside CodeBuddy IDE
disable: false
agent_created: true

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` 三个集成，别改错。

加载与启动契约：

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

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

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

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 已支持