文档	内容
architecture.md	项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界
backend.md	后端实现细节：模块 API、工具函数索引、数据访问函数清单、AI 层说明
frontend.md	前端实现细节：运行时代码结构、组件索引、页面组成、hooks/工具清单
release.md	开发服务、前后端集成、构建、脚本、环境变量
../README.md	文档路由、文档归属矩阵、文档更新规则

开发规范

以下规范是所有代码变更必须遵守的约束。AI 工具必须严格遵守，开发者 review 时以此为准。

一、全局规则

语言与环境

使用中文编写注释、文档和项目内交流内容。
仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
运行工具使用 bunx，禁止使用 npx、pnpx。
当前项目无需考虑向前兼容。

依赖引入

后端：新增依赖前必须按以下优先级检查，上层已有方案则不得引入新依赖：

优先级	来源	典型用途
1	Bun 内置 API	Bun.serve、Bun.file、Bun.YAML、Bun.spawn、bun:sqlite
2	es-toolkit	类型判断、深度比较、并发控制
3	标准 Web API	Headers、fetch、AbortController
4	主流三方库	pino、@sinclair/typebox、ajv、drizzle-orm
5	自行实现	仅在以上都无法满足时

前端：新增代码优先复用已有组件、工具和依赖库，不引入新依赖。确需新增依赖时先说明原因。

Git 提交

提交信息使用中文，格式为 类型: 简短描述。
提交类型限定为：feat、fix、refactor、docs、style、test、chore。
多行提交描述时，标题和正文之间空一行。

目录边界

目录	约定
`src/server/`	Bun 后端代码，不能 import src/web/，HTML import 集成除外
`src/server/db/`	SQLite 数据库模块，包含 schema、connection、migration 和 data access
`src/server/ai/`	AI Provider Registry 构建与连接测试
`src/web/`	React 前端，不能 import src/server/ 运行时实现
`src/shared/`	前后端共享 TypeScript 类型
`scripts/`	独立运行脚本，可 import 项目源码
`drizzle/`	Drizzle Kit 生成的 SQL migration 文件（开发期产出）
`tests/`	测试目录，结构镜像 src/
`docs/user/`	用户使用、配置、部署和排障文档
`docs/development/`	架构、后端、前端、发布开发文档
`openspec/`	OpenSpec 变更管理与规格文档

类型与配置

共享类型以 src/shared/api.ts 为唯一源头。
应用常量以 src/shared/app.ts 为唯一源头。
版本号以 package.json.version 为唯一源头。
前端不得 import src/server/ 下的任何文件。
配置加载流程固定为：unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ServerConfig。
Ajv 保持严格拒绝模式：不开类型强制转换、不注入默认值、不自动删除未知字段。
新增或修改配置字段时必须同步更新 TypeBox schema fragments、config.schema.json、测试和对应用户文档。

后端日志

后端运行时代码统一通过 Logger 接口输出日志，禁止直接使用 console.*（仅 src/server/logger.ts 的实现类内部可用）。
敏感信息自动 redact authorization、cookie、password 等字段。

API 路由

路由文件位于 src/server/routes/，每个端点一个文件。
路由通过 server.ts 的 Bun.serve({ routes }) 声明式注册。
新增路由步骤：创建 handler 文件 → 在 server.ts 注册 → 在 tests/server/ 添加测试。

前端数据层

统一使用 fetch，不引入 axios。
错误抛异常，由 TanStack Query 的 error 状态承接。
前端 fetch 返回类型必须匹配后端真实 JSON 形状；后端返回包装对象（如 { project: Project }）时，应声明对应响应类型并在 hook 内提取业务对象。
不引入额外状态管理库。TanStack Query 承担服务端状态，组件内状态使用 useState。

二、前端红线

组件红线

优先使用 antd 组件默认能力和 props 配置行为，不额外改写组件视觉。
全局使用 ConfigProvider 配置中文 locale 和主题切换，不在 CSS 中硬编码亮色或暗色分支。
需要 message、modal、notification 等应用级能力时，在 ConfigProvider 内包裹 App（代码中别名为 AntApp），组件内通过 App.useApp() 获取。
页面组件保持编排职责，组合 hooks 和展示组件；当页面同时承担查询、筛选、分页、表格列、弹窗表单和 mutation 时，应按功能边界拆分。

样式红线

