kairos

Imported from Yuki-Nagori/kairos (AGENTS.md). Install upstream with npx skills add Yuki-Nagori/kairos. Copyright stays with the author.

AGENTS.md

Kairos：注塑成型 CAE 仿真软件，对标行业领先的同类产品（自主实现全部功能，不使用任何第三方专有代码或数据）。本文件是面向 AI 编码代理的项目入口（路由），改代码前先按需阅读所引文档。

文档路由

不可违反的约定（速查）

• 目录职责：src-web/ 前端（TypeScript）；src-crates/ Rust 领域层 crate（kairos-core 领域逻辑 + kairos-cli 无头 CLI）；src-tauri/ Tauri 桌面适配层。各目录内部的 src/ 是 Rust crate 固定结构，勿混淆。
• 依赖方向：前端 views / components → stores → api → utils / render；Rust src-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。