一天一个开源项目（第33篇）：MyCodeAgent - 面向学习的 Claude Code 风格代码代理框架

引言

"让 Agent 能做什么与 Agent 为什么能做，都可追溯、可验证、可扩展。"

这是「一天一个开源项目」系列的第 33 篇文章。今天介绍的项目是 MyCodeAgent（GitHub）。

想深入理解「Claude Code 式」代码代理的运作方式——工具协议怎么设计、上下文如何压缩、子代理如何协作、Trace 如何落盘——往往缺少一个可读、可改、可跑的开源样本。MyCodeAgent 正是面向学习与实验的代码代理框架：用 Function Calling 做工具调用（不依赖 Action 文本解析）、用统一工具响应协议和 MCP 做扩展、用上下文工程（截断、压缩、持久化）和 Trace 做可观测性，并提供了 Skills / Task 子代理 / AgentTeams 等机制，方便你在本地搭一个「可追溯、可验证、可扩展」的 Agent 试验场。

为什么值得看？

📐 工具协议系统化：统一响应格式（status/data/text/stats/context/error），Function Calling 驱动，不依赖自然语言解析
🧠 上下文工程：分层注入、历史压缩、@file 强制读取、超限落盘到 tool-output/
🔧 内置工具齐全：LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser
👥 AgentTeams（实验性）：TeamCreate、SendMessage、Task 持久队友、TeamFanout/TeamCollect 并行分工
📊 可观测性：JSONL + HTML 双轨 Trace、脱敏、token 统计、工具调用树
🔌 MCP 扩展：通过 mcp_servers.json 接入外部工具
🎓 学习友好：文档覆盖协议、上下文、截断、Trace、Skill、Task、交接说明

你将学到什么

MyCodeAgent 的定位与适用场景（学习 function calling、上下文工程、Skills/Task 子代理）
统一工具响应协议与 Function Calling 的落地方式
上下文工程：截断、压缩、持久化、@file 与落盘策略
Skills 目录约定与 SKILL.md 写法
Task 子代理类型与权限隔离
AgentTeams MVP：Team 工具、Task 三种模式（oneshot / persistent / parallel）
项目结构、环境变量、CLI 使用与多模型/多供应商配置
与 OpenCode、HelloAgent 等同类项目的对比与参考

前置知识

对 AI Agent、LLM 有基本概念
了解 Function Calling / Tool Use 更佳
本地运行需 Python 3.8+，可选配置智谱等兼容 OpenAI API 的供应商

项目背景

项目简介

MyCodeAgent 的副标题是 「Claude Code like agent for study」。它是一个面向学习与实验的代码代理框架，重点放在四件事上：

工具协议：如何定义、调用、响应工具，让行为可预期、可调试
上下文工程：如何截断、压缩、持久化对话与工具输出，控制 token 与成本
子代理机制：Skills、Task 子代理、AgentTeams 如何分工与协作
可观测性：Trace、日志、统计如何让「Agent 做了什么、为什么这样做」可追溯

目标可以概括为：让「Agent 能做什么」与「Agent 为什么能做」都可追溯、可验证、可扩展。

面向的用户：

想学习 function calling 与工具协议真实落地的开发者
研究上下文工程（截断、压缩、持久化）的工程师或学生
需要实验 Skills / Task 子代理协作的 Agent 开发者
想快速搭一个可扩展本地 Agent 试验场的学习者

作者/团队介绍

仓库：YYHDBL/MyCodeAgent（GitHub）
致谢：README 中致谢 Datawhale 的 HelloAgent、shareAI-lab 的 Kode-Cli、MiniMax-AI 的 Mini-Agent、anomalyco 的 opencode 等开源项目

项目数据

⭐ GitHub Stars: 约 105
🍴 Forks: 约 22
📦 仓库状态: 79 commits，持续维护
📄 License: MIT（可自由使用与二次开发）
📚 文档: 仓库内 docs/ 含工具协议、上下文工程、截断、Trace、Task、Skill、交接说明等

技术栈：Python 3.x、openai / pydantic / mcp / anyio、rich / prompt_toolkit。

主要功能

核心作用

MyCodeAgent 的核心作用是：提供一个可读、可改、可跑的「Claude Code 风格」代码代理实现，让你能：

学习工具协议：基于 Function Calling 的调用、统一响应格式（status/data/text/stats/context/error）
实践上下文工程：分层注入、历史压缩、@file 强制读取、超限结果落盘到 tool-output/
实验子代理与协作：Skills、Task 子代理、AgentTeams（Team + Task 持久/并行）
观察行为：Trace（JSONL + HTML）、token 统计、工具调用树、会话 /save 与 /load

从而在本地完成从「会用 Agent」到「能设计、实现、调试 Agent」的过渡。

使用场景

学习 Function Calling 与工具协议
- 看真实项目里工具如何注册、如何被 LLM 调用、响应如何被解析与展示
研究上下文工程
- 体验截断策略、压缩阈值、@file 注入、长输出落盘，理解对 token 与效果的影响
实验 Skills / Task 子代理
- 用 SKILL.md 挂载技能、用 Task 派发子代理（general/explore/plan/summary），观察主/轻量模型与权限隔离
体验 AgentTeams（实验性）
- 创建 Team、发送消息、用 Task 的 persistent/parallel 模式做多角色协作与并行分工
快速搭建本地 Agent 试验场
- 换模型、换供应商（如智谱）、接 MCP、加 Skill，快速迭代想法

