开发者指南
从功能分支开始，安装锁定依赖及两个浏览器修订版，构建并运行完整 Jest。扩展现有契约的归属模块，让文档、provider 测试和原生应用证据随行为变化同步。
准备工作副本
克隆仓库，阅读 AGENTS.md，创建功能分支。插件 CI 在 Linux／Windows 使用 Node 20；网站使用 Node 24，在仓库根目录和 website/ 分别安装依赖。
在仓库根目录执行：
npm ci
npx --no-install playwright install --with-deps chromium
node node_modules/playwright-chromium/cli.js install chromium
npm run build
npm test -- --runInBand
两个 Playwright 包可能锁定不同 Chromium，干净环境只安装一个不够。main.js 是被 Git 忽略的构建产物，旧 bundle 不能证明新提交。
修改前确认归属
| 职责 | 主要源码 |
|---|---|
| 插件生命周期、命令与宿主路由 | src/main.ts |
| Provider 预设、协议元数据与校验 | src/llmProviders.ts |
| 请求构造、传输、重试与流式响应 | src/llmUtils.ts |
| Operation 定义、schema 与公开 CLI 选择 | src/operations/, src/cliContracts.ts |
| 文件任务、研究与翻译 | src/fileUtils.ts, src/searchUtils.ts, src/translate.ts |
| 工作流动作与侧栏组合 | src/workflowButtons.ts, src/ui/NotemdSidebarView.ts |
| 图表规格与渲染 | src/diagram/, src/rendering/ |
| UI 字符串与支持语言 | src/i18n/ |
| 公开指南与译文 | website/docs/, website/i18n/ |
| 维护者手册与带日期证据 | docs/maintainer/ |
生产 bundle 自包含，包含内联预览宿主。候选独立 render-host 路径不是已发布资产契约；启用前须同步包装、发布资产、审计和文档。
实现有边界的改动
- 行为变更前复现问题，添加聚焦的失败测试。
- 修改不变量归属模块，在外部边界校验，避免各调用者复制 provider／operation 知识。
- 重跑聚焦及完整测试；写文件任务应覆盖取消、错误和持久化。
- 更新英文源指南与受影响语言；计划、任务和 walkthrough 在
docs/保留完整分离的中英文版本。 - 视觉／原生导出改动应在目标应用检查；XML、截图或构建通过不能单独证明可编辑性或连接线附着。
新增 provider 时修改 llmProviders.ts，兼容时复用传输，更新 llmProviders.test.ts、llmUtilsProviderSupport.test.ts、README 和连接测试，保留流式及中断响应处理。
Operation 暴露前定义输入／结果 schema、上下文、副作用和 handling tag。注册不自动形成公开 Agent 端点，见 Agent 指南。
验证改动
npm run build
npm test -- --runInBand
npm run audit:i18n-ui
npm run audit:render-host
npm run lint:regressions -- --base-ref origin/main
git diff --check
Lint 门禁比较具体诊断。既有债务不能成为新增错误的理由，总数下降也不能掩盖新回归。本地检索改动按需运行 npm run benchmark:local-kb，报告语料和环境，不作普遍速度承诺。
网站使用 Node 24：
npm --prefix website ci
npm --prefix website run build
npm --prefix website run audit:build
npm run docs:build
1.9.9 文档由 Codex 直接撰写并审核译文。不要运行旧翻译写入脚本，也不要调用 LM Studio／翻译端点准备文案。工具只用于排版、校验和渲染已写文本。
在 Obsidian 与原生应用中测试
使用可丢弃 Vault。仓库宿主验证脚本要求 .notemd-host-verification 标记并核对复制的 bundle，避免真实用户 Vault。CLI 集成须尝试 obsidian help 与 obsidian-cli help，如实记录缺失工具，不把命令桩当宿主验证。
原生 PowerPoint、CircuitikZ 与幻灯片导出各有依赖和证据。遵循可靠性验收记录和发布手册，保留移动端与最低版本未验证声明。
贡献与发布
PR 写明具体问题、最终行为、测试和限制。Issues 接收可复现报告，不提交凭据、私密 Vault 或无关生成文件。
发布由仓库 publisher 与手册负责：同步版本、数字 tag、干净 tag 源码、双语说明、验证草稿资产，再公开并显式部署 Pages。不可移动已发布 tag 替换二进制。.trellis/ 是本地状态，不能成为 CI 依赖。