WorthPath/docs/update-oauth-permissions-2026-10-05.md

OAuth 三档权限选择与权限缓存提示词

完成时间：2026-10-05 21:34（UTC+8）。

OAuth 授权页始终提供只读查询、草稿修改和直接写入三个等级，默认只读。即使客户端只申请 read，普通用户也可以在网页主动选择 draft 或 write，服务端按明确确认的范围发行令牌，并在 token.scope 返回实际范围。选择直接写入后显示即时写入说明，不自动替用户选择或确认。

隐藏读写仍要求客户端申请对应范围并由用户勾选。只读系统用户能看到三档说明，但草稿和直接写入不可选；服务端也拒绝授予写入。刷新令牌仍不能自行扩大范围，授权有效期和撤销规则保留。

授权预览新增 availableScopes 和 canWrite，scopes 保留客户端原申请，页面区分“客户端申请权限”与“最终权限代码”。三档权限互斥，draft/write 不同时授予。

提示词

页面的“Agent 使用教程”和“Codex 配置提示词”现在明确：

• 连接时发现真实工具，调用一次 connection_info 核对当前资源、权限、scopes 与隐藏读写，并在本连接中缓存。
• 权限可能在网页更改，旧申请或聊天中的权限不代表当前授权。
• 不需要每次查询或写入前检查；重新连接/授权、用户告知变更、权限错误或缓存不足以判断可执行范围时，再检查一次并更新缓存。
• 初次配置仍核对本次预期范围；不匹配时报告差异，不擅自申请更高权限或绕过真实 pending 的人工确认。
• 缓存是助手的查询策略；服务端每次请求仍检查实际授权、有效期、撤销状态和用户权限。

验证

7 项隔离 MySQL/HTTP/官方 SDK 集成测试通过，包括客户端仅申请 read 时分别确认三档权限、令牌 scope 正确、默认只读、只读用户拒绝写入、隐藏权限约束、原有 OAuth/刷新与业务回归。前后端生产构建通过。

独立临时数据库网页验收显示三个可选按钮，选择直接写入后最终授权与说明同步变化。未点击真实用户 OAuth 确认，也未改变线上连接或账目。清理测试库、服务和一次性脚本；保留可重跑回归测试。截图保存在仓库外，docs 无图片。本次没有数据库结构变更。

本地提交，不推送、不部署。已有 compose.yaml 和 docker.md 改动保留。