feat(page-ai): add skill context and agent profile policy

2026-05-29 21:57:29 +08:00
parent 631205ba2f
commit 49a0545148
18 changed files with 3478 additions and 259 deletions
@@ -0,0 +1,425 @@
+# 7-41 Page AI Hermes / Reasonix user profile isolation v2
+
+> 创建时间：2026-05-29
+>
+> 状态：`process`
+>
+> Owner：Page AI agent identity / Hermes profile policy / Reasonix memory policy
+>
+> 上位依据：
+> - `design/07-ai/done/7-39-page-ai-agent-selector-context-authorization-settings-v1.md`
+> - `design/07-ai/done/7-40-page-ai-context-envelope-and-run-receipt-v1.md`
+> - `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
+> - `design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md`
+>
+> 参考依据：
+> - Hermes 官方 profile 文档：profile 是独立 Hermes home，包含 `config.yaml`、`.env`、`SOUL.md`、memories、sessions、skills、cron、state database、gateway state。
+> - Hermes WebUI：技能 toggle 直接写 profile `config.skills.disabled`。
+> - Hermes VSCode：只管理会话和一次性上下文建议，不提供真正的 per-user skill disable。
+> - PilotDeck：以 WorkSpace 为边界隔离文件、记忆和技能，并强调白盒记忆可追溯。
+> - Reasonix 文档/本地实现：默认使用 `~/.reasonix/memory/global` 与 `~/.reasonix/memory/<project-hash>`，`REASONIX_MEMORY=off|false|0` 可关闭 memory 注入。
+
+## 1. 背景
+
+`7-39` 已把 Page AI UI 收口为 agent selector + contextRefs + SQLite per-user preference。`7-40` 进一步把 MNote skill library 定位为 agent 可按需读取的能力摘要，而不是每轮强行注入 prompt。
+
+但当前 Hermes skill/profile 的真实边界仍不正确：
+
+- Hermes 的 `skills.disabled` 是 profile 级配置，不是 MNote 用户级偏好。
+- Hermes profile 自带 `SOUL.md`、memory、session、skills 和 state；多个 MNote 用户共用同一个可写 profile，会把个人偏好、记忆和技能配置混在一起。
+- 当前 Page AI UI 已经能展示 Hermes skill toggle，但普通用户如果直接写共享 Hermes profile，就会影响其它用户。
+- Reasonix 虽然不像 Hermes 那样有 SOUL 人格，但它也有 global/project memory。默认共享 `~/.reasonix` 时，不能假设完全无状态。
+
+因此本稿把 Page AI agent identity 从“选择 Hermes / Reasonix”提升为“选择 agent + profile scope + memory policy”。
+
+## 2. 产品决策
+
+### 2.1 Hermes profile 分层
+
+Hermes profile 分为两类：
+
+| profile kind | owner | 普通用户能否使用 | 普通用户能否改 skill | memory/session |
+| --- | --- | --- | --- | --- |
+| `personal` | 单个 MNote 用户 | 能 | 能，仅限自己的 profile | 用户独立 |
+| `shared` | 系统 / 管理员 | 能，若管理员公开 | 不能 | 默认不写入用户私有长期记忆 |
+
+初始共享 Hermes profile 只包含 `lite`。
+
+要求：
+
+- 每个 MNote 用户可以访问自己的 personal Hermes profile。
+- 每个 MNote 用户可以访问被管理员公开的 shared Hermes profile。
+- shared Hermes profile 的 skill/config 只有管理员能改。
+- personal Hermes profile 的 skill/config 只有该 profile owner 或管理员能改。
+- Page AI 发送请求时必须携带解析后的 `agentProfileRef`，不能只携带裸 `profile=lite`。
+
+### 2.2 MNote 内置技能开关
+
+MNote 内置 skill / tool 属于 MNote 自己的能力面，普通用户应该可以按用户启停。该开关不写 Hermes profile，而是写 SQLite control-plane。
+
+含义：
+
+- `mnote_builtin_skill_enabled` 是 per-user 偏好和服务端执行策略，必须按当前 SQLite 用户隔离。
+- `hide_builtin_skills=true` 只是 UI 展示偏好，用于折叠或隐藏 MNote 内置能力说明；它不等于禁用。
+- MNote tool 是否可调用由服务端根据 `user_id + agentId + contextRefs + allowedRoots + mnote_builtin_skill_enabled` 决定。
+- 普通用户可启停自己的 MNote 内置 skills；管理员可设置默认值或全局禁用策略。
+- MNote 内置 skill 开关不修改 Hermes profile `config.yaml`，也不影响 shared Hermes profile。
+
+### 2.3 Hermes profile skills
+
+可以配置的只有 Hermes profile 自己的 skills。
+
+规则：
+
+- personal profile：用户可启停该 profile 下的 Hermes skills，写入该 personal profile 的 `config.yaml`。
+- shared profile：普通用户只读；管理员可启停 shared profile skills。
+- skill toggle API 必须做服务端权限检查，不能只靠 UI 禁用按钮。
+- MNote 不再把 `ai.agent.hermes.profile.<name>.skills.enabled` 当成普通用户对共享 profile 的安全开关；MNote 内置 skill 的 per-user 开关应使用独立 SQLite key。
+
+### 2.4 Reasonix memory policy
+
+Reasonix 默认关闭 memory 注入。
+
+规则：
+
+- 默认启动 Reasonix ACP 时设置 `REASONIX_MEMORY=off`。
+- 每个 MNote 用户可在设置中开启 Reasonix memory。
+- 该设置保存到 SQLite `user_ui_preferences`，按用户隔离。
+- 开启后，UI 需明确标注 Reasonix 将使用 global/project memory。
+- 第一阶段不强制给 Reasonix 每用户独立 HOME；若后续需要更强隔离，再增加 `reasonix_home_mode=per_user`。
+
+## 3. 数据合同
+
+### 3.1 Agent profile ref
+
+Page AI payload 中新增或固定以下结构：
+
+```json
+{
+  "agentId": "hermes",
+  "agentProfileRef": {
+    "kind": "personal",
+    "profileId": "usr_123_default",
+    "ownerUserId": "usr_123",
+    "baseProfile": "default",
+    "displayName": "我的 Hermes"
+  }
+}
+```
+
+shared profile：
+
+```json
+{
+  "agentId": "hermes",
+  "agentProfileRef": {
+    "kind": "shared",
+    "profileId": "shared_lite",
+    "ownerUserId": null,
+    "baseProfile": "lite",
+    "displayName": "Lite"
+  }
+}
+```
+
+服务端要求：
+
+- 不接受浏览器直接提交任意 Hermes filesystem path。
+- `profileId` 必须由 SQLite control-plane 解析到当前用户可访问的 profile。
+- 对 personal profile，当前用户必须是 owner 或 admin。
+- 对 shared profile，必须是公开 profile 或 admin。
+- 所有 run / skill list / skill toggle / settings read 都通过 `agentProfileRef` 解析，不走裸 profile name。
+
+### 3.2 SQLite control-plane
+
+建议新增控制面表，避免只用偏好 key 表达权限关系：
+
+```text
+ai_agent_profiles
+- id
+- agent_id                 # hermes
+- profile_kind             # personal | shared
+- owner_user_id            # personal 必填，shared 为空
+- base_profile_name        # Hermes 原始 profile 名或模板名
+- isolated_profile_name    # MNote 管理后的真实 Hermes profile 名
+- display_name
+- status                   # active | disabled
+- created_at
+- updated_at
+
+ai_agent_profile_grants
+- profile_id
+- user_id
+- role                     # owner | user | admin
+- can_run
+- can_manage_skills
+- can_manage_config
+- created_at
+- updated_at
+```
+
+第一阶段也可以在现有 `user_ui_preferences` 中保存默认选择：
+
+- `ai.agent.hermes.default_profile_id`
+- `ai.agent.hermes.hide_builtin_skills`
+- `ai.agent.mnote_builtin.skills.enabled`
+- `ai.agent.reasonix.memory_enabled`
+
+但 profile 权限、owner、shared/personal 类型不应只存在于 UI preference。
+
+MNote 内置 skill 的用户级开关可以第一阶段存在 `user_ui_preferences`，但服务端 tool policy 读取时必须视为执行策略，而不是纯 UI 状态。若后续需要审计、管理员默认值或组织策略，应升级为独立表：
+
+```text
+ai_user_skill_preferences
+- user_id
+- skill_id
+- enabled
+- updated_at
+```
+
+### 3.3 Hermes profile provisioning
+
+创建 personal Hermes profile 时：
+
+- 可从共享模板复制 `config.yaml`、`.env`、`SOUL.md` 和 skills。
+- 不复制 memories、sessions、state database、gateway state。
+- 生成的真实 profile name 必须包含 MNote 用户隔离标识，例如 `mnote-u-<userId>-default`。
+- provisioning 过程由服务端执行，并记录到 SQLite control-plane。
+
+shared `lite`：
+
+- 初始由管理员登记为 `shared_lite`。
+- 普通用户只可 run / list readonly。
+- 管理员可改 skill/config。
+
+## 4. API 合同
+
+### 4.1 Profile list
+
+`GET /api/ai/agent-profiles?agentId=hermes`
+
+返回当前用户可访问 profiles：
+
+```json
+{
+  "profiles": [
+    {
+      "profileId": "usr_123_default",
+      "kind": "personal",
+      "displayName": "我的 Hermes",
+      "canRun": true,
+      "canManageSkills": true
+    },
+    {
+      "profileId": "shared_lite",
+      "kind": "shared",
+      "displayName": "Lite",
+      "canRun": true,
+      "canManageSkills": false
+    }
+  ]
+}
+```
+
+### 4.2 Skill list
+
+`GET /api/hermes/client/skills?profileId=...`
+
+要求：
+
+- personal profile 返回可 toggle 状态。
+- shared profile 对普通用户返回 readonly 状态。
+- MNote 内置 skills 返回值必须标记 `builtin=true`、`configurable=true`、`configScope=user_sqlite`。
+- Hermes profile skills 标记 `builtin=false`、`configurable=canManageSkills`。
+
+### 4.3 Skill toggle
+
+`PUT /api/hermes/client/skills/toggle`
+
+请求：
+
+```json
+{
+  "profileId": "usr_123_default",
+  "skillName": "writer",
+  "enabled": false
+}
+```
+
+服务端必须：
+
+- 解析 `profileId`。
+- 若 `skillKind=mnote_builtin`，写当前用户 SQLite skill preference，不写 Hermes profile。
+- 若 `skillKind=hermes_profile`，校验 `canManageSkills=true`。
+- 拒绝普通用户修改 shared profile 的 Hermes profile skills。
+- personal profile skill toggle 只写目标 Hermes profile 的 `config.yaml`。
+
+错误码建议：
+
+- `ai_profile_not_found`
+- `ai_profile_forbidden`
+- `ai_profile_readonly`
+- `ai_builtin_skill_preference_failed`
+- `hermes_skill_toggle_failed`
+
+### 4.4 Reasonix run
+
+Reasonix ACP spawn / session create 需读取当前用户设置：
+
+```json
+{
+  "agentId": "reasonix",
+  "memoryPolicy": {
+    "enabled": false,
+    "source": "user_ui_preferences"
+  }
+}
+```
+
+默认：
+
+- `enabled=false`
+- 子进程环境包含 `REASONIX_MEMORY=off`
+
+开启：
+
+- 不设置 `REASONIX_MEMORY=off`，或设置为 `on`
+- UI 明确展示 memory 已开启
+
+## 5. UI 设计
+
+### 5.1 Agent selector
+
+Hermes agent 下增加 profile 子选择：
+
+```text
+Hermes
+  我的 Hermes              personal · 可配置
+  Lite                     shared · 只读
+```
+
+显示规则：
+
+- personal profile 显示“可配置”。
+- shared profile 显示“共享 / 只读”。
+- 若普通用户选择 shared profile，技能开关显示为只读。
+- 管理员选择 shared profile，技能开关可用，并显示“管理员正在修改共享 profile”。
+
+### 5.2 Skills panel
+
+三组仍保留：
+
+- MNote 内置技能：可折叠，可隐藏/显示，也可由普通用户按自己账号启停。
+- Hermes 技能：随当前 Hermes profile 变化；personal 可配置，shared 普通用户只读。
+- Reasonix 技能：展示可用能力；memory 是单独设置，不混入 skill toggle。
+
+Hermes profile 切换时：
+
+- 必须重新加载 profile skills。
+- 必须清空旧 profile skill cache。
+- `hide_builtin_skills` 不随 Hermes profile 改变；它是用户 UI 偏好。
+- MNote 内置 skill enable/disable 不随 Hermes profile 改变；它是当前 MNote 用户的 SQLite policy。
+
+### 5.3 Settings
+
+设置页拆分：
+
+- Common：授权区域、contextRefs 默认值、内置技能显示/隐藏、内置技能启停。
+- Hermes：默认 Hermes profile、personal profile 管理、shared profile 只读/管理员管理。
+- Reasonix：默认关闭 memory；用户可开启。
+- Chat-only：只聊天配置。
+
+## 6. 非目标
+
+- 不让普通用户直接修改 shared Hermes profile。
+- 不把 shared Hermes profile 用作沉淀个人偏好的长期人格。
+- 不在本阶段实现 Reasonix per-user HOME；只实现默认 memory off 与可选开启。
+- 不新增第二套目录授权真相；文件访问仍由 SQLite directory grants / allowedRoots 控制。
+- 不实现 PilotDeck 的完整 router、always-on 或 memory engine。
+
+## 7. Checklist
+
+### Batch A - 现状冻结与风险取证
+
+- [ ] 复核当前 Page AI Hermes skill toggle 的真实写入路径，确认是否直接写 Hermes profile `config.yaml`。
+- [ ] 复核当前 UI preference 中 `hide_builtin`、MNote 内置 skill enabled、profile skill enabled、default profile 的存储键。
+- [ ] 复核 Reasonix ACP spawn 环境，确认当前是否默认注入 memory。
+- [ ] 形成 RED 证据：普通用户修改 shared profile skill 会影响其它用户，或当前缺少服务端权限边界。
+- [ ] 验证：Rust/JS 只读审计记录在本文档或后续 checklist evidence 中。
+
+### Batch B - SQLite profile policy 合同
+
+- [ ] 新增或扩展 SQLite control-plane profile policy：`ai_agent_profiles` / `ai_agent_profile_grants` 或等价结构。
+- [ ] 初始化 shared Hermes profile：仅 `lite`，普通用户 `canRun=true`、`canManageSkills=false`。
+- [ ] 为每个用户 provision personal Hermes profile。
+- [ ] 补 Rust 定点测试：personal owner、shared readonly、admin manage、跨用户不可管理。
+- [ ] 验证：不同用户查询 profile list 只返回自己 personal + shared lite。
+
+### Batch C - Hermes profile resolver
+
+- [ ] 新增服务端 `agentProfileRef` resolver，禁止前端提交任意 Hermes path。
+- [ ] `/api/hermes/client/runs` 从 `profileId` 解析真实 Hermes profile。
+- [ ] `/api/hermes/client/skills` 从 `profileId` 解析真实 Hermes profile。
+- [ ] 保留旧 `profile=` 参数只作为兼容入口，并映射到当前用户可访问 profile。
+- [ ] 验证：旧路径兼容不允许越权访问 shared/admin profile。
+
+### Batch D - Skill toggle 权限收口
+
+- [ ] 修改 skill toggle API：只接受 `profileId + skillName + enabled`。
+- [ ] 区分 `mnote_builtin` 与 `hermes_profile` skill kind。
+- [ ] MNote 内置 skill toggle 写当前用户 SQLite preference。
+- [ ] 拒绝普通用户修改 shared profile 的 Hermes profile skills。
+- [ ] personal profile skill toggle 只写该用户 isolated profile `config.yaml`。
+- [ ] shared profile skill toggle 仅 admin 可写。
+- [ ] 验证：Rust API 测试覆盖 `ai_profile_readonly`、MNote 内置 skill per-user toggle、personal profile skill success。
+
+### Batch E - MNote 内置 skill per-user policy
+
+- [ ] 将 MNote 内置 skill enable/disable 保存为 SQLite per-user policy。
+- [ ] UI 中 `hide_builtin_skills` 只影响展示，不影响 enable/disable。
+- [ ] Skills panel 标记 `builtin=true`、`configurable=true`、`configScope=user_sqlite`。
+- [ ] 服务端 MNote tool policy 按 `user_id + agentId + contextRefs + allowedRoots + mnote_builtin_skill_enabled` 判断。
+- [ ] 验证：用户 A 禁用某内置 skill 不影响用户 B；禁用后对应 MNote tool 被服务端拒绝；隐藏展示不影响 enable 状态。
+
+### Batch F - Reasonix memory policy
+
+- [ ] 新增 per-user 设置 `ai.agent.reasonix.memory_enabled`，默认 `false`。
+- [ ] Reasonix ACP spawn 默认设置 `REASONIX_MEMORY=off`。
+- [ ] 开启 memory 后不注入 `REASONIX_MEMORY=off`，并在 UI 显示 memory enabled。
+- [ ] 补 JS/Rust 测试或 smoke，覆盖默认 off、用户开启、不同用户隔离 preference。
+- [ ] 验证：普通消息由 Reasonix 自己决定是否使用工具；MNote 不再强行注入 memory/context 正文。
+
+### Batch G - UI 收口
+
+- [ ] Agent selector 中 Hermes profile 显示 personal/shared/readonly 状态。
+- [ ] Skills panel 三组均可折叠。
+- [ ] Hermes profile 切换必须刷新 skill catalog，避免旧 profile skill 残留。
+- [ ] shared profile 的 Hermes profile skills 对普通用户展示只读开关或锁定状态。
+- [ ] MNote 内置 skills 对普通用户展示可启停状态，并标明按当前 MNote 用户保存。
+- [ ] 管理员对 shared profile 显示可管理状态，并提示影响所有用户。
+- [ ] 验证：真实浏览器截图覆盖 MNote 内置 skill per-user 可配置、personal Hermes skill 可配置、shared Hermes skill 只读、admin shared 可配置。
+
+### Batch H - 回归矩阵与文档收尾
+
+- [ ] 更新 Page AI 设计说明，明确 MNote 内置 skill per-user policy、personal/shared Hermes profile 与 Reasonix memory policy。
+- [ ] 更新 smoke：agent 切换、MNote 内置 skill per-user toggle、Hermes profile 切换、shared readonly、personal skill toggle、Reasonix memory off/on。
+- [ ] 运行 `node --check` 覆盖相关 browser runtime / smoke。
+- [ ] 运行 Rust 定点测试覆盖 SQLite profile policy 与 Hermes skill toggle 权限。
+- [ ] 运行真实浏览器验证并截图。
+- [ ] 运行 `git diff --check`。
+- [ ] 涉及代码图后运行 `codegraph sync .`。
+- [ ] 完成后将本 checklist 移动到 `done/` 或标记为 `done`。
+
+## 8. 验收口径
+
+完成后必须满足：
+
+- 普通用户可以启停自己的 MNote 内置 skills，开关保存到 SQLite 并由服务端 tool policy 执行。
+- 用户 A 的 MNote 内置 skill 开关不影响用户 B。
+- 普通用户无法修改 shared `lite` 的 Hermes profile skills。
+- 普通用户可以修改自己的 personal Hermes profile skills。
+- MNote 内置 skill 的显示/隐藏与启停是两个不同状态：隐藏只影响 UI，启停影响服务端可调用性。
+- Hermes profile 切换后 skill catalog 正确刷新。
+- Reasonix 默认 memory off，开启 memory 是 per-user preference。
+- Page AI run payload 不再用裸 Hermes profile name 表达身份，而是经服务端解析的 `agentProfileRef` / `profileId`。
+- 所有文件访问仍受 SQLite directory grants / allowedRoots 约束。