learnNote

主题

miniClaudeCode -- 从 0 到 1 构建 nano Claude Code-like Agent ​

精简自 learn-claude-code，仅保留 Python Agent 核心代码和教学文档。

                THE AGENT PATTERN
                =================

    User --> messages[] --> LLM --> response
                                      |
                            stop_reason == "tool_use"?
                           /                          \
                         yes                           no
                          |                             |
                    execute tools                    return text
                    append results
                    loop back -----------------> messages[]


    这是最小循环。每个 AI 编程 Agent 都需要这个循环。
    生产级 Agent 还会叠加策略、权限与生命周期层。

12 个递进式课程 ​

课程主题格言
s01Agent 循环Bash 就够了
s02工具循环没有变
s03TodoWrite先计划再行动
s04子智能体进程隔离 = 上下文隔离
s05Skills按需加载, 而非预装
s06Compact策略性遗忘
s07任务系统状态在压缩后存活
s08后台任务发射后不管
s09智能体团队追加即发送, 排空即读取
s10团队协议同一个 request_id, 两个协议
s11自治智能体轮询, 认领, 工作, 重复
s12Worktree + 任务隔离目录隔离, 任务 ID 协调

快速开始 ​

sh
cd miniClaudeCode
pip install -r requirements.txt
cp .env.example .env   # 或直接编辑 .env，填入 API Key 和模型配置

python agents/s01_agent_loop.py        # 最小 Agent 循环
python agents/s02_tool_use.py          # 多工具分发
python agents/s_full.py                # 完整参考 Agent（合并 s01-s11）
python agents/s12_worktree_task_isolation.py  # Worktree 隔离

项目结构 ​

miniClaudeCode/
├── .env                 # API Key 和模型配置（不要提交到 Git）
├── .gitignore
├── requirements.txt     # Python 依赖
├── README-zh.md         # 本文件
├── agents/              # Python 教学 Agent（s01-s12 + 完整版 s_full）
│   ├── s01_agent_loop.py        # 最小循环
│   ├── s02_tool_use.py          # 多工具分发
│   ├── s03_todo_write.py        # TodoManager + nag 提醒
│   ├── s04_subagent.py          # 子智能体
│   ├── s05_skill_loading.py     # 技能按需加载
│   ├── s06_context_compact.py   # 三层上下文压缩
│   ├── s07_task_system.py       # 文件持久化任务
│   ├── s08_background_tasks.py  # 后台线程 + 通知
│   ├── s09_agent_teams.py       # 团队 + JSONL 邮箱
│   ├── s10_team_protocols.py    # 关机 + 计划审批
│   ├── s11_autonomous_agents.py # 自治智能体
│   ├── s12_worktree_task_isolation.py # Worktree 隔离
│   └── s_full.py                # 综合参考（合并 s01-s11）
├── .skills/             # s05 使用的技能文件
├── skills/              # s_full 使用的技能文件
└── docs/{en,zh,ja}/     # 每课配套文档（三种语言）

支持的模型 ​

在 .env 中配置，支持所有兼容 Anthropic API 的提供商：

提供商MODEL_ID备注
Anthropicclaude-sonnet-4-6默认（无需 BASE_URL）
DeepSeekdeepseek-chat国内外统一端点
MiniMaxMiniMax-M2.5国内/国际端点不同
GLM (智谱)glm-5国内/国际端点不同
Kimi (月之暗面)kimi-k2.5国内/国际端点不同

文档 ​

心智模型优先: 问题、方案、ASCII 图、最小化代码。

许可证 ​

MIT

模型就是智能体。我们的工作就是给它工具, 然后让开。