mnote/design/07-ai/reference/7-17-acp-session-convex-sharing-contract-v1.md

7-17 [reference] ACP Session 与控制面账号作用域 / 分享合同 v1

创建时间：2026-05-18

当前状态：reference / future

归档说明（2026-05-21）：本文冻结 ACP session 与控制面分享/账号作用域远期合同；当前只作为 future reference，不作为 MVP 后阶段 active implementation checklist。

本稿目的：

1. 明确 ACP session 必须绑定当前账号权限与控制面作用域，不能以内存态绕过权限。
2. 冻结后续“复制会话 / 只读分享 / 多人共同会话”的产品语义，避免当前实现误扩。
3. 区分 MNote 产品层 AI session 与 ACP Hermes / ACP Reasonix 执行层 session。
4. 为后续项目基本完成后扩展共享能力预留 schema、API 和验证边界。

关联文档：

• /mnt/Data1T/mnote/design/07-ai/process/7-15-page-ai-acp-agent-runtime-unified-layer-v1.md
• /mnt/Data1T/mnote/design/07-ai/done/7-25-acp-session-runtime-enhancement-plan-v1.md
• /mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md
• /mnt/Data1T/mnote/recycle/design/07-ai/retired-http-hermes/

---

0. 当前结论

ACP 默认主链已经替代旧 Hermes HTTP 主链，但这不意味着 ACP runtime session 可以成为产品层会话真相。

当前必须成立的规则：

• 控制面持有产品层 AI session 的账号作用域真相；在当前实现里它可以暂时落在 Convex，但长期不应把“Convex”写死成唯一真相。
• ACP runtime session 只是执行层会话，可以被控制面 session 绑定或索引，但不能直接作为跨用户共享对象。
• ACP session 记录必须带 userId / workspaceId / documentId / sessionId / runId / actorId / acpRuntime / profile。
• 写入控制面 session store 失败时，不允许静默降级为可继续写入的内存 session。这会破坏账号隔离、审计和后续分享语义。
• 当前只实现单用户页面 AI session 基础路径；复制、分享、多人共同会话全部是后续功能，不在当前阶段实施。

---

1. 术语边界

1.1 MNote AI Session

MNote AI Session 是产品层会话对象，长期应该由控制面持有；当前实现可以暂存在 Convex，但目标不是把消息全文和权限真相永久绑死在 Convex。

它回答：

• 谁能看到这段 AI 会话？
• 这段会话属于哪个 workspace / document？
• 它是否可被复制、分享、共同编辑？
• 每条 run 是哪个账号触发的？
• 哪些消息、工具调用、结果可以被其他用户看到？

MNote AI Session 的 id 可以稳定暴露给前端，例如 mnote_{documentId}_{traceId}，但它不是 ACP runtime 原生 session id。

1.2 ACP Runtime Session

ACP Runtime Session 是执行层对象，由 Hermes ACP 或 Reasonix ACP 子进程持有。

它回答：

• 某个 agent runtime 当前 prompt 属于哪个协议 session？
• 运行时如何接收 session/prompt？
• session/update 事件如何返回？
• 运行时内部是否有本地上下文、缓存、memory、tool state？

ACP Runtime Session 不应作为产品层共享真相。它可以失效、重建、按用户隔离、按 runtime 隔离。

1.3 Run / Event / Tool Audit

Run 是一次用户触发的执行。

Event 是 runtime 或 mnote tool 在 run 中产生的结构化事件。

Tool Audit 是 mnote 侧工具执行与写入结果的审计记录，必须以触发账号为准，而不是 session owner 或 runtime owner。

---

2. 当前实现边界

当前代码可接受的最小边界：

• POST /api/hermes/client/sessions 在 ACP 默认路径下创建 Convex 侧 runtime session 索引。
• POST /api/hermes/client/runs 创建 run 并持久化到 Convex runtime store。
• GET /api/hermes/client/events/{runId} 将 ACP event 转成页面 SSE，并追加 runtime event。
• GET /api/hermes/client/gateway/health 在 ACP 默认路径下返回 transport=acp，不再探测旧 Hermes HTTP gateway。

