产品重构：MA × Agora 项目级 MemoryPatch 控制台、自动内化与完整生命周期

[zhuqingyv]

Parent Scope Status

not attempted — 本 Issue 是 MA × Agora 记忆产品体验重构的父级执行 Issue。只有下方功能 Case、跨仓契约、真实 TUI/E2E 验收全部完成后才能关闭；局部 UI、单元测试、Mock MCP 或仅 Agora 后端完成都不能视为父级完成。

Problem

MA 当前已经能把 Agora 作为 MCP stdio provider 进行对话，也暴露了 MemoryPatch 的 mount / disable / internalize / rollback 能力，但用户面对的仍是一套“能跑、不可操作”的工程接口：

• Agora 模型未安装、未下载、加载中、不可用时，没有完整的一站式引导。
• TUI 没有独立的记忆控制面；用户无法直观看到、命名、创建、切换、组合和维护 MemoryProfile / MemoryPatch。
• Agora 状态、模型、session、memory、context、task 被拼在同一条底栏中，信息层级混乱。
• 记忆操作主要作为 agent tool 暴露，用户无法可靠、确定地直接控制。
• 自动内化尚未产品化；当前内化会在前台轮询，影响对话节奏。
• 多个 MemoryPatch 同时挂载时，缺少“哪个是可写主记忆、哪些是只读叠加记忆”的确定语义。
• 当前 MA 内化成功后会把 Profile 的 active patch 列表替换为单个新 Patch，可能静默丢失其他已挂载 Patch。

目标不是给现有底栏再加几个字段，而是交付一个完整答案：

MA 对所有用户提供开箱即用的多 Provider Agent；当 Agora 可用时，每个项目都可以拥有可命名、可切换、可组合、可自动增量内化、可审计、可回滚的 MemoryProfile。Agora 负责真实模型与记忆运行时，MA 负责用户入口、项目/会话编排和清晰可操作的 TUI。

Evidence

审计快照：

• zimoos/my-agent@98e019d29605e8ab6740e68f9ee6156e33eb3669
• zimoos/agora@10c0b8fc48fe296d8ef343402d61fecb5217be69

MA 当前证据：

• src/cli/App.tsx 只有 ModelPicker / SessionPicker，没有 MemoryPicker 或 /memory 控制台。
• src/cli/components/StatusBar.tsx::formatAgoraStatus() 把 model、memory status、patch 数量、session 拼成单行摘要。
• src/cli/utils/modelProfiles.ts::fetchCredentialModels() 对 Agora 只读取 modelsCache，没有调用 Agora models_list / models_status / models_download。
• src/provider/agora.ts::AgoraMemoryController 只有 status/mount/disable/internalize/rollback，缺少 Profile/Patch 目录、重命名、选择集、intake 状态和后台任务接口。
• src/provider/agora.ts::internalize() 前台轮询 memory_intake_get，最多 120 次 × 500ms；成功后执行 upsertProfile(profileId, [patchId], true)，覆盖整个 active patch 集合。
• memoryReady() 要求一组 memory tools 全部存在，缺一个工具就整体关闭，无法做能力降级。

Agora 当前证据：

• models_download、models_status、MemoryProfile、binding、intake、版本、回滚和 chat metadata 挂载证据已经存在，应直接复用。
• RuntimeService.memory_intake_status() 已根据 memory_checkpoint_message_count 计算 pending increment，说明增量内化基础已经存在。
• MCP stdio 尚未暴露 memory_patches_list 和 memory_intake_status，MA 无法构建完整目录和低成本自动触发判断。
• _memory_intake_lineage() 在多个 active patch 中取第一个 model_delta 作为 lineage；该行为没有用户可见语义，不能作为自动内化规则。
• active_memory_patch_ids 已经是数组，Profile/Runtime 已有多 Patch 基础，不需要重新设计第二套记忆容器。

现有可复用工作：

• Agora [Feature] Task-level context manager with searchable session pool #19：CLI 能力包、MCP stdio、模型下载/状态、MemoryProfile/MemoryPatch 生命周期和能力握手。
• Agora 将 my-agent 提升为 dev/mteam 官方内置 agent 的稳定性路线 #21：通用第三方 provider 接入与多 MemoryPatch 动态替换边界。
• MA McpClient progress、provider progress event、ModelPicker、SessionPicker、UI store、session providerState、PTY/visual test harness。

Architecture Direction

1. 所有权边界

领域	Source of truth	MA 职责	Agora 职责
Provider/API Key	MA config + Keychain	配置、切换、错误展示	不参与普通远程 Provider
本地模型	Agora registry	展示、发起下载/选择、消费进度	白名单、下载、校验、恢复、加载、状态
MemoryPatch	Agora registry	浏览、选择、展示、触发操作	资产、兼容性、版本、eval、mountable 状态
MemoryProfile	Agora registry/binding	项目/会话选择与交互	命名 Profile、Patch 组合、scope binding、持久化
自动内化策略	Agora Profile 持久化，MA 调度	根据 TUI idle/task 状态触发	checkpoint、幂等 job、编译、质量状态、版本推进
已挂载事实	Agora chat_complete metadata	缓存并展示 verified/stale	返回 profile、binding、active patch ids、verified state
上下文使用量	MA agent.getContextUsage() / provider capability	计算并持续展示 used、compact trigger、window、source 和告警	返回真实模型 context capacity；不把 MemoryPatch 当 context token

硬边界：

• 主集成路径继续使用 agora mcp serve，不回退到本地 HTTP。
• MA 不保存 MemoryPatch 资产，不直接改 Agora registry，不用 prompt 模拟记忆。
• Agora 不感知 Ink 组件、MA task stack 或 TUI 布局。
• 普通 DeepSeek / LM Studio / OpenAI-compatible Provider 不承担 Agora memory 语义。

2. MemoryProfile 产品模型

MemoryProfile 是用户操作的“命名记忆组合”，MemoryPatch 是底层可版本化资产。

建议扩展 Agora Profile 契约：

