企业官网建设流程全解析

Easydict 贡献指南语义移植：跨仓库文档迁移的决策、结构与验证实践

【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict

本篇指南基于 Easydict 仓库中记录的一次真实文档治理任务——将上游 Scoco 项目最新的CONTRIBUTING.md相关提交语义移植到 Easydict，最终形成一个以根目录中文贡献指南为核心的统一贡献入口。读完本篇，你将掌握跨仓库移植贡献文档时的结构设计思路、语言策略取舍、PR 契约保留方法，以及一套可复用的 Markdown 文档静态验证流程，并能在本仓库中直接对照最终产物与实际执行记录。

任务背景与目标

Easydict 是一个支持查词、文本翻译、划词翻译和 OCR 截图翻译的 macOS 词典翻译应用，仓库同时维护中英文两份 README（README_ZH.md 与 README.md）。在 2026-09-02 之前，项目的贡献说明分散在多个位置，缺少一个 GitHub 可发现的根目录统一入口。

本次移植任务的用户请求非常明确：将 Scoco 最新的CONTRIBUTING.md相关提交合并移植到当前 Easydict，并创建一个本地提交。任务的完整执行记录保存在 docs/histories/2026-09/2026-09-02-easydict-contributing-guide-port.md，对应的归档计划位于 docs/exec-plans/completed/2026-09/2026-09-02-easydict-contributing-guide-port.md。

来源是 Scoco 的三个连续提交：ae0ecdf46、7d74c756a、ae7fa25f4。这三个提交本身是一次"扩展 → 纠正环境前置 → 收敛"的连续编辑过程，最终结构以ae7fa25f4为准。

任务初始状态

移植任务开始前，仓库处于一个干净的基线状态，这也是执行模式任务的典型前置条件：

• 分支：dev
• initial_head：35e9f6cc2ecfde4ad74eaeb0cb452d42bce4285d
• 初始暂存区：空
• 初始工作树：干净
• 初始冲突：无

记录中"自动提交资格：eligible"表明，在验证和精确暂存通过后，任务会以一次本地提交交付，且不 push。

核心变更：统一贡献入口

本次移植落地了四项关键变更，最终产物可以直接在仓库根目录验证：

1. 新增根目录中文CONTRIBUTING.md，将参与方式、源码构建入口、PR 要求和详细文档集中为一个 GitHub 可发现的根目录入口。这是本次任务最核心的产物，实际内容见 CONTRIBUTING.md。
2. 收束两个 README 的贡献段落：英文 README 明确说明其贡献指南链接目标为中文；中英文 README 均指向同一份根目录指南。
3. 保留 Easydict 专属的贡献契约：dev默认分支、类型/简短描述分支命名、Angular-style 提交格式、关联 Issue、验证和 UI 截图契约，全部保留。
4. 取消不完整的双语镜像方案：经用户复核，改为遵循来源最终结构——中文贡献指南承载完整规则，英文 README 明确指向该中文指南。

从变更范围看，这次任务被严格限定在文档治理层面：允许修改路径仅为CONTRIBUTING.md、README.md、README_ZH.md、docs/exec-plans/与docs/histories/2026-09/，不涉及任何产品代码、Xcode 工程或外部服务。

适配决策：为什么是"语义移植"而非 cherry-pick

这是本次任务最值得借鉴的技术决策点。三个来源提交是一次连续编辑过程，因此没有直接 cherry-pick，而是按ae7fa25f4的最终简洁结构合并为一个 Easydict 提交。原因在于：

• 直接 cherry-pick 会引入 Scoco 的中间状态（如扩展阶段产生的冗余内容），而语义移植只继承最终语义；
• Scoco 有而 Easydict 没有的事实不能混入：Scoco.xcworkspace、Scocoscheme、macOS 14.6、README_EN.md、changelog.md、Bundler、常规pod install等均被排除在公开入口之外；
• 一个语义聚焦的提交比多个中间提交更符合 Easydict 的提交规范。

第二个关键决策是构建入口的简洁化。来源提交7d74c756a移除了 Bundler 和常规pod install前置，Easydict 采纳了"构建入口保持简洁"的语义：贡献指南只链接现有的中文 Developer Build Guide（docs/user-docs/zh/GUIDE.md#开发者构建），不把签名配置、CocoaPods 故障排查等内容重复为首次构建前置条件。这类"文档入口只做路由、细节留在专题文档"的做法，也是本仓库 AGENTS.md 中"现行规则文档单一职责，跨职责使用链接，不复制条款"原则的体现。

第三个决策是语言结构：来源的英文 README 明确指向中文贡献指南，Easydict 复用该结构，而不是维护缺少架构和 Agent 文档译本的双语镜像。同时，既有中英文 GUIDE 的详细贡献章节不在来源差异范围内，保持不动，避免无关的公共文档重构。

最终贡献指南的结构解析

最终落地的 CONTRIBUTING.md 是一份完整的简体中文指南，共九个部分，每个部分解决一个具体的贡献问题。以下结合仓库内实际文件逐一解析。

如何参与

