Super Productivity 仓库 AI 协同开发指南架构地图、同步不变量与工程护栏【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity导读Super Productivity 是一款基于 Angular Electron Capacitor 的待办事项与时间追踪应用其仓库为 AI Agent 提供了一份专门的协作指南CLAUDE.md——它既是一张架构地图feature、op-log、pfapi、packages 的职责划分也是一套工程红线同步正确性不变量、lint 强制的编码护栏、1200 行服务上限更是一份可执行的命令手册checkFile、单元测试、Electron 测试、Playwright E2E。读完本文你将掌握这个仓库的目录结构、核心开发命令、同步系统的 11 条正确性规则与反模式清单并能以与仓库维护者一致的方式提交高质量改动。仓库地图从 feature 到 op-log 的分层架构CLAUDE.md首先给出了一份精简的仓库地图指向整个项目的代码组织方式。结合目录结构各层职责如下src/app/features/ —— 功能模块tasks、planner、project、schedule、boards 等其中tasks/是核心热路径任务组件在超长可滚动列表中每个任务渲染一次任何改动都必须经过性能双重检查见下文“项目规则”。src/app/root-store/ —— NgRx 根 storemeta/存放跨实体的 meta-reducers是实现“多实体变更 一次 meta-reducer 处理”的关键位置。src/app/op-log/ —— 操作日志同步管线capture、apply、persistence、validation是整个同步系统的核心包含持久化如 operation-log-store.service.ts与验证如 frozen-state.spec.ts。src/app/pfapi/ —— 底层持久化层model/database controllers。src/app/imex/ —— 导入/导出与同步设置 UI。src/app/core/、core-ui/、ui/ —— 核心服务与共享 UI 构建块util/ 存放纯函数工具。packages/ —— workspace 包sync-core与sync-providers共享同步逻辑、shared-schema、super-sync-server、plugin-api与plugin-dev。electron/ —— Electron 主进程测试为*.test.cjsandroid/ 与 ios/ 为 Capacitor 壳。e2e/ —— Playwright 测试套件配套的 Agent 指南见 e2e/CLAUDE.md。值得注意Electron 主进程测试必须是*.test.cjs而不能是.spec.ts因为 electron/tsconfig.electron.json 排除了*.spec.ts——一个误放在electron/下的 spec 会被静默跳过、永远不运行。产品原则构建决策的底层约束CLAUDE.md从项目宣言Deep Work, Your Way中提炼出四条影响构建决策的产品原则每个新功能都要以此权衡避免功能膨胀Avoid feature creep这是个人深度工作工具不是团队管理或报表产品。优先用最小改动解决真实问题新 UI、设置项与同步面都是永久成本先扩展现有构建块功能只有让用户“更快”而非“更忙”才允许发布。更少噪音、更深专注Less noise, more depth拒绝持续弹窗、虚荣仪表盘、连击与多巴胺循环。提醒与通知是核心功能但一切抓眼球的东西默认关闭并保持安静流畅而非摩擦。适应而非强加Adapt, dont impose人们计划、追踪、反思的方式各不相同所以新行为以构建块形式发布。优先一个冷静的默认值而非新开关只有当真实工作流确实分化时才加设置“不构建 → 冷静默认 → 可选设置”的决策链。隐私与离线优先Privacy offline first无分析、无追踪、无遥测。核心任务与时间追踪必须完全离线可用同步与在线集成是可选层优雅降级、绝不成为前置条件。开工前必读任务类型与文档映射CLAUDE.md按任务类型列出了“必需阅读”保证改动与既有约定对齐改动类型必读文档样式改动docs/styling-guide.md面向用户的功能改动docs/documentation-guide.md同步、op-log、向量时钟docs/sync-and-op-log/涉及同步状态的 Effects/reducers/批量派发docs/sync-and-op-log/contributor-sync-model.mdE2E 测试e2e/CLAUDE.md承重架构决策ARCHITECTURE-DECISIONS.md评审功能或 PRdocs/feature-review-guide.md判断同步 bug 是否真实/严重程度docs/sync-and-op-log/sync-severity-triage.md核心命令从单文件检查到全套 E2ECLAUDE.md强调一条硬性规定任何修改过的.ts或.scss文件在报告完成前必须先运行npm run checkFile filepath。完整的命令矩阵如下对应 package.json 中的 scriptsnpm run checkFile filepath # 对单个文件执行 prettier lint npm run prettier # 多文件格式化 npm run lint # 多文件 lint npm test # 全部单元测试Jasmine/Karma.spec.ts 与被测文件同目录 npm run test:file filepath # 运行单个 spec npm run test:electron # Electron 主进程测试——electron/*.test.cjs而非 .spec.ts npm run e2e # 全部 E2EPlaywright较慢 npm run e2e:file path -- --retries0 # 单条 E2E约 20s/条追加 --grep name 过滤单测 npm start # Electron 开发模式 ng serve # Web 开发模式或 npm run startFrontend npm run dist # 生产构建本机可用的所有平台补充细节npm run lint的真实构成从 package.json 可以看到npm run lint并不是单一命令而是五个阶段lint:ts——ng lint基于 eslint.config.js 的 flat configlint:scss——stylelint **/*.scss src/assets/themes/*.csslint:css-vars——node tools/check-css-vars.js校验主题 CSS 变量完整性test:lint-rules——node eslint-local-rules/run-specs.js运行仓库内置 lint 规则自身的单测每个本地规则都带同名.spec.jstest:tools与test:mac-icon—— 校验工具脚本与 macOS 图标契约。E2E 的运行策略CLAUDE.md建议SuperSync 与 WebDAV 全套 E2E 通过 GitHub Actions 手动派发E2E Tests (Scheduled)运行而不是在本地跑全套——工作流提供了专用的 WebDAV 与分片的 SuperSync 任务可选的grep输入只过滤 SuperSync 任务。本地则优先单文件运行npm run e2e:file tests/feature/test.spec.ts -- --retries0 --grep should XSuperSync 本地 E2E 通过 docker-compose 启动docker compose -f docker-compose.yaml -f docker-compose.supersync.yaml up -d supersync再配合scripts/wait-for-supersync.sh等待健康检查详见 e2e/CLAUDE.md。全部 E2E 参考同样见 e2e/CLAUDE.md其中定义了 page objectsworkViewPage、taskPage等、fixture 表、断言助手与关键规则每条测试必须以workViewPage.waitForTaskList()开头、禁止waitForTimeout()、测试间完全隔离等。项目规则编码规范与工程护栏CLAUDE.md的项目规则是改动前必须遵守的硬约束翻译UI 字符串一律通过T/TranslateService只编辑en.json绝不编辑其他语言文件见 src/assets/i18n/。隐私无分析、无追踪除非用户显式同步否则用户数据留在本地。依赖PR 不得向根项目的dependencies/devDependencies新增包优先使用平台 API、既有包或仓库内的小实现。单独插件作用域内的依赖仅在其必要且隔离时允许。Electron使用 Electron 专有 API 前必须检查IS_ELECTRON。模板纯 HTML、最小化 CSS/类节制使用 Angular Material见 docs/styling-guide.md。样式评审不得为一次性上下文需求在本地重排 Angular Material 或共享src/app/ui/组件样式包括通过.mat-*、.mdc-*、button[mat-*]覆盖按钮样式优先复用既有 inputs/classes/tokens需要新变体时应做成可复用或加入共享样式层。严格 TypeScript禁止any确属未知时用unknown。状态绝不修改 NgRx state——reducer 必须返回新对象优先使用 Signals 而非 Observables。测试新服务与状态逻辑必须配套单元测试。服务体积上限任何 service 不得超过 1200 行物理行含空行与注释由 eslint 的max-lines在**/*.service.ts上强制eslint.config.jsspec 除外。超限前按职责拆分抽取协作者、把纯逻辑移到 utils 或packages/。既有超限文件在eslint.config.js中以 warning 降级该名单只允许缩小、绝不允许增长。Agent 控制文件未经用户当前任务显式要求不得修改AGENTS.md、CLAUDE.md、.agents/**、.codex/**此类改动须与产品/代码改动隔离在独立 commit 或 PR 中并说明其对未来 Agent 行为的影响。新增事故派生规则时只保留“不变量 强制执行 issue/文档指针”叙述性内容移到docs/引用的统计数据必须标注日期measured YYYY-MM。加固需要实例支撑Hardening needs an observed instance添加护栏lint 规则分支、运行时断言、防御性检查前先在仓库中 grep 到它捕获的形状的真实出现零出现 → 记录为已知缺口。生成的允许清单只能缩小绝不因误报而扩张而是修复检查或带理由地限定禁用。它配得上存在吗Does it earn its place?新功能的第一评审问题是“它是否应该存在”而不是 diff 是否正确。新增复杂度是永久的正确且经过测试但“不配存在”的实现依然应该被拒绝——把陈述动机当作需要验证的主张而不是默认接受的上下文。代码评审权衡改动引入的长期成本——维护负担、难逆转的选择数据形状、公开/插件 API、同步格式、锁定依赖、只在规模化或跨同步客户端时暴露的陷阱——而不只是当前 diff 是否正确。任务组件是热路径任何对 src/app/features/tasks/task/task.component.* 的改动都必须复查负面性能影响——避免模板中的函数/getter 调用、额外变更检测工作、未清理的订阅——并在大型任务列表上验证。同步正确性规则一个不变量十一条铁律CLAUDE.md强调同步系统的每次改动都是高风险操作——一个隐蔽 bug 可能静默损坏或丢失跨设备用户数据且难以恢复。规则 1–3 与 6 本质上是同一个不变量一个用户意图 一个 op重放/远程 op 不得再次触发 effects。完整推导见 docs/sync-and-op-log/contributor-sync-model.md。在改动前阅读对应源码与文档获取完整推理。严重度判断与可复现起点判断同步 bug 严重度前master会发布给真实用户——Play internal track、Snapedge、supersync:latest都会从每次 push 自动发布。不要从日期或最新 tag 推断“已发布”要用git tag --contains证明。未复现的发现不等于误报。→ docs/sync-and-op-log/sync-severity-triage.md从可复现问题开始任何同步改动必须以可复现的失败为起点——针对真实数据形状fixture 或播种的 DB 状态的失败测试或脚本化 E2E 复现而不是 mock 的接缝。没有观察到的端到端失败就做的加固正是同步层堆积过度防御复杂度的原因。十一条规则详解规则 1Effects 注入LOCAL_ACTIONS绝不注入Actions。唯一例外是 op-log 捕获 effect 使用ALL_ACTIONS远程归档副作用走ArchiveOperationHandler而非ALL_ACTIONS。由 lint 规则no-actions-in-effects强制eslint-local-rules/rules/no-actions-in-effects.js该文件注释说明这是“单一同步不变量”的 Boundary 1重放与远程 op 必须永不重触发 effects。token 实现见 src/app/util/local-actions.token.tsLOCAL_ACTIONS通过filter(action !action.meta?.isRemote)过滤掉标记为远程/重放的 action 并share()ALL_ACTIONS则透传完整的Actions流仅供必须响应远程操作且内部处理isRemote的 effect 使用。规则 2优先 action 驱动的 effectselector 驱动的 effect 需要skipDuringSyncWindow()。由 lint 规则require-hydration-guard强制。规则 3多实体变更 meta-reducer而非 effect 扇出一次 reducer 处理 一个 op。实现在 src/app/root-store/meta/task-shared-meta-reducers/其中包含task-shared-crud.reducer.ts、lww-update.meta-reducer.ts、task-batch-update.reducer.ts等配套大量 spec 与 integration spec 验证重放确定性。规则 4逻辑时钟——“今天是哪天”必须路由到DateServicesrc/app/core/date/date.service.ts的getLogicalTodayDate、isToday、todayStr。纯 reducer/selector 以参数形式接收startOfNextDayDiffMs并调用isTodayWithOffset保证重放确定性。DateService.startOfNextDayDiff是private在服务边界使用getStartOfNextDayDiffMs()该访问器为只读纯工具需要以参数接收此值。底层纯函数位于 src/app/util/start-of-next-day.util.ts 与 src/app/util/is-today.util.ts并有对应.spec.ts覆盖边界如 #7645非法时间字符串会使整对参数不可信应重置为默认值。规则 5TODAY_TAGTODAY是虚拟标签——绝不加入task.tagIds成员关系来自task.dueWithTime或task.dueDay。TODAY_TAG.taskIds只存顺序。定义见 src/app/features/tag/tag.const.ts完整论证见ARCHITECTURE-DECISIONS.mdDecision #2。规则 6批量派发循环——循环后必须await new Promise(r setTimeout(r, 0))否则 50 次快速派发会丢状态。详见 docs/sync-and-op-log/contributor-sync-model.md 与OperationApplierService.applyOperations()。规则 7SYNC_IMPORT/BACKUP_IMPORT替换状态并有意识地丢弃并发 op向量时钟判定为 CONCURRENT 或 LESS_THAN——这是设计而非 bug。实现在SyncImportFilterService。规则 8向量时钟——MAX_VECTOR_CLOCK_SIZE 20。服务器在冲突检测后、存储前裁剪。详见 docs/sync-and-op-log/vector-clocks.md。规则 9日志——用Log.log({ id: task.id })绝不用Log.log(task)或Log.log(title)——日志历史可导出绝不可记录用户内容。由 lint 规则no-user-content-in-logs强制eslint.config.js该规则以error级别让新泄露在引入它的 PR 上直接挂 CI。规则 10schema bump 的默认答案是“不 bump”——bump 保护不了已发布舰队、近乎不可逆、即使安全也不免费。新 op 语义必须在旧客户端上优雅降级LwwUpdatePayloadenvelope / 惰性 marker 模式。旧客户端会错误应用的改动不能仅靠 bump 发布旧客户端能容忍的改动则根本不需要 bump。见 packages/shared-schema/src/schema-version.ts当前CURRENT_SCHEMA_VERSION 4、MIN_SUPPORTED_SCHEMA_VERSION 1且刻意不设前向兼容带规范策略在 docs/sync-and-op-log/operation-log-architecture.md §A.7.11 Bump Policy。规则 11持久化模型的新 REQUIRED 字段会破坏所有既有安装——必须设为可选?并加运行时默认值。用户磁盘上已有数据缺少该字段typia 会在水合时拒绝TypeScript 只守卫新数据导致构建绿灯但每个既有安装校验失败且失败潜伏到无关 bump 把旧数据拖上迁移路径。由 src/app/op-log/validation/frozen-state.spec.ts 守护——若它失败修模型而非修 fixture。完整分析见 docs/sync-and-op-log/persisted-model-fields.md。反模式清单被禁止的写法与替代方案CLAUDE.md以表格形式给出了最常踩的反模式禁止应改为any类型恰当的类型确属未知时用unknown直接 DOM 访问Angular 绑定、viewChild()构造函数中的副作用asyncpipe 或toSignal订阅后不清理takeUntilDestroyed()或 async pipe新代码使用NgModulesstandalone components重声明 Material 主题样式复用既有主题变量一次性.mat-*、.mdc-*、button[mat-*]或共享组件覆盖可复用的 inputs、tokens 或共享样式这些反模式与上文“项目规则”中的 eslint 强制项一一对应例如no-actions-in-effects、require-hydration-guard、no-multi-entity-effect、require-entity-registry、require-text-locale、no-adapter-in-tx、require-frontier-report-on-ops-append、no-user-content-in-logs、no-console等本地规则均在 eslint.config.js 与 eslint-local-rules/rules/ 中实现其中每条规则都带自身的.spec.js单测由npm run test:lint-rules执行确保“能失败的检查确实会失败”。此外eslint.config.js 还内置了若干层边界护栏体现同样的纪律src/app/ui与src/app/core不得反向导入features/静态与动态导入双重拦截、packages/sync-core必须保持领域无关禁止导入 Angular/NgRx/app 代码、sync-providers只能使用sync-core的公开导出等——这些边界在 CI 上以零违规维持。如何利用这份指南高效贡献改动前先对号入座按上文的“任务类型 × 必读文档”表读对应文档同步相关改动必读 contributor-sync-model.md。改动中守纪律遵守严格 TS无any、不可变 NgRx state、无新增依赖、模板走构建块、服务不超过 1200 行。改动后先自检再报告对每个修改的.ts/.scss文件运行npm run checkFile为新增服务与状态逻辑补.spec.ts同步改动则以可复现失败开头并逐条对照 11 条规则。善用 CI全套 SuperSync/WebDAV E2E 通过手动派发.github/workflows/e2e-scheduled.yml运行本地只需npm run e2e:file path -- --retries0快速迭代。这份指南的本质是用“文档 lint 强制 源码组织”把同步正确性不变量固化成可执行约束让 Agent 与人类开发者共享同一套判断标准——理解它就等于理解了 Super Productivity 的工程灵魂。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