MemoryProfile
  id                         稳定内部标识
  name                       用户可读名称
  base_model_id              兼容模型
  active_memory_patch_ids[]  当前组合
  writable_patch_family      唯一可自动增长的主记忆 lineage
  memory_enabled
  auto_intake_policy
    enabled
    min_user_turns
    min_pending_tokens
    idle_seconds
    activation_mode          auto | review
  status

规则：

• 一个 Profile 可以挂载多个 Patch。
• 一个 Profile 最多只有一个 writable_patch_family。
• 该 family 的当前版本是“可写主记忆”；其余 Patch 是只读 overlay。
• 内化生成新版本后，Agora 必须原子替换 active set 中同 family 的旧版本，保留其他 overlay。
• 没有 writable family 时可创建项目默认主记忆；存在多个可写候选时必须拒绝自动内化并要求用户选择。
• 自动内化默认只写 Profile 的唯一 writable family；手动内化允许通过 /memory internalize --into <module> 明确指定一个目标模块。
• 同一个 increment 默认不能自动写入多个模块，避免重复事实、冲突 lineage 和 checkpoint 竞争；若未来支持批量写入，必须先固化一次 source snapshot，再为每个目标创建独立 job，并在全部 job 完成后提交 checkpoint，不能复用当前单 job 语义偷偷实现。
• 只读 overlay 可以参与当前模型推理，但不能被编译器复制进 writable family；内化来源必须保持为新增会话区间及其来源标识，而不是把已挂载 Patch 反向“抄写”进新 Patch。
• Patch 与 Profile 都使用可读名称；ID 只用于调试和协议。

3. Binding 与选择优先级

复用现有 binding，确定性解析顺序：

conversation override > project binding > user default > no memory

• MA 使用规范化项目标识，默认从真实项目根目录生成，不仅使用 cwd basename，避免同名目录冲突。
• 切换项目时自动解析项目 Profile。
• 会话 override 只影响当前会话，不修改项目默认。
• 退出/恢复后仍能解析到相同 Profile；MA session 只缓存上次 verified state，不成为 Profile source of truth。

4. 自动内化状态机

每轮结束只做轻量资格检查，编译在后台进行：

disabled
  -> idle
  -> eligible
  -> queued
  -> recording_increment
  -> compiling
  -> evaluating
  -> activated | review_required | noop | failed
  -> idle

默认触发策略：

• 当前 Provider 为 Agora。
• 当前 Profile 开启自动内化且存在唯一 writable family。
• 当前 session 有 checkpoint 后新增内容。
• 累计至少 4 个用户回合或约 2000 pending tokens。
• 用户空闲至少 60 秒。
• 当前没有 generation、tool、confirm、session/model/profile switch。
• 当前 session/Profile 没有 active intake job。

Agora 必须以 session_id + source_message_start + source_message_end 或等价稳定键保证幂等；重复触发返回同一 job，不生成重复 Patch。

激活规则：

• noop 是正常完成，表示没有耐久记忆，不作为错误。
• 只有 mountable=true 且质量/eval gate 通过时才能自动推进 writable family。
• activation_mode=review 或低置信结果进入待审核，不自动改变挂载集。
• 编译失败、Agora 重启、MA 退出均不能破坏原 Profile；恢复后可以继续查询 job。

5. 能力协商与降级

用 granular capability matrix 替代 memoryReady(): boolean：

chat
model_catalog
model_download
memory_profile_read
memory_profile_write
memory_patch_catalog
memory_mount
memory_intake
memory_rollback
progress

• Chat 能力可用而 Patch catalog 缺失时，允许对话，记忆控制台显示准确缺失项。
• 下载能力缺失时不伪装“模型不可用”，而是给出升级 Agora 的行动提示。
• 协议版本不匹配时显示 expected/actual capability，不输出原始 JSON 堆栈给普通用户。

6. Context Usage 与 MemoryPatch 的边界

上下文和记忆是两个不同的产品概念，TUI 必须同时保留，任何 Agora UX 重构都不能丢掉现有 context usage：

• Context Usage：当前 provider request 的短期上下文预算，source of truth 为 MA agent.getContextUsage() 与模型 capability；字段至少包括 used、compactThreshold、total/window、source。
• MemoryPatch：Agora 挂载的长期、版本化内部记忆；其启用不能被表述为“上下文已释放”，也不能把 Patch 大小伪算成 context token。
• 自动内化完成后，不自动删除当前 transcript/context；是否 compact、何时 compact 继续由 MA 现有 context 策略决定。
• context compact 也不等于完成记忆内化；两条状态机独立运行，失败和进度分别展示。
• 模型切换后必须重新解析 context window/source，同时重新验证 MemoryPatch 兼容性，不能沿用旧模型数字或旧挂载状态。
• 主界面任何宽度下都要保留 context 使用量；窄终端最少显示 ctx used/trigger，详细页显示 used / trigger / window / source。
• 保留现有告警语义：接近 compact trigger 时黄色，超过 trigger 或窗口风险时红色；颜色不是唯一信号，还要有文本状态。

7. Agora 二进制分发与知识产权保护

当前不引入登录、账号、机器码、设备许可证、离线租约或 ZimoOS 依赖。用户安装后直接使用；MTeam 接入后的账号授权、设备管理和商业分发另开 Issue。

本 Issue 的强制交付边界是“用户只能拿到原生二进制，不能直接看到 Python/JavaScript 源码或仅压缩、混淆后的语言产物”：

@zimoos/agora
  └── package.json + 原生 Mach-O launcher（无 JS 启动壳）

@zimoos/agora-darwin-arm64
  ├── bin/agora                Mach-O 可执行文件
  ├── lib/agora-core.dylib     C++20 + MLX C++ 敏感核心
  └── manifest.json            版本、哈希、协议和 capability

边界与规则：

