TauriTavern/AGENTS.md

TauriTavern Workspace Guidelines for AI Agent/Chat

道：项目哲学

完整说明见 CONTRIBUTING.md 的“项目哲学”。下面七条原则用于指导需求分析、设计、实现和评审。遇到取舍时，应结合用户需求、SillyTavern 生态、平台条件和能够验证的事实作出判断。

1. 通用大于特判。 先判断若干需求是否共享同一语义，优先扩展一处共同机制。真实差异应当清楚保留；缺少共同需求时，不要提前建立万能抽象。
2. 从第一性原理出发。 先确认用户希望得到什么、哪些行为已经成为外部契约、现有判断有多少证据，以及哪些条件必须长期成立。完成这些确认后，再选择具体技术和改动位置。
3. Fail fast，避免静默降级。 约束失效或结果无法确认时，停止相关操作并传播带有上下文的错误。预期内的恢复路径需要语义明确且对调用者可见；面对未知状态时，不要猜测默认结果。
4. 可维护性优先。 软件工程没有魔法。代码和文档应让后来的维护者能够理解、验证和修改系统，无需依赖未写下来的历史。额外复杂度需要现实问题和测量结果支撑。
5. KISS 与 60/95 原则。 选择能够完整解决当前问题的最简单方案。60/95 表示用约 60% 的复杂度覆盖约 95% 的现实边界；缺少现实依据的罕见场景可以留待真正出现时处理。
6. 简洁与优雅。 概念应当清楚，责任应当放在拥有相关事实的地方，数据流和错误路径应当容易追踪。实现应尊重用户选择和既有生态，并让 Rust、Tauri 与现代软件工程实践服务于问题本身。
7. 遵循，但不拘泥。 原则之间可能产生张力。遇到冲突时，回到原始目标和已有证据，说明取舍，运用第一性原理和实践判断选择当前合适的方案；新事实推翻旧判断时，应当修改设计。

术：工程实践

• 核心架构: 严格遵循 docs/BackendStructure.md 中定义的 workspace crate 边界。tauritavern host 只承载 Tauri shell、composition、commands、AppHandle/WebView/resource/platform glue；Tauri-free concrete IO 应放入对应 tt-adapter-* crate。
• Rust 哲学: 编写符合 Rust 习惯的惯用代码（idiomatic code）。优先使用 Result 和 thiserror/anyhow 进行错误处理。注意所有权和借用规则。
• 模块化与抽象: repository trait / outbound port 放在 tt-ports；具体实现放在 adapter crate。不要为单个实现新增无意义 trait、factory 或 facade。
• 代码复用 (DRY): 先复用项目已有 helper；不要为了“看起来通用”抽出跨 bounded context 的清洗器、格式库或抽象层。
• 文档优先: 在开始编码前，务必查阅 docs/ 目录下的相关文档（特别是 BackendStructure.md, FrontendGuide.md, FrontendHostContract.md），理解需求、架构和计划。
• 代码一致性: 在实现新功能前，检查项目中是否已有类似功能的代码或定义，尽可能复用或保持一致。
• 收尾标准: 逐路径自审概念、职责、状态归属和数据链路，确保代码可读且易维护；测试通过只是行为核对，不能作为收尾依据。可读性、可维护性与认知一致性是硬性收尾门控。交付后由维护者从第一性原理审核，通过审核才算收尾。
• 错误处理: 必须实现清晰的错误传播。遵循 fail-fast，避免静默降级；Tauri command 边界使用 CommandError，领域/仓储侧使用 DomainError。
• 异步处理: 对于 I/O 密集型或需要并发的操作（如文件读写、网络请求），必须使用 async/await 和 tokio 运行时。
• 数据传输对象 (DTO): 在应用层和表示层（Tauri 命令）之间传递数据时，必须使用 DTO。DTO 的定义需参考文档并保持前后端一致。
• Tauri 命令: #[tauri::command] 只能存在于 presentation 层，并且应该调用 application 层的服务来执行业务逻辑，避免在命令中直接处理复杂逻辑或操作基础设施。
• 注释: 为复杂、非显而易见的逻辑或算法添加清晰、简洁的注释。
• 测试准入: 只为可观察的稳定行为、非平凡不变式或边界，以及已经发生并修复的具体缺陷添加测试；代码变化和覆盖率本身不是理由。禁止用正则或文本断言源码，不测试字面量、明显控制流、直接委托、实现细节或已移除功能，不提前添加回归测试。
• 测试实践: 优先复用最高层的现有行为覆盖，避免在各层重复同一断言；并发测试使用确定性协调，不依赖 sleep。删除功能或测试时同步删除失效的 fixture、fake、hook 与依赖。核心仓储迁移或格式语义变更保留最小可运行测试；先运行受影响 crate 的 focused tests 与 scripts/check-rust-crate-boundaries.mjs，每次实现完成后运行完整 harness：pnpm run check。
• 前端交互: 注意 FrontendGuide.md 中关于与前端交互的说明，特别是 DTO 和事件的约定。
• 仓库级 Skill: 日常开发 Skill 以 .agents/skills/ 为唯一来源，.claude/skills 是指向它的软链接；.github/codex/skills/ 只供 CI 受控使用。涉及架构规划、统一机制、上游同步或审阅时，使用 maintain-conceptual-integrity。