/AGENTS.md

Maintainer Automation Notes

External contributors should start with CONTRIBUTING.md. This file documents stricter maintainer and agent automation workflows; it is not the public contribution checklist.

AGENTS 索引

本文件是贡献者规则的入口。详细策略文本位于 .agents/docs/standards/*.md。

Documentation Boundary

docs/ is reserved for public project documentation and README assets that open-source users or external contributors read directly. Maintainer policies, implementation plans, learning records, PR evidence, and recording assets belong under .agents/ so internal automation workflows stay out of the public docs tree.

Public user-facing documentation must be bilingual. Add or update the English document and the Simplified Chinese counterpart together; use README.md with README_zh.md, and use *.zh.md beside English guide files under docs/guides/.

Review Guidelines

When reviewing pull requests, prioritize findings that can cause correctness bugs, regressions, security or privacy issues, release failures, broken CI, broken packaging, or misleading evidence. Treat these as high-priority review findings.

Do not block on style-only or preference-only comments unless they make the code materially harder to maintain or violate an existing repository rule.

For every pull request, check:

1. The implementation matches the requested scope and does not mix unrelated refactors, feature work, or generated artifacts.
2. Tests contain meaningful assertions that would fail for realistic regressions, not only line coverage.
3. UI, viewer, or evidence changes include real trace-backed screenshots or recordings when required by repository policy.
4. Public documentation changes are bilingual, with matching English and Simplified Chinese updates.
5. Workflow, release, credential, subprocess, network, filesystem, and dependency changes use least privilege and avoid leaking secrets.
6. Commit titles, PR titles, PR bodies, and evidence links follow the repository contribution and preflight requirements.

When a finding is speculative, state the assumption and the concrete evidence needed to confirm it. Prefer a small number of actionable, high-signal findings over broad commentary.

Pre-commit Hook

项目提供了 .githooks/pre-commit 自动在 commit 前运行 lint 检查。首次 clone 后执行：

git config core.hooksPath .githooks

不可协商规则

以下规则是强制性的，并会在 review 中执行：

1. 每次 commit 前运行 gate 检查：uv run ruff check .、uv run ruff format --check .、uv run pytest tests/ -x --timeout=60。启用 pre-commit hook 可自动执行 lint 检查。
2. UI 变更要求在 PR 中提供使用 raw.githubusercontent.com 绝对 URL 的截图。
3. 每个 commit 只处理一个关注点（不要在同一 commit 中混合 refactor 与 feature/fix）。
4. 代码、注释、commit message 和 skill 文件仅使用英文。对外文档必须中英文双份，中文内容放在 README_zh.md 或对应的 *.zh.md 文件中。
5. 证据必须使用 .traces/ 中的真实 trace 数据（禁止合成 mock 截图/演示）。
6. 编码前必须执行 pre-work checklist，开 PR 前必须执行 pre-PR checklist。
7. 不要留下仅本地存在的工作；你必须执行 git add、git commit 和 git push。
8. 你必须使用 gh pr create 打开 GitHub PR。

标准目录

• 硬性规则与仓库策略：.agents/docs/standards/hard-rules.md
• 验证 gate 与必需命令：.agents/docs/standards/validation-and-gates.md
• E2E 与截图证据要求：.agents/docs/standards/e2e-and-evidence.md
• 截图采集与验证标准：.agents/docs/standards/screenshot-standards.md
• 编码与运行时安全规则：.agents/docs/standards/coding-and-runtime.md
• 工作流、review 与 Brain/Hands 协议：.agents/docs/standards/workflow-and-review.md
• 调试方法论与反模式：.agents/docs/standards/debugging-standards.md
• 客户端支持矩阵与 URL 构造规则：docs/support-matrix.md
• 标准文档元数据与维护流程：.agents/docs/standards/README.md

Skills 目录

可复用的 agent 技能位于 .agents/skills/，按功能分类：

测试

• e2e-test：pytest E2E 测试套件
• real-e2e-test：真实 Claude CLI E2E 测试（pytest + tmux 模式）
• js-in-html-testing：HTML 内嵌 JS 的两层测试策略（Python 单测 + Playwright）

验证

• legibility-check：文档结构、标准 freshness、manifest 路径、plan 状态检查
• screenshot-validation：截图质量 + viewer HTML 渲染验证
• pr-preflight：PR 合并就绪全面检查（lint + test + CI + 截图）

翻译

• translate-i18n：自动补全 viewer I18N 缺失翻译（via OpenRouter）

发布

• push-release：推送代码并按需 bump 版本触发 PyPI 发布

资产生成

• demo-video：从真实 E2E 运行录制演示视频
• playwright-screen-recording：Playwright 录屏用于 PR review

Scripts 目录

scripts/ 下的确定性脚本，部分已被 skill 包装：

脚本	对应 Skill	用途
check_legibility.py	legibility-check	文档可读性检查（CI: legibility.yml）
check_changelog.py	legibility-check	publish 阶段校验 release tag 与 CHANGELOG.md 覆盖
update_changelog.py	legibility-check	auto-release 发 tag 前自动补齐 CHANGELOG.md release section，分支保护下会走 auto-merge release PR
check_coverage.py	-	Python/backend 与 viewer.html/frontend 的项目覆盖率和增量覆盖率 gate
check_pr_policy.py	pr-preflight	PR body、证据链接、危险文件和运行时变更 evidence policy gate（CI: pr-policy）
check_screenshots.py	screenshot-validation	截图质量检查（CI: ci.yml）
check_screenshots.sh	screenshot-validation	检查 git staged 图片的 shell 包装
verify_screenshots.py	screenshot-validation	Playwright viewer HTML 渲染验证
check_pr.sh	pr-preflight	PR 合并就绪检查
translate_i18n.py	translate-i18n	自动翻译 i18n 缺失 key
run_real_e2e.sh	real-e2e-test	真实 E2E（非 tmux）
run_real_e2e_tmux.sh	real-e2e-test	真实 E2E（tmux 交互模式）

可读性检查

确定性的可读性检查由 scripts/check_legibility.py 实现，并在 CI 中通过 .github/workflows/legibility.yml 运行。