RepoPrompt CE 是一款免费、开源的 macOS 原生应用，定位为面向 AI 编码代理的上下文工程（Context Engineering）工作台：它先从文件、代码结构图（CodeMap）、仓库结构和 Git diff 中组装出聚焦、可审查的上下文，再把这些上下文交给 Codex、Claude Code 等 AI 编码代理，让它们在动手写代码之前真正"读懂"你的代码库。项目采用 Apache-2.0 协议开源，并附带一个内置的 MCP CLI，方便外部代理直接接入。

🎯 它解决什么问题？

大模型代理最常见的翻车场景是：不了解仓库现状就盲目改代码。RepoPrompt CE 的核心思路是把"喂给 AI 什么"这件事产品化：

• 组装高密度上下文：把文件树、选中文件内容、行级切片、CodeMap 摘要和 Git diff 组合成模型真正需要的内容，而不是把整个仓库硬塞进去；
• 上下文可审查：所有选中的上下文都可以逐项预览、调整、再复制，避免"黑盒投喂"；
• 代理编排：在同一个原生 macOS 界面里启动、协调多个 CLI 编码代理，而不是在终端窗口间来回切换。

架构细节可见官方文档：README.md 与 docs/architecture/context-composer.md。

🧩 核心功能一览

其中 MCP 工具目录共 30 个规范化工具（如read_file、get_file_tree、file_search、apply_edits、agent_run、manage_worktree、context_builder等），完整定义见 docs/spec/mcp-domain-canonical-tool-definitions.generated.json。

🚀 三种方式在 macOS 上快速安装

方式一：Homebrew 安装签名公证版（推荐）

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

方式二：本地生产版安装脚本

双击仓库根目录的 Install RepoPrompt CE Local Production.command，它会把 release 版应用安装到/Applications。注意：该版本仅供本机使用，不可分发到其他 Mac。

方式三：源码构建（面向贡献者）

要求 macOS 26+ 与完整 Xcode 26（仅 Command Line Tools 不够），可用 Scripts/doctor.sh 检查工具链。克隆仓库后即可：

git clone https://gitcode.com/gh_mirrors/re/repoprompt-ce make xcode # 生成并打开 Xcode 贡献者工作区

Xcode 工作区的生成与边界规则详见 docs/architecture/xcode-workspace.md。

🔌 让外部 AI 代理接入：内置 MCP 服务器

RepoPrompt CE 不只是"人用的 GUI"，它还是一个代理可用的上下文后端。内置的repoprompt-mcp支持三种会话后端：

repoprompt-mcp --backend app # 经由已运行的 App 代理（stdio 默认） repoprompt-mcp --backend headless # 无界面直连运行时 repoprompt-mcp --backend auto # 一次性探测后锁定后端

• headless 模式完全不依赖 AppKit/SwiftUI 与窗口，可独立在 CI 或脚本中运行，运行时核心位于 Sources/RepoPromptDomainRuntime/，设计文档见 docs/architecture/headless-mcp-runtime.md；
• 长任务进度上报：context_builder、Oracle 等耗时工具支持标准 MCPprogressToken，客户端可以实时看到"模型解析中、响应流式输出"等阶段，规范细节见 docs/mcp-progress.md；
• 受保护变更默认拒绝：文件编辑走统一的 apply-edits 引擎，带路径围栏、审批和重试分类，防止代理越权写入。

🌳 为代理准备"隔离施工区"：Worktree 机制

代理改代码时最怕弄脏你的主工作区。RepoPrompt CE 支持为代理创建应用管理的 Git worktree，并有几个贴心的细节：

• APFS 写时复制克隆：新 worktree 的已跟踪文件与源检出共享磁盘块，几乎不额外占空间；
• .worktreeinclude本地文件拷贝：在仓库根目录创建该文件（.gitignore语法），代理的 worktree 会自动带上.env.local等"被忽略但开发必需"的本地文件；
• 完整规则与安全边界见 docs/worktrees.md。

📂 项目代码结构速览

项目采用 Swift Package Manager 组织，边界划分非常清晰，值得参考：

• Sources/RepoPrompt/ —— App 主体：Features/（AgentMode、ContextBuilder、Chat、Prompt 等功能模块）与Infrastructure/（AI、文件系统、VCS、安全存储等）；
• Sources/RepoPromptDomainRuntime/ —— 无 AppKit 依赖的 MCP 领域运行时与规范化工具注册中心；
• Sources/RepoPromptCodeMapCore/ —— 确定性的代码结构解析与查询核心；
• Sources/RepoPromptMCP/ 与 Sources/RepoPromptMCPCore/ —— 薄入口repoprompt-mcp可执行文件及其实现库；
• Sources/RepoPromptFileSystem/、Sources/RepoPromptVCS/ —— 文件系统与 Git/worktree 可复用底座；
• Packages/RepoPromptAgentProviders/ —— 代理提供方插件包（Claude 兼容家族），插件机制详见 docs/architecture/provider-plugins.md。

完整的模块归属与放置规则文档：docs/architecture/source-layout.md。

📚 延伸阅读与资料路径

• 架构总览：docs/architecture/（含模型路由 model-routing.md、设置持久化 settings-persistence.md）
• 贡献指南：CONTRIBUTING.md、AGENTS.md
• 构建入口：Makefile；开源就绪与第三方许可清单：docs/open-source-readiness.md、ThirdPartyLicenses/

写在最后

RepoPrompt CE 把"上下文工程"这个抽象概念做成了一个可触摸的 macOS 产品：你在 Context Composer 里看到的每一行上下文，都是代理将要读到的内容。如果你正在用 Codex、Claude Code 等代理做日常开发，它提供了从"投喂仓库"到"精调上下文"之间的完整工具链——而且完全免费、开源。