# 2026-04-01

## report-api 归因处理（api_design / JSSDK / 后端 API）

- 尝试执行 `npm run report:dev`，确认当前仓库无该脚本；本地 `http://127.0.0.1:5174/api/openapi.json` 已可访问
- 仅通过 report-api 排查并更新 5 条归因 issue，统一设置 `owner=codex`、`resolutionStatus=in_progress`
- 已更新 issue：
  - `issue_mnetwkbv_1yfik9`：CloudBase JS SDK signUp 类型/返回契约不一致
  - `issue_mnetl6ls_qg1579`：CloudBase JS SDK 手机号登录初始化与 API 选型指引不足
  - `issue_mnf5yws3_qoohgc`：DescribeSafeRule 对不存在集合不返回错误
  - `issue_mnf6i7pu_2r7k04`：DescribeStorageACL 对不存在 Bucket 不返回错误
  - `issue_mnf8tqbz_ymput8`：MySQL 开通成功状态与实际可用性存在延迟
- 本轮未补 externalUrl：可用 report-api 信息不足，且 issue 详情接口多次返回 Prisma connection pool timeout

## 429 误判历史数据修复

- 通过 `GET/PATCH /api/runs/{caseId}/{runId}/attribution` 回填 429 污染数据：将 997 条 workerLog 含 `429 usage exceeds frequency limit` 且误写为 `status=done` 的 run attribution 统一修正为 `status=error`
- 通过 `PATCH /api/attributions/{issueId}` 将 6 条完全由 429 导致的历史 issue 标记为 `invalid`，统一写入 `owner=codex` 和审计 notes
- 另外确认 2 条 issue 为混合样本（同时含真实非 429 runs），未误判为 invalid：`issue_mnarbty6_sbdqdw`、`issue_mmedoevg_0eqexc`
- 重要限制：report-api 当前仅暴露 attribution 写接口，不支持直接改 `/api/runs/.../result` 中的 run status；因此本轮修复的是 attribution / issue 层的历史数据

## 重建并提交 PR #461

- 因原工作区处于未完成 merge 状态，未直接改动现场；改用独立 worktree：`/Users/bookerzhao/.config/superpowers/worktrees/cloudbase-turbo-delploy/feature-dependency-audit-vuln-cleanup`
- 基于 `github/main` 新建分支 `feature/dependency-audit-vuln-cleanup`，cherry-pick `dba0fae` 与 `a49eb27`，并创建 PR #461：`https://github.com/TencentCloudBase/CloudBase-MCP/pull/461`
- 已确认 PR 状态 OPEN，worktree 头提交 `a1c9b57`

## 分析 PR #461 构建失败原因

- 失败 run：`https://github.com/TencentCloudBase/CloudBase-MCP/actions/runs/23829012219/job/69458257767?pr=461`
- 在独立 main worktree 上执行 `cd mcp && npm ci && npm run build` 可成功构建；在 PR 分支同样执行可稳定复现 62 个 `TS2353`（`annotations.category` 非法）
- 结论：不是显式修改 `mcp/package.json` 里的 SDK 版本，而是 `mcp/package-lock.json` 重算后把顶层 `@modelcontextprotocol/sdk` 从 `1.16.0` 漂到 `1.29.0`，并把 `@cloudbase/mcp` 从 `1.0.0-beta.25` 漂到 `1.0.0-beta.30`，触发更严格的类型检查，暴露出已有的 `category` 字段问题

## 修复 PR #454 合并冲突

- 在 `feature/skill-contract-refresh` 分支执行 `git merge --no-commit --no-ff github/main`，复现唯一冲突文件为 `config/source/editor-config/compat-baseline.json`
- 根因是该文件为生成产物，PR 分支和 main 都更新了 compat baseline；通过重新执行 `npm run update:compat-baseline` 重建基线而不是手工挑选冲突块
- 重新生成后校验 JSON 合法、无冲突标记，`node scripts/diff-compat-config.mjs` 退出码 0
- 提交合并提交 `9e30f03` 并推送到 `github/feature/skill-contract-refresh`
- 通过 GitHub PR 页面再次确认：PR #454 已不再显示 `This branch has conflicts that must be resolved`

## 收敛 PR #461 的依赖漂移并评估 B 方案

