📄 明确代理创建 PR 的描述规范

AGENTS.md

@@ -99,3 +99,7 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of
 > Two conventions are enforced via built-in rules in `eslint.config.mjs`: `no-restricted-imports` bans `@radix-ui/react-*` single packages (use the merged `radix-ui`) and the `sonner` `toast` export (use `notify`); `no-restricted-syntax` bans `forwardRef` across `src/pages/**` (use React 19 `function` + ref-prop). All four syntax-based harness rules are covered by `eslint-rules/harness.test.mjs`.
 >
 > Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` — `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so `async` JSX handlers are allowed), and `await-thenable`, all `error` — to catch missing `await`s and promises misused as void callbacks. These need type information, so they are *not* part of `harness.test.mjs`.
+
+## Pull Request Description Format
+
+Detailed PR description guidance lives in [`docs/pull-request.md`](docs/pull-request.md). Start from the human-facing template, preserve its checklist, and expand the description only when the change needs more context. Do not claim human review or other evidence that did not happen.

docs/DOC-MAINTENANCE.md

@@ -27,6 +27,7 @@ Aspirational / feature-branch content belongs in that branch's docs, or is clear
 | --- | --- |
 | [`../AGENTS.md`](../AGENTS.md) | Engineering principles + architecture quick-map. Single source of truth; `CLAUDE.md` only `@import`s it. |
 | [`develop.md`](./develop.md) | The concrete "how": commands, structure, style, i18n, commit/PR; testing mechanics split to [`references/develop-testing.md`](./references/develop-testing.md). |
+| [`pull-request.md`](./pull-request.md) | Detailed PR description structure and guidance for agents and contributors; the human-facing template remains lightweight. |
 | [`design.md`](./design.md) | The design system: theme mechanism, shadcn component selection, new-page recipe; tokens split to [`references/design-tokens.md`](./references/design-tokens.md), component palette to [`references/design-components.md`](./references/design-components.md), layout/motion/state/a11y patterns to [`references/design-patterns.md`](./references/design-patterns.md). |
 | [`verification.md`](./verification.md) | Lightweight end-to-end functional verification — throwaway scratch scripts driving the real built extension; report template split to [`references/verification-report-template.md`](./references/verification-report-template.md), debugging FAQ to [`references/verification-debugging.md`](./references/verification-debugging.md). |
 | [`architecture.md`](./architecture.md) | Deep internals: process model, message passing; subsystem deep-dives split to [`references/architecture-services.md`](./references/architecture-services.md), [`references/architecture-data.md`](./references/architecture-data.md), [`references/architecture-gm-api.md`](./references/architecture-gm-api.md), [`references/architecture-execution.md`](./references/architecture-execution.md), [`references/architecture-build.md`](./references/architecture-build.md). |

docs/README.md

@@ -8,6 +8,7 @@
 | --- | --- |
 | [`../AGENTS.md`](../AGENTS.md) | 工程原则、架构速览、AI/贡献者约定的单一信息源(`CLAUDE.md` 仅导入它)。 |
 | [`develop.md`](./develop.md) | 开发规范:命令、目录结构、编码风格、UI/主题、i18n、提交/PR 流程;测试机制(含 Vitest 性能)拆到 [`references/develop-testing.md`](./references/develop-testing.md)。**写代码前先读。** |
