企业官网建设流程全解析

• 开发工具
• 版本控制

本文深入解读 GitLens 仓库中/live-perf技能（.claude/skills/live-perf/SKILL.md）的完整方法论：如何在正在运行的扩展里对某个功能做性能测量、建立基线、按"Measured / Conventions / Speculation"三层纪律派发修复 Agent，并循环重测直至无回归。读完本文，你将掌握一套可直接复用的"测量优先、规范优先、杜绝臆测"的性能改进工作流，并了解其与仓库内 MCP 工具链、RPC 日志层、@memoize装饰器及 git 调用测试的对应关系。

一、/live-perf 是什么：一次"测量驱动"的性能闭环

/live-perf是 GitLens 为 Agent 定义的一等技能，其核心信条只有一句话："Measure-first or don't touch. Speculation goes to open-questions, never to agents."（先测量，否则不要动代码；臆测一律进 open-questions，绝不派发给 Agent）。

该技能用于三种典型场景：

• 独立使用（Standalone）：对既有功能做性能调优，而无需走完整的/live-exercise功能审计。典型目标包括渲染回归、RPC 消息频繁程度（chattiness）、git 调用风暴（git-call storms）、热路径上缺失的缓存。
• 被/live-exercisePhase 7 委托：作为发布前（ship-gate）收敛循环的一部分被调用，属于"先修功能、再调性能"流水线的最后一环。

/live-perf明确声明不适用的场景同样重要：

• 对"没有被测量出慢"的代码做投机性优化；
• 当功能性与意图本身存疑时替代/live-exercise（应先修功能，再对可工作的部分做性能调优）；
• 完全没有实时测量支撑的静态代码审查。

与其他技能的分工

可以看出，/live-perf是五个技能中唯一同时要求"实时"与"测量"的——它不信任静态推理，一切结论必须以数字或既定规范为依据。

二、前置条件：MCP 工具链与构建验证

技能执行前需要满足三个前置条件，这些条件在仓库中都有实际落点：

1. vscode-inspectorMCP 已连接。仓库根目录的 .mcp.json 已经声明了该服务器：

   { "mcpServers": { "vscode-inspector": { "command": "node", "args": ["scripts/mcp-vscode-server.mjs"] } } }

   对应的服务端实现位于 scripts/mcp-vscode-server.mjs，它暴露了/live-perf全流程依赖的原始工具：launch（启动 VS Code）、evaluate_in_webview（在 webview 内执行 JS 并取回数值）、evaluate（在扩展宿主侧执行）、read_logs（读取日志）、read_console、list_webviews等。

2. 构建通过：pnpm run build:quick。该脚本定义在仓库 package.json 中（"build:quick": "node ./scripts/build.mjs --quick"），是每次派发修复 Agent 之后必须运行的验证命令。
3. 能识别 Scope（范围）：特性、生命周期阶段、用户流程、diff、后台操作或临时代码路径——"对一切做性能优化"的模糊调用不属于本技能范畴。

三、三维轴：Scope / Exercise / Baseline

每次/live-perf调用都沿着三个轴展开，轴值从用户请求中推导；框架本身（三层纪律、收敛循环、退出条件）不变，只有轴值变化。轴值需要记录在baseline.md顶部，以保证意图可审计。

轴 1 —— Scope（测量什么）

轴 2 —— Exercise（如何驱动）

轴 3 —— Baseline（拿什么对比）

默认组合表

如果任一轴无法确定，技能要求只问用户一个问题："What's the scope — a specific feature, a lifecycle stage (activation/startup), a cross-feature user flow, the diff on this branch, or a background operation?"，然后按默认组合表推断其余两轴。

四、测量四类别：渲染、RPC、热路径、Git 调用

无论 Scope 是什么，每一轮测量都必须覆盖四个类别（确实不适用时才跳过，且需记录跳过原因）。原技能特别指出：在 Opus 上运行时，原始测量采集默认委托给inspector-driver子 Agent（Sonnet 5）——通过Agent({ subagent_type: "inspector-driver", model: "sonnet", prompt: <精确探针> })传入确切的探针（performance.now()差值、updateComplete时序、通知计数、采样数 N）。子 Agent 只负责返回数字，三层分类（Measured/Convention/Speculation）与所有修复决策始终由主 Agent 保留。冷启动指标与基线↔修复后对比需按"重置规则"复用已启动实例或自行采样。