- 在 PR #461 上新增提交 `05e4aa0`：`fix(deps): 🔒 restore stable mcp lockfile after miniprogram cleanup`，将 `mcp/package.json` / `mcp/package-lock.json` 回收到 `github/main` 基线后，仅以最小变更移除 `miniprogram-ci`
- 推送后最新检查显示 `Build package` 已通过；当前失败点已从 TypeScript 编译错误转为 `../tests/runtime-validation.test.js` 的 `beforeAll` 10 秒超时，属于测试阶段问题而非 SDK 类型问题
- B 方案可行性结论：从代码结构看，升级后主要冲突出在 `ExtendedMcpServer` 没显式放宽 `registerTool` 的 meta 参数类型，而工具注册处普遍带有自定义 `annotations.category`；理论上通过在本地扩展 `registerTool` 签名或为工具元数据定义兼容类型，可较低成本消除这批 `TS2353`
- B 方案风险：会把 PR 范围从“依赖清理”扩展为“SDK 兼容层修复”，需补充构建与测试验证，且仍需单独处理当前 runtime-validation 超时问题

## 新建跟踪 issue：tool category 契约

- 新建 GitHub issue #462：`feat(mcp): 明确 tool category 的兼容契约并梳理调用方消费方式`
- issue 链接：`https://github.com/TencentCloudBase/CloudBase-MCP/issues/462`
- 记录的重点：`annotations.category` 不能只从类型侧简单移除，需要先梳理 IDE / 前端 / 服务端 / 兼容层等调用方是否依赖该字段做分组、展示、过滤或权限判断，再决定兼容方案与迁移路径

## 配置本地 claude-code-router 试用路由

- 查阅 `musistudio/claude-code-router` 文档并确认本地配置目录为 `~/.claude-code-router/`，主配置文件为 `config.json`
- 读取现有本地配置后，先备份到 `~/.claude-code-router/config.json.2026-04-01T12-20-00Z.ai-trial.bak`
- 在不改动现有默认模型的前提下，将 Router 调整为分场景试用：`default/background` 仍走 `小米,mimo-v2-pro`，`think` 改为 `deepseek-api,deepseek-reasoner`，`longContext` 改为 `hunyuan,hunyuan-standard-256K`，`webSearch` 改为 `openrouter,google/gemini-2.5-pro-preview`
- 已执行 `ccr restart`，本地 router 服务已重新启动生效

## 同步 run result 更正文档

- 复核本地 `http://127.0.0.1:5174/api/attributions` 与 issue 详情接口，确认 live API 真实字段为 `resolutionStatus`、`owner`、`notes`、`externalUrl`，OpenAPI 仍存在旧 `status` schema 漂移
- 确认 attribution worker 的 `ExecutionError` / `error_during_execution` / `429 usage exceeds frequency limit` 已按 run result `error` 处理，历史 issue notes 中可见 `Affected run attribution status has been backfilled to error`
- 已把这一结论同步写入 `skills/mcp-attribution-worktree/references/report-api-workflow.md` 与 `specs/mcp-attribution-worktree-skill/implementation-summary.md`
- 本次同步范围仅限文档层：共 2 个文件，diff 统计为 25 行新增、7 行删除，未改业务代码或测试

## 分析 searchKnowledgeBase 的 skill 来源与滞后点

- 结论：`searchKnowledgeBase(mode="skill")` 的 skill 列表不是直接读当前仓库，而是启动时先下载 `https://static.cloudbase.net/cloudbase-examples/web-cloudbase-project.zip`，再从压缩包内 `.claude/skills/**/SKILL.md` 收集 description 与正文
- 该 ZIP 来源于外部仓库 `TencentCloudBase/awsome-cloudbase-examples` 的构建产物；本仓库通过 `.github/workflows/build-zips.yml` + `scripts/sync-config.mjs` 同步内容到外部仓库后，再由外部 `build-zips.js` 打包
- 本地还存在第二层缓存：`mcp/src/tools/rag.ts` 默认把资源缓存到 `~/.cloudbase-mcp/`，TTL 为 24 小时，可通过 `CLOUDBASE_MCP_CACHE_TTL_MS` 调整；因此即使上游 ZIP 已更新，本地 skill 检索结果也可能继续滞后一段时间
- 2026-04-01 18:06 核对时间：远端 `web-cloudbase-project.zip` 响应头 `Last-Modified=Sat, 28 Mar 2026 00:34:44 GMT`（北京时间 2026-03-28 08:34:44 +0800）；本地缓存文件修改时间为 `2026-04-01 10:39:35 +0800`
- 复核 `.github/workflows/sync-branch.yml`：当前仅声明 `workflow_dispatch`，属于手动触发工作流；触发后会执行 `scripts/sync-config.mjs --skip-git`，并在 `commit_changes=true` 时自动 commit/push 到 `awsome-cloudbase-examples` 目标分支，但不会在源仓库 push 后自动运行
- 判断结论：不建议把 `sync-branch.yml` 直接改成“任意分支 push 即自动同步”；更稳妥的是仅对 `main`（或受控发布分支）+ 相关路径变更做自动 sync/build/publish，而 feature 分支继续手动触发。原因是该工作流会写外部仓库，且仅同步 branch 并不能单独解决 `searchKnowledgeBase` 的滞后，真正生效还依赖后续 ZIP 构建/发布链路
- 进一步建议：若要自动化，优先选“`main` 合并后自动 sync 到 examples”作为发布边界；技术上更建议监听 `push` 到 `main` 而不是 `pull_request.closed`，并加 path filter，只在 `config/source/skills`、`config/source/guideline`、`config/source/editor-config`、同步脚本等发布相关路径变更时执行
- baseline 判断补充：`config/source/editor-config/compat-baseline.json` 更适合作为自动 sync 前的“兼容面守门员”，而不是唯一触发条件。原因是 `diff-compat-config` 对 machine 配置漂移会阻断，但对 text surfaces 内容变化仅 advisory；而 skill/guideline 文本变化本身仍然应该继续同步到 examples，不能因为 baseline 未更新就被误判为无需发布
- 自动同步设计方向已确认：新增独立 workflow（保留 `sync-branch.yml` 手动用法），监听 `push` 到 `main` 并同步到 `awsome-cloudbase-examples/master`；保持现有同步动作不变，仅调整触发时机，并使用 path filter + `diff-compat-config` 作为前置校验/守门逻辑

