daisyUI 仓库 Agent 工作区规则Bun Monorepo 结构、包职责划分与 AI Agent 开发命令指南【免费下载链接】daisyui The most popular, free and open-source Tailwind CSS component library项目地址: https://gitcode.com/GitHub_Trending/da/daisyui本文以 daisyUI 仓库中的 packages/AGENTS.md 为主体完整解读这套面向 AI 编码代理Agent的工作区约定它如何定义 Bun Workspaces 单仓结构、五个包的职责与读写边界、七条核心命令的真实落地脚本以及针对 Agent 输出的沟通规则帮助你在参与 daisyUI 仓库开发时快速建立正确的工作方式与命令使用习惯。一、文档定位为什么 daisyUI 单仓需要一份 Agent 契约daisyUI 的官方仓库是一个包含主包、文档站、生成产物、试验场等多个子项目的 monorepo。对于人类开发者来说仓库结构可以通过浏览目录自行摸索但对于 AI 编码代理而言哪些目录可以读写、用什么运行时、命令该在哪个目录执行这些约束如果不显式声明极易导致 Agent 去修改生成产物、在错误的目录执行命令或者引入未经批准的依赖。packages/AGENTS.md 就是为解决这类问题而写的 Agent 行为契约全文分三部分Workspace Rules工作区规则声明仓库是 Bun Workspaces 管理的 monorepo且每个包各自拥有packages目录下的独立文件夹Our Stack技术栈声明运行时、模块系统、版本策略与依赖纪律Communication Rules沟通规则约束 Agent 的回答与输出方式。值得注意的是daisyUI 仓库根目录还有一份 plugin.json它把 daisyUI 声明为 Official daisyUI component library skill for building Tailwind CSS interfaces说明让 AI 工具理解并遵循本仓库约定是这个项目工程化的组成部分而 packages/AGENTS.md 正是其中面向仓库开发场景的规则文件。二、工作区规则Bun Workspaces 单仓与包边界AGENTS.md 的 Workspace Rules 部分给出两条基本规则本项目是一个由Bun Workspaces管理的 monorepo每个包在packages目录下拥有自己独立的文件夹。这两条规则可以直接在仓库根目录的 package.json 中得到验证{ name: daisyui-monorepo, private: true, packageManager: bun1.4.0, workspaces: [ packages/* ] }packageManager: bun1.4.0锁定了 Bun 版本配合packageManager字段corepack 风格约定保证所有协作者与 Agent 使用同一运行时版本workspaces: [packages/*]声明了工作区通配符即packages下的每个目录都是工作区成员。文档站与试验场正是通过这种机制引用尚未发布的主包——例如 packages/docs/package.json 与 packages/playground/package.json 中都有daisyui: workspace:*表示依赖本地工作区内的 daisyUI 源码而非 npm 上的发布版本。由此可以推断在本仓库中开发时所有跨包引用都应走workspace:*协议而不是把外部版本号钉死这样主包的 CSS 改动才能即时反映到文档站与 playground 中。三、技术栈约定Bun、ESM 与依赖纪律AGENTS.md 的 Our Stack 部分明确列出五条技术栈规则规则含义仓库中的对应证据使用 Bun.js 作为运行时与包管理器构建、测试、脚本执行统一走bun而非 Node npm/yarn根目录 package.json 的packageManager: bun1.4.0脚本中大量bun run --bun、bunx用法使用 JavaScript ESM代码以 ES Module 编写各包package.json均声明type: module如 packages/daisyui/package.json、packages/docs/package.json所有包、语言、库使用最新稳定版保持依赖处于 latest stable 状态根目录 devDependencies 钉定了tailwindcss 4.3.3、prettier 3.9.6、lightningcss 1.33.0等当前稳定版本并提供update:tw脚本一键升级 Tailwind 全家桶monorepo 由 Bun Workspaces 管理见上一节同上未经询问不得新增任何包或依赖依赖变更必须先征求同意这是一条流程纪律用于防止 Agent 顺手bun add引入无用依赖对 AI Agent 而言最后一条尤其关键它把是否允许改依赖从一个开放问题变成了明确的禁止项。结合根目录脚本可以看出日常开发所需的工具Prettier、OXLint 等是通过bunx -y按需拉取运行的例如格式化命令bunx -y prettier packages/{daisyui,docs}/{src,functions}/**/*.{css,js,json,svelte} --write也就是说工具链尽量即用即取、不落依赖与不轻易加包的纪律是自洽的。四、包职责划分五个目录与各自的读写边界AGENTS.md 在 Packages 小节逐一声明了五个包的定位其中两个目录被明确标记为禁止读写1. packages/daisyui主包daisyUI 本体。从 packages/daisyui/package.json 可以看到它是唯一面向 npm 发布的包版本5.7.27描述为 daisyUI 5 - The Tailwind CSS Component LibraryMIT 协议入口为./index.jsbrowser字段指向./daisyui.cssexports除了主入口外还暴露了./theme、./theme/object、./functions/themeOrder、./functions/variables等子路径供使用方按需引入主题与工具函数files字段列出了发布产物base、colors、components、utilities、theme目录以及daisyui.css、themes.css、chunks.css等并显式排除components/*/class.json。其 Tailwind 插件入口在 packages/daisyui/index.js通过plugin.withOptions注册接收include/exclude/prefix选项再分别遍历base、components、utilities三组样式注入器。这里的plugin是本地实现见 packages/daisyui/functions/plugin.js它把withOptions包装成一个带__isOptionsFunction标记的选项函数返回{ handler, config }供 Tailwind 消费。理解这一调用链有助于在修改主包 CSS 或插件逻辑时判断影响面。2. packages/docsSvelteKit 文档站daisyUI 官网。packages/docs/package.json 显示其技术栈为sveltejs/kit 2.70.1svelte 5.56.8vite 8.1.5依赖mdsvex渲染 Markdown 文档、theme-change处理主题切换且要求node 20.18.1。开发服务器固定监听3000端口vite dev --port 3000 --open这与 AGENTS.md 中 bun run dev在http://localhost:3000启动文档站 的说明完全对应。3. packages/bundle生成产物目录禁止读写AGENTS.md 明确写着 This directory contains generated bundle files. Do not read nor write code here.。该目录下现有的 packages/bundle/daisyui.js、daisyui.mjs、daisyui-theme.js、daisyui-theme.mjs等文件均由构建流水线生成。从根目录脚本bundle: bun packages/daisyui/functions/bundle.js与 packages/daisyui/package.json 中commit-and-tag-version的postbump钩子bun run --bun build bun run --bun bundle git add --all packages/bundle/可以看出每次版本号提升后会自动重建 bundle 并提交产物。因此修改这个目录下的文件没有意义——它们会在下一次发布构建中被覆盖Agent 应当把精力放在packages/daisyui的源文件上。4. packages/logs性能日志目录禁止读写同样标注为 generated log files for performance analysis. Do not read nor write code here。根目录提供了对应的消费脚本logs: bun run --bun build:dev cd packages/logs bunx browser-sync start -s --files .即先以开发模式构建 daisyUI再用 browser-sync 监听 logs 目录做性能日志的实时分析。这类目录是构建副产物不应成为代码修改对象。5. packages/playground组件试验场AGENTS.md 称其为 an Astro project used for testing and experimenting with daisyUI components. It is not part of the main application. 需要指出的是从源码看当前 playground 的实际工具链是Vite而非 Astropackages/playground/package.json 声明dev: bun dev.js、build: vite build、preview: vite previewdevDependencies 为daisyui: workspace:*与vite 8.1.5packages/playground/vite.config.js 配置了多页构建递归扫描src/pages下所有index.html生成路由/、/dark/、/light/、/ltr/、/rtl/、/prefix/等并注册了tailwindcss()tailwindcss/vite插件与一个static-html插件后者负责把!-- include path --注释替换为组件源码、把!-- pages --替换为页面导航Tailwind 入口 packages/playground/tailwind.css 只有四行import tailwindcss、两个source含src/components/Component.html以及plugin daisyui。这意味着 playground 的定位与文档一致——它不是主应用的一部分只是用来快速试验 daisyUI 组件的独立小工程但其框架描述Astro与实际实现Vite存在出入按源码现状以 Vite 为准即可。playground 还有一个值得留意的热更新机制见 packages/playground/dev.js它递归监听../daisyui/src目录下的.css变更防抖 100ms 后调用build-daisyui.js重建对应源文件然后杀掉并重启 Vite 进程再刷新。源码注释解释了原因Tailwind caches daisyUIs generated modules, so CSS edits need a fresh Vite process. 这解释了为什么在本仓库中直接改packages/daisyui/src下的 CSS 能在 playground 里实时看到效果。五、命令体系七条核心命令与实际脚本实现AGENTS.md 要求所有命令从仓库根目录执行。以下把它列出的七条命令与 package.json 中的真实脚本逐一对应AGENTS.md 命令根目录脚本实际内容作用说明bun run devbun run --bun build:dev cd packages/docs bun run --bun dev先以开发模式构建 daisyUI 包再在文档站启动开发服务器访问http://localhost:3000bun run buildcd packages/daisyui bun run --bun build内部为bun build.js构建 daisyUI 主包产物bun run build:docsbun run --bun build cd packages/docs bun run --bun build先正式构建 daisyUI再生产构建文档站NODE_ENVproduction vite buildbun run formatbunx -y prettier packages/{daisyui,docs}/{src,functions}/**/*.{css,js,json,svelte} --write用 Prettier 格式化全部仓库文件实际覆盖 daisyui 与 docs 两个包的src/functions下 css/js/json/svelte 文件bun run lintbunx -y oxlintlatest --ignore-pattern packages/playground用 OXLint 对全仓做静态检查并显式忽略 playgroundbun run testbun test --parallel4用 Bun 内置测试运行器以 4 并行度跑所有包的测试bun run dev:localapibunx -y concurrently -k bun run api PUBLIC_DAISYUI_API_PATHhttp://localhost:4000/docs bun run dev用 concurrently 同时启动本地 API 服务cd ../daisyui-api bun run dev与文档站并通过PUBLIC_DAISYUI_API_PATH环境变量把文档站指向本地 APIhttp://localhost:4000/docs几个实现层面的细节值得注意bun run --bun前缀根脚本几乎全部使用bun run --bun script形式即让子脚本由 Bun 原生执行而非退回 Node这是 Bun 提供的加速机制也再次印证整个仓库以 Bun 为第一运行时的约定。build:docs隐含构建顺序依赖文档站消费的是workspace:*的 daisyUI所以必须先build主包再构建文档站dev命令同理采用build:dev开发模式产物保留可调试性先行构建的顺序。dev:localapi的适用范围api脚本执行cd ../daisyui-api bun run dev即依赖仓库同级目录下存在独立的daisyui-api仓库若本地没有该仓库此命令无法完整工作。检查组合命令AGENTS.md 之外根目录还定义了check: bun run --parallel lint test lang:validate可以理解为lint test 翻译校验的一键组合适合在提交前作为完整的本地验证手段。翻译工具链与文档站的多语言目录 packages/docs/src/translation 配套根目录提供lang:add/lang:prune/lang:report/lang:validate四个脚本底层是 packages/docs/src/lib/scripts 下的addTranslations.js、pruneTranslations.js、reportTranslations.js、validateTranslations.js。这解释了check中lang:validate的来源仓库对多语言词条一致性有强制校验。六、沟通规则对 Agent 输出的六条约束AGENTS.md 的 Communication Rules 部分针对 AI 代理的回答行为给出六条规则Do not explain things unless asked——不主动解释除非被要求Do not confirm nor deny anything unless you are 100% sure——不是百分之百确定时既不要确认也不要否认某个说法Always fact check your answers——回答必须经过事实核查If you are unsure about something, say I dont know——不确定就直说我不知道Do not write intros like I will help you with this——不要写我来帮你解决这个问题之类的开场白直接执行任务Do not write conclusions or summaries unless asked——未被要求时不写结论或总结。这六条规则的共同目标是降低 Agent 输出中的冗余与幻觉风险前两条把确定性变成硬性门槛第三条要求以仓库事实为准例如前文发现的 playground Astro vs Vite 描述差异按此规则就应如实指出而非掩盖后三条则约束输出格式让 Agent 的回复聚焦于任务本身。对以人类身份参与协作的开发者这套规则同样适用在 daisyUI 仓库的讨论中未经验证的断言与不必要的铺垫都是被明确不欢迎的。七、实操建议如何按 AGENTS.md 在仓库中工作结合本文梳理的规则一次典型的 daisyUI 仓库开发流程应当是确认改动落点改组件样式/主题/工具类 → 只动 packages/daisyui/srcbase、components、themes、utilities子目录改文档 → 动 packages/docs严禁触碰packages/bundle与packages/logs这两个生成产物目录不新增依赖需要新工具时优先考虑bunx按需运行确需落依赖则必须先征求维护者同意从仓库根目录执行命令日常开发用bun run dev构建主包 3000 端口文档站生产验证用bun run build与bun run build:docs提交前跑bun run format、bun run lint、bun run test或直接bun run check一键完成 lint、test、翻译校验快速试验组件启动 playgroundbun run play即先build:dev再进 playground 跑dev.js在src/components/Component.html里写组件片段即可热更新预览Component.html不存在时predev脚本会自动生成一个含button classbtnHello/button的默认文件保持输出克制遵循 Communication Rules结论必须能从源码、配置或测试中找到依据不确定就明说。八、小结packages/AGENTS.md 虽然篇幅不长却把 daisyUI 仓库的协作契约压缩成了三个可执行层面结构层面用 Bun Workspaces 划分包边界并圈出两个只读生成目录工具层面固定了 Bun ESM 最新稳定版的栈并把七条命令与根目录 package.json 脚本一一对齐行为层面用六条沟通规则约束 Agent 的输出质量。理解并遵守这份文档是稳定参与 daisyUI 单仓开发尤其是以 AI 代理方式开发的前提。【免费下载链接】daisyui The most popular, free and open-source Tailwind CSS component library项目地址: https://gitcode.com/GitHub_Trending/da/daisyui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考