Imported from Yuki-Nagori/kairos (
AGENTS.md). Install upstream withnpx skills add Yuki-Nagori/kairos. Copyright stays with the author.
AGENTS.md
Kairos:注塑成型 CAE 仿真软件,对标行业领先的同类产品(自主实现全部功能,不使用任何第三方专有代码或数据)。本文件是面向 AI 编码代理的项目入口(路由),改代码前先按需阅读所引文档。
文档路由
| 需要了解 | 去处 |
|---|---|
| 分层规则、IPC/错误契约、长任务与进度回传模式、新增领域模块 recipe | ai-docs/ARCHITECTURE.md |
| Web 前端职责边界、composable/store 约定、反模式清单 | ai-docs/web-conventions.md |
| Rust 代码归属、模块组织、utils/错误/命名/测试/注释约定 | ai-docs/rust-conventions.md |
| 图标设计语言、双轨分类与强制参数 | ai-docs/icon-design.md |
| 项目推进到哪了、每个阶段的时间与决策 | ai-docs/timeline.md |
| 未来路线图、任务拆解(做新功能前必读) | ai-docs/tasks/README.md |
| 去哪找评审 / 复现报告 / 上游往来 | ai-docs/reviews/README.md |
| 预研与可行性(DOE、多物理场、特殊工艺) | ai-docs/research/README.md |
| 已定型的架构决策(GPL 隔离、运行时分发、Gmsh 选型) | ai-docs/decisions/README.md |
| 测试地图:全部测试的位置、分类与跑法 | tests/README.md |
| 求解器(moldingFoam)逐版本性能与收敛记录 | ai-docs/moldingfoam-perf.md |
| 面向人的项目简介、环境要求、快速开始、常用命令 | README.md |
不可违反的约定(速查)
- 目录职责:
src-web/前端(TypeScript);src-crates/Rust 领域层 crate(kairos-core领域逻辑 +kairos-cli无头 CLI);src-tauri/Tauri 桌面适配层。各目录内部的src/是 Rust crate 固定结构,勿混淆。 - 依赖方向:前端
views / components → stores → api → utils / render;Rustsrc-tauri/kairos-cli→kairos-core,core 内部error ← utils ← models / services。kairos-core禁止依赖 tauri;命令层不写业务逻辑,业务只住 core;utils不认识领域类型(签名里出现网格/场/工况等词汇即出局)。 - 逻辑归属(Rust 优先):计算密集 / 数值 / 几何 / 场处理逻辑一律在 kairos-core 实现(TS 性能大部分场景不如 Rust,前端以 UI 编排为主);TS 只做 UI 状态聚合与展示层逻辑,禁止重写 core 已有计算。判断口诀见 ai-docs/ARCHITECTURE.md §1.1。
- 错误契约:命令一律返回
Result<T, KairosError>,跨 IPC 序列化为{ code, message };code ∈ validation / not_found / io / solver / internal。前端按code分支,禁止文本匹配 message。 - DTO 双端镜像:Rust
models/↔src-web/types/index.ts,任何改动必须同步两处并让契约测试(tests/rust/contract/main.rs)通过。 - 线程模型:同步 Tauri 命令跑在主线程,重计算必须异步 / 另起线程;进度回传用
tauri::ipc::Channel;大体积数据用tauri::ipc::Response。 - 覆盖率门槛:
kairos-core行覆盖 100%(bun run coverage:rust,cargo-llvm-cov)、前端逻辑层全量 100%(utils/+stores/+composables/+ 各use*.ts,bun run test:coverage,行/函数/语句/分支全 100);api / render 薄适配层不计入门槛。两端均已并入 verify 门禁。 - GPU 计算:统一经 wgpu 抽象层覆盖 NVIDIA / AMD / Intel / Apple(Vulkan/DX12/Metal),禁止引入 CUDA 等单厂商 SDK;后处理以硬件加速 GPU 为运行前提,不提供 CPU 运行时回退。CPU 实现仅可作为正确性基准与测试参考;缺少可用 GPU 时必须明确提示该能力不受支持。
- 路径一律走库:任何路径拼装 / 解析 / 判定用
std::path(join/file_name/file_stem/extension/components/with_extension),禁止手写分隔符或split('/')——Windows 与 Unix 的分隔符、盘符、保留字符差异只在这一个工具模块里处理:src-crates/kairos-core/src/services/paths.rs(拼装 / 清洗 / 存储形态归一 / 盘符映射)。 跨机器落盘的相对路径统一用/(经paths::to_storage),读取侧用paths::from_storage。 前端不解析路径:格式判定之类交给 Rust(如导入按扩展名分派在import_geometry)。 - 锁文件:根
Cargo.lock与bun.lock必须提交、保持同步(整个工作区只有根目录这一份 Cargo.lock)。 - 提交前门禁:仓库根
bun run verify(typecheck + clippy -D warnings + format + test + 覆盖率门槛 + knip,前端与 Rust 全量),通过才算完成。 - 时间线:每完成一个任务,在 ai-docs/timeline.md 末尾追加一行(时间 + 阶段 + 内容),一行对应一个 commit,随该任务的提交一并入库。
- 文档图表:md 里的架构图 / 流程图 / 时序图优先用 mermaid 代码块(GitHub 与主流编辑器原生渲染),不用 ASCII 字符画;目录树保持纯文本代码块。新写图表后须经渲染校验(如 mermaid.ink)再入库。
- 覆盖率写法:不要用
#[allow]/ignore掩盖「假未覆盖」;隐藏落点(内联闭包、map_err闭包、?落点、偏态分支、跨平台语义差异)要改写成无隐藏落点的写法,同一语义的错误映射只写一处(详见 ai-docs/ARCHITECTURE.md §6)。 - 引入依赖:必须同时给许可(permissive)、性能(旧实现留在基准里同台对照)、包体(同口径构建)三项对照;自写成本更低就不引。换实现前先跑基线,别拿记忆里的数比。
- 批次性改动:收编 / 合并清单每条动手前先核实存在性;不要用重复出现的片段当锚点,机械替换要逐处断言原文并回读确认;迁移类改动分批提交。
- 里程碑评审:每个里程碑结束强制执行 T21 整体评审与优化(架构 / 性能 / 质量 / 文档 / 安全八项清单),发现按「立即修 / 回流任务 / 接受并记录」闭环,未通过不得开启下一里程碑。
详细理由与代码模板见 ai-docs/ARCHITECTURE.md。
- 测试地图见 tests/README.md。