指南明确了三类参与方式的分层：

• 报告缺陷前先搜索已有 issue，并提供复现步骤、版本和可公开的日志或截图；
• 较大的功能、界面或架构变更，先讨论目标和用户体验再实现；
• 范围明确的小修复、文档、本地化和测试改进可以直接提交 PR。

同时强调"每个 PR 保持聚焦，不混入无关改动、本地配置、密钥或用户数据"，这一契约与AGENTS.md中"用户的禁止、范围和顺序要求优先"的任务边界原则相互呼应。

使用编程 Agent

这是 Easydict 贡献指南的特色章节。仓库已深度集成 Agent 辅助开发流程：

• 开始贡献前强烈建议阅读 AGENTS.md，并按其中"任务路由"一节阅读相关专题规则；
• 欢迎使用 Codex、Claude 等编程 Agent 阅读代码、分析问题、规划实现、生成补丁和参与 review，建议选择当前最新、适合复杂编程任务的 GPT 或 Claude 模型；
• 使用 Agent 不转移贡献者责任：提交者必须理解最终代码、确认改动符合项目架构与规范，并排除无关修改、虚构实现或未经验证的假设。

AGENTS.md 本身是"Agent 的唯一任务入口"，它定义了计划模式（只读分析）与执行模式（修改交付）两类任务模式，并给出任务路由：构建与测试走 docs/agents/build-and-test.md，代码质量走 docs/agents/coding-guidelines.md，计划与 history 记录走 docs/exec-plans/README.md 与 docs/histories/README.md。

指南还提到常用 Skill（review、review-pr、submit-pr、git-commit、worktree-rebase-merge等）由上游统一维护，Easydict 的项目专属规则仍以AGENTS.md为准，Skill 的具体能力与安装方式以上游文档为准。

开始开发

从源码构建请参阅开发者构建指南。关键要求是用 Xcode 打开Easydict.xcworkspace（workspace）而不是Easydict.xcodeproj，选择Easydictscheme 后编译或运行。修改前先理解涉及的实际行为、调用关系和架构边界——架构边界可以参考 docs/design-docs/application-architecture.md，其中给出了Easydict/App、Easydict/Swift（Feature/Model/Service/Utility/View）与Easydict/objc的源码布局。

提交 Pull Request

这一节集中了 Easydict 的核心 PR 契约，也是移植时明确保留的内容：

• 默认向dev提交，维护者指定其他目标分支时以其为准；
• 分支使用类型/简短描述的 kebab-case 格式，例如feat/openai-translation或fix/ocr-window-focus，禁止直接在dev或main上提交；
• 提交使用 Angular-style 格式，保持单个提交语义聚焦；
• 在 PR 模板的"关联 Issue"区域填写相关 Issue，不使用 GitHub 自动关闭关键字或 Development 侧栏的自动关闭关联；
• PR 应说明目的、主要变化、影响范围和验证结果；UI 变化附截图或录屏，行为变化同步必要测试和用户文档。

值得注意的是，本次移植任务自身的交付就遵循了这一契约——所有变更通过一次本地 Angular-style 提交交付，不 push。

提交前的 review 与验证

对于 Agent 参与的改动，提交 PR 前必须仔细 review 最终 diff，并在实际使用场景中运行验证，至少覆盖：原问题或目标场景、正常流程、受影响的关键边界。指南明确指出"Agent review、自动测试和 CI 都不能替代实际场景验证"。

PR 中需要写明验证环境、步骤、结果和未验证项。纯文档或其他静态修改按实际范围完成链接、格式或配置检查即可，不要把未运行的构建或测试写成已通过。这与 docs/agents/build-and-test.md 中"测试只修改已授权的测试与 fixture；不把未运行、失败或环境阻塞的检查写成通过"的规则完全一致。

提交后的 review 流程

本项目会为 GitHub Pull Request 启用 Codex Automatic reviews。PR 进入 review 后，Codex 会按照适用的AGENTS.md规则提供额外审查，也可以显式请求审查。

处理 reviewer 意见的原则是"先逐条甄别"：

• 有效问题应修复并重新验证；
• 不准确或不适用的评论不必盲从，但应回复原因，并提供代码、测试或运行证据；
• 有分歧时继续讨论，不要只为清空状态而直接 resolve thread；
• 更新代码后检查 CI、冲突和剩余评论，确认没有无人回应或尚未处理的有效 review 问题。

指南同时强调，自动 review 是额外的质量检查，不能替代贡献者 review、测试、分支保护或维护者的最终判断。

Review 周期与处理优先级

由于活跃维护者数量有限，人工 review 周期可能较长且无法承诺固定处理时间。等待期间贡献者应主动推进流程：自查 diff、处理 CI 和冲突、回复 review 评论、补齐验证证据，准备完成后简要说明进展并请求复审。

会被优先处理的 PR 特征包括：明确修复可复现 bug 或解决具体且充分说明的问题；改动聚焦、代码清晰、符合现有架构与代码规范；提供自动测试或可靠的实际场景验证结果且 CI 通过；review 意见已充分处理。但优先处理不代表必然合并，维护者仍会根据正确性、产品方向、兼容性和维护成本作出最终判断。