+| [`pull-request.md`](./pull-request.md) | PR 描述指南:代理与贡献者使用的详细章节、按变更类型取舍规则、验证与审查信息要求。 |
 | [`design.md`](./design.md) | 设计系统参考:主题机制、shadcn 组件选型、新建页面配方总览;令牌完整值拆到 [`references/design-tokens.md`](./references/design-tokens.md),组件清单拆到 [`references/design-components.md`](./references/design-components.md),布局/响应式/动效/状态/无障碍范式拆到 [`references/design-patterns.md`](./references/design-patterns.md)。**做页面/对话框/区块前先读。** |
 | [`verification.md`](./verification.md) | 功能验证指南:用一次性 scratch 脚本驱动真实扩展做端到端验证(不跑全量 E2E、不加永久用例);报告模板拆到 [`references/verification-report-template.md`](./references/verification-report-template.md),调试 FAQ 拆到 [`references/verification-debugging.md`](./references/verification-debugging.md)。**验证改动是否真正跑通时读。** |
 | [`architecture.md`](./architecture.md) | 内部原理总览:多进程模型、消息传递;各子系统深入拆到 [`references/architecture-services.md`](./references/architecture-services.md)(服务层)、[`references/architecture-data.md`](./references/architecture-data.md)(数据层)、[`references/architecture-gm-api.md`](./references/architecture-gm-api.md)(GM API)、[`references/architecture-execution.md`](./references/architecture-execution.md)(脚本执行)、[`references/architecture-build.md`](./references/architecture-build.md)(构建管线)。 |

docs/develop.md

@@ -106,6 +106,6 @@ Commits must be single-purpose and **start with a gitmoji emoji** — use the ac
 
 Work from a feature branch or fork and open PRs against `main`. Chinese PR titles are preferred for changelog generation.
 
-Use `.github/pull_request_template.md` (checklist + description + screenshots). Include a problem/solution summary, linked issues (`close #123` / `fix #123`), test results, and screenshots or recordings for UI changes.
+Use `.github/pull_request_template.md` as the starting point. It is intentionally lightweight for human-authored PRs; agents should preserve its checklist and expand `Description / 描述` only when useful. The detailed structure is defined in [`pull-request.md`](./pull-request.md). Keep exact commands and results in `验证`, describe UI evidence when the change is visual, and do not claim checks or evidence that did not happen.
 
 **Review policy**: review **all** modified files (including `.md`/`.json`); PR description is context only — judge from the diff. Verify every code path touched.

docs/pull-request.md

@@ -0,0 +1,62 @@
+# Pull Request Description Guide
+
+This guide defines the detailed PR description format for agents and contributors. The human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) intentionally remains lightweight; use it as the starting point and expand its `Description / 描述` section when the change needs more context.
+
+## Recommended structure
+
+For a normal feature or behavior change, use the following sections when they are meaningful:
+
+```markdown
+## Checklist / 检查清单
+
+- [ ] Fixes ... / 已修复或实现 ...
+- [ ] Code reviewed by human / 代码通过人工检查
+- [ ] Changes tested / 已完成测试
+
+## 背景
+
+<!-- What problem, compatibility gap, or maintenance need does this solve? -->
+
+## 本次改动
+
+<!-- Summarize user-visible behavior and important implementation changes. -->
+
+## 实现考虑
+
+<!-- For non-trivial changes: explain key design decisions, invariants, races, or compatibility choices. -->
+
+## 已知限制
+
+<!-- Record explicit scope boundaries, unsupported cases, and follow-up work. -->
+
+## 建议审查重点
+
+<!-- List concrete behaviors or risks reviewers should verify. -->
+
+## 参考
+
+<!-- Specs, documentation, code locations, or external API references. -->
+
+## 关联
+
+<!-- Related issues or PRs, using links or closing keywords when applicable. -->
+
+## 验证
+
+<!-- Exact commands and concise results. Include known warnings or explain why a check was not run. -->
+```
+
+`Checklist`、`背景`、`本次改动` and `验证` are the recommended core for a normal feature or behavior change, not mandatory headings for every PR. Add `实现考虑` for meaningful design or concurrency implications; add `已知限制` and `建议审查重点` when reviewers need explicit boundaries or risk areas. `参考` and `关联` are optional.
+
+Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR.
+
+## Review-oriented content
+
+For non-trivial changes, make the description useful for review:
+
+- `背景` explains the problem, compatibility gap, or maintenance need.
+- `本次改动` summarizes user-visible behavior and important implementation changes.
+- `实现考虑` records design decisions, invariants, lifecycle behavior, races, or compatibility choices.
+- `已知限制` records unsupported cases, explicit scope boundaries, and follow-up work.
+- `建议审查重点` lists concrete behaviors or risks reviewers should verify.
+- `验证` lists exact commands and concise results, including known warnings or why a check was not run.