From 4eb8d9511f6f7029787866a3b3b3133738e923de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=90=E6=B6=9B?= Date: Thu, 7 May 2026 09:27:04 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E6=9E=84=E5=BB=BA=E5=88=9D=E5=A7=8B?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++++ AGENTS.md | 128 +++++++++++++++++++++++++++++ Cargo.toml | 6 ++ README.md | 3 + src/lib.rs | 14 ++++ 5 files changed, 383 insertions(+) create mode 100644 .gitignore create mode 100644 AGENTS.md create mode 100644 Cargo.toml create mode 100644 README.md create mode 100644 src/lib.rs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2acdacb --- /dev/null +++ b/.gitignore @@ -0,0 +1,232 @@ +### Windows ### +# Windows thumbnail cache files +Thumbs.db +Thumbs.db:encryptable +ehthumbs.db +ehthumbs_vista.db + +# Dump file +*.stackdump + +# Folder config file +[Dd]esktop.ini + +# Recycle Bin used on file shares +$RECYCLE.BIN/ + +# Windows Installer files +*.cab +*.msi +*.msix +*.msm +*.msp + +# Windows shortcuts +*.lnk + +### Linux ### +*~ + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# Metadata left by Dolphin file manager, which comes with KDE Plasma +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +# Log files created by default by the nohup command +nohup.out + +### macOS ### +# General +.DS_Store +.localized +__MACOSX/ +.AppleDouble +.LSOverride +Icon[ ] + +# Resource forks +._* + +# Files and directories that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent +.com.apple.timemachine.supported +.PKInstallSandboxManager +.PKInstallSandboxManager-SystemSoftware +.hotfiles.btree +.vol +.file +.disk_label* +lost+found +.HFS+ Private Directory Data[ ] + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +# Mac OS 6 to 9 +Desktop DB +Desktop DF +TheFindByContentFolder +TheVolumeSettingsFolder +.FBCIndex +.FBCSemaphoreFile +.FBCLockFolder + +# Quota system +.quota.group +.quota.user +.quota.ops.group +.quota.ops.user + +# TimeMachine +Backups.backupdb +.MobileBackups +.MobileBackups.trash +MobileBackups.trash +tmbootpicker.efi + +### VisualStudioCode ### +# Visual Studio Code +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +!.vscode/*.code-snippets +!*.code-workspace + +# Built Visual Studio Code Extensions +*.vsix + +### JetBrains ### +# Covers JetBrains IDEs: IntelliJ, GoLand, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider +# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 + +# User-specific stuff +.idea/**/workspace.xml +.idea/**/tasks.xml +.idea/**/usage.statistics.xml +.idea/**/dictionaries +.idea/**/shelf + +# AWS User-specific +.idea/**/aws.xml + +# Generated files +.idea/**/contentModel.xml + +# Sensitive or high-churn files +.idea/**/dataSources/ +.idea/**/dataSources.ids +.idea/**/dataSources.local.xml +.idea/**/sqlDataSources.xml +.idea/**/dynamic.xml +.idea/**/uiDesigner.xml +.idea/**/dbnavigator.xml + +# Gradle +.idea/**/gradle.xml +.idea/**/libraries + +# Gradle and Maven with auto-import +# When using Gradle or Maven with auto-import, you should exclude module files, +# since they will be recreated, and may cause churn. Uncomment if using +# auto-import. +# .idea/artifacts +# .idea/compiler.xml +# .idea/jarRepositories.xml +# .idea/modules.xml +# .idea/*.iml +# .idea/modules +# *.iml +# *.ipr + +# CMake +cmake-build-*/ + +# Mongo Explorer plugin +.idea/**/mongoSettings.xml + +# File-based project format +*.iws + +# IntelliJ +out/ + +# mpeltonen/sbt-idea plugin +.idea_modules/ + +# JIRA plugin +atlassian-ide-plugin.xml + +# Cursive Clojure plugin +.idea/replstate.xml + +# SonarLint plugin +.idea/sonarlint/ +# see https://community.sonarsource.com/t/is-the-file-idea-idea-idea-sonarlint-xml-intended-to-be-under-source-control/121119 +.idea/sonarlint.xml + +# Crashlytics plugin (for Android Studio and IntelliJ) +com_crashlytics_export_strings.xml +crashlytics.properties +crashlytics-build.properties +fabric.properties + +# Editor-based HTTP Client +.idea/httpRequests +http-client.private.env.json + +# Android studio 3.1+ serialized cache file +.idea/caches/build_file_checksums.ser + +# Apifox Helper cache +.idea/.cache/.Apifox_Helper +.idea/ApifoxUploaderProjectSetting.xml + +# Github Copilot persisted session migrations, see: https://github.com/microsoft/copilot-intellij-feedback/issues/712#issuecomment-3322062215 +.idea/**/copilot.data.migration.*.xml + +### Rust ### +# Generated by Cargo +# will have compiled files and executables +debug +target + +# These are backup files generated by rustfmt +**/*.rs.bk + +# MSVC Windows builds of rustc generate these, which store debugging information +*.pdb + +# Generated by cargo mutants +# Contains mutation testing data +**/mutants.out*/ + +# rustc will dump stack traces when hitting an internal compiler error to PWD +rustc-ice-*.txt + +# RustRover +# JetBrains specific template is maintained in a separate JetBrains.gitignore that can +# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore +# and can be added to the global gitignore or merged into this file. For a more nuclear +# option (not recommended) you can uncomment the following to ignore the entire idea folder. +#.idea/ + + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5450450 --- /dev/null +++ b/AGENTS.md @@ -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 格式：`(): ` +- 类型：`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 diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..a7d2155 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,6 @@ +[package] +name = "agcore" +version = "0.1.0" +edition = "2024" + +[dependencies] diff --git a/README.md b/README.md new file mode 100644 index 0000000..57480f8 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# AG Core + +AG Core是一个用于提供构建智能体的底层工具箱，其中提供的功能主要包括基础的大模型调用的完整周期，提示词的组合与优化，记忆检索与管理、MCP与工具的调用等。 diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 0000000..b93cf3f --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,14 @@ +pub fn add(left: u64, right: u64) -> u64 { + left + right +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn it_works() { + let result = add(2, 2); + assert_eq!(result, 4); + } +}