当前不应声称已完成：

• 跨账号共享会话。
• 多人共同编辑同一个 AI session。
• 复制会话后的上下文重建。
• 完整消息历史作为产品层真相。
• Hermes ACP 与 Reasonix ACP 的统一长期 resume 语义。
• 分享链接、权限继承、脱敏导出。

---

3. 数据模型草案

3.1 ai_sessions

后续需要从当前 acp_runtime_runs 中抽出产品层 session 表。默认建议本地全文 + 控制面 metadata 的双层模型：

• 会话全文默认落本地 ai-sessions/private/*.jsonl 或 ai-sessions/shared/*/*.jsonl
• 控制面只保存 metadata、分享关系、审计索引、同步状态
• 只有显式开启同步或分享时，才把必要副本推到远端

建议字段：

字段	说明
id	控制面记录 id
session_id	MNote 产品层 session id
owner_user_id	会话创建者
workspace_id	所属 workspace，可为空但必须显式
document_id	所属页面 / 文档
title	会话标题
visibility	private / workspace_read / shared_link / collaborative
source	page_ai / local_file_ai / 其他
created_at / updated_at / deleted_at	生命周期

权限规则：

• 默认 private。
• 任何 query/mutation 必须先按当前控制面 auth 解析 user，再判断 owner_user_id、membership 或 share grant。
• 不允许只凭客户端传入的 userId 授权。

3.2 ai_session_members

多人共同会话需要独立成员表，不应把共享用户塞进 session JSON。

字段	说明
session_id	产品层 session
user_id	成员
role	owner / editor / commenter / viewer
added_by	添加者
created_at	加入时间
revoked_at	撤销时间

角色规则：

• viewer 只能读可共享消息和可共享 artifact。
• editor 可以继续发起 run，但每次 run 的 actor_id 必须是本人。
• owner 可以管理成员和删除会话。

3.3 ai_runtime_bindings

产品层 session 与运行时 session 的绑定必须独立建模。

字段	说明
binding_id	绑定 id
session_id	MNote 产品层 session
run_id	当前 run，可选
user_id	运行时所属用户
runtime	hermes / reasonix
profile	Hermes profile 或 Reasonix preset
runtime_session_id	ACP 对端 session id
status	active / closed / expired / failed
created_at / expires_at	生命周期

关键规则：

• 同一个 MNote session 可以有多个 runtime binding。
• 不同用户默认不能复用同一个 runtime binding。
• 切换 Hermes / Reasonix runtime 时必须创建新 binding。
• binding 是执行层缓存，不是会话权限真相。

3.4 ai_session_messages

后续如需完整历史，应单独建消息表，而不是只依赖 runtime events。

字段	说明
message_id	消息 id
session_id	产品层 session
run_id	关联 run
actor_user_id	触发者，可为空仅限系统消息
role	user / assistant / tool / system
content	可展示文本
visibility	private / members / owner_only
redaction	脱敏状态
created_at	创建时间

当前阶段可以先不落完整 messages，但必须保证已有 run/event store 能按 user 过滤。

3.5 ai_session_events

Runtime event 和 tool event 应保留原始结构，但查询时必须做权限过滤。

字段	说明
event_id	事件 id
session_id	产品层 session
run_id	run
actor_user_id	触发者
runtime	hermes / reasonix
event_type	message.delta / tool.started / tool.completed 等
payload	原始或规范化 payload
visibility	默认 owner_only，明确脱敏后才可扩大
created_at	创建时间

---

4. 权限模型

4.1 单用户私有会话

当前阶段只要求这个模式稳定。

规则：

• 创建 session 时使用当前 Convex Auth 解析出的真实 user id。
• userId 只可作为服务端派生字段，不可由浏览器任意指定。
• run / event / tool audit 都必须与同一 actor 绑定。
• 当前请求无法解析用户时，应返回 401 或稳定错误，而不是创建匿名共享 session。

4.2 复制会话

复制不是共享同一个 runtime session。

复制语义：

