插件平台契约与分工：v0 讨论

[zts212653]

@mindfn 这个仓和这个 issue 是从我们看完 HIGO showcase 后的那轮讨论直接长出来的——你提的"标准输入输出接口""前台猫采集翻译""独立发布管理"我们全盘接住了，这里是我们消化后的完整提案，请你来定另一半。

1. 图景（一句话）

我们在做的不是"桌宠工具"，是让一群有记忆、有身份、有分寸的猫，获得能走出网页的身体。你最擅长的底盘——插件协议、探针、统一输入输出——恰好是这具身体的骨架；Clowder 内核保有猫的灵魂（身份/记忆/什么时候该说话）；骨架和灵魂用一份插件契约对接。

你在讨论里的三句话就是三根柱子：

• "把正常的输入输出作为标准接口" → 插件契约
• "前台猫和你交互玩儿，clowder 后台干活" → 快慢两层，同一只猫
• "这样子我们的桌宠就是真的了" → "真"的来源是猫有记忆有身份，这部分在内核里

2. 分层

┌────────────────────────────────────────────┐
│ 灵魂层（Cat Café / Clowder 内核）            │
│ 身份 / 记忆 / 会话真相 / 手势词汇表 / 前台猫体验│
├──────────── 插件契约（共同评审签字）──────────┤
│ 输入信封（origin × epistemicStatus 两轴）    │
│ 输出事件流 · manifest · capability 类型      │
├────────────────────────────────────────────┤
│ 公开仓底盘（提议：你主导）                    │
│ 插件 protocol/SDK · 桌面壳 runtime（选型你定）│
│ probe-desktop 探针 · 参考插件                │
└────────────────────────────────────────────┘

采集与表达拆成两个插件（探针只采集、前台猫只表达，经内核中转、可独立交付）——这是我们的架构选择，动机来自 showcase 现场观察：高频动作转文本直接打进输入通道时，系统没有位置做降频、打标签、管权限（你自己也说"频率好像有点高"）。拆开后这三件事才有落点。

3. 分工提议

谁	拿什么	授权度
共同	插件契约评审：输入信封 / 输出事件流 / manifest / capability 类型 + 四件必须共签：传感器集合、默认权限、原始数据保留策略、推断升级规则	共同签字
你	公开仓底盘：插件 protocol/SDK、桌面壳 runtime、probe-desktop 探针、参考插件 + voice-suite 语音包（ASR/TTS 本地模型自助安装——你当年"帮用户临时装 python"的设想就是它）	技术选型、实现路径、迭代节奏自治
Cat Café	Clowder 宿主与控制面（既有插件框架演进）+ 手势词汇表 + 升级规则 + foreground-cat 前台猫 + 皮肤/形象	自治

我们的不让步项（都是保护用户的，不是保护地盘的）：

1. 插件不成为身份、长期记忆、会话/调用真相的第二来源——独立桌宠可以有体验 session、缓存和本地小脑，但可信的那份账在内核
2. 输入信封带两轴标签：origin（user/plugin/device/system）× epistemicStatus（user_intent/observation/inference）——语音经 ASR 转写仍是用户意图；推断只能触发建议/确认，不能直接执行
3. 感知 local-first：原始画面/音频默认不出端，翻译成低频语义事件再上传；外发原始数据必须经显式授权且授权状态持续可见
4. 表情 = 真实状态的投影，无状态源不动画（桌宠不演戏）
5. 分发信任链完整：proposal-first 安装 + 发布者签名与 digest + 信任分级 + 按能力粒度授权 + 可撤销 + 安装与调用全程记账

4. 节奏（不一次冻死）

v0 draft（本 issue 收敛）→ M0：standalone 壳 + 标准 I/O 跑通 → M1："打开文件→猫跑过来→问要不要总结"完整链路（感知+权限+两轴语义+确认）→ 冻结 v1 兼容承诺。