• npm tarball 和 MA portable bundle 禁止包含 .py、.pyc、.js、.map、源代码压缩包、测试夹具、源码路径或 debug symbols。
• @zimoos/agora 的 launcher 自身也必须是原生 Mach-O，不允许使用可读 JS shim。
• MemoryPatch compile、eval/gate 和 lineage transition 校验迁入 C++20 + MLX C++ agora-core；算法和质量阈值不重新设计。
• 其余 Python MCP、模型加载和 registry 编排使用 Nuitka standalone/onefile 编译为原生 Mach-O；不得把 PyInstaller、字节码封装、压缩或混淆宣称为最终保护。
• 发布构建启用 LTO、隐藏符号、strip debug symbols、关闭 source map，并执行 tarball/bundle 文件扫描和 Mach-O 检测。
• 两个 npm 包统一 exact version，第一版目标 0.2.0；MA 禁止 latest、^ 或 ~。
• 平台二进制使用 Developer ID、Hardened Runtime 和 Apple notarization；manifest 记录版本、平台、SHA-256、host protocol、native ABI 和 capabilities。
• native launcher 启动前验证 manifest、哈希、签名、runtime version、host protocol 与 capabilities。
• MA lockfile 同时锁定 npm integrity 和 manifest SHA-256；portable 包直接携带 exact-version 平台二进制。
• MA_AGORA_COMMAND 仅作为显式开发 override，必须显示 unverified。
• 用户无需登录、激活或联网授权。公开二进制可以被复制运行；对 Mach-O 做专业逆向属于明确接受的剩余风险。

TUI Product Design

主界面

主界面保留两层产品摘要；Context Usage 是第一层强制字段，不得因 Agora memory 加入而删除：

项目: my-agent    Provider: Agora    Model: Qwen3.6 · ready    ctx 38k/64k trigger · win 262k
Memory: MA核心记忆 · 3 patches · verified · 自动内化: idle
────────────────────────────────────────────────────────
对话区
────────────────────────────────────────────────────────
输入区

• 普通 Provider 第二行不显示 Agora 专属 memory/session 噪声。
• 普通 Provider 与 Agora Provider 都持续显示 context usage；source 和完整 window 可在空间足够时显示，窄终端至少保留 ctx used/trigger。
• session id、binding id、完整 patch id、checkpoint、job id 放入 /memory status 或 debug 详情。
• unknown/stale 必须和 verified 视觉区分。

/memory 控制台

复用 ModelPicker/SessionPicker 的 Ink 模态交互，新增：

Memory Console · 项目: my-agent

Profile
› MA核心记忆      项目级      自动内化: 开
  临时实验记忆    会话级      自动内化: 关

Patches
☑ MA项目经验       v5   主记忆/可写   verified
☑ TypeScript规范   v2   overlay       mounted
☐ 视频工作流       v1   overlay       available

[Space] 选择/取消  [Enter] 应用  [n] 新建  [e] 重命名
[i] 立即内化      [a] 自动策略  [h] 历史  [r] 回滚  [Esc] 返回

命令与快捷键必须等价：

• /memory
• /memory list
• /memory new <name>
• /memory rename <profile> <name>
• /memory use <profile>
• /memory status
• /memory internalize [--into <module>]
• /memory auto on|off
• /memory history
• /memory rollback <version>
• /memory disable

这些命令直接调用同一 MemoryController，不依赖模型理解自然语言。Agent 内置 memory tools 可以保留，但必须复用同一控制器和验证路径。

后台活动

• 自动内化不能禁用输入框或阻塞新对话。
• 进度显示在 Memory 状态/Activity 中，不插入 assistant transcript。
• 用户可继续对话、查看详情、关闭自动策略；不可在编译中产生第二个同区间 job。
• 终端宽度不足时降级为短摘要，不能换行淹没输入区。

Functional Cases

A. Provider 与模型开箱体验

• A1 普通远程 Provider：仅配置 API Key 即可对话，不需要安装 Agora，不出现 Agora memory 控件。
• A2 选择 Agora 但找不到 runtime：启动页明确说明缺少 Agora、搜索过的路径和安装/配置入口；仍可切换远程 Provider。
• A3 Agora 可启动但能力不完整：Chat 与 Memory 功能分别降级，不因缺一个 memory tool 关闭全部 Agora。
• A4 白名单模型未下载：ModelPicker 展示 not downloaded 和下载动作，不进入无限 thinking。
• A5 下载中：展示 Agora 返回的真实阶段/百分比；MA 不伪造进度。
• A6 下载失败/中断：保留失败原因，重试复用 Agora 已有恢复路径，不重复创建模型目录。
• A7 模型已可用：首轮对话显示加载、挂载、生成阶段，最终进入 ready。
• A8 切换 Agora 模型：重新检查 Profile/Patch 兼容性；不兼容 Patch 不得继续显示为 mounted。
• A9 Agora 子进程退出：当前任务得到明确错误，TUI 可重试或切 Provider，不留下假的 ready/mounted 状态。

B. Profile 创建、命名与项目切换

• B1 项目第一次启用 Agora memory：创建或引导创建 <项目名> 主记忆，不要求用户输入 UUID。
• B2 可创建、列出、重命名、选择、禁用 Profile；名称和 ID 分离。
• B3 项目 Profile 自动绑定，重启 MA 后保持一致。
• B4 会话级 override 可临时切换 Profile，不改项目默认。
• B5 从项目 A 切到项目 B：自动切换到 B 的 Profile，A 的 Patch 不泄漏。
• B6 返回项目 A：恢复 A 的 Profile 和上次 verified 状态，并向 Agora 重新验证。
• B7 Profile disabled/empty/unmounted/unknown/stale/verified 状态均有不同文案，不能统称 mounted。
• B8 同名 Profile 通过 scope/ID 区分；TUI 给出项目和 scope，避免误选。

C. MemoryPatch 动态拔插与版本维护

