AgoraIO-Extensions / AgoraIO-Extensions/agent-infra
feat(connection-web): publish AI-readable Codex MCP installation guide
- Vorherrschende Sprache
- TypeScript
- Sterne
- 0
- Forks
- 0
- Ø Merge
- 8 Std. 51 Min.
- Gemergte PRs (30 T.)
- 99
Beschreibung
## Problem
Connection 的公开网站入口 `https://agent-connector.la3.agoralab.co/connection` 当前直接进入管理控制台,未向 AI 客户端提供公开、无凭证的产品说明和 Codex MCP 安装步骤。用户把该 URL 发给 Codex 并要求安装时,Codex 无法从页面本身稳定获得 MCP endpoint、安装命令、OAuth 登录步骤和安全边界。
`llms.txt` 是面向 LLM 的约定式 Markdown 入口,但不是 Codex 已承诺的自动安装协议。实现必须同时让 `/connection` 页面本身可读,并暴露 `/llms.txt`;不能把“可发现安装说明”描述为静默安装或自动信任。
## Scope
- 在 Connection Web 增加无需登录的 `/connection` 安装说明页,面向用户简要说明 Connection,并给出当前公开部署的 Codex CLI 安装与 OAuth 登录步骤。
- 在网站根路径发布符合 llms.txt 约定的 `/llms.txt`,包含 Connection 用途、公开 MCP endpoint、Codex 安装命令、OAuth 登录步骤、授权前置条件和相关公开页面链接。
- 从 HTML head 显式链接 `/llms.txt`,使读取 `/connection` 的客户端可发现机器可读说明。
- 安装说明只能包含公开 URL 和无密钥命令;不得包含 PAT、LDAP 密码、Provider Credential、内部地址或用户身份字段。
- 保持 `/connection/login`、管理控制台、MCP OAuth、Grant 和 Provider 授权流程不变。安装仍需用户明确执行,认证和授权仍由 Connection 服务端完成。
- 本票不实现 Codex 客户端改动、浏览器静默安装、通用网站自动发现协议、PAT 自动配置、部署发布或生产环境变更。
## Acceptance criteria
- [ ] **AC-1:** 未登录访问 `/connection` 可直接看到 Connection 的 Codex 安装步骤,至少包含 `codex mcp add connection --url https://agent-connector.la3.agoralab.co/mcp` 和 `codex mcp login connection --scopes mcp --oauth-client-registration dcr`,并清楚说明安装不会授予 Provider 权限。
- [ ] **AC-2:** `GET /llms.txt` 返回 UTF-8 `text/plain` 内容,包含同一公开 MCP endpoint、相同命令、控制台入口和安全边界,且不经过 SPA fallback 或 Connection API proxy。
- [ ] **AC-3:** Connection Web HTML head 通过标准 link 元数据指向 `/llms.txt`;页面与 llms.txt 不承诺 Codex 自动发现、静默安装或绕过确认。
- [ ] **AC-4:** `/connection/login` 和现有已认证管理路由行为不变;OAuth、Grant、Connection 和 Provider Credential 的权威边界不变。
- [ ] **AC-5:** focused Web/static routing tests、仓库根完整验证序列和 `git diff --check` 通过;若基线失败,单独记录且不得包装成变更已通过。
## HLD / PRD mapping
- `PRD-connection-M1.md` 6.3:Direct MCP Client 只配置 Connection endpoint,支持 OAuth 的客户端由 Connection 提供浏览器登录。
- `HLD-connection-M1.md` 22.4:Direct Auth API 和 `/connection/login` 的身份边界保持不变。
- `HLD-connection-M1.md` 22.5:Connection Web 持有 presentation;新增内容不进入领域规则或 API 授权判断。
## Validation
- 构建 Connection Web,检查产物中的 `llms.txt` 和 HTML link。
- 验证 Nginx 对 `/llms.txt` 使用静态 `text/plain` 响应,且 `/connection`、`/connection/login` 路由符合预期。
- 运行 Connection Web focused tests、scaffold/HLD boundary tests及 `AGENTS.md` 完整验证序列。
Beitragsleitfaden
Für dieses Repository ist kein Beitragsleitfaden indexiert
Bewertung
Dieses Issue wurde noch nicht bewertet.