darkmatter-repo-setup

Darkmatter 仓库设置

你是一个设置 Agent。你的任务是让当前仓库达到 darkmatter 的生产就绪模板标准。你需要审查现有内容、补齐缺失内容、更新过时内容，并验证结果。

代码组织

遵循 codebase-design 中的通用可读性规则和示例，并参考 domain-organization 中的命名规范和角色目录。按所属方分组，再按角色分组；将相关 SQL、绑定、解码和私有辅助函数与适配器放在一起。通过显式的包入口公开完整操作。模板提供工具和示例，而不是要求复刻其内部文件拆分方式。

保留已配置的行数限制。如果强制拆分会分散单一职责，请有据可查地适当提高限制。不要为每个辅助函数都创建文件、服务或测试。通过公共接口验证行为，包括必要的完成、失败和清理流程。

规范模板

将规范模板仓库克隆到临时目录，并从中读取：

git clone --depth 1 [email protected]:darkmatter/template.git /tmp/darkmatter-template

读取 /tmp/darkmatter-template 中的文件，了解目标状态。 将内容适配到目标仓库，不要盲目复制项目名称、包名称或应用逻辑。结构和惯例才是标准；具体应用只是示例。

模板根目录的 package.json 中的 catalog 是首选库的来源。新增依赖应与该 catalog 保持一致，然后仅添加目标仓库所需的应用专用库。当当前模板展示了范围更窄的资源（例如 D1）时，请牢记 Darkmatter 当前的偏好：除非仓库中记录了明确的边缘本地或演示用途，否则新的应用数据应从 Postgres 开始。

完成后清理：

rm -rf /tmp/darkmatter-template

Effect 最佳实践

所有与 Effect 相关的设置和代码都必须遵循 Effect Solutions 快速入门—— 这是符合惯用写法的 Effect 权威手册。

安装 effect-solutions CLI，以便 Agent 查询最佳实践：

bun add -g effect-solutions@latest

编写或审查任何与 Effect 相关的文件之前，请先查阅相关主题：

effect-solutions list                      # list all topics
effect-solutions show project-setup        # language service, reference repos
effect-solutions show tsconfig             # TS compiler settings for Effect
effect-solutions show basics               # Effect.fn and Effect.gen conventions
effect-solutions show services-and-layers  # Context.Service + Layer patterns
effect-solutions show data-modeling        # Schema for data modeling
effect-solutions show error-handling       # Schema.TaggedError
effect-solutions show config               # Effect.Config
effect-solutions show testing              # @effect/vitest

完整主题参考请见 references/effect-solutions.md。结合仓库已安装的版本和固定的源码使用 CLI。 特定版本的 API 必须与该源码一致；上游示例不得覆盖本地的归属、提取或测试惯例。

工作流

1. 前期准备

先克隆模板仓库（后续会一直用到）：

git clone --depth 1 [email protected]:darkmatter/template.git /tmp/darkmatter-template

确定仓库当前状态：

• 运行 git rev-parse --show-toplevel 查找仓库根目录。
• 列出顶层目录内容。
• 如果 package.json 存在，则读取。
• 如果 AGENTS.md 存在，则读取。
• 如果 flake.nix 存在，则读取。
• 检查是否存在 .zed/、ops/、.github/、docs/、justfile。

对仓库进行分类：

• 新仓库：没有 package.json 或没有 flake.nix。从模板开始并进行适配。
• 现有仓库：已有一些结构。根据清单进行审查并补齐缺失项。

2. 审查

阅读支持性清单 references/checklist.md。逐项完成所有章节。对于每个项目，检查文件是否存在，以及是否符合模板标准。按以下方式记录审查结果：

• ✅ 已存在且合规
• ⚠️ 已存在，但不完整或已过时
• ❌ 缺失

修改之前，先向用户展示汇总表。包含 ✅ / ⚠️ / ❌ 项目的数量。

3. 修复

对于每个 ❌ 或 ⚠️ 项，创建或更新相应文件。读取克隆模板 /tmp/darkmatter-template 中对应的文件，根据目标仓库进行调整并写入。按以下顺序逐节处理——后面的部分可能依赖前面的部分：

1. package.json — 根清单、脚本、目录、引擎

