docs(structure): 梳理清减 docs/ 结构并兑现 AGENTS.md 引用承诺

docs/agents/browser-validation.md

@@ -0,0 +1,172 @@
+# Browser Validation Protocol（浏览器验证协议）
+
+> 由 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，**任何 AI Agent 在执行浏览器自动化任务前必须完整遵循**。
+>
+> **协议版本**：v1.0 ｜ **生效范围**：所有面向本仓库的 AI Agent 协作场景
+>
+> **关联工具**：`chrome-devtools` MCP、`claude-in-chrome` MCP、`playwright` MCP
+
+[TOC]
+
+---
+
+## 1. 协议目的
+
+为 AI Agent 在浏览器自动化场景下提供**统一、可审计、不可绕过**的认证态使用规范，解决以下问题：
+
+- AI Agent 不应也不可代用户决策"我是谁"——所有登录态归属问题必须由用户本人主导
+- 浏览器自动化能力一旦失控，可能在用户毫不知情时产生不可撤销的副作用（消息发送、订单提交、权限变更等）
+- OAuth / SSO 同意屏在自动化上下文中存在被绕过的潜在风险，违反平台 ToS 与基本伦理
+
+本协议通过"原则—红线—操作流程—验证"四层结构，将上述问题约束在工程可控范围内。
+
+---
+
+## 2. 核心原则
+
+| 原则                       | 具体含义                                                                                              |
+| -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **登录态归属于用户**       | Agent 不得自行完成、绕过或模拟任何 OAuth / SSO 认证流程；所有登录态来源于用户已认证的 Chrome 主 profile |
+| **真实主 profile 优先**    | 浏览器自动化默认接入用户日常使用的 Chrome 主 profile，复用其 Cookie / Session / SSO 状态              |
+| **可审计、可回放**         | 浏览器路径关键操作（点击、表单填写、跳转）应留下可被 GIF 回放或日志追溯的痕迹                         |
+| **最小副作用**             | 优先以只读方式（查看、提取、断言）完成任务；写操作（提交、发送）需在协议第 5 节框架下显式确认         |
+
+---
+
+## 3. 安全红线
+
+> 以下条款**不可协商**，违反任一条款即视为协议违反。
+
+1. **禁止跳转 Google 同意屏**：在 Sandbox / 自动化浏览器环境内**严禁**触发 Google OAuth 同意屏跳转。同意屏只能在用户主 profile 的真实浏览会话中由用户本人完成。
+2. **禁止模拟身份**：禁止以模拟用户身份、虚构 Cookie、第三方账号或测试账号替代真实登录态完成任务。
+3. **禁止凭证泄露**：禁止要求用户在 chat 中粘贴密码、Cookie、Session Token、二维码扫描结果或任何形式的验证码（含 6 位数字、短信、TOTP）。
+4. **禁止跨账号操作**：在多用户环境下，Agent 不得在未经显式确认的情况下切换 profile 或账号身份。
+5. **禁止规避 ToS**：不得通过 Headless 模式、UA 伪装、Captcha 自动求解等方式规避目标站点的服务条款。
+6. **禁止下载执行**：浏览器路径触发的任何文件下载需在主对话中显式确认；下载文件不得自动执行或注入到项目目录。
+
+---
+
+## 4. 连通性自检（Connectivity Probe）
+
+执行浏览器自动化任务前，Agent **必须**完成以下自检序列：
+
+| 步骤                  | 操作                                                              | 通过判据                                                  |
+| --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| 4.1 工具可用性        | 列出当前会话可用的 MCP 工具                                       | 至少存在 `chrome-devtools` / `claude-in-chrome` 之一      |
+| 4.2 主 profile 加载   | 通过工具调用获取当前 Tab 列表或 Page 列表                         | 返回非空，且 Tab 标题来自用户真实浏览历史而非空白会话     |
+| 4.3 目标域名可达      | 通过 `navigate_page` 或 `browser_navigate` 访问目标域名首页       | HTTP 200 / 已登录态正常加载                               |
+| 4.4 登录态识别        | 在目标域名首页定位"已登录"标识（头像、用户名、退出按钮）          | 能在 Snapshot / AOM 中找到一致标识                        |
+| 4.5 异常路径分类      | 若 4.4 失败，按"未登录 vs 会话过期 vs 拒绝服务"分类，**不**自动重登 | 输出明确分类，转入第 5 节的用户接力流程                   |
+
+> **失败处置**：自检任一步骤失败，Agent **必须**停止任务、向用户输出诊断结论，**不得**尝试 OAuth / 凭证补救。
+
+---
+
+## 5. 凭证管理（Credential Lifecycle）
+
+### 5.1 发现路径
+
+凭证通过以下路径**被动**发现，Agent **不**主动读取、导出或日志化：
+
+- 浏览器 Cookie / LocalStorage（仅由浏览器引擎内部使用）
+- 浏览器扩展（如 Claude in Chrome）持有的 Session
+- 用户在 chat 中以"我刚登录了 X"形式给出的事实陈述（非凭证本身）
+
+### 5.2 过期检测信号
+
+| 信号                                     | 处置                                            |
+| ---------------------------------------- | ----------------------------------------------- |
+| HTTP 401 / 403                           | 转 5.3 接力流程                                 |
+| 重定向到登录页（含 `/login`、`/signin`） | 转 5.3 接力流程                                 |
+| 同意屏触发（OAuth scope 变更）           | **立即停止**，由用户在主 profile 完成同意       |
+| Captcha 出现                             | **立即停止**，输出"需用户介入"                  |
+
+### 5.3 用户接力流程（Re-authentication Handoff）
+
+```
+1. Agent 检测到登录态失效
+2. Agent 向用户输出：（a）失效域名 （b）建议在用户主 profile 完成登录的指引
+3. Agent 暂停浏览器任务，**不**触发任何登录流程
+4. 用户在真实浏览器完成登录后，回到 chat 通知 Agent
+5. Agent 重新执行第 4 节连通性自检
+6. 自检通过后恢复任务
+```
+
+### 5.4 凭证刷新约束
+
+- Agent **不**调用任何 refresh_token / device_code 接口
+- Agent **不**触发邮箱链接、短信验证码、TOTP 输入
+- 凭证刷新由用户在原始登录路径自主完成
+
+---
+
+## 6. E2E 集成（End-to-End Integration）
+
+### 6.1 与项目 OAuth 模块的边界
+
+本项目内置 GitHub Device Flow 与 Google OAuth 模块（`src/coding/proxy/auth/`）。浏览器协议与之的边界如下：
+
+- **项目 OAuth 模块**：服务端运行时凭证管理，由 `coding-proxy auth login/reauth` CLI 触发，目标是给 **proxy 自身**获取上游 API 凭证
+- **本协议**：客户端浏览器自动化场景，目标是让 **Agent 协助用户**完成日常任务（如查文档、填表单）
+
+二者**互不调用**：Agent 不调用 `coding-proxy auth` 替用户完成项目 OAuth；项目 OAuth 流程也不依赖本协议第 4 节自检。
+
+### 6.2 与 CLI 命令的协同
+
+| 场景                            | 由谁触发                  |
+| ------------------------------- | ------------------------- |
+| 给 proxy 注入 GitHub PAT        | 用户运行 `auth login`     |
+| 给 proxy 注入 Google OAuth      | 用户运行 `auth login`     |
+| 凭证过期重认证                  | 用户运行 `auth reauth`    |
+| 浏览器查看 GitHub Token 状态    | Agent 通过本协议浏览器访问 |
+
+### 6.3 测试用例的浏览器隔离
+
+- 单元测试（`tests/unit/`）**不**触发任何浏览器路径
+- 集成测试（`tests/integration/`）**不**触发任何浏览器路径
+- 浏览器路径仅在交互式 Agent 会话中触发，不进入 CI 自动化测试链路
+
+---
+
+## 7. 实机回归（Real-Device Regression）
+
+### 7.1 提交前的浏览器路径自检清单
+
+涉及浏览器路径的改动在提交前需手工核验：
+
+- [ ] 第 4 节连通性自检在用户主 profile 通过
+- [ ] 第 3 节安全红线未被触碰（特别是同意屏、密码粘贴）
+- [ ] 浏览器路径的关键操作有 GIF / Snapshot 留痕
+- [ ] 失败路径输出明确的用户接力指引
+
+### 7.2 与 CI 的边界
+
+CI 流水线（详见 [ops/ci-cd.md](../ops/ci-cd.md)）**不**触发浏览器自动化路径。所有浏览器侧验证均在本地实机完成。
+
+### 7.3 回归失败上报
+
+若实机回归失败：
+
+1. 在 [docs/issue.md](../issue.md) 记录现象、根因、防范
+2. 若涉及协议本身缺陷，提交 PR 修订本文件并同步 [AGENTS.md](../../AGENTS.md) 锚点
+3. 不通过的 Agent 行为应在 [knowledge-map.md](./knowledge-map.md) 标注为已知问题
+
+---
+
+## 8. 引用规范
+
+- 本协议章节可被 [AGENTS.md](../../AGENTS.md) / [CLAUDE.md](../../CLAUDE.md) 通过标题锚点形式引用
+- 修订本协议**必须**在 [docs/issue.md](../issue.md) 留存背景与决策记录
+- 协议条款发生变更时，需同步检查 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 的兜底原则与本协议是否一致
+
+---
+
+## 附录 A：术语对照
+
+| 术语                | 说明                                                              |
+| ------------------- | ----------------------------------------------------------------- |
+| 主 profile          | 用户日常使用的 Chrome / Edge 浏览器档案，含真实登录态             |
+| Sandbox 浏览器      | 自动化工具启动的临时/隔离浏览器，无真实用户态                     |
+| 同意屏（Consent）   | OAuth 流程中用户授予权限范围的页面                                |
+| 接力流程            | Agent 停止 → 用户介入完成 → Agent 恢复 的三段式协作               |
+| 实机回归            | 在用户真实终端（非 CI）完成的端到端验证                           |