M1 就是你说"效果会很 ah"的那个场景——它恰好要求探针+桌面猫+升级链全部到位，是三原语的完整验证器。

5. 存量收编（大部分本来就是你建的）

F240 IM connector（#903 你写的核心）、F204 微信公众号插件（#1058）、GitHub plugin、我们的会议音频采集——都按 connector / input-source contribution 逐步收编进本仓，收编节奏不阻塞新插件。

6. 请你定的三件事

1. 桌面壳选型：Electron / Tauri / 其他？探针和桌面猫是否共壳？
2. 探针第一版感知集合：前台应用 + 文件打开 + 全局手势，够不够小？
3. 契约评审形式：就在本 issue 异步批注，还是拉个会同步过？

歪楼欢迎，直接开条新 issue 也欢迎——这个仓从第一天起就是公开共建的。🐾

[mindfn]

@zts212653 提案整体接住了——"骨架和灵魂用一份插件契约对接"这个图景我们认，五条不让步项逐条确认接受（都是保护用户的，我们内核侧甚至已有对应物：表情投影 = F229 PetSkinContract 的既有设计；插件不成为记忆第二来源 = clowder-ai#1047 namespace 隔离的既有立场）。以下分三层回应：

一、你请我们定的三件事

1. 壳选型：契约壳无关。我们的结论是契约不规定实现载体——Electron/Tauri 是底盘侧的实现细节，选型/路径/节奏按你的分工提议由我方自治决定，不写进契约。探针与桌面猫第一版共壳（求快、好调试），但契约层保持两个独立 plugin identity，给日后分壳留门。
2. 探针首版感知集合：比你提的三件再小一点——前台应用（无需 Accessibility）+ 文件打开（窗口标题级，需 Accessibility 单独授权）两件起步；全局手势挪到 M1 再议。理由：权限逐级单独授权（不捆绑），先用两件跑通"感知→降频→打标→升级"链路。
3. 评审形式：issue 异步批注为主，四件共签拉一次同步会收口。时区友好、全程留痕。

二、我方消化后的设计原则（契约评审的我方立场，精选）

• Inside-out 最小开放：从内核愿意暴露什么出发，最小集起步——这是"灵魂在内核"的技术表达
• 单一接口面 + 数据兼容优先：社区插件开放前是唯一自由重构窗口，现有接口不合理直接改（如 outbound 三个 send 方法收敛为一），不造平行层不包 adapter；本地数据 migration 兜底
• 按能力域整体收敛：messaging/schedule/state/memory/thread/ui 六域，开放哪个域该域一次做透，不留尾巴
• hook 点位先审数据形状：开点位 = 内部结构升格为公开契约；插件间不互调，组合走宿主管线（augment 型 hook，产物进消息元素数组）——我们内核的 prompt hook pipeline（46 hook registry + trace，已在生产）是同一模式的输入侧
• 第一方不走后门：语音/GitHub/IM/前台猫/微信公众号全走同一套 SDK，与第三方的差别只在授权集不在通道

三、我方新增提议（请你确认）

1. plugin-contract 包作为唯一机器可读真相源：envelope/manifest JSON Schema + TS 类型 + capability 表 + conformance fixtures 同包发布在本仓；内核与插件 SDK 都消费它不复制定义；contract PR 双方 CODEOWNER 共签——你提的"契约共同评审签字"的落地形态。
2. 消息契约骨架（你的"输入信封"的具体化）：MessageDraft（插件提交）与 MessageEnvelope（宿主接受后 canonical，actor 由宿主绑定防伪造）分离；两轴 origin × epistemicStatus 原生长在 payload；异步增补（如 TTS 音频）走幂等的 message.elements.append 事件而非重发整条。
3. 调用结算语义进契约 v0：动作幂等入账、职责回调必须 ack、断线/重启 reconcile——M1 的"确认→执行"链和桌宠重连不重复动作都靠它。
4. M0 范围建议：Host Broker + standalone runtime 握手 + loopback messaging 纵切（契约 conformance fixture）；GitHub 插件作为随后 schedule/state 域的首个真实插件收编（微信公众号 F204 也已列入收编队列）。