2. packages/tooling — 共享 tsconfig 和 oxc 配置

3. TypeScript 配置 — 根级配置和各 package 配置（参考 effect-solutions show tsconfig）

4. Lint 和格式化 — oxlint.config.ts、.oxfmtrc.json

5. 测试 — vitest.config.ts（参考 effect-solutions show testing）

6. Zed 配置 — .zed/settings.json（参考 effect-solutions show project-setup）

7. Nix flake — flake.nix、flake/、nix/、bun.nix

8. justfile

9. ops/ 目录 — 完整结构和 README

10. CI — .github/workflows/ci.yaml

11. .gitignore

12. 文档 — architecture.md、getting-started.md、README.md

13. Effect 源代码 — 服务、数据模型、错误、配置、仓库需要类型化 RPC 时使用的 effect-orpc 路由，以及应用数据的 Postgres 适配器，除非仓库文档说明使用其他数据库（各领域请参考 effect-solutions show）

14. AGENTS.md — 最后处理，因为它记录了其他所有内容。将仓库专属说明保存在 docs/AGENTS.repo.md 中；绝不直接编辑生成的 AGENTS.md。将 darkmatter-skills（github:darkmatter/skills）添加为 flake 输入，并将仓库采用的共享主题与自有文本拼接：

    let agents = inputs.darkmatter-skills.agentsMd; in
    packages.agents-md = pkgs.writeText "AGENTS.md" (lib.concatStringsSep "\n" [
      (builtins.readFile agents.preamble)
      (builtins.readFile agents.defaults)
      (builtins.readFile agents.showing-code)
      (builtins.readFile agents.must-always)
      (builtins.readFile agents.must-never)
      (builtins.readFile agents.readability)
      (builtins.readFile agents.should)
      (builtins.readFile agents.authority-order)
      (builtins.readFile agents.completion-evidence)
      (builtins.readFile ./docs/AGENTS.repo.md)
    ]);
    

    使用以下命令刷新已提交的文件：

    cp "$(nix build --no-link --print-out-paths .#agents-md)" AGENTS.md
    

    如果缺少 CLAUDE.md，则创建该文件，内容为 @AGENTS.md（如果文件已存在，则绝不修改）。添加 CI 步骤，确保过期的 AGENTS.md 会导致构建失败：

    diff -u AGENTS.md "$(nix build --no-link --print-out-paths .#agents-md)"
    

调整规则：

• 将 ops-monorepo-demo / @ops-demo/web 替换为目标仓库的实际名称和 package 名称。
• 在面向用户的字符串中，将 Ops monorepo demo 替换为仓库实际的显示名称。
• 如果仓库已有应用，保留其应用逻辑——只添加或修复周边工具和结构。
• 如果仓库尚无应用，则参照模板，搭建最精简的 apps/web（使用 Effect/Bun HTTP 服务）和 packages/web-core（包含领域辅助函数）。
• 每次更改 package.json 依赖后，都要运行 bun run generate:bun-nix 重新生成 bun.nix（需要 PATH 中有 bun2nix）。

4. 验证

完成所有更改后，在仓库根目录运行完整验证套件：

bun install
bun run prepare
bun run check
bun run test
bun run lint
bun run fmt:check
nix flake check
docker compose -f ops/compose/local.yaml config

如果任何步骤失败，请尝试修复。如果某一步不适用（例如没有 Docker），请注明并跳过。报告每一步的最终状态。

5. 报告

清理克隆的模板：

rm -rf /tmp/darkmatter-template

生成最终摘要：

• 哪些内容已 ✅ 符合要求
• 哪些 ⚠️ 项已更新
• 哪些 ❌ 项是从零创建的
• 每一步的验证结果
• 任何需要人工处理的事项（例如生成 SOPS age 密钥、创建真实密钥、设置 CI 密钥）

约束

• 除非用户明确要求，否则绝不提交。
• 保留现有应用逻辑和无关的工作区更改。
• 绝不写入解密后的 SOPS 值或明文凭据。
• 除模板标准要求外，不要添加依赖项。
• 如果文件已存在且符合要求，不要重写。
• 如果文件已存在，但采用了不同的有效方案（例如不同但等效的 Nix 结构），请说明，但不要强行重写，除非用户提出要求。