Easydict 贡献指南语义移植跨仓库文档迁移的决策、结构与验证实践【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。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 词典翻译应用仓库同时维护中英文两份 READMEREADME_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为准。任务初始状态移植任务开始前仓库处于一个干净的基线状态这也是执行模式任务的典型前置条件分支devinitial_head35e9f6cc2ecfde4ad74eaeb0cb452d42bce4285d初始暂存区空初始工作树干净初始冲突无记录中自动提交资格eligible表明在验证和精确暂存通过后任务会以一次本地提交交付且不 push。核心变更统一贡献入口本次移植落地了四项关键变更最终产物可以直接在仓库根目录验证新增根目录中文CONTRIBUTING.md将参与方式、源码构建入口、PR 要求和详细文档集中为一个 GitHub 可发现的根目录入口。这是本次任务最核心的产物实际内容见 CONTRIBUTING.md。收束两个 README 的贡献段落英文 README 明确说明其贡献指南链接目标为中文中英文 README 均指向同一份根目录指南。保留 Easydict 专属的贡献契约dev默认分支、类型/简短描述分支命名、Angular-style 提交格式、关联 Issue、验证和 UI 截图契约全部保留。取消不完整的双语镜像方案经用户复核改为遵循来源最终结构——中文贡献指南承载完整规则英文 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 Guidedocs/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。指南还提到常用 Skillreview、review-pr、submit-pr、git-commit、worktree-rebase-merge等由上游统一维护Easydict 的项目专属规则仍以AGENTS.md为准Skill 的具体能力与安装方式以上游文档为准。开始开发从源码构建请参阅开发者构建指南。关键要求是用 Xcode 打开Easydict.xcworkspaceworkspace而不是Easydict.xcodeproj选择Easydictscheme 后编译或运行。修改前先理解涉及的实际行为、调用关系和架构边界——架构边界可以参考 docs/design-docs/application-architecture.md其中给出了Easydict/App、Easydict/SwiftFeature/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 故未运行git diff --check通过检查空白错误如尾随空白这是 docs/agents/build-and-test.md 中每次变更运行的默认检查。Markdown 相对链接检查通过所有新增本地目标存在英文 README 和中文 README 均可定位到根目录贡献指南。这也是文档治理的关键——AGENTS.md 明确要求文档使用相对仓库路径不提交机器本地绝对路径。贡献契约与负向扫描通过保留 Angular-style、分支命名、关联 Issue、UI 截图和AGENTS.md公开入口未出现 Scoco、Scoco.xcworkspace、macOS 14.6、README_EN.md、changelog.md、Bundler 或常规pod install。语言结构复查通过根目录贡献指南为完整中文文档英文 README 明确标注链接目标为中文不存在不对等的语言区块。尾随空白检查新增 Markdown 无尾随空白README 既有的尾随空白行未修改避免无关 diff。变更路径检查仅包含任务契约中的 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同一任务与计划共享 slugdocs/exec-plans/README.md 规定多步骤、跨模块或高风险任务在active/建计划完成后归档到completed/YYYY-MM/。这套体系与贡献指南中使用编程 Agent 时理解最终代码、确认改动符合项目规范的要求形成闭环Agent 的每一次文档治理变更都有计划、有记录、可追溯。总结从这次移植任务可以提炼出跨仓库贡献文档迁移的四条核心经验语义移植优于机械合并连续编辑的上游提交应按最终结构合并为单一提交只继承最终语义不引入中间状态。入口路由优于内容复制根目录指南只保留稳定入口和 PR 契约构建细节、签名配置、故障排查等继续由专题文档维护避免多份文档重复维护、内容漂移。语言策略要明确对等中文指南承载完整规则英文 README 明确指向中文指南放弃不完整的双语镜像保证单一权威来源。静态验证可完全自动化git diff --check、相对链接可达性、负向扫描、语言结构复查、尾随空白检查构成一套不依赖 Xcode 的文档治理验证清单。最终的 CONTRIBUTING.md 已经在仓库根目录就位中英文 README 的贡献入口均已收束到该指南Easydict 的dev分支、分支命名、Angular-style 提交、关联 Issue、UI 截图等贡献契约也全部保留——一次聚焦的文档治理迁移由此完成。【免费下载链接】Easydict一个简洁优雅的词典翻译 macOS App。开箱即用支持离线 OCR 识别支持有道词典 苹果系统词典 苹果系统翻译OpenAIGeminiDeepLGoogleBing腾讯百度阿里小牛彩云和火山翻译。A concise and elegant Dictionary and Translator macOS App for looking up words and translating text.项目地址: https://gitcode.com/gh_mirrors/ea/Easydict创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
