# agent-builder
**Repository Path**: yegetaier/agent-builder
## Basic Information
- **Project Name**: agent-builder
- **Description**: 基于Claude Agent SDK，使用markdown编排，实现主子架构的自主智能体。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 🧩 agent-builder
### 把可描述、可流程化的 SOP 写成 Markdown，就能跑出一条多 Agent 协作的工作流
**业务逻辑写在 Markdown 里，引擎通用不改一行代码。**
审核判定、内容创作、研究汇总、批量自动化…… —— 同一套引擎，换一套 `Markdown + 技能` 就能跑，几小时上线一个新 Agent。
[](https://www.python.org/)
[](https://docs.claude.com/en/api/agent-sdk)
[](#-60-秒看懂工作原理)
[](#-核心能力)
[](LICENSE)
**简体中文** ｜ [English](README.en.md)
---
> ### 一句话
> 凡是 **「可描述、可流程化、可 SOP」** 的业务 —— 既包括**判定类**（风险审核、合规审查、材料初筛、简历筛选、工单分级、内容审核……），也包括**生成 / 执行类**（写一篇文章并发布、生成一条短视频、出一份带引用的研究简报、批量产出文案、串起一条数据处理流水线……）—— 你都可以**只写 Markdown + 技能（Skill）**，复用本项目的通用引擎，跑成一个多 Agent 协作的工作流，输出**结构化结果**（内置判定 schema，或你自定义的产出结构）。
---
## 😫 你是不是也遇到过这些
- **流程天天变，每次改都要改代码、发版、等开发排期。** 想调一条规则 / 一个步骤，得开一张需求单等一周。
- **一个巨型 prompt 越塞越乱。** 步骤越加越多、多份材料顾此失彼，改 A 处坏 B 处，没人敢动。
- **输出格式靠运气。** 这次返回 JSON，下次夹带一段废话，解析代码天天打补丁；LLM 一抽风，整条链路直接崩。
- **懂业务的不写代码，写代码的不懂业务。** 业务专家把 SOP 讲得头头是道，却落不进系统；开发照着抄，细节全靠猜。
**agent-builder 把这件事反过来：让业务流程回到它本来该在的地方 —— 一份人人能读、能改、能评审的 Markdown。**
---
## 💡 它是什么
一套基于 [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk) 的**多 Agent 工作流编排骨架**，把「主协调器（Master）按流程调度若干专精子 Agent、各自产出、再汇总成结构化结果」这一范式，固化成一个**开箱即用、业务无关**的通用引擎。
```
你写这里 ✍️ 引擎搞定 ⚙️（不用改）
┌────────────────────┐ ┌──────────────────────────────┐
│ task.yaml │ │ 驱动 Claude Agent SDK │
│ master/CLAUDE.md │ ───────▶ │ 按流程调度子 Agent · 超时重试 │
│ sub_agents/*.md │ │ 结构化校验 · 异常兜底 │
│ skills/*（可选） │ │ │
└────────────────────┘ └──────────────────────────────┘
纯 Markdown + 技能的业务流程 framework/ 通用内核
```
- **引擎（`framework/`）业务无关**：负责驱动 SDK、按你的 Markdown 调度子 Agent、超时重试、结构化校验、异常兜底。**一般一行都不用改。**
- **任务（`tasks//`）是纯 Markdown**：`master/CLAUDE.md` 写编排与决策规则，`sub_agents//CLAUDE.md` 写每个专精子 Agent 的职责，一个 `task.yaml` 把它们串起来。
- **技能（`skills/`）= 能力与动作的来源**：读文件、调外部 API、生成内容、发布到某平台…… 都是一个「脚本 + SKILL.md」的技能，子 Agent 在 `task.yaml` 里按白名单 opt-in。**这就是把"会判断"的 Agent 变成"能干活"的 Agent 的开关。**
> 📦 **开箱即跑的样板**是**简历筛选**（一个判定类 SOP）：Master 把每份简历分发给 `resume-parser` 解析，再分发给 `fit-evaluator` 对照 JD 打分，最后汇总出每位候选人的判定与整体推荐。它演示的"调度 → 专精 → 汇总"范式，对生成 / 执行类 SOP 同样成立 —— 见 [👉 不止审核](#-不止审核还能做什么)。
---
## ⭐ 核心能力
| 能力 | 说明 |
| --- | --- |
| 📝 **Markdown 即编排** | task.yaml + CLAUDE.md 定义整条多 Agent 工作流，**判定类任务默认零 Python**。业务同学改 Markdown 就能上线 / 调流程。 |
| 🧠 **Master + 专精子 Agent** | 主协调器按流程调度、汇总；子 Agent 各管一段（取数 / 生成 / 校验 / 判断）。任何能拆成步骤的 SOP 都能拆得开、说得清、加得上。 |
| 🎯 **结构化输出，强约束** | JSON Schema 锁死输出。内置通用判定 schema（`PASS / REJECT / REVIEW` + 逐对象 `items` + 逐维度 `dimensions`，每条都带理由）；**任何其它产出**（文章、报告、文案、生成物的地址……）只需在 `task.yaml` 指向你自己的 schema。 |
| 🔌 **可插拔技能 = 能干活** | 内置 `reading-files`（读 PDF/Word/Excel/图片 + OCR，本地与 URL 通吃）。要发布、要调用生成 API、要联网取数？**自己写一个 Skill**（脚本 + SKILL.md），子 Agent 通过 Bash 调用 —— 和 demo 读文件是同一套机制。 |
| 🛟 **永不崩的兜底** | 单次会话硬超时 + 自动重试（退避间隔逐次递增）；**任何异常都兜底成一个 schema 合法的结果**（判定类任务兜底为 `REVIEW`），上游永远拿到合法回包，不会因 LLM 抽风而崩。 |
| 🔍 **所见即所得** | 每次运行在 `.runs//` 重建工作区 —— 那就是 SDK 实际看到的全部上下文，排障时一眼到底。 |
| 🔄 **模型无关** | 走 Anthropic 兼容端点，默认接智谱 GLM；换模型 / 换厂商只改 `.env` 两行。 |
| 🌐 **可选联网能力** | 配上 `SERPER_API_KEY` 即获 Google 搜索，加上内置 `WebFetch` 抓网页 —— 框架提供联网管道，怎么用由你的 Markdown 决定。 |
| 🧬 **会自进化** | 从**人工反馈**中自动蒸馏「特殊规则」并沉淀复用 —— 经验 / 技能 / 规则三重沉淀，基础 SOP 不变、**越用越准**。`run --evolve` 开启，详见下方「会自进化」一节。 |
---
## 🕐 60 秒看懂工作原理
```
$ python cli.py run -i input.json
│
▼
framework.run_task(task, input)
├─ ① 读 tasks//task.yaml + 各 CLAUDE.md（早校验，缺文件立即报错）
├─ ② 把输入里的相对文件路径改写成绝对路径（技能稳定可读）
├─ ③ 装配工作区：把 Markdown + 声明的 skills 拷进 .runs//
├─ ④ 取结果 JSON Schema（默认通用判定 schema，可被 task.yaml 指向你的自定义 schema）
└─ ⑤ 构造 SDK options（cwd=master、注册子 Agent、output_format=结果 schema）
│
▼
MasterAgent 驱动 Claude Agent SDK：
Master 按 master/CLAUDE.md 调度子 Agent ──▶ 子 Agent 各自产出
（子 Agent 可调用白名单内技能：读文件 / 调 API / 生成 / 发布 / 联网……）
──▶ Master 汇总 ──▶ StructuredOutput
│
▼
结构化结果（默认判定结果，或你自定义的产出结构）
```
**关键心智模型**：业务流程全在 Markdown 里、动作全在技能里；Python 引擎是通用的「放映机」，把它们喂给 Claude Agent SDK 跑起来。想改流程？改 Markdown，不碰代码。
---
## 🎯 什么场景该用它
判断只需一句话：
> ### 「这件事能不能写成一份**可复用的 SOP 手册**，交给一个新人照着一步步做出来？」
> 能 → 它就是为你造的。**结论是"通过 / 不通过"可以，产出是"一篇文章 / 一段视频 / 一份报告"也可以。**
| 适合 ✅ | 例子 |
| --- | --- |
| 流程能用文字讲清楚、可拆成步骤 | 「先读文件抽字段，再按规则核验」「先研究选题、再拟纲、再成文」 |
| 要稳定的结构化产出 | 判定结果、或一篇带字段的文章、一份带引用的报告 —— 都要能被下游直接消费 |
| 多份材料 / 多个对象 / 多个镜头横向处理 | 多份单据交叉校验、多名候选人排序、多镜头逐个生成 |
| 需要可解释、可复核 | 每一步、每条结论都有迹可循 |
| 能容忍秒级~分钟级延迟 | 异步处理 / 批处理，不卡在用户同步点击路径上 |
**不适合 ❌**：一句 prompt 就能解决、不值得编排的一次性小事；流程完全说不清、纯临场主观发挥、无法沉淀成步骤的事；毫秒级强实时链路。
> 💡 关于"动作 / 副作用"：子 Agent 默认**不授予** `Write/Edit/MultiEdit`（避免乱改文件）。真正要"产出文件 / 调用生成 API / 发布"时，通过你显式授予的**技能 / Bash / MCP**来完成 —— 能力是你主动装上去的，而不是放任 Agent 乱来。
📊 和「直接调一次 LLM」相比，省在哪？
| | 直接调一次 LLM | agent-builder |
| --- | --- | --- |
| 流程维护 | 塞进一个巨型 prompt，越改越乱 | 拆进多份 Markdown，分层清晰 |
| 多材料 / 多步骤 | 容易顾此失彼 | 每段一个子 Agent，互不干扰 |
| 结果可靠性 | 输出格式靠运气 | JSON Schema 强约束 + 异常兜底 |
| 可解释性 | 一段话 | 每步 / 每对象都有结构化记录 |
| 扩展性 | 改 prompt | 加一个子 Agent / 加一个技能（= 加 Markdown / 加脚本） |
只是「问一句答一句」？本框架是杀鸡用牛刀。一旦涉及**多步骤、多材料、要可解释、要稳定结构化产出**，它就开始显著省事。
---
## ✨ 不止审核：还能做什么
审核只是其中一类。同一套「Master 调度 + 专精子 Agent + 结构化产出」范式，**换一套 Markdown + 技能（+ 可选自定义 schema）**就能跑别的 SOP：
| 你想做的事 | 怎么拆成子 Agent（示例） | 产出 / 落地方式 |
| --- | --- | --- |
| ✍️ **写一篇文章并发布** | 选题研究 → 拟提纲 → 撰写 → 校对润色 →（发布） | 文章正文（自定义 schema）；发布由一个 `publish` 技能调平台 API |
| 🎬 **生成一条短视频** | 写脚本 → 分镜 → 逐镜头生成 → 配音 → 合成 | 视频文件 / URL；生成由 `video-gen` 技能调外部生成 API |
| 📑 **出一份研究简报** | 多源检索（联网）→ 交叉验证 → 汇总成稿（带引用） | 结构化报告（自定义 schema） |
| 🗂️ **批量生成营销文案** | 按产品并行生成 → 统一风格校对 | 文案集合（自定义 schema） |
**关键点**：在这些任务里，「**动作**」（发布、调用生成 / 检索 API）由你写的 **Skill** 承担 —— 和 demo 里 `reading-files` 读文件是同一套机制；「**产出结构**」由你的 **schema** 描述；而**调度、并行、重试、兜底**仍然由通用引擎负责。你依旧只写 `Markdown + 技能（+ 可选 schema）`，不碰引擎。
> 本仓库内置的 demo 与默认 schema 面向判定类任务；上面这些生成 / 执行类玩法需要你按 [docs/create-a-new-task.md](docs/create-a-new-task.md) 写自己的 Markdown、技能与（如需）schema —— 范式完全一致。
---
## 🧬 会自进化：经验 · 技能 · 规则，三重沉淀
别的 Agent 跑完就忘；agent-builder 把每一次运行都**沉淀成资产**，越用越聪明。
| 三重沉淀 | 沉淀什么 | 怎么来 | 收获 |
| --- | --- | --- | --- |
| 🗄️ **经验沉淀** | 每次运行的输入、结构化判定、子 Agent 推理轨迹 → 可追溯 `episode` | **自动**（开 `--evolve` 即捕获，无需人工） | 越用越懂你的业务 |
| 🧩 **技能沉淀** | 每写一个技能（脚本 + `SKILL.md`）→ 全任务、全 Agent 复用 | 人工写一次，处处复用 | 越用越能干 |
| 📋 **规则沉淀** | 每条人工反馈 → 自动蒸馏成带条件、带置信度的结构化规则 | **人工反馈驱动** | 越用越准 |
**两层分离**：公共 / 基础 SOP 留在 `CLAUDE.md`（人写、版本化、**永远权威**）；**特殊规则**从「运行轨迹 + 人工反馈」蒸馏出来，沉淀后下次运行**自动召回、注入**到基础之上 —— 基础不变，特殊经验自动生长。
**闭环（人工只给反馈，其余全自动）**：
```
运行(--evolve) → 注入已沉淀规则 + 捕获 episode → 人工复核给反馈
→ 自动蒸馏候选规则 → 沉淀(advisory) → 下次运行自动召回复用 → 置信度维护
```
```bash
# 1) 开启自进化跑任务（运行结束自动捕获 episode，无需人工）
python cli.py run resume-screening -i examples/resume-screening/input.json --evolve
# → 末尾打印「📌 已捕获 episode=ep_xxx」；忘了可用 `python cli.py episodes list --task resume-screening` 查
# 2) 人工复核后给一次反馈（ep_xxx 换成上一步的 id）—— 之后蒸馏 + 沉淀全自动，不需要另起命令
python cli.py feedback ep_xxx --task resume-screening \
--subject 张三 --corrected REJECT --comment "无相关经验"
# → 已记录反馈 → 自动蒸馏并沉淀规则 rule_xxx（advisory · 置信度 0.60，下次运行起自动召回复用）
# 3)（可选）治理规则：查看 / 升级 / 调置信度 / 退役 / 体检
python cli.py rules list --task resume-screening
python cli.py rules promote # advisory → active
python cli.py rules outcome --contradicted # 后续被证伪 → 降置信度
python cli.py rules lint --task resume-screening
```
> **安全可控**：人工闸门（`proposed → advisory → active`）+ 注入前防提示注入消毒 + 作用域隔离（规则绑到具体子 Agent / 维度）+ 置信度随反馈升降、坍塌自动退役 + 一键回滚（规则是 git 文件）。**基础 SOP 永远权威**，学习规则只是作用域内的例外 / 细化。
>
> 默认关闭（`--evolve` 显式开启），不影响普通运行。基于 [claude-mem](https://docs.claude-mem.ai/) 的本地记忆范式，融合 Reflexion / ExpeL / Meta-Policy Reflexion；设计详见 [docs/superpowers/specs/2026-06-14-agent-self-evolution-design.md](docs/superpowers/specs/2026-06-14-agent-self-evolution-design.md)。
---
## 🚀 使用手册（新手 5 分钟跑通）
> 🤖 **在用 AI 编程助手（Claude Code / Cursor / Cline…）？** 把仓库里的 **[use-agent-install.md](use-agent-install.md)** 整个发给它 —— 它会自动装依赖、配密钥、跑通 demo，并按你的描述改造成新任务。你只需在它要密钥时把 GLM Key 交给它。
>
> 下面是**手动版**：跟着 7 步走，零基础也能跑通、看懂、验证。命令均可直接复制粘贴。
### ✅ 开跑前，先备齐这几样
| 你需要 | 干嘛用 | 怎么拿 / 自检 |
| --- | --- | --- |
| **Python ≥ 3.10** | 运行环境 | 终端跑 `python3 --version`；没有就去 [python.org](https://www.python.org/downloads/) 装 |
| **智谱 GLM API Key** | **唯一必填**密钥 | 到 [open.bigmodel.cn](https://open.bigmodel.cn/) 免费注册 → 控制台「API Keys」→ 新建，复制形如 `xxxxxxxx.yyyyyyyy` 的串 |
| **git**（可选） | 拉代码 | `git --version`；没有也行 —— 在仓库页点「下载 ZIP」解压即可 |
> ⚠️ 跑 demo 会发起**真实、计费**的 GLM 调用（一次通常几分钱）。示例简历是纯文本 PDF，**happy path 不需要 OCR 或任何其它密钥**。
### 第 1 步 · 拿到代码
```bash
git clone https://gitee.com/yegetaier/agent-builder.git
cd agent-builder
```
> 没装 git？在仓库页下载 ZIP，解压后用终端 `cd` 进入该目录即可。
### 第 2 步 · 建好并激活虚拟环境
```bash
# macOS / Linux
python3 -m venv .venv && source .venv/bin/activate
# Windows（PowerShell）
python -m venv .venv ; .venv\Scripts\Activate.ps1
```
> 激活成功后，命令行最前面会出现 `(.venv)` 字样。**之后每开一个新终端，都要重新 `activate`。**
### 第 3 步 · 安装依赖
```bash
pip install -r requirements.txt
```
> 装得慢 / 失败？换国内镜像重装：`pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`
### 第 4 步 · 填入你的 API Key
```bash
cp .env.example .env # Windows: copy .env.example .env
```
用任意编辑器打开 `.env`，把密钥填到这一行（等号后**直接粘贴**，不要加引号）：
```ini
GLM_API_KEY=在这里粘贴你的智谱密钥
```
> 整个文件**只有 `GLM_API_KEY` 必填**，其余项都有默认值。框架会自动把它桥接成 SDK 需要的 `ANTHROPIC_API_KEY` 并指向智谱端点 —— 你不用操心。
### 第 5 步 · 生成示例数据
```bash
python examples/resume-screening/make_sample_resumes.py
```
> 会在 `examples/resume-screening/resumes/` 下生成 3 份示例简历 PDF（张三 / 李四 / 王五）。
### 第 6 步 · 跑通内置 demo
```bash
python cli.py list # ① 先看看有哪些任务
python cli.py run resume-screening -i examples/resume-screening/input.json # ② 跑「简历筛选」
```
### 第 7 步 · 看懂并验证结果
跑完后，终端会打印一段结构化 JSON（节选）：
```json
{
"result": "PASS",
"reason": "3 名候选人中 1 人完全匹配，推荐张三进入面试；王五待定、李四不通过。",
"items": [
{"subject": "张三", "result": "PASS", "score": 90, "reason": "本科 + 6 年后端 + Python/MySQL/Redis 全覆盖",
"dimensions": [{"name": "核心技能", "result": "PASS", "score": 95, "reason": "..."}]},
{"subject": "王五", "result": "REVIEW", "score": 45, "reason": "简历过简，缺学历与工作年限，需人工"},
{"subject": "李四", "result": "REJECT", "score": 20, "reason": "命中一票否决：无任何后端开发经验，学历大专"}
]
}
```
**怎样算「验证通过」？逐条对照：**
- ✅ 顶层有 `result`（`PASS` / `REVIEW` / `REJECT`）和一句 `reason`
- ✅ `items` 里**每位候选人**都有自己的判定、`score`、`reason`，以及逐维度的 `dimensions`
- ✅ 语义合理：张三 ≈ `PASS`、李四 ≈ `REJECT`（命中「无后端经验」一票否决）、王五 ≈ `REVIEW`（资料太少、需人工）
- ✅ 打开 `.runs/resume-screening/` 目录，能看到这次运行 SDK **实际看到的全部上下文**（Markdown + 技能 + 输入）—— 排障时所见即所得
> 💡 LLM 有创造性，分数 / 措辞每次略有不同属正常；只要**结构合法**且**三人判定方向大致正确**，就说明你已经跑通。
### （可选）第 8 步 · 让它「越用越准」
demo 跑通后，想让 Agent 从你的纠偏中自我进化？见上文 [🧬 会自进化](#-会自进化经验--技能--规则三重沉淀)：`--evolve` 跑一次 → `feedback` 给一次反馈 → 规则自动沉淀，下次运行自动复用。
### 🆘 卡住了？常见问题排查
| 现象 / 报错 | 多半是因为 | 怎么解决 |
| --- | --- | --- |
| `运行时配置校验失败：缺少 GLM_API_KEY` | `.env` 没填密钥 | 回到第 4 步，把密钥填进 `GLM_API_KEY=` |
| `401` / `令牌已过期或验证不正确` | 密钥不对，或机器上有更高优先级的 Anthropic 凭证 | 先确认密钥正确；框架已自动清理 Claude Code 的 `ANTHROPIC_AUTH_TOKEN` / OAuth，若仍报错，检查 shell 里有没有手动设过 `ANTHROPIC_API_KEY=""` 之类的空值 |
| `command not found: python` | 你的系统命令叫 `python3` | 把命令里的 `python` 换成 `python3` |
| 命令行没有 `(.venv)` 前缀 | 虚拟环境没激活 | 重跑第 2 步的 `activate`（每个新终端都要） |
| `pip install` 卡在 PyMuPDF / Pillow | 网络慢或缺编译环境 | 用上面的清华镜像重装 |
| 结果整体兜底成 `REVIEW`、`reason` 像「系统异常」 | LLM 调用超时 / 失败 / 额度不足 | 查网络与密钥余额；到 `.runs/resume-screening/` 看实际报错 |
| Windows 激活报「无法加载…执行策略」 | PowerShell 默认禁止脚本 | 先跑 `Set-ExecutionPolicy -Scope Process RemoteSigned`，再激活 |
跑通之后，下一节教你把它**改造成你自己的任务**。
---
## 🛠️ 造一个你自己的任务（判定类默认零 Python）
**判定类示例（报销单审核）**：
```bash
cp -r tasks/resume-screening tasks/reimbursement-audit # ① 复制 demo 作骨架
```
```yaml
# ② 改 task.yaml：声明你的子 Agent 和它们能用的技能
name: reimbursement-audit
title: 报销单审核
description: 审核报销单与配套发票，核对金额一致性与合规性，输出 PASS/REVIEW/REJECT。
sub_agents:
- key: invoice-parser # 要读文件 → 给它 reading-files
description: 发票解析专家——读取单张发票，抽取金额/开票方/日期/税号等字段。
skills: [reading-files]
- key: compliance-checker # 纯推理 → 不给技能
description: 合规核验专家——对照报销单与发票，核对金额一致性与报销规则。
skills: []
```
```text
③ 重写两类 Markdown：
• master/CLAUDE.md —— 输入结构 / 调度顺序 / 汇总决策 / 输出约定
• sub_agents//CLAUDE.md —— 每个子 Agent 的角色、要做的事、降级规则
④ python cli.py run reimbursement-audit -i path/to/input.json
```
**生成类示例（文章撰写）** 的差异只有两处：
- **加一个"动作"技能**：写 `skills/publish/`（`SKILL.md` + 一个调用平台 API 的脚本），在某个子 Agent 的 `skills:` 里登记它（和 `reading-files` 完全一样）。
- **指定产出 schema**：在任务目录写一个 `schema.py`（Pydantic 模型，如 `{title, body_markdown, tags, status}`），在 `task.yaml` 里 `schema: schema.py:ArticleResult` 指向它。
```yaml
# task.yaml（节选）
sub_agents:
- key: researcher # 联网检索选题素材
skills: [] # 用内置 WebFetch / Serper
- key: writer # 按提纲撰写
skills: []
- key: publisher # 调平台 API 发布
skills: [publish] # ← 你写的动作技能
schema: schema.py:ArticleResult # ← 你的产出结构
```
> 经验法则：**凡是「取数 / 生成 / 调外部 API」的环节，独立成一个子 Agent 并配上对应技能；「做判断 / 汇总」的环节，再独立一个。** 子 Agent 越聚焦，越好写、越稳。
>
> 📌 三处名字要一致：任务**目录名** = `task.yaml` 的 `name` = `cli.py run ` 里的参数。
📖 手把手详解见 **[docs/create-a-new-task.md](docs/create-a-new-task.md)**。
---
## 📁 项目结构
```
agent-builder/
├── framework/ # ★ 通用引擎（业务无关，一般不改）
│ ├── runner.py # 高层入口 run_task()
│ ├── master_agent.py # 驱动 SDK：调度 / 重试 / 超时 / 结构化 / 兜底
│ ├── options.py # 组装 ClaudeAgentOptions（工具 / 域名 / MCP / 输出 schema）
│ ├── agent_definitions.py# 从 CLAUDE.md 构造子 Agent
│ ├── workspace.py # 把任务资产装配进可运行工作区
│ ├── task.py # task.yaml 清单加载
│ ├── schemas.py # 通用结果 TaskResult + 校验（可被任务自定义 schema 覆盖）
│ ├── config.py # .env 加载（GLM → Anthropic 桥接）
│ └── evolution/ # 🧬 自进化层：episodes / rules / feedback + 注入 / 治理 / 蒸馏
├── skills/ # 共享技能库（任务按名 opt-in）—— 读文件 / 动作 / 生成 的来源
│ └── reading-files/ # 读 PDF/Word/Excel/图片（+OCR），本地路径与 URL 通吃
├── tasks/ # ★ 你真正复制 / 编辑的地方
│ └── resume-screening/ # demo：简历筛选（判定类）
│ ├── task.yaml
│ ├── master/CLAUDE.md
│ └── sub_agents/{resume-parser,fit-evaluator}/CLAUDE.md
├── examples/ # demo 输入 + 示例简历 + 简历生成脚本
├── cli.py # 命令行入口（list / run / feedback / episodes / rules）
├── use-agent-install.md # 🤖 发给 AI Agent：自动安装 / 运行 / 改造本项目
├── tests/ # 测试套件（mock SDK，不打真实 GLM）
└── docs/ # 详细文档（见下）
```
---
## 📚 文档
| 文档 | 解决什么问题 |
| --- | --- |
| [use-agent-install.md](use-agent-install.md) | 🤖 **给 AI Agent 的安装运行手册**：发给 Claude Code / Cursor 等，自动装好、跑通、并帮你改造成新任务 |
| [docs/when-to-use.md](docs/when-to-use.md) | 什么场景适合 / 不适合用它（含判断清单） |
| [docs/how-it-works.md](docs/how-it-works.md) | 架构与一次运行的完整数据流（含「我想改 X 该动哪里」对照表） |
| [docs/create-a-new-task.md](docs/create-a-new-task.md) | **手把手**：复制 demo → 改 Markdown → 跑起来，造你自己的任务 |
| [docs/writing-claude-md.md](docs/writing-claude-md.md) | 怎么写好 Master / 子 Agent 的 CLAUDE.md（章节套路 + 实战踩坑） |
---
## 🧱 技术栈
- **编排内核**：[Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk)（`ClaudeSDKClient` + `AgentDefinition` + 结构化输出）
- **结构化校验**：Pydantic v2（结果 schema + 三态归一；任务可指向自定义 schema）
- **LLM 后端**：Anthropic 兼容端点，默认 [智谱 GLM](https://open.bigmodel.cn/)（`glm-4.6`）；改 `.env` 的 `ANTHROPIC_BASE_URL` / `CLAUDE_MODEL` 即可切换厂商
- **文件读取**：`reading-files` 技能凭 magic bytes 识别并读取 PDF / DOC / DOCX / XLS / XLSX / JPG / PNG（PyMuPDF / python-docx / openpyxl / xlrd / Pillow / httpx）；图片走智谱 GLM 视觉模型 OCR；旧版 `.doc` 需运行环境内有 LibreOffice 或 antiword
- **可选联网**：Serper MCP（Google 搜索）
---
## 📄 License
[MIT](LICENSE) —— 自由用于商业与个人项目。