---
name: contribute
description: 引导读者为《追忆似水年华》译文贡献修订：优先复用环境记忆，缺失或变化时检查并准备 Git／GitHub 连接器环境，再核实 polish/dev 中的待改文字，对照 raw-md 法语原文提供直译和文化说明，待用户再次确认后修订，按权限通过 fork 提交 PR，或由 Collaborator 直接提交到上游新建分支／main。在用户要求参与贡献、修订译文并提交，或按贡献指南操作时使用。
---

# 贡献译文修订

上游仓库：<https://github.com/QriDoki/in-search-of-lost-time-translation-project>。
全程用中文指导，尽量由 Agent 完成操作，只把必须由用户完成的登录、授权和内容决策交给用户。GitHub 将合并请求称为 Pull Request（PR），本流程中的 MR 指同一件事。

完成流程：读取环境记忆 → 按需检查／准备环境并更新记忆 → 接收修改需求 → 核实 polish/dev 与其他版本 → 对照 raw-md 提供法语原文、直译与文化说明 → 用户再次确认 → 按权限准备目标仓库与分支 → 修订和核对 → 提交修订（需要时创建 PR）。仅被要求编写或解释本指南时，不执行贡献流程。

## 强制提交边界

**先提供核查信息，再取得用户对具体修订的明确确认。** 用户最初提供改前文字和期望改法，或笼统要求“修订并提交”，均不代替看到原文、直译和文化说明后的再次确认。环境记忆读取与必要的环境准备放在最前，可先完成工具安装、登录授权、检查已有 fork；仅有连接器且缺少 fork 功能时，可先引导用户在 GitHub 网页创建 fork。除上述环境准备外，确认前只做读取、定位和分析，不改写正文，不创建贡献分支，不执行 Git 提交、推送或 GitHub 写入操作。具备 fork 功能时，Agent 创建 fork 仍在用户确认具体修订之后进行。

按实际验证的身份选择提交路径：

- **普通贡献者或身份／写权限无法验证**：本地修改／连接器写入 → 提交到自己的 fork 贡献分支 → 向上游创建 MR／PR。不得直接写入上游；fork 不可用时保留成果并处理阻塞，不改为直接写入上游。
- **已验证的上游 Collaborator，且具有仓库写权限**：可以直接提交到上游**本次新建的贡献分支**，或直接提交到上游 **`main`**，无需强制 fork。只能更改 `polish/dev/` 下的文件。未指定目标时优先提议新建贡献分支；在第 5 节确认时写明目标仓库、分支和是否创建 PR，不能把用户对新建分支的确认当成直接提交 `main` 的许可。
- **所有身份都禁止更改 `release` 分支**：不得向其提交、push、创建／更新／删除引用，或通过连接器、API、网页编辑及合并 PR 写入；管理员权限也不例外。不得选择 `release` 作为本次提交或 PR 的目标分支。
- 译文贡献只修改 `polish/dev/`，不得新建时间戳文件夹或修改已有正式版本、工作流等其他文件。直接写入上游时，应核对本次全部待推送提交相对目标分支的差异，而不只检查工作区最新一次修改；不得夹带目录外的历史提交。
- 不自动合并 PR，不绕过分支保护；目标写入被拒时保留进度并说明阻塞，不改写 `release`、不强制推送、不修改权限或保护规则。
- `dev` 不参与 CI/CD 发布；正式版本由维护者发布时整理。

## 1. 优先读取环境记忆

启动时，先读取“本项目 + 当前用户 + 当前环境”的贡献记忆：优先使用 Agent 持久记忆，否则读取项目根下的 `work/contribute-memory.md`；也可使用用户提供的恢复摘要。

- **已有可用记录**：直接沿用工具路径、账号、已验证权限及 fork 信息，跳过环境准备文件，进入第 3 节。不重复执行版本、认证、连接器能力、Collaborator 权限或 fork 检查，也不因新会话或时间经过重新要求安装、登录或授权。
- **没有记忆、记忆缺少所需信息或属于不同用户／环境**：必须先读取 [环境准备](environment-setup.md)，仅检查缺失项并写入记忆，再继续正文核查。
- **记忆存在待处理项**：必须读取环境准备文件，从已记录的步骤恢复，只验证该项；例如重启后只验证连接器加载情况，不重跑全部检查。
- **用户告知环境变化或实际操作出现异常**：将受影响记录标为待验证／不可用，读取环境准备文件对应部分，定向处理并更新记忆。

用户已提供的改前文字和期望改法直接保留。环境记忆用于复用配置，不替代第 5 节对具体修订及目标仓库／分支的确认，也不替代实际写入前的目标与差异核对。

