架构与实现

这一页写给要读代码或改代码的人：分层、请求流、数据模型、分页与 SQLite 限制的处理方式。

分层与依赖方向

Hetu.Api           控制器 / SSE 流 / 后台 Worker / DI 装配
   │  （依赖 Core 与 Infrastructure 的接口）
Hetu.Core          实体 · 领域服务 · 仓储接口        ← 不引用 EF Core / ASP.NET 实现
   ▲
Hetu.Infrastructure  EF Core 实现 · AI Provider · MCP · sqlite-vec · 文件与进程
Hetu.Shared         DTO / 枚举 / 常量（前后端契约）

依赖方向是 Api → Core ← Infrastructure：Core 只定义规则与接口，具体实现（数据库、模型调用、进程、文件系统）都在 Infrastructure。

一次请求的路径

1. 前端（React + TanStack Query）调用 /api/*，统一走 axios 实例与响应拦截器。
2. 控制器只做参数校验与调用服务；业务逻辑在 Hetu.Core/Services。
3. 服务通过 IUnitOfWork 暴露的仓储访问数据库（EF Core），只读查询用 AsNoTracking 与投影。
4. 需要长耗时的动作（索引、抽取、Wiki、看板执行）交给 IBackgroundTaskCoordinator，写入 TaskItem 记录后由后台 Worker 执行。
5. 对话类请求走 SSE：控制器把事件流写回前端，前端按事件类型渲染。

数据模型要点

数据表一览（按域）

仓储接口

关键文件落点

SQLite 的 DateTimeOffset 限制（实际踩过的坑）

• EF Core 的 SQLite provider 不支持在 SQL 中排序或聚合 DateTimeOffset：ORDER BY 抛 NotSupportedException，MAX() 无法翻译；比较表达式（x.CreatedAt > since）同样不能翻译。
• 处理方式：分页用 GetPagedByDateAsync；分组计数用 CountByAsync；时间戳聚合只投影两列后在内存取最大值；需要「最近 N 天」这类判断时先投影时间戳再在内存过滤。
• 不要在 IQueryable 上直接写 OrderBy(x => x.CreatedAt)——运行时才会炸。PostgreSQL 侧不受此限制。

性能实践

Agent 循环

1. 请求带上权限模式、工具白名单、联网/知识库/记忆开关与推理强度。
2. 循环开始时先取「运行中引导」（steering）：如果在流式过程中用户注入了新指令，会在这一步并入上下文。
3. 模型返回工具调用 → 按权限模式决定直接执行还是发审批请求 → 执行结果回填。
4. 过程事件通过 SSE 推送：正文增量、思考、工具调用与结果、检查点、通知。
5. 队列中的下一条消息在本轮结束后自动发送；真实落库的会话由首条消息创建。

质量约定

• 后端 dotnet build 与前端 npx eslint . 都要求零告警，且不接受任何抑制注释（#pragma warning disable / SuppressMessage / eslint-disable / @ts-ignore）。
• 依赖漏洞告警按升级包处理（例如把带漏洞的传递依赖固定到修复版本），而不是忽略。
• 文档站与 README 中英双语必须同步；截图放在 docs/screenshots/ 并保持命名稳定。