# 仓库维护

[English](maintaining_EN.md) · 中文

适用于有本仓库写入、合并或发布权限的维护者与其使用的 agent。贡献入口见 [CONTRIBUTING](../CONTRIBUTING.md)。当前主要维护者为 [@g-yixuan](https://github.com/g-yixuan)。

## 开发与合并

- `main` 是唯一日常主线。功能、修复、文档、CI、依赖与版本变更都从主题分支开 PR；维护者和 agent 遵守相同规则。
- PR 合并前，`ci` 和六个固定宿主 `plugin-mount` 检查全部成功，review threads 已处理，分支与当前主线兼容。周度 `host-canary` 单独跟踪宿主漂移，不作为每条 PR 的必需检查。
- 不直接推送、强推或删除 `main`，不以手动发布替代合并检查。紧急修复也走小 PR；CI 故障应先修复或公开说明有针对性的规则调整，不能默认忽略失败。
- 维护者审查问题、改动范围、回归风险和验证证据。外部 PR 经维护者审查后合并。当前单维护者阶段，自己的 PR 可在自查并通过全部 CI 后合并；不设置无法满足的“第二个人批准”要求。
- GitHub 的独立批准人数当前为 0，仍强制 PR、CI 和处理 review threads。有至少两位稳定维护者后，将人数调整为 1，自己的 PR 由另一人审查。
- 通常使用 Squash and merge，让 PR 对应一个清晰的变更；需要保留独立提交或多人历史时可使用 merge commit。合并前核对作者和共同作者署名，不把外部贡献改成自己的署名。
- PR 标题应描述用户可见行为，合并后按 GitHub 设置清理已合并分支。不要改写已合入的历史。

`main` 的规则通过 GitHub ruleset 执行：必须 PR、基础 CI 与固定宿主矩阵、review thread 解决、禁止强推和删除，维护者不设常规绕过。修改 CI 矩阵的 PR 必须同步调整 ruleset 的检查名称，避免留下失效门槛；配置入口为仓库 Settings → Rules → Rulesets。

宿主验收复用同一套核心 journey：实际 fork 出子会话、继承历史与输入框可用、消息进入子会话持久日志且未进入父会话。tab 出现、fork 错误态或乐观清空草稿都不能单独算通过；无凭证验收只证明消息接受与交互，不能证明模型回答成功。

每组 CI 保存 `test-results/host-inventory.json`、截图及失败日志。inventory 核对精确 CLI、实际激活的客户端 bundle 版本、宿主依赖版本与本次插件构建摘要；无法读取的组件记为未知，不用 CLI 或 devDependencies 补值。浏览器流程开始前拒绝旧构建，结束后再次核对。手工钉版验收时设置 `DSH_EXPECTED_VERSION`，脚本会拒绝实际版本不符或命令缺失，不自动换测 latest。

0.2.0-rc.2 已通过完整准入，作为第六组固定必需检查；原有五组全部保留。周度 canary 只解析一次 latest，随后按该精确版本跑相同核心流程并保存证据；失败在对应 job 中可见。后续候选仍需完整功能、相关真实运行及可见浏览器验收，再通过 PR 更新支持表和 required checks，并核对实际 ruleset。

兼容状态、有限支持窗口与候选准入见[兼容政策](compatibility.md)。旧版冻结仍守数据与投递承诺；退役必须独立 PR，不能按年龄或未知占比自动删除检查。

## Issue 与需求处理

优先检查重复反馈、复现是否充分、是否属于本插件和支持的宿主范围。需要补充信息时说明具体缺少什么，提供可操作的复现建议。

| 标签 | 用途 |
|---|---|
| `bug` / `enhancement` / `question` / `documentation` | 问题类型 |
| `needs reproduction` | 需要版本、步骤或可验证的复现；收到信息后移除 |
| `accepted` | 范围和方向已认可，可准备实施；不代表承诺日期 |
| `help wanted` | 欢迎协助；Issue 中应写明需要复现、测试、文档还是代码 |
| `good first issue` | 范围小、入口和验收清楚，维护者愿意协助新人 |
| `duplicate` / `wontfix` | 关闭时链接已有议题或解释取舍 |

先处理数据丢失、错误会话执行、无法使用与已支持宿主的回归，再处理普通缺陷和新需求。排序由维护者依据影响判断，不由提交者抢填优先级。

大需求先确认使用场景、边界、替代方案和验收；不要求所有小修复都先创建 Issue。PR 开始实施时关联原 Issue，完成时说明受影响版本；合入不等于已经发布。

不自动按静置天数关闭 Issue 或 PR。无法继续的事项由维护者说明原因后关闭，新增证据时可以重开。维护按可用时间进行，不承诺固定响应 SLA。

## 让更多人参与

定期把已确认的小任务整理成可开始的 Issue：说明问题、相关文件或入口、范围和完成信号，再使用 `good first issue` 或 `help wanted`。

主动邀请复现、答疑、测试和 review；这些贡献同样值得在 Issue、PR 和发布说明中感谢。使用 GitHub 自动贡献统计，不额外维护 README 头像名单。

持续做出可靠贡献并愿意承担维护的人，可与现有维护者公开讨论协作范围。先协助 triage/review，再按职责授予仓库权限；合并与发布权限单独明确。没有固定提交数量门槛，也不要求长期值班；不再参与时沟通交接并调整权限。

## 发布与规则演进

版本变更也走发布 PR；通过检查并合入后，按[发布指南](releasing.md) 创建 GitHub Release。发布说明用中英文简述变化、兼容性与已知限制，链接相关 PR 并保留贡献者署名。可使用 GitHub 的 Generate release notes 和 [分类配置](../.github/release.yml)。

新增规则、提高审批人数、兼容范围变化和维护职责调整均通过 PR 公开说明。当前不要求 CLA、DCO 签署、自动评审机器人或额外贡献账户认证。

公开规则的事实、命令和流程变化在同一 PR 同步中英文版本；维护者可以协助贡献者补齐翻译。单语言润色、日常 Issue/PR 讨论和本地工作记录不要求双语。参见[文档语言](../CONTRIBUTING.md#文档语言)。