xt/agcore

Fork 0

Files

T

徐涛 2b523a3e72 docs: clarify commit message description rule

2026-05-07 10:41:18 +08:00

4.5 KiB

Raw Blame History

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 时不用，引用必须合法

模块组织

按功能领域组织模块（一个模块一个职责）
功能相关和相似的代码归入同一模块
使用 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/ 目录

依赖管理: 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

4.5 KiB Raw Blame History Unescape Escape