1. 渲染 / Webview 性能

测量内容：

• 每个 webview 的首次渲染 + 水合时间（从launch/刷新到 Lit 的updateComplete）；
• 状态切换期间的重复渲染频率（Lit 组件updated()计数）；
• 布局抖动 / 强制回流（Performance API 的layout-shift、长任务）；
• 动画/过渡流畅度（合成 vs 主线程、掉帧）。

工具：evaluate_in_webview配合performance.now()、PerformanceObserver、performance.getEntriesByType("measure")，以及针对 Lit 的document.querySelector('...').updateComplete。

关于多 webview 性能，技能给出一个关键提醒：当同时打开 2 个以上 webview 时，未指定目标的evaluate_in_webview会静默运行在第一个（通常不是你想要的那个）里。必须先执行list_webviews，再用webview_url/webview_index限定每次测量。

2. RPC / 数据传输

测量内容：

• 每个用户动作触发的通知数（按类型计数）；
• 每条通知的负载大小（大数组会被标记）；
• N+1 模式（请求循环而非批量拉取）；
• 每个流程的往返次数。

工具与仓库落点：通过evaluate_in_webview对 RPC 层插桩，包裹 src/webviews/apps/shared/rpc/rpcController.ts 下的RpcController/RpcClient。该文件是 webview 侧的 RPC 控制器实现（RpcController<TServices> implements ReactiveController, WebviewRpc），其hostConnected/hostDisconnected生命周期里管理长连接与按会话挂载的服务代理。日志侧，使用read_logs检索RpcHost/RpcLogger流量——src/system/rpc/logger.ts 提供了createSupertalkLogger(prefix)与formatWebviewLogTag(webviewId, webviewInstanceId)，日志行会形如[RPC:host(gitlens.views.commitDetails|5cf1bc7c)]或[RPC:client(gitlens.views.timeline|4103a120)]，每个通道都能在日志中被精确识别。该文件的注释还说明它会把 Error-like 参数归一化为"name: message"形式，避免 JSON 序列化时把异常打成{}，这保证了日志中通知负载与错误的可读性。扩展宿主侧则用read_logs按通知名做模式匹配。

3. 热路径代码审计（纯代码级，不测量）

审计内容：

• 未缓存的重读操作（多次 await 同一个 getter / provider 方法）；
• 纯函数且高频调用的 getter 上缺少@memoize；
• git 派生数据未用GitCache/PromiseCache；
• 本可Promise.all却串行await的代码；
• 高频事件（scroll、resize、input、mousemove）缺少 debounce / throttle。

审计对象是 Scope 覆盖的代码——某个特性的源码、某个分支的 diff、激活路径等，用 Read 与 Grep 完成。仓库中@memoize的行为有完整测试佐证：src/system/decorators/tests/decorators.test.ts 的memoize套件覆盖了默认用法、自定义resolver、以及@memoize({ version: 'providers' })的版本化失效——这正对应"每次@memoize都是关于身份与失效的一次决策"这一技能断言。

4. Git 调用

关键认知：git 调用的成本在 spawn（进程创建）而非执行本身。

测量/审计内容：

• 跨组件的冗余 git 命令（一次用户动作触发了多次相同的git log/git status）；
• 未批处理解析（每条命令只取一条信息，而不是从单次输出解析多条）；
• 重复调用方缺少缓存（相同 git 结果被重复拉取）；
• git 触发的刷新风暴（一次外部变更引发 N 次刷新）。

工具与仓库落点：read_logs配合 git 命令日志模式匹配（GitLens 开启 debug 日志后会记录 git 调用）；代码审计模式参考 packages/git-cli/src/providers；扩展宿主侧用evaluate在一个用户动作窗口内统计命令调用次数。

仓库的集成测试直接印证了这些关注点：