## 2. 必须更新环境记忆

环境核查结果以及后续工具、登录、授权、账号、权限、fork、路径或提交方式的变化，都必须及时写入记忆，不能只在回复中说明。优先持久记忆，否则使用不加入提交的 `work/contribute-memory.md`；无法持久化时明确说明并提供恢复摘要。

保存实际结果、验证依据、当前状态及待处理步骤；用户声称完成但尚未验证时记为“待验证”。账号或认证上下文变化时，不继承其他身份的权限。详细字段及恢复规则见 [环境准备文件的记忆规范](environment-setup.md#必须保存环境核查与后续变更)，在需要创建或更新环境记录时按需读取，不在环境可用时例行加载。

## 3. 接收需求，核实 polish/dev 中的原句

用户尚未说明需求时，询问：

> 你想修改哪一卷、哪一章或哪段文字？请粘贴改前文字和希望改成的样子，也可以描述需要解决的问题。我会先核实版本、对照法语原文，提供直译和文化说明，再请你确认是否提交修订。

用户已经提供的信息直接沿用，只补问缺失部分。收到改前文字后，先在 `polish/dev/` 中搜索，读取命中文件的完整相关段落，核对上下文；不能仅凭用户给出的路径或其他版本的命中认定句子存在于开发稿。可用本地工具时先用 `rg -n -F -- '<改前文字>' polish/dev`，连接器则读取并核对对应完整正文。多行文字或标点、空白、注释差异导致无法精确命中时，可用辨识度高的片段辅助定位，但必须展示实际原句并说明差异。

- **dev 中找到**：告知文件路径、章节、行号或段落定位及当前原句。多处命中时展示候选上下文，让用户选定，不能默认全部替换。
- **dev 中未找到**：继续搜索 `polish/` 下除 `dev/` 以外的其他版本，明确告知是否找到，并列出命中的版本、文件位置与原句；不能把其他版本的句子说成开发稿正文。若其他版本有命中，再定位 dev 中的对应段落，展示当前措辞及差异。若当前 dev 已是用户期望的文字，说明无需重复修订。
- **两处都未找到或对应关系不明确**：如实说明检索范围和结果，请用户补充卷章或更长上下文；可展示候选段落，但未确认对应关系前不进入提交确认。

项目结构为：

```text
polish/
  <时间戳版本>/chapters/*.md  # 正式版本，只读，可用于核实用户所读版本
  dev/chapters/*.md           # 唯一译文修订目标
raw-md/
  vol*/chapters/*.md          # 法语原文，对照时只读
```

通常上游已经有 `polish/dev/chapters/`。直接复用它，保留已有的全部修订，不再从正式版本覆盖，不为每次贡献创建新文件夹。`dev` 已存在但正文缺失或不完整时，先调查原因，不能重新拷贝整个目录覆盖已有工作。

仅当 `polish/dev` 完全不存在时，读取上游基线，筛选带 `chapters/` 子目录且名称符合 `YYYYMMDDhhmmss`（可带递增后缀）的文件夹，按文件夹名降序确定最新来源。此时明确告知用户“dev 尚不存在”，可先用该来源做原文核查和修订提案，不能声称句子已在 dev 中。获得第 5 节的确认后，才在本地或已确认目标仓库的允许分支完整复制该目录到 `polish/dev` 初始化一次。没有可用来源时报告阻塞，不凭空生成全书。

初始化时核对相对文件清单与逐文件内容，确保复制完整，不仅复制准备修改的章节。连接器必须读取完整内容并核对写回结果，无法完整复制时报告缺失能力。记录上游基线提交；后续以该提交中的 `polish/dev` 核对本次变化，首次初始化时以被复制的时间戳目录作为内容对照。

## 4. 在 raw-md 中定位法语原文并提供参考

先读取本技能目录中的 [开发稿与法语原文文件对应表](chapter-map.md)，按 `vol{x}-y` 或已定位的 dev 文件查找对应 raw-md 文件。表中是文件级映射，具体句子仍须用上下文核实；文件结构变化或表中未列出时，调查实际对应关系，不机械套用编号。

以已定位的中文段落、卷章标题及前后文，在 `raw-md/` 中找到对应的法语原文，读取足够的上下文核实对应关系。中法文件的分章和编号可能不同，不能仅靠文件名或编号配对。展示法语原句及文件路径、章节、行号或段落定位；无法可靠定位时说明缺口并继续查找或请用户补充信息，不凭记忆编造原文，不进入提交确认。

给用户提供：

- **平铺直叙的直译参考**：以法语原文为依据，用最朴素、清楚的中文表达字面意思，保留否定、时态关系、人物指代及关键意象。可拆开长句帮助理解，不为追求文采增删意思；有歧义时说明可能的读法与上下文依据。这是参考，不自动作为最终修订。
- **文化说明**：涉及典故、历史人物、宗教、社会习俗、称谓、艺术作品或双关等文化因素时，说明具体所指及其在此句中的作用，以及不同改法可能保留或损失的含义。优先查看项目已有注释与资料，需要外部核实时引用可靠来源；区分已核实背景和解释性推断，不确定时明确标注。没有相关文化因素时简短说明即可，不硬加解释。
- **对期望改法的说明**：并列当前 dev 原句、用户期望的改法及拟提交的具体文字，说明改法与原意是否一致、是否影响语气或文化含义。如需调整用户的改法，明确给出建议及理由，不能悄悄替用户决定。

其他版本命中时，同时列明用户所引文字的版本及 dev 的当前措辞；始终针对当前 dev 提出修订。文化说明默认在会话中提供，未经用户要求，不自动向正文增添注释。

## 5. 展示完整提案，等待用户再次确认

完成版本核实、原文定位、直译及文化说明后，展示可审阅的修订提案：目标 dev 文件与段落、当前文字、拟修改文字、对应法语原文及位置、直译参考、文化说明和需要用户决定的歧义，并列明已验证的身份、目标仓库与分支，以及提交方式（fork PR／上游新建分支／上游 main）。用户引用的是其他版本时，突出说明本次实际修改的 dev 文字；需要首次初始化 dev 时，列明复制来源。

普通贡献者按 fork PR 路径明确询问：

> 以上是版本核查、法语原文、直译参考和文化说明。是否确认按上述“拟修改文字”修订 `polish/dev`，并通过 fork 向上游提交 PR？

Collaborator 采用上游提交路径时，明确询问：

> 是否确认按上述“拟修改文字”修订 `polish/dev`，并直接提交到上游仓库的 `<本次新建贡献分支或 main>`？本次仅修改 `polish/dev/`，不更改 `release` 分支。<若计划创建 PR，一并说明其 base 和 head。>

**等待用户明确同意该具体提案后，才进入贡献分支创建、后续修订及提交操作。** 沉默、先前的概括性提交请求或用户继续讨论措辞，都不算确认。用户提出新改法时，更新相关参考和提案，再请其确认；用户不提交时保留讨论结果，不执行提交。

若用户明确只要本地修订，将问题中的提交范围改为“仅本地修改，不提交 GitHub”，按该范围执行，不推断远程提交授权。恢复任务时，只有能核实用户已经确认且提案、目标正文均未变化，才可沿用该确认；若后续上游变化或冲突使实际修订内容改变，重新展示相关原文参考及修订提案并取得确认。

## 6. 按权限准备目标仓库和分支

远程准备仅适用于第 5 节已确认远程提交的情况；仅本地修订时保留现有工作，必要时使用本地独立分支，跳过远程准备。

- **普通贡献者**：读取上游默认分支及最新 SHA 作为基线；若默认分支是 `release`，改用已核实存在的 `main` 作为基线及 PR 目标，没有允许的目标则报告阻塞。复用已验证的 fork，没有则创建并等待就绪；连接器不能 fork 且没有可用 fork 时，读取 [环境准备](environment-setup.md) 中的网页 fork 指引。仅在 fork 中从基线创建 `codex/polish-dev-<简短主题或唯一后缀>` 分支，不在上游创建分支。
- **Collaborator 直接提交上游**：沿用记忆中已验证的当前身份与写权限，若发生账号变更或权限异常则先定向复查并更新记忆；核实确认目标为上游 `main` 或本次新建的贡献分支，不能使用 `release` 或其他已有上游分支。直接提交 `main` 时以其最新 SHA 为基线；新建分支默认从最新 `main` 创建，名称使用 `codex/polish-dev-<简短主题或唯一后缀>`，已存在同名分支时另选名称并更新提案确认，恢复同一任务已创建的分支除外。新建分支如需 PR，base 使用已确认的非 `release` 分支，默认 `main`。
- **共同核对**：记录基线 SHA，以其中的 `polish/dev` 为正文对照。若目标段落与已确认提案不同，重新进行第 3 至 5 节的核查与确认。
- **本地 Git**：先检查未提交修改，不清理、不覆盖、不夹带无关工作。必要时使用单独工作目录；复用已有 remote，不因名为 `origin` 就假定其指向 fork 或上游。使用 `git remote get-url --push --all <目标remote>` 核对全部推送地址均为已确认仓库，检查明确的目标分支及全部待推送提交。普通贡献者的地址只能是其 fork；只有已验证的 Collaborator 才能使用上游地址。
- **连接器**：每次创建分支、写文件、提交或更新引用前，核对仓库与分支符合用户已确认的路径及身份权限。普通贡献者只写 fork，Collaborator 可写已确认的上游新建分支或 `main`，均不得写 `release`。读取固定基线的完整正文，不使用搜索摘要代替内容；工具无法处理完整文件或初始化复制时，报告缺失能力或改用可用本地路径。

用户在第 5 节已确认具体修订、目标仓库与分支后，无需反复请求同一操作的许可。变更目标仓库、分支或实际修订内容时重新确认。本指南不要求合并 PR。

## 7. 按要求修改并核对

只对第 5 节已确认的章节、段落和拟修改文字实施修订，写入前再次核对当前正文。范围或措辞变化时返回提案确认，不自行扩大为全书重译或全局替换。保留 Markdown 结构、脚注引用与定义、标题层级及未涉及的正文。

向用户展示实际修改的前后文与原因。核对分两层进行：

1. **正文差异**：把 `dev` 与上游基线提交中的 `dev` 比较（首次初始化时与复制来源比较），确保只有本次预期段落改变、章节齐全、没有截断或脚注丢失。不把上游已有的未发布修订算作本次修改。
2. **提交差异**：检查贡献分支相对上游基线的文件清单，译文变更应全部位于 `polish/dev/`，不包含时间戳目录、用户其他修改、记忆文件或构建产物。

本地 Node 与项目依赖可用时，显式运行 `POLISH_VERSION=dev npm run build` 验证开发稿；涉及电子书结构时再运行 `POLISH_VERSION=dev npm run build:epub`。本地未显式指定时只会构建正式版本，不能用这种结果声称已验证 `dev`。CI/CD 会忽略 `dev`，不要为绕过发布限制而创建时间戳目录或修改工作流。依赖或运行能力缺失时如实列明未运行项，在提交结果及 PR（如有）中说明，不能宣称验证通过。

## 8. 按确认路径提交修订

- 无实际正文变化时不创建空提交或空 PR；告知用户并保留准备工作。
- 写入前重新读取目标分支的最新正文。若其他贡献已合入，基于共同祖先合并本次修改并保留双方修订；连接器读取最新文件后迁移改动，不能用旧全文覆盖。语义冲突或实际修订内容变化时，按第 4、5 节更新参考与提案并等待确认；不覆盖用户未提交的工作。
- 本地仅暂存本次修改的 `polish/dev/` 文件，避免 `git add .`。检查暂存差异及目标分支之外的全部待推送提交，确保全部文件变化均在 `polish/dev/` 下。推送前核对全部推送地址和目标分支；身份与权限沿用有效环境记录，有变化或异常时定向复查并更新记忆，使用 `git push <已验证目标remote> HEAD:refs/heads/<已确认分支>`。普通贡献者只能推送 fork；Collaborator 可推送已确认的上游新建分支或 `main`。禁止向 `release` 或标签写入、无目标的 `git push`、`--all`、`--mirror` 和强制推送。连接器每次写入前同样按已记录身份核对目标仓库、分支、路径与基线，确认最终仅包含本次已确认修订。
- **fork 路径**：查询该 fork 分支是否已有 PR，有则更新原 PR；否则在上游创建，base 为第 6 节确定的非 `release` 分支，head 为 `<用户>:<贡献分支>`，避免误建到 fork 自己。
- **上游新建分支路径**：将修订提交到该分支；用户确认包含 PR 时，在上游创建或复用该分支的 PR，base 默认 `main`，head 为该贡献分支，禁止以 `release` 为 base。
- **上游 main 路径**：将修订提交到 `main`，核实返回的提交 SHA 和文件差异，给出提交链接；不强制创建 PR。若分支保护拒绝直接提交，说明原因并提出改走新建分支或 fork PR，取得目标变更确认后再执行，不绕过保护。
- PR 标题概括具体修订，正文写明 `polish/dev`、基线 SHA、修改位置与原因、少量前后对照及实际验证结果，说明开发稿不直接发布。首次初始化时补充复制来源及实际正文变更范围。
- 完成后核实目标仓库、分支、提交 SHA，以及 PR 的 base／head（如有），记录到贡献记忆；支持 PR 附件时附到会话。最终提供提交或 PR 链接、修改摘要和验证情况。失败时记录分支与具体阻塞，从失败处恢复，不声称已提交、不自动合并、不更改 `release`。