AI Agent 接入指南

AI Agent 可以完成 IWish Auth 接入代码，但必须把公开文档和机器契约作为唯一协议来源，并由人工复核身份、权限、secrets 和业务数据授权。

1. 必须读取的输入

按顺序读取：

1. /llms.txt：边界、入口和文件索引。
2. /llms-full.txt：完整接入规范。
3. /openapi.json：HTTP 契约。
4. /auth-manifest.schema.json：Manifest 契约。
5. 当前技术栈框架指南。
6. 当前 App 的代码、依赖、路由和权限盘点。

如果文档与代码导出冲突，停止修改并报告冲突，不要猜测 API。

2. Agent 执行顺序

1. 识别技术栈和服务端入口。
2. 搜索本地登录、密码、session、角色和权限判断。
3. 输出旧角色到新 permission/role 映射，等待或记录人工确认。
4. 创建 auth.manifest.json 并通过 schema/CLI 校验。
5. 安装官方 SDK。
6. 接入服务端 login、callback、logout 和 App session。
7. 用 requirePermission 替换服务端角色判断。
8. 仅在业务需要时使用 clientAssignments。
9. 移除本地身份和统一角色写入口。
10. 添加 401、403、跨 App、登出和关键业务测试。
11. 运行 typecheck、test、build、lint 和 Manifest validate。
12. 输出变更、验证证据、迁移风险和人工操作项。

3. 不可突破的边界

• 不直接接飞书 OAuth 或通讯录。
• 不直接使用 Supabase Auth SDK 完成业务 App 登录。
• 不读取或写入 IWish Auth 数据库。
• 不把 client secret、token、密码写入代码、日志或回复。
• 不创建 Auth Proxy、长期双登录或降级身份 Header。
• 不自行解析 opaque App session。
• 不用 clientAssignments 代替 App permission 或业务数据授权。
• 不根据邮箱自动合并飞书员工与外部账号。
• 不静默扩大 callback allowlist、CORS 或 cookie Domain。

4. 期望交付格式

Agent 最终输出：

变更文件：
- ...

权限映射：
- 旧角色/判断 -> permission -> role

验证结果：
- manifest validate
- test
- typecheck
- build
- lint

人工操作：
- 创建/更新 OAuth client
- 同步 Manifest
- 配置服务端 secrets
- 分配试点角色

剩余风险：
- ...

5. Agent 自检问题

提交前必须回答：

1. 所有身份恢复是否都来自 IWish Auth session introspection？
2. 是否有任何浏览器代码可以读取 client secret 或 App session？
3. 每个高风险服务端动作是否有 permission 检查？
4. 是否错误删除了业务 App 自身的数据授权？
5. 是否把项目分工当成权限？
6. 是否保留了旧密码、角色写入口或双登录？
7. 是否验证了跨 App session/permission 被拒绝？
8. 所有示例 API 是否存在于 OpenAPI 或 SDK 导出？

6. 可验证示例

仓库中的 examples/ai-agent-app 是按本指南生成的最小 Express-like 接入成果。它只使用官方 SDK、Manifest 和 App session context，并由 verify:phase-7 自动检查。该示例不是业务模板，真实迁移仍需盘点本地数据授权和回滚边界。