协作规范¶

本页定义了贡献者在共享仓库中应如何协作，不论另一位贡献者是人类队友还是自动化工具。

共享工作树流程¶

        flowchart LR
    Start["Start work"] --> Status["Check git status"]
    Status --> Dirty{"Dirty or shared worktree?"}
    Dirty -- "No" --> Scope["Confirm task scope and contracts"]
    Dirty -- "Yes" --> ReRead["Re-read active files and identify unrelated changes"]
    ReRead --> Conflict{"Direct conflict?"}
    Conflict -- "Yes" --> Coordinate["Pause and coordinate before editing"]
    Conflict -- "No" --> Scope
    Scope --> Edit["Make focused edits"]
    Edit --> Contract{"Changed shared contract?"}
    Contract -- "Yes" --> Update["Update tests, docs, and handoff notes"]
    Contract -- "No" --> Validate["Run required validation"]
    Update --> Validate
    Validate --> Handoff["Share summary, contracts, validation, and follow-ups"]

        flowchart LR
    Start["开始工作"] --> Status["检查 git status"]
    Status --> Dirty{"是否为脏工作树或共享工作树?"}
    Dirty -- "否" --> Scope["确认任务范围与共享契约"]
    Dirty -- "是" --> ReRead["重读活跃文件并识别无关改动"]
    ReRead --> Conflict{"是否存在直接冲突?"}
    Conflict -- "是" --> Coordinate["暂停编辑并先协调"]
    Conflict -- "否" --> Scope
    Scope --> Edit["进行聚焦编辑"]
    Edit --> Contract{"是否修改了共享契约?"}
    Contract -- "是" --> Update["同步更新测试、文档与交接说明"]
    Contract -- "否" --> Validate["运行所需验证"]
    Update --> Validate
    Validate --> Handoff["共享摘要、契约、验证与后续事项"]

当多个贡献者或工具都可能修改当前工作树时，这就是默认协作路径。

共享工作树纪律¶

在进行大规模编辑之前，先检查当前工作树状态。
对于与当前任务无关的本地改动，除非您有明确证据证明它们可丢弃，否则都应视为他人的工作。
不要使用破坏性的 git 命令丢弃并非由您产生的改动。
在编辑正在频繁变化的文件之前，请先重新阅读其最新内容，尤其是大型 route handler、共享工具以及文档入口文件。

开始编辑前¶

先判断这项任务是单一关注点还是多个关注点。若一个变更同时混入行为调整、重构和贡献者工作流更新，请拆分成不同分支或 PR。
在编辑前先识别您可能会改动的共享契约。Schema、环境变量、路由返回形状、工具名称、持久化客户端键以及贡献者命令都需要明确的后续处理。
在开始写代码前就确定需要运行哪些验证命令，以及需要同步更新哪些文档。

范围纪律¶

让每个分支或 PR 都聚焦于一个工程关注点。
除非重构是保证行为变更安全所必需的，否则应将重构与行为修改分开。
迁移、环境变量修改和 API 契约变更要显式呈现，不要把它们藏在大而泛的清理型 diff 里。
像迁移文件或 .po 更新这类由源变更所要求的生成产物，应与源变更放在同一个提交中，便于评审者验证完整的契约变化。

共享契约¶

当您修改以下任何仓库级共享契约时，都需要谨慎协同：

数据库 schema 与迁移
环境变量与启动假设
API 请求与响应形状
工具名称、工具权限等级与技能契约
持久化的客户端/会话键，例如由 localStorage 支撑的智能体状态
贡献者使用的文档入口页

当您修改共享契约时：

在同一个变更中更新相关文档
更新契约边界的测试
在 PR 或交接摘要中明确说明该变化

可评审性¶

使用具描述性的分支名与 Conventional Commits。
优先提交便于评审的小型补丁，而不是大而混杂的 diff。
写明您实际运行过的验证命令以及观察到的结果。
对于 UI 或工作流变更，在可行时附上截图、短录屏或精确的复现说明。

评审与交接清单¶

在请求评审或将工作移交给其他贡献者之前，请包含以下内容：

变更了什么，以及它对用户或维护者有什么影响
哪些共享契约、迁移或高风险文件需要额外关注
您实际运行过的验证命令以及观察到的结果
任何已知的后续事项、上线步骤或尚未解决的风险

在可能的情况下，使用简洁的交接格式：

Summary:
Contracts:
Validation:
Follow-ups:

交接示例¶

Summary: Added repository and agent contribution flow diagrams to the development docs.
Contracts: Contributor guidance changed in AGENTS.md and docs/development/*.md; translation catalogs refreshed.
Validation: npm run lint; npm test; NEXT_TELEMETRY_DISABLED=1 npm run build; sphinx-build en/zh with -W --keep-going.
Follow-ups: Translate newly added Chinese msgstr entries if localized docs need complete coverage.

人与自动化的协作¶

在要求自动化工具修改仓库之前，先让它们阅读 AGENTS.md。
给自动化工具分配边界清晰、文件或子系统范围明确的任务。
审查自动化生成的 diff 时，应保持与审查人工提交同样的怀疑态度。
自动化工具完成后要重新运行验证，而不是直接相信它的成功声明。
如果自动化任务修改了贡献者工作流、文档或架构边界，请确保人工评审者先看到这些变化。
在自动化开始编辑前，要明确告诉它哪些内容不可触碰、哪些契约敏感、以及必须运行哪些验证命令。
把自动化工具的摘要当作线索，而不是真相。最终的契约、风险和验证检查责任仍在评审者。

文档与翻译工作流¶

英文 Markdown 源文件是文档的权威来源。
当英文文档发生变化时，请刷新 .po 文件，以便翻译漂移能被立即发现。
让仓库级贡献者指南在 AGENTS.md、CONTRIBUTING.md 与 docs/development/ 之间保持一致。

何时应暂停并协调¶

若出现以下情况，请先暂停并协调，再继续推进：

另一位贡献者的改动与您的任务直接冲突
您需要重写一个被多个子系统使用的共享契约
您不确定某个仅本地使用的目录，是否实际上已被他人的工作流当作源码输入
某项迁移或执行路径变更可能在没有明确发布路径的情况下破坏现有环境