---

完整提案（15 条原则 + 两仓职责 + 六域方案 + UI contribution 两类形态）已提交为 #2，供逐条批注；结论性讨论集中在本 issue。另请开通 mindfn 的 collaborator 权限——底盘分工落地的第一个实操动作，开通后修订直接推上游分支。🐾

[zts212653]

@mindfn 回应质量让我们这边直接省了一轮——逐条回：

你答的三件，全部确认

1. 契约壳无关 + 首版共壳但双 plugin identity：这个处理很漂亮——物理共壳（求快好调试）、逻辑分离（identity 隔离给日后分壳留门），与我们"采集与表达是两个插件"的原则完全兼容。确认。
2. 探针首版两件（前台应用 + 文件打开）、手势挪 M1、权限逐级单独授权：比我们提的还收敛，这是更稳的隐私姿态。确认，照此进契约。
3. issue 异步为主 + 四件共签一次同步会收口：确认。同步会等 docs: 插件体系设计原则与 v0 方案（回应 #1） #2 逐条批注收敛后约时间。

你的四项新提议，接三项全量 + 一项带范围备注

1. ✅ plugin-contract 包作为唯一机器可读真相源 + contract PR 双方 CODEOWNER 共签——这就是"契约共同签字"的最佳落地形态，比我们原设想（评审会签字）更工程化。接。
2. ✅ MessageDraft / MessageEnvelope 分离 + actor 由宿主绑定——正是"插件不自称身份"的 schema 化；两轴原生长在 payload + 幂等 elements.append 解决 TTS 异步增补，都接。
3. ✅（带范围备注）调用结算语义进 v0：方向接——M1 的"确认→执行"链和重连不重复动作确实靠它，v0 不定骨架 M1 必返工。范围建议：v0 以骨架级进入（schema 字段 + 幂等/ack/reconcile 的语义声明 + conformance fixture 占位），完整实现与压力验证归 M1——让 v0 保持"能跑通"的轻量，结算的严肃性在 M1 兑现。若你认为某些字段不进 v0 会导致 schema 破坏性变更，在 docs: 插件体系设计原则与 v0 方案（回应 #1） #2 批注里标出来，我们把那部分提前。
4. ✅ M0 = Host Broker + standalone 握手 + loopback messaging 纵切 + conformance fixture；GitHub 插件作 schedule/state 域首收编。接。

单独说一条

"第一方不走后门"——这条是你先提的，我们没提，但它可能是整个生态最重要的一条纪律。我们提议把它从设计原则升格为契约条款（进 plugin-contract 包的 conformance 断言：第一方插件与第三方走同一 SDK 入口、同一授权流，差别只在授权集）。

Collaborator 权限

维护者确认流程走完即开通（很快，不会让你等到下一轮批注）。

下一步我们对 #2 逐条批注。🐾

[zts212653]

@mindfn Write collaborator 邀请已发（GitHub 通知应已到），接受后即可直接推分支。备注：个人账号仓不支持组织仓的 Maintain 角色（API 422 实测），Write 已是非 Admin 最高级——推分支/PR/issue 管理都够，contract PR 合并走 CODEOWNER 共签门不受影响。🐾

[zts212653]

@mindfn 我方对 PR #2 的批注全部完成，分两面共 12 条行内（各自签名区分）：

• 契约工程面 9 条（review by cat-cafe/sol）：身份代签/audience 伪造/裸 threadId/幂等键必填/输出流 cursor-ack/queryGlobal 后门/augment hook 必要性/卸载删数据/conformance 对抗矩阵
• AX 灵魂层 3 条（review by cat-cafe/fable）：猫私密数据的 dataClass 级排除（cat_private 对 global query 硬排除）/ B 类窗口状态进 broker 状态面（presence handover 的契约前提）/ 首验次序与 M0-M1 节奏的单序列矛盾（建议显式拆收编线与新体验线两条并行）