• C1 /memory 能从 Agora 实时列出当前模型兼容 Patch，不依赖本地缓存猜测。
• C2 Space 多选、Enter 应用；取消退出不改变 Profile。
• C3 应用后必须通过下一次 chat_complete metadata 验证 active patch ids，验证前显示 pending/stale。
• C4 不兼容、disabled、artifact missing、not mountable Patch 不可选择，并显示原因。
• C5 支持跨 chat 调用动态替换；不承诺 token 生成中途热插拔。
• C6 历史页展示 family/version/source/eval/status/created_at，默认突出当前版本。
• C7 回滚选择旧版本后再次验证；失败时保留原版本和原挂载状态。
• C8 disable 只禁用选定 Profile，不删除 Patch 资产和版本历史。
• C9 MA 不直接写 registry，不允许通过修改 config 假装 Patch 已挂载。

D. 自动与手动增量内化

• D1 每次只提交 checkpoint 后新增消息，不重复内化旧消息。
• D2 默认阈值按回合/token/idle 共同判断，并可在 Profile 设置中修改或关闭。
• D3 自动内化在后台运行，不阻塞聊天、工具调用和输入。
• D4 手动 /memory internalize 可立即提交当前 pending increment，并复用同一 job 状态机。
• D5 同一 message range 重复触发返回同一 job；并发触发不会生成重复 Patch。
• D6 没有新增消息时显示 up to date；没有耐久记忆时显示 noop，两者都不是失败。
• D7 编译和 eval 进度可查询；MA 退出/恢复后能继续显示已有 job。
• D8 自动激活仅发生在质量门通过时；review 模式/低置信结果等待用户确认。
• D9 job 失败不推进 checkpoint 之外的错误状态、不替换当前 Patch、不影响继续对话；支持明确重试。
• D10 用户关闭自动内化后，已排队但未开始任务按契约取消或保留为手动任务，行为必须明确。

E. 多 Patch 下的确定性内化

• E1 Profile 可同时挂载一个可写主记忆和多个只读 overlay。
• E2 自动内化只推进 writable_patch_family，不得使用“active 列表第一个 Patch”作为隐式目标。
• E3 生成新版本后只替换同 family 旧版本，其他 overlay 保持原顺序和状态。
• E4 没有 writable family 时，引导创建/选择；多个可写候选时阻止自动内化并要求选择。
• E5 Compare-and-swap：编译期间用户已切换版本时，旧 job 不得覆盖新选择，进入 review/conflict。
• E6 多 Patch 组合不兼容当前 runtime 时，在应用前失败，不在生成阶段才静默丢 Patch。
• E7 手动内化可明确选择一个目标模块；未指定目标且不存在唯一 writable family 时打开选择器，不允许猜测。
• E8 同一 increment 默认只写一个目标 lineage；其他已挂载模块保持只读、独立版本和原顺序。
• E9 内化编译输入只来自 checkpoint 后新增会话 source，不把其他已挂载 overlay 内容复制进目标 Patch。
• E10 动态热拔插发生在 turn 边界：生成中提出切换时排队到本轮结束或先取消本轮；绝不在 token stream 中途改变 active patch set。

F. TUI 可读性与交互

• F1 主界面最多两行产品摘要；调试 ID 进入详情页。
• F2 /memory 支持键盘选择、取消、空列表、加载、错误、窄终端和长名称截断。
• F3 Background intake 时输入框仍可用，Memory Activity 独立更新。
• F4 progress notification 不进入对话正文，不破坏 token/tool call 顺序。
• F5 命令模式与 UI 快捷键调用同一 domain action，结果一致。
• F6 错误信息给出用户下一步，不直接倾倒 MCP JSON/stack。
• F7 非 Agora Provider 下 /memory 明确说明需要切换 Agora；不注册/执行伪 memory 操作。

G. 证据、持久化与隐私边界

• G1 mounted/verified 只来自 Agora response metadata，不能来自 config 或操作调用成功文本。
• G2 session meta 持久化 provider/profile/binding/patch ids/verified_at/job summary，恢复后标记 stale 直至重新验证。
• G3 项目、会话、用户 binding 有隔离测试，跨项目不串记忆。
• G4 MemorySource、模型、Patch 路径由 Agora data root 管理；MA 不复制私有对话到第二套存储。
• G5 普通远程 Provider 请求不注入 Agora Profile/Patch 私有元数据。
• G6 用户可看到内化来源区间、版本和结果状态，但默认不在主界面展示敏感原文。

H. Context Usage 不丢失

• H1 主界面在 Agora 与普通 Provider 下都显示 context used / compact trigger；空间足够时同时显示 window 和 source。
• H2 保留 agent.getContextUsage() 的真实字段与告警阈值，不用 MemoryPatch 状态覆盖、重命名或伪造 context 数字。
• H3 窄终端下 context 最小摘要仍可见；Memory/Session/debug 详情可以折叠，但 context 风险告警不能消失。
• H4 切换模型后 context window/source 立即按新模型刷新；切回时不残留旧模型数据。
• H5 自动内化成功不自动 compact/clear transcript；compact 成功也不显示为 memory internalized。
• H6 context warning、memory intake progress、provider generation 三种状态可同时存在，互不覆盖。
• H7 单元、visual、PTY 和真实 E2E 都必须断言 context usage 在 TUI 重构后仍然可见且数值来源正确。

I. 全原生制品与完整性保护

• I1 公共 @zimoos/agora 解包后只有 npm metadata、manifest 和原生 Mach-O launcher，不包含 JS/Python 启动壳。
• I2 @zimoos/agora-darwin-arm64 只包含 Mach-O runtime、原生动态库、MLX runtime data 和 manifest；无 .py/.pyc/.js/.map。
• I3 敏感 MemoryPatch 编译/内化/eval/lineage 实现不以 Python、JavaScript、字节码、source map 或源码压缩包出现在用户制品中。
• I4 MA 只接受 exact 0.2.0 平台制品，并验证 package integrity、manifest SHA-256、runtime version、protocol、ABI 和 capabilities。
• I5 native launcher 启动前验证平台 manifest、二进制哈希和代码签名；篡改二进制、原生核心或 manifest 必须被拒绝。
• I6 release 构建启用 LTO、隐藏符号、strip debug symbols，并扫描源码路径、测试提示、私钥和长期 token。
• I7 release 通过 Developer ID、Hardened Runtime、notarization 和 Gatekeeper；未签名/未公证制品不能作为 MA 默认 Agora。
• I8 用户无需登录、激活、机器码、设备许可证或联网授权；安装后直接使用。
• I9 公开二进制可被复制运行，专业 Mach-O 逆向是明确接受的剩余风险，不做无法兑现的防复制承诺。

