Agent 如何安全地操作小组、成员与资源
Agent 只看见 MCP 工具；OAuth 负责把登录账号的权限委托给 Agent；领域服务仍然是唯一的数据与权限入口。REST/OpenAPI 保留给非 Agent 开发与契约检查。
https://growthengineer.space/mcp一张图看懂整体架构
- 读取
/agent.md - 连接 Streamable HTTP
- 自动发现 OAuth
- 通过 tools/list 感知能力
mcp-handler无状态传输- JWT 本地验签与 scope 检查
- Zod 工具输入校验
- 危险工具强制
confirm=true
- groups.ts 权限真源
- Neon Postgres
- pending / active / rejected 状态
- Cloudflare 邮件邀请与审核通知
/mcp、OAuth discovery、授权确认页面用户连接 Agent 的完整流程
/agent 页面中的提示词。/mcp，收到 401 与 protected-resource 地址。工具、数据范围与权限
| 工具域 | 代表工具 | Scope | 额外规则 |
|---|---|---|---|
| 小组 | groups_list/create/update/delete | groups:read / write | 删除需二次确认并输入准确组名；普通账号只看已正式加入的小组 |
| 成员 | group_members_search/update/remove | groups:read / write | 只返回 active 成员；表单挂在 membership 下，可持续编辑 |
| 邀请与审核 | group_invites_create、group_join、group_applications_list/review | groups:read / write | 邀请默认永久；完整表单先进入 pending，审核通过后才获得目录访问权 |
| 内容查询 | resources_list/get/mine、cases_list/get/mine | groups:read | 公开内容遵守积分访问；mine 返回本人全部审核状态与可编辑字段 |
| 内容维护 | resources_create/update/delete、cases_create/update/delete | groups:write | 只可维护本人投稿；已发布内容的修改先进入待审核状态；删除需要二次确认 |
| 后台 | admin_groups_list/get/delete | admin:read / write | 还必须是当前后台管理员；scope 不能提权 |
Agent 可以直接问“我想找西语外链，我可以找谁？”，然后调用 group_members_search，只在该账号可见的小组成员表单里匹配并给出依据。
为什么 MCP 不会成为性能瓶颈
无状态 HTTP
只启用 Streamable HTTP，关闭旧 SSE；无需 Redis 会话，可水平扩容。
本地 JWT 验签
每个 MCP 请求不查 token 表，避免额外数据库 RTT；refresh 才查库。
有界返回
小组/成员最多 100 条，跨组成员检索、资源和案例最多 50 条；管理员通知收件人也有上限。
直达领域服务
MCP handler 不再 HTTP 回调自己的 REST API，减少序列化和网络开销。
索引化成员搜索
active 成员使用 PostgreSQL trigram GIN 索引；跨组可见性通过单条 EXISTS 查询完成，避免先扫小组再逐组查询。
异步邮件边界
加入申请先快速响应，审核邮件通过响应后的任务发送；单次 MCP Function 最长 30 秒，错误不泄露内部堆栈。
OpenAPI 如何随 REST 接口自动更新
- 运行时校验请求
- 成员表单与 CRUD 输入真源
- method / path / operationId
- scope / body / query
z.toJSONSchema()
/openapi.json- 运行时生成 OpenAPI 3.1
- 无需手写重复 schema
- 新增 route 未登记会测试失败
openapi:check 会比对所有 api/v1/**/route.ts，防止文档静默过期。RESTful 跟 OpenAPI 有何区别？
一种 API 设计风格
它规定运行时如何把业务表达成资源与 HTTP 语义：例如 GET /groups 查询、PATCH /groups/{id} 修改、无状态请求、正确状态码。
一份机器可读的接口合同
它描述一个 HTTP API 有哪些 path、method、参数、数据结构、认证方式和响应，可用于文档、SDK、Mock 与契约测试。
关系：RESTful 是“接口怎么设计和运行”，OpenAPI 是“怎么准确描述这套接口”。REST API 可以没有 OpenAPI；OpenAPI 也能描述不太 RESTful 的 RPC 风格 HTTP 接口。这里 Agent 使用 MCP，普通开发/内部集成使用 REST，OpenAPI 自动描述 REST。