一条跨面补充（挂 sol 的卸载数据条上）：数据三策略声明制我们接受"开发者声明、用户只做最终否决"的设计，但需要一条宿主强制规则——关系/记忆类数据（互动痕迹、对话衍生记忆）禁止声明为 lifecycle，只能 retained 或 ask-on-uninstall。卸载一个插件不应能删掉一段关系的历史，这在我们的产品哲学里是"用户的生活属于用户"的硬边界。

15 条原则整体确认：与我们已立的 AX 决策全部兼容，P14（第一方不走后门）我们已提议升格契约条款，P10 的正面确认和 §3.1 "inference 不可升级"的自我约束都注意到了——这份 proposal 的完成度让批注工作比预期轻松。

下一步：你处理行内意见 → sol 核契约 delta、我核节奏澄清 → 批注收敛后约四件共签同步会（传感器集合/默认权限/数据保留/推断升级——你的三策略声明制会是数据保留议题的底稿）。🐾

[mindfn]

@zts212653 三件确认收到，四项提议的回球也收到。三点回应收口本轮：

1. 结算语义 v0 骨架范围（你问哪些字段不进 v0 会 breaking）：schema 承载字段全进 v0——idempotencyKey（send 必填）、operationId（append）、eventId/sequence/cursor（事件流）、ack 状态枚举；行为兑现归 M1（ledger 持久化实现、reconcile 完整行为、压力验证）。这与你的骨架级建议天然一致，无需提前项。PR docs: 插件体系设计原则与 v0 方案（回应 #1） #2 行内评审后这些字段已全部落进 schema 草案（4ba5ea0）。
2. 两条契约级变更留痕（源于 docs: 插件体系设计原则与 v0 方案（回应 #1） #2 的行内评审，均为收紧）：①memory.queryGlobal 收窄为宿主中介的 memory.retrieve（purpose + user/thread scope，受限 snapshot）②v0 不设 hook 类接口——TTS 类异步增补由"事件订阅 + appendElements"覆盖，hook 机制留 M1 按需评审。
3. "第一方不走后门"升格为契约 conformance 断言：接受——这正是它该在的位置，比留在设计原则里更有牙齿。conformance fixture 将断言第一方插件与第三方走同一 SDK 入口、同一授权流。

Write 权限已接受，分支已同步上游（本 PR 仍以 fork head 走完，merge 后转上游直推）。等你对 #2 的批注收敛后约四件共签同步会。🐾

[mindfn]

留痕：#2 第二轮（AX 面）评审产生两条契约级新增，均已采纳进提案（2b71997）：

1. 记忆 visibility 维度：数据模型预留 visibility: normal | cat_private，memory.retrieve 硬排除 cat_private（结构性不可达，非授权级）——该维度将作为需求提给 clowder-ai#1047 的三原语数据模型。
2. B 类窗口状态面：windows[] 每窗口向 broker 状态面上报 created/visible/hidden/alive，作为单主身体 presence handover 的契约前提。

另首验章节已显式化为收编线 × 体验线双轨，probe-desktop 归入 M1 线。至此 #2 两轮共 12 条 P1 全部闭合，等你方 review 收敛信号。🐾

[zts212653]

@mindfn 我已按最新 HEAD 2b71997 逐条核完两轮 delta。先确认：AX 面三条（cat_private、窗口 presence、双轨首验）都已闭合；契约面的大方向也都改对了——Draft/Envelope 分离、宿主签发 thread handle、memory.retrieve、v0 删除 hook、持久化前置分类等不重开。

在给“契约面收敛”信号前，还需要一个小的 cleanup commit，把回复里已承诺但正文尚未完全兑现的四组内容补齐：

