chore: 构建初始项目结构。
This commit is contained in:
徐涛
@@ -0,0 +1,128 @@
|
||||
# AGENTS.md
|
||||
|
||||
Karpathy-inspired behavioral guidelines for this project.
|
||||
|
||||
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
|
||||
|
||||
---
|
||||
|
||||
## 核心原则 (Karpathy)
|
||||
|
||||
### 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
|
||||
**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.
|
||||
|
||||
### 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
|
||||
**Define success criteria. Loop until verified.**
|
||||
|
||||
For multi-step tasks, state a brief plan:
|
||||
```
|
||||
1. [Step] → verify: [check]
|
||||
2. [Step] → verify: [check]
|
||||
3. [Step] → verify: [check]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 技术栈规范
|
||||
|
||||
### 通用规范
|
||||
|
||||
**包管理器**: `cargo`
|
||||
|
||||
**代码风格**
|
||||
- 文件/文件夹命名：`kebab-case`
|
||||
- 类/组件命名：`PascalCase`
|
||||
- 变量/函数命名：`snake_case`
|
||||
|
||||
**测试要求**
|
||||
- 新功能建议附测试；修复 bug 建议附回归测试
|
||||
- 简单明确的逻辑不需要创建测试（如枚举字面值、Getter、无分支的简单转换）
|
||||
- 测试结构：AAA 模式 (Arrange-Act-Assert)，优先测试边界条件和错误场景
|
||||
|
||||
**错误处理**
|
||||
- 优先使用 `Result` 处理错误，避免 `unwrap()`
|
||||
- 使用自定义 Error 类型，错误消息对用户友好、对开发者有调试信息
|
||||
|
||||
**安全规范**
|
||||
- 不硬编码密钥，使用环境变量
|
||||
- 用户输入必须验证
|
||||
|
||||
**Git Commit 规范**
|
||||
- 使用 Conventional Commits 格式：`<type>(<scope>): <description>`
|
||||
- 类型：`feat` `fix` `enhance` `docs` `style` `refactor` `test` `chore`
|
||||
- 描述使用祈使句、现在时态、句尾无句号
|
||||
|
||||
---
|
||||
|
||||
### Rust
|
||||
|
||||
**包管理器**: `cargo`
|
||||
|
||||
**代码风格**
|
||||
- `cargo fmt` 格式化，`cargo clippy` 检查
|
||||
- 变量/函数命名：`snake_case`
|
||||
- 优先使用 `Result` 处理错误，避免 `unwrap()`
|
||||
- 所有权规则：不使用 `&mut` 时不用，引用必须合法
|
||||
|
||||
**测试文件**: 内联测试（`#[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` 定义错误类型
|
||||
- 跨 module 依赖通过 trait 而非具体类型
|
||||
- 配置优先从环境变量读取，支持 builder 模式注入
|
||||
|
||||
---
|
||||
|
||||
**这些指南生效的标志：**
|
||||
- diff 中不必要的改动更少
|
||||
- 因过度复杂而导致的重写更少
|
||||
- 澄清问题在实现之前提出
|
||||
- 干净、精简的 PR
|
||||
Reference in New Issue
Block a user