# RBAC / Skill / 主 Agent 权限与回归矩阵

更新时间：`2026-04-27`

这份文档只梳理当前已经落地或明确未生产化的多用户、RBAC、Skill、主 Agent 权限和多设备控制链路。当前运行真相仍以 `current_runtime_and_deploy_status_cn.md` 和 `api_and_service_inventory_cn.md` 为准。

## 1. 当前开发状态

### 1.1 已落地

- 多用户 / RBAC 第一阶段已经落地到文件状态：`accountDeviceGrants / accountProjectGrants / accountSkillGrants / skillCatalog / permissionAuditLogs` 已进入 `BossState`。
- 最高管理员授权台已经可用：`GET/POST /api/v1/admin/access` 仅 `highest_admin` 可访问，支持创建 / 更新子账号、授予设备 / 项目 / Skill 权限、套用模板和撤销授权。
- Web `/me/access` 与 Android `AccessManagementActivity` 已接入授权管理；`member` 不显示入口，直接请求也应返回 `403`。
- 会话、设备、项目详情、消息读写、设备 Skill、`/api/state` 已按当前登录账号裁剪；最高管理员保持全局可见。
- 主 Agent prompt 与任务队列已接入授权快照：生成提示词时只带当前账号可见设备、项目、线程状态文档、进展事件和 Skill；`MasterAgentTask` 会记录 `authorizedDeviceIds / authorizedProjectIds / authorizedSkillIds / requiredPermissions`。
- 本地 `local-agent` 已能扫描 `~/.codex/skills` 并同步到云端设备 Skill 接口；Web / Android Skill 页按授权后的设备和 Skill 展示。
- 普通线程单聊、群聊下发、设备导入审核、browser/desktop 控制都已经进入 `master-agent task queue -> local-agent -> complete` 主链。
- browser/desktop 控制已从占位结果升级为外部 runtime 桥：未配置时 fail closed，配置 smoke runtime 时可回写结构化 `control_summary`。

### 1.2 部分落地但仍属 MVP

- 登录会话已有 `boss_session`、原生 `restore token` 和单会话撤销，但还没有独立刷新令牌、完整吊销审计、CSRF 防护和更细风控策略。
- `permissionAuditLogs` 已有第一版最高管理员查询入口和 deterministic 风险摘要；仍不是后台持久告警、归档和独立审计存储系统。
- Skill 当前已支持“扫描、展示、授权、复制调用语句、进入主 Agent 授权上下文”，并新增最高管理员发起的远程安装 / 更新 / 卸载 / 回滚 / 版本锁请求；local-agent 会认领并执行本机 Skill 文件或 Git 操作，但还不是带签名校验、依赖沙箱和执行审计的完整 Skill 平台。
- 主 Agent 可以携带授权快照并派任务，但审批流仍是局部场景：群聊 `approval_required` 已有确认 / 拒绝；高风险 Skill、远程安装、跨设备接管还没有统一审批引擎。
- 多设备控制当前以设备在线状态、设备绑定、项目线程绑定和 runtime 配置为准，尚未形成租约、抢占、并发冲突仲裁的完整生产级控制面。

## 2. 权限模型

### 2.1 角色

| 角色 | 当前含义 | 当前边界 |
| --- | --- | --- |
| `highest_admin` | 最高管理员，默认账号 `krisolo` | 全局可见；可管理账号、授权、AI 账号、Telegram、运维入口和所有活跃会话 |
| `admin` | 管理员 / 可信协作者 | 可见更多“我的”入口，但当前不是全局授权管理员；不能访问 `/api/v1/admin/access` |
| `member` | 子账号 / 普通成员 | 只看被授权设备、项目和 Skill；`我的` 入口限制为个人安全、设置、技能、关于 |

### 2.2 权限点