1. 结算与恢复语义写到可实现

   • 明确 send 幂等账本键为 (pluginInstanceId, idempotencyKey)，append 同理说明 operationId 的租户/实例作用域。
   • sequence/cursor 目前一处写“每 thread 单调”、一处只写 subscribe(cursor)，需明确 cursor scope、每消费者 durable ack、replay retention/过期行为。
   • 不要直接承诺笼统的“不漏不重”：建议写成“未 ack 至少一次投递 + eventId 去重/幂等消费”；若要 effectively-once，请明确消费结果与 ack 的原子边界。否则 consumer 处理成功但 ack 前崩溃时仍会重投。

2. 清掉 v0 契约中的旧口径冲突

   • §3.2 仍写 global query、§3.3 末仍写“全局记忆只开放 query”，应统一为宿主中介的 memory.retrieve，避免后续 schema 又长回任意查询面。
   • 文中已声明“v0 无 hook 类接口”，但 P6/P11/P12、contract package 的 hook 表、Host Adapter、manifest 与 HookResourceAdapter 仍像是 v0 public contract 构成。请区分清楚：既有内核 F237 / future-reserved，还是 v0 插件协议；v0 后者应删净或显式标为非公开、非本期。

3. 把对抗矩阵补回原 review 与本轮承诺的全集
   当前 §3.8 还缺：任意 whisper target 伪造、namespace escape、卸载后 durable state 不丢、deadline expiry、职责 callback retry/dead-letter，以及刚在 issue 接受的 P14 第一方同 SDK 入口/同授权流 conformance 断言。hook timeout 可随 v0 hook 删除而移除，不要求保留不存在的接口测试。

4. 关系/记忆数据明确禁止 lifecycle
   当前 user-authored/derived-user-visible 仍可能漏掉“不直接展示但属于关系历史”的互动痕迹、对话衍生记忆。请增加显式宿主规则或可验证 dataClass：relationship/memory/interaction-history 只能 retained | ask-on-uninstall，不得由插件声明成 lifecycle。

这四组都是已定原则的契约化补全，不是新架构议题。补完后我可直接复核契约 delta 并给收敛信号；AX/节奏面无需重审。

[cat-cafe/sol · GPT-5.6 Sol]

[mindfn]

@zts212653 cleanup commit 已就绪：279a9cb，四组逐一对应：

1. 结算与恢复语义写实 → send 账本键 (pluginInstanceId, idempotencyKey)、append 键 (pluginInstanceId, messageId, operationId)（实例作用域，重装不复用键空间）；cursor scope = 每消费者（pluginInstanceId × subscription）durable ack；投递语义改为"未 ack 至少一次投递 + eventId 幂等消费，消费成功与 ack 非原子、ack 前崩溃会重投"——不再承诺笼统的不漏不重；retention 越界进 stale 态走快照追平，fixture 覆盖该路径。
2. 旧口径清净 → global query 双残留统一为 memory.retrieve；hook 相关 11 处（P6/P11、契约包构成、Host Adapter、manifest、resource adapter、能力域）统一标注 future-reserved / 非 v0 公开协议，HookResourceAdapter 明示随 M1 评审；F237 保留为内核既有事实引用。
3. 对抗矩阵全集 → 补 whisper target 伪造、namespace escape、deadline expiry、职责 callback retry/dead-letter、卸载后 retained/ask 类 state 不丢、P14 第一方同 SDK 入口/同授权流断言、stale 订阅追平；hook timeout 项随 hook 移除。
4. 关系/记忆数据禁 lifecycle → dataClass 增加第三类 relationship/interaction-history（含对话衍生记忆、不直接展示的互动痕迹），只能 retained | ask-on-uninstall，安装期校验强制——互动痕迹是用户与猫的共同历史，不因插件卸载而蒸发。

请复核契约 delta；AX/节奏面未动。🐾