• packages/git-cli/src/providers/tests/integration/branches.test.ts 中 "a local miss is cached, so repeated lookups spawn once" 断言缓存未命中后重复查询只 spawn 一次symbolic-ref；
• packages/git-cli/src/providers/tests/integration/config.measure.test.ts 用spawn-counter通道精确计数：一次分支总览渲染原先对每个命名空间各 spawn 一次--get-regex（4 次），现在改为一次批量读取（1 次）；
• packages/git-cli/src/providers/tests/integration/commits.test.ts 验证被取消的调用方不能误杀共享同一次 in-flight spawn 的并发调用方。

这些测试正是"一个用户动作 >3 次 git 调用即可疑"这条阈值的实现基础。

五、三层纪律：Measured / Conventions / Speculation

每个发现都必须归入三层之一，层决定是否派发 Agent 以及按什么规则派发：

| 层 | 规则 | 动作 | ID 前缀 | | -- | ---- | ---- | ------- | |Measured| 相对基线有量化回归，或可测量的热路径超过阈值 |派发修复 Agent，修复后必须重新测量确认改进 |PR| |Conventions| 违反 GitLens 规范（热 getter 漏缓存/漏 memoize、串行 await、缺 debounce） |派发自由修复 Agent，在decisions.md记录条目。无需基线——规范本身就是 bug |PC| |Speculation| "这个也许能更快"——无测量、无既定规范 |记入open-questions.md，不碰代码|PS|

三条铁律：

• Measured 层必须先测量：动手前捕获基线，修复后捕获新测量。如果修复后相比基线没有改进，就回滚并重新调查——不发布"没效果的修复"。
• Convention 层可仅凭审计派发：重复的纯 getter 上缺@memoize本身就是 bug，不需要先量化收益再修。
• Speculation 永不派发：测不出来、又不是规范违反，那就是给用户的开放问题。

六、工作循环：七步收敛

步骤 1 —— 推导 Scope / Exercise / Baseline

从用户调用、/live-exercise交接或默认组合表为三轴各取一个值；任何轴不明确就问那一个问题。从/live-exercisePhase 7 进入时：Scope 是 live-exercise 正在跑的对象，Exercise 默认用户式，Baseline 默认绝对 + 多次平均。独立调用时按默认组合表映射。若存在goals.md，读取其中声明的性能要求（阈值、预算），它们会成为轴 3 的目标。把选定的轴记录在baseline.md顶部。

步骤 2 —— 基线采集（不改代码）

若 VS Code 未运行则launch。按轴 2 的 Exercise 策略驱动：

1. 开启相关日志/插桩（git debug 日志、RPC logger、PerformanceObserver）；
2. 按策略驱动：
   • 用户式：点击/滚动/输入走完整流程，按基线策略重复；
   • 程序化：execute_command、事件派发或evaluate，按基线策略重复；
   • 环境观察：保持 VS Code 运行，观察 2–5 分钟，不去驱动；
   • 冷启动：每次运行都拆除 + 重启（启动类必须每次冷态）；
   • 压力：按配对测量需要做快速重复、并发或大数据变体；
3. 对适用类别采集测量（渲染用evaluate_in_webview+performance.measure/updateComplete；RPC 用日志解析通知计数与负载；Git 用read_logs计数；热路径仅审计不测量）；
4. 把基线数字写入.work/live/<feature>-perf/baseline.md：

# <Feature> — Perf Baseline Recorded: <ISO date> ## Render - Home webview hydration: 220ms (avg 5 runs) - Repeat render on branch switch: 85ms ## RPC - Notifications per branch switch: 12 - `DidChangeRepositoriesNotification` payload: 48KB ## Git - Commands per branch switch: 7 (3x `git log`, 2x `git status`, 2x `git rev-parse`)

步骤 3 —— 评估：测量 + 规范审计

把测量结果与以下内容对比：

• 阈值（通用指引：webview 水合 <150ms；webview 刷新 <100ms；单个用户动作 >3 次 git 调用可疑；单个动作 >5 条通知可疑）；
• 既有基线（上一轮.work/live/<feature>-perf/baseline.md或 git 历史）；
• goals.md中的声明要求。

