ztt0216 / MyAgent

# MyAgent
项目仓库：ztt0216/MyAgent。
MyAgent 是一个基于 Python 实现的通用 **Agent Runtime**。它不是简单的命令行聊天工具，而是一个可运行、可阅读、可扩展的本地 runtime：统一编排模型推理、工具调用、权限控制、长期记忆、Skills、自进化、MCP 外部工具、子 Agent 和会话恢复。
项目重点是 **Harness**。模型只负责推理和提出工具调用意图，真正的环境操作由 Runtime 统一做权限判断、工具执行、结果回写、上下文压缩和经验沉淀。它适合学习通用 Agent 的底层机制，也适合作为个人 Agent、项目分析助手或领域 Agent 的二次开发基础。
## 核心亮点
- **通用 Agent Runtime**：统一编排模型、工具、权限、上下文、Memory、Skills 和外部扩展。
- **完整 Agent Loop**：模型请求、tool call 解析、权限检查、工具执行、tool result 回写、继续推理、会话保存形成闭环。
- **OpenAI / Anthropic 双协议**：支持 OpenAI-compatible 和 Anthropic-compatible 接口。
- **工具系统与权限控制**：支持读写文件、精确编辑、搜索、Shell、Skill 调用、子 Agent 和 MCP 工具；Plan Mode 下阻断写操作和 Shell。
- **Skills 体系**：通过项目级和用户级 `SKILL.md` 保存可复用方法，支持检索、调用、inline / fork 执行和版本化演化。
- **长期 Memory**：按项目路径 hash 隔离记忆，保存用户偏好、项目背景、历史决策和参考资料。
- **Skills 自进化**：从用户反馈中自动抽取可复用规则，新增或合并到 `SKILL.md`。
- **MCP 外部工具扩展**：自研 stdio JSON-RPC MCP Client，把外部 MCP Server 工具包装为 `mcp__server__tool`。
- **子 Agent**：支持 `explore`、`plan`、`general` 以及自定义子 Agent。
- **会话恢复和上下文压缩**：自动保存 session，支持 `--resume`、`/compact`，并对大工具结果做截断或持久化。
## 项目架构
核心运行链路：
 [code] 
## 目录结构
 [code] 
## 快速启动
### 1. 准备环境
推荐环境：
- Python 3.11+
- macOS / Linux
- Git
- ripgrep，可选但推荐
- 一个 OpenAI-compatible 或 Anthropic-compatible 模型接口
安装依赖：
 [code] 
### 2. 配置 `.env`
项目会自动读取当前目录或父目录中的 `.env`。
Anthropic-compatible 示例：
 [code] 
OpenAI-compatible 示例：
 [code] 
也可以使用通用变量：
 [code] 
协议判断规则：
- `API` 或 `--api-base` 路径包含 `/anthropic` 时，按 Anthropic-compatible 调用。
- 否则有 OpenAI base URL 时，按 OpenAI-compatible 调用。
- `--model` 会覆盖 `.env` 中的 `MODEL`。
### 3. 启动 REPL
 [code] 
启动后直接输入任务，例如：
 [code] 
### 4. 执行一次性任务
 [code] 
### 5. 使用 Plan Mode
Plan Mode 适合重构、复杂修复和多文件修改。它会先只读分析和写计划，用户审批后再执行。
 [code] 
REPL 中也可以输入：
 [code] 
### 6. 恢复最近会话
 [code] 
## Skills 自进化
MyAgent 的核心特色是 **Skills 自进化**。它可以从用户明确反馈中抽取未来可复用的规则，并自动新增或合并到项目级或用户级 `SKILL.md`。
### 1. 开启自动自进化
默认 `BEAR_AUTO_SKILL_EVOLUTION` 是开启的。为了明确配置，建议在 `.env` 中写：
 [code] 
含义：
- `BEAR_AUTO_SKILL_EVOLUTION=1`：启用在线 Skill 自进化。
- `BEAR_AUTO_SKILL_TARGET=project`：自动新增的 Skill 写入当前项目 `.bear/skills/`。
如果希望沉淀为所有项目共享的个人 Skill：
 [code] 
对应路径：
 [code] 
### 2. 用允许写入的权限模式启动
后台自动写入 Skill 需要当前权限模式允许写文件。推荐使用：
 [code] 
也可以使用更激进的模式：
 [code] 
不建议长期默认使用 `--yolo`，因为它会跳过确认。日常推荐 `--accept-edits`。
### 3. 给出可复用反馈
自进化不是把每一句话都写成 Skill。它只适合沉淀稳定、明确、未来同类任务仍适用的规则。
不太适合沉淀：
 [code] 
适合沉淀：
 [code] 
适合演化已有 Skill：
 [code] 
### 4. 自进化链路如何工作
 [code] 
核心文件：
 [code] 
审计产物：
 [code] 
## 更多文档
- 从0到1学习了解项目
- 架构设计
- 核心源码阅读指南
- 技术亮点
- Skills自进化逻辑与实现思路
- 评测部分
## 开发与测试
 [code] 
测试不调用模型，覆盖权限模式（plan / acceptEdits / dontAsk）、危险命令检测、权限规则优先级、编辑前必须先读和 mtime 校验、Skill 加载优先级与 BM25 检索。CI 在 Python 3.11 和 3.12 上运行。
欢迎提 Issue 和 Pull Request。提 PR 前请确保 `python -m pytest -q` 通过。
## License
MIT