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

• 数据同步

Self-hosted LiveSync（obsidian-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"开篇，将规范性要求划分为四个层次：

1. 改动文档、面向用户的文本或设置之前必须先阅读的参考文件；
2. 文档与面向用户文本的措辞和拼写规则；
3. 技术与架构层面的硬性约束；
4. 提交代码前必须执行的本地验证命令。

在 devs.md 中，这些规则被进一步落实为具体的工程实践，例如测试基础设施的分类（单元测试、集成测试、CLI E2E、真实 Obsidian E2E）与模块化架构的演进方向。因此，AGENTS.md 可以视为"开发者入口"，devs.md 则是其展开的工程手册。

改动前必读的五个参考文件

AGENTS.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而不是don't，写cannot而不是can't，写is not而不是isn't。
• 引号风格：正文优先使用单引号'，仅在需要时（如 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 files

AGENTS.md 明确指出两条恢复相关的核心规则：

• Fast Setup（Simple 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 将这一机制实现为带优先级的FlagFileHandler：SCRAM 挂起处理器优先级为 5，fetch-all 处理器优先级为 10，rebuild-all 处理器优先级为 20；三个处理器通过useRedFlagFeatures注册到appLifecycle.onLayoutReady事件上。可读的现代名称flag_fetch.md与flag_rebuild.md在 docs/recovery.md 的旗标参考表中与旧名称redflag3.md、redflag2.md等价：

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 中给出了这些命令的完整定义：

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 E2E（src/apps/cli/testdeno/）：宿主无关的消费方工作流，如npm run test:e2e:cli:p2p验证 P2P 场景；
• 真实 Obsidian E2E（test/e2e-obsidian/）：启动真实 Obsidian 与临时 Vault，用于启动序列、Vault 回映、RedFlag 流程、Fast Setup 等依赖 Obsidian 本身的行为，如npm run test:e2e:obsidian:two-vault-sync；
• Docker 服务：CouchDB 与 MinIO（S3），通过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 newer（SIMPLE_FETCH_STAGE1_NEWER_WINS）：按修改时间比较并取较新版本；
• Overwrite all with remote files（SIMPLE_FETCH_STAGE1_REMOTE_WINS）：远程数据为唯一事实来源；
• Use the detailed flow（SIMPLE_FETCH_STAGE1_DETAILED）：退回传统的分步设置向导。

第二阶段根据第一阶段的选择配置冲突与删除规则：remote-wins 路径下可选择是否删除本地独有文件（ExtraOnRemote.DELETE_LOCAL_MISSING），newer-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_INSTALL（Unix 用:分隔、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 与源码，参与该仓库时可遵循以下最小工作流：

1. 改动前依次阅读 docs/terms.md、docs/glossary.md、docs/settings.md、docs/troubleshooting.md 与 devs.md，确保术语与拼写一致；
2. 面向用户的文本坚持英式拼写、牛津逗号、无缩略形式，区分dialogue/dialog与plug-in/plugin；
3. 涉及远程数据库交互的功能必须伴随*.integration.spec.ts或*.integration.test.ts集成测试；涉及启动序列、Vault 回映等 Obsidian 行为的功能优先使用真实 Obsidian E2E 脚本；
4. 提交前运行npm run check与npm run test:unit，对改动边界运行聚焦测试，只启动所需 Docker 服务；
5. 功能或修复 PR 同步更新 updates.md 的## Unreleased节；
6. 涉及共享同步逻辑的改动，遵循"先改 Commonlib、验证打包产物、再更新本仓库精确依赖"的边界，不在本仓库重建源码镜像。

AGENTS.md 的独特价值在于：它把"人读的贡献规范"与"AI 助手的执行约束"合而为一，并将最重要的判断标准下放到仓库自身的术语表、恢复文档与测试基础设施中。对希望参与 Self-hosted LiveSync 开发的读者而言，这份文件既是入门地图，也是贯穿始终的行为准则。

• 数据同步