同时用 Read + Grep 对 Scope 代码做规范违规审计。技能提醒：阈值是启发式而非教条——超过阈值且用户可感知的才是真问题。

步骤 4 —— 汇总发现

写入.work/live/<feature>-perf/findings.md：

# <Feature> — Perf Findings ## Status | ID | Tier | Category | Title | Status | Baseline → Target | | ------ | ----------- | -------- | ----------------------------------------- | ------ | ----------------- | | I1-PR1 | Measured | Render | Home hydration 220ms (threshold 150ms) | open | 220 → <150 | | I1-PC1 | Convention | Hot-path | Missing @memoize on GitProvider.getBranch | open | — | | I1-PS1 | Speculation | Git | Could batch log+status into one spawn | see Q1 | — | ## Measured (PR) ### I1-PR1 — Home hydration exceeds threshold - **Baseline**: 220ms avg over 5 runs (fresh launch → `gl-home-app.updateComplete`) - **Target**: <150ms - **Hypothesis**: RPC warmup serialized; Lit templates heavy - **Fix direction**: check if Home state can be prefetched / cached; audit Lit template for unused imports ## Convention (PC) ### I1-PC1 — Missing @memoize on getBranch - **File**: `packages/git-cli/src/providers/branches.ts:L88` - **Convention**: pure getter called in render paths → must be @memoize'd - **Evidence**: grep shows 7 call sites, 3 in render paths - **Fix**: add `@memoize()` decorator ## Speculation (PS) ### I1-PS1 — Could batch log+status into one spawn - Moved to `open-questions.md` Q1

投机性条目写入.work/live/<feature>-perf/open-questions.md：

## Q1. Batch log + status for branch switch? Currently 2 git spawns per branch switch. Could batch via combined `git log --name-status` parsing. **Pros**: saves ~30ms/switch (~estimated, not measured) **Cons**: touches parser layer, risk of parser bugs, speculative savings **Recommendation**: file for later unless branch-switch latency is user-visible bad

步骤 5 —— 派发修复 Agent（仅 Measured + Conventions）

对每条 Measured 和每条 Convention 发现：

• 归组相关修复（如同一文件内的所有@memoize补充 → 一个 Agent）；
• 并发上限 5–6 个；
• 每个 Agent 的 prompt 必须包含：
  • 精确文件路径 + 行号；
  • 层级（Measured 或 Convention）；
  • Measured 层：基线数字 + 目标。Agent 必须通过实时重测验证改进，而非假设；
  • Convention 层：被违反的规范 + 应套用的规范模式；
  • 验证命令（pnpm run build:quick）；
  • 项目规范（.js导入扩展名、无 barrel 文件、无顺手重构（drive-by refactors）、不用--no-verify）；
  • 明确的 out-of-scope。

Speculation 永不派发，那是用户通过 open-questions.md 决定的事。

子 Agent 必须重测，不能假设

派发 Measured 层修复时，prompt 必须要求子 Agent 在修复后重新驱动功能并重新采集测量。示例 prompt：

Fix the Home hydration baseline of 220ms by [approach]. After the fix, rebuild withpnpm run build:quick, relaunch VS Code via the vscode-inspector MCP, re-exercise fresh-launch → Home →updateComplete5 times, capture the new average. Report the baseline → post-fix numbers. If post-fix >= baseline, revert and report.

步骤 6 —— 验证与循环

Agent 完成后：

1. pnpm run build:quick，修复一切破坏；
2. 每个 Agent 之后都要git diff——不要盲信任何东西；
3. 为重新测量做重置：冷启动/启动类指标与每次基线↔修复后对比都需要完整拆除 + 重启——缓存状态会毁掉基线。同一构建内的热操作样本（渲染/RPC/git）可以复用运行中的实例并重新触发，但代码变更后必须先全新构建 + 重启，修复后的数字才算数；
4. 重新驱动功能，对 Agent 触碰过的所有指标重新采集；
5. 更新findings.md：修复后超过目标 → 标记完成；未改进 → 保持 open 并重新调查（不发布"不是修复的修复"）；修复导致其他指标回退 → 进入下一轮新发现；
6. Convention 修复落地后，重新审计确认模式已一致；
7. 回到步骤 2 循环，直到无遗留发现、也无新发现浮现。