| 权限 | 作用对象 | 当前作用 |
| --- | --- | --- |
| `device.view` | 设备 | 查看设备；可带来该设备关联项目的只读可见性 |
| `device.manage` | 设备 | 预留给设备管理动作，当前不是主要前台能力 |
| `project.view` | 项目 / 线程 / 群聊 | 查看项目详情、会话列表、线程状态和项目投影 |
| `thread.chat` | 项目 / 线程 / 群聊 | 向普通项目或线程发送消息并创建 `conversation_reply` |
| `master_agent.ask` | 项目 / 主 Agent | 向主 Agent 提问或让主 Agent 生成推荐 / 任务 |
| `master_agent.takeover` | 项目 / 线程 | 允许主 Agent 接管或代表用户推动线程执行 |
| `computer.control` | 设备 / 项目 | 允许 browser/desktop 控制类任务进入执行链 |
| `skill.view` | Skill | 查看已授权 Skill |
| `skill.use` | Skill | 把 Skill 作为可用能力放入授权上下文或调用语句 |
| `skill.manage` | Skill | 预留给细粒度 Skill 管理；当前远程安装 / 更新仍由 `highest_admin` 入口硬限制 |
| `account.manage` | 账号 | 预留；当前账号授权管理仍以 `highest_admin` 角色硬限制为准 |
| `audit.view` | 审计 | 预留；当前权限审计查询入口仍以 `highest_admin` 硬限制为准 |

### 2.3 继承与显式授权

- `highest_admin` 绕过设备、项目和 Skill 授权检查。
- 非最高管理员如果拥有某台设备或被授予 `device.view`，可以只读看到该设备关联的项目。
- `device.view` 不会自动放大为 `thread.chat / master_agent.ask / master_agent.takeover / computer.control / skill.use`。
- 聊天、主 Agent 接管、电脑控制和 Skill 使用必须来自项目授权、设备授权或 Skill 授权中的显式权限。
- Skill 授权可带 `deviceId / projectId` scope；同名 Skill 会聚合进 `skillCatalog`，但实际可见 / 可用仍要按设备和项目 scope 判断。
- 过期授权通过 `expiresAt` 失效；当前应在回归中覆盖过期授权不再生效。

### 2.4 内置模板

| 模板 | 设备权限 | 项目权限 | Skill 权限 | 适用场景 |
| --- | --- | --- | --- | --- |
| 只读观察员 | `device.view` | `project.view` | `skill.view` | 只看设备、项目和 Skill，不允许聊天或执行 |
| 项目开发者 | `device.view` | `project.view / thread.chat / master_agent.ask` | `skill.view / skill.use` | 参与项目开发，可问主 Agent 和调用已分配 Skill |
| 设备操作者 | `device.view / computer.control` | `project.view / thread.chat / master_agent.ask / master_agent.takeover / computer.control` | `skill.view / skill.use` | 可信协作者，可触发接管和电脑控制 |

## 3. 控制链路权限边界

### 3.1 主 Agent 单聊

- 入口：`POST /api/v1/projects/master-agent/messages`。
- 权限：当前需要 `master_agent.ask`；最高管理员全局通过。
- 执行链：写入消息后创建 `MasterAgentTask`，优先走 `Master Codex Node`，设备离线或立即失败时可退到已配置 API / 阿里备用链。
- 授权快照：任务保存 `authorizedDeviceIds / authorizedProjectIds / authorizedSkillIds / requiredPermissions`，用于执行器和后续审计判断。

### 3.2 普通线程单聊

- 入口：`POST /api/v1/projects/[projectId]/messages`。
- 权限：普通项目需要 `thread.chat`；只读 `project.view` 不能发送消息。
- 执行链：创建 `conversation_reply`，由绑定设备 `local-agent` 用 `codex exec resume <targetCodexThreadRef>` 回到真实 Codex 线程。
- 重要边界：如果线程缺失、设备离线、cwd 不匹配或历史只读线程上下文未解除，应失败并给出明确原因，不应假成功。

### 3.3 群聊下发