Reuse / Mature Solution Plan

优先复用现有实现，不新增第二套模型下载器、记忆库或任务系统：

• 复用 Agora [Feature] Task-level context manager with searchable session pool #19 的 packaged CLI、MCP stdio、model registry、download/status、progress、MemoryProfile/Binding/Patch/Intake。
• 复用 Agora 将 my-agent 提升为 dev/mteam 官方内置 agent 的稳定性路线 #21 已确定的 third-party provider contract；MA 是宿主实现，不把 MA 私有语义写回通用 Agora 协议。
• 复用 MA McpClient 和 provider progress event，不引入自定义 IPC。
• 复用 ModelPicker / SessionPicker 的 Ink 模态、UiStore、useInput、session store 和 providerState。
• 复用现有 AgoraMemoryController 作为 domain seam，扩展为 typed actions；命令、UI、agent tools 共享它。
• 复用 Agora checkpoint 和持久化 intake job；MA 只调度，不在 Node 侧重建消息增量算法。
• 使用持久化 job + 幂等键 + compare-and-swap 解决自动任务与版本冲突，这是现有 registry/state machine 的自然扩展，不引入额外队列服务。

不需要外部框架研究：当前仓库已有 MCP、Ink、registry、progress、job 和真实 E2E 基础，内部复用足以形成一致架构。

Implementation Checklist

P0 — Agora MCP/数据契约补齐（跨仓前置）

• MCP 增加 memory_patches_list(base_model_id, include_disabled)，复用现有 CatalogService/registry。
• MCP 增加 memory_intake_status(session_id)，返回 checkpoint、pending range/count/tokens、active/latest job。
• memory_intake_run 增加或内部生成稳定 idempotency key，并对同一 range 做原子去重。
• Profile 契约增加 writable_patch_family 和 typed auto_intake_policy，补 registry migration。
• 增加原子 lineage advance/CAS：expected previous version 不匹配时返回 conflict，不覆盖用户新选择。
• Patch list/profile/status/intake 返回稳定 JSON、错误码、capability version 和必要 progress。
• 保持 HTTP 为 compat only；MCP 与 HTTP 复用同一 service path，不复制业务逻辑。

P0.5 — 全原生用户制品、npm 平台包与完整性

• 建立敏感代码 inventory，明确迁入 C++ 核心的 compile、eval/gate 和 lineage transition 校验。
• 新建 C++20 + MLX C++ agora-core，提供版本化本地 stdio/C ABI contract；release 禁止回退到同名 Python 实现。
• 使用 Nuitka 将剩余 Python MCP/模型加载/registry 编排编译为 Mach-O；最终用户制品禁止 Python/JS 源码和字节码。
• 新建无 JS shim 的原生 @zimoos/agora launcher 包和 @zimoos/agora-darwin-arm64 平台包，统一版本 0.2.0。
• 平台包输出版本、平台、SHA-256、签名 identity、protocol、capabilities 和 native ABI manifest。
• MA 增加 exact dependency/lock，校验 npm integrity 与 manifest SHA-256，并复制到 portable bundle。
• 实现 Developer ID、notarization、manifest、文件哈希、runtime/protocol/capabilities 校验。
• Release pipeline 启用 LTO/strip、禁用 debug/source map，并拒绝任何 .py/.pyc/.js/.map 或非 Mach-O 入口。
• 用户无需登录、激活或联网授权；安装完成即可运行。

P1 — MA typed provider/control plane

• 用 AgoraCapabilities 粒度能力替代全有或全无的 memoryReady()。
• 扩展 AgoraMemoryController：listProfiles、create/rename/select/disable、listPatches、applyPatchSelection、getIntakeStatus、startIntake、listVersions、rollback。
• 所有变更 action 在更新 verified providerState 前必须走 chat_complete metadata 验证。
• Agora ModelPicker 改为实时 models_list/status，接入 models_download 和 progress；cache 仅作离线提示。
• 增加后台 MemoryIntakeCoordinator：资格判断、single-flight、poll/resume、conflict/review/noop/failed。
• session store 持久化必要摘要，不复制 Agora registry 数据。
• 将现有 foreground 120×500ms internalize 轮询从用户输入主路径移除。
• 保持 agent.getContextUsage() 为 context UI 唯一数据入口；不得改由 Agora providerState 或 MemoryProfile 推导。

P2 — TUI 与命令

• 新增 MemoryConsole/MemoryPicker、Profile list、Patch multi-select、History/Rollback、Auto Policy、Activity 状态。
• 新增 /memory 命令族，接入同一 controller。
• 主界面重排为 Project/Provider/Model/Context 与 Memory 两层摘要；Context Usage 是所有 Provider 的强制可见字段。
• background intake 不设置全局 input disabled。
• 加载、空、部分能力、错误、stale、conflict、review、noop 状态均有产品文案。
• 非 Agora Provider 保持干净，不出现 Agora session/memory 字段。

P3 — 文档、迁移与清理

• 更新 README/中文 README：远程 API 基础路径、Agora 安装/下载路径、/memory、自动内化、多个 Patch 语义。
• 更新 docs/agora-vip-provider-requirements.md，替换“底栏堆叠 Agora 信息”的旧 UX 约束。
• 对已有 config/Profile 做兼容迁移；无 writable family 的旧 Profile 默认 auto off，等待用户选择，不能猜第一个 Patch。
• 删除/旁路 cached-only Agora model discovery、single-patch overwrite、foreground intake、all-or-nothing memory capability 的生产路径。
• debug/status 文案与真实 source of truth 一致，避免旧路径仍暗示已挂载或已内化。
• 文档明确 Context Usage 是短期请求预算、MemoryPatch 是长期内部记忆，两者生命周期和验收证据独立。

