My-Agent

一个从零构建、可扩展且真实可运行的 Python Agent Runtime。

它将 Adaptive Planning、Step ReAct、Dynamic Replanning、独立 Judge 审核、Tools、MCP、Skills、事件回放 和 Textual TUI 组织在同一套运行时中。CLI 与终端界面消费相同的 Agent 事件，不各自维护一套执行循环。

运行架构

flowchart TD
    U["用户请求"] --> A{"Task Analyzer"}
    A -->|"direct_response"| O["生成候选答案"]
    A -->|"direct_execution"| E["Step ReAct Executor"]
    A -->|"requires_plan"| P["Adaptive Planner"]
    P --> E
    E --> T["Tools / Skills / MCP"]
    T --> M{"Plan Monitor"}
    M -->|"步骤完成"| N{"还有步骤？"}
    N -->|"是"| E
    N -->|"否"| O
    M -->|"发生偏差"| R["Dynamic Replanner"]
    R --> E
    O --> J{"Independent Judge"}
    J -->|"PASS"| F["最终回答"]
    J -->|"REVISE"| V["定向修订 / 补充工具验证"]
    V --> J
    J -->|"NEEDS_INPUT"| I["请求用户介入"]

Loading

统一状态机：

IDLE → ANALYZING → PLANNING → EXECUTING → MONITORING
     → REPLANNING → REVIEWING → REVISING
     → COMPLETED | FAILED | NEEDS_INPUT

核心能力

模块	能力
Task Analyzer	结构化判断 direct_response、direct_execution 或 requires_plan
Adaptive Planner	生成带依赖、前置条件、允许工具和完成标准的版本化计划
Step ReAct	在单个步骤内完成多轮模型调用与工具执行；多个工具可并发运行，并按原始 Tool Call 顺序回填历史
Plan Monitor	检查工具错误、预算、步骤完成标准、新约束和后续计划有效性
Dynamic Replanner	支持 PATCH_STEP、REPLAN_REMAINDER 和 FULL_REPLAN，且不篡改已完成步骤
Judge Agent	使用独立消息上下文审核目标完成度、缺失要求、工具结果冲突和无依据结论
Tool System	内置 Shell、文件写入、Skill 发现与延迟激活，并可继续注册自定义工具
MCP	基于官方 Python SDK 接入 stdio、Streamable HTTP 与 legacy SSE Server
Event Store	记录计划、工具、重规划和审核事件，支持 JSONL 回放和敏感字段脱敏
Textual TUI	展示消息、计划进度、工具结果、Plan Diff、Judge 结论和运行状态

项目结构

My-Agent/
├── src/my_agent/
│   ├── agent/       # Runtime、Planner、Executor、Monitor、Replanner、Judge
│   ├── models/      # 消息、计划、事件、配置等 Pydantic 模型
│   ├── providers/   # OpenAI-compatible 模型 Provider
│   ├── tools/       # Tool 协议、Registry、Shell、文件与 Skill 工具
│   ├── mcp/         # MCP Client 生命周期与 Tool Adapter
│   ├── skills/      # SKILL.md 发现、提示构建与延迟激活
│   └── tui/         # Textual 终端界面
├── skills/          # 项目自带示例 Skills
├── tests/           # 不依赖真实 API Key 的自动化测试
├── workspace/       # Shell Tool 的默认工作目录
├── config.json      # 非敏感运行配置
├── .env.example     # 环境变量模板
└── pyproject.toml

快速开始

1. 克隆并安装

运行环境：Python 3.12 和 uv。

git clone https://github.com/Huixin615/My-Agent.git
cd My-Agent
cp .env.example .env
uv sync --locked

编辑 .env，填入自己的模型密钥：

DEEPSEEK_API_KEY=your_api_key_here

config.json 中的 api_key 保存的是环境变量名称，不保存真实密钥。默认使用 DeepSeek 的 OpenAI-compatible Chat Completions 接口，也可以修改 base_url 和 model 接入其他兼容服务。

2. 启动终端界面

uv run my-agent

3. 无界面执行单次任务

uv run my-agent --prompt "在 workspace 中创建一个贪吃蛇游戏并验证它"

配置