快速开始

环境：Python 3.8+、pip。

# 克隆
git clone https://github.com/YYHDBL/MyCodeAgent.git
cd MyCodeAgent

# 虚拟环境（推荐）
python -m venv venv
source venv/bin/activate   # Linux/Mac
# .\venv\Scripts\activate  # Windows

# 依赖
pip install -r requirements.txt

配置：复制或创建 .env，配置例如：

# LLM
export OPENAI_API_KEY="your-api-key"
export DEFAULT_MODEL="gpt-4"
export TEMPERATURE="0.7"

# AgentTeams（可选，默认关闭）
export ENABLE_AGENT_TEAMS="true"

# 上下文
export CONTEXT_WINDOW="128000"
export COMPRESSION_THRESHOLD="0.8"

运行交互式 CLI：

python scripts/chat_test_agent.py

指定模型与供应商（如智谱）：

python scripts/chat_test_agent.py \
  --provider zhipu \
  --model GLM-4.7 \
  --api-key YOUR_API_KEY \
  --base-url https://open.bigmodel.cn/api/coding/paas/v4

调试时查看原始输出：

python scripts/chat_test_agent.py --show-raw

核心特性

Function Calling 工具调用
- 不依赖「Action 文本解析」，直接使用 LLM 的 function/tool 调用能力，行为更稳定、可追溯
统一工具响应协议
- 工具返回统一结构：status / data / text / stats / context / error，便于解析、展示与日志
内置工具
- LS / Glob / Grep / Read / Write / Edit / MultiEdit / Bash / TodoWrite / Skill / Task / AskUser 等，覆盖常见文件与执行需求
AgentTeams MVP（实验性）
- TeamCreate / SendMessage / TeamStatus / TeamDelete；Task 支持 oneshot、persistent（teammate）、parallel（fanout）；TeamFanout / TeamCollect 做并行分工与结果收集
上下文工程
- 分层注入、历史压缩、@file 强制读取；超限工具输出写入 tool-output/，避免撑爆上下文
轻量熔断
- 连续失败的工具会被临时禁用，减少无效重试
Trace 追踪
- JSONL + HTML 双轨日志、脱敏、可选包含原始响应，便于复现与调试
会话持久化
- 支持 /save 与 /load，便于长时间会话与复现
MCP 扩展
- 通过 mcp_servers.json 配置并接入外部 MCP 工具
Enhanced CLI UI
- 工具调用树、token 统计、进度显示，提升可读性

项目优势

对比项	MyCodeAgent	纯黑盒 Agent 产品	仅 Demo 型项目
工具协议	统一响应协议 + Function Calling	多为内部实现	常无规范
上下文工程	截断/压缩/落盘/@file 可配置	多不可见	简单或缺失
可观测性	Trace JSONL/HTML、脱敏、统计	有限或无	多为 print
子代理/协作	Skills + Task + AgentTeams	视产品而定	少有
文档	协议/上下文/截断/Trace/Skill/Task 等	多为使用说明	较少
定位	学习与实验	生产/产品	演示为主

为什么选 MyCodeAgent？

代码与文档都围绕「可追溯、可验证、可扩展」设计，适合学习 Agent 内部机制
工具协议、上下文、Trace 有专门文档，便于二次开发与教学
内置 Skills / Task / AgentTeams，便于做多角色与协作实验
MIT 协议，可自由修改与集成

项目详细剖析

架构与目录结构

README 给出的结构概览如下：

agents/           主代理实现
core/             核心运行时与上下文工程
tools/            工具系统与注册表
prompts/          系统提示词与工具提示词
docs/             设计与协议文档
scripts/          CLI 入口（如 chat_test_agent.py）
tests/            测试集
memory/           trace、session 输出（本地）
tool-output/      长输出落盘目录
mcp_servers.json  MCP 工具配置

agents/：主 Agent 的调度、轮次、工具调用流程
core/：上下文构建、压缩、截断、注入（含 @file）
tools/：工具注册、执行、统一响应封装
prompts/：系统 prompt、工具描述等，影响 LLM 行为

工具协议与 Function Calling

工具通过 Function Calling 暴露给 LLM，不依赖从自然语言里解析「Action」
工具返回遵循统一协议，包含但不限于：
- status：成功/失败等
- data / text：结构化或文本结果
- stats / context：统计或上下文信息
- error：错误信息

这样便于：

前端/CLI 统一展示
Trace 中完整记录
后续做重试、熔断、统计

文档入口：docs/通用工具响应协议.md。

上下文工程

分层注入：系统提示、工具描述、历史消息等分层组织，控制进入上下文的内容
历史压缩：当历史过长时按策略压缩（如摘要、截断），相关环境变量包括 CONTEXT_WINDOW、COMPRESSION_THRESHOLD、MIN_RETAIN_ROUNDS、SUMMARY_TIMEOUT
@file 强制读取：用户通过 @file 引用时，保证对应内容被加入上下文
工具输出截断与落盘：单次工具输出过长时截断（head/tail/head_tail），超限部分写入 tool-output/，避免占满 context