docs/agents/knowledge-map.md

@@ -1,3 +1,95 @@
 # Knowledge Map（知识索引）
 
-(WIP)
+> 项目所有文档的统一入口与权威索引。由 [AGENTS.md §Knowledge Map](../../AGENTS.md) 锚定，文档目录变更时**必须**即时同步更新本文件。
+>
+> **使用方式**：按"受众 × 目的"二维定位所需文档；不确定起点时，从「入口导航」开始。
+
+[TOC]
+
+---
+
+## 1. 入口导航
+
+| 文档                                          | 角色                                            | 受众            |
+| --------------------------------------------- | ----------------------------------------------- | --------------- |
+| [README.md](../../README.md)                  | 项目首页（英文版门面）                          | 公开访客        |
+| [docs/zh-CN/README.md](../zh-CN/README.md)    | 项目首页中文镜像（与英文版功能对等）            | 中文公开访客    |
+| [docs/user-guide.md](../user-guide.md)        | 用户操作上位导航 + 配置概览速查                 | 终端用户        |
+| [docs/framework.md](../framework.md)          | 架构枢纽（项目动机、设计目标、模块清单）        | 架构师/贡献者   |
+
+---
+
+## 2. 用户向（[docs/guide/](../guide/)）
+
+> 面向最终用户的操作手册，按"安装 → 配置 → 运行 → 观测 → 排障"线性铺陈。
+
+| 文档                                              | 主旨                                                |
+| ------------------------------------------------- | --------------------------------------------------- |
+| [guide/quickstart.md](../guide/quickstart.md)     | 环境要求、安装、最小配置、启动、Claude Code 集成    |
+| [guide/vendors.md](../guide/vendors.md)           | 全部 9 种供应商配置详情、模型映射、定价表           |
+| [guide/cli-reference.md](../guide/cli-reference.md) | start / status / usage / reset / auth 全部命令      |
+| [guide/api-reference.md](../guide/api-reference.md) | /v1/messages、health、status、reset、dashboard 等   |
+| [guide/dashboard.md](../guide/dashboard.md)       | Web 可视化看板功能与交互                            |
+| [guide/monitoring.md](../guide/monitoring.md)     | 日志、用量统计、性能调优、常见场景、故障排查        |
+
+---
+
+## 3. 架构向（[docs/arch/](../arch/)）
+
+> 面向贡献者与维护者的架构与实现细节，从 [framework.md](../framework.md) 正交分解而来。
+
+| 文档                                                  | 主旨                                                  |
+| ----------------------------------------------------- | ----------------------------------------------------- |
+| [arch/config-reference.md](../arch/config-reference.md) | 配置参数权威定义（Single Source of Truth）            |
+| [arch/design-patterns.md](../arch/design-patterns.md) | 13 种设计模式详解（熔断器、状态机、Composite 等）     |
+| [arch/routing.md](../arch/routing.md)                 | 路由引擎 12 个子模块职责                              |
+| [arch/vendors.md](../arch/vendors.md)                 | Vendor 类层次结构与 9 种实现                          |
+| [arch/convert.md](../arch/convert.md)                 | Anthropic ↔ Gemini ↔ OpenAI 三向格式转换              |
+| [arch/testing.md](../arch/testing.md)                 | 测试覆盖矩阵与工具链                                  |
+
+---
+
+## 4. 运维向（[docs/ops/](../ops/)）
+
+> 面向运维与发布工程的流程文档。
+
+| 文档                                | 主旨                                              |
+| ----------------------------------- | ------------------------------------------------- |
+| [ops/ci-cd.md](../ops/ci-cd.md)     | 发布流程、热修复、回滚、CI/CD 故障排查            |
+
+---
+
+## 5. Agent 协作（[docs/agents/](./)）
+
+> AGENTS.md 工程行为准则的卫星文件，定义 AI Agent 协作过程中的规范与协议。
+
+| 文档                                                            | 主旨                                          |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| [agents/knowledge-map.md](./knowledge-map.md)                   | 本文件——项目文档统一索引                      |
+| [agents/reference-specifications.md](./reference-specifications.md) | IEEE 文献引用格式模板与实践指南               |
+| [agents/browser-validation.md](./browser-validation.md)         | 浏览器验证协议（连通性自检、凭证管理、E2E）   |
+
+---
+
+## 6. 问题档案
+
+| 文档                              | 主旨                                                  |
+| --------------------------------- | ----------------------------------------------------- |
+| [docs/issue.md](../issue.md)      | 已处理 Issue 摘要档案（表因、根因、防范）              |
+
+---
+
+## 7. 工程规范（顶层）
+
+| 文档                              | 主旨                                                  |
+| --------------------------------- | ----------------------------------------------------- |
+| [AGENTS.md](../../AGENTS.md)      | 工程行为准则与 AI Agent 协作协议（与 CLAUDE.md 同源） |
+| [CHANGELOG.md](../../CHANGELOG.md)| 版本历史与变更日志                                    |
+
+---
+
+## 维护约束
+
+1. **同步原则**：新增/删除/重命名 `docs/` 下任意 .md 文件时，**必须**同步本索引。
+2. **路径基准**：本文件位于 `docs/agents/`，所有相对路径以此为基准（向上一级 `../` 访问 `docs/`，向上两级 `../../` 访问仓库根）。
+3. **链接验证**：维护者修改本文件后应通过 grep 自检：所有 `[...](path)` 中的 `path` 文件存在。

docs/arch/vendors.md

@@ -1,7 +1,7 @@
 # 供应商模块（vendors/）
 
 > 路径约定：相对于 `src/coding/proxy/`
-> 定位：从 [framework.md](./framework.md) 提取，详述供应商分类体系与各供应商实现。
+> 定位：从 [framework.md](../framework.md) 提取，详述供应商分类体系与各供应商实现。
 
 [TOC]