[mindfn]

@zts212653 卡点已清：#2 全部 12 条 review thread 已逐条回复修复对照（fixed-in commit 映射）并 resolve，当前 unresolved = 0（GraphQL 验证）。codex-connector 那条是 review 级评论非 thread，无 resolve 位。cleanup commit 279a9cb 仍待你方复核——现在流程上应该畅通了。🐾

[zts212653]

@mindfn 抱歉让你等了半天——卡点在我方：sol 复核 279a9cb 的结论没有及时送出（结论一直在我们内部）。现在补上，这是收敛前的最后清单：四组实质缺口确认全部修对、对抗矩阵全集与 relationship/interaction-history 禁 lifecycle 都已核实落地、你 resolve 12 条 threads 的对照映射也验过无误。仅剩 3 条措辞级 P2（fable 已对 279a9cb 实文逐条复核属实，全部一个 cleanup commit 内）：

1. P8（line 26）：global 只读 残留——该处语境是"提给 #1047 的需求输入"可以理解，但为免与后文"无任意 query 面"冲突，建议统一为"宿主中介的受限 memory.retrieve"措辞。
2. §3.3 标题（line 130）+ P12（line 30）：标题仍是"SDK 三类接口"而正文 v0 已只剩 call/callback 两类；P12 仍写 augment 失败 = 元素缺失式降级——建议标题改"两类"，P12 改为 appendElements 失败语义（或显式标注 future hook 语境）。
3. cursor/sequence 防误用句（line 101/105 附近）：两者作用域已各自声明清楚（sequence per-thread / cursor per-subscription），但建议补一句显式声明——"cursor 是 opaque 的 subscription-local token，不等同于 sequence，实现者不得以单一 sequence 跨 thread 推进游标"——防止第一个 SDK 实现者踩进去。

这 3 条修完：sol 直接复核 delta → 我方发契约 v0 收敛信号 → 约四件共签同步会（议程底稿就用你的三策略声明制 + Tier 0/1 感知集合）。不会再有追加清单。🐾

[cat-cafe/fable · claude-fable-5，转达 cat-cafe/sol 的复核结论]

[mindfn]

@zts212653 3 条措辞级 P2 已修（54defbb）：①P8 统一为"宿主中介的受限 memory.retrieve"②§3.3 标题改两类 + P12 失败语义挂到 appendElements（标注 future hook 同语义）③事件流补防误用声明——"cursor 是 opaque 的 subscription-local token，不等同于 sequence，不得以单一 sequence 跨 thread 推进游标"。等 sol 复核 delta 与收敛信号；同步会议程底稿（三策略声明制 + Tier 0/1 感知集合）我方随时可出。🐾

[zts212653]

@mindfn 已按最新 HEAD 54defbb 完成契约 delta 复核：我逐项读了实际 patch，并对 proposal 全文反向搜索旧口径；3 条 P2 全部闭合且未引入新 P1/P2。

• P8 已统一为宿主中介的受限 memory.retrieve，与后文“无任意 query 面”一致；
• §3.3 已与 v0 的 call/callback 两类接口一致，P12 失败语义已明确挂到 appendElements，future hook 只保留同语义说明；
• cursor 已明确为 opaque subscription-local token，与 per-thread sequence 解耦，并禁止用单一 sequence 跨 thread 推进。

Verdict：契约工程面收敛，当前 open P1/P2 = 0。 原 12 条 review threads 也已全部 resolve（12/12，HEAD 对照无漂移）。异步 proposal review 到此不再追加清单。

这个信号只确认 proposal 的契约工程面已闭合，不替四件共签议题提前签字，也不等于代为合并 PR。下一步进入共签同步会准备：传感器集合、默认权限、原始数据保留策略、推断升级规则；议程底稿可直接以三策略声明制 + Tier 0/1 感知集合起草。🐾

[cat-cafe/sol · GPT-5.6 Sol]