- 入口：群聊消息进入主 Agent 推荐；用户确认后调用 dispatch plan confirm。
- 权限：需要项目聊天 / 主 Agent 推荐能力；最终下发目标必须是真实可执行线程成员。
- 当前审批：`approval_required` 群聊支持确认 / 拒绝，一次只保留一个待确认推荐，避免叠加。
- 回写：`dispatch_execution` 完成后线程原始结果回群，再追加主 Agent 汇总；重复完成应幂等。

### 3.4 Skill

- 采集：`local-agent` 扫描本机 `~/.codex/skills`，上报 `/api/v1/devices/[deviceId]/skills`。
- 展示：`GET /api/v1/devices/[deviceId]/skills` 和 Web / Android Skill 页按账号授权过滤。
- 使用：`skill.use` 决定 Skill 是否能进入当前账号的主 Agent 授权上下文或被用户复制调用。
- 已落地第一版：远程安装、远程更新、远程卸载、Git checkout 回滚和版本锁请求会被 local-agent 认领执行并同步最新清单。
- 未生产化：远程 Skill 执行、签名校验、沙箱隔离、撤销后本地禁用、来源信任和依赖安装策略尚未完成。

### 3.5 多设备与电脑控制

- 设备能力来自 heartbeat：Codex GUI / CLI、browserAutomation、computerUse 等。
- browser/desktop 控制任务要求 `computer.control`，并通过 `MasterAgentTask` 进入 `local-agent` 外部 runtime 桥。
- smoke runtime 当前能做最小真实动作和 artifact 回写，但还不是完整 Playwright / Computer Use 生产运行时。
- 同项目 GUI / CLI 并行写入已有冲突控制：默认阻断，用户可对异常项目选择本次 / 永久放行。

## 4. 回归矩阵

### 4.1 Web / API

| 场景 | 要测什么 | 命令 |
| --- | --- | --- |
| 基础构建 | Next.js 构建和 lint 无退化 | `npm run build && npm run lint` |
| 健康检查 | Web 服务可启动、健康探针正常 | `npm start` 后执行 `curl -sS http://127.0.0.1:3000/api/health` |
| 登录态 | 登录、session、restore、logout 链路 | `curl -sS -H 'Content-Type: application/json' -d '{"account":"krisolo","password":"<admin-password>","method":"password"}' http://127.0.0.1:3000/api/auth/login` |
| 会话治理 | 最高管理员可看全部会话，子账号只能看自己，会话 token 不泄露 | `curl -sS http://127.0.0.1:3000/api/v1/auth/sessions` |
| 授权台保护 | 未登录返回 `401`，非最高管理员返回 `403`，最高管理员可读脱敏数据 | `curl -i http://127.0.0.1:3000/api/v1/admin/access` |
| 授权动作 | `upsert_account / grant_device / grant_project / grant_skill / apply_template / revoke_grant` 都写入 `permissionAuditLogs` | 用最高管理员 Cookie 对 `/api/v1/admin/access` 发 JSON POST |
| 权限审计查询 | 最高管理员可按 action / actor / target / device / project / skill / cursor / limit 查询，普通账号 `403` | `npx tsx --test tests/audit-permission-logs-route.test.ts` |
| 权限审计风险 | 能识别短时间大量授权、Skill lifecycle 失败、过期授权仍存在、admin route 拒绝访问 | `npx tsx --test tests/audit-permission-logs-route.test.ts` |
| 账号裁剪 | 子账号只看到被授权设备 / 项目 / Skill | 用子账号 Cookie 分别请求 `/api/v1/devices`、`/api/v1/conversations`、`/api/v1/devices/mac-studio/skills` |
| 项目写权限 | 只有 `thread.chat` 可发普通线程消息，只读账号应 `403` | `curl -i -H 'Content-Type: application/json' -d '{"kind":"text","body":"权限回归"}' http://127.0.0.1:3000/api/v1/projects/<projectId>/messages` |
| 主 Agent 权限 | `master_agent.ask` 才能进入主 Agent 任务链，任务包含授权快照 | `curl -sS -H 'Content-Type: application/json' -d '{"kind":"text","body":"列出我可见的设备和 Skill"}' http://127.0.0.1:3000/api/v1/projects/master-agent/messages` |
| Skill 过滤 | Skill 列表按设备和账号授权过滤 | `curl -sS http://127.0.0.1:3000/api/v1/devices/mac-studio/skills` |
| Skill 治理请求 | 最高管理员可创建请求，设备可认领和回写 | `npx tsx --test tests/skill-lifecycle-route.test.ts` |
| browser/desktop fail closed | 未配置 runtime 时返回明确 disabled，不写假成功 | 关闭 `browserControl* / computerUse*` 后发控制类主 Agent 消息 |
| 群聊审批 | `approval_required` 只能有一条待确认推荐，确认 / 拒绝状态正确 | 用群聊项目消息接口触发 dispatch plan，再测 confirm / reject |