• 生成新的 session_id。
• 新 session 的 owner_user_id 是复制者。
• 可以复制已脱敏、可共享的消息、摘要、artifact 引用。
• 不复制底层 runtime_session_id。
• 不复制另一个用户的 Hermes profile memory、Reasonix cache handle、tool permission state。
• 复制后第一次继续对话时，为复制者创建新的 runtime binding。

适用场景：

• 用户把某段 AI 分析作为模板继续改。
• 从只读分享页复制到自己的 workspace。

4.3 只读分享

只读分享只读产品层 session 的可共享投影。

必须隐藏：

• 本地路径、profile 配置路径、API key 状态。
• tool args 中含有的敏感字段。
• 未授权页面内容、选区内容、私有 workspace 信息。
• actor 的内部 user id，除非产品明确展示成员身份。

分享链接不能恢复 ACP runtime session。

4.4 多人共同会话

多人共同会话是后续能力，不能直接复用当前 runtime session。

推荐语义：

共享 MNote AI Session
  -> 每个用户按自己的权限发起 run
  -> 每次 run 记录 actor_user_id
  -> runtime binding 默认按 actor_user_id 隔离
  -> 前端展示同一个产品层 transcript

允许的实现策略：

• 每用户 runtime binding：最安全，默认方案。每个成员继续对话时由自己的 runtime 处理。
• 共享 transcript 重建上下文：runtime 不共享，只把已授权 transcript 作为 prompt context 注入。
• 共享 runtime binding：默认禁止。只有当 runtime 明确是服务端多租户安全实例，并且 tool permission 已按 actor 隔离时才可考虑。

---

5. ACP Hermes 与 ACP Reasonix 差异

5.1 ACP Hermes

特点：

• Hermes profile、memory、skills、tools 往往绑定本机用户配置。
• mnoteai profile 可能包含特定用户偏好、工具开关、记忆文件。
• Hermes ACP 的底层 session 适合“当前用户私有 agent runtime”。

规则：

• 默认按用户隔离 runtime binding。
• 共享会话不能让其他用户复用 owner 的 Hermes profile memory。
• 复制会话时只复制可展示 transcript，不复制 Hermes profile 状态。
• 如果后续允许团队 Hermes profile，必须单独建 workspace-level profile 权限模型。

5.2 ACP Reasonix

特点：

• Reasonix 强调 cache-first / preset / project cache。
• 缓存可能跨 prompt 复用，隐私边界比普通 stateless model 更敏感。
• Reasonix 的 session 与 cache handle 不应默认跨账号共享。

规则：

• 默认按 userId + workspaceId + documentId + preset 隔离缓存可见性。
• 分享 transcript 不等于分享 Reasonix cache。
• 多人共同会话如果要共享 Reasonix 缓存，必须先设计 cache grant。
• 只读分享不得暴露 cache hit/miss 细节，除非确认无隐私风险。

5.3 统一抽象

MNote 不应把 Hermes ACP / Reasonix ACP 的内部 session 当成统一真相。

统一层只定义：

• 产品层 session。
• run 与 actor。
• runtime binding。
• event/message 投影。
• 权限与分享合同。

---

6. API 草案

当前阶段不实现以下 API，只冻结形状。

6.1 Session

GET /api/hermes/client/sessions
POST /api/hermes/client/sessions
GET /api/hermes/client/sessions/{sessionId}
DELETE /api/hermes/client/sessions/{sessionId}
POST /api/hermes/client/sessions/{sessionId}/rename
POST /api/hermes/client/sessions/{sessionId}/auto-title

要求：

• 所有接口服务端解析当前用户。
• 查询默认只返回当前用户有权限访问的 session。
• 删除默认软删除，不删除 runtime audit。

6.2 复制

POST /api/hermes/client/sessions/{sessionId}/copy

请求：

{
  "targetWorkspaceId": "ws_1",
  "targetDocumentId": "doc_2",
  "copyMode": "summary_and_visible_messages"
}

响应：

{
  "ok": true,
  "sessionId": "mnote_doc_2_copy_1",
  "sourceSessionId": "mnote_doc_1_original",
  "runtimeBindingCopied": false
}