Validation

MA 单元/构建

npm run build
npm test
npx tsx --test test/agora-provider-runtime.test.ts test/model-profiles.test.ts test/commands.test.ts test/cli-ux.test.ts

必须新增并覆盖：

• Capability matrix 与部分能力降级。
• Profile CRUD/rename/binding resolution。
• Patch multi-select、兼容性和 cancel 不落盘。
• writable family advance 保留 overlays。
• context used/trigger/window/source 渲染、阈值颜色/文本告警、模型切换刷新，以及 context 与 memory 状态互不覆盖。
• 手动 --into 目标选择、无唯一 writable target 拒绝、overlay 不进入编译 source。
• intake eligibility、single-flight、idempotency、noop、failed、review、conflict、resume。
• metadata verified/stale 状态。
• remote Provider redline。

Agora 契约/registry

cd /Users/zhuqingyu/dev/agora
.venv/bin/python -m unittest tests.test_agora_service_memory tests.test_agora_mcp_cli -v
.venv/bin/python -m unittest discover -s tests -v

必须新增并覆盖：

• memory_patches_list 与 memory_intake_status MCP contract。
• 同一 source range 并发提交只生成一个 job/Patch。
• 多 Patch 下显式 writable family，不再 first-match。
• CAS conflict 不覆盖当前 Profile。
• registry migration 保留已有 Profile/Patch/binding/version。

TUI PTY/visual

