Skip to content

📝 新增 AGENTS.md AI 编码代理指南及配套文档体系#1488

Merged
CodFrm merged 3 commits into
mainfrom
docs/agent-guides-and-doc-reorg
Jun 3, 2026
Merged

📝 新增 AGENTS.md AI 编码代理指南及配套文档体系#1488
CodFrm merged 3 commits into
mainfrom
docs/agent-guides-and-doc-reorg

Conversation

@CodFrm
Copy link
Copy Markdown
Member

@CodFrm CodFrm commented Jun 3, 2026 •
edited
Loading

Checklist / 检查清单

  • Fixes mentioned issues / 修复已提及的问题
  • Code reviewed by human / 代码通过人工检查
  • Changes tested / 已完成测试

Description / 描述

以新增 AGENTS.md 为核心，建立面向 AI 编码代理的贡献者文档体系（纯文档 + 工具配置，无业务代码改动）。

核心

  • 新增 AGENTS.md：AI 编码代理的唯一指南（工程原则 + 架构地图 + 文档导航）；CLAUDE.md 仅 @import AGENTS.md，不再单独维护内容。

配套文档体系

  • docs/DEVELOP.md — 开发规范（命令、结构、风格、UI/主题、测试、i18n、提交/PR 流程）
  • docs/ARCHITECTURE.md — 架构深入（多进程模型、消息传递、服务/数据层、GM API、构建管线 + 扩展配方）
  • docs/VERIFICATION.md — 用一次性 scratch 脚本端到端验证真实扩展
  • docs/DOC-MAINTENANCE.md — 文档维护规范（链接、索引、去重、可验证）
  • docs/README.md — 全量贡献者文档索引

整理与配套调整

  • 翻译相关文档归入 docs/translation/（README + terminology-*），删除被 AGENTS.md 取代的 docs/AI prompt.md
  • 重写 SECURITY.md：私密漏洞上报流程与协调披露（CONTRIBUTING / CONTRIBUTING_ZH / CONTRIBUTING_RU 同步补充安全提示）
  • 新增 playwright.scratch.config.ts + e2e/scratch/（已 gitignore）+ playwright.config.ts 的 testIgnore，支撑一次性验证脚本
  • eslint.config.mjs 忽略 playwright-report/ 与 test-results/ 生成产物，避免 lint 被污染

本 PR 不关联具体 issue。改动均为文档与工具配置，本地 tsc --noEmit && eslint . 通过；未涉及业务逻辑与单测 / E2E 用例。

Screenshots / 截图

无（纯文档 / 配置改动）。

@CodFrm
📝 新增 AGENTS.md AI 编码代理指南及配套文档体系
6dca634 
- 新增 AGENTS.md：AI 编码代理的唯一指南（工程原则 + 架构地图 + 文档导航），
  CLAUDE.md 仅 @import 引用，不再单独维护内容
- 配套新增文档体系：docs/DEVELOP.md（开发规范）、docs/ARCHITECTURE.md（架构深入）、
  docs/VERIFICATION.md（功能验证）、docs/DOC-MAINTENANCE.md（文档维护）、docs/README.md（文档索引）
- 翻译相关文档归入 docs/translation/（README + terminology-*），删除被 AGENTS.md 取代的「docs/AI prompt.md」
- 配套调整：重写 SECURITY.md 私密漏洞上报流程（CONTRIBUTING 同步补充）、
  新增 playwright scratch 一次性验证脚本工具链、eslint 忽略 playwright-report/ 与 test-results/ 生成产物
@CodFrm CodFrm force-pushed the docs/agent-guides-and-doc-reorg branch from aeeaa1d to 6dca634 Compare June 3, 2026 06:55
@CodFrm CodFrm changed the title 📝 重构贡献者文档，新增 AI agent 指南与安全策略 📝 新增 AGENTS.md AI 编码代理指南及配套文档体系 Jun 3, 2026
@CodFrm CodFrm requested a review from Copilot June 3, 2026 14:44
Copilot AI reviewed Jun 3, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

本 PR 以新增 AGENTS.md 为核心，建立面向 AI 编码代理/贡献者的文档体系，并配套调整安全上报说明与 Playwright 一次性端到端验证（scratch）流程相关配置；整体不涉及业务逻辑改动。

Changes:

  • 新增贡献者/代理文档集：开发规范、架构深入、一次性验证指南、文档维护规范、翻译/术语规范与索引。
  • 重写/补强安全策略与贡献指南中的私密漏洞上报提示。
  • 增加 Playwright scratch 专用配置并在主配置中忽略 scratch；ESLint 与 gitignore 增补忽略 Playwright 产物与 scratch 目录。

Reviewed changes

