DiAL/docs/development/README.md

开发文档

本文档是 DiAL 的开发入口。AI 工具和开发者应先阅读 ../README.md 判断文档归属，再阅读本文和最小必要专题。

适用场景：修改源码、测试、构建脚本、开发流程、架构边界、checker 开发机制或项目工程规则。

专题索引

文档	内容
architecture.md	项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界
backend.md	后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型
frontend.md	React、TDesign、TanStack Query、组件、样式和前端测试规范
checker.md	新增或修改 checker 的实现机制、测试要求、文档同步和 checklist
release.md	开发服务、前后端集成、构建、Docker、release、脚本、环境变量
../README.md	文档路由、文档归属矩阵、development/user 文档更新规则

常用命令

命令	说明
bun install	安装依赖
bun run dev probes.yaml	启动双进程开发环境
bun run dev:server probes.yaml	仅启动后端 API server
bun run dev:web	仅启动 Vite dev server
bun run schema	生成 probe-config.schema.json
bun run schema:check	检查导出 schema 是否同步
bun run typecheck	TypeScript 类型检查
bun run lint	ESLint 和 Prettier 格式检查
bun run format	Prettier 自动格式化
bun test	运行全部测试
bun run check	schema:check + typecheck + lint + test
bun run build	构建生产可执行文件
bun run verify	check + build 完整验证
bun run release	跨平台发布打包
bun run clean	清理构建缓存与产物

质量门禁

代码变更必须按影响范围执行验证。

变更类型	必跑命令
常规代码变更	bun run check
构建、部署、发布、前后端集成变更	bun run verify
配置 schema 变化	bun run schema、bun run schema:check、bun run check
checker 新增或修改	bun run schema、bun run schema:check、bun run check
仅文档变更	检查链接、索引和文档归属一致性

正式提交或影响构建产物时优先运行 bun run verify。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。

全局工程规则

• 使用中文编写注释、文档和项目内交流内容。
• 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
• 运行工具使用 bunx，禁止使用 npx、pnpx。
• 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
• 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
• 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、styles.css CSS 类，最后才自行开发组件。
• 前端禁止组件内联 style、覆盖 TDesign 内部类名、使用 !important、硬编码色值。
• 当前项目未上线，不需要为旧行为做向前兼容，除非用户明确要求。

包管理、依赖与提交

• 仅使用 bun 安装依赖和运行项目脚本，锁文件为 bun.lock。
• 新增依赖前先确认 Bun 内置 API、es-toolkit、标准 Web API、现有三方库和项目公共工具是否已满足需求。
• Git 提交信息使用中文，格式为 类型: 简短描述。
• 提交类型限定为 feat、fix、refactor、docs、style、test、chore。
• 多行提交描述时，标题和正文之间空一行。

目录边界

目录	约定
src/server/	Bun 后端代码，不能 import src/web/，HTML import 集成除外
src/web/	React Dashboard，不能 import src/server/ 运行时实现
src/shared/	前后端共享 TypeScript 类型
scripts/	独立运行脚本，可 import 项目源码
tests/	测试目录，结构镜像 src/
docs/user/	用户使用、配置、部署、checker 和排障文档
docs/development/	架构、后端、前端、发布和 checker 开发文档
openspec/	OpenSpec 变更管理与规格文档

文档影响分析

每次代码变更都必须执行文档影响分析。

如果变更影响	更新
用户可见行为、配置、checker、expect、部署、状态模型	docs/user/ 对应文档
开发流程、架构、测试、构建发布、checker 开发机制	docs/development/ 对应文档
项目定位、快速开始、核心能力列表、文档导航	README.md
文档同步规则或文档归属矩阵	docs/README.md 和 openspec/config.yaml

如果无需更新文档，必须在收尾说明中说明原因。详细规则见 文档总览。

OpenSpec 协作规则

• 本项目 OpenSpec 使用 fast-drive schema，变更文档只包含 design.md 和 tasks.md，不创建 proposal.md 或 specs/*.md。
• design.md 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。
• tasks.md 必须从 design.md 派生，一行一个 checkbox 任务。
• 实现阶段按 tasks.md 顺序执行，完成后立即标记任务状态。

事实来源

主题	事实来源
代码结构和实现	src/、scripts/、tests/
配置 schema	TypeBox fragments、probe-config.schema.json、schema 测试
项目全局规则	openspec/config.yaml、本文档、本目录专题文档
checker 流程	checker.md

更新触发条件

修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。