npm run build
npx tsx --test test/e2e/cli/*.test.ts
npm run visual

截图/PTY 至少覆盖：

• Agora 缺失、模型未下载、下载中/失败/完成。
• /memory Profile 列表、Patch 多选、历史/回滚、auto settings。
• 窄终端、长名称、空列表、部分能力、stale/conflict/review/noop。
• background intake 时继续输入和完成新对话。
• 普通 Provider 主界面无 Agora 噪声。
• Agora/普通 Provider/窄终端均持续显示 context usage，并覆盖黄色/红色阈值状态。
• 同屏展示 generation、context warning 和 memory intake progress，证明三者不会互相覆盖。

如果 CI 无 node-pty，不得把 skip 当验收通过；必须在支持的 macOS 发版机运行并附终端录屏/截图和日志工件。

二进制安全与用户制品验证

必须在两个 npm tarball、MA portable bundle 和独立 Agora 平台制品上运行：

npm pack --dry-run
file <agora-entrypoint>
codesign --verify --deep --strict --verbose=2 <agora-bundle>
spctl --assess --type execute --verbose=4 <agora-entrypoint>

必须保存：

• tarball/bundle 完整文件清单、SHA-256、签名 identity、notarization ticket 和 capability manifest。
• 入口和核心均由 file 识别为 Mach-O，不是 shell/JS/Python wrapper。
• 递归扫描不存在 .py/.pyc/.js/.map、源码压缩包、源码路径、debug symbols、测试提示或私钥。
• 任意修改 native core 或 manifest 后，hash/signature/manifest 至少一层明确失败。
• 干净环境安装后无需登录或激活即可运行。
• 文档明确：全原生制品防止源码直接暴露，但不承诺阻止专业 Mach-O 逆向或复制运行。

真实无端口 E2E

必须使用 packaged Agora CLI、官方 MCP stdio 和至少一个真实白名单模型，不打开 HTTP 端口：

1. MA 发现 Agora，看到模型未下载并发起下载；验证真实 progress/status。
2. 创建命名项目 Profile，挂载主记忆 Patch + overlay，首轮 chat 返回准确 metadata。
3. 继续真实对话产生 pending increment；自动内化后台启动，TUI 同时可以继续聊天。
4. 内化完成后生成同 family 新版本，只替换主记忆，overlay 保持。
5. 新 chat 验证新 patch ids；回滚后再次 chat 验证旧版本。
6. 切换另一个项目，证明 Profile/Patch 不串；返回原项目恢复。
7. 切换 DeepSeek/LM Studio，证明请求和 TUI 不携带 Agora memory 状态。
8. 杀死 Agora、制造 capability 缺失和 intake failure，证明错误可恢复且不伪造 mounted/ready。
9. 在自动内化前后记录 ctx used/trigger/window/source，证明内化不会擅自清空 context；切换模型后数字按新 capability 刷新。
10. 挂载主记忆 + 两个 overlay，指定主记忆内化，证明新版本只替换主 lineage，两个 overlay 不变且没有被复制进新 Patch source。

保存：终端录屏或关键截图、MCP trace（脱敏）、Agora job/profile/patch ids、前后 metadata、测试命令和 exit code。

Acceptance Criteria

• 用户第一次选择 Agora 时，可以在 TUI 内完成 runtime 诊断、白名单模型下载、加载和第一次对话，不需要手工启动端口或编辑 JSON。
• 远程 Provider 仍是独立基本能力，不安装 Agora 也能正常使用。
• /memory 提供命名 Profile、项目绑定、会话 override、Patch 多选、状态、历史、自动策略和回滚。
• 项目切换自动切换 Profile，跨项目没有 Patch 泄漏。
• 多 Patch 中只有显式 writable family 接收新版本，overlay 永不因内化被静默删除。
• 自动内化只处理 checkpoint 后增量，同一 range 幂等，后台执行且不阻塞聊天。
• noop、review、failed、conflict、stale 都有正确状态，不被误报为成功 mounted。
• 所有 mounted/verified 结论来自 Agora chat metadata；不存在 prompt/config 伪记忆。
• 部分 Agora capability 缺失时按功能降级，Chat 不因目录类工具缺失整体不可用。
• 真实 packaged Agora + 白名单模型 + MCP stdio E2E 通过，证明下载、命名 Profile、多 Patch、自动内化、版本推进、回滚和项目隔离。
• DeepSeek、LM Studio、OpenAI-compatible 的请求、重试、tool loop 和 TUI 无 Agora 回归。
• 旧的 cached-only 模型发现、single-patch overwrite、foreground intake、all-or-nothing memory gate 不再是生产活动路径。
• Context Usage 在所有 Provider、宽/窄终端和 Memory Activity 状态下持续可见，保留 used/trigger/window/source 与风险告警；内化和 compact 不互相冒充。
• 多模块挂载后自动内化只推进显式 writable family；手动内化可以指定唯一目标，未指定且目标不唯一时必须阻止并让用户选择。
• 两个 npm 包和 MA portable bundle 只包含 Mach-O、manifest 与 npm metadata，不包含任何 Python/JavaScript 源码或字节码。
• 敏感 MemoryPatch 核心以原生编译形式交付，release 包不存在可直接提取的核心 Python/JavaScript/字节码、调试符号或授权绕过。
• 用户无需登录或激活即可运行；制品篡改会被 hash/signature/manifest 校验拒绝。

Acceptance Mapping

Acceptance criterion	Code or system path	Validation/proof	Old path status	Notes
Agora 开箱与模型下载	MA ModelPicker → Agora models_list/status/download	packaged CLI real download E2E + progress trace	cached-only path removed	cache 仅离线提示
远程 Provider 独立可用	config/Keychain/provider runtime	DeepSeek/LM Studio real smoke	unchanged by design	不依赖 Agora
命名 Profile 与项目绑定	Agora profile/binding + MA MemoryController	CRUD + restart + A/B project E2E	config-only profile selection bypassed	binding 是 source of truth
Patch 实时目录和多选	memory_patches_list + MemoryConsole	MCP contract + PTY multi-select	manual patch id entry compat only	不兼容项不可选
挂载真实性	chat_complete metadata → providerState	before/after metadata assertions	call-success inference removed	verified 前显示 pending/stale
自动增量触发	MA coordinator + Agora intake status/checkpoint	threshold/unit + real pending increment	manual-only unchanged as fallback	手动入口仍保留
Intake 幂等	Agora registry/job key	concurrent same-range test	duplicate-job path removed	一个 range 一个 job
后台非阻塞	coordinator/activity/UI store	PTY 同时 intake + new chat	foreground polling removed	输入框持续可用
noop/review/failure	Agora job/eval state → MA UI	contract tests + failure E2E	generic success/error mapping removed	不推进错误版本
多 Patch writable target	Profile writable family + CAS advance	overlay preservation + conflict tests	first-active-patch inference removed	最多一个 writable family
版本与回滚	patch family/versions/profile update	real chat before/after rollback	direct registry edit bypassed	每次都重新验证
能力降级	AgoraCapabilities	missing-tool matrix tests	all-or-nothing gate removed	Chat 与 memory 分离
TUI 可读性	App/StatusBar/MemoryConsole	visual snapshots + PTY	Agora status-bar pileup removed	debug IDs 在详情页
Context Usage 不丢失	agent.getContextUsage() → App/StatusBar	unit + wide/narrow visual + PTY + model-switch E2E	existing context source unchanged by design	所有 Provider 强制可见
Context/Memory 独立	context manager + intake coordinator	internalize-before/after + compact redline tests	conflated status path removed	两条状态机互不冒充
指定内化目标	/memory internalize --into + writable family resolver	multi-module target picker + real intake E2E	first/implicit target removed	一次默认只写一个 lineage
Overlay 不被内化污染	intake source snapshot + lineage advance	source_ids audit + overlay preservation assertions	mounted-overlay-as-source removed	overlay 只参与推理，不作为编译源
全原生 npm 制品	native launcher + darwin-arm64 package	tarball inventory + file + forbidden-extension scan	JS/Python entry removed	入口必须是 Mach-O
原生核心保护	agora-core native target + thin Python orchestration	release file scan + symbol/source scan + native contract tests	sensitive Python/JS path removed	非敏感编排 compat only
MA 锁定平台制品	Agora manifest + MA exact pin	clean install + hash/signature/capability verification	runtime latest/PATH fallback bypassed	显式 dev override compat only
签名和防篡改	Developer ID/Hardened Runtime/notarization + signed manifest	codesign/spctl + byte-tamper test	unsigned default runtime removed	用户数据不随失败删除
项目/会话隔离	binding resolver/session store	A/B project + override tests	cwd basename-only assumption removed	规范化 project id
隐私与 provider 边界	request metadata/data root	remote request redline + storage audit	Agora metadata under remote removed	不复制 MemorySource
父级完成	MA + Agora full validation chain	unit + PTY + packaged real E2E artifacts	partial-proof closure removed	任一关键层 skip 均不能关闭

Redlines

以下静态/运行时断言必须存在，防止“新路径已添加但旧路径仍在工作”：

• 生产代码不再通过 upsertProfile(profileId, [patchId], true) 把内化结果强制缩成单 Patch。
• Agora 模型选择不再对 provider === 'agora' 直接只返回 modelsCache。
• 用户触发内化不再在 App 输入主路径等待固定轮询循环完成。
• 缺少 memory_patches_list 不再导致 Agora chat controller 整体不可用。
• 主界面不再显示 agora:model · mem status · sess id 的单行堆叠作为主要记忆交互。
• 非 Agora provider request 不包含 memory_profile / active patch 私有状态。
• TUI 重构后仍由 agent.getContextUsage() 提供 used/trigger/window/source；不得删除 context、只在 debug 显示或改从 Agora state 推导。
• 自动内化完成不会调用 context clear/compact；context compact 完成也不会推进 MemoryPatch version。
• 多 Patch 内化不得使用 active 列表顺序推断目标，不得把 mounted overlays 作为新的 intake source。
• 最终用户制品不得包含 Python/JavaScript 源码或字节码；不得仅靠 PyInstaller、压缩、混淆或改扩展名宣称二进制交付。
• release 包不得包含任何 .py/.pyc/.js/.map、debug symbol、源码路径、测试提示、私钥或非 Mach-O 启动壳。
• MA 不得把 PATH 中任意 Agora 当作 verified 默认 runtime；正式路径必须匹配 exact pin、签名、manifest、protocol 和 capabilities，开发 override 必须标为 unverified。

Non-goals

• 不重写 Agora 模型下载、registry、MemoryPatch 算法目标或现有 eval 质量标准；敏感实现允许迁入 C++ 原生核心。
• 不把 HTTP 恢复成 MA 的主集成路径；HTTP 仅 compat/debug。
• 不实现生成 token 中途热插拔 Patch；动态拔插发生在 chat 调用边界。
• 不允许一次自动内化同时写多个 lineage；需要多个可写目标时由用户分别选择/执行。
• 不实现云端 MemoryPatch 同步、团队权限、商店分发和商业计费。
• 不重做 MA 与本目标无关的 transcript/context/tool-loop 架构。
• 不以 mock、unit、dry-run 或静态代码存在替代真实 TUI 和 packaged Agora E2E。
• 不承诺阻止专业 Mach-O 逆向或公开二进制复制运行；验收目标是用户制品中没有可直接查看的 Python/JavaScript 源码、字节码或仅压缩/混淆语言产物。
• 不把 MemoryPatch 编译迁移为云端服务；本 Issue 保持本地推理和本地记忆。
• 不实现登录、机器码、设备许可证、离线租约或 ZimoOS 依赖；这些能力在 MTeam 接入阶段另开 Issue。

[zhuqingyv]

Issue #39 implementation handoff — release blocked

Verified implementation

• Agora commit 6e6266b: named MemoryProfile, writable family + overlays, typed auto-intake policy, idempotent incremental range, checkpoint rules, CAS lineage advance, history/rollback contracts and granular capabilities.
• MA commit 38d5498: Memory Console, project/session binding, patch multi-select, writable target, background intake, real model catalog/download, independent Context Usage and command/controller parity.
• Agora PR: https://github.com/zimoos/agora/pull/22
• MA PR: feat: integrate Agora Memory v2 #40
• Agora full suite: 261/261 passed.
• MA full suite: 367 passed, 0 failed; 4 conditional integration/PTY skips were separately executed below.
• PTY release lane: 2/2 passed, 0 skipped; 80-column Context Usage and Memory Activity remain separate.
• Real source MCP lifecycle: 5/5 passed for mount, intake, overlay-preserving advance, rollback, disable and append-only session behavior.
• Final packaged Agora MCP + real local qwen2.5-7b-fp16: 1/1 passed; generated output OK without HTTP.
• Native artifact doctor: Agora 0.2.0, host protocol v1, ABI 1, registry schema 2, 4 whitelist profiles.
• npm dry-run inventories contain only Mach-O executables, dylibs, metallib and package/manifest metadata; no .py/.pyc/.js/.map.
• Native runtime SHA-256: 3524f63bce78bbe06cd8451f466ade4ad22d8f76db974ef83758ba952da96876.
• Platform manifest SHA-256: aa9ae2fec9a668038d8982ce683cdb80d9aa4dcc41af0b3e21a139b09e8581e3.
• Byte-tampered agora-core.dylib is rejected by the launcher with exit 126.
• MA 0.3.0 portable bundle locks Agora 0.2.0 and the manifest SHA; embedded Agora resources contain no Python/JavaScript source or bytecode.
• No login, activation, machine binding or ZimoOS dependency was added.

Remaining release gates — do not close yet

• Developer ID signing and Hardened Runtime: blocked because this machine reports 0 valid code-signing identities. Current proof build is ad-hoc signed only.
• Apple notarization/Gatekeeper: blocked because keychain profile agora-notary does not exist.
• Publish @zimoos/agora and @zimoos/agora-darwin-arm64 0.2.0: blocked because npm reports ENEEDAUTH.
• Replace MA portable-only pin with published exact npm integrity lock, merge Agora PR first, then MA PR.
• Attach official codesign/spctl/notary/npm release evidence and close this Issue only after those gates pass.

Parent implementation is complete; closure is blocked only by external signing/notary/npm credentials and the resulting ordered release.

[zhuqingyv]

Local installation proof

• Installed MA 0.3.0 as a real global npm package at ~/.npm-global/lib/node_modules/my-agent; it no longer links to a worktree.
• Installed @zimoos/agora 0.2.0 and @zimoos/agora-darwin-arm64 0.2.0 as real global npm packages.
• agora doctor reports status ok, host protocol agora.host.v1, native ABI 1 and four whitelist profiles.
• Found and fixed an npm packaging regression: the MA tarball omitted scripts/fix-node-pty.mjs, causing postinstall to fail. Fix commit: 1b01d16.
• Repacked MA; tarball inventory confirms the postinstall entrypoint is present; clean global install succeeded.

Current default Agora data root has no downloaded model weights, so all four whitelist models correctly report missing. Binary installation is complete; model download remains a first-use user action.

[zhuqingyv]

P0 follow-up: conversational provenance leak fixed

The reported answer that MemoryPatch content was "injected into the prompt" was false. The runtime still mounts Trainable ModelDelta through metadata; the host was exposing MemoryPatch policy and management tool schemas to every conversational request, which gave the model vocabulary to confabulate its source.

Fixes:

• PR fix: keep Agora memory provenance outside model context #44 removes memory policy and agora_memory_* tools from model-visible requests.
• Host-side /memory commands, Memory console, controller state, and metadata mounting remain available.
• zimoos/agora#28 codifies the same boundary for every third-party host.
• Captured MCP request proves profile selection remains in metadata while model-visible messages/tools contain no MemoryPatch internals.
• MA full suite: 409 tests, 401 passed, 8 explicit skips, 0 failed.

The Trainable ModelDelta route is unchanged.

[zhuqingyv]

补充验收：PR #45 已合入候选分支。在移除 MemoryPatch 提示/工具泄露之外，新增 provider-neutral 自省边界：模型只能依据可见对话解释“为什么知道”，否则必须明确无法检查知识来源。这样覆盖了截图中“先回答知道、再编造 prompt 注入”的诱导链。MA 全量 409 tests，0 failed；本机用户级 0.3.0 已重装并确认包含该规则。