步骤 7 —— 退出

满足以下全部条件才退出：

• 所有 Measured 发现都有已验证的改进，或被重新分类（连同理由移入 open-questions）；
• 所有 Convention 发现已修复；
• Speculation 条目已归档到 open-questions 供用户审阅；
• 重新采集的基线没有新回归。

从/live-exercisePhase 7 进入时：退出即把控制权交还 live-exercise；若本轮产生变更，live-exercise 回到其 Phase 5 循环；Speculation 条目随 live-exercise 的open-questions.md一起呈现给用户。

七、陷阱清单与循环红线

常见陷阱

暂停循环的红旗

• 在没有捕获基线的情况下即将派发修复；
• Agent 报告"改进"但git diff只有重写、没有测量逻辑；
• 基线与修复后测量之间没有拆除 + 重启；
• 修复后测量相对基线在噪声内（<10%）——你只是"赢在方差上"；
• 某条 speculation 连续 3+ 轮挂着未处理——升级给用户，不要悄悄派发；
• 即将把规范修复应用到实际上不在热路径上的代码。

"跳过测量"的绊线

推理中出现以下任何一句，立即停下先测量：

• "这显然更快"（This is obviously faster）
• "标准优化模式"（Standard optimization pattern）
• "大家都这么缓存"（Everyone caches this kind of thing）
• "看起来像热路径"（Looks like a hot path）
• "加个 @memoize 没坏处"（Won't hurt to add @memoize）
• "Agent 说它改进了"（Agent said it improved）

Measured 层需要数字，Convention 层需要模式匹配——两者都不接受"显然"。

需要抵制的合理化借口

八、输出物与完成检查

每次完整运行产生的产出物：

• .work/live/<feature>-perf/baseline.md—— 捕获的测量基线（每轮迭代）；
• .work/live/<feature>-perf/findings.md—— 按层分类的发现，含基线 → 修复后数字；
• .work/live/<feature>-perf/open-questions.md—— 给用户审阅的投机性条目；
• 干净的 working tree（针对性提交 / 暂存变更）；
• 记录实际改进的修复后测量（而非一句"LGTM"）。

声明"live-perf complete"前必须逐项确认：

1. 每个正在处置的指标都有文档化的基线；
2. 只派发了 Measured + Convention 发现——speculation 留在 open-questions；
3. 修复后测量经过重新驱动 + 重新采集验证（非 Agent 自报）；
4. 对每个 Agent 的工作做过git diff——无静默回归；
5. 基线与修复后测量之间拆除 + 重启过；
6. 已把open-questions.md呈现给用户；
7. 若从/live-exercise进入：退出后已归还控制权，变更（如有）触发父循环继续。

九、相关技能与后续衔接

/live-perf的强制前置背景是/live-inspect——它提供本流程所有原始 MCP 工具（evaluate_in_webview、read_logs、evaluate、read_console）的完整参考。相关技能还包括：

• /live-exercise—— 在 Phase 7 调用本技能；功能/意图问题先用它；
• /live-pair—— 交互式对等技能，遇到"这个感觉慢"的信号时把工作委托到这里；
• /simplify—— 性能修复后的代码质量清理；
• /deep-review—— 静态正确性追踪，能捕获当前负载下未暴露的性能 bug。

整体而言，/live-perf代表了一种可移植的工程纪律：把"性能工作"从凭直觉改代码，变成"定义轴 → 采基线 → 分类 → 定向派发 → 重测收敛"的可审计闭环。仓库中 .claude/skills/live-perf/SKILL.md 即完整规范，而 scripts/mcp-vscode-server.mjs、src/system/rpc/logger.ts、src/webviews/apps/shared/rpc/rpcController.ts 与packages/git-cli/src/providers/__tests__/integration/下的 spawn 计数测试，共同构成了这套方法论在 GitLens 中的真实落地底座。

• 开发工具
• 版本控制