agentleFS
pa001024pa001024/dna-builder/AGENTS.md

dna-builder

AGENTS.md159 starsChanged 2 days agoMITView on GitHub

Guidelines for agentic coding assistants working on the dna-builder codebase. 本文件只做*索引*:命令、约定与硬性规则留在本页,机制细节一律放独立文档,避免单文件无限膨胀。 新增说明请写进 .agents/docs/:常走到的路径登记进下表,冷路径(一次性标定 / 实施记录 / 低频子系统)只挂在下方一行,用到再读,不要往本页堆内容。 其他冷路径不列出 .agents/docs/*.md 新增文案应*一次补齐 6 种语言、每种用自己的语言书写*(别 6 个参数都填中文,模型会加漏或理解错意思); add 结束会按实际文件内容检查,缺语言时输出 ⚠ warning(只改一门译文、文件本就齐全时不会误报)。 细节见技能 .agents/skills/i18n/SKILL.md。 把图标从库里添加到Icon.vue组件库:

  • Installs packages

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No shortcuts: Never remove functions, skip processing, or use TODO placeholders instead of real code

    line 115
  2. Distinctive:

    Consistency: Check sibling files before writing to match existing patterns

    line 116
  3. Very specific:

    Always verify: Run pnpm lint and pnpm test(if modified test related files) after frontend changes / cargo check after backend changes

    line 117
  4. Very specific:

    put all temporary files in .tmp directory

    line 122
  5. Distinctive:

    Don't touch git: Never use git for test, like add, stash, commit, push, pull, merge, rebase, cherry-pick, etc.

    line 123

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Guidelines for agentic coding assistants working on the dna-builder codebase.

本文件只做索引:命令、约定与硬性规则留在本页,机制细节一律放独立文档,避免单文件无限膨胀。 新增说明请写进 .agents/docs/:常走到的路径登记进下表,冷路径(一次性标定 / 实施记录 / 低频子系统)只挂在下方一行,用到再读,不要往本页堆内容。

文档索引

主题文档
构建 / 增量 lint / SSG 预渲染 / 数据包改写(动手前必读)build-and-ssg.md
代码风格细则(Formatter / TS / Vue / Rust)code-style.md
提交规范(type / scope、正文 - 列表、拆分粒度、示例)commit-convention.md
Dev Tools(i18n / 图标 / 称号框 / 属性 i18n / 文本包 / 数据包)dev-tools.md
游戏数据 GraphQL 接口(gameData* 查询、数据集 id 口径、查询语义)game-data-api.md
RAG 检索层与向量索引(rag_search、Worker 索引、服务端索引库)rag.md
后台管理(/admin)页面的设计约定、共享配方与加页流程admin-ui.md
Agent 技能(远端 skill 的 zip 下发 / 落盘缓存 / 虚拟文件系统工具)agent-skills.md
dob-ui 组件库(daisyUI fork、db-style 覆写层、类名无前缀)dob-ui.md
深链(dobapp:// 协议注册、解析口径、中转页、平台差异)deep-link.md
桌面端自动更新(exe 差量包、feed 格式、本地测试、发布流程)updater.md
桌面分身(Windows child session、ActiveX 嵌入、投送/输入、排障与限制)desktop-clone.md
B 站动态自动发布(DeepSeek 富文本、卡片渲染、Secrets 配置)bili-dynamic.md
皮肤模型二次元渲染(卡通光照 / ramp LUT / 描边,对标游戏截图)specs/skin-toon-render.md

其他冷路径不列出 .agents/docs/*.md

  • 技能:.agents/skills/*/SKILL.md
  • Spec 文档:specs/(面向外部 agent 的协议 / 实现 spec)

Build / Lint / Test Commands

Frontend (Vue + TypeScript)

pnpm dev                              # Development server (http://localhost:1420/)
pnpm lint                             # 增量 lint:Biome + vue-tsc 只处理改动过的文件
pnpm test                             # Run all tests (vitest run)
pnpm --filter dna-builder-data test -- tests/foo.test.ts  # Run single data test file
pnpm format                           # Format with Biome

i18n(bun i18n = bun tools/i18n.ts)

