agcore/AGENTS.md

AGENTS.md

---

交互要求

• 思考过程全程必须使用中文，包括需求分析、逻辑拆解、方案选择等所有推理环节
• 最终输出内容必须全部使用中文，除代码语法本身和英文关键词以外

---

核心原则 (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

测试要求

• 核心业务逻辑需测试（关键算法、边界条件、错误处理）
• 简单逻辑不需要测试（枚举字面值、Getter、无分支的简单转换）
• 不主动补测试（除非用户明确要求）

错误处理

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

安全规范

• 不硬编码密钥，使用环境变量
• 用户输入必须验证
• 依赖升级策略：
  • 安全补丁：立即升级（修复已知漏洞）
  • 次要版本：评估后升级（新功能、向后兼容）
  • 主要版本：谨慎升级（可能破坏兼容性，需全面测试）
  • 验证：升级后运行完整测试套件确保无回归

Git Commit 规范

• 使用 Conventional Commits 格式：<type>(<scope>): <description>
• 描述使用中文
• 类型：
  • feat - 新功能
  • fix - Bug 修复
  • enhance - 增强现有功能（非新功能）
  • docs - 文档更新
  • style - 代码格式（不影响功能）
  • refactor - 重构
  • test - 测试相关
  • chore - 构建/工具/配置
• 描述使用祈使句、现在时态、句尾无句号
• Body 规则：不列举 commit 中每一个文件的变更，body 只列出变更概要列表即可
• Scope 推导规则：
  • 从被提交的文件路径中推导出一个最相关的 scope
  • 一个 commit 只写一个主要 scope，不要罗列多个
  • 如果改动涉及多个模块，选择影响范围最大的那个或使用更上层抽象名称
  • 如果改动是全局的，可以省略 scope 或使用 core/global
• 示例：
  • feat(llm): 添加流式响应支持（修改 src/llm/stream.rs）
  • fix(memory): 修复向量检索边界条件（修改 src/memory/vector_store.rs）
  • refactor(core): 统一错误类型定义（修改多个模块的错误处理）
  • docs: 更新 API 文档（全局文档更新）
  • chore(deps): 升级 tokio 到 1.40（依赖更新）

Commit 提交流程

在生成 commit message 后，必须先展示给用户确认，不可直接执行 git commit。

流程：

1. Agent 根据 diff 生成符合规范的 commit message
2. 展示生成的 message，等待用户明确回应
3. 用户有三种选择：
   • 确认 → 执行 git commit
   • 重新生成 → 根据用户反馈修改 message 后重新展示
   • 取消 → 放弃本次 commit 操作

---

Rust

包管理器: cargo

代码风格

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

模块组织

• 按功能领域组织模块（一个模块一个职责）
• 2018+ 版风格：使用 foo.rs 作为模块根，子模块放在 foo/ 目录下
• 扁平优先：如果模块没有子模块，直接用单个 foo.rs 文件
• 需要子模块时才用目录：只有当模块需要组织多个子模块时才创建 foo/ 目录
• 避免 mod.rs：不使用 foo/mod.rs 风格，统一使用 foo.rs 作为模块根
• 公共 API 重导出：在模块根中使用 pub use 重新导出子模块的公共类型，提供清晰的 API 边界

示例结构图：

src/
├── lib.rs                  # crate 根，声明顶层模块
├── llm.rs                  # LLM 模块（无子模块，扁平文件）
├── memory.rs               # 记忆模块根（有子模块）
├── memory/
│   ├── conversation.rs     # ✓ 子模块
│   └── vector_store.rs     # ✓ 子模块
├── prompt.rs               # 提示词模块根（有子模块）
├── prompt/
│   ├── template.rs         # ✓ 子模块
│   └── optimizer.rs        # ✓ 子模块
├── tool.rs                 # 工具模块根（有子模块）
├── tool/
│   ├── mcp.rs              # ✓ 子模块
│   └── registry.rs         # ✓ 子模块
└── agent.rs                # Agent 模块根（有子模块）
└── agent/
    ├── runtime.rs          # ✓ 子模块
    └── planner.rs          # ✓ 子模块

# ❌ 避免的风格
src/
└── memory/
    └── mod.rs              # ❌ 不使用 mod.rs 风格

# ✅ memory.rs 示例：声明子模块并重导出公共 API
pub mod conversation;
pub mod vector_store;

// 重导出常用类型，提供简洁的公共 API
pub use conversation::ConversationMemory;
pub use vector_store::VectorStore;

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

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

---

文档规范

文档编号规范（design/pdd/ + design/prd/）

design/pdd/（方案文档）和 design/prd/（需求文档）使用相同的命名格式，但各自独立编号：

<序号>-<简短描述>.md

规则：

• 序号使用数字，从 1 开始递增。创建前必须通过 shell 命令确认目标目录当前实际最大编号再加 1：

  # 查 design/pdd/ 的最大编号
  ls design/pdd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
  # 查 design/prd/ 的最大编号
  ls design/prd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
  # 无输出则从 1 开始
  

  禁止使用上下文中缓存的编号。
• 描述：中文，简短概括主题
• 两个目录各自独立编号——design/pdd/ 已有 3- 时，design/prd/ 的新文件仍从当前最大号 +1 开始，互不影响

方案文档（design/pdd/）应包含：

• 背景与目标
• 需求推演概要（需求拆解、边界识别、关键假设的简要推演）
• 当前问题分析
• 架构决策记录（重大技术选型、架构变更的决策过程与理由）
• 设计方案（含架构图/流程图）
• 实施步骤
• 验证标准
• 回滚方案（如适用）

示例：

• design/pdd/1-ui-components重构方案.md
• design/prd/1-用户认证需求.md
• design/pdd/2-数据库迁移方案.md

---

设计目录（design/）

项目根下的 design/ 目录集中管理所有设计相关的文件，供人类和 agent 共同读写。

子目录	内容	谁写	谁读
design/pdd/	方案设计文档（PDD）→ 架构方案、设计决策、转换方案	proposal→writer pipeline	Think 参考、Build 实现、Vet 审查
design/prd/	需求文档（PRD）→ 功能需求、用户故事、验收标准	人写	Think 分析、Proposal 写方案时参考
design/prototype/	OD 导出的原型 HTML → 视觉稿、交互原型、页面 layout	OD 桌面版导出	Think 分析结构、Build 对照实现
design/notes/	笔记记录 → 零散想法、会议纪要、调研速记	人写	各 agent 参考
design/roadmap/	路线图 → 里程碑规划、版本计划、优先级列表	人写	Proposal 排期参考
design/DESIGN.md	设计系统（品牌规范）→ 色板、字体、间距、语气	OD 导出 / 人维护	Think 提取 token、Build 同步到 src/
design/tokens.css	设计 Token CSS → 从 DESIGN.md 提取的 CSS 变量	人同步 / agent 同步	所有 Svelte 组件引用

访问规则：

• 读：所有 agent 默认可读（read_file 不需要额外权限）
• 写：writer agent 可通过 "design/**": allow 写入 design/ 下任意子目录
• 注意：prototype/ 由 OD 桌面版导出，agent 只读不写；DESIGN.md 和 tokens.css 建议手动维护或 agent 写入时确认后再改

兜底规则： 文档类型不在上表时（如教程、接口文档、临时记录），或目标目录不存在时 → 向用户提问确认路径。不允许自行推断存放位置。

---

项目特定规则

项目结构

• 源代码：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