obsidian-livesync 仓库的 AI 编码助手规范：读懂 AGENTS.md 中的协作、风格与发布纪律

数据同步【免费下载链接】obsidian-livesync项目地址https://gitcode.com/gh_mirrors/ob/obsidian-livesync点击查看免费下载Self-hosted LiveSyncobsidian-livesync是一个用于跨设备同步 Obsidian 库的插件代码库采用 TypeScript、Svelte 与 PouchDB 的模块化架构。仓库根目录下的 AGENTS.md 是一份面向 AI 编码助手与人类贡献者的协作规范文件规定了在撰写代码、注释、文档与提交信息时必须遵守的一致性准则。阅读本文后你将掌握该仓库的必读参考资料、文档措辞约定、核心架构约束、本地验证命令以及版本发布纪律能够以符合项目预期的方式参与开发与审查。AGENTS.md 的定位与工作方式AGENTS.md 本身是仓库对自动编码代理的行为约束说明。它以When working on this repository (writing code, comments, documentation, or commits), you MUST follow these guidelines开篇将规范性要求划分为四个层次改动文档、面向用户的文本或设置之前必须先阅读的参考文件文档与面向用户文本的措辞和拼写规则技术与架构层面的硬性约束提交代码前必须执行的本地验证命令。在 devs.md 中这些规则被进一步落实为具体的工程实践例如测试基础设施的分类单元测试、集成测试、CLI E2E、真实 Obsidian E2E与模块化架构的演进方向。因此AGENTS.md 可以视为开发者入口devs.md 则是其展开的工程手册。改动前必读的五个参考文件AGENTS.md 要求在任何改动开始之前按顺序阅读以下文件路径均已转换为仓库根目录相对路径参考文件提供的信息docs/terms.md文档风格与词汇约定英式拼写、标点、术语docs/glossary.md面向用户、运维、开发与设计术语的稳定定义docs/settings.md 与 docs/settings_ja.mdUI 设置项及其设置键的映射关系docs/troubleshooting.md故障排查指南与常见恢复步骤flag files、SCRAM 状态等devs.md开发工作流、模块架构与测试基础设施其中 docs/glossary.md 值得特别留意它记录了诸如Chunk存储于数据库或对象存储中用于高效同步的数据分片、Metadata存储文件属性、大小、路径并引用 Chunks 的文档、Fast Setup (Simple Fetch)、Flag files、Scram Switches、Setup URI等项目的专属含义是阅读代码与撰写文档时避免概念混淆的基础。术语表还区分了面向用户与运维的术语和开发者与设计术语两类后者如 Active publication、Admission、Replicator provider definition可能不会出现在 UI 中但用于架构文档与代码评审。文档与面向用户文本的措辞规则AGENTS.md 对文档和用户可见文本提出了严格的风格约束这些规则在 docs/terms.md 中有完整的披露与维护说明英式拼写British English全部文档与用户消息使用英式英语倾向使用-ise与-isation后缀而非-ize与-ization例如initialisation、synchronisation、organisation如有疑问可以参考 BBC News Styleguide。牛津逗号Oxford Comma三个及以上项目的列表使用序列逗号例如写settings, snippets, and themes而非settings, snippets and themes。逻辑标点Logical Punctuation标点符号放在引号外除非它本身属于被引用的文本例如写dialogue而不是dialogue,。不使用缩略形式正文中写do not而不是dont写cannot而不是cant写is not而不是isnt。引号风格正文优先使用单引号仅在需要时如 JSON 代码块内使用双引号。术语拼写面向用户文本与一般文档使用dialogue仅在源码类名、方法名中使用dialog面向用户文本使用带连字符的plug-in仅在代码文件、配置设置或技术语境中使用plugin。回复语言始终以用户提问所用的语言回复用户。此外docs/terms.md 补充了一条重要惯例HTML、CSS、JavaScript 等领域的惯用术语与所用技术语言保持一致如color而非colour且尽量使用肯定形式如Discard而非Do not keep。技术与架构层面的硬性约束数据库结构Metadata 与 Chunks 分离Self-hosted LiveSync 将文件拆分为Metadata文件属性、大小、路径与Chunks实际内容两类文档禁止将原始内容直接存入 metadata 文档。这一设计在 docs/glossary.md 的 Chunk / Chunks 与 Metadata 词条中得到印证并在 devs.md 的 Database Operations 一节进一步说明EntryDoc覆盖文件 Metadata、Chunks、数据库版本信息、Milestone 信息、Node 信息与 Chunk Packs。理解这一分离是排查size mismatch大小不匹配类问题的前提——它描述的正是文件 Metadata 与 Chunks 中存储的内容不一致的状态。设置与恢复Fast Setup 与 Flag filesAGENTS.md 明确指出两条恢复相关的核心规则Fast SetupSimple Fetch是次要设备初始复制的首选流程。它利用基于流的复制获得更高速度并延迟本地文件回映delayed local file reflection以抑制临时性同步警告。详细流程见 docs/tips/fast-setup.md。Flag files如redflag.md、redflag2.md、redflag3.md位于 Vault 根目录用于控制启动序列并触发自动化的 fetch/rebuild 任务。源码层面src/serviceFeatures/redFlag.ts 将这一机制实现为带优先级的FlagFileHandlerSCRAM 挂起处理器优先级为 5fetch-all 处理器优先级为 10rebuild-all 处理器优先级为 20三个处理器通过useRedFlagFeatures注册到appLifecycle.onLayoutReady事件上。可读的现代名称flag_fetch.md与flag_rebuild.md在 docs/recovery.md 的旗标参考表中与旧名称redflag3.md、redflag2.md等价Vault 根目录下的文件效果redflag.md挂起普通 LiveSync 工作以便诊断需手动移除flag_fetch.md或redflag3.md预约从所选远程执行Reset Synchronisation on This Deviceflag_rebuild.md或redflag2.md预约Overwrite Server Data with This Devices Files无中心远程时执行本地 P2P 准备Flag files 本身被排除在同步之外fetch 与 rebuild 旗标会在调度工作流完成或安全取消后移除而失败 Fast Setup 会保留 fetch 旗标以便后续启动重试。恢复流程的完整说明见 docs/recovery.md。子仓库livesync-commonlib 是外部权威包AGENTS.md 要求将vrtmrz/livesync-commonlib视为外部权威包修改应在该包的仓库中进行验证打包产物与下游 LiveSync 消费方再在本仓库更新精确依赖版本禁止在本仓库重建src/lib源码镜像或生成_types回退。从 package.json 可以看到它作为精确版本依赖被锁定vrtmrz/livesync-commonlib: 0.1.23而 devs.md 进一步说明共享同步代码由该包编译与类型化本仓库不编译 Commonlib 源码也不提交回退声明。应用目录划分src/apps 目录包含相互独立的应用模块cli命令行界面应用其单元测试与端到端测试在 src/apps/cli 内通过本地的package.json脚本运行webapp基于 Web 的应用webpeer基于 Web 的对等实用工具。在 package.json 的 workspaces 字段中可以看到这三个目录被声明为 npm workspaces同时vrtmrz/livesync-commonlib的代码被cli、webapp、webpeer及外部工具共享是平台无关同步逻辑的载体。提交前的验证命令AGENTS.md 要求提交代码前在本地运行验证脚本package.json 中给出了这些命令的完整定义命令作用npm run check综合代码验证依次执行类型检查tsc-check、tsc-check:apps、ESLintlint、lint:community、lint:community:tools、Svelte 检查svelte-check与兼容性检查check:compatibilitynpm run test:unit使用 Vitest 运行快速本地单元测试npm run test:unit:coverage需要单元测试覆盖率时使用npm run build编译生产 bundlemain.jsnpm run dev开发模式下的监听/自动重建任务AGENTS.md 特别提醒应针对所改动边界运行聚焦的集成测试、CLI E2E 或真实 Obsidian E2E 命令并且只启动该命令所需的 Docker 服务。在 devs.md 中可以看到测试基础设施的全貌单元测试*.unit.spec.ts运行于 Node.js与实现文件同目录放置通过npm run test:unit执行集成测试*.integration.spec.ts/*.integration.test.ts针对真实 CouchDB 实例运行通过npm run test:integration执行凡是与远程数据库交互的新功能都强烈要求编写集成测试CLI E2Esrc/apps/cli/testdeno/宿主无关的消费方工作流如npm run test:e2e:cli:p2p验证 P2P 场景真实 Obsidian E2Etest/e2e-obsidian/启动真实 Obsidian 与临时 Vault用于启动序列、Vault 回映、RedFlag 流程、Fast Setup 等依赖 Obsidian 本身的行为如npm run test:e2e:obsidian:two-vault-syncDocker 服务CouchDB 与 MinIOS3通过npm run test:docker-all:start/stop管理。深入npm run check 的组成npm run check并非单一工具而是一条命令链见 package.json 第 26 行npm run tsc-check npm run tsc-check:apps npm run lint npm run lint:community -- --quiet npm run lint:community:tools npm run svelte-check npm run check:compatibility其中tsc-check:apps会分别对src/apps/browser、src/apps/cli、src/apps/webapp、src/apps/webpeer执行独立的 TypeScript 项目检查这呼应了 AGENTS.md 中应用目录相互独立的约束check:compatibility则调用 utils/check-compatibility.js 对构建产物进行 iOS 15 兼容性验证。从源码看 AGENTS.md 背后的实现细节Fast Setup 的两阶段决策流src/serviceFeatures/redFlag.simpleFetch.ts 将 Fast Setup 实现为两阶段对话。第一阶段选择数据处理方式Compare time and take newerSIMPLE_FETCH_STAGE1_NEWER_WINS按修改时间比较并取较新版本Overwrite all with remote filesSIMPLE_FETCH_STAGE1_REMOTE_WINS远程数据为唯一事实来源Use the detailed flowSIMPLE_FETCH_STAGE1_DETAILED退回传统的分步设置向导。第二阶段根据第一阶段的选择配置冲突与删除规则remote-wins 路径下可选择是否删除本地独有文件ExtraOnRemote.DELETE_LOCAL_MISSINGnewer-wins 路径下可选择是否删除远端已删除的本地文件ExtraOnLocal.DELETE_DB_DELETED。用户的选择会被记入simple-fetch-mode小配置setSmallConfig下次启动时直接复用。实际执行时流程调用rebuilder.$fetchLocalDBFast(false)完成快速数据库下载再调用 Commonlib 的synchroniseAllFilesBetweenDBandStorage执行全量扫描以将数据库变更回映到本地文件这与 docs/tips/fast-setup.md 中 Step 3 的描述完全对应。构建期的平台文件替换AGENTS.md 与 devs.md 提到的文件命名约定——.platform.ts后缀在生产构建中替换为.obsidian.ts、.dev.ts替换为.prod.ts——由 esbuild.config.mjs 中的moduleAliasPlugin实现第 33-71 行。该插件在生产模式下拦截带.dev或.platform的导入路径并解析到对应替代文件。同一文件还实现了PATHS_TEST_INSTALL自动复制逻辑通过.env中的PATHS_TEST_INSTALLUnix 用:分隔、Windows 用;指定测试 Vault 的插件目录后开发构建会自动把main.js、styles.css与修改过版本的manifest.json复制过去方便实时调试。国际化i18n工作流虽然 AGENTS.md 未展开但 devs.md 记录了仓库的翻译工作流先在 src/common/messagesYAML 编辑人类可读的 YAML 文件运行npm run i18n:bake将其编译为 JSON 与 TypeScript 常量再使用$msg()、$t()、$f调用翻译。支持的语言包括def英语、de、es、fr、he、ja、ko、ru、zh、zh-tw与 src/common/messages 目录下的语言文件一一对应。Commonlib 负责消息的英文权威定义LiveSync 提供多语言应用目录并注入翻译器未翻译的键回退到 Commonlib 英语。日志级别与通知归属devs.md 的 Diagnostic and notice ownership 一节对日志使用给出了清晰的边界内部操作应在LOG_LEVEL_VERBOSE记录详细诊断并以类型化结果让调用方区分 complete、partial、failed 三种结局只有掌握交互上下文的应用边界才应提升到LOG_LEVEL_NOTICE向用户展示且应描述可见后果与下一步操作而不是暴露内部阶段名。例如好的应用通知是Not all files could be synchronised. Check the affected files. Generate a report to review the detailed log.而不是Local database initialisation did not complete.。LOG_LEVEL_DEBUG仅供调试不出现在默认构建中开发模式会在.obsidian/下创建ls-debug/目录输出调试信息但这会带来显著的性能开销。贡献与发布纪律AGENTS.md 的贡献与发布部分强调了几条与代码风格同样重要的流程约束Unreleased 变更记录日常开发期间 updates.md 顶部保持## Unreleased功能或修复 PR 若影响用户应在同一 PR 内更新该节发布时替换为目标版本标题如## 0.25.81并在上方新建空的## Unreleased。仅记录用户可见变更避免罗列纯内部重构、维护杂务、生成文件变更与依赖升级除非它们影响用户嵌入插件的updates.md只保留大约最近五个已发布版本更早的版本原样归档到 docs/releases 对应发布线。预发布版本策略使用 SemVer beta 标识如1.0.0-beta.0从不可变且已评审的 tag 发布预发布不得替换最新稳定版1.0.0-rc.0保留给功能与契约冻结的首个候选版本。发布工作流维护者通过Prepare Release PR、Finalise Release Tags与Release Obsidian Plugin三个 GitHub Actions 工作流完成版本生命周期最终发布版本需经过 BRAT 验证。发布操作的完整清单见 devs.md 的 Release Cheat Sheet。依赖升级谨慎升级依赖升级后用 diff 工具检查产物确保构建输出只有预期内的变化避免意外漏洞。开源优先新功能应考虑存在 OSS 实现避免使用可能限制使用的专有服务或 API连接新型服务器的功能应要么有对应的 OSS 实现要么在受控的责任与限制下管理例如通过客户端加密、自行审计服务器来缩减监控面。对贡献者与 AI 助手的实用建议综合 AGENTS.md、devs.md 与源码参与该仓库时可遵循以下最小工作流改动前依次阅读 docs/terms.md、docs/glossary.md、docs/settings.md、docs/troubleshooting.md 与 devs.md确保术语与拼写一致面向用户的文本坚持英式拼写、牛津逗号、无缩略形式区分dialogue/dialog与plug-in/plugin涉及远程数据库交互的功能必须伴随*.integration.spec.ts或*.integration.test.ts集成测试涉及启动序列、Vault 回映等 Obsidian 行为的功能优先使用真实 Obsidian E2E 脚本提交前运行npm run check与npm run test:unit对改动边界运行聚焦测试只启动所需 Docker 服务功能或修复 PR 同步更新 updates.md 的## Unreleased节涉及共享同步逻辑的改动遵循先改 Commonlib、验证打包产物、再更新本仓库精确依赖的边界不在本仓库重建源码镜像。AGENTS.md 的独特价值在于它把人读的贡献规范与AI 助手的执行约束合而为一并将最重要的判断标准下放到仓库自身的术语表、恢复文档与测试基础设施中。对希望参与 Self-hosted LiveSync 开发的读者而言这份文件既是入门地图也是贯穿始终的行为准则。赞分享数据同步【免费下载链接】obsidian-livesync项目地址https://gitcode.com/gh_mirrors/ob/obsidian-livesync点击查看免费下载相关推荐Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束Screenpipe 仓库 AI Agent 协作开发规范全解读懂 AGENTS.md 的工程纪律与约束 导读 screenpipe 是一个本地优先的开源计AI 应用大模型本地部署AI AgentMCP 服务屏幕录制语音qm 仓库的 AGENTS.md 工程协作规范解读AI 编码时代的多智能体 Agent 项目开发纪律qm 仓库的 AGENTS.md 工程协作规范解读AI 编码时代的多智能体 Agent 项目开发纪律 本文以 qm 仓库根目录下的 AGENTS.md htt后端人工智能AI Agent前端AI 技能Zod 仓库工程协作手册从 AGENTS.md 读懂 zod 的贡献规范与 AI 编码代理工作流Zod 仓库工程协作手册从 AGENTS.md 读懂 zod 的贡献规范与 AI 编码代理工作流 本文导读 AGENTS.md 是 Zod 仓库TypeS后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考