本文基于 FrontAgent 全流程定量测试结果，提出下一阶段性能优化方案。测试显示：Planner 与 Filesense 导航已不再是主要瓶颈，create-component 场景平均耗时达到 261.78ms，显著高于 query/refactor/debug 场景。方案将优化重点从“继续压缩 Filesense”转向“建立可观测 Trace、拆解 Executor 固定成本、收口 create_file 执行链路、沉淀轻量 benchmark 守护”，目标是在不牺牲安全与能力的前提下，把 create 类任务的编排开销降低到可解释、可回归、可持续优化的状态。 :::

FrontAgent 已完成 Filesense 集成优化：旧的全仓 filesense_sync_and_summarize('.') 被替换为按需、预算化的 filesense_navigate。单独 Filesense 基准显示，根目录轻量导航平均耗时从旧方案的 101.09ms 降到 5.08ms，明确局部导航降到 0.25ms。

在此基础上，进一步做了 FrontAgent 全流程微基准。链路覆盖：

任务输入 → Planner.plan → phase injection → Executor.executeSteps → MCP Tool 调用

测试刻意使用 useLLM=false 与本地 stub MCP client，目的是排除外部 LLM、网络、浏览器和真实 shell 的干扰，先看 FrontAgent 编排层自身的基础成本。结论比较明确：当前主要瓶颈已经从 Filesense 转移到 Executor 内部执行链路，尤其是 create 类任务。

从数据看，Planner 平均耗时均低于 0.5ms，没有优化优先级。Filesense 在全流程中的样本耗时约 0.25ms~1.35ms，也不是主要矛盾。create-component 的 261.78ms 与其他场景拉开两个数量级，需要专项拆解。

Filesense 当前已经具备两个收益：

1. 默认更轻：明确单文件 query 不再注入 Filesense。
2. 需要时可控：结构、debug、refactor 类任务会注入导航，但预算受 depth / maxEntries / maxBytes / timeoutMs 限制。

因此下一阶段不建议继续优先改 Filesense 主路径，而应先补齐全流程 profiling 能力。

当前数据能确认“慢在哪里”，但还不能完全确认“为什么慢”。尤其是 create-component：

filesense_navigate(intent=prepare_create, paths=['src'], depth=1, maxEntries=180)
read_file
create_file

最后一次样本中，filesense_navigate 仅约 1.35ms，但 execute 平均达到 261.41ms。这说明瓶颈大概率出现在 create_file 执行链路周边，包括但不限于：

这里要避免直接拍脑袋优化。第一阶段目标不是立刻改快 create_file，而是把 create_file 的 261ms 拆成可归因的分段耗时。

优化分四层推进：

┌────────────────────────────────────────────┐
│ Benchmark Layer：可复现全流程基准           │
├────────────────────────────────────────────┤
│ Trace Layer：Executor 阶段级耗时埋点         │
├────────────────────────────────────────────┤
│ Execution Layer：create_file 链路收口        │
├────────────────────────────────────────────┤
│ Guardrail Layer：CI 性能守护与退化阈值        │
└────────────────────────────────────────────┘

推荐按顺序落地。原因是当前 create 场景缺少分段数据，直接改执行逻辑容易把问题藏起来，也可能破坏安全与校验链路。

将本次 /tmp/frontagent-flow-benchmark.mjs 临时脚本沉淀到仓库，例如：

benchmarks/frontagent-flow-benchmark.mjs
benchmarks/fixtures/frontagent-flow-fixture.ts
benchmarks/README.md

基准分三档：

输出统一 JSON：

{
  "scenario": "create-component",
  "runs": 10,
  "planMs": { "avg": 0.38, "median": 0.26 },
  "executeMs": { "avg": 261.41, "median": 203.59 },
  "steps": [
    {
      "action": "create_file",
      "durationMs": 202,
      "trace": {
        "validateBeforeMs": 0.3,
        "prepareToolParamsMs": 180.0,
        "callToolMs": 1.2,
        "validateAfterMs": 20.5
      }
    }
  ]
}

这样后续文档里的数据不再依赖手工复制，避免单位和口径混乱。

在 Executor.executeStep 内增加轻量 trace，不改变默认行为。建议新增配置：

interface ExecutorConfig {
  trace?: {
    enabled?: boolean;
    onStepTrace?: (trace: StepTrace) => void;
  };
}

核心数据结构：

interface StepTrace {
  taskId: string;
  stepId: string;
  action: string;
  tool: string;
  totalMs: number;
  stages: Array<{
    name:
      | 'validate_params'
      | 'validate_before'
      | 'prepare_tool_params'
      | 'security'
      | 'call_tool'
      | 'validate_after'
      | 'recovery';
    durationMs: number;
    success: boolean;
    error?: string;
  }>;
}

需要注意两点：

1. trace 必须是旁路能力，默认关闭。
2. trace 不能吞异常、不能改变原有 success/error/rollback 语义。

这一步完成后，可以直接回答：create_file 的 261ms 是耗在动态生成、校验、安全，还是工具调用。

在 trace 明确瓶颈后，再对 create 路径做定向优化。预期有三类优化点。

如果 create_file 的 params.content 已存在，或任务是 benchmark/stub 模式，则不应触发额外 LLM 生成。建议规则：

content 已存在 → 直接写入
content 缺失 + canGenerate=true → 进入生成链路
content 缺失 + canGenerate=false → 返回参数缺失错误

这样可以避免 create 类任务在规则 planner 下误入生成路径。

当前所有 create/modify 都走相近的前后置校验，会让简单文件创建承担过多成本。建议把校验分为三档：

默认 create_file 使用 basic 或由 planner 指定 validationLevel。只有明确需要时才升级到 syntax/project。

refactor 样本显示 apply_patch 内部会出现额外 read_file 前置读取，这本身合理，但可以通过 step context 缓存降低重复读取：

同一 task 内相同 path 的 read_file 结果 → 放入 ExecutorCollectedContext
apply_patch 前置读取 → 优先复用 context.files
写入/patch 成功 → 失效对应 path 缓存

这不会改变语义，但能减少多文件任务中的重复 I/O 与重复 MCP 调用。

新增 CI smoke benchmark，目标不是精确性能测试，而是防止明显退化。

建议阈值：

CI 上绝对耗时会波动，因此阈值要宽松；更重要的是守住“是否注入重工具”和“是否出现数量级退化”。

方案落地后，至少满足以下标准：

1. pnpm bench:flow:local 能稳定输出 JSON 与 Markdown 摘要。
2. create-component 的 261ms 能被拆分到具体阶段，且 top stage 占比清晰。
3. 明确单文件 query 不注入 Filesense，调用次数为 0。
4. 结构/debug/refactor 任务仍能注入 filesense_navigate，但不触发全仓 sync。
5. pnpm --filter @frontagent/core typecheck、pnpm --filter @frontagent/mcp-filesense test -- --run、pnpm build 通过。

FrontAgent 当前的性能优化重点已经发生变化：Filesense 的重扫问题已通过 filesense_navigate 基本收口，Planner 也不是瓶颈。下一阶段应围绕 Executor 可观测性与 create_file 链路治理 展开。

推荐先做 trace 与 benchmark 入仓，再基于数据优化 create/modify/refactor 的具体阶段。这样既能避免盲改，也能把性能收益沉淀成长期守护能力。