人工智能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点击查看免费下载本文基于 memory-runtime-decoupling.md 执行计划结合 CodePilot 仓库源码Electron Next.js 多模型 AI Agent 桌面客户端讲解其 Memory 系统如何从「两套 Memory handler、依赖具体 Runtime SDK」演进为「无 Runtime SDK 依赖的共享核心 三 Runtime 薄适配」以及辅助调用自动抽取、Quick actions、AI 重排如何修复凭据误判、未知错误分类与重复上报问题。读完本文你将掌握 Memory Core 的查询/记录/生命周期分层设计、memory/records.md事实源与 CAS 写入模型、助理工作区绑定作用域以及「仅 credentials 等待配置变化、429 与其他 4xx 有界冷却」的故障处理策略并能在自己的多 Runtime 客户端中复现这套解耦方案。一、问题背景与设计取舍1.1 用户反馈的三个核心问题该执行计划源于 2026-09-21 用户明确授权修复的一批问题核心诉求有三Sentry 免费额度耗尽遥测系统存在 settings-only 凭据能力误判、unknown 分类和重复上报导致无效事件挤占额度Memory 必须 Runtime 无关用户要求 Memory 不因 Claude/Codex/Native 三种 Runtime 的不同而行为不一致不通过隐藏错误或另装 Memory 引擎解决修复必须直面根因而非掩盖或替换。此前已审阅的原因报告确认了六个具体缺口settings-only 凭据能力误判、unknown 分类和重复上报、两套 Memory handler、路径边界/全文漏召回、抽取生命周期和来源更正遗忘缺口。1.2 关键取舍决策计划明确了实施红线详见执行计划保留用户 Markdown 与已有会话抽出无 Runtime SDK 依赖的共享核心模型增强明确能力与状态基础记忆无模型也可用——这是Memory 不依赖任何 Runtime的落点单一写入与来源回执替代字符串猜测——模型口头说已记住不再算保存证据不同 Runtime 协议可以不同但数据/scope/权限/结果语义必须一致原生会话 owner 不变无关的 Gemini/UI 改动原样保留不混合提交。该计划最终随v0.67.17发布不可变 tag 指向4ddcd1a0f7931fc2ba3d3a1cf2802782bdc4712e正式 CI 七个 job 全部 success全量测试5704 pass / 0 fail / 1 skip。计划明确不把发布事实补记为 Smoke passed / Release ready——真实账号三 Runtime 记忆端到端、打包客户端人工流程仍未执行这一严谨边界贯穿始终。二、总体架构Memory Core 三 Runtime 薄适配 辅助执行2.1 三层架构从守护契约与源码结构可以清晰看到分层层关键文件职责依赖Memory Corememory-service.ts、memory-records.ts、memory-binding.ts查询/读取/写工具的共同 contract 与 handler、Markdown 事实源、CAS/幂等/更正/撤销/锁、助理作用域仅 fs/zod/用户文件无 Agent SDK、AI SDK、凭据、网络、数据库依赖协议适配层memory-search-mcp.ts、builtin-tools/memory-search.ts、codex/proxy/builtin-bridge.tsNative / Claude MCP / Codex proxy 的薄适配各自 Runtime 协议但不得另写检索业务可选增强层auxiliary-provider.ts、memory-rerank.ts、memory-lifecycle.ts模型能力、policy、瞬态冷却、AI 重排、自动抽取 jobAI SDK 等仅作为可选增强不可用时基础功能照常memory-service.ts文件头注释直接写明Runtime-neutral local Memory queries. This module has no Agent SDK, provider, credentials, network, or database dependency. Adapters only marshal its tools.2.2 三 Runtime 一致性原则约束来自计划设计与执行约束与守护契约第 2 节查询核心不 import Claude Agent SDK / AI SDK参数、1-based 行号、排序、预算、路径 realpath、来源格式三端一致默认确定性排序可选模型增强必须显式使用统一能力接口同一 fixture 经 Native、MCP 与 proxy 的实际 handler 返回一致不能只看函数同名——这一条对应测试codex-builtin-bridge-parity.test.ts等 parity 套件。三、事实源与记录模型memory/records.md3.1 用户可读 Markdown 即事实源计划明确用户可读 Markdown 为记忆事实源索引可重建。对应 memory-records.ts唯一事实源路径为memory/records.mdMEMORY_RECORDS_PATH带文件头!-- memory-records:v1 --每条记录是!-- memory-record metadata --\ncontent\n\n格式metadata 含contentLength与记录字段正文长度由 JSON 中的contentLength精确界定active 投影readActiveMemoryProjection将 active 记录渲染为虚拟memory/records/id.md供模型检索索引可随时从事实源重建旧索引路径别名也被过滤为私有历史防止 superseded/revoked 内容复活为有效事实。3.2 原子写入CAS 单写者锁 fsync写入路径mutateLocked实现了一套严格的持久化协议绝对路径与符号链接校验locations()拒绝非绝对路径、非目录工作区、符号链接目标单写者锁memory/.records-lock以wx排他创建0o600内含{machineId, pid, nonce}时间流逝本身不能证明写者崩溃只有同机、未变、进程被 OS 证实死亡的 lease 才可回收deadLocalLeaseCAS 乐观并发写入前比对expectedRevisionsha256(root\0raw)落盘前再次重读校验 revision防止外部编辑被覆盖原子替换与双 fsync先写临时文件memory/.records-uuid.tmp并 fsync再renameSync替换正式文件随后尝试目录 fsyncWindows 不支持则忽略EINVAL/EPERM等容量上限 2 MiBMAX_BYTES硬限制写入前预检assertMemoryStorageWritable预留 32 KiB满额时返回capacity错误提示忘记无用记录而非让用户清空 tombstone。3.3 记录生命周期remember / update / forgetMemoryRecord具有status: active | superseded | revoked、rootId根记录族、operationHash幂等标识、supersedes替代关系等字段remembersaveMemoryRecordCandidates批量保存 1–40 条同一operationHash幂等去重同 key 不同内容/来源则抛conflictupdate更正correctMemoryRecord将旧记录标记superseded并新增 active 新版本新记录operationHash hash(correction:id:expectedRevision:content)、supersedes指向旧 idforget忘记revokeMemoryRecord将该rootId族的所有版本置为revoked并清空正文——更正/撤销不得在索引、recent、上下文或自动抽取中复活正文清空 来源 tombstone 双保险tombstone 同时阻止自动抽取因同一来源再次写入secret 防护validateContent通过findSecretLeaks拒绝含凭据/密钥的内容secret错误码避免把 API key 写进记忆。错误类型统一为MemoryRecordError的九个 codeconflict / invalid / secret / unsafe_path / busy / not_found / capacity / corrupt / storage管理 UI 据此显示中英文精准文案。四、查询核心正文召回、路径边界与预算4.1 搜索工具集memory-service.ts 提供三个读工具createMemoryQueryTools与三个写工具createMemoryMutationTools工具作用关键参数codepilot_memory_search关键词/标签/文件类型过滤 时域衰减 可选 AI 重排query(1–2000)、tags(≤20)、file_type(all/daily/longterm/notes)、limit(1–20)codepilot_memory_get按来源路径读取1-based 行号、char_start续读file_path、line_start、line_end、char_start(≤512 KiB)codepilot_memory_recent每轮开头的 long-term/daily/active 回顾days(1–7默认 3)codepilot_memory_remember保存事实返回memory_write_receiptcontent(1–16000)、idempotency_keycodepilot_memory_update更正 active 记录id(UUID)、content、expected_revision(64 位 hex)codepilot_memory_forget撤销全部版本id、expected_revision4.2 正文召回而非标题过滤关键设计对应计划全文漏召回缺口搜索先收敛到正文再按 manifest 过滤——prepareSearch中先searchWorkspaceSnapshot全文检索随后才应用 file_type/tags 过滤与时域衰减防止标题唯一命中被 manifest 先筛掉。时域衰减applyMemoryTemporalDecay匹配YYYY-MM-DD.md命名的 daily 文件按 30 天半衰期衰减score * exp(-ln2 * age/30)新近记忆天然靠前且默认确定性排序、同分按路径字典序。4.3 路径安全与扫描预算normalizeRelativePath拒绝绝对路径含 Windows 盘符路径、\0、..越界readLocalFile每次读取都realpathSync校验防止 symlink 逃逸.assistant、.git与受管记忆私有路径memory/records/、memory/.records-一律不可作为查询内容privatePath扫描预算硬性封顶最多512 文件 / 8 MiB / 10000 目录项、单文件 512 KiB、深度 12超出明确返回Partial search: ...警告并建议用memory_get定向读取——避免大型目录无限占用内存长单行支持字符分页get每次返回 3000 字符next_char_start指示续读位置响应总量截断 12000 字符。4.4 确定性降级与 AI 重排AI 重排memory-rerank.ts是可选项createMemoryReranker仅在能捕获明确辅助路由时返回否则undefined搜索直接走关键词排序。重排约束严格模型只能对已过滤、有界的候选集≤20 条做排列返回 JSON 数组须恰好包含每个候选 index 一次超时3s、非法 JSON、缺失/重复 index、抛出异常 → 全部确定性降级并说明原因基础检索仍有结果不换 Provider、不吞掉真实产品异常。五、作用域与绑定仅助理工作区启用5.1 绑定语义memory-binding.ts 明确Memory scopes belong to CodePilot sessions, never to a Runtime. 关键判定bindAssistantMemory(sessionId)仅显式助理入口调用要求canonicalMemoryWorkspace(session.working_directory) 配置的 assistant_workspace_pathtask 来源会话拒绝绑定cwd 相等不是绑定意图getAssistantMemoryWorkspace读 getter不写 DB不因读取回填设置绑定持久化于 settings 的memory.assistant-binding.sessionIdversion 1或依赖runtime_binding_source assistant_session_create这一持久显式来源普通项目不挂载 Memory 工具、不追加每轮 recent 指令、不自动扫描或创建memory/records.md旧版按 cwd 识别的助理会话仅升级时一次性迁移assistant-memory-migration.ts启动事务回填不改变会话 Runtime owner之后新普通会话不再按 cwd 猜身份目录切换事件立即清旧标识并重新读取失败清状态。5.2 写权限与 PlancanWriteSessionMemory在执行时重查 mutable session scope 与 Plan 模式Plan / heartbeat 只挂读工具不宣称写能力memory_write是单独 capabilityClaude 不能整服 auto-allow精确放行 read3 个读工具Codex 写操作走独立 MCP server 审批codex-memory-mcp-route.test.ts覆盖Native 按实际已挂载工具过滤能力提示工具来源 session 从宿主上下文获取模型不能伪造来源模型返回的来源回执不被采信。六、生命周期与自动抽取6.1 成功回合事件驱动memory-lifecycle.ts 实现durable, Runtime-neutral automatic memory jobs入队条件enqueueCommittedMemoryTurnsuccessful ownerValid !systemTurn entryPoint ! headless、用户消息非空、会话绑定助理工作区、session.mode ! plan、助手消息stream_status completed、来源对user.rowid assistant.rowid且是真实人类用户排除 task_run 与 heartbeat ack失败、取消、stale owner、save 失败、read-only、failed-write、system origin均不入队Bridge 走同一生命周期与终态判定共享stream-turn-outcome.ts的 sticky error/is_error/interrupted/inProgress 判定错误后成功帧不能反转。6.2 3 回合批次与 job 预算每会话每3 个成功回合生成一个批次批次覆盖前 3 回合全部真实来源pendingSources持久化前 2 回合崩溃可恢复job ledger 持久化于工作区.assistant/memory-jobs.json4 MiB 上限、5000 回合上限、损坏即报MEMORY_JOB_CORRUPT只存引用不复制聊天原文抽取系统提示词强制输出仅 JSON 数组max 8每项须含messageIdcontentevidenceevidence必须是该用户消息原文中的精确子串userText.includes(evidence)校验——杜绝模型凭空编造来源job attempts 预算最多 3 次生成尝试MAX_MEMORY_JOB_ATTEMPTS 3attempt 在模型执行前持久化重启/配置变化/手动 Retry 均不重置未发模型的 unavailable/cooldown 不计次耗尽显示unavailable / retry_exhausted并隐藏无效 RetrySDK 内部 HTTP retry 不计入 job 次数operationHash 恢复记录 batch 原子落盘后即使 job 未 settle重启也按operationHash digest(job.id:index)识别已提交操作并恢复为 completed不重复生成不同文本模型执行后再次重验绑定/Plan/来源source_changed则 skipped防止异步窗口内用户消息被编辑或会话切走。6.3 回执与成功判定memory-extractor.ts 的hasMemoryWritesInResponse规定只有memory_write_receipt且status saved、带非空 revision的 tool_result 才算成功写入读取、写入尝试、is_error、模型文字已记住一律不算。只有真实成功写入回执才能抑制该回合的自动抽取防止同一事实重复抽取但失败写入不会阻止后续抽取。七、辅助执行与故障分类修复7.1 统一执行器auxiliary-provider.ts 提供createAuxiliaryTextRunner统一承载三类辅助场景automatic_memory_extract/automatic_quick_actions/active_turn_memory_rerankroute snapshotcaptureAuxiliaryRoute一次捕获解析后的 Provider/config/fingerprint指纹routeFingerprint只含 CodePilot 自有 OAuth 状态绝不持久化明文 key 或无盐配置摘要私有 app-data HMAC可用性判定settings-only 凭据、transport 不可用、policy 拒绝分别映射为claude_settings_only/runtime_unsupported/policy_blocked有界冷却429/400/413 等非凭据 4xx 按cooldownMs * 2^min(failures-1,3)指数退避上限 300s并持久化retryAtin_flight防并发仅 credentials 持久阻断401/403、缺 key、OAuth 过期rootCause credentials才写 v2 持久回执blockAuxiliaryConfiguration等待配置身份变化后立即重新评估跨 scope/重启不按 300s 重试凭据回执写失败先保留内存 latchunsavedCredentialBlocks只重试持久化、不重复请求模型旧 v1 回执治理无法证明根因的旧user_action_required/configuration_required回执不再自行锁死忽略并重新分类——这正是遥测 outcome 不等于重试策略这一错误抽象的纠正。7.2 遥测降噪修复后缺 key 零 event、首个 unknown/5xx/产品异常可诊断、重复预算受控、suppressed 计数可见不再把缺 key 的固定 SDK 错误包装成 unknown 静默降级并重复上报。对应测试auxiliary-provider.test.ts、telemetry-provider-noise.test.ts。八、验证矩阵、Smoke 记录与发布8.1 验证矩阵六域正反例范围正例反例辅助执行明确 Native 配置成功、route snapshotsettings-only/无key/过期/策略禁止、不意外fetch或切厂商遥测首个 unknown/5xx/产品异常可诊断缺key零event、重复预算、无secret/body、suppressed计数查询正文唯一词、中文、标签、行号、recentsibling/symlink/private metadata、过大文件、空query记录手动保存/来源回查/更正/忘记stale revision、重复source、外部编辑、删除重建不复活生命周期desktop三Runtime/Bridge成功回合cancel/error/stale owner/save失败/read-only/failed-write/system origin作用域显式助理绑定、升级保留已有助理身份同名目录、目录等于assistant但无绑定、跨session伪造用户界面真正保存/更正/忘记、状态与错误无凭据仍基础可用、旧数据保留、无假成功8.2 Smoke Ledger 摘录DateRuntimeProviderModel凭据形态场景Result2026-09-21Web Dev / 隔离 DB无无未配置 ProviderSettings 助理 Memory保存→更正→忘记Smoke passed真实浏览器操作磁盘两版本正文已清除2026-09-21Native / MCP / Codex proxy无无无 key同 fixture 实际 handler 搜索/读取/最近记忆Tests pass非真实模型端到端2026-09-21AI SDK transport合成 AnthropicHaikusynthetic key生产 auxiliary→model factory→AI SDK 合成 SSETests pass不访问真实账号2026-09-22Web Dev / 隔离 DB本机合成 Anthropic辅助 Haikusynthetic keyQuick actions 401→429 冷却→恢复Smoke passed模型请求计数 1→2→3未执行Claude / Codex / Native 真账号———打包客户端真实模型自主调用/续聊未验证工具与 HTTP wire 不能替代8.3 测试与静态检查最终状态npm run test5704 pass / 0 fail / 1 skip5705 tests含 TypeScript 与 harness boundary定向复核生命周期/绑定事务 30/30、辅助执行器/Quick actions 32/32、辅助/遥测 53/53、重排 70/70、records/API/UI 错误码 22/22含双进程与 SIGKILL 恢复改动/新增 TS/TSX ESLint0 errors / 26 warnings现有大文件/unused 类警告lint:hooks、lint:docs-drift、git diff --check通过测试文件索引见守护契约第 6 节与src/__tests__/unit/下的memory-scope-entrypoints.test.ts、memory-rerank.test.ts、memory-records-recovery.test.ts、memory-lifecycle.test.ts、codex-memory-mcp-route.test.ts、codex-builtin-bridge-parity.test.ts等。8.4 发布与剩余边界v0.67.17 正式发布公开 Release 精确 20 个资产、checksum 逐一匹配 GitHub 资产 SHA-256、Mac feed 与 Windows feed 引用同版本产物、SHA-512 与实际下载字节一致证据目录/private/tmp/codepilot-v0.67.17-public/剩余边界诚实披露三 Runtime 同 fixture/HTTP/SDK wire 与隔离 UI 已验证但真实账号下模型自主调用/完整打包客户端 smoke 未执行不标记 Release ready旧 Sentry Default key 未改动停收需另行决策停收窗口不能补回聊天 DB 与文件 ledger 无跨存储原子 outbox不声称分布式 exactly-once5000 回合 ledger / 2 MiB records 为容量边界而非无限存储承诺。九、给多 Runtime 客户端架构的启示从本方案可以提炼出一套可复用的解耦范式核心与协议分离让 handler 只依赖 fs/zod 与用户文件memory-service.ts的模式Runtime SDK 仅存在于薄适配层三端用同一 fixture 断言语义一致事实源即用户可读文件Markdown 既是存储也是审计依据索引/投影可重建CAS 单写者锁 fsync 保证写入原子性tombstone 防止删除内容复活模型是可选增强基础能力CRUD、确定性检索无模型可用AI 重排、自动抽取走统一辅助执行器不可用时确定性降级并诚实显示 unavailable/failed/cooldown凭据与瞬时故障分类仅明确 credentials 根因持久等待配置变化429 等 4xx 有界冷却重试遥测 outcome 不能直接当作重试策略作用域绑定归属会话而非 Runtime显式助理入口绑定 启动事务一次性迁移旧会话杜绝按 cwd 猜身份带来的越权。如需进一步深入可阅读 执行计划含三轮复审修复映射与手动验收方案 MEMCHECK-0921、Memory 守护契约、根因研究报告以及src/lib/memory-*.ts系列实现与src/__tests__/unit/memory-*.test.ts测试。赞分享人工智能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点击查看免费下载相关推荐Waoowaoo Codex Creative Runtime唯一 Agent Runtime 的架构不变量、双层隔离与实战避坑指南Waoowaoo Codex Creative Runtime唯一 Agent Runtime 的架构不变量、双层隔离与实战避坑指南 本文基于仓库架构文档 dCross-Session Memory 实战用 ADK 与 Vertex AI Memory Bank 构建跨会话记忆 AgentCross Session Memory 实战用 ADK 与 Vertex AI Memory Bank 构建跨会话记忆 Agent 导读 本指南以 core示例工程CodePilot 日志暴涨与 Codex Runtime 闪退排查实录12.5G 主日志根因分析、修复落地与崩溃留证方案CodePilot 日志暴涨与 Codex Runtime 闪退排查实录12.5G 主日志根因分析、修复落地与崩溃留证方案 本文以 docs/exec pla人工智能AI 应用AI Agent交互助手MCP Clients本地部署上一篇如何用Make-A-Video-Pytorch突破文本到视频生成的技术瓶颈下一篇ws-scrcpy浏览器端Android设备屏幕镜像与控制完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考