### 4.2 local-agent / 本机设备

| 场景 | 要测什么 | 命令 |
| --- | --- | --- |
| 健康探针 | `launchd` 常驻不被首次 heartbeat 阻塞 | `curl -sS http://127.0.0.1:4317/health` |
| Skill 扫描 | 本机 Skill 能递归扫描并返回 | `curl -sS http://127.0.0.1:4317/api/v1/skills` |
| Skill lifecycle | local-agent 能认领请求、执行版本锁/卸载等安全本机操作并同步清单 | `node --test tests/local-agent-skill-lifecycle-runner.test.mjs` |
| 心跳上报 | 设备、能力、Skill、thread-context 能上报 | `curl -sS -X POST http://127.0.0.1:4317/api/v1/heartbeat` |
| 任务认领 | `conversation_reply / dispatch_execution / browser_control / desktop_control` 能被认领或明确失败 | 触发对应 Web/API 消息后观察项目消息账本和 local-agent 日志 |
| Codex 线程恢复 | 有 `targetCodexThreadRef` 时走 `codex exec resume`，缺失时才退 `--ephemeral` | 发送普通线程消息并检查回写内容 |
| rollout 镜像 | Boss 用户消息先镜像进 Codex Desktop 同线程，重试不重复写入 | 对已绑定真实线程的项目发送消息后检查 Desktop 线程历史 |

### 4.3 Android

| 场景 | 要测什么 | 命令 |
| --- | --- | --- |
| 构建 | Debug APK 可构建并发布到 downloads | `npm run apk:debug` |
| Release | signed release APK 可构建 | `npm run apk:release` |
| 单元测试 | Android 本地测试串行通过，避免 Gradle 中间产物互踩 | `cd android && ./gradlew testDebugUnitTest` |
| 真机安装 | OPPO `PHZ110` 安装并可启动 | `adb -s U84XJRIB7D65ZH45 install -r android/app/build/outputs/apk/debug/app-debug.apk` |
| 角色入口 | `member / admin / highest_admin` 的“我的”入口差异正确 | 真机登录不同账号，检查 `用户与权限 / 技能 / 运维 / AI 账号 / Telegram` 可见性 |
| 权限管理页 | 最高管理员可创建子账号、套模板、撤销授权 | 真机打开 `我的 > 用户与权限` |
| Skill 页 | 子账号只看到授权 Skill，可复制调用语句 | 真机打开 `我的 > 技能` |
| 聊天等待态 | 主 Agent、普通线程、群聊下发都显示等待直到真实回写或超时 | 真机分别发送三类消息 |
| 控制结果卡 | browser/desktop 控制结果以目标 URL / 应用名卡片展示 | 真机向主 Agent 发送控制类请求 |

### 4.4 真机 / 多设备控制