# 插入/覆盖:一次补齐 6 种语言,每种用自己的语言书写
bun i18n add setting.generative_ai \
  -cn "生成式AI" -tw "生成式AI" -en "Generative AI" -jp "生成AI" -kr "생성형 AI" -fr "IA générative"

bun i18n get <key> [--lang cn,en]          # 读取各语言的值(默认全部 6 种)
bun i18n rm <key>                          # 删除某键(所有语言)
bun i18n export/import                     # 导出/导入缺失翻译(tools/i18n-diff.json)
bun i18n check [--json] [--locale-gap]     # 扫描代码引用但翻译文件缺失的键

新增文案应一次补齐 6 种语言、每种用自己的语言书写(别 6 个参数都填中文,模型会加漏或理解错意思); add 结束会按实际文件内容检查,缺语言时输出 ⚠ warning(只改一门译文、文件本就齐全时不会误报)。

细节见技能 .agents/skills/i18n/SKILL.md。

Icon Tool(bun icon = bun tools/icon-tool.ts)

把图标从库里添加到Icon.vue组件库:

bun icon add <icon-name>

Server (Bun + Elysia)

pnpm install                              # Workspace 根目录安装全部依赖(含 apps/server,运行时仍用 Bun)
cd apps/server && bun run dev         # Start dev server (port 8887)
bun run gen                      # Generate database migrations

Project Structure

apps/
├── web/               # 前端应用(Vue):src/(components/store/views/api/utils/shared…)、
│                      # public/、mock/、index.html、vite/vitest 配置与 src-tauri 桌面壳
├── server/            # Bun + Elysia backend(bun 独立安装,不在 pnpm workspace 内)
└── dob-bot/           # GitHub App bot(bun 独立安装)
packages/
├── data/              # dna-builder-data:游戏数据模型与计算(原 src/data)
├── dna-api/           # BBS API 客户端(原 externals/dna-api,workspace 包)
├── graphql-mobius/    # GraphQL 类型安全客户端(原 externals/graphql-mobius)
└── dob-script/        # dob-script CLI 的 npm 包装
tools/                # 仓库级 Dev tools(i18n.ts、icon-tool.ts、data-pack.ts…),cwd 无关
crates/               # Rust crates(buildhub-core 解释器+wasm ABI、buildhub-aot 编译器+运行库、
                      # hpatchz-wasm、mcp_server、dob-script-runtime)

Key Technologies

  • Frontend: Vue 3, TypeScript, Tailwind CSS v4, daisyUI v5, reka-ui
  • State: Pinia v3
  • Routing: Vue Router
  • i18n: i18next
  • Desktop: Tauri 2 (Rust + WebView2)
  • Server: Bun + Elysia + Drizzle ORM + GraphQL (graphql-yoga)
  • Testing: Vitest
  • Build: Vite v7
  • Linting/Formatting: Biome

Important Rules

<system_rules>

  1. DO NOT RUN pnpm dev or pnpm build — view http://localhost:1420/ directly in browser
  2. COMMENTS: Limit the amount of comments you put in the code to astrict minimum. You should almost never add comments,except sometimes on non-trivial code, or for complex function (>100 lines) (Chinese JSDoc format). 1-3 line summary.
  3. No shortcuts: Never remove functions, skip processing, or use TODO placeholders instead of real code
  4. Consistency: Check sibling files before writing to match existing patterns
  5. Always verify: Run pnpm lint and pnpm test(if modified test related files) after frontend changes / cargo check after backend changes
  6. Git workflow: For complex tasks, git add to staging first so you can git checkout to revert mistakes
  7. Prefer native APIs over adding new library dependencies
  8. Use bun -e "code" for inline code execution
  9. Sensitive operations, such as generating migrations via bun run gen, must be confirmed by the user.
  10. put all temporary files in .tmp directory
  11. Don't touch git: Never use git for test, like add, stash, commit, push, pull, merge, rebase, cherry-pick, etc.
  12. 工作文档(任务书、调研报告、基准图等过程产物)放 .docs/(已被 gitignore,不入库);.agents/docs/ 只放稳定的项目文档
  13. JavaScript expression in vue template must be single line

</system_rules>

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.