文档入口：docs/上下文工程设计文档.md、docs/工具输出截断设计文档.md。

Skills 机制

约定目录：skills/<skill-name>/SKILL.md
SKILL.md 示例结构：

---
name: code-review
description: Review code quality and risks
---
# Code Review

Use this checklist:
- ...

$ARGUMENTS

$ARGUMENTS 会被 Skill 工具传入的 args 替换，从而把「技能说明 + 参数」一起注入上下文。

文档入口：docs/skillTool设计文档.md。

Task 子代理（MVP）

子代理类型：general / explore / plan / summary 等，用于不同复杂度的子任务
模型选择：主代理可用 main / light 模型，子代理可配置为轻量模型以节省成本
权限隔离：子代理可配置为只读或受限工具集，保证安全与可控

文档入口：docs/task(subagent)设计文档.md。

AgentTeams（实验性）

开关：ENABLE_AGENT_TEAMS=true（默认关闭），便于回滚
Team 工具：TeamCreate / SendMessage / TeamStatus / TeamDelete
并行分工：TeamFanout / TeamCollect；Task 的 mode=parallel 配合 tasks 列表
Task 模式：
- oneshot：单次子任务（默认，兼容旧行为）
- persistent：创建持久 teammate（team_name + teammate_name）
- parallel：一次性派发多个任务（team_name + tasks）
状态：消息 ACK（pending/delivered/processed）、work item（queued/running/succeeded/failed/canceled）

最小示例（交互中由主代理触发）：

TeamCreate(team_name="demo")
Task(mode="persistent", team_name="demo", teammate_name="dev", ...)
SendMessage(team_name="demo", from_member="lead", to_member="dev", text="...")
TeamStatus(team_name="demo")
TeamDelete(team_name="demo")

快速回滚：将 ENABLE_AGENT_TEAMS 设为 false 或删除该环境变量。

Trace 与可观测性

Trace 输出：JSONL + HTML 双轨，可选脱敏、可选包含原始 LLM 响应
环境变量：如 TRACE_ENABLED、TRACE_DIR、TRACE_SANITIZE、TRACE_HTML_INCLUDE_RAW_RESPONSE
便于复现问题、分析 token 与调用链

文档入口：docs/TraceLogging设计文档.md。

MCP 集成

在项目根目录配置 mcp_servers.json，以命令式启动 MCP 服务，例如：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "some-mcp-server", "--api-key", "${API_KEY}"]
    }
  }
}

即可在 Agent 中使用该 MCP 提供的工具。

关键环境变量小结

README 中列出的主要类别：

Context / 历史：CONTEXT_WINDOW、COMPRESSION_THRESHOLD、MIN_RETAIN_ROUNDS、SUMMARY_TIMEOUT
工具输出截断：TOOL_OUTPUT_MAX_LINES、TOOL_OUTPUT_MAX_BYTES、TOOL_OUTPUT_TRUNCATE_DIRECTION、TOOL_OUTPUT_HEAD_TAIL_LINES、TOOL_OUTPUT_DIR、TOOL_OUTPUT_RETENTION_DAYS
Skills：SKILLS_REFRESH_ON_CALL、SKILLS_PROMPT_CHAR_BUDGET
Subagent：SUBAGENT_MAX_STEPS、LIGHT_LLM_MODEL_ID / LIGHT_LLM_API_KEY / LIGHT_LLM_BASE_URL
AgentTeams：ENABLE_AGENT_TEAMS、AGENT_TEAMS_STORE_DIR、AGENT_TASKS_STORE_DIR
Trace：TRACE_ENABLED、TRACE_DIR、TRACE_SANITIZE、TRACE_HTML_INCLUDE_RAW_RESPONSE

项目地址与资源

官方资源

🌟 GitHub: github.com/YYHDBL/MyCo…
📚 文档：仓库内 docs/
- 工具协议：docs/通用工具响应协议.md
- 上下文工程：docs/上下文工程设计文档.md
- 工具输出截断：docs/工具输出截断设计文档.md
- Trace：docs/TraceLogging设计文档.md
- Task 子代理：docs/task(subagent)设计文档.md
- Skill：docs/skillTool设计文档.md
- 交接说明：docs/DEV_HANDOFF.md
🐛 Issue Tracker: GitHub Issues

参考资源（README 致谢）

Datawhale HelloAgent 教程
shareAI-lab Kode-Cli
MiniMax-AI Mini-Agent
anomalyco opencode

适用人群

想学习 Function Calling、工具协议、上下文工程、Trace 的开发者
需要实验 Skills、Task 子代理、多角色协作（AgentTeams）的 Agent 开发者
希望有一个可读、可改、可跑的 Claude Code 风格参考实现的学习者
打算在本地搭可扩展 Agent 试验场、接 MCP、换模型/供应商的团队

欢迎来我中的个人主页找到更多有用的知识和有趣的产品