## 提交自动同步 PR

- 新建分支 `feature/auto-sync-main-to-examples`，仅提交 `.github/workflows/sync-main-to-examples.yml` 与 `CONTRIBUTING.md` 中对应说明，未带入本地其余未提交改动
- 提交信息：`feat(ci): 🔄 auto sync main changes to examples`
- 已验证 `sync-main-to-examples.yml` 可被 YAML 解析，且 `node scripts/diff-compat-config.mjs` 通过
- 已推送到 `github/feature/auto-sync-main-to-examples` 并创建 PR #463：`https://github.com/TencentCloudBase/CloudBase-MCP/pull/463`

## 收敛 runtime-validation hook 超时

- 调整 `tests/runtime-validation.test.js`：删除固定 `delay(2000)`，改为 `client.connect()` 后用 `client.listTools()` 做显式就绪探测；`beforeAll` 局部超时提升到 30000ms，`afterAll` 设为 10000ms，并改用唯一临时目录与 `process.execPath` 启动 CLI
- 在 `mcp/src/tools/functions.ts` 抽出 `resolveEventFunctionRuntime()`，统一处理 Event runtime 默认值、空格归一化与非法值报错；`mcp/src/tools/functions.test.ts` 新增 3 条单测覆盖上述行为
- 验证结果：`cd mcp && npx vitest run src/tools/functions.test.ts` 通过；`node --check tests/runtime-validation.test.js` 通过；完整 `npm run build` 仍被仓库现有 `annotations.category` 类型错误和 `miniprogram-ci` 缺失阻断，因此本轮无法在本地跑通依赖 `dist/cli.cjs` 的集成回归

## 推送 runtime-validation 修复分支

- 基于最新 `origin/main` 切出独立分支 `fix/runtime-validation-stability`，避免把这轮 runtime 修复混入已有 `feature/auto-sync-main-to-examples` PR
- 仅提交 3 个相关文件：`mcp/src/tools/functions.ts`、`mcp/src/tools/functions.test.ts`、`tests/runtime-validation.test.js`
- 提交信息：`fix(runtime-validation): 🧪 stabilize event runtime validation tests`
- 已推送到 `github/fix/runtime-validation-stability` 并创建 PR #464：`https://github.com/TencentCloudBase/CloudBase-MCP/pull/464`
- 推送后已切回原工作分支 `feature/auto-sync-main-to-examples`；其余未提交文档/技能改动保持原样未带入本次提交

## 清理本地 rules 缓存 zip

- 已按确认流程处理 `~/.cloudbase-mcp/web-cloudbase-project.zip`
- 清理前先备份到 `~/.cloudbase-mcp/backups/web-cloudbase-project.zip.20260401-203111.bak`
- 原文件随后已移入 macOS 废纸篓，当前 `~/.cloudbase-mcp/` 下已不再保留该 zip 缓存

## 清理本地 cache-meta.json

- 已按确认流程处理 `~/.cloudbase-mcp/cache-meta.json`
- 清理前先备份到 `~/.cloudbase-mcp/backups/cache-meta.json.20260401-203436.bak`
- 原文件随后已移入 macOS 废纸篓，当前 `~/.cloudbase-mcp/` 下已不再保留该缓存元数据文件
