chore: 更新AGENTS.md指引文件

AGENTS.md

@@ -1,47 +1,50 @@
 # AGENTS.md
 
-Karpathy-inspired behavioral guidelines for this project.
+Karpathy 启发式行为指南，适用于 OpenCode。可根据需要与项目特定指令合并使用。
 
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+**权衡：** 这些指南倾向于谨慎而非速度。对于简单任务，可自行判断使用。
 
 ---
 
 ## 核心原则 (Karpathy)
 
-### 1. Think Before Coding
+### 1. 先思考再编码 (Think Before Coding)
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
+**不要预设。不要隐藏困惑。呈现权衡。**
 
-- State your assumptions explicitly. If uncertain, ask.
+- 明确陈述你的假设。如果不确定，就问。
-- If multiple interpretations exist, present them - don't pick silently.
+- 如果存在多种解释，全部列出——不要默默选择其一。
-- If a simpler approach exists, say so. Push back when warranted.
+- 如果有更简单的方法，就说出来。在必要时提出反对。
-- If something is unclear, stop. Name what's confusing. Ask.
+- 如果某件事不清楚，停下来。说出困惑所在。然后提问。
 
-### 2. Simplicity First
+### 2. 简洁优先 (Simplicity First)
-**Minimum code that solves the problem. Nothing speculative.**
+**解决问题的最小代码量。不写任何推测性代码。**
 
-- No features beyond what was asked.
+- 不实现超出需求的特性。
-- No abstractions for single-use code.
+- 不为只用一次的代码创建抽象。
-- No "flexibility" or "configurability" that wasn't requested.
+- 不添加未经要求的"灵活性"或"可配置性"。
-- No error handling for impossible scenarios.
+- 不为不可能发生的场景做错误处理。
-- If you write 200 lines and it could be 50, rewrite it.
+- 如果你写了 200 行而它本可以用 50 行完成，重写它。
 
-### 3. Surgical Changes
+### 3. 精准变更 (Surgical Changes)
-**Touch only what you must. Clean up only your own mess.**
+**只改动必须改的。只清理你自己造成的混乱。**
 
-- Don't "improve" adjacent code, comments, or formatting.
+- 不要"优化"相邻的代码、注释或格式。
-- Don't refactor things that aren't broken.
+- 不要重构没有问题的代码。
-- Match existing style, even if you'd do it differently.
+- 遵循已有风格，即使你自己的写法不同。
-- If you notice unrelated dead code, mention it - don't delete it.
+- 如果你注意到不相关的死代码，提出来——但不要删除它。
-- Remove imports/variables/functions that YOUR changes made unused.
+- 删除你的改动导致的未使用的导入/变量/函数。
 
-### 4. Goal-Driven Execution
+### 4. 目标驱动执行 (Goal-Driven Execution)
-**Define success criteria. Loop until verified.**
+**定义成功标准。迭代直至验证通过。**
 
-For multi-step tasks, state a brief plan:
+- "添加验证" → "通过测试验证已有实现的正确性"
+- "修复缺陷" → "编写测试复现问题，验证修复"
+- "重构 X" → "确保重构后测试仍然通过"
+
+对于多步骤任务，简要列出计划：
 ```
-1. [Step] → verify: [check]
+1. [步骤] → 验证：[检查项]
-2. [Step] → verify: [check]
+2. [步骤] → 验证：[检查项]
-3. [Step] → verify: [check]
 ```
 
 ---
@@ -58,22 +61,32 @@ For multi-step tasks, state a brief plan:
 - 变量/函数命名：`snake_case`
 
 **测试要求**
-- 新功能建议附测试；修复 bug 建议附回归测试
+- 新功能建议附测试；修复 bug 建议附回归测试（不主动编写测试）
 - 简单明确的逻辑不需要创建测试（如枚举字面值、Getter、无分支的简单转换）
 - 测试结构：AAA 模式 (Arrange-Act-Assert)，优先测试边界条件和错误场景
 
 **错误处理**
 - 优先使用 `Result` 处理错误，避免 `unwrap()`
-- 使用自定义 Error 类型，错误消息对用户友好、对开发者有调试信息
+- 异步 API 使用 `?` 传播错误，不在 `catch` 中静默吞掉错误
+- 错误按层级组织：公开 API 用全局 Error，内部实现可定义细粒度子错误
 
 **安全规范**
 - 不硬编码密钥，使用环境变量
 - 用户输入必须验证
+- 依赖包保持更新
 
 **Git Commit 规范**
 - 使用 Conventional Commits 格式：`<type>(<scope>): <description>`
-- 类型：`feat` `fix` `enhance` `docs` `style` `refactor` `test` `chore`
+- 类型：
-- 描述优先使用中文、祈使句、现在时态、句尾无句号
+  - `feat` - 新功能
+  - `fix` - Bug 修复
+  - `enhance` - 增强现有功能（非新功能）
+  - `docs` - 文档更新
+  - `style` - 代码格式（不影响功能）
+  - `refactor` - 重构
+  - `test` - 测试相关
+  - `chore` - 构建/工具/配置
+- 描述使用祈使句、现在时态、句尾无句号
 
 ---
 
@@ -89,20 +102,7 @@ For multi-step tasks, state a brief plan:
 
 **模块组织**
 - 按功能领域组织模块（一个模块一个职责）
-- 功能相关和相似的代码归入同一模块
+- 使用 Rust 新风格模块结构：`foo.rs` 作为模块根，子模块在 `foo/bar.rs`
-- 使用 Rust 新风格模块结构：`foo.rs` 作为模块根，子模块在 `foo/bar.rs`，**不使用 `mod.rs`**
-- 示例：
-  ```
-  src/
-    lib.rs                # crate 根
-    types.rs              # mod types
-    provider.rs           # mod provider (根)
-    provider/
-      openai.rs           # provider::openai
-    cycle.rs              # mod cycle (根)
-    cycle/
-      retry.rs            # cycle::retry
-  ```
 
 **测试文件**: 内联测试（`#[cfg(test)] mod tests {}`）或 `tests/` 目录
 
@@ -133,6 +133,7 @@ agcore 是一个智能体（Agent）核心工具箱，提供：
 ### 特殊约定
 - 所有公开 API 必须有文档注释（`///`）
 - 使用 `thiserror` 或 `derive_more` 定义错误类型
+- 错误按层级组织：公开 API 用全局 Error，内部实现可定义细粒度子错误
 - 跨 module 依赖通过 trait 而非具体类型
 - 配置优先从环境变量读取，支持 builder 模式注入
 
@@ -142,4 +143,4 @@ agcore 是一个智能体（Agent）核心工具箱，提供：
 - diff 中不必要的改动更少
 - 因过度复杂而导致的重写更少
 - 澄清问题在实现之前提出
-- 干净、精简的 PR
+- 干净、精简的 PR