boss/docs/architecture/rbac_skill_regression_matrix_cn.md

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、退信策略和真实外部收件链路仍需最终验收。