主题
MyAgent CLI — 类 Claude Code 终端 AI 编程智能体设计与实现
一、项目定位
MyAgent 是一个开源的终端 AI 编程智能体，借鉴 Claude Code 的核心架构思想，实现一个功能完整、可扩展、支持多模型的 CLI 编码助手。
核心特性：
- 基于 TypeScript 实现，Node.js 运行
- Agent Loop 驱动的自主编程能力
- 内建 7 个核心工具（Read/Write/Edit/Glob/Grep/Bash/WebFetch）
- 支持多 LLM 提供商（OpenAI/Anthropic/本地模型）
- 权限分层管控 + 可配置审批策略
- AGENTS.md 项目级指令支持
- 交互式终端 UI + 非交互管道模式
技术栈：
- 语言：Python 3.10+
- 终端 UI：Rich（格式化输出）+ prompt-toolkit（交互输入）
- LLM 通信：OpenAI Python SDK（兼容 API）
- HTTP 客户端：httpx
- CLI 框架：Click
- 文件搜索：ripgrep（通过 Shell 调用）
- 包管理：pip + pyproject.toml
二、架构设计
2.1 三层架构
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: CLI 层 (src/cli/) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ 交互式 │ │ 管道模式 │ │ 斜杠命令 │ │ 配置管理 │ │
│ │ Terminal │ │ Pipe │ │ Commands │ │ Config │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬───────┘ │
├───────┼──────────────┼──────────────┼──────────────┼─────────┤
│ Layer 2: Core 层 (src/core/) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ Agent │ │ LLM │ │ Prompt │ │ Permission │ │
│ │ Loop │ │ Client │ │ Builder │ │ Manager │ │
│ └────┬─────┘ └──────────┘ └──────────┘ └────────────┘ │
├───────┼─────────────────────────────────────────────────────┤
│ Layer 3: Tool 层 (src/tools/) │
│ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌────────┐ │
│ │ Read │ │Write │ │ Edit │ │ Glob │ │ Grep │ │ Bash │ │
│ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └────────┘ │
└─────────────────────────────────────────────────────────────┘2.2 核心数据流
用户输入
│
▼
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Prompt │───►│ LLM Client │───►│ LLM API │
│ Builder │ │ (发送请求) │ │ (云端模型) │
└──────────┘ └──────────────┘ └──────┬───────┘
│
▼
┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ 对话历史 │◄───│ Agent Loop │◄───│ 模型响应 │
│ 追加结果 │ │ (循环控制) │ │ (文本/工具) │
└──────────┘ └──────┬───────┘ └──────────────┘
│
有工具调用？
╱ ╲
是 否
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ Tool │ │ 返回最终 │
│ Executor │ │ 响应给用户│
│ (执行工具)│ └──────────┘
└──────────┘三、模块详细设计
3.1 Agent Loop
Agent Loop 是核心引擎，职责：
- 接收用户输入，调用 Prompt Builder 组装完整提示
- 通过 LLM Client 发送请求
- 解析响应，判断是否包含工具调用
- 如有工具调用，通过 Tool Executor 执行，将结果追加到对话历史
- 循环直到模型返回无工具调用的纯文本响应
- 支持 max_turns 限制防止无限循环
3.2 LLM Client
- 封装与 LLM API 的通信
- 支持流式输出（SSE）
- 支持多提供商（OpenAI / Anthropic / 兼容 API）
- 统一的请求/响应格式（内部使用 OpenAI 格式作为规范）
3.3 Prompt Builder
- 组装系统提示（角色定义 + 行为准则）
- 注入工具定义（JSON Schema）
- 加载 AGENTS.md 项目指令
- 注入环境上下文（当前目录、Git 状态等）
- 拼接对话历史
3.4 Tool 体系
7 个核心工具，统一接口：
| 工具 | 参数 | 功能 | 需权限 |
|---|---|---|---|
| Read | path, offset?, limit? | 读取文件 | 否 |
| Write | path, contents | 创建/覆写文件 | 是 |
| Edit | path, old_string, new_string | 精准替换 | 是 |
| Glob | pattern, cwd? | 文件模式匹配 | 否 |
| Grep | pattern, path?, include? | 正则搜索文件内容 | 否 |
| Bash | command, timeout? | 执行 Shell 命令 | 是 |
| WebFetch | url | 获取 URL 内容 | 是 |
3.5 权限管理
- 只读工具自动放行（Read/Glob/Grep）
- 写入工具需要用户确认（Write/Edit/Bash/WebFetch）
- 支持 allowlist / denylist 规则
- 支持
--auto自动批准模式
3.6 配置系统
- 全局配置：
~/.myagent/config.json - 项目配置：
.myagent/config.json - 项目指令：
AGENTS.md（兼容业界标准）
四、项目目录结构
my-agent-cli/
├── pyproject.toml ← 项目配置与依赖
├── README.md
├── myagent/
│ ├── __init__.py
│ ├── __main__.py ← CLI 入口（Click）
│ ├── core/
│ │ ├── __init__.py
│ │ ├── types.py ← 类型定义（dataclass）
│ │ ├── agent_loop.py ← Agent Loop 核心引擎
│ │ ├── llm_client.py ← LLM API 客户端
│ │ ├── prompt_builder.py ← 提示组装器
│ │ ├── permission.py ← 权限管理器
│ │ ├── conversation.py ← 对话历史管理
│ │ └── config.py ← 配置加载器
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── base.py ← 工具抽象基类
│ │ ├── registry.py ← 工具注册表
│ │ ├── read.py
│ │ ├── write.py
│ │ ├── edit.py
│ │ ├── glob_tool.py
│ │ ├── grep.py
│ │ ├── bash.py
│ │ └── web_fetch.py
│ └── cli/
│ ├── __init__.py
│ ├── interactive.py ← 交互式 REPL
│ ├── commands.py ← 斜杠命令处理
│ └── display.py ← Rich 输出格式化
└── tests/
└── __init__.py五、实现代码
详见 /data/workspace/my-agent-cli/ 项目目录。