【免费下载链接】repoprompt-ceCommunity edition of RepoPrompt: a native macOS context engineering app for AI coding agents, with an MCP CLI.项目地址https://gitcode.com/gh_mirrors/re/repoprompt-ce点击查看免费下载RepoPrompt CE 是一款原生 macOS 的 AI 编码代理上下文工程工具内置 MCP 服务器与命令行工具rpce-cli。它的一项实用能力是当 MCP 长时任务如 Context Builder、Oracle 会话正在执行时通过标准的notifications/progress进度通知持续上报阶段与耗时让你一眼看清它正在做什么而不是盯着一个疑似卡死的窗口干等。本文带你彻底搞懂这套 MCP 进度通知机制的设计与实现。为什么长时任务会看起来卡住MCPModel 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你什么都不用配——它直接把进度消息打到stderrstdout 仍然保持干净的 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 被完整枚举并归入三个有序 stageStage代表 Phase含义discoveringprovider_process_starting→child_connection_observed→routing_confirmed子 provider 进程启动、连接与路由观察generatingmodel_resolution、payload_packaging、streaming、message_finalization模型解析、打包、响应流式输出processingselection_reply_rendering选择结果渲染这些 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会同时监听两条通道标准 MCPnotifications/progress首选RepoPrompt 私有的repoprompt/control/progress通知兼容旧版 App 构建的回退路径定义见 MCPControlMessages.swift。这样即使客户端是新版、App 是旧版进度依然可见平滑度过版本过渡。快速上手 macOS 用户一条命令安装签名版brew tap repoprompt/repoprompt-ce brew install --cask repoprompt-ce之后用rpce-cli -e发起非交互式调用进度消息就会自动出现在 stderrstdout 干净可管道。小结机制作用源码/文档位置progressToken订阅客户端声明我要看进度docs/mcp-progress.md单调序号 stage/phase可读、可判断卡在哪一步MCPContextBuilderProgressTimeline.swift心跳 软超时区分正常慢与真卡住MCPToolHeartbeat.swiftlatest-wins 终态失效进度永不拖累最终结果MCPDomainRequestProgressState.swiftrpce-clistderr 输出零配置、不污染 stdoutInteractiveMCPClientSession.swift进度通知的本质是给长时任务加一块透明仪表盘它不改变结果、不接管取消、不制造失败只是诚实地告诉你——我在generating阶段Oracle 响应已经开始流式输出总共跑了 47 秒。告别卡住假象从这一行行[progress]开始。赞分享【免费下载链接】repoprompt-ceCommunity edition of RepoPrompt: a native macOS context engineering app for AI coding agents, with an MCP CLI.项目地址https://gitcode.com/gh_mirrors/re/repoprompt-ce点击查看免费下载相关推荐Python SDK 进度通知指南用 report_progress 与 progress_callback 为 MCP 长任务构建实时进度Python SDK 进度通知指南用 report_progress 与 progress_callback 为 MCP 长任务构建实时进度 一个要跑三十秒的人工智能MCP 服务MCP Clients工具调用iSH通知系统后台任务与进度报告机制iSH通知系统后台任务与进度报告机制 概述 iSH作为iOS平台上的Linux shell模拟器在处理文件系统导入导出等耗时操作时需要一套完善的进度报告和操作系统虚拟化JIT编译MCP Python SDK 进度通知Progress Notifications机制让长任务工具实时反馈的实现原理与实战指南MCP Python SDK 进度通知Progress Notifications机制让长任务工具实时反馈的实现原理与实战指南 本文围绕 mcp Pyth人工智能MCP 服务MCP Clients工具调用上一篇AIPyApp测试框架单元测试与集成测试完整指南下一篇彻底解决Flow Launcher插件设置显示异常的5种实战方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考