桌面应用网络后端【免费下载链接】MotrixA full-featured download manager.项目地址https://gitcode.com/GitHub_Trending/mo/Motrix点击查看免费下载本文围绕 Motrix 开源仓库的 .claude/rules/language-and-docs.md 规则文件展开系统讲解该仓库在「协作语言、双语公开文档、公开/私有内容边界、维护者文档Obsidian 网关」四个层面的强制约定。读完本文你将掌握 Motrix 贡献者协作时需要遵守的语言与文档纪律理解pnpm run docs网关的设计意图与完整用法并能对照仓库源码scripts/obsidian-docs.mjs、scripts/obsidian-docs-lib.mjs与测试tests/scripts/obsidian-docs.test.ts验证每条规则的真实落点。规则文件在仓库协作体系中的位置Motrix 以 Claude Code 规则作为规范性的 Agent 协作指引。根据 AGENTS.md任何 Agent 在检查或修改文件前必须依次读取 CLAUDE.md 与全部.claude/rules/*.md中无pathsfrontmatter 的全局规则其中就包含本规则文件。规则冲突时的裁决顺序为当前用户指令 AGENTS.mdCLAUDE.md 匹配的.claude/rules/*.md 默认行为。在 CLAUDE.md 的规则路由表中language-and-docs.md的职责被标注为Language and public/private documentation语言与公开/私有文档与commit-and-quality.md提交与质量门禁、git-workflow.mdGit 工作流等并列属于所有文件与所有操作都必须遵循的全局规则。它在仓库中被 git 跟踪git ls-files可见与.gitignore中的CLAUDE.local.md形成对照——前者是团队共享约定后者是个人机器专属内容。语言约定面向人的内容用对方语言面向机器的内容用英文规则文件第一条约束是「语言」代码、注释、提交信息、PR 标题、分支名、文件名与标识符一律使用英文与用户交流时使用用户所使用的语言例如中文用户会得到中文回复。这两条看似简单实则划清了「机器可读产物」与「人类可读沟通」的边界。对 Motrix 这类国际化下载管理器而言代码与标识符的英文统一保证了 src/core 等跨 shell 复用模块Electron 桌面端与 Node/Web 服务端共享同一核心在命名上的一致性而响应语言跟随用户则是社区协作的基本体验要求。仓库中的落地佐证用户可见文案通过 src/shared/locales 下 26 份语言资源文件管理并由 scripts/check-i18n.mjs 校验各语言逻辑键集合、复数类别与占位符一致性——UI 字符串的「多语言化」走的是 i18n 目录而非硬编码这恰好与「代码用英文、文案走翻译资源」的约定呼应。公开文档双语成对发布与同步更新成对发布规则规则规定新增的最终用户指南以及已有翻译对应版本的文档必须同时以英文name.md与中文name.zh-CN.md成对交付。仓库 docs 目录正是这样实践的例如 docs/plugin-hook-runtime.md 与 docs/plugin-hook-runtime.zh-CN.md、docs/bridge-pairing-protocol.md 与 docs/bridge-pairing-protocol.zh-CN.md、docs/docker-server.md 与 docs/docker-server.zh-CN.md 等release notes 目录同样按.md/.zh-CN.md成对组织。例外条款治理类文件、生成产物、子目录/开发者 README 可以保持单语言除非维护者明确建立成对版本。这意味着并非所有文件都必须双语判断标准是「读者是否为最终用户」。成对文件的同步纪律修改一对文件中的任何一个时必须在同一次变更中更新另一个并保证标题headings、命令commands、路径paths与代码示例code samples在两份文件中保持一致各自语言的行文必须地道idiomatic prose而不是机械翻译。该约束在仓库工具链中也有呼应docs目录属于已审阅的公开产物reviewed public artifacts而非私有设计资料tests/scripts/check-i18n.test.ts 等测试进一步佐证仓库对「双语内容对齐」的自动化校验倾向。公开/私有边界哪些内容永远不能进仓库规则文件用一整节强调公开与私有的边界这是 Motrix 作为开源仓库的安全底线机器专属的 Agent 上下文应放在被忽略的CLAUDE.local.md中.gitignore 第 141 行确实将其列入忽略清单永远不得提交私有计划private plans、提示词prompts、交接信息handoffs、凭据credentials、私有应用或 vault 名称、以及绝对本地路径absolute local paths公开的贡献流程必须能在**普通检出normal checkout**下运行——即不依赖任何私有账号、私有应用或相邻私有仓库若要把私有素材转为公开产物必须先改写为独立成篇的公开文档并审阅后再提交。这一节的工程后果是任何贡献者或 Agent都不应把本地机器路径、私人笔记库名称写进跟踪文件。仓库 .gitignore 第 154–156 行进一步将/obsidian-docs.config.json、/.obsidian-doc-context.json及临时文件排除在版本控制之外正是为了容纳「本地专属」的文档网关配置。维护者文档Obsidian 网关pnpm run docs全解规则明确指出维护者操作手册、部署 runbook、内部规格与实施计划默认归属 Obsidian 管理而不是直接塞进仓库。仓库提供了一套 CLI 网关封装对 Obsidian 的操作核心诉求是「要文档进仓库必须有用户明确请求否则一律走网关写入外部 vault」。为什么必须用pnpm run docs而不是裸pnpm docs规则特别警告裸pnpm docs可能被 pnpm 解析为内置的包文档命令因此必须显式写成pnpm run docs -- command或使用对应的docs:*脚本。仓库 package.json 第 57–66 行注册了整套脚本脚本等价命令用途docsnode scripts/obsidian-docs.mjs网关入口需跟命令docs:createnode scripts/obsidian-docs.mjs create创建文档docs:doctornode scripts/obsidian-docs.mjs doctor环境自检docs:listnode scripts/obsidian-docs.mjs list列出计划/规格docs:statusnode scripts/obsidian-docs.mjs status计划进度与验证状态docs:tasknode scripts/obsidian-docs.mjs task更新任务完成状态docs:usenode scripts/obsidian-docs.mjs use选择当前计划docs:contextnode scripts/obsidian-docs.mjs context输出计划上下文docs:checknode scripts/obsidian-docs.mjs check校验全部活动计划docs:clearnode scripts/obsidian-docs.mjs clear清除本地上下文初次使用时应先运行pnpm run docs -- help pnpm run docs -- doctorhelp打印完整用法与七个目标目录doctor则依次调用 Obsidian CLI 检查版本、vault 名称、项目根目录、文件数量与当前 Git 分支/HEAD实现见 scripts/obsidian-docs.mjs 的doctor分支runObsidian(config, [version])、vault infoname、folder path... infofiles再叠加getGitState输出branchhead。配置文件从示例模板起步网关依赖被忽略的本地配置文件obsidian-docs.config.json仓库只提供示例模板 obsidian-docs.config.example.json{ version: 1, vault: your-obsidian-vault, projectRoot: projects/motrix, repository: Motrix, contextFile: .obsidian-doc-context.json, commandTimeoutMs: 30000, directories: { activeSpecs: 20-active-specs, activePlans: 30-active-plans, decisions: 40-decisions, evidence: 50-evidence, publication: 60-publication, archivePlans: 90-archive/plans, legacyImport: 90-legacy-import } }使用时把示例复制为本地obsidian-docs.config.json并修改 vault 与目录。注意validateDocsConfigscripts/obsidian-docs-lib.mjs会强制校验version必须为 1vault、projectRoot、repository、contextFile必须为非空字符串且 vault 不含控制字符commandTimeoutMs必须是不小于 1000 的整数七个目录键必须齐全且所有路径必须是安全相对路径禁止\、NUL、绝对路径、空段、.与..。测试 tests/scripts/obsidian-docs.test.ts 覆盖了../plans穿越、C:\outside.json、\\server\share等恶意路径被拒绝的用例。在新工作树worktree中如果已有配置好的检出可用通过--config existing-local-config指定本地配置例如pnpm run docs -- doctor --config /path/to/obsidian-docs.config.json创建文档的标准姿势规则禁止用「直接写 vault 文件系统」或「UI 自动化」绕过网关。创建文档必须走pnpm run docs -- create directory name.md --from temporary-file参数说明directory必须是七个目录之一specs、plans、decisions、evidence、publication、archive-plans、legacy-import映射关系见DOCUMENT_DIRECTORY_KEYSname.md必须以.md结尾且解析后必须落在配置的projectRoot之下--from temporary-file指向仓库之外的临时源文件且必须指向普通文件而非符号链接若目标文档已存在必须先检查既有笔记--overwrite只允许用于预期中的更新。源码层面的三重安全闸门见 scripts/obsidian-docs-lib.mjs 的createDocument--from与--stdin二选一同时给出会报错内容禁止包含 NUL 字符且 UTF-8 字节数不得超过 512 KiBMAX_CREATE_CONTENT_BYTES先通过 Obsidian 的 eval 检查目标是否已存在且为 Markdown 文件——若存在而未传--overwrite根本不会调用 create 命令测试rejects an existing document before invoking the create command直接断言了这一点。创建后的回读校验规则强调创建命令成功并不代表手册完好。必须回读已保存的内容检查代码块与字面转义序列literal escape sequences是否原样保留。这条提醒对应网关以content参数把整篇文档透传给 CLI 的实现方式——超长、含特殊字符或换行异常的内容可能在传输中受损只有回读才能确认正文完整性。网关不可用时的兜底策略若网关或配置不可用例如本机没有obsidianCLI 或缺少obsidian-docs.config.json规则要求报告具体的阻塞原因blocker在仓库之外保留临时副本不得退而求其次把手册放进docs/也不得通过 PR 发布它。这与「docs/ 只存放已审阅公开产物」的边界一致——内部运维手册没有明确的公开化请求前任何形式的入库都是违规的。loadDocsConfig在找不到配置文件时会抛出「Copy obsidian-docs.config.example.json to obsidian-docs.config.json and customize the ignored local file」的明确指引测试explains how to create an optional local config也验证了这条报错路径。计划文档的配套机制任务 ID、进度与配对校验虽然规则文件本体不长但网关生态中与「维护者文档」配套的机制值得一并理解它们直接支撑「双语成对、进度可信」这两条规则稳定任务 ID任务行格式为- [x] [DOC-01] 描述ID 须匹配TASK_ID_PATTERN如DOC-01。parseTaskLines会检测重复 IDderiveProgress根据勾选状态推导implementation_statusnot-started/in-progress/verification双语配对校验validatePlanPair强制英文/中文两份文档的 doc_id、任务 ID 顺序、完成状态完全一致frontmatter 中bilingual_pair必须互为反向引用且要求 8 个元数据字段齐全含verified_head、verified_repository、progress_schema: stable-task-ids-v1本地上下文pnpm run docs -- use -- plan-id会把选中的计划写入检出根目录的.obsidian-doc-context.json0600 权限、拒绝符号链接、原子写入后续status/context/task不显式传参时可自动解析当前计划docs:clear清除它。规则在 Agent 协作中的实际执行路径把规则文件与仓库工具串起来Motrix 的文档协作闭环是日常协作代码、注释、提交、分支全英文回复用户用对方语言。公开文档新增指南按name.mdname.zh-CN.md成对提交标题/命令/路径/代码示例严格对齐。私有内容机器配置放忽略的CLAUDE.local.md绝不把私密计划、凭据、绝对路径提交进仓库。维护者手册默认写 Obsidian通过pnpm run docs -- help|doctor|create ...网关操作创建后回读校验配置与上下文文件一律 gitignore异常时保留仓库外副本并报告 blocker。自动化校验tests/scripts/obsidian-docs.test.ts 以 30 余个用例守护上述全部安全与一致性约束CLAUDE.md 则将commit-and-quality.md定为权威提交门禁文档规则由门禁联动执行。对任何打算向 Motrix 提交代码或文档的开发者/Agent先读 CLAUDE.md 与本规则文件、再动手修改是仓库强制要求的第一步而本文给出的源码与测试路径可以让你在动手前就对每条约定的「为什么」了然于心。赞分享桌面应用网络后端【免费下载链接】MotrixA full-featured download manager.项目地址https://gitcode.com/GitHub_Trending/mo/Motrix点击查看免费下载相关推荐Obsidian i18n 文档维护指南Mintlify 双语文档的写作规范、术语表与提交前校验Obsidian i18n 文档维护指南Mintlify 双语文档的写作规范、术语表与提交前校验 本篇技术指南围绕 obsidian i18n 仓库中的文档贡AI 应用开发工具大模型app-store-screenshots 贡献实战指南双文档仓库的改动边界、验证套件与 PR 规范app store screenshots 贡献实战指南双文档仓库的改动边界、验证套件与 PR 规范 本文基于仓库根目录的 CONTRIBUTING.md hEasy-Vibe 仓库工程指南VitePress 多语言文档站的开发、协作规范与部署实战Easy Vibe 仓库工程指南VitePress 多语言文档站的开发、协作规范与部署实战 本文基于 easy vibe 仓库根目录的 AGENTS.md h教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考