Copilot reviewed 16 out of 24 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
SECURITY.md 重写安全策略：明确支持版本策略与私密漏洞上报流程，并补充中文指引。
playwright.scratch.config.ts 新增 scratch 专用 Playwright 配置（复用主配置，定向 e2e/scratch/）。
playwright.config.ts 主 Playwright 配置忽略 e2e/scratch/，避免 scratch 脚本进入正式套件/CI。
eslint.config.mjs ESLint 忽略 playwright-report/ 与 test-results/ 生成目录，避免 lint 扫到产物。
docs/VERIFICATION.md 新增一次性端到端验证指南：用 scratch 脚本驱动真实构建扩展验证功能。
docs/translation/terminology-zh-TW.md 新增 zh-TW 术语与界面文案规范。
docs/translation/terminology-zh-CN.md 新增 zh-CN 术语与界面文案规范。
docs/translation/terminology-vi-VN.md 新增 vi-VN 术语与界面文案规范。
docs/translation/terminology-ru-RU.md 新增 ru-RU 术语与界面文案规范。
docs/translation/terminology-ja-JP.md 新增 ja-JP 术语与界面文案规范。
docs/translation/terminology-en-US.md 新增 en-US 术语与 UI 文案规范（作为翻译模板/回退语言的校准来源）。
docs/translation/terminology-de-DE.md 新增 de-DE 术语与界面文案规范。
docs/translation/README.md 新增翻译/本地化单一信息源与工作流说明，并登记各 locale 术语规范。
docs/README.md 新增贡献者文档索引页，汇总开发/架构/验证/维护/翻译/贡献指南入口。
docs/DOC-MAINTENANCE.md 新增文档维护与事实核对指南，强调 git-aware 校验与反“分支泄漏”。
docs/DEVELOP.md 新增开发规范：命令、结构、风格、测试、i18n、提交/PR 流程等。
docs/CONTRIBUTING_ZH.md 补充“安全漏洞不要公开提 Issue”的提示并链接安全策略。
docs/CONTRIBUTING_RU.md 同步补充安全漏洞私密上报提示并链接安全策略。
docs/ARCHITECTURE.md 新增架构/内部原理深挖文档（多进程模型、消息层、服务/数据层、GM API、构建等）。
docs/AI prompt.md 删除被新文档体系取代的旧 AI prompt 文档。
CONTRIBUTING.md 英文贡献指南增加安全漏洞私密上报提示并链接安全策略。
CLAUDE.md 新增 Claude 入口文件，仅指向 AGENTS.md。
AGENTS.md 新增 AI 编码代理唯一指南：工程原则 + 架构速览 + 文档导航。
.gitignore 不再忽略 CLAUDE.md；新增忽略 e2e/scratch/（一次性验证脚本目录）。

Comment thread AGENTS.md Outdated
Comment on lines +58 to +59
└── WindowMessage ──→ Offscreen (src/offscreen.ts)
└── WindowMessage ──→ Sandbox (src/sandbox.ts)
Comment thread AGENTS.md Outdated
Execution paths: page scripts → `chrome.userScripts`; background → SW → Offscreen → Sandbox; scheduled → cron in Sandbox.

### Message Passing (`packages/message/`)
`ExtensionMessage` (chrome.runtime), `WindowMessage` (postMessage), `CustomEventMessage` (CustomEvent), `MessageQueue` (cross-context broadcast).
Comment thread docs/README.md Outdated
| 文档 | 说明 |
| --- | --- |
| [`translation/README.md`](./translation/README.md) | 翻译 / 本地化指南(单一信息源):术语与修改规则、工作流、提取翻译提示词。**翻译前先读。** |
| [`translation/terminology-<locale>.md`](./translation/) | 各语言地区术语与界面文案规范(en-US / zh-CN / zh-TW / ja-JP / ru-RU / de-DE / vi-VN)。 |
CodFrm added 2 commits June 3, 2026 23:05
@CodFrm
📝 修正 AGENTS.md 消息通道描述与文档索引链接
0d5d5b8 
- AGENTS.md 多进程图与消息传递清单:SW → Offscreen 实为 ServiceWorkerMessageSend(Chrome,clients.matchAll + postMessage)/ EventPageOffscreenManager(Firefox),WindowMessage 仅用于 Offscreen ↔ Sandbox,与 ARCHITECTURE.md 保持一致
- docs/README.md:术语规范条目链接指向 translation/README.md 的术语表锚点,不再误导为某个具体文件
@CodFrm
📝 修正文档与代码不符的事实性描述
c9cc138 
按 docs/DOC-MAINTENANCE.md 的事实核对方法逐条对照已提交代码:

ARCHITECTURE.md
- Offscreen 实际运行 Server("offscreen")(非 Server-less)
- MockMessage 由测试(tests/utils.ts)直接使用,并非通过 chrome-extension-mock 暴露 / 在 vitest.setup.ts 注册;后者注册的是 chrome.* mock
- LoggerDAO 继承 DAO<T>(Dexie/IndexedDB),而非 Repo<T>
- @tests 别名仅在 vitest/tsconfig 定义,Rspack 构建只有 @App/@Packages
- 版本号不在 CopyRspackPlugin 改写,而在打包(pack.js)阶段注入
- pack.js 默认仅产出 Chrome zip + .crx,Firefox zip 由 PACK_FIREFOX 开关控制(默认关闭)
- filesystem 适配器无 local,实为 WebDAV / 云盘(OneDrive/Google Drive/Dropbox/百度/S3)/ zip

DEVELOP.md
- lint-fix 实际为 tsc --noEmit + eslint --fix

VERIFICATION.md
- 五个示例脚本的汇总行格式各异(合并行 / 分行 / 英文),正则可同时匹配
@CodFrm CodFrm merged commit 3d1cb79 into main Jun 3, 2026
2 of 4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@CodFrm