人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载分支预览Branch Preview Build是 CodePilot 在正式合并 main 之前把某个 worktree 分支打成安装包、交给少量测试用户先行验证的一种发布形态。本文以仓库中 docs/preview/branch-preview-2026-05-31.md 为骨架结合docs/exec-plans/completed/preview-build-readiness.md执行计划、electron-builder.yml、preview-build.yml 以及src/lib下的运行时实现完整还原这套流程预览包的定位与边界、版本单源策略、安装/备份/回滚、Windows 交叉构建陷阱、P0/P1/P2 反馈闭环以及打包后运行时故障的分诊方法。读完本文你将掌握 CodePilot 分支预览包从打出来到安全发给测试用户的全部操作步骤与源码级验证手段。预览包的定位为什么不直接合并 main当一次大规模重构worktreeproduct-refactor-research尚未达到合入 main 的完成度时CodePilot 的做法不是继续闷头开发而是先把当前分支打成小范围预览包让少量用户提前验证新视觉、Runtime 引擎与 MCP 能力。这一决策记录在 docs/exec-plans/completed/preview-build-readiness.md 的背景与目标中macOS 只打 Apple Siliconarm64Windows 只打 x64macOS 负责验证新视觉 / Runtime / MCP 能力Windows 负责验证跨平台基础体验。预览包必须满足以下边界任何一条都不可妥协不合并 main预览分支停留在独立 worktree 上。不推送正式 release、不开启自动更新预览包不是稳定版也不走自动更新渠道electron/updater.ts 中的自动更新在运行时不检查更新。明确标注 Preview 性质测试用户拿到的是 Beta 包而非静默覆盖稳定版反馈目标是 Runtime / MCP / Windows / macOS 视觉与通知。不把 deferred 能力包装成已完全支持例如默认模型不切opus只保留显式opus-4-8不自动开启高副作用能力。预览包标识信息以 2026-05-31 批次为例分支worktree-product-refactor-research、Commit2606371、版本0.53.0。注意这一批次后来被整体废弃原因见下文 P0 复盘真正可发的版本必须高于0.54.0且版本号全链路一致。一次失败的复盘0.53.0 预览包为何被废弃2026-05-31 的本地预览包被标记为 已废弃 / 不分发直接原因来自用户安装后的三个 P0 信号详见 preview-build-readiness.md 的 2026-05-31 P0 复盘版本仍显示 0.53打包时只用了electron-builder --config.extraMetadata.version0.55.0-preview.2临时覆盖 Electron 包元数据而仓库package.json仍是0.53.0。应用内多处读取package.json/NEXT_PUBLIC_APP_VERSION/ packaged standalone 里的版本导致 Info.plist 与 UI / runtime clientInfo 不一致。结论禁止只靠 extraMetadata 做 preview 版本。Codex app-server 启动失败packaged app 仍在用旧参数启动codex app-server --listen ...真实 Codex 0.133 报unexpected argument --listen found——说明安装包没有包含当前 P0 修复坏包是6923f13之前的过时构建。ClaudeCode 输入框长期停在正在准备运行环境日志显示Claude Code compat API error: 503 model_not_found裸sonnet短别名落到错误的渠道分组。复盘结论成为后续所有预览包的硬约束必须先修版本源、确认打包 commit、再跑 packaged app 真实启动 smoke任何没跑 packaged Runtime smoke 的本地临时包都不得再分发。这也直接催生了下一节介绍的版本单源策略与 CI 打包工作流。版本单源策略让所有版本读取点指向同一个 package.json预览包最容易犯的错误是看起来成功、实包不可用的假阳性。为此 CodePilot 确立了P0 版本单源规则打包前用 commit 修改package.jsonpackage-lock.json到0.55.0-preview.N或用户指定版本禁止只用electron-builder --config.extraMetadata.version覆盖。NEXT_PUBLIC_APP_VERSION由 next.config 派生、app.getVersion()Info.plist、Codex clientInforeadCodePilotVersion读 pkg.version必须全部从 package.json 同一来源派生。打包完成后用 packaged app 验证四处一致plutil读CFBundleShortVersionString、app 内 About 显示、/api/app/updates当前版本、codex app-server initialize的clientInfo.version。preview-build.yml中version-patch-auditjob 把这一步做成可审计的流程用npm version ${{ inputs.preview_version }} --no-git-tag-version --allow-same-version打补丁随后把package.json/package-lock.json的 diff 和三个版本源lock root、lockpackages[]一并上传为 artifact供评审者核对预览版本到底动了哪些字节。安装前必读数据目录、备份与回滚预览包沿用正式版数据目录与 app identityappIdcom.codepilot.app、productNameCodePilot、~/.codepilot因此它会替换当前 CodePilot并读取 / 迁移现有数据。安装前必须退出 CodePilot备份~/.codepilot/codepilot.dbmacOS 如使用了 Application Support 数据一并备份~/Library/Application Support/CodePilot不要同时运行正式版和预览版回滚方式 重新安装稳定版并在需要时恢复备份的codepilot.db。为什么要备份数据共享的风险点在于数据库迁移。从 src/lib/db.ts 的源码看迁移采用PRAGMA table_info按列存在性做增量迁移49 个ALTER ADD 41 个CREATE IF NOT EXISTS没有user_version单调版本门也没有schema 太新即拒绝的上界——stable 打开被 preview 向前迁移过的 DB 不会被拒只补自己认识的列、忽略多出的列/表因此回滚基本安全。残留风险有三项试用说明必须写明安装替换用户 stable app回滚 重装 stable 包DB 向前迁移基本可回滚不保证 100%db.ts中一条非纯增量迁移DELETE FROM api_providers WHERE protocolopenai-compatible会清掉该类 provider可重加。如果未来需要 preview 与 stable并存 / 零数据触碰才考虑完全隔离方案独立productNameCodePilot Preview 独立appIdCLAUDE_GUI_DATA_DIR~/.codepilot-preview。当前决策是共用 明确告知 备份指引。2026-05-31 批次包状态与签名说明平台架构包SHA-256状态macOSApple Siliconrelease-preview-2026-05-31/CodePilot-0.53.0-preview-2026-05-31-arm64.dmg7965d9f51df41814c86785d0a16cc64966f5a9dc1692f35e0c10ee684ed285a8 已废弃 / 不分发0.53.0 旧版 过时构建仅诊断样本macOSIntel x64release-preview-2026-05-31/CodePilot-0.53.0-preview-2026-05-31-x64.dmgbe65141fd48643439f0d95a9cd94e56cd3e5fe2ed686cf91a8096d22bd351bd0 已废弃 / 不分发同上Windowsx64待 Windows 机器本地构建待补⏳ 不能在 Mac 上交叉构建可用包这批 macOS 包是ad-hoc signed、没有公证。首次打开可能需要右键打开或在 System Settings → Privacy Security 里允许打开。release/目录里那批 Developer ID 构建签名校验失败codesign --verify --deep --strict不通过不给测试用户使用以release-preview-2026-05-31/目录为准。macOS 的 ad-hoc 签名由 scripts/after-sign.js 的 afterSign 钩子执行顺序严格由内向外① 全部原生二进制.node / .dylib / .so→ ② Frameworks 内无扩展名可执行 helper如chrome_crashpad_handler这正是 x64 本地 ad-hoc 签名失败的根因→ ③ 所有.framework→ ④ 所有 Helper.app→ ⑤ 主.appbundle最后codesign --verify --deep --strict校验。签名策略由 scripts/macos-signing-policy.cjs 的resolveMacosSigningMode决定有 Developer ID 证书CODEPILOT_REQUIRE_DEVELOPER_ID1时只验证不重签无证书且显式允许CODEPILOT_ALLOW_ADHOC_SIGNING1时才走 ad-hoc。Windows 构建步骤为什么必须在 Windows 机器上打Windows 包必须在 Windows 机器或 Windows CI 上构建。原因在 scripts/after-pack.js 与preview-build-readiness.mdPhase 2 中都写得很清楚better-sqlite3是原生模块需要目标平台的 Electron ABI 重编译macOS 无法交叉编译出可用的 Windows 版.node在 Mac 上electron:pack:win的产物会带 Mac 二进制 → Windows 一读 DB 即崩。从同一 worktree / commit 构建的命令在 Windows 机器或 Windows CI 上cd product-refactor-research-worktree npm install npm run build npx electron-builder --win --x64 --config electron-builder.yml对应 package.json 中的脚本是electron:pack:winnpm run electron:build electron-builder --win --config electron-builder.yml其中electron:build会先跑prepare-macos-universal-runtime、next build与build-electron。Windows 侧打包配置见 electron-builder.yml 的win/nsis段NSIS 目标、oneClick: false、allowToChangeInstallationDirectory: true让用户选择安装位置、differentialPackage: true、forceCodeSigning与 RFC3161 时间戳服务器。Windows 验收必须在真机完成安装 NSIS 包并启动打开 Chat / Settings → Runtime / Models / Plugins让 Agent 生成创建目录并写文件的命令确认默认是 PowerShell / Windows 兼容语法确认没有把 macOS 的 shell / 路径 / 视觉假设带到 Windows。Windows shell 方言的源码实现预览包要堵住的核心失信问题之一是Windows 版 Agent 生成 bash 命令。修复落在 src/lib/platform.tsgetPlatformShell()win32 默认返回powershell只有用户显式设置CLAUDE_CODE_GIT_BASH_PATH时才返回 bash——检测到 Git Bash 就允许 bash是错误信号因为 Git for Windows 几乎人人都有但多数人把命令粘贴进 PowerShell 而不是 bash。WSL 上报platformlinux走 linux 分支不属 win32 关注范围。platformCommandGuidance()仅在 Windows 默认 PowerShell 时返回非空字符串注入系统提示词要求模型生成的命令必须是 PowerShell / Windows 兼容语法并明确列出禁用词rm -rf、export VAR...、source、/tmp、mkdir -p、链、$VAR与替代写法Remove-Item -Recurse -Force、$env:VAR ...、New-Item -ItemType Directory -Force、$env:TEMP、;或分行。该函数纯 可覆盖设计使其可被单测process.platform只读通过opts覆盖平台 / bash 是否 opt-in / shell env对应单元测试见 src/tests/unit/platform-shell.test.ts。构建环境的两处必须与一处恢复陷阱Windows 必须在windows-latest构建preview-build.yml的build-windows-x64jobbetter-sqlite3/zlib-sync等原生模块的正确平台。macOS arm64 用固定的 Apple Silicon runnermacos-15不用浮动的macos-latest保证可复现。本地打多架构的恢复陷阱在 Apple Silicon 机器上构建 x64 macOS 包会让 afterPack 把 worktree 的node_modules/better-sqlite3重编成 x64打包后必须执行npm rebuild better-sqlite3恢复 host 架构否则本机单测会因ERR_DLOPEN_FAILED失败。afterPackstandalone 原生模块的 Electron ABI 重建scripts/after-pack.js 解决了一个隐蔽问题标准electron/rebuild只重建files配置里的原生模块而better-sqlite3是通过extraResources.next/standalone/进入 app 的会被跳过。该钩子显式执行npx electron-rebuild -f -o better-sqlite3,zlib-sync -v electronVersion -a arch把 standalone 树里的原生模块重编为目标 Electron ABI而非 host Node ABI校验每个重建的.node文件存在遍历standalone/下所有资源位置macOS 的Contents/Resources/standalone、Windows/Linux 的resources/standalone用重建产物替换所有同名.node文件。这就是为什么 packaged app 里ELECTRON_RUN_AS_NODE1 binary -e require(.../better-sqlite3)必须打印 Electron ABI如143并成功加载——ABI 不匹配如127意味着该包没走正确的打包流程诊断文档中 preview.1 的失败正是NODE_MODULE_VERSION 127 ... requires 143。测试重点P0 / P1 / P2 分级预览包反馈必须分级优先 P0 / P1视觉细节P2可以后置级别定义示例P0无法继续测试或可能损坏数据无法安装 / 无法启动 / 现有会话丢失 / 数据库损坏 / 无法回滚 / 登录凭据丢失P1核心路径不可用无法发送消息 / Runtime 切换错误 / Provider 不可用 / Codex MCP 能力不可用 / Windows 命令不可执行 / macOS 通知完全无 fallbackP2可绕过但影响体验视觉错位 / 文案不清 / 轻微交互问题 / console 已知 noise建议 Smoke 清单拿到预览包后按以下顺序冒烟覆盖数据保留、默认 Runtime、能力清单、Codex 生态路径与通知链路安装并打开预览版确认旧会话、Provider、模型、素材库还能看到用当前默认 Runtime 发一条普通消息打开 Settings → Runtime确认能力清单与当前引擎一致如果你使用 Codex Account测试 Memory / Widget / Tasks / Dashboard / CLI 任意 2-3 条路径创建一个 3 分钟定时提醒确认 app 内 toast 或 macOS 系统通知至少一种可见如在 Windows额外测试 PowerShell 命令生成。反馈表模板反馈必须结构化避免混成一堆聊天记录。标准模板如下原文完整保留测试人 / 联系方式 系统版本 架构 安装包路径 / SHA 是否使用已有 CodePilot 数据 安装前是否已备份 严重级别P0 / P1 / P2 一句话标题 复现步骤 1. 2. 3. 期望结果 实际结果 截图 / 录屏 / 日志 是否稳定复现 临时绕过方式 是否阻塞继续测试preview-build-readiness.md的 Smoke Ledger 要求跑了真实 smoke 必须追加一行且必须写平台 / runtime / provider / 场景 / 结果 / 证据不能只写我试了可以。可复现打包基础设施preview-build.yml 与四道 Gate为了让预览包不依赖某台开发机的本地状态、临时 config 或手工记忆仓库新增了独立于正式 build.yml 的 .github/workflows/preview-build.yml。它只在workflow_dispatch手动触发输入三个参数preview_version必须是合法 semver且 0.54.0默认0.55.0-preview.3build_macos_arm64/build_windows_x64布尔开关分别产出 macOS 与 Windows 包commit_sha要构建的 commit留空则用触发 ref。工作流权限contents: read只上传 workflow artifacts不建 Release、不推 tag、不走 stable auto-update feed。它内置四道 fail-closed GateGate 0validate-inputs校验preview_version是合法 semver 且 0.54.0否则直接拒绝构建——避免0.53.1这类手误复现包显示旧版本的 P0。Gate Averify-sourcegit merge-base --is-ancestor 6923f13 HEAD必须包含 Codex/ClaudeCode 启动修复 grep 确认src/lib/codex/app-server-manager.ts不再出现--listen。设计要点是 gate 步骤从**本 workflow 文件触发 ref**运行并直接检查 checkout 出来的文件而不是信任目标 commit 自己的测试——过时 commit 的回归 pin 尚不存在其测试会自洽地通过必须由外部 gate 兜底。Gate BClaudeCode sonnet 别名规范化用tsx以静态 import 方式运行checkout 出来的src/lib/provider-resolver.ts的toClaudeCodeEnv断言裸sonnet被规范化成ANTHROPIC_MODELclaude-sonnet-4-6防止回退到503 model_not_found。版本补丁审计version-patch-auditnpm version打真实 package.json/lockfile 补丁并上传 diff。macOS jobbuild-macos-arm64用macos-15runner先配置 fail-closed 的 Apple 公证凭据缺失即失败然后npm run electron:build、分别electron-builder --mac --arm64 --x64与--universal出更新包、notarize-macos-dmgs.mjs公证并 staple DMG最后依次校验DMG 文件名含预览版本、Info.plist的CFBundleShortVersionString等于输入版本、verify-macos-developer-id、verify-macos-notarization、better-sqlite3 在 packaged Electron 下加载ABI 校验、verify-packaged-server.mjsverify-electron-main-health.mjs启动验证、SHA-256 清单。Windows jobbuild-windows-x64在windows-latest上配置 fail-closed 签名凭据PFX、密码、Publisher Subject 缺一即失败→npm run electron:buildelectron-builder --win --x64→ 校验 NSIS 安装包文件名含版本 → ABI 校验 → packaged 启动验证 →verify-windows-signing.ps1验证 Authenticode 签名与时间戳 → SHA-256 清单。打包后运行时故障诊断三个症状一个根因preview 包最大的坑在于开发态正常、packaged 态启动失败。仓库为此沉淀了完整的诊断方法论详见 docs/research/packaged-preview-runtime-diagnosis-2026-05-31.md核心要点如下。打包态 PATH 与二进制发现从访达 / Dock 启动的打包 Electron不继承 shell 的完整 PATH不读~/.zshrc裸 PATH 只有/usr/bin:/bin:...。CodePilot 的补救启动时跑 login shell 读userShellEnvgetExpandedShellPath()并注入 Next server 子进程electron/main.ts的startServerenv 包含扩展后的 PATH 与HOME。findCodexBinary()的查找顺序是CODEX_DISABLED→CODEX_BIN→ 遍历扩展后的process.env.PATH→ macOS bundle fallback/Applications/Codex.app/Contents/Resources/codex。Codex 应用服务启动失败 spawn_failed 的三产生点Settings → 执行引擎里显示启动失败不等于未安装——能到spawn_failed说明findCodexBinary已经找到二进制。src/lib/codex/app-server-manager.ts中spawn_failed有三个产生点各自对应不同 reason#位置reason 形态含义1spawn 抛spawn ENOENT/EACCES/EINVAL找到的路径不对 / 不可执行 / env 异常2子进程启动后 exitexited with codeX signalY二进制跑起来又立刻退出——旧版本没有app-server子命令 / 仍带--listen的过时构建 / 启动期 panic3initialize 抛Codex app-server initialize failed: …app-server 起来了但 JSON-RPC initialize 握手失败协议 / 版本不匹配 / 超时屏幕上Codex 应用服务启动失败这一句基本就能定到上表四行之一若含--listen→ 过时构建走 preview-build.yml 重打Gate A 会挡若无--listen但exited with code→ 安装的 Codex 太旧若是initialize failed→ 协议/版本不匹配需单独适配。三个症状的统一根因30s RPC 超时正在准备运行环境 / 模型加载中问题 A、Settings 页面几十秒才加载问题 C、Codex 启动失败问题 B在 2026-06-01 被定位为同一个根因取模型列表GET /api/providers/models在runtimeauto或无 runtime 时命中 Codex 分支 →getCodexAppServer()冷启 spawn initialize→listCodexModels()而 src/lib/codex/app-server-client.ts 的请求超时是30_000msinitialize与listModels各走一次。只要 Codex app-server 的 RPC 不响应聊天输入框useProviderModels、Settings 概览useOverviewData、Runtime 面板RuntimePanel都会卡满 30s。关键分诊如果 Settings 卡几十秒说明 app-serverspawn 起来了但 initialize 握手 hang 到超时更可能是协议/版本不匹配而非过时构建过时构建的--listen会立刻退出、快速失败Settings 不会卡。治本修复2026-06-01 已提交CodexTransport增加可选onCloseclient 在attach()订阅进程死时handleClose()立即 reject 所有 pending并置closed不再让每个请求干等 30smanager 的makeStdioTransport在exit/error时fireClose()并对已关闭后才订阅的 client 同步回放消除竞态。回归测试codex-app-server-client.test.ts用真实 30s 超时配置断言 close 后 reject 耗时 1000ms。另有一个防御性修复新增src/lib/codex/effort.ts的clampCodexEffort把xhigh/max钳制到high绝不外发 Codex 不认识的档位只作用于 codex_runtime不碰 Claude Code / Native。ABI 不匹配与 sonnet 别名ABI 不匹配preview.1 包报NODE_MODULE_VERSION 127 ... requires 143——better-sqlite3 没重编到 Electron ABI。走preview-build.yml含 native ABI 校验步骤出包即可杜绝。ClaudeCode sonnet503 model_not_found ... 分组 auto 下模型 sonnet 无可用渠道属于 provider 侧网关配置网关要有对应渠道 短别名规范化。6923f13已让toClaudeCodeEnv把裸sonnet规范化为claude-sonnet-4-6Gate B 与回归 pinsrc/tests/unit/provider-resolver.test.ts持续守护。合入门槛Go / No-go 标准预览包反馈闭环完成后是否合入 main 有明确的 go/no-go 标准不用感觉差不多拍脑袋。两道门要分开来自 2026-05-29 的 Codex review①Ship-to-testers 门槛能不能发预览包给用户 Phase 1 blocker 全关 两平台安装 smoke 各一轮 数据隔离方案已定 签名/绕过说明就位②Merge-to-main 门槛下面的 Go 标准 试用反馈 P0/P1 关闭后才评估。先过 ① 才发包试用后再谈 ②。Go 标准Phase 1 blocker 全部关闭macOS Windows 预览包各至少一轮真实安装 smoke三 Runtime 核心路径 smoke 无 P0/P1Settings Runtime 能力清单与实际能力没有明显相反承诺已知问题写入 release notes / tech-debt tracker用户确认可以合 main。No-go 标准任一命中即不合任一平台包无法启动预览包 app 内仍显示0.53.0或任何低于0.54.0的版本macOS packaged app 日志出现codex app-server的旧--listen参数ClaudeCode packaged app 仍卡在正在准备运行环境或默认sonnet解析到model_not_foundWindows 仍默认输出 bash-only 命令Mac 定时任务仍静默无通知 / 无 fallbackRuntime 选择 UI 与实际运行 runtime 不一致Provider / model resolver 出现用户无法自行恢复的错误不隔离时未在试用说明告知preview 会替换 stable 改其数据、需先备份~/.codepilot/codepilot.db外部测试用户因 Gatekeeper / SmartScreen 打不开包且未提供绕过指引。已知边界与分发纪律macOS 未公证包属于内部预览验证外部 Mac 被 Gatekeeper 拦截时给出绕过指引右键打开 /xattr -dr com.apple.quarantineWindows「更多信息 → 仍要运行」。Windows 包尚未产出时必须 Windows 侧补构建与真机 smoke不能用 macOS 结果代替 Windows 结果。预览包不自动更新、不合 main、不推正式 release。这次测试目标是发现 P0/P1不要求所有 P2 视觉细节一次收口。生成物输出目录采用release-*命名并加入.gitignore与tsconfig.exclude——Electron 包内含standalone/源码副本若留在 worktree 根目录被tsc扫入会把包内站点源码误当仓库源码检查导致npm run test失败。整个分支预览流程的启示在于预览包不是打个包发出去这么简单它是一条从版本单源、数据迁移评估、跨平台构建约束、packaged 运行时 smoke、结构化反馈到合入门槛的完整质量链路。对于任何想在合入主干前安全试错的多平台 Electron 桌面应用CodePilot 这套流程与 CI 门禁都值得作为参考模板。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐CodePilot 分支预览包Branch Preview Build发布前收口实战版本单源、打包态 Runtime P0 修复与双平台发布门槛CodePilot 分支预览包Branch Preview Build发布前收口实战版本单源、打包态 Runtime P0 修复与双平台发布门槛 本文整理人工智能AI 应用AI Agent交互助手MCP Clients本地部署Pulse Cloud Hosted Tier 运行时就绪度验证从本地化预演到发布门禁 RA11 的完整证据链Pulse Cloud Hosted Tier 运行时就绪度验证从本地化预演到发布门禁 RA11 的完整证据链 导读 本文以 Pulse 仓库发布管控记录 c可观测性运维后端最完整的OpenCode包发布指南从NPM分发到版本管理最完整的OpenCode包发布指南从NPM分发到版本管理 你还在为开源项目的NPM包发布流程繁琐而烦恼吗手动更新版本号、生成变更日志、处理多包依赖关系这些人工智能AI 应用AI Agent代码智能体CLI开发者工具上一篇B站成分检测器一眼看穿评论区用户的真实身份下一篇B站成分检测器技术解析基于用户行为分析的智能标签系统实现方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考