企业官网建设流程全解析

RepoPrompt CE 是一款原生 macOS 的 AI 编码代理上下文工程工具，内置 MCP 服务器与命令行工具rpce-cli。它的一项实用能力是：当 MCP 长时任务（如 Context Builder、Oracle 会话）正在执行时，通过标准的notifications/progress进度通知持续上报阶段与耗时，让你一眼看清"它正在做什么"，而不是盯着一个疑似卡死的窗口干等。本文带你彻底搞懂这套 MCP 进度通知机制的设计与实现。

为什么长时任务会"看起来卡住"？😤

MCP（Model Context Protocol）工具调用是请求-响应模型：客户端发出tools/call，服务端埋头干完活才返回最终结果。问题是，Context Builder 这类任务动辄要经历子进程启动、模型解析、上下文打包、响应流式输出、状态持久化等多个阶段，耗时从几十秒到数分钟不等。

在这段"静默窗口"里，客户端收不到任何消息，界面就像死了一样——其实背后可能一切正常。RepoPrompt CE 的解法是：在不改变最终工具结果和取消契约的前提下，为长时任务增加一条纯观察性的进度上报通道。

官方说明文档位于：docs/mcp-progress.md

一键开启：用 progressToken 订阅进度

启用进度通知只需一步：客户端在tools/call请求的_meta对象里带上一个唯一的progressToken：

{ "jsonrpc": "2.0", "id": 42, "method": "tools/call", "params": { "name": "context_builder", "arguments": { "instructions": "Trace the authentication path" }, "_meta": { "progressToken": "context-builder-42" } } }

请求执行期间，RepoPrompt CE 就会用同一个 token 回传标准的notifications/progress通知。注意两点设计取舍：

• progress是单调递增的事件序号，不是百分比。因为代码发现与模型生成没有可靠的工作总量，硬算百分比反而会误导；
• 省略total字段，同理。

而rpce-cli的非交互式调用（rpce-cli -e）会自动请求一个唯一的进度 token，你什么都不用配——它直接把进度消息打到stderr，stdout 仍然保持干净的 MCP/命令输出，管道脚本完全不受污染：

[progress] context_builder [discovering]: Running Context Builder agent... [progress] context_builder [discovering]: Still in tab-context commit ... [progress] context_builder [generating]: Oracle response streaming started ...

相关实现见 InteractiveMCPClientSession.swift。

阶段 + 细粒度 Phase：进度消息"可读"的秘密 🔍

进度消息不是干巴巴的"还在跑"，而是stage（大阶段）+phase（细粒度阶段）的组合。以 Context Builder 为例，phase 被完整枚举并归入三个有序 stage：

这些 phase 定义在 MCPContextBuilderProgressTimeline.swift 中。

一个值得注意的细节：provider_process_starting虽然名字带 "starting"，却被有意归在discovering下——因为顶层的starting阶段专门留给"工具调用本身的初始化"，而它是工具初始化完成后才启动的嵌套发现 provider。命名不会改变归属，语义才会。

心跳与软超时：长阶段的"活着证明" 💓

两个机制让"卡住 vs 正常慢"变得可区分：

1. 心跳（Heartbeat）——长阶段会周期性地发出 "Still in ..." 消息，并附带该阶段已耗时与总耗时：

Still in tab-context commit (phase 12s, total 47s)

心跳逻辑封装在 MCPToolHeartbeat.swift 中，默认 30 秒一拍；取消心跳不会影响操作本身的已定结果——进度永远是观察性的。

2. 软边界（Soft Bound）——每个 phase 可配置一个诊断性秒数上限（如tab_context_commit为 15 秒、model_resolution为 2 秒）。超过上限只会多上报一条soft_bound_exceeded事件，绝不因此让运行失败。换句话说：软超时是"提醒你该看一眼了"，而不是"熔断器"。

其他 MCP 工具（read_file、get_code_structure、prompt_export等）的执行阶段也通过 MCPToolExecutionPhaseInstrumentation.swift 记录了 started/completed 转换与耗时，方便进一步诊断。

交付保障：进度通知"尽力而为，绝不拖后腿" 🛡️

进度通道的设计核心是建议性（advisory），几条原则值得借鉴：

• 丢了不失败：一条进度通知丢失，不会让工具调用报错；
• 最新值优先（latest-wins）：每次请求最多一个在途通知 + 一个待发送更新，突发消息不会排队堆积，拖慢主流程；
• 终态即失效：服务端在返回最终结果前会invalidate()请求进度，并排空已接纳的待交付通知——心跳、软边界、时间线任务都不可能对着一个已完成的请求继续发送。核心状态机见 MCPDomainRequestProgressState.swift；
• 连接断开即停：传输层返回connectionTerminal时，进度接纳直接关闭，不再做无谓 I/O；
• 取消走正门：取消请求仍然走 MCP 标准请求取消，通过既有生命周期路径停止底层 Context Builder 工作，进度通道不参与取消决策。

另外，不带_meta.progressToken的客户端会收到完全相同的最终结果，只是没有进度通知——进度是增强，不是前提。

兼容旧版本：一条控制通道兜底 🤝

新旧组件混跑时，rpce-cli会同时监听两条通道：

1. 标准 MCPnotifications/progress（首选）；
2. RepoPrompt 私有的repoprompt/control/progress通知（兼容旧版 App 构建的回退路径），定义见 MCPControlMessages.swift。

这样即使客户端是新版、App 是旧版，进度依然可见，平滑度过版本过渡。

快速上手 🚀

macOS 用户一条命令安装签名版：

brew tap repoprompt/repoprompt-ce brew install --cask repoprompt-ce

之后用rpce-cli -e发起非交互式调用，进度消息就会自动出现在 stderr，stdout 干净可管道。

小结

进度通知的本质是给长时任务加一块透明仪表盘：它不改变结果、不接管取消、不制造失败，只是诚实地告诉你——"我在generating阶段，Oracle 响应已经开始流式输出，总共跑了 47 秒"。告别"卡住"假象，从这一行行[progress]开始。