agcore/AGENTS.md

AGENTS.md

Karpathy 启发式行为指南，适用于 OpenCode。可根据需要与项目特定指令合并使用。

权衡： 这些指南倾向于谨慎而非速度。对于简单任务，可自行判断使用。

---

核心原则 (Karpathy)

1. 先思考再编码 (Think Before Coding)

不要预设。不要隐藏困惑。呈现权衡。

• 明确陈述你的假设。如果不确定，就问。
• 如果存在多种解释，全部列出——不要默默选择其一。
• 如果有更简单的方法，就说出来。在必要时提出反对。
• 如果某件事不清楚，停下来。说出困惑所在。然后提问。

2. 简洁优先 (Simplicity First)

解决问题的最小代码量。不写任何推测性代码。

• 不实现超出需求的特性。
• 不为只用一次的代码创建抽象。
• 不添加未经要求的"灵活性"或"可配置性"。
• 不为不可能发生的场景做错误处理。
• 如果你写了 200 行而它本可以用 50 行完成，重写它。

3. 精准变更 (Surgical Changes)

只改动必须改的。只清理你自己造成的混乱。

• 不要"优化"相邻的代码、注释或格式。
• 不要重构没有问题的代码。
• 遵循已有风格，即使你自己的写法不同。
• 如果你注意到不相关的死代码，提出来——但不要删除它。
• 删除你的改动导致的未使用的导入/变量/函数。

4. 目标驱动执行 (Goal-Driven Execution)

定义成功标准。迭代直至验证通过。

• "添加验证" → "通过测试验证已有实现的正确性"
• "修复缺陷" → "编写测试复现问题，验证修复"
• "重构 X" → "确保重构后测试仍然通过"

对于多步骤任务，简要列出计划：

1. [步骤] → 验证：[检查项]
2. [步骤] → 验证：[检查项]

---

技术栈规范

通用规范

包管理器: cargo

代码风格

• 文件/文件夹命名：kebab-case
• 类/组件命名：PascalCase
• 变量/函数命名：snake_case

测试要求

• 新功能建议附测试；修复 bug 建议附回归测试（不主动编写测试）
• 简单明确的逻辑不需要创建测试（如枚举字面值、Getter、无分支的简单转换）
• 测试结构：AAA 模式 (Arrange-Act-Assert)，优先测试边界条件和错误场景

错误处理

• 优先使用 Result 处理错误，避免 unwrap()
• 异步 API 使用 ? 传播错误，不在 catch 中静默吞掉错误
• 错误按层级组织：公开 API 用全局 Error，内部实现可定义细粒度子错误

安全规范

• 不硬编码密钥，使用环境变量
• 用户输入必须验证
• 依赖包保持更新

Git Commit 规范

• 使用 Conventional Commits 格式：<type>(<scope>): <description>
• 类型：
  • feat - 新功能
  • fix - Bug 修复
  • enhance - 增强现有功能（非新功能）
  • docs - 文档更新
  • style - 代码格式（不影响功能）
  • refactor - 重构
  • test - 测试相关
  • chore - 构建/工具/配置
• 描述使用祈使句、现在时态、句尾无句号

---

Rust

包管理器: cargo

代码风格

• cargo fmt 格式化，cargo clippy 检查
• 变量/函数命名：snake_case
• 优先使用 Result 处理错误，避免 unwrap()
• 所有权规则：不使用 &mut 时不用，引用必须合法

模块组织

• 按功能领域组织模块（一个模块一个职责）
• 使用 Rust 新风格模块结构：foo.rs 作为模块根，子模块在 foo/bar.rs

测试文件: 内联测试（#[cfg(test)] mod tests {}）或 tests/ 目录

依赖管理: Cargo.toml，语义化版本

---

项目特定规则

项目结构

• 源代码：src/（lib crate）
• 测试：内联 #[cfg(test)] mod tests {}

项目目标

agcore 是一个智能体（Agent）核心工具箱，提供：

• LLM 调用：完整的请求/响应周期管理
• 提示词工程：组合、模板化、优化
• 记忆系统：存储、检索、管理对话/向量记忆
• 工具调用：MCP 协议集成与自定义工具注册
• Agent 运行时：多轮对话、任务编排

设计原则

• 模块化：每个功能领域独立 module，通过 trait 定义接口
• 可插拔：LLM 后端、记忆存储、工具注册均通过 trait 抽象
• 无运行时依赖：core 层尽量少依赖，具体实现在 separate crates
• 异步优先：涉及 IO 的 API 均使用 async

特殊约定

• 所有公开 API 必须有文档注释（///）
• 使用 thiserror 或 derive_more 定义错误类型
• 错误按层级组织：公开 API 用全局 Error，内部实现可定义细粒度子错误
• 跨 module 依赖通过 trait 而非具体类型
• 配置优先从环境变量读取，支持 builder 模式注入

---

这些指南生效的标志：

• diff 中不必要的改动更少
• 因过度复杂而导致的重写更少
• 澄清问题在实现之前提出
• 干净、精简的 PR