• config.json：模型、规划、审核、事件日志、Skills、workspace 和 MCP 配置。
• config.example.json：不包含密钥的完整配置示例。
• .env：保存本机密钥，已被 Git 忽略。
• AGENT_CONFIG：可选，用于指定其他配置文件。

所有相对路径均以配置文件所在目录为基准解析。Shell Tool 的当前目录已经是项目自己的 workspace/，命令无需再次添加 workspace/ 前缀。

动态规划的关键配置：

{
  "planning": {
    "enabled": true,
    "max_model_calls": 30,
    "max_steps": 8,
    "max_step_iterations": 6,
    "max_step_attempts": 2,
    "max_local_replans": 2,
    "max_full_replans": 1
  },
  "review": {
    "enabled": true,
    "max_revisions": 1,
    "model": null
  },
  "event_store": {
    "enabled": true,
    "directory": "./log/runs"
  }
}

planning.max_model_calls 限制单次自适应任务的全局模型调用次数，max_step_iterations 防止单个步骤无限循环。关闭动态规划时，max_iterations 继续作为传统 ReAct Loop 的安全上限。

review.model 为 null 时，Judge 使用当前 Provider 和模型，但拥有完全独立的消息上下文；也可以填写其他模型名称。Judge 调用失败不会被伪装为审核通过。

MCP Server

在 config.json 的 mcp_server_config 中声明 Server。框架会并发连接多个 Server，单个连接失败只产生警告；成功发现的工具统一命名为 mcp_<server>_<tool>。

配置中的 http 可作为 streamable_http 的别名，以兼容常见配置习惯。

Skills

启动时仅扫描 SKILL.md 的 YAML frontmatter 并向模型暴露名称与摘要。只有 Agent 调用 activate_skill 后才读取完整正文，已激活内容会缓存，避免反复加载。

计划、审核与运行回放

复杂任务会产生：

• 带版本号与依赖关系的 ExecutionPlan。
• 带完成条件、工具边界和尝试次数的 PlanStep。
• 说明触发原因和 Plan Diff 的 PlanRevision。
• PASS、REVISE 或 NEEDS_INPUT 类型的 ReviewReport。

事件默认写入 log/runs/run_<run_id>.jsonl。日志包含状态变化、计划版本、工具调用摘要、重规划原因和 Judge 结论，可通过 JsonlEventStore.replay(run_id) 回放。常见 API Key、Authorization Header、密码型环境变量和含认证信息的 URL 会在落盘前脱敏。

TUI 快捷键

• Enter：发送
• Ctrl+S：立即发送，适用于中文输入法与 Enter 冲突的终端
• Shift+Enter：换行
• Ctrl+L：清空界面与 Agent 历史
• Ctrl+U：清空输入
• PageUp / PageDown、Home / End：滚动
• Esc / Ctrl+C：退出

为兼容中文、日文等终端输入法，程序默认关闭 Textual 的 Kitty 扩展键盘协议，使用普通 UTF-8 输入路径。如需恢复，可在启动前设置 TEXTUAL_DISABLE_KITTY_KEY=0。

安全边界

• .env、运行日志、workspace 生成物、缓存、虚拟环境和常见密钥文件均已加入 .gitignore。
• Shell 子进程使用环境变量白名单，不继承 DEEPSEEK_API_KEY 或其他常见 Token。
• Shell 默认采用无交互、带超时的输出捕获模式；GUI 或长时间服务可使用 background=true。
• 日志保存前会对常见凭据形式进行脱敏。

需要注意：cwd=workspace 不是操作系统沙箱。Shell 仍可能通过相对路径或绝对路径访问本机其他文件。请只在可信环境中使用，不要加载未审核的 Skill、MCP Server 或提示词；处理不可信输入时，应将工具执行放进容器或其他系统级沙箱。

开发与验证

开发工具位于独立的 dev 依赖组：

uv sync --locked --group dev
uv run --group dev pytest
uv run --group dev mypy src
uv run --group dev ruff check .
uv run --group dev ruff format --check .

自动测试使用 Fake Model、Fake Tools 和本地 Fixture，不需要真实 API Key 或公网。

License

本项目基于 MIT License 开源，Copyright © 2026 Huixin615。