# rarch (归藏) - AI 助手开发规约

作为 **rarch** 的 AI 编程助手，在进行代码生成、重构或功能扩展时，必须严格遵守以下原则和设计模式。

## 1. 核心哲学与架构原则 (Core Philosophy)

*   **数据安全高于一切**：任何涉及文件移动、重命名或去重的操作，必须首先确保它是可逆的（通过 `Journal`）。
*   **内容优先于后缀**：在进行分类匹配时，应始终优先调用 `infer` 驱动的真实二进制头匹配逻辑，而非仅仅依赖文件名后缀。
*   **极简核心，功能分层**：
    *   `Engine`：保持无状态或轻量级，仅处理逻辑。
    *   `Journal`：必须是原子的（Atomic），确保操作日志 100% 写入。
    *   `UI/Watcher`：作为可选 Feature，不应侵入核心整理引擎。

## 2. 代码开发准则 (Coding Standards)

*   **错误处理**：统一使用 `anyhow` 进行上下文包装，提供更有意义的错误信息（包括涉及的文件路径）。
*   **路径安全**：始终使用 `std::path::PathBuf` 进行跨平台路径拼接。严禁手动拼字符串路径。
*   **并发性能**：批量处理必须并行化。优先使用 `rayon` 的 `into_par_iter`。
*   **变量命名**：遵循 Rust 命名惯例。在处理占位符和模板时，使用 `placeholder` 或 `template` 字样以示区分。

## 3. 常见任务模式 (Patterns)

### 增加新规则匹配项
1. 在 `config.rs` 的 `Rule` 结构中更新字段。
2. 在 `engine.rs` 的 `match_rule` 函数中实现匹配逻辑。优先级：`MIME` > `Type` > `Extensions`。

### 扩展模板变量 (Placeholders)
1. 在 `engine.rs` 的 `resolve_placeholders` 函数中注册新变量。
2. 确保新变量具有防御性（例如，如果元数据缺失，应保留原样或回退到默认值）。

## 4. 文档同步要求 (Documentation Synchronization)

*   **双语同步**：任何对 README 或核心文档的修改，必须同时应用到 `README.md` (English) 和 `README_ZH.md` (简体中文)。
*   **去图形化符号**：文档应保持简洁、专业，避免过度使用 Emoji 干扰阅读。

## 5. 禁止操作 (Forbidden Actions)

*   **禁止硬编码中文路径**：所有示例路径必须使用标准英文/通用路径。
*   **禁止静默失败**：对于无法移动的文件，必须在日志中记录原因，不能吞掉错误。
*   **禁止未授权的依赖引入**：核心库应保持小巧，除非必要，否则不引入大型臃肿框架。
