参与开发

ASP.NET Core + React 全栈项目，外加 Tauri 桌面壳。动手前先读仓库根目录的 AGENTS.md。

仓库结构

src/
├── Hetu.Api/                                  控制器、SSE、后台 Worker、Program.cs
├── Hetu.Core/                                 实体、领域服务、仓储接口
├── Hetu.Infrastructure/                       EF Core、仓储实现、AI Provider、MCP、sqlite-vec
├── Hetu.Infrastructure.PostgresMigrations/    PostgreSQL 迁移
└── Hetu.Shared/                               DTO / 枚举 / 常量（前后端契约）
frontend/src/{pages,components,hooks,stores,services,types,utils,i18n}
shell/hetu-desktop/{src,src-tauri}              Rust 外壳、Tauri 配置、安装器钩子
scripts/                                       启动 / 打包 / 发版 / 冒烟测试
docs/                                          本网站与截图

构建与验证

# 后端（期望 0 告警 0 错误）
dotnet build src/Hetu.Api/Hetu.Api.csproj -c Release -v q

# 前端类型检查与静态检查
cd frontend && npx eslint . && npx tsc -b

# API 冒烟（后端已启动）
./scripts/test-api.sh

# 桌面壳 Rust 检查
cd shell/hetu-desktop/src-tauri && cargo check

告警零容忍：不接受 #pragma warning disable、SuppressMessage、eslint-disable、@ts-ignore。可空性加判空、平台 API 加 OperatingSystem.IsXxxVersionAtLeast 守卫、依赖漏洞升级包。

容易踩的约定

主题	约定
列表接口	必须分页，且分页与排序在数据库完成（不要 `ToList()` 后再 `Skip/Take`）
SQLite 时间排序	用 `GetPagedByDateAsync` / `CountByAsync` / `PruneAsync`，或投影排序键后在内存定序
前端副作用	不要在 `useEffect` 里同步 `setState`，改用派生值
组件导出	组件文件只导出组件，工具函数放 `utils/`（否则 Fast Refresh 失效）
文案	中英两份必须同步新增（后端 `Locales/{zh,en}`、前端 `i18n/locales/{zh,en}`）
异步迭代器	带取消令牌的参数必须标 `[EnumeratorCancellation]`，否则取消不生效（CS8425）
后台任务	长耗时操作交给 `IBackgroundTaskCoordinator`，别用即发即忘的 `Task.Run`
文档站	双语页面成对维护；改完本地起静态服务器逐页点一遍

版本号要改两处，推 tag 后由 CI 完成构建、签名、清单生成与发布。

发版流程

同步两处版本号：shell/hetu-desktop/src-tauri/tauri.conf.json 与 src/Hetu.Api/Hetu.Api.csproj（前端「关于」页读的是后者）。
提 PR 合并到 main。
打 tag 触发发布：

pwsh ./scripts/tag-release.ps1 -Version 0.4.0

CI 会构建 fat / slim 两个渠道的 Windows 与 Linux 安装包（带签名）、生成更新清单（latest*.json 及三个镜像变体）并创建 Release；任一渠道清单生成失败会让发布直接失败，避免发出「更新点不动」的版本。

提交信息

<type>(<scope>): <subject>

# type : feat | fix | docs | style | refactor | perf | test | chore
# scope: api | ui | db | ai | work | desktop | config

当前状态

尚无自动化测试工程；当前把关方式是 Release 构建 0 告警 + eslint / tsc + API 冒烟 + 浏览器实测。欢迎补 xUnit 测试工程。
已知限制：MCP 仅 stdio 完整可用；笔记全文检索基于 LIKE（FTS5 / tsvector 在计划中）。