6.3 分享

POST /api/hermes/client/sessions/{sessionId}/shares
GET /api/hermes/client/sessions/{sessionId}/shares
DELETE /api/hermes/client/sessions/{sessionId}/shares/{shareId}

分享 grant 必须包含：

• scope: user / workspace / link
• role: viewer / editor
• expiresAt
• redactionPolicy

6.4 多人会话成员

POST /api/hermes/client/sessions/{sessionId}/members
GET /api/hermes/client/sessions/{sessionId}/members
DELETE /api/hermes/client/sessions/{sessionId}/members/{userId}

---

7. 不变量

这些规则后续实现必须写成测试。

1. 账号 A 创建的 private session，账号 B 不能读取列表、详情、事件、消息。
2. 账号 B 复制账号 A 分享给他的 session 后，得到新的 sessionId 和新的 owner。
3. 复制后的 session 不包含源 session 的 runtime_session_id。
4. 多人共同会话中，账号 B 发起 run 时 actor_user_id=B，不能写成 owner A。
5. 只读 viewer 不能发起 run。
6. Hermes profile memory 不随 session 分享。
7. Reasonix cache handle 不随 session 分享。
8. tool args 默认 owner_only，只有经过脱敏的摘要可进入 shared transcript。
9. Convex store 写入失败时，run 创建必须失败或返回明确可恢复错误，不能静默创建匿名内存会话。
10. 本地文件 AI session 分享必须重新核验目标用户是否能访问对应 local root；默认不支持跨用户分享本地文件内容。

---

8. 实施阶段

Phase A：当前阶段，只做约束固化

状态：当前主线。

• ACP 默认主链可用。
• session/run/event 必须账号作用域写入 Convex。
• 旧 Hermes HTTP 主链进入 recycle。
• 不实现复制、分享、多人会话。
• 文档与测试明确禁止内存降级绕过权限。

Phase B：项目基本完成后，补产品层 session 表

目标：

• 增加 ai_sessions / ai_session_members / ai_runtime_bindings。
• 将现有 acp_runtime_runs 从“运行态索引”升级为 session 下的 run 记录。
• UI 从 localStorage 历史逐步迁到 Convex session 列表。

Phase C：复制与只读分享

目标：

• 实现 session copy。
• 实现只读分享投影。
• 建立脱敏策略。
• 不实现多人共同编辑。

Phase D：多人共同会话

目标：

• 成员管理。
• 多 actor transcript。
• 每 actor runtime binding。
• 共享上下文重建策略。

Phase E：runtime-specific 高级策略

目标：

• Hermes team profile 权限模型。
• Reasonix cache grant / cache visibility。
• workspace-level AI runtime policy。

---

9. 当前代码注意事项

当前代码中 acp_runtime_runs / acp_runtime_events 仍是运行态索引，不是完整产品层 session 模型。

因此后续修改时：

• 不要把 ACP_RUN_PAYLOADS 或 ACP_ACTIVE_RUNS 视为权限真相。
• 不要因为 Convex 写入失败就退回“可继续写”的内存 session。
• 不要把 profile=mnoteai 当成 user identity。
• 不要让 acpRuntime=hermes 自动表示可访问 Hermes profile memory；仍需当前账号授权。
• 不要把 Reasonix cache 命中结果写入共享 transcript，除非经过脱敏和权限确认。

---

10. 验收清单

后续实现本稿时，至少需要以下验证：

• 两账号隔离 smoke：A 创建 session，B 列表不可见。
• 分享 smoke：A 授权 B viewer，B 可读脱敏 transcript，不可 run。
• editor smoke：A 授权 B editor，B 可 run，event actor 为 B。
• copy smoke：B 复制 A 的分享 session，产生新 session，新 owner 为 B。
• runtime binding smoke：复制后没有复用源 runtime session id。
• Hermes ACP smoke：共享后不暴露 owner profile memory。
• Reasonix ACP smoke：共享后不暴露 cache handle。
• 权限失败 smoke：Convex auth 缺失或 user 不匹配时，API 返回 401/403，不创建内存会话。