From 2cb1b43cab901c6a1bf204ae98ba62b98a917273 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Sun, 17 May 2026 22:34:43 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(structure):=20=E6=A2=B3=E7=90=86?= =?UTF-8?q?=E6=B8=85=E5=87=8F=20docs/=20=E7=BB=93=E6=9E=84=E5=B9=B6?= =?UTF-8?q?=E5=85=91=E7=8E=B0=20AGENTS.md=20=E5=BC=95=E7=94=A8=E6=89=BF?= =?UTF-8?q?=E8=AF=BA;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 修复 docs/arch/vendors.md 第 4 行的 framework.md 断链路径（./ → ../） - 补全 docs/agents/knowledge-map.md 占位为真正的项目文档索引（兑现 AGENTS.md L51 承诺） - 新建 docs/agents/browser-validation.md 完整浏览器验证协议（兑现 AGENTS.md L49 承诺） - 迁移 docs/ci-cd.md 至 docs/ops/ 子目录，建立运维向正交分类 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- docs/agents/browser-validation.md | 172 ++++++++++++++++++++++++++++++ docs/agents/knowledge-map.md | 94 +++++++++++++++- docs/arch/vendors.md | 2 +- docs/{ => ops}/ci-cd.md | 12 +-- 4 files changed, 272 insertions(+), 8 deletions(-) create mode 100644 docs/agents/browser-validation.md rename docs/{ => ops}/ci-cd.md (98%) diff --git a/docs/agents/browser-validation.md b/docs/agents/browser-validation.md new file mode 100644 index 0000000..bed80b6 --- /dev/null +++ b/docs/agents/browser-validation.md @@ -0,0 +1,172 @@ +# Browser Validation Protocol（浏览器验证协议） + +> 由 [AGENTS.md L49-50](../../AGENTS.md#L49) 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，**任何 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) 通过 `#L<行号>` 或 `#章节锚点` 形式引用 +- 修订本协议**必须**在 [docs/issue.md](../issue.md) 留存背景与决策记录 +- 协议条款发生变更时，需同步检查 [AGENTS.md L49-50](../../AGENTS.md#L49) 的兜底原则与本协议是否一致 + +--- + +## 附录 A：术语对照 + +| 术语 | 说明 | +| ------------------- | ----------------------------------------------------------------- | +| 主 profile | 用户日常使用的 Chrome / Edge 浏览器档案，含真实登录态 | +| Sandbox 浏览器 | 自动化工具启动的临时/隔离浏览器，无真实用户态 | +| 同意屏（Consent） | OAuth 流程中用户授予权限范围的页面 | +| 接力流程 | Agent 停止 → 用户介入完成 → Agent 恢复 的三段式协作 | +| 实机回归 | 在用户真实终端（非 CI）完成的端到端验证 | diff --git a/docs/agents/knowledge-map.md b/docs/agents/knowledge-map.md index 70e90bf..fc06537 100644 --- a/docs/agents/knowledge-map.md +++ b/docs/agents/knowledge-map.md @@ -1,3 +1,95 @@ # Knowledge Map（知识索引） -(WIP) +> 项目所有文档的统一入口与权威索引。由 [AGENTS.md](../../AGENTS.md#L51) 锚定，文档目录变更时**必须**即时同步更新本文件。 +> +> **使用方式**：按"受众 × 目的"二维定位所需文档；不确定起点时，从「入口导航」开始。 + +[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` 文件存在。 diff --git a/docs/arch/vendors.md b/docs/arch/vendors.md index 2ec79ad..0e0d862 100644 --- a/docs/arch/vendors.md +++ b/docs/arch/vendors.md @@ -1,7 +1,7 @@ # 供应商模块（vendors/） > 路径约定：相对于 `src/coding/proxy/` -> 定位：从 [framework.md](./framework.md) 提取，详述供应商分类体系与各供应商实现。 +> 定位：从 [framework.md](../framework.md) 提取，详述供应商分类体系与各供应商实现。 [TOC] diff --git a/docs/ci-cd.md b/docs/ops/ci-cd.md similarity index 98% rename from docs/ci-cd.md rename to docs/ops/ci-cd.md index 6b35b38..65d0464 100644 --- a/docs/ci-cd.md +++ b/docs/ops/ci-cd.md @@ -211,7 +211,7 @@ CI 流水线中使用的工具及其版本均与项目实际配置严格对齐 | 工具 | 版本 / 引用 | 来源 (Action) | 与项目配置的对齐关系 | | -------------- | ----------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------- | -| Python | `["3.12", "3.13", "3.14"]` (matrix) | `actions/setup-python@v5` | 对齐 [`pyproject.toml`](../pyproject.toml) 中 `requires-python = ">=3.12"` | +| Python | `["3.12", "3.13", "3.14"]` (matrix) | `actions/setup-python@v5` | 对齐 [`pyproject.toml`](../../pyproject.toml) 中 `requires-python = ">=3.12"` | | uv | latest (v4) | `astral-sh/setup-uv@v4` | 项目强制包管理器（见 AGENTS.md 包管理规范） | | build | latest | `uv pip install --system build` | PEP 517 构建前端，后端为 hatchling | | twine | latest | `uv pip install --system twine` | 包元数据校验与上传工具 | @@ -435,7 +435,7 @@ flowchart TD ### 4.1 promote.yml 工作流架构 -[`promote.yml`](../.github/workflows/promote.yml) 由两个 Job 组成，形成 **Validate → Promote** 的串行管线： +[`promote.yml`](../../.github/workflows/promote.yml) 由两个 Job 组成，形成 **Validate → Promote** 的串行管线： #### Job 1：validate（验证门控） @@ -629,7 +629,7 @@ flowchart TD | 问题现象 | 可能原因 | 排查步骤 | 解决方案 | | ------------------------------- | ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------- | | `release.yml` 未触发 | Release 创建时未触发 `published` 事件（如 Draft 状态） | 检查 Actions 页面是否有该 workflow run | 确保 Release 为非 Draft 状态；或重新发布 | -| `build` Job 失败 | `twine check` 报错（包元数据不合规） | 查看 build Job 日志中的 twine 输出 | 修复 [`pyproject.toml`](../pyproject.toml) 中的元数据字段 | +| `build` Job 失败 | `twine check` 报错（包元数据不合规） | 查看 build Job 日志中的 twine 输出 | 修复 [`pyproject.toml`](../../pyproject.toml) 中的元数据字段 | | publish 失败 (HTTP 400) | 包名或版本号冲突（目标仓库已有同版本） | 查看 verbose 日志中的响应体（已启用 `verbose: true`） | 检查 TestPyPI/PyPI 是否已有同版本；使用递增版本号 | | publish 失败 (HTTP 403) | 认证失败（Token 无效或缺失） | 检查 Job 日志中的认证错误详情 | 验证 Secret 配置或 Trusted Publisher 设置（参见 §7.2） | | `promote.yml` validate 失败 | Target release 不是 prerelease（已是 stable） | 查看 validate Job 错误信息 | 确认输入的 `tag_name` 对应的是 prerelease release | @@ -701,7 +701,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置 | CI 配置 | 项目配置 | 对齐关系 | | ------------------------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `python-version: "${{ matrix.python-version }}"` | `requires-python = ">=3.12"` in [`pyproject.toml`](../pyproject.toml) | CI 构建环境必须满足项目的最低 Python 版本要求（matrix: 3.12 / 3.13 / 3.14） | +| `python-version: "${{ matrix.python-version }}"` | `requires-python = ">=3.12"` in [`pyproject.toml`](../../pyproject.toml) | CI 构建环境必须满足项目的最低 Python 版本要求（matrix: 3.12 / 3.13 / 3.14） | | `hatchling.build` (build-backend) | `[build-system] requires = ["hatchling"]` | 构建后端声明必须一致 | | `uv pip install --system` | AGENTS.md 强制使用 `uv` | GitHub Actions Runner 默认无激活的 virtualenv，需 `--system` 标志 | | `retention-days: 14` | — | Artifact 保留两周，覆盖正常的验证窗口期（通常 1-3 天） | @@ -714,7 +714,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置 ### 8.1 release.yml 结构索引 -[`.github/workflows/release.yml`](../.github/workflows/release.yml) 文件结构一览： +[`.github/workflows/release.yml`](../../.github/workflows/release.yml) 文件结构一览： | 行范围 | 区块 | 内容摘要 | | ------- | ----------------------- | ---------------------------------------------------------------------------------------------------- | @@ -729,7 +729,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置 ### 8.2 promote.yml 结构索引 -[`.github/workflows/promote.yml`](../.github/workflows/promote.yml) 文件结构一览： +[`.github/workflows/promote.yml`](../../.github/workflows/promote.yml) 文件结构一览： | 行范围 | 区块 | 内容摘要 | | ------ | --------------- | -------------------------------------------------------------- | From 9ccf1279735c4b911494f5910fcbb45c15fd022b Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Sun, 17 May 2026 22:44:49 +0800 Subject: [PATCH 2/2] =?UTF-8?q?fix(docs):=20=E7=A7=BB=E9=99=A4=E4=B8=8D?= =?UTF-8?q?=E5=8F=AF=E5=AF=BC=E8=88=AA=E7=9A=84=20#L<=E8=A1=8C=E5=8F=B7>?= =?UTF-8?q?=20=E9=94=9A=E7=82=B9=E9=93=BE=E6=8E=A5;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GitHub Markdown 渲染视图不为列表项生成行号锚点，#L49/#L51 等后缀无法定位到目标位置。 统一改为 §名称 前缀 + 纯文件链接，保留人眼可读性。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- docs/agents/browser-validation.md | 6 +++--- docs/agents/knowledge-map.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/agents/browser-validation.md b/docs/agents/browser-validation.md index bed80b6..ee4b705 100644 --- a/docs/agents/browser-validation.md +++ b/docs/agents/browser-validation.md @@ -1,6 +1,6 @@ # Browser Validation Protocol（浏览器验证协议） -> 由 [AGENTS.md L49-50](../../AGENTS.md#L49) 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，**任何 AI Agent 在执行浏览器自动化任务前必须完整遵循**。 +> 由 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，**任何 AI Agent 在执行浏览器自动化任务前必须完整遵循**。 > > **协议版本**：v1.0 ｜ **生效范围**：所有面向本仓库的 AI Agent 协作场景 > @@ -155,9 +155,9 @@ CI 流水线（详见 [ops/ci-cd.md](../ops/ci-cd.md)）**不**触发浏览器 ## 8. 引用规范 -- 本协议章节可被 [AGENTS.md](../../AGENTS.md) / [CLAUDE.md](../../CLAUDE.md) 通过 `#L<行号>` 或 `#章节锚点` 形式引用 +- 本协议章节可被 [AGENTS.md](../../AGENTS.md) / [CLAUDE.md](../../CLAUDE.md) 通过标题锚点形式引用 - 修订本协议**必须**在 [docs/issue.md](../issue.md) 留存背景与决策记录 -- 协议条款发生变更时，需同步检查 [AGENTS.md L49-50](../../AGENTS.md#L49) 的兜底原则与本协议是否一致 +- 协议条款发生变更时，需同步检查 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 的兜底原则与本协议是否一致 --- diff --git a/docs/agents/knowledge-map.md b/docs/agents/knowledge-map.md index fc06537..08bd983 100644 --- a/docs/agents/knowledge-map.md +++ b/docs/agents/knowledge-map.md @@ -1,6 +1,6 @@ # Knowledge Map（知识索引） -> 项目所有文档的统一入口与权威索引。由 [AGENTS.md](../../AGENTS.md#L51) 锚定，文档目录变更时**必须**即时同步更新本文件。 +> 项目所有文档的统一入口与权威索引。由 [AGENTS.md §Knowledge Map](../../AGENTS.md) 锚定，文档目录变更时**必须**即时同步更新本文件。 > > **使用方式**：按"受众 × 目的"二维定位所需文档；不确定起点时，从「入口导航」开始。