AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(connection-web): publish AI-readable Codex MCP installation guide

Abierto
#452 3 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement ready-for-agent
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

## 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` 完整验证序列。

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.