严禁在组件中使用 style 属性内联样式。
严禁通过 CSS 覆盖 antd 组件内部类名（.ant-*）。
严禁使用 !important。
严禁使用硬编码色值，颜色统一使用 antd CSS 变量（var(--ant-*)）。
默认不引入 Tailwind、Sass、Less、CSS-in-JS 等额外样式方案；确需引入时必须先说明原因和影响范围。

样式指导原则

antd 承担主视觉系统，项目 CSS 只补足页面外壳和局部布局，不另起一套样式体系。
样式选择优先级：antd 默认能力 → antd props → antd 布局组件 → theme token → antd CSS 变量 → 全局 CSS。
全局 CSS 仅承载应用外壳和基础样式，类名使用 app-* 前缀，禁止泛名类（如 .container、.title）。
当样式需求增长到需要就近维护时，使用 CSS Modules 与页面/组件同级放置。

表单与交互

Modal + Form 提交使用 Form onFinish 处理业务提交，Modal onOk 只触发 form.submit()。
不在 Modal onOk 中直接执行异步 validateFields 和提交逻辑。
文本必填字段同时配置 required: true 和 whitespace: true，保持前后端校验一致。
操作确认优先使用 Popconfirm，成功/失败反馈优先使用 antd message。

错误边界

生产入口必须启用 ErrorBoundary。
ReactQueryDevtools 仅在 import.meta.env.DEV 条件下渲染。

三、测试规范

后端测试

API 路由集成测试必须通过真实 startServer 覆盖路由注册、HTTP method、fallback、响应 header 和核心错误路径。
SQLite 相关测试必须复用 tests/helpers.ts 中的测试数据库 helper，不要在测试文件内分散实现临时目录清理。
DAO 和路由边界测试应优先使用真实 migration 初始化测试库。
logger/bootstrap 中预期的 fallback 输出必须在测试中捕获并断言，正常通过的测试不应污染 stdout/stderr。

前端测试

测试目录为 tests/web/，结构对应 src/web/。
组件测试使用 jsdom 和 @testing-library/react，测试用户行为而非实现细节。
断言优先基于用户可见文本、role、按钮和交互结果，不依赖 .ant-* 内部类名。
系统边界（fetch mock、路由、QueryClientProvider）优先复用 tests/web/test-utils.tsx。
数据驱动页面至少覆盖请求 URL/query、method/body、成功后的用户可见结果，以及关键错误路径。
ErrorBoundary、hooks 纯逻辑和 fetch helper 应使用单元测试覆盖异常回退，页面测试只保留真实用户路径。

常用命令

命令	说明
`bun install`	安装依赖
`bun run dev config.yaml`	启动双进程开发环境
`bun run dev:server config.yaml`	仅启动后端 API server
`bun run dev:web`	仅启动 Vite dev server
`bun run schema`	生成 config.schema.json
`bun run schema:check`	检查导出 schema 是否同步
`bun run typecheck`	TypeScript 类型检查
`bun run lint`	ESLint 和 Prettier 格式检查
`bun run format`	Prettier 自动格式化
`bun run format:check`	Prettier 格式检查
`bun test`	运行全部测试
`bun run check`	schema:check + typecheck + lint + test
`bun run build`	构建生产可执行文件
`bun run verify`	check + build 完整验证
`bun run clean`	清理构建缓存与临时文件
`bun run version:patch`	升迁 patch 版本（x.y.Z）
`bun run version:minor`	升迁 minor 版本（x.Y.0）
`bun run version:major`	升迁 major 版本（X.0.0）
`bun run version:set`	显式设置版本号

质量门禁

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

变更类型	必跑命令
常规代码变更	`bun run check`
构建、部署、前后端集成变更	`bun run verify`
配置 schema 变化	`bun run schema`、`bun run schema:check`、`bun run check`
SQLite 测试基础设施变化	相关单文件测试 + SQLite 聚焦 `--rerun-each` + `bun run check`
仅文档变更	检查链接、索引和文档归属一致性

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

已知设计决策

决策	原因
Provider.apiKey 返回给前端	个人项目，apiKey 非严格密码，前端需要展示和编辑。如需保护，应改为返回脱敏值或仅后端存储。

文档影响分析

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

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

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

更新触发条件

修改常用命令、质量门禁、开发规范（任何章节）、目录边界或开发文档索引时，必须更新本文档。

README.md Unescape Escape

开发文档

专题索引