| 场景 | 要测什么 | 命令 |
| --- | --- | --- |
| ADB 目标 | 默认只使用 OPPO `PHZ110`，不自动回退旧设备 | `adb devices` |
| 无线调试 | 同一局域网 + USB 初次启用后可切无线 | `adb -s U84XJRIB7D65ZH45 tcpip 5555 && adb connect <phone-ip>:5555` |
| 设备在线 | Boss 设备页显示 `mac-studio` 在线及 browser/computer 能力 | `curl -sS http://127.0.0.1:4317/health && curl -sS -X POST http://127.0.0.1:4317/api/v1/heartbeat` |
| GUI / CLI 冲突 | 同项目双执行模式默认阻断，允许本次 / 永久放行生效 | 在设备详情或项目冲突提示中切换策略后再次派发 |
| 设备离线 | 主 Agent / 项目确认接口返回明确离线原因，不假成功 | 停掉 local-agent 后发送线程或控制任务 |

### 4.5 服务器部署

| 场景 | 要测什么 | 命令 |
| --- | --- | --- |
| SSH 健康 | 固定服务器 `106.53.170.158` 可连 | `"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" health` |
| Web 服务 | `boss-web.service` 运行且本机 API 正常 | `"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status boss-web --no-pager && curl -sS http://127.0.0.1:3000/api/health"` |
| Caddy / HTTPS | Caddy 运行，域名跳转正常 | `"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status caddy --no-pager && curl -I --resolve boss.hyzq.net:443:127.0.0.1 https://boss.hyzq.net"` |
| 外网域名 | 当前网络能访问公网 HTTPS API | `curl -I https://boss.hyzq.net && curl -sS https://boss.hyzq.net/api/health` |
| 状态文件 | 部署不覆盖服务器 `data/boss-state.json` | 部署前后在服务器检查 `/opt/boss/data/boss-state.json` mtime 和关键账号数据 |
| 邮件端口 | Postfix / Dovecot 在线 | `"$HOME/.codex/skills/boss-server-debug/scripts/server_ssh.sh" exec "systemctl status postfix --no-pager && systemctl status dovecot --no-pager"` |

## 5. 剩余缺口

### 5.1 需要生产化的权限能力

- Skill 远程安装 / 更新 / 卸载：第一版设备端安装器和版本锁已落地；仍需要签名校验、来源信任、安装审计增强和失败自动回滚。
- Skill 远程执行：需要明确输入输出协议、沙箱边界、资源限制、敏感权限提示和 per-run 审计。
- 统一审批流：高风险 Skill、电脑控制、跨设备接管、生产部署、账号和存储配置变更应进入同一审批模型，而不是分散在群聊确认里。
- 多级组织：当前只有角色 + 单账号授权；还没有组织、团队、项目组、继承授权、批量授权、离职回收和委派管理员。
- 审计告警：授权日志已有账本，但缺少审计检索、异常检测、告警通道、不可篡改归档和审计报表。
- 风险分级执行：`requiresConfirmation / riskLevel` 已开始进入任务元数据，但还没有统一策略中心约束哪些风险必须二次确认。

### 5.2 需要生产化的运行能力

- 数据库：当前仍是 `data/boss-state.json` 文件存储；RBAC、审计、会话和任务队列生产化前需要迁移到数据库并补索引和事务边界。
- 会话安全：需要独立刷新令牌、完整吊销审计、CSRF 防护、设备绑定策略、登录风险检测和异常会话告警。
- 多设备控制租约：需要 device lease、抢占、超时释放、只读观察、独占输入和并发写入审计。
- 真实 Browser / Computer Use runtime：当前 smoke runtime 只能作为过渡层；生产需要接入真实浏览器自动化和桌面控制执行器。
- 服务器出网：公网服务器当前对 `api.openai.com` 直接出网仍未完全打通，OpenAI API 线上探针和调用依赖网络恢复。
- 生产邮件验收：Postfix / Dovecot 已部署，但 SPF、DKIM、DMARC、MX、退信策略和真实外部收件链路仍需最终验收。