详细文档

指南末尾以链接列表收束到全部详细文档，形成"根目录指南路由 + 专题文档承载细节"的完整结构：

• 开发者构建指南
• 架构与源码定位
• 构建与测试
• 编码规范（代码质量、Swift/API 与本地化）
• Agent 开发入口

README 贡献入口的设计

本次移植的另一半工作是调整两个 README 的贡献段落，形成"英文 README → 中文贡献指南 → 专题文档"的入口链：

• README.md 的Contributing一节明确写着"Read the Chinese contribution guide"，并在AI Coding小节中同样指向中文指南——即使贡献者是英文读者，也以中文指南为唯一权威来源；
• README_ZH.md 的"贡献"与"AI 辅助编程"两个小节都链接到根目录 CONTRIBUTING.md；
• 两个 README 均保留了既有 Issue/PR 处理说明（维护者通常周末处理 issue、优先 PR）。

这个设计的取舍在于：与其维护一份缺少架构和 Agent 文档译本的不完整英文镜像，不如让英文 README 明确指向结构完整的中文指南，保证信息一致性和可维护性。

验证方法：一套可复用的 Markdown 文档治理检查清单

本次任务的验证环节非常值得借鉴，因为它提供了一套不依赖 Xcode 的纯文档静态验证方法（源码修改才需要xcodebuild，本次仅改 Markdown 故未运行）：

1. git diff --check通过：检查空白错误（如尾随空白），这是 docs/agents/build-and-test.md 中"每次变更运行"的默认检查。
2. Markdown 相对链接检查通过：所有新增本地目标存在，英文 README 和中文 README 均可定位到根目录贡献指南。这也是文档治理的关键——AGENTS.md 明确要求"文档使用相对仓库路径，不提交机器本地绝对路径"。
3. 贡献契约与负向扫描通过：保留 Angular-style、分支命名、关联 Issue、UI 截图和AGENTS.md；公开入口未出现 Scoco、Scoco.xcworkspace、macOS 14.6、README_EN.md、changelog.md、Bundler 或常规pod install。
4. 语言结构复查通过：根目录贡献指南为完整中文文档，英文 README 明确标注链接目标为中文，不存在不对等的语言区块。
5. 尾随空白检查：新增 Markdown 无尾随空白；README 既有的尾随空白行未修改（避免无关 diff）。
6. 变更路径检查：仅包含任务契约中的 README、贡献指南、plan 和 history 路径，没有越界改动。

这套方法可以概括为：范围检查（只改该改的）+ 链接检查（相对链接全部可达）+ 负向扫描（不混入来源专属事实）+ 语言结构检查（多语言入口语义一致）+ 空白检查（最小化 diff）。

配套的执行记录体系

移植任务本身的执行过程也被完整记录在仓库的 plan/history 体系中，这套机制同样面向 Agent 协作：

• 计划归档于 docs/exec-plans/completed/2026-09/2026-09-02-easydict-contributing-guide-port.md，包含任务契约、初始状态、来源与适配、实施步骤、风险与决策、验证六个部分；
• 历史记录（即本主题关联文档）链接到归档计划，记录"已落地结果与关键决策，不复制完整对话"；
• 命名遵循 docs/histories/README.md 的 slug 规则：YYYY-MM-DD-<slug>.md，同一任务与计划共享 slug；docs/exec-plans/README.md 规定多步骤、跨模块或高风险任务在active/建计划，完成后归档到completed/YYYY-MM/。

这套体系与贡献指南中"使用编程 Agent 时理解最终代码、确认改动符合项目规范"的要求形成闭环：Agent 的每一次文档治理变更都有计划、有记录、可追溯。

总结

从这次移植任务可以提炼出跨仓库贡献文档迁移的四条核心经验：

1. 语义移植优于机械合并：连续编辑的上游提交应按最终结构合并为单一提交，只继承最终语义，不引入中间状态。
2. 入口路由优于内容复制：根目录指南只保留稳定入口和 PR 契约，构建细节、签名配置、故障排查等继续由专题文档维护，避免多份文档重复维护、内容漂移。
3. 语言策略要明确对等：中文指南承载完整规则，英文 README 明确指向中文指南，放弃不完整的双语镜像，保证单一权威来源。
4. 静态验证可完全自动化：git diff --check、相对链接可达性、负向扫描、语言结构复查、尾随空白检查，构成一套不依赖 Xcode 的文档治理验证清单。

最终的 CONTRIBUTING.md 已经在仓库根目录就位，中英文 README 的贡献入口均已收束到该指南，Easydict 的dev分支、分支命名、Angular-style 提交、关联 Issue、UI 截图等贡献契约也全部保留——一次聚焦的文档治理迁移由此完成。

【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用，支持离线 OCR 识别，支持有道词典，🍎 苹果系统词典，🍎 苹果系统翻译，OpenAI，Gemini，DeepL，Google，Bing，腾讯，百度，阿里，小牛，彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict