本文将通过：什么是动态工作流、如何使用、基本语法、A股调研工作流等这么几个阶段带你了解熟悉动态工作流。

普通对话：一次只能跟一个 Agent 交互，Claude Code 逐轮决定做什么
Dynamic Workflow：你把编排逻辑写成脚本，运行时执行脚本，中间结果留在脚本变量里，Claude Code 的上下文只持有最终答案

核心区别在于：谁掌握计划？ 子Agent和 Skills 由 Claude Code 逐轮决定接下来做什么；工作流把计划移入代码，由脚本决定。

为什么需要它？

子Agent和 Skills 的局限

当你让 Claude 用子Agent处理大任务时，它可能会：

• 上下文窗口被中间结果填满，忘记前面的分析
• 每次运行的编排流程不一致，结果不可重复
• 遇到循环逻辑（"找到 bug → 修复 → 再找"）时难以自动迭代

subagents — Claude 生成的工作者▸ 谁决定：Claude，逐轮 ▸ 中间结果：上下文窗口 ▸ 可重复：工作者定义 ▸ 规模：每轮几个 ▸ 中断：重启轮次工作流 — 运行时执行的脚本▸ 谁决定：**脚本** ▸ 中间结果：**脚本变量** ▸ 可重复：**编排本身** ▸ 规模：数十到数百个Agent ▸ 中断：同一会话可恢复

把计划移入代码，还让工作流可以应用可重复的质量模式——比如让独立Agent在报告之前对彼此的发现进行对抗性审查，或从多个角度起草计划并相互权衡，获得比单次通过更可信的结果。

快速上手

方式一：在提示中说"workflow"

在你的提示中包含单词 workflow，Claude Code 就会为任务编写工作流脚本，而不是逐轮处理：

运行一个 workflow 测试并修复当前应用

Claude Code 会在你的输入中高亮 workflow 这个词，然后自动编写脚本并启动运行。

小贴士：如果不小心触发了，按 Alt+W 为此提示忽略它。要完全关闭关键字触发，在 /config 中关闭 "Dynamic workflows"。

方式二：使用 Ultracode

Ultracode 结合了 xhigh 推理努力与自动工作流编排。启用后，Claude Code 为每个实质性任务自动规划工作流：

/effort ultracode

启用后，单个请求可能变成一系列工作流：一个理解代码，一个进行更改，一个验证它。Ultracode 只在当前会话生效，新会话会重置。返回日常工作用 /effort high。

方式三：运行内置工作流

Claude Code 内置了 /deep-research 工作流，一行命令启动：

/deep-research 研究下海南自贸港的优势与机会

它会自动完成多角度搜索 → 提取声明 → 对抗性验证 → 综合报告的完整研究流程。

方式四：让 Claude 直接编写自定义工作流

你也可以直接描述工作流任务，让 Claude 编写一个完整的工作流脚本。脚本写好后，工作流在未来会话中从任一位置作为 / 触发运行。

批准与权限

工作流启动前，Claude Code 会显示计划的阶段和选项：

• **Yes, run it **：启动运行
• **Yes, and don’t ask again for in **：启动，并跳过此项目中此工作流的后续提示
• **View raw scrip **：在决定前读取脚本
• 否：取消

不同权限模式的行为：

• Default / accept edits：每次运行（除非选了"不再询问"）
• Auto：仅首次启动，之后记住同意
• Bypass permissions / claude -p：从不提示，立即启动

注意：工作流中的子Agent始终在 acceptEdits 模式下运行，文件编辑自动批准。Shell 命令和网络请求仍可能提示你。

核心 API 详解

工作流脚本是一个 JavaScript 文件，必须导出 meta 对象。脚本体内可以直接使用以下全局函数，无需 import。

meta —— 工作流元数据

export const meta = {  name: 'code-review',  description: '多维度代码审查工作流',  phases: [    { title: 'Review', detail: '并行审查多个维度' },    { title: 'Verify', detail: '验证每个发现' },  ],}

meta 必须是纯字面量——不能有变量、函数调用或模板插值。

phase(title) —— 阶段分组

phase('准备')// ... 所有 agent 归入"准备"阶段phase('执行')// ... 所有 agent 归入"执行"阶段

阶段在进度显示中作为分组框，帮助你一眼看清工作流进展到哪一步。phase() 调用的标题应该和 meta.phases 中的 title 一致。

agent(prompt, opts) —— 生成子 Agent

这是最核心的函数。每个 agent() 调用会生成一个独立的 Agent 实例：

const result = await agent(  '你的任务描述...',  {    label: '显示名称',          // 在进度树中显示    phase: '阶段名',            // 归入哪个阶段    schema: { ... },            // JSON Schema，强制返回结构化数据    model: 'haiku',             // 可选：haiku / sonnet / opus    isolation: 'worktree',      // 可选：在独立 Git 分支中运行    agentType: 'code-reviewer', // 可选：使用自定义 Agent 类型  })

关键点：

• schema 参数让 Agent 必须返回符合 Schema 的 JSON，运行时自动校验，不需要你手动解析文本
• 没有 schema 时，返回 Agent 的最终文本
• model 可以为不同阶段路由不同模型，控制成本
• isolation: 'worktree' 让 Agent 在独立 Git 分支中工作，适合并行修改文件的场景

pipeline(items, ...stages) —— 流水线

const results = await pipeline(  ['auth.ts', 'db.ts', 'api.ts'],  // 要处理的项目列表  // Stage 1: 实现  (prevResult, file, index) => agent(`实现 ${file} 的功能`, { phase: 'Implement' }),  // Stage 2: 测试  (prevResult, file, index) => agent(`为 ${file} 写测试`, { phase: 'Test' }),  // Stage 3: 审查  (prevResult, file, index) => agent(`审查 ${file} 的代码质量`, { phase: 'Review' }))

流水线的魔力：auth.ts 在做测试时，db.ts 可能还在实现。各项目独立推进，总耗时 = 最慢单项的耗时，而不是所有阶段耗时之和。

这是多阶段工作的默认选择。每个阶段回调接收 (prevResult, originalItem, index) 三个参数。

parallel(thunks) —— 并行屏障

const [security, perf, style] = await parallel([  () => agent('安全审查', { phase: 'Review' }),  () => agent('性能审查', { phase: 'Review' }),  () => agent('风格审查', { phase: 'Review' }),])// 三个同时跑，全部完成后才继续

什么时候用 barrier vs pipeline？

• parallel：需要所有结果一起才能进行下一步（如汇总、去重）
• pipeline：各项独立，不需要交叉上下文

一个失败的 thunk 不会拒绝整个调用——它在结果数组中变为 null，使用前记得 .filter(Boolean)。

log(message) —— 进度输出

log(`已完成 ${count}/10 个文件`)

显示在进度树上方，给用户实时反馈。

args —— 调用参数

调用者传入的参数在脚本中通过全局变量 args 访问：

// 脚本中const feature = args?.feature || 'unknown'// 调用时Workflow({ name: 'feature-impl', args: { feature: '用户认证' } })

传数组/对象时用实际 JSON 值，不要用 JSON 字符串。

budget —— 预算控制

当用户指定了 Token 预算时（如 "+500k"），脚本可以动态调整工作深度：

const findings = []while (budget.total && budget.remaining() > 50_000) {  const result = await agent('深入分析下一个模块', { schema: ANALYSIS_SCHEMA })  findings.push(...result.items)  log(`${findings.length} items, ${Math.round(budget.remaining()/1000)}k remaining`)}

budget.total 为 null 时 remaining() 返回 Infinity，不限制循环。

实战模式

模式 1：对抗性验证（Adversarial Verify）

防止"看似正确实则错误"的发现存活。每个发现让 N 个独立 Agent 尝试反驳，多数反驳成功则剔除：

// 每个发现让 3 个独立 Agent 尝试反驳const votes = await parallel([  () => agent(`尝试反驳：${claim}。默认 refuted=true 如果不确定。`, { schema: VERDICT }),  () => agent(`尝试反驳：${claim}。默认 refuted=true 如果不确定。`, { schema: VERDICT }),  () => agent(`尝试反驳：${claim}。默认 refuted=true 如果不确定。`, { schema: VERDICT }),])// 2/3 以上认为无法反驳，才保留const survives = votes.filter(Boolean).filter(v => !v.refuted).length >= 2

模式 2：循环直到达标（Loop-until-dry）

适用于不确定需要多少轮的探索性任务：

const bugs = []const seen = new Set()let consecutiveEmpty = 0while (consecutiveEmpty < 2) {  const result = await agent('找出代码中的 bug', { schema: BUGS_SCHEMA })  const newBugs = result.bugs.filter(b => !seen.has(b.id))  if (newBugs.length === 0) {    consecutiveEmpty++  } else {    consecutiveEmpty = 0    bugs.push(...newBugs)    newBugs.forEach(b => seen.add(b.id))  }  log(`已找到 ${bugs.length} 个 bug`)}return { bugs }

模式 3：多视角评审（Judge Panel）

从不同角度生成方案，再用评委打分：

// 三个 Agent 从不同角度提方案const approaches = await parallel([  () => agent('从 MVP 角度设计方案', { phase: 'Design' }),  () => agent('从安全性角度设计方案', { phase: 'Design' }),  () => agent('从用户体验角度设计方案', { phase: 'Design' }),])// 评委打分const scores = await parallel(  approaches.map(a => () =>    agent(`评估这个方案：${a.summary}`, {      phase: 'Judge',      schema: SCORE_SCHEMA,    })  ))// 选最高分，融合其他方案的优点const winner = approaches[scores.indexOf(Math.max(...scores.map(s => s.score)))]

模式 4：多维度扫描（Multi-modal Sweep）

平行搜索不同维度，每个 Agent 看到不同角度：

const DIMENSIONS = [  { key: 'security', prompt: '审查安全性：SQL 注入、XSS、硬编码密钥' },  { key: 'performance', prompt: '审查性能：N+1 查询、内存泄漏、不必要的重渲染' },  { key: 'maintainability', prompt: '审查可维护性：代码重复、过长函数、深层嵌套' },]const reviews = await parallel(  DIMENSIONS.map(d => () =>    agent(d.prompt, {      label: `review:${d.key}`,      phase: 'Review',      schema: FINDING_SCHEMA,    })  ))

模式 5：流水线处理（Pipeline Processing）

多个文件独立经历 实现 → 测试 → 审查 的完整流程：

const results = await pipeline(  files,  file => agent(`实现 ${file}`, { phase: 'Implement' }),  (prev, file) => agent(`为 ${file} 写测试`, { phase: 'Test' }),  (prev, file) => agent(`审查 ${file}`, { phase: 'Review' }))

完整示例：Bug 修复工作流

export const meta = {  name: 'fix-bugs',  description: '发现并修复代码中的 bug',  phases: [    { title: 'Discover', detail: '发现 bug' },    { title: 'Fix', detail: '修复 bug' },    { title: 'Verify', detail: '验证修复' },  ],}const BUG_SCHEMA = {  type: 'object',  properties: {    bugs: {      type: 'array',      items: {        type: 'object',        properties: {          id: { type: 'string' },          title: { type: 'string' },          file: { type: 'string' },          line: { type: 'number' },          description: { type: 'string' },          fix: { type: 'string' },        },        required: ['id', 'title', 'file', 'description', 'fix'],      },    },  },  required: ['bugs'],}// ── Discover：多角度搜索 bug ──phase('Discover')const searches = await parallel([  () => agent(    '从错误处理角度找 bug：未捕获的异常、空指针、类型错误',    { label: 'search:error-handling', phase: 'Discover', schema: BUG_SCHEMA }  ),  () => agent(    '从并发角度找 bug：竞态条件、死锁、资源泄漏',    { label: 'search:concurrency', phase: 'Discover', schema: BUG_SCHEMA }  ),  () => agent(    '从逻辑角度找 bug：边界条件、off-by-one、错误的条件判断',    { label: 'search:logic', phase: 'Discover', schema: BUG_SCHEMA }  ),])// 去重const seen = new Set()const bugs = searches  .filter(Boolean)  .flatMap(r => r.bugs)  .filter(b => {    const key = `${b.file}:${b.line}:${b.title}`    if (seen.has(key)) return false    seen.add(key)    return true  })log(`发现 ${bugs.length} 个唯一 bug`)// ── Fix：逐个修复 ──phase('Fix')const fixes = await pipeline(  bugs,  bug => agent(    `修复以下 bug：\n` +    `文件: ${bug.file}:${bug.line}\n` +    `问题: ${bug.title}\n` +    `描述: ${bug.description}\n` +    `建议修复方案: ${bug.fix}\n\n` +    `请实现修复，然后运行 pnpm typecheck 验证。`,    { label: `fix:${bug.id}`, phase: 'Fix' }  ))// ── Verify：最终验证 ──phase('Verify')const verification = await agent(  `验证所有 bug 修复：\n` +  `1. 运行 pnpm typecheck\n` +  `2. 运行 pnpm test\n` +  `3. 确认以下文件的修复：${bugs.map(b => b.file).join(', ')}`,  {    label: 'final-verify',    phase: 'Verify',    schema: {      type: 'object',      properties: {        typecheckPassed: { type: 'boolean' },        testsPassed: { type: 'boolean' },        allFixesVerified: { type: 'boolean' },      },      required: ['typecheckPassed', 'testsPassed', 'allFixesVerified'],    },  })return {  bugsFound: bugs.length,  bugsFixed: fixes.filter(Boolean).length,  verification,}

完整示例：A 股深度调研工作流（含网络检索）

下面是一个真实可用的自定义工作流——A 股上市公司深度调研。它展示了 parallel + WebSearch/WebFetch + schema + 对抗性验证在金融场景下的完整应用。

文件路径：.claude/workflows/a-share-research.js

调用方式

/a-share-research 调研XXX股票

工作流架构（5 阶段，含网络检索）

标的确认（1个Agent）│  ← WebSearch + WebFetch 确认股票代码、行业、股价    ↓数据采集（5个Agent并行网络检索）⬅ 关键阶段├── 财务数据：搜索财报、ROE、PE/PB → WebFetch 东方财富├── 行情数据：搜索最新股价、技术指标、资金流向├── 新闻公告：搜索最新公告、研报、政策├── 行业数据：搜索行业景气度、竞争对手、市场份额└── 风险信息：搜索质押、监管处罚、大股东增减持    ↓五维并行分析（5个Agent同时跑）│  基于采集数据 + 可补充 WebSearch├── 基本面：财务指标、估值、机构持仓├── 技术面：K线、均线、MACD、资金流向├── 消息面：公告、政策、传闻、催化剂├── 行业对比：竞争格局、护城河、景气度└── 风险评估：财务/监管/治理/黑天鹅    ↓交叉验证（最多11个Agent并行）│  每个验证 Agent 独立执行 WebSearch + WebFetch├── 优先验证：低置信度 + 无来源的发现├── 对高影响力利好：独立搜索反驳└── 对高影响力利空：独立搜索反驳    ↓综合研判（1个Agent汇总）    → 投资评级 + 综合评分 + 核心逻辑 + 风险提示 + 数据来源汇总

关键设计亮点

1. 独立数据采集阶段，确保数据有源

与普通分析工作流最大的区别：在分析之前，先用 5 个 Agent 并行采集原始数据。

// 每个采集 Agent 执行 3 次 WebSearch + 多次 WebFetchconst rawDataResults = await parallel(  SEARCH_QUERIES.map(sq => () =>    agent(      `采集【${sq.key}】维度数据...\n` +      `必须执行：\n` +      sq.queries.map((q, i) => `${i+1}. WebSearch: "${q}"`).join('\n') +      `\n选择权威页面 WebFetch 获取详细数据...`,      { schema: RAW_DATA_SCHEMA }  // 返回 sources[] + rawDataSummary    )  ))

每个采集 Agent 返回 { sources: [{url, title, keyData}], rawDataSummary }，后续分析 Agent 直接基于这些数据工作，而不是凭记忆编造。

2. Schema 增加数据溯源字段

每个发现都必须标注来源和时效性：

{  findings: [{    title, detail,    sentiment: '利好'|'利空'|'中性',    confidence: '高'|'中'|'低',    source: 'https://...',                          // 必填，数据来源 URL    dataFreshness: '实时'|'近期'|'历史'|'待验证'       // 数据时效  }],  summary, score,  dataQuality: '高'|'中'|'低'                        // 整体数据质量评估}

3. 交叉验证使用独立网络搜索

验证 Agent 不是简单地"想想对不对"，而是真正去搜索独立数据源：

// 验证 Agent 的 prompt`1. WebSearch: "${stockName} ${finding.title}" — 获取独立信息源 2. WebSearch: "${stockName} 最新 ${finding.dimension}" — 交叉数据 3. WebFetch: 访问东方财富/巨潮资讯等权威页面 4. 对比独立获取的数据与原始发现是否一致`

验证结果返回 { isReal, reason, verificationSource }——每条结论都有独立来源背书。

4. 三类发现优先验证

// 1. 存疑发现：低置信度 / 无来源 / 时效待验证const needVerify = allFindings  .filter(f => f.confidence === '低' || !f.source || f.dataFreshness === '待验证')// 2. 高影响力利好：用怀疑视角验证// 3. 高影响力利空：用乐观视角验证

运行效果示例

🎯 开始调研：贵州茅台✅ 标的确认：贵州茅台（600519.SH）| 食品饮料 | 来源：东方财富▸ 数据采集  🌐 启动5路并行网络数据采集...  财务数据：5 个来源 | 行情数据：3 个来源 | 新闻公告：4 个来源  行业数据：3 个来源 | 风险信息：2 个来源  ✅ 数据采集完成，共 17 个数据来源▸ 五维分析  基本面评分：8/10 | 数据质量：高 | 6/7 条有明确来源  技术面评分：6/10 | 数据质量：中 | 4/6 条有明确来源  消息面评分：7/10 | 数据质量：高 | 5/5 条有明确来源  行业对比评分：9/10 | 数据质量：中 | 5/6 条有明确来源  风险评估评分：5/10 | 数据质量：中 | 3/5 条有明确来源▸ 交叉验证  待验证：2 条存疑 + 3 条利好 + 2 条利空  ✅ 验证完成：6 条通过，1 条被质疑▸ 综合研判  📊 调研报告：贵州茅台（600519.SH）  综合评级：推荐 | 综合评分：78/100 | 数据来源：17 个  核心逻辑：行业龙头地位稳固，品牌护城河深厚...  主要风险：估值处于历史中高位，消费降级压力...

如何定制

• 增加分析维度：在 DIMENSIONS 和 SEARCH_QUERIES 数组中添加新项
• 改变验证强度：调整各 .slice(0, N) 的数量
• 增加数据源：在 SEARCH_QUERIES[].fetchUrls 中添加目标页面
• 增加行业特定指标：修改各维度的 prompt 和搜索关键词
• 输出 Markdown 报告：在最终 agent 的 prompt 中要求输出 Markdown
• 对接内部数据库：在数据采集阶段添加 API 调用逻辑

内置工作流：Deep Research

Claude Code 内置了 /deep-research 工作流，是体验 Dynamic Workflows 的最快方式。

一行命令启动

/deep-research Claude Code 最新特性与最佳实践

它做了什么？

deep-research 内部包含 5 个阶段：

▸ Scope        分解研究问题为 5 个搜索角度▸ Search       5 个并行 Agent，每个负责一个角度的 Web 搜索▸ Fetch        去重 URL，抓取 Top 15 源，提取可验证的声明▸ Verify       每条声明 3 个 Agent 独立对抗性验证（2/3 反驳成功则剔除）▸ Synthesize   合并语义重复，按置信度排序，生成引用报告

运行完成后，报告进入你的会话。它引用每个声明来自的来源，未通过交叉检查的声明已被过滤掉。

值得了解？

这个工作流本身就是 Dynamic Workflows 的教科书级示例，它展示了本文介绍的几乎所有核心模式：

• parallel：Search 阶段 5 个 Agent 同时搜索
• pipeline：Fetch 阶段对每个 URL 独立提取声明
• 对抗性验证：Verify 阶段每条声明 3 个 Agent 独立反驳
• schema：每个 Agent 都用 JSON Schema 强制结构化输出
• log：实时输出进度（"Found 12 unique sources"）
• 阶段分组：5 个 phase() 清晰划分工作流进度

管理运行

查看进度

工作流在后台运行，会话在 Agent 工作时保持响应。随时运行 /workflows 列出运行中和已完成的工作流：

/workflows

进度视图显示每个阶段及其Agent计数、令牌总数和经过的时间。快捷键：

• ↑ / ↓：选择一个阶段或Agent
• Enter 或 →：深入选定的阶段，读取其提示、工具调用和结果
• Esc：返回一个级别
• p：暂停或恢复运行
• x：停止选定的Agent，或停止整个工作流
• r：重启选定的运行中Agent
• s：保存运行的脚本为命令

保存工作流以供重用

当 Claude 为你的重复任务编写了工作流时，可以将脚本保存为命令：

1. 运行 /workflows
2. 选择你想保留的运行
3. 按 s
4. Tab 切换保存位置：
   • .claude/workflows/（项目内，团队共享）
   • ~/.claude/workflows/（个人，跨项目可用）
5. 按 Enter 保存

保存后，工作流在未来会话中作为 /<name> 运行，出现在 / 自动补全中。

成本控制

工作流生成许多Agent，单次运行可以比普通对话消耗更多 Token。控制成本的方法：

• 在大型运行前检查 /model，确认当前模型
• 为不需要最强模型的阶段指定 model: 'haiku'
• 使用 budget 对象动态控制循环深度
• 随时从 /workflows 停止运行，不会丢失已完成的工作

运行约束

• 无中途用户输入：仅权限提示可以暂停运行
• 脚本本身无文件系统/shell 访问：Agent读写文件和运行命令，脚本只协调Agent
• 最多 16 个并发Agent（CPU核数少会更少）：限制本地资源使用
• 每次运行 1,000 个Agent总数：防止失控循环

关闭工作流

如果不需要工作流功能：

• 在 /config 中切换 "Dynamic workflows" 关闭（会话内持续）
• 在 ~/.claude/settings.json 中设置 "disableWorkflows": true
• 设置环境变量 CLAUDE_CODE_DISABLE_WORKFLOWS=1

版本与可用性

• 最低版本：Claude Code v2.1.154+
• 计划要求：Pro、Max、Team、Enterprise（Pro 需在 /config 中手动启用）
• API 支持：Anthropic API、Amazon Bedrock、Google Cloud Vertex AI、Microsoft Foundry
• 当前状态：研究预览阶段

总结

Dynamic Workflows 是 Claude Code 处理复杂任务的利器。它让你能够：

1. 编排多个 Agent：定义清晰的执行顺序和依赖关系
2. 并行处理：独立任务同时执行，节省时间
3. 结构化输出：JSON Schema 保证数据一致性
4. 流水线模式：各项目独立推进，最大化吞吐
5. 断点恢复：中断后从上次位置继续
6. 预算控制：精确控制 Token 消耗

当你遇到这样的场景：一个复杂任务需要多个 Agent 分工合作，有的并行审查，有的串行依赖，有的需要循环迭代直到达标。Claude Code 的 Dynamic Workflows 可能是你最好的选择

微信公众号：https://mp.weixin.qq.com/s/9JgHxT8yqGnUt16k-DneEQ

把做过的事自己沉淀下来用户下次不用再把同一套流程教一遍

Hermes 对这个问题的处理没有往玄学上飘，也没吹嘘自己在后台偷偷训练新模型。它做得很朴素，也很工程化：每当 Agent 在任务里摸索出一套可以复用的做法，就通过 skill_manage 把这套做法写回本地技能文件。下次遇到类似任务，再把它拿出来继续用、继续改。

Hermes 的技能进化，不是参数层面的学习，更不是凭空长出什么新能力。它更像是把一次任务里跑通的经验，整理成一份能随时查阅、修改、甚至回滚的操作手册。

下面顺着这条链路拆开看一看。

Hermes 里”自动创建技能”的真实路径

自动创建技能：本质是文件写回，不是训练

Hermes 所谓的自动生成技能，本质上是一套工具调用流程，而不是训练流程。

Agent 并不会把一次任务丢给某个学习器，然后在模型参数里“长”出新能力。它做的是：

1. 任务进行时， 提醒模型尽量使用和维护技能；
2. 任务结束后， 回头审视这次有没有值得复用的流程；
3. 如果有， 就调用 skill_manage() 创建新技能，或者给旧技能打补丁；
4. 把结果写回本地技能目录， 让后面的会话可以直接复用。

所以 Hermes 的“进化”，准确来说是文件层面的经验写回。

听起来当然没有“模型自我学习”那么高级，但好处很实在：它可控。

 它学到了什么，你能打开文件直接看。   它写到了哪里，你能精确定位。   它有没有写坏，你可以审查、回滚、再改。   下一次为什么做得更顺，也都有迹可循。

为什么能进化？经验有地可写，且支持打补丁

很多 Agent 系统并不是发现不了经验，而是发现之后没地方存储处理。

这次调通了一套部署流程，下次还得重新琢磨；这次踩过一个环境坑，下次换个会话又踩一遍。问题不是在于“有没有经验”，如果用户没有主动把本次流程固化为Skills就等于是“经验有没有被系统接住”。

Hermes 把这件事做成了一条明确的写回路径，skill_manage() 支持的操作包括：

 create：创建一个新技能 patch：给已有技能打补丁 edit：重写 SKILL.md write_file：给技能增加附属文件 remove_file、delete：删除内容

最值得关注的是打补丁。

Hermes 不鼓励 Agent 一上来就重写整份技能文档，而是更偏向“补一小段”。这更接近真实的维护习惯：任务里发现了一个新坑、一个命令差异、一个验证步骤，就把它追加或修正到相应位置。

这样做有几个实际好处：token 消耗更小，修改范围更窄，更适合持续修补那些从真实任务里冒出来的细节。并且它的打补丁不是死板的字符串替换，底层用了模糊匹配，模型不需要精确记住原文里的每个空格，只要上下文能对上，就有机会把补丁打到正确位置。这就是它能**“边用边修”**的原因。

自动创建不靠开关，而是三层机制叠在一起

Hermes 的技能进化不是靠某个神秘按钮触发的，更像是三层提示和流程叠加出来的结果。

1. 系统提示词持续提醒系统提示会反复提醒模型两件事：复杂任务结束后，考虑要不要保存成技能；使用技能时，如果发现过时、缺漏或错误，及时打补丁。这会让模型不只盯着解决眼前问题，也会被引导去思考“有什么值得留下”。

2. 工具的 schema 告诉它“怎么保存”skill_manage 的 schema description 里有详细的操作规范：什么情况适合创建，什么情况更适合打补丁，什么样的技能才算质量过关，创建和删除前最好确认用户意图。Hermes 不仅告诉模型“你可以保存经验”，还告诉它“别乱写，尽量这样写”。

3. 后台复盘把“想一想”变成固定流程真正把这套机制推起来的，是 run_agent.py 里的后台复盘。Hermes 会维护一个技能计数器，当达到阈值，主任务完成后会启动一个后台复盘代理。这个代理不直接跟用户聊天，而是拿着当前会话快照加上复盘提示，专门判断“有没有值得沉淀成技能的非平凡工作流”。有就创建或更新，没有就安静退出。这就把“顺手记一笔”从模型自觉变成了系统级的固定动作。

后台复盘如何在主任务完成后异步沉淀技能

不是自治，不“裸写”：半自动背后的边界与安全

如果给这套机制一个准确的描述，就是：提示驱动、阈值触发、后台复盘、文件写回。它不是完全自治，主要有三个原因。

首先，是否值得保存仍然要靠模型判断，不会每次任务都产出新技能。其次，创建前确认用户意图更多是软约束，存在于提示和工具描述层，不是硬阻断。再者，它不是一个无限膨胀的知识工厂，重点是留下真正有复用价值的流程。

更能体现工程成熟度的，是它对写入环节的约束。只要允许 Agent 写文件，真正要关心的就不是“能不能写”，而是“写得稳不稳、边界够不够硬”。

Hermes 在 skill_manage() 的真实写入阶段做了大量校验：技能名称是否合法，分类是否合法，SKILL.md frontmatter 是否完整，内容大小是否超限，附属文件是否只写到允许的子目录，路径有没有穿越风险。写入后还会经过 skills_guard 安全扫描，不通过就回滚。尤其对 Agent 自己创建的技能，策略并不宽松，某些风险判定可能直接阻断。

技能写回不是直接落盘，而是带校验和回滚

复盘时机：后台一次，会话重置前再兜底一次

Hermes 没有在任务中途打断主流程，而是在主任务给出最终回复后，异步拉起一个轻量 Agent 做复盘。这个后台 Agent 复用当前模型和上下文快照，却不污染主会话，也不抢注意力。如果创建或更新了技能，前台只给一个很短的摘要提示。好处很直接：当前任务先完成，经验沉淀不干扰主推理，交付和复盘可以并行。

除了这种后台复盘，Hermes 还有另一道保险。当会话因为长时间不活跃或定时重置即将被清空，系统会再启动一轮清场复盘，用一个临时代理回顾整段对话，看看有没有遗漏的记忆或技能值得保存。很多复杂任务当下未必能立刻意识到是一套可复用流程，会话结束前再看一遍，等于给经验沉淀加了一层兜底。

因此，技能进化实际上有两个出口：主任务后的后台复盘和会话重置前的清场复盘。

为什么好用？工程化学习与可审计的闭环

一次复杂任务结束后，如果系统能把“什么时候该触发、先做什么后做什么、哪些命令有效、哪些坑已经踩过、最后怎么验证”这些信息留下来，下一次类似任务到来时，Agent 就不需要重新猜测，可以直接沿着上次真实跑通过的流程往前走。重复劳动少了，失败成本低了，而且因为技能是文件，人可以审查、补充、分发，团队协作也更容易。

所以我更愿意把 Hermes 的技能进化叫作“工程化学习”。它没有神秘感，但非常能落地。

归结成一句话：Hermes 让经验以工程资产的形式留下来，而不是散落在一次次对话里。你也可以说“Hermes 自己长出技能了”，它长出的不是参数能力，而是一份份能打开查看、能继续维护、能打补丁、也能被安全扫描的技能文件。这背后是一条非常清晰的闭环：在任务中发现经验，在任务后判断价值，用工具写回，用安全机制限制风险，在未来会话中再次加载和修补。

它没有”自治超级智能”那么夸张，却很像真正能落地的软件工程——一个 Agent 变好用，不是因为它声称自己会成长，而是因为它知道经验应当放在哪里，下一次又该怎么拿出来用。

深入分析源码就会发现两套 Loop 确实都在做“模型调工具再继续推理”这件事，但服务的运行场景完全不同，控制逻辑也不是一个量级。

先介绍 Agent Loop ，Hermes 里的 Loop，核心就是下面这四步：

1. 把当前消息发给 LLM
2. LLM 返回文本和可选的 tool calls
3. 如果有工具调用，就执行工具并把结果追加回消息列表
4. 如果没有工具调用，就认为任务完成，退出循环

这四步是Agent Loop的基本流程，但这四步之外还包很多逻辑。用户交互要处理流式输出、重试、打断、上下文压缩；训练 rollout 则关心 async、token/logprobs、reward 计算和并发调度。Hermes 没把这些需求硬塞进同一个大循环里，而是直接拆成了两套实现Agent Loop：

• 面向用户实时交互的 AIAgent
• 面向 RL rollout 的 HermesAgentLoop

拆分不是为了拆分而拆分，根本是因为两个场景本来就不是同一个问题。

一套用于用户交互，一套用于RL训练

AIAgent 对应的是 CLI、Gateway、Telegram、Discord 这类直接面向人的入口。用户在前台等回复，这条链路不是只追求“能跑通”，还需要把交互过程本身兜住。源码里能直接看到这类需求留下来的痕迹：流式输出、Provider 容错、上下文压缩、用户中断、预算耗尽后的 Grace Call、子 Agent 委派、插件钩子，基本都堆在这条路径上。

AIAgent 的复杂度，不是来自“调模型”这一步，而是来自调模型失败以后怎么办、用户半路打断怎么办、上下文塞不下了怎么办。也正因为这样，这个循环体才会达到数千行。它已不是一个单纯的推理循环，而是一条完整的交互控制链。

HermesAgentLoop 而完全是另一回事。它不面向用户，而是被 Atropos 调起来做 rollout。这里没有人盯着屏幕，也不需要跨 Provider 兜底。训练场景真正看重的是另外几件事：

• 必须是 async，才能并发跑大量 rollout
• 必须拿到真实 token、logprobs、masks，供 GRPO 训练使用
• 必须把工具执行和 reward 验证放在同一个 sandbox 上下文里
• 必须保持循环本身足够轻，避免把交互系统里的复杂分支带进训练路径

这也是为什么 HermesAgentLoop 看起来简洁很多的原因。主要是负责把一次 rollout 跑完整，并且把训练真正要用的数据带出来。

在训练链路，HermesAgentLoop 关键不在“它也会调工具”，而在于它站在一条完整的 RL 数据生产链上。

单次 rollout 生命周期dataset item   │   ▼format_prompt()   │   ▼HermesAgentLoop.run()   │   ├─ server.chat_completion / managed generate   ├─ parse tool calls   ├─ execute tools   └─ 产出 AgentResult + managed_state   │   ▼ToolContext.compute_reward()   │   └─ 在同一个 sandbox 中验证结果，得到 reward   │   ▼ScoredDataItem(tokens, masks, scores)   │   ▼GRPO trainer 更新模型

为什么不合成一个超级 Loop

在 AIAgent 这条路径存在很多逻辑：流式处理、空响应恢复、Provider 轮转、上下文压缩，这些逻辑对用户交互很重要，但对 rollout 来说并无多大作用。AIAgent 这套控制流也不适合直接嵌进 Atropos 的异步并发环境；训练真正要的 managed_state、token 级数据和 ToolContext，也不是它天然会产出的东西。

把 HermesAgentLoop 拿去服务用户也不现实。它没有流式输出，没有那套完整的错误恢复，也没有 Grace Call 和子 Agent 委派。跑 benchmark 或 rollout 没问题，放到产品入口里就太薄了。

从上面的分析也可以看到这两个Loop的业务流程，完全不一样，强制融合在一起会导致Loop复杂度过高，可靠性降低。

该复用的不是循环体，而是工具调度层

Hermes Agent 并没有把两套系统彻底割裂。它复用的是更底层的能力，如 handle_function_call() 这一层的工具调度，以及工具结果预算、持久化这些基础设施。

复用点不在 Loop 本身，而在工具执行链路。

这个切分比“有没有统一框架”更重要。Agent 系统里真正容易失控的，往往不是某个工具实现，而是围绕工具调用长出来的控制流：什么时候继续，什么时候停，错误怎么恢复，上下文什么时候压，结果怎么进入训练信号。Hermes 的处理方式很直接：不同场景用不同的 loop policy，能共享的则压到更下面一层去共享。

写在最后

很多时候设计 Agent 架构时，天然会想先抽一个“统一循环”。Hermes 这套实现给了一个很实用的反例：只要场景的目标函数已经变了，循环层通常就不该强行共用。

用户交互系统优化的是体验、鲁棒性和可恢复性；RL rollout 优化的是吞吐、并发和训练信号精度。它们都叫 Agent Loop，但回答的不是同一个工程问题。

更稳妥的做法，反而是把系统拆成两层：

• 上层按场景定义各自的循环控制策略
• 下层复用工具调度、结果存储和共享基础设施

Hermes 的双 Loop 结构，最有参考价值的地方也在这里：它没有执着于“所有能力必须收敛到一个抽象里”，接受业务循环层天然会分叉，把复用点放在了更合适的位置。

摄像头怎么接？截图怎么做？通知、照片、位置这些能力如何统一暴露？更重要的是，这些能力不是在本地脚本里临时调用一下，而是要进入一个可连接、可调度、可鉴权、可回传结果的系统里。

它不是一个单纯的客户端，也不是一个只能本地点击使用的小工具。更准确地说，它是 OpenClaw 体系中的设备能力宿主：运行在具体设备上，以 Node 身份接入 OpenClaw 网关，把本地设备上的真实能力，以标准化接口接进整个系统。

开源地址：https://github.com/linxin26/openclaw-nodes

一、OpenClaw 里，Node 能解决什么

从系统角色来看，OpenClaw 可以理解为三个核心部分：

Gateway：负责连接、鉴权、路由和控制平面协调Operator：负责发起操作、承载用户交互、消费系统状态Node：负责承载真实设备能力，并执行来自系统的调用请求

它是客户端又不是，很多人第一反应可能会把它理解成“被控端”或者“远程客户端”。在 OpenClaw 里，Node 的定位不是“一个能被点来点去的客户端”，而是“一个可被系统调度的能力节点”。

如果只是一个普通客户端，它的重点通常是界面、交互和用户本地操作；但如果它是一个能力节点，它就必须完成一整条系统链路：

连接 Gateway完成身份建立与鉴权声明自己有哪些能力接收调用请求在本地执行具体能力将结果或错误结构化返回

只有这几个环节形成闭环，设备能力才算真正进入了 OpenClaw，而不是停留在“本机能跑几个脚本”的阶段。

二、为什么不能只靠脚本拼起来

在很多设备能力确实可以先靠脚本或平台命令跑通。比如截图、拍照、读取系统信息，这些都不算难。但真正困难的地方，从来不是“把能力调起来”，而是“把能力接进系统”。

因为一旦进入系统，它面对的问题就会立刻升级：

系统怎么知道这个节点具备哪些能力？请求如何准确路由到对应能力？输入输出格式是否统一？失败时如何表达错误，而不是只吐出一段日志？掉线、重连、状态变化怎么处理？Windows、macOS、Linux 的差异如何隔离？

如这些问题没有被抽象清楚，那所谓的“设备接入”，最终就会退化成一堆平台脚本和临时判断，能跑，但很难扩展，更难产品化。

从工程角度看，OpenClaw Node 的重点并不是“把摄像头调用起来”，而是“把摄像头、截图、通知、照片这些本地能力，以统一协议和统一结构接入 OpenClaw 网关体系”。

三、 Node 的核心架构是什么

从结构上看，这类应用大致可以拆成四层。

1. 连接层

这一层负责和 OpenClaw Gateway 建立长连接，处理握手、身份校验、在线状态维护，以及断开后的重连恢复。

它解决的问题是：这个节点如何稳定地进入系统，连接层不稳，后面的能力层再完整，也只是本地孤岛。

2. 能力层

这一层负责把设备能力组织成清晰的能力接口，比如 camera、screen、photos、notifications、location 等。

重点不是能力做了多少，而是能力边界是否清楚、命令语义是否统一。只有接口定义清楚，上层系统才能稳定调用，下层实现才能逐步演进。

3. 分发层

来自网关的调用请求，不应该直接落到某个平台脚本或系统命令上，而是先进入统一的分发逻辑。

这一层负责：

参数校验能力可用性检查路由到具体 handler统一结果结构统一错误模型

它的价值在于把“协议请求”和“本地执行”隔开，让系统层和设备层各自保持边界。

4. 宿主层

这部分就是应用本身承担的运行时支撑能力，包括配置管理、日志、状态展示、系统托盘，以及单纯后台应用或是基于GUI 控制面板。

它可实现为桌面应用形式或者只是以后台应用形式存在。它对来说 Node 是否有界面并不是很重要。但如果现实了GUI可做到节点不只是“后台有个进程在跑”，它还具备：

可见的可配置的可诊断的可控制的

换句话说，宿主层并不是协议核心，但它决定了这个 Node 是“后台节点”，还是“桌面应用”。

四、一次能力调用的具体流程

用一个具体例子更容易说明问题。假设系统要调用 screen.snapshot 这个能力，整个链路通常会是这样：

1. Operator 或上层控制端发起截图请求2. Gateway 根据目标节点和能力，把请求路由到对应 Node3. Node 收到请求后，先做参数与状态检查4. 分发层把请求交给 `screen` 对应的 handler5. 本地平台实现执行截图动作6. 结果被整理成统一结构返回给 Gateway7. Gateway 再把结果交回上层调用方8. 同时，Node 本地的 GUI 或日志系统展示这次调用状态

这个流程真正重要的地方，不是“截图成功了”，而是每一层都只做自己该做的事。

协议层不需要知道截图到底调用了哪套系统接口；设备能力实现也不需要关心 WebSocket 帧结构；GUI 层更不应该直接承担底层执行逻辑。

正是这种分层，让 OpenClaw Node 不只是“能跑”，而是“能演进”。

五、桌面 GUI 还是后台应用

Node 是否需要 GUI，完全取决于它运行在什么样的设备上。在桌面电脑上，宿主层可以呈现为带有系统托盘、配置窗口、状态面板的桌面应用。连接状态、能力开关、日志诊断——这些可视化的能力让节点变得可观察、可控制。但在很多设备上，GUI 既不可能，也不必要。

网络摄像头：算力只够维持视频流，没有屏幕，也没有人机交互场景路由器/网关设备：嵌入式系统，资源受限，通常只有串口或 Web 管理ESP32/单片机设备：内存以 KB 计，连接本身就是最大的能力消耗服务器/容器环境：无头运行，依赖日志和外部监控系统

对于这些设备，宿主层退化为更轻量的形态：后台进程、系统服务、甚至固件级常驻程序。它依然承担配置管理、日志输出、状态维护的职责，只是交互方式从"界面点击"变成了"配置文件 + 远程查询"或"硬件指示灯 + 串口日志"。

无论有没有 GUI，它都要完成同样的系统链路——连接 Gateway、声明能力、接收调用、执行回传。GUI 只是宿主层在特定设备形态下的一种可选表达，而不是 Node 的定义性特征。真正重要的是，宿主层让 Node 从"一段能跑能力的代码"变成"一个可配置、可诊断、可维护的能力宿主"。至于这个宿主以什么形态呈现，应该由设备能力和部署场景决定，而不是架构预设。

六、多平台支持与统一语义

不同设备的底层实现可以天差地别，但对 OpenClaw 暴露出来的能力语义必须保持一致。

例如：

`camera.snap` 在不同平台上可能走不同媒体链路`screen.snapshot` 可能依赖不同系统接口`photos` 的来源目录和权限模型也可能不同`notifications`、`location`、`calendar` 在各平台上的支持程度也会有明显差异

但对于 Gateway 和上层调用者来说，它们最好仍然表现为：

相同的命令接口相近的输入参数统一的结果结构一致的错误表达方式

这也是为什么能力实现不能简单散落在脚本里，而要下沉到平台 provider 层，由统一的能力接口和分发逻辑向上收口。

OpenClaw Node 要解决的，不是“把多端都各写一遍”，而是“在统一协议语义下，把平台差异控制在实现层内部”。

七、这个应用带来了什么

如果只把 Node 看成"某个设备上的客户端程序"，它的价值会被明显低估。它真正重要的地方在于：让物理设备以标准化节点的身份进入 OpenClaw。

一个跑在 ESP32 上的轻量 Node，和一个运行在服务器上的完整 Node，在 OpenClaw 体系中是平等的能力节点——它们各自声明自己支持的能力，各自响应调用，各自按统一格式回传结果。

要解决的不是“本机能不能截图”，也不是“能不能做个 GUI”，而是如何把真实设备上的能力，稳定地接进 OpenClaw 网关，放进统一的连接、鉴权、声明、调用和回传链路里。

Node 的价值不是"多了一个客户端"，而是为 OpenClaw 补上了可运行、可扩展、可跨平台部署的能力宿主——让系统的触角真正延伸到设备层面。

大模型的理解能力越来越强，但还是会出现：“好的，现在请您打开手机相册，找到那张图片并上传给我。” AI 被困在了云端的沙盒里，碰不到真实世界的设备。需要各种MCP、Skills才能去打通这些资源。

你想让它自动截屏、读个本地通知、或者获取一下当前位置？可以，需要部署MCP、安装Skills。

OpenClaw 试图通过“网关 + 节点”的架构，把这套脏活累活标准化。 它的节点服务，给 AI 铺了一条直达真实设备的管线。

节点服务，解决了什么？

OpenClaw 的节点服务是一个运行在本地的 Agent 侧常驻进程。

它的运行机制有几个非常实在的工程考量：

第一，主动反向连接。 节点主动通过 WebSocket/长链接连到网关。

第二，显式的能力注册（Capabilities Registry）。 设备连上网关时，会主动上报：“我是一台安卓机，我支持 camera.snap（拍照）、location.get（获取定位）”。系统不用去瞎猜这台设备能干嘛，网关层面可以直接基于这些注册的能力去做鉴权和路由。

第三，标准的执行闭环。 节点收到指令 》调起本地原生 API（比如调起 Android Camera） 》 拿到照片 》 传回网关。它把底层设备 API 包装成了大模型能直接理解的标准化 Tool 调用。

Agent 最需要的不是各种花哨的 UI，而是这种“稳定、可组合、能返回确切结果”的本地 API、CLI。

为什么 Android 节点很关键？

之前 OpenClaw 有桌面端节点，大家觉得“用 AI 控制电脑执行脚本”挺好用。但 Android 节点的出现，把场景拓宽了。

因为手机才是我们日常上下文最丰富的地方。

你的位置、最新收到的短信验证码、刚拍的照片、各种 App 的通知推送，都在手机上。把手机变成一个 Node，意味着你的 Agent 突然有了随身携带的传感器。

这两类节点有明确的区分：

• 桌面节点： 偏向生产力自动化，比如操作文件、跑脚本、读取屏幕内容。
• Android/IOS 节点： 偏向个人上下文感知，比如位置流、消息通知、移动摄像头的视觉输入。

把手机节点化，等于是把移动端的碎片化能力，变成了 Agent 可以随时调用的标准组件。

架构设计：Node 与 Operator 解耦

OpenClaw 架构设计上并没有把客户端做成一个臃肿的“全家桶”，而是严格区分了 Node（节点）和 Operator（操作端）。

• Node（节点）： 只负责干活。它是一个无头（Headless）服务或者轻量级后台，职责仅仅是声明能力、接收调用、返回结果。
• Operator（操作端）： 负责控制和交互。用来发号施令、看执行状态、或者做人工审批（Human-in-the-loop）。

这种解耦非常友好。这意味着，如果你想把一个吃灰的树莓派或者旧手机接入 Agent 网络，你只需要跑一个纯粹的 Node 服务就行，不需要带着沉重的 UI 和控制逻辑。权限归权限，执行归执行，这在实际部署中极其重要。

真正好用的是“工作流组合”

单个设备的 API 调用不稀奇，写个 Python 脚本也能搞定。但把这些节点能力标准化并接入 OpenClaw 后，真正的威力在于编排。

你可以很顺畅地写出这样的流：

1. Agent 收到指令，调用 Android 节点读取最新的一条应用通知。2. LLM 分析通知内容，如果是重要报警，则调用桌面节点在你的电脑屏幕上弹窗。3. 如人不在电脑前（桌面节点无响应），再调用 Android 节点的短信接口发一条消息。

这类组合一旦跑通，Agent 就不再只是“云端对话机器人”，可以真正能在你的多台设备之间穿梭、执行真实任务的自动化助手。

节点服务目前还不成熟

这套节点服务目前还处于非常早期的阶段。

目前的 Android 节点，截至目前，官方甚至还没有正式发布可用的 APK 安装包。 核心代码和框架还在高频迭代中。但这应该是未来的一个方向。

Android节点初体验

虽然目前 Android 节点没正式发版，但在github仓库已经有完整代码，可以自己去拉取编译就可以安装安卓节点体验Openclaw的节点。

目前的安卓节点连接到Openclaw 网关后可以提供以下一些能力：

 📍 定位 - 获取当前位置   📸 拍照/录像 - 调用前后摄像头   🚶 运动数据 - 步数、活动状态（需授权权限）   🔔 通知 - 查看通知列表   📱 设备信息 - 电池、存储等状态   📅 日历 - 查看日程事件（需授权）   📞 通话记录 - 查看通话记录（需授权）   📇 联系人 - 搜索联系人（需授权）   📷 相册 - 查看最新照片（需授权）  

总结

如果把 OpenClaw 的节点服务剥开来看，它就是一套面向大模型时代的基础设施中间件。

把不同操作系统的底层能力做了标准化封装，解决了网络联通和能力注册的问题。对于想要真正把 AI 落地到物理设备上的开发者来说，这套机制提供了一个非常清爽的参考实现。

未来的 AI 应用，拼的不仅是 Prompt 写得有多好，更要看你的系统能调度多少真实的本地资源。

趋势必然是多 Agent 协同作业（Multi-Agent）——让负责调度的“老板”、负责写代码的“技术专家”和负责搜集信息的“情报员”各司其职，通过标准的协议进行串联、并联。

上篇文章我们介绍了多Agent的配置与接入，这里将拆解 OpenClaw 的多 Agent 协作机制，将上篇文章所创建的三个Agent，组建成为一支“数字”团队。

注意，这里使用的是点对点平级的Agent，不是主从/派生Agent。不适合真实公司一个Gateway多用户共用的情况，可能会有数据泄露的情况。

01 | 核心协作机制：Agent 们是如何沟通的？

在 OpenClaw 中，Agent 之间的通讯并非黑盒，而是建立在极其严谨的会话隔离（Session Isolation）与分发机制之上，从根本上杜绝了信息串扰。

• 唯一标识符（agentId）：定义 Agent 时，必须确保所有的 agentId 都是小写（例如：code-agent, news-agent, main），这是系统精准路由请求、建立独立上下文队列的基础。
• 指令流转路径：当你向 Agent X 下达复杂任务时，X 会通过内置工具 sessions_send 唤起专业的 Agent T 协助。Agent T 在自己的“独立沙箱”中完成工作流后将结果返回，最后由 Agent X 汇总交付。
• 会话隔离与穿透：默认情况下，每个 Agent 处于绝对的上下文隔离中，只关注自己的目标。如果调度者需要跨 Agent 查看历史会话，必须通过 sessions_spawn 或 sessions_history 工具显式调用。

02 | 权限边界与安全隔离

在多 Agent 协作的架构中，越权调用（比如让新闻助理拥有执行 Shell 脚本的权限）可能会带来灾难性的安全风险。OpenClaw 提供了细粒度的能力控制方案（Capability-based permissions）：

1. 开启点对点通讯白名单我们需要明确告知系统，哪些 Agent 允许直接对话。在配置中定义通讯白名单：

"tools": {  "agentToAgent": {    "enabled": true,    "allow": ["code-agent", "news-agent", "main"]  }}

2. 设定会话可见度（Session Visibility）为了防止非必要的信息干扰，可以控制 Agent 是否能“偷听”全局对话：

"tools": {  "sessions": {    "visibility": "all"  // agent仅可见自身会话，设置为 "all" 则全局可见  }}

3. 严格的工具权限控制（Deny 优先原则）根据岗位职责限制 Agent 能使用的工具。注意：在 OpenClaw 中，deny 的优先级永远高于 allow。 例如，“新闻资讯助理”只需要查阅和发送消息，必须明确禁用其系统操作权限：

{  "id": "news-agent",  "name": "新闻资讯助理",  "tools": {    "allow": ["sessions_list", "sessions_send", "read"],    "deny": ["write", "edit", "exec", "apply_patch", "bash"]   }}

03 | 内外兼修的解耦架构：身体 与 大脑

OpenClaw 将 Agent 的“物理运行环境”与“灵魂认知记忆”做了彻底的解耦。这种计算与状态分离的设计，使动态扩展多 Agent 变得非常轻量。每个 Agent 实体由两部分核心目录构成：

🛠 一、 agentDir (物理配置层 - Body)

默认路径： ~/.openclaw/agents/<agentId>/agent/这里是 Agent 的“躯壳”，负责最基础的工程接入与鉴权。

• auth-profiles.json：存放各类 API Keys、数据库密码等敏感认证凭证。
• models.json：定义该 Agent 调用的基座大模型（例如：主节点用复杂推理模型，子节点用低延迟的快模型）。

🧠 二、 Workspace (认知记忆层 - Brain)

默认路径： ~/.openclaw/workspace-<name>/这是 Agent 的核心“大脑”。在这个目录中，通过一系列纯文本的 .md 文件定义了 Agent 的运行时状态：

• 身份设定：SOUL.md (系统提示词、人格特性)、IDENTITY.md (名称、头像)
• 行为规范：AGENTS.md (行为规则、工作流、具体职责、擅长什么)、USER.md (主人的偏好)
• 知识与生命周期：MEMORY.md (长期记忆区)、HEARTBEAT.md (定时主动任务清单)

关注点： agentDir 决定了“用什么算力和密钥”，而 Workspace 决定了“它是谁、它懂什么、它该和谁协同”。不要在不同的 Agent 之间复用同一个 agentDir，这会导致 Auth 和 Session 严重冲突！

04 | 实战演练：组建你的三剑客团队

让团队无缝协同，最关键的是为每个 Agent 注入专属的灵魂（SOUL.md），并在 AGENTS.md 中写明团队的“路由表”和“协作边界”。

下面配置一个由“老板、技术专家、情报助理”组成的三人微型团队。

权限配置

修改openclaw.json文件，定义允许相互通讯的Agent，设置sessions对话全局可见。visibility：agent 仅可见自身会话，设置为 "all" 则全局可见，可选值:self、tree、agent、all

"tools": { "agentToAgent": {   "enabled": true,   "allow": ["code-agent", "news-agent", "main"] }, "sessions": {   "visibility": "all" }}

角色一：main（老板 / 任务调度中枢）

Workspace 路径: /root/.openclaw/workspace-main/

作为整个工作流的控制节点，main 负责接收你的自然语言需求，并将其拆解分发。

【注入灵魂：SOUL.md】

# SOUL.md - main我是小飞本，团队领导，负责协调团队任务分发。我的性格：高效、冷静。负责团队协调、任务调度和进度追踪。遇到需要具体执行的任务，请毫不犹豫地分配给对应的专业 Agent。团队通讯录在 AGENTS.md 中。

【团队通讯录与路由：AGENTS.md】

# AGENTS.md - 团队通讯录与任务调度规则## 团队成员- **newsAgent** (agentId: news-agent) - 职责：行业资讯抓取、信息总结。- **main** (你-agentId: main) - 职责：团队管理、任务分发。- **codeAgent** (agentId: code-agent) - 职责：代码编写与审查、系统架构设计。## 任务调度规则| 任务类型 | 目标 Agent | 调用语法示例 ||---------|----------|---------|| 资讯抓取/总结 | news-agent | `sessions_send(agentId="news-agent", task="...")` || 代码/技术支持 | code-agent | `sessions_send(agentId="code-agent", task="...")` |## 工作流约束不要自己写代码或抓取网页！必须通过 `sessions_send` 将专业任务委派给对应的 Agent，并等待其返回结果后再汇报给用户。

角色二：codeAgent（底层技术专家）

Workspace 路径: /root/.openclaw/workspace-code/

【注入灵魂：SOUL.md】

# SOUL.md - code-agent你是团队的首席技术专家。性格：严谨、极客、专注于最佳实践。职责：代码编写、审查、技术方案设计及 Bug 修复。当你收到代码需求时，必须提供可直接运行、包含清晰注释的代码片段。必要时允许使用本地工具链进行测试。

【团队通讯录与协作边界：AGENTS.md】

# AGENTS.md - 团队成员与协作边界- **main** (调度中枢/老板) - 你的直接汇报对象。当你完成脚本编写、组件开发或底层架构设计后，请将代码结果、测试覆盖情况和运行日志准确无误地汇报给它。- **codeAgent** (你 - 技术专家) - 负责底层代码实现与 Review。- **newsAgent** (情报助理) - 你不需要主动联系它，除非涉及资讯抓取爬虫的代码维护，或者它主动向你报告工具运行报错。

角色三：newsAgent（外部信息触角）

Workspace 路径: /root/.openclaw/workspace-news/

【注入灵魂：SOUL.md】

# SOUL.md - news-agent你是团队的情报助理。性格：敏锐、客观、信息处理速度极快。职责：只负责全网行业资讯的抓取、清洗与聚合。你需要过滤噪音，并将冗长的网页文本转化为结构化的简报返回给调度者。

【团队通讯录与协作边界：AGENTS.md】

# AGENTS.md - 团队成员与协作边界- **main** (调度中枢/老板) - 你的唯一业务汇报对象。请将抓取、清洗并结构化处理好的行业资讯简报（去除广告和冗余噪音）直接发送给它。- **codeAgent** (技术专家) - 你的技术后盾。如果你的资讯抓取脚本失效，或遭遇反爬虫策略导致工具报错，可以通过 `sessions_send` 向它求助，要求它提供修复方案或更新代码。- **newsAgent** (你 - 情报助理) - 专注全网资讯处理与降噪，不参与任何系统级别的代码修改。

结语

** 为不同 Agent 绑定不同的通讯渠道 (Channel Binding)**OpenClaw 支持将不同的 Agent 绑定到不同的通讯软件账号上。例如：你可以将 main 调度者绑定到你的个人 QQ 账号，而将 codeAgent 作为一个专门的机器人绑定到你们团队的 飞书 频道中。通过同一个 Gateway 服务，实现多渠道、多身份的无缝切换。

多 Agent 的魅力就在于此：将复杂的长逻辑链条，拆解为多个高内聚、低耦合的专业节点异步协作。

单机器人多群聊多Agent：配置多个群聊对应单机器人多个不同Agent，每个Agent之间数据隔离、模型可以不一样，实现群数据隔离。
多机器人多Agent：添加多个机器人连接到同一个OpenClaw，不同的机器人可以对应不同Agent，Agent之间数据隔离、模型可以不一样。

一、多群聊多Agent

多个群组同时往一个机器人发消息时由于它背后对应的是同一个Agent此时如果Agent有在处理任务其他消息会进入队列等待。如果想让同一个机器人在不同的群中扮演不同的角色，对应不同的技能，不同群组之间数据进行隔离能否做到？答案是可以做得到，这就是本章节要介绍的主要内容。

多群聊单个机器人对应OpenClaw中多个不同的Agent，就能达到上面所说的目标：不同的技能，不同群组间数据隔离。

备份OpenClaw

备份是为了避免误操作之后无法回复数据。

 cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak_$(date +%Y%m%d_%H%M%S) ls -l ~/.openclaw/openclaw.json*

恢复OpenClaw的配置。

 cp ~/.openclaw/openclaw.json.bak_YYYYMMDD_HHMMSS ~/.openclaw/openclaw.json ##openclaw.json.back_YYYYMMDD_HHMMSS为备份时的实际文件名

1、新增 Agents

使用openclaw agents add 命令可以添加新 Agent，需要把workspace 路径和Agent 的名称换为自己设置的路径和名称：

 openclaw agents add --workspace 工作空间路径 Agent名称   参数说明： • --workspace：独立的工作空间路径，如：/root/.openclaw/workspace-feishu-code •  Agent名称：此名称唯一，也啊AgentId，可为任意名称，推荐见名知意，如：code-agent • --model：需要使用自定义模型，可以添加此参数填写模型 ID，否则使用默认模型

这里以创建一个Code Agent 为例，命名为code agent，对应的 workspace 设置为/root/.openclaw/workspace-code-agent。

 openclaw agents add --workspace /root/.openclaw/workspace-code-agent code-agent

2、验证 Agent

查看创建的Agent是否成功。

 openclaw agents list

3、飞书群组绑定

配置飞书群组与Agent的绑定关系，先查看当前是否还有其他绑定数据，现在需要新增一个群组与Agent的绑定关系。查看当前的绑定关系：openclaw config get bindings

在原来的基础上添加新的绑定关系，如果当前绑定为空，可以在替换 id 为实际的飞书群组会话id后直接执行下面语句。

openclaw config set --json bindings '[  {    "agentId": "code-agent",    "match": {      "channel": "feishu",      "peer": {        "kind": "group",        "id": "oc_34fdfds3333jkjjjjhhhhbdd222"      }    }  }]'

对于存在绑定关系的可以先get bindings得到原先关系，在按照下面方法设置新关系。路由的匹配规则：从精确到模糊、从上到下。精确的路由规则尽量放在上面，Default 为兜底规则。
执行：config set --json bindings '[ 原绑定, 新飞书群绑定 ]'
绑定完后可再次执行：openclaw config get bindings 确认是否绑定正确。

4、群组允许列表

默认channels.feishu.groupPolicy是open，允许响应所有群组的消息，可以将其设置为allowlist。只响应经过授权的群组消息。
使用 allowlist 策略确保配置在 groupAllowFrom 中的群组才可访问 OpenClaw。

 openclaw config set channels.feishu.groupPolicy allowlist openclaw config set --json channels.feishu.groupAllowFrom '["oc_34fdfds3333jkjjjjhhhhbdd222"]'

在非授权群组@机器人时OpenClaw日志如下：

 [feishu] feishu[default]: received message from ou_29474ba1e15f058a10da8b83c037734d in oc_12c8eec3fcb22fc9aa634dfe29fddf2d (group) [feishu] feishu[default]: group oc_12c8eec3fcb22fc9aa634dfe29fddf2d not in groupAllowFrom (groupPolicy=allowlist)

5、重启Gateway

 openclaw gateway restart

配置完后可看到新的agent。

同一个机器人在不同的群组中绑定不同Agent，数据按群组隔离。

二、多机器人多Agent

上面使用过了 openclaw config 指令完成 OpenClaw 配置的更新，这里直接修改 openclaw.json 文件完成多机器人多Agent的配置。

1、创建工作空间

 mkdir -p /root/.openclaw/workspace-news-agent

编辑openclaw.json文件
vim /root/.openclaw/openclaw.json在 agents 键的 list 数组中添加一个 Agent，这里新增的 Agent 为 news-agent。

"list": [    {      "id": "main"    },    {      "id": "code-agent",      "name": "code-agent",      "workspace": "/root/.openclaw/workspace-feishu-code",      "agentDir": "/root/.openclaw/agents/code-agent/agent"    },    {      "id": "news-agent",      "name": "news-agent",      "workspace": "/root/.openclaw/workspace-feishu-news",      "agentDir": "/root/.openclaw/agents/news-agent/agent",      "model": {        "primary": "minimax-cn/MiniMax-M2.5"      }    }  ]

id: Agent 唯一标识agentDir: agent目录default: 标记默认 Agent 只有一个可为 trueworkspace: 工作空间路径model.primary:  Agent 使用的模型  

这里 id 为 main 的为默认主Agent，可以不要此Agent，添加 default 为 true 的key将其他Agent设置为主Agent。

2、配置飞书机器人

channels.feishu 键中新添加一个机器人：

"channels": {   "feishu": {     "enabled": true,     "accounts": {         "main":{              "appId": "cli_a911111111111111",              "appSecret": "WeiX4e8rjfLR91Uz0N7xTeqffffffffff"         },         "news-agent":{              "appId": "cli_a922222222222222",              "appSecret": "f9oDvGGhVRjDeAbXjEL1hggggggggggggg"         }     },     "domain": "feishu",     "groupPolicy": "open",     "dmPolicy": "open",     "allowFrom": [       "*"     ],     "renderMode": "card",     "streaming": true,     "footer": {       "status": true,       "elapsed": true     },     "groupAllowFrom": [       "oc_12xxxxxxxxxxxxxxxxx"     ]   } }

每个accounts 的 key（如code-agent）与每个 Agent ID 一一对应。 appId 和 appSecret 为每个飞书机器人的应用凭证。

3、配置绑定路由

"bindings": [    {           "agentId": "code-agent",       "match": {        "channel": "feishu",        "accountId": "main",        "peer": {          "kind": "group",          "id": "oc_12xxxxxxxxxxxxxxxxx"        }      }    },{        "agentId": "news-agent",        "match": {         "channel": "feishu",         "accountId": "news-agent"       }    }  ]

修改完openclaw.json后执行 openclaw config get bindings 检查绑定对不对。

match.channel: 固定为 "feishu"match.accountId: 对应飞书机器人的 key 这里是 news-agentagentId:  消息路由到的 Agent

还可以为每个Agent创建记忆文件，如IDENTITY、SOUL.md、AGENTS.md、MEMORY.md等。

4、重启Gateway

##重启openclaw gateway restart## 查看状态openclaw gateway status

重启完之后即可看到新接入的不同Agent的机器人。

完成上面的配置后OpenClaw同时具备了单机器人多群聊多Agent、多机器人多Agent的能力。

总结

这里使用了两种方式来完成 OpenClaw 多 Agent 的配置。使用命令行完成 Agent 的添加、配置的修改可能对非IT人员来说更简单下，直接修改~/.openclaw/openclaw.json 文件也许对于非码农来说可能难度更高。当然还可以直接使用小龙虾来完成上述模型，如果你用的是比较差的模型，你还是慎重，小龙虾比较容易把自己搞死。

单Agent如果职责过多可能会造成完成任务的质量下降，或记忆混乱。 为了职责分明，可以在多Agent的基础上让各个Agent之间相互通讯，进行分工协作完成任务。

要实现 UX 升级、RSS 集成、智能搜索、视觉创新四大模块，按传统开发节奏至少需要一个月。这次全程使用 Claude Code 作为结对编程伙伴。

今天分享的不是 AI 代替开发者的神话，而是介绍人机协作的真实工作流——哪些事交给 AI，哪些事需要自己把控，以及如何让 Claude Code 发挥最大价值。

🛠️ Claude Code 是什么？

简单说，它是 Anthropic 推出的命令行 AI 编程助手。

• 与 IDE 插件不同，Claude Code 直接在终端运行
• 可以读写文件、执行命令、运行测试、启动服务
• 支持多 Agent 并行执行——可以同时让几个 AI Agent 干不同的活
• 有 Plan 模式，可以先让 AI 做完整的技术方案，审核后再动手

📋 四大升级计划总览

💡 工作流一：Plan 模式，让 AI 先“过脑子”

传统开发的痛点： 我们通常会先写设计文档（Design Doc），但人脑很难记全整个项目的历史代码。可能会出现文档写得完美，一写代码全废 ——因为忽略了某个角落里的遗留依赖，导致中途必须推倒重来。

Claude Code 方式：进入 /plan 模式，AI 实时扫描代码库 → 发现隐蔽依赖 → 生成基于现状的可执行方案，还可以人为调整方案。

我: /plan 给 NewsFlow 添加动态词云功能Claude Code:📋 Plan Mode正在分析代码库...正在设计实现方案...计划概要:- 使用 d3-cloud 实现词云布局- 后端添加 /api/news/wordcloud 端点- 前端创建 WordCloud 组件- 支持点击筛选、深色主题适配- 预估工作量: 2 天详细步骤 [点击展开]...[批准计划] [修改建议] [取消]

Plan 模式的价值：

• 开发前做好计划
• AI 读代码库，了解现有架构
• 提出的方案遵循现有代码风格
• 可以在 AI 写一行代码之前就发现方向性问题

🤝 工作流二：并行执行，效率翻倍

Claude Code 可以多 Agent 并行执行，目前还升级了 Agent Teams 可以让团队成员无缝协同工作。

比如开发 UX 升级模块时，让三个 Agent 同时工作：

我: 启动并行任务Agent 1 (后端):正在扩展 /api/news 端点，添加 since 参数...✓ 添加 /api/news/latest 端点✓ 更新 NewsResponse 模型✓ 添加缓存逻辑Agent 2 (前端组件):正在创建 SkeletonLoader 组件...✓ 实现 shimmer 动画✓ 复用 NewsCard 布局结构✓ 添加可配置数量参数Agent 3 (测试):正在编写 E2E 测试...✓ 骨架屏测试✓ 主题切换测试✓ 无限滚动测试All agents completed in parallel ✅

这相当于同时有三个工程师在干活，而且它们之间不会产生代码冲突（因为我设置了清晰的依赖关系）。

🧩 工作流三：AI 写代码，我来 Code Review

Claude Code 生成的代码不是直接提交的，而是进入 Code Review 流程：

Agent: 代码已生成，正在启动 code-reviewer Agent...code-reviewer:审查文件: frontend/src/components/WordCloud.tsx发现 1 个 CRITICAL 问题:- 词云颜色未适配深色主题发现 2 个 HIGH 优先级问题:- 缺少错误边界处理- 未添加 loading 状态修复建议 [点击应用]

对于 code-review 出现的问题可以选择：

1. 让 AI 自动修复
2. 自己手动修改
3. 标记为"可接受"

这种工作流让开发者保持对代码质量的掌控，AI 是加速器，不是黑盒。

📊 实战案例：RSS 集成模块

这是四个模块中最复杂的一个，涉及后端解析、配置系统、前端重构。NewsFlow 需要聚合来自不同源（少数派、36Kr、个人博客）的 RSS，痛点是格式标准不一（RSS 2.0）。

以前写这种解析器，需要手动去调试每个字段的映射。而 Claude Code 具有**数据归一化（Normalization）**能力，它理解了“聚合阅读器”的业务本质。

来看看 Claude Code 是怎么完成的。

Phase 1: 架构设计（Plan 模式）

Claude Code 分析结果:当前架构问题:- NewsItem.source 是硬编码字面量类型- 添加新数据源需要修改 7 个文件- 无统一配置管理建议方案:✓ 使用 JSON 配置文件管理数据源✓ feedparser 解析 RSS✓ 渐进式重构，保持向后兼容✓ 分 4 个 Wave 并行执行

Phase 2: 并行开发

Wave 1 (并行):├── Agent A: 安装 feedparser 依赖├── Agent B: 创建 data_sources.json 配置├── Agent C: 实现 RSS 抓取器└── Agent D: 编写 RSS 单元测试Wave 2 (Wave 1 完成后启动):├── Agent E: 重构数据模型├── Agent F: 重构 API 端点├── Agent G: 编写 API 测试└── Agent H: 更新 config.py

Phase 3: 集成测试

Agent: 启动集成测试✓ 向后兼容性测试通过✓ 标签筛选功能正常✓ Top 5 统计显示正确✓ 已读变色功能工作E2E 测试报告: 16/16 通过

🎨 视觉创新模块：词云组件的诞生

动态词云是这次升级的"颜值担当"，功能横跨了后端（Python）和前端（React），是检验 AI 全栈能力的试金石。业务流程：后端提取关键词 -> 前端 D3 可视化 -> 点击交互联动。

Phase 1: Plan 模式确定方案

我: /plan 给 NewsFlow 添加动态词云功能Claude Code (planner):━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━# 实现计划：动态热度词云## 技术选型- 词云布局: d3-cloud（本地实现，无需大模型 API）- 中文分词: jieba- 后端 API: GET /api/news/wordcloud- 前端组件: WordCloud.tsx## 实现阶段1. 后端词频统计 API（2h）2. 前端依赖安装（0.5h）3. 词云组件开发（4h）4. 点击筛选交互（2h）5. 错误处理和优化（2h）━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━我: yes，按此计划执行

Phase 2: 按计划执行

Agent (执行):━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━正在执行 Phase 1: 后端词频统计 API✓ 添加 GET /api/news/wordcloud 端点✓ 集成 jieba 中文分词✓ 添加 TTLCache 缓存（300秒）✓ 支持 source 和 tags 参数过滤正在执行 Phase 2: 前端依赖✓ 安装 d3-cloud, d3, d3-selection, d3-scale正在执行 Phase 3: 词云组件✓ 创建 WordCloud.tsx（700+ 行）  • 骨架屏加载动画（shimmer effect）  • D3 过渡动画（渐入 + 浮动）  • 错误状态 UI（重试按钮）  • 响应式布局（移动端适配）  • 主题色适配（浅色/深色）正在执行 Phase 4: 点击筛选交互✓ 实现点击词语触发新闻筛选✓ 与现有筛选器集成（AND 逻辑）正在执行 Phase 5: 错误处理和优化✓ 添加错误边界✓ React.memo 优化重渲染✓ 加载状态管理━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 3: Code Review

code-reviewer Agent:审查文件: frontend/src/components/WordCloud.tsx━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━✓ TypeScript 类型安全✓ React.memo 优化重渲染✓ 错误边界完善✓ 无障碍性标签完整✓ 性能优化✓ 主题色正确适配代码质量: 优秀建议: 无需修改

🎯 核心经验总结

✅ Claude Code 擅长的

1. 重复性代码 - 数据模型、API 端点、CRUD 操作
2. 标准化任务 - 单元测试、E2E 测试、配置文件
3. 并行执行 - 多个独立模块同时开发
4. 代码审查 - 第一轮筛选，我聚焦于架构和业务逻辑

⚠️ 需要人工把控的

1. 架构决策 - Plan 模式给出方案。开发人员来拍板。是做单体还是微服务？数据怎么流转？
2. 业务逻辑 - AI 不懂产品，需求必须我明确。
3. 代码审查 - 最终审核权在人手里，Code Review 成了核心工作。
4. 调试疑难问题 - AI 能帮忙，需要开发者引导。

具体、带上下文、有参考， Claude Code 的输出质量会高很多。

结语

把AI用好了，Agent就是你的团队成员。AI 不是替代开发者，而是放大开发者的能力。

• 开发者花更多时间在架构设计/审核和需求把控上
• Claude Code 负责代码实现和重复劳动
• Code Review 保持代码质量在可控范围内

AI 编程不是简单地理解为 AI 替我们"写完了所有代码"，而是有整套 AI-Native 工作流：以 Claude Code 这类工具为执行引擎，以 Vibe Coding 为协作理念，让 AI 真正参与到软件工程的每个阶段。

  本文将完整记录这一开发流程，通过 NewsFlow 项目的真实案例，展示 AI 如何参与从产品构思到上线的各个环节，以及 AI-Native 工作流是如何运作的。

一、开发实录：工具与方法

1.1 核心工具：Claude Code 的能力边界

Claude Code 不是简单的"代码生成器"，而是一个具备工程能力的 AI 智能体（Agent）。它通过终端交互环境，能够：

   文件操作：读取、编辑、批量重构代码文件
   命令执行：运行测试、安装依赖、操作 Git、部署服务
   上下文管理：通过分析项目结构理解代码库
   子代理（Subagents）：并行处理多任务，如同时审查代码和检查安全漏洞

在实践中，Claude Code 扮演的角色随阶段变化：

  产品阶段：需求顾问（头脑风暴、可行性分析）
  设计阶段：架构师（技术选型、方案设计）
  实现阶段：全栈工程师（前后端代码实现）
  验证阶段：测试工程师（调试、优化、写测试）
  交付阶段：DevOps（部署脚本、本地运维配置）

1.2 方法论：Vibe Coding 的底层支撑

之所以能实现全流程 AI 协作，依赖于 Vibe Coding（氛围编程） 的工作理念——这不是一套严格的流程规范，而是一种沉浸式的协作心态：

  自然语言驱动：用"做个深色主题的新闻卡片"代替详细的需求文档
  即时反馈循环：边聊边做，有疑问当场澄清，确认后立即执行
  上下文连续性：AI 记住之前的所有决策，不会每次归零重启

这种理念让 AI 能够真正参与创造性工作（如产品构思），而非仅仅是执行指令。

二、全流程开发实录

阶段一：产品构思与技术验证

阶段目标：把模糊的想法变成可执行的方案，验证技术可行性。AI 协作过程：

头脑风暴阶段：

开发者：我想做个技术新闻聚合站，聚合 IT 之家和界面新闻，要简洁好看。Claude Code: 这个需求很清晰。先澄清几个产品决策：1. 是只展示标题列表，还是要有详情页？2. 内容怎么获取？被动等用户提交，还是主动爬取？3. 更新频率要求？实时还是每日批量？4. 需不需要用户系统（收藏、登录）？开发者：先 MVP，只展示列表，跳转到原文。主动爬取，每日更新一次。不要用户系统，越简单越好。Claude Code: 明白，纯展示型产品。技术上建议：- 前端：Next.js 15 App Router（SEO 好，部署灵活）- 后端：FastAPI（Python，写爬虫方便）- 数据存储：TTLCache 内存缓存（轻量级，适合 MVP）- 部署：跨平台启动脚本 + systemd（本地开发和生产环境）这个方案零成本启动，后期流量大了再优化。需要我现在验证一下 IT 之家的反爬策略吗？

技术验证：Claude 直接写了段测试代码验证爬虫可行性，确认可以拿到数据。

关键产出：
产品需求明确（边界清晰）
技术栈确定（Next.js 15 + FastAPI + 内存缓存）
项目初始化完成

阶段二：建立 AI 项目记忆

关键认知：AI 需要"项目记忆"来理解代码库的上下文，这样才能生成符合项目规范的代码。

AI 协作过程：

当项目骨架创建后，AI 会主动分析项目结构，建立"项目记忆"：

Claude Code: 正在分析项目结构...检测到技术栈：Next.js 15 (App Router), TypeScript, Tailwind CSS, FastAPI前端架构：- App Router 模式（app/page.tsx, app/layout.tsx）- React 本地状态管理（useState，无全局状态库）- 前端 API 代理模式（/api/news → 后端）- 组件组织：src/components/（Header, StatsBar, NewsCard, NewsGrid）后端架构：- FastAPI + uvicorn（全异步）- 爬虫实现：ithome.py（多页分页）+ jiemian.py（24小时滚动）- 数据存储：TTLCache 内存缓存（无持久化）- 中间件：速率限制、请求日志、CORS、GZip- 日志系统：loguru 结构化日志代码质量：- TypeScript 严格模式- ESLint 严格规则- 前端：Jest 已配置但无测试文件- 后端：pytest 已配置，10 个测试文件，覆盖率 7.22%已建立项目记忆，后续所有对话都将基于这些上下文进行。

CLAUDE.md 的作用：

  持久化记忆：避免每次对话重复项目背景和技术约束
  风格一致性：AI 生成的代码与现有代码风格统一
  减少无效确认：既然已知用 Tailwind，就不会再问"用什么 CSS 方案"

最佳实践：

  1. 进入项目第一件事（或技术栈变更后）：运行 /init
  2. 将 CLAUDE.md 纳入版本控制，团队协作时保持一致
  3. 在每次开发会话开始时，让 AI 分析项目结构  4. 确认 AI 理解当前的技术约束和约定  5. 项目架构或技术栈变更后，重新建立项目记忆

阶段三：架构设计与数据建模

阶段目标：完成数据模型设计、API 规范、组件结构。

AI 协作过程：

Claude 根据已建立的上下文，直接生成了完整的架构文档，并主动考虑了扩展性：

Claude Code: 我看到你选择了"每日更新"的策略，建议数据模型这样设计：**数据模型（Pydantic v2）**：class NewsItem(BaseModel):    source: Literal['ithome', 'jiemian']    title: str    url: str    time: str  # YYYY-MM-DD HH:MM:SS    summary: str    category: Optional[str]  # IT之家有，界面新闻无**缓存策略（TTLCache）**：- 缓存键：`ithome_news`, `jiemian_news`, `all_news`- 过期时间：300 秒（5 分钟）- 最大条目数：1000- 特性：TTL 过期、异步锁保护、命中率统计考虑到后期可能加搜索，是否需要将摘要扩展到更长的文本？另外，要不要考虑引入 Redis 替代内存缓存？开发者：暂时不用，MVP 阶段够用了。爬虫逻辑怎么设计？Claude Code: 两个方案：[方案 A] 异步 HTTP 请求：httpx + BeautifulSoup4，简单直接[方案 B] 分布式爬取：Scrapy + Celery + Redis，支持大规模抓取考虑到 MVP 阶段，我推荐方案 A，但代码结构要预留扩展性。比如抽象异步上下文管理器，后期换 Scrapy 只需修改实现。需要我现在生成完整的数据模型和爬虫基类吗？

关键产出：  1. Pydantic v2 数据模型（带字段验证）  2. TTLCache 缓存实现（带统计功能）  3. 爬虫抽象类（异步上下文管理器）  4. API 路由规划（RESTful 规范）  5. 前端组件结构（基于 Next.js App Router）

阶段四：核心功能开发

阶段目标：完成数据爬取、前端展示、基础交互。

AI 协作过程：

这是最高强度的编码阶段。Claude Code 展现了上下文感知生成的能力——它不再询问技术细节，而是基于项目分析直接生成符合项目规范的代码。

场景示例 1：NewsCard 组件开发

开发者：做新闻卡片组件，深色主题，展示标题、摘要、时间、来源标签。Claude Code: （基于项目分析，已了解 Tailwind 配置和颜色定义）明白，使用 slate-900 作为卡片背景，gray-100 作为文字色。根据项目约定，摘要使用原文 summary，时间用相对时间格式化（2小时前）。来源标签用不同颜色区分：IT 之家用橙色，界面新闻用蓝色。（生成代码...）需要我加上 hover 时的阴影效果吗？另外，点击卡片是新标签页打开还是当前页跳转？

场景示例 2：爬虫逻辑调试

开发者：IT 之家爬虫报 403 错误。Claude Code: （读取 scrapers/ithome.py）检测到缺少 User-Agent 头。此外，IT 之家有简单的反爬，建议加 1-3 秒随机延时。需要我帮你加上这些，并测试一下吗？开发者：加吧。Claude Code: （修改代码，运行测试）已修复。抓取 10 条测试数据成功。建议把爬取间隔配置化写到 .env 里，方便调整：```bashITHOME_DELAY=1.0ITHOME_TIMEOUT=10

场景示例 3：批量重构

当需求变更（如"缓存 TTL 从 300 秒改到 600 秒"）时：

开发者：所有地方的缓存 TTL 改成 600 秒。Claude Code: 正在扫描项目...发现 3 处需要修改：1. backend/app/config.py（CACHE_TTL 默认值）2. backend/app/utils/cache.py（__init__ 默认参数）3. backend/.env.example（注释说明）已统一修改为 600 秒，并确保所有引用处同步更新。

子代理并行处理

Agent还可以多任务并行工作，如同时处理前端样式优化和后端性能优化。Claude 创建了子代理：

  Subagent A：优化前端虚拟滚动（处理长列表性能）
  Subagent B：给 API 加缓存统计接口

两者并行工作，互不干扰，主会话保持对整体进度的把控。

阶段五：测试与质量保证

阶段目标：确保功能稳定，修复潜在问题。

AI 协作过程：

传统测试中，开发者需要手动编写测试用例、反复运行、查看日志。而在 AI-Native 流程中，测试是一个对话式排查过程。

场景：性能问题诊断：

开发者：新闻列表加载慢，分析一下。Claude Code: （读取前端代码和后端 API 逻辑）发现三个问题：1. API 没做分页，一次性返回所有数据（当前缓存已有 2000+ 条）2. 前端图片没做懒加载，首屏加载 20 张图3. 缓存命中率低，频繁请求后端修复建议：[1] API 加分页（limit/offset），默认 20 条[2] 图片加 loading="lazy" 属性[3] 调整缓存 TTL 从 300 秒到 600 秒优先级？建议先做分页，影响最大。

测试现状评估：

开发者：评估一下当前测试覆盖情况。Claude Code: 正在分析测试基础设施...前端测试：- ✅ Jest 29.7.0 + @testing-library/react 已安装- ✅ jest.config.js 配置正确（jsdom 环境、覆盖率收集）- ❌ 0 个测试文件（*.test.tsx 或 *.spec.tsx 不存在）- ❌ 0% 覆盖率（11 个源文件完全未测试）后端测试：- ✅ pytest 7.4.4 + pytest-asyncio + pytest-cov 已安装- ✅ pyproject.toml 配置完整（测试标记、覆盖率报告）- ⚠️ 10 个测试文件（组织混乱：根目录 6 个，backend/ 3 个，backend/tests/ 2 个）- ❌ 7.22% 覆盖率（仅 models.py 78.57%，其他核心模块 0%）核心问题：1. 完全未遵循 TDD 原则（所有生产代码都没有测试）2. 测试文件组织混乱（未使用 pytest 标准组织）3. 缺少关键测试类型（API 路由、抓取器、缓存、中间件）

测试补充建议：

Claude Code: 建议分阶段补充测试：阶段一（紧急）：- 清理测试文件组织（移至 backend/tests/）- 为核心组件添加测试（NewsCard, StatsBar）- 为工具函数添加测试（utils.ts, logger.ts）阶段二（核心）：- 添加 API 路由集成测试（test_routers.py）- 添加抓取器异步测试（test_scrapers.py）- 添加缓存功能测试（test_cache.py）阶段三（全面）：- 添加 E2E 测试（Playwright）- 设置覆盖率目标（80%+）- 配置 CI/CD 自动化测试需要我现在开始补充测试吗？

安全审查：通过子代理自动扫描依赖漏洞，发现 lodash 版本过低，提示升级。

阶段六：文档补充

阶段目标：上线验证，补全文档，准备交接。

AI 协作过程：

   Smoke Test：Claude 运行启动脚本，验证主流程通畅
   文档生成：基于代码结构自动生成项目文档
   API 文档：使用 FastAPI 自动生成交互式文档（/docs Swagger, /redoc）

最终交付物：
   ✅ 可访问的网站（已上线）
   ✅ 完整代码库（含注释）
   ✅ 部署文档（README.md, frontend/README.md, backend/README.md）
   ✅ 启动和停止脚本（start.bat/start.sh, stop.bat/stop.sh）
   ✅ 环境变量示例（.env.example）
   ✅ API 文档（/docs, /redoc）
  ⚠️ 测试覆盖：前端 0%，后端 7.22%（需后续补充）

三、关键经验：为什么 AI 能完成全流程？

3.1 上下文连续性是关键

分析项目结构后，AI 记住了：
  产品定位：纯展示型，深色主题，每日更新
  技术约束：Next.js 15 + FastAPI，Tailwind 样式规范
  已做决策：用内存缓存而非数据库，暂时不做用户系统
  代码风格：TypeScript 严格模式，ESLint 规则，Pydantic v2 数据验证

这使得在部署阶段，AI 依然记得最初定的技术栈，不会突然问"要不要换成 Vue"。

3.2 自然语言接口降低沟通成本

在架构设计阶段，用自然语言对话完成了传统开发中需要长时间评审的技术方案。当 AI 问"要不要引入 Redis 替代内存缓存"时，回复"暂时不用，MVP 阶段够用了"，这种模糊但高效的沟通只有在 Vibe Coding 状态下才能实现。

3.3 工具链集成实现闭环

Claude Code 不仅是"聊天写代码"，它能：

执行命令：运行测试、部署服务、启动/停止应用读写文件：批量重构、更新配置、生成文档并行处理：子代理让测试和开发同步进行

这种REPL（读取-求值-输出-循环）式的交互，让 AI 能真正参与工程实践，而不只代码建议。

3.4 诚实地面对局限

AI 协作也不是万能的。在本次开发中，真实地记录了：
  ❌ 无数据库持久化（仅内存缓存）
  ❌ 测试覆盖不足（前端 0%，后端 7.22%）
  ❌ 无 CI/CD 自动化
  ❌ 无定时任务配置
  ❌ 无分布式缓存

这些局限不是 AI 的问题，而是项目阶段的自然选择。AI 帮助我们在 MVP 阶段快速上线，同时清晰地记录了改进方向。

四、避坑指南

  正确使用项目分析：在开发前让 AI 分析项目结构，确保理解技术栈和约定
  关键节点人工确认：虽然 AI 能独立完成部署，但生产环境变量修改等高危操作必须人工确认
  定期清理上下文：长时间开发后重新分析项目结构，防止早期重要决策（如"不做用户系统"）被遗忘
  保持代码审查：AI 生成的代码功能可用，但需关注边界情况处理（如空值、异常流）
  区分 Vibe 的 Ask 与机械 Ask：如果感觉像在填表而不是对话，说明需要调整提问方式。Vibe 的 Ask 应该像结对编程时的即时确认，而非面试问卷。
  诚实记录局限：不要为了"看起来完美"而隐瞒问题。诚实地记录当前状态（无数据库、测试不足），并讨论改进空间。
  TDD 是硬约束：如果选择 TDD 工作流，必须先写测试再写代码。如果暂时不遵循 TDD，也要明确记录原因。

五、结语：AI-Native 开发的未来

NewsFlow 的开发证明了一件事：AI 已经能够承担软件工程的全流程工作，不再是简单的代码补全工具。

在这个过程中，Claude Code 作为具备工程执行能力的智能体，让我们可以用自然语言驱动从脑洞到产品的完整链路。而 Vibe Coding 作为一种工作理念，确保了这种协作是流畅、沉浸且高效的。

一个人 + AI = 产品团队（产品+架构+前后端+测试+运维）。这不再是比喻，而是已经落地的现实。

AI 协作可以让我们清楚的知道当前项目的真实状态：
  ✅ 快速实现 MVP，验证产品想法
  ✅ 技术栈现代化（Next.js 15 + FastAPI）
  ✅ 代码质量高（TypeScript 严格模式、Pydantic v2）
  ⚠️ 需要补充测试（TDD 工作流）
  ⚠️ 需要引入数据库（持久化）
  ⚠️ 需要配置 CI/CD（自动化）

AI 可以帮我们写代码，还可以帮我们看清了项目的全貌，清楚了解做得好的地方和需要改进的地方。这才是 AI-Native 开发的真正价值：不是替代开发者，可以让开发者更快地做出更好的决策。

Agent也从最开始的使用特定提示词、工具调用到基于MCP、基于工作流、A2A形式的，再到目前基于Skills。

在2025年一系列标准协议的发布，Agent进化已经进化到极低门槛。在2025年底Anthropic推出了Skills，从这两三月来看各个厂商也加入了Skills的支持，随着各家厂商的跟进Agent将会有更高的可用程度。

Skills是什么

使用官方定义：Agent Skills是一种简单、开放的格式，为Agent赋予技能以及专业知识。

• 纯提示词的Agent只能够使用大脑(大模型)，去解决自身所具备知识的能力，没有执行脚本的能力。
• 使用了工具调用的Agent具备了通过工具去扩充大模型知识边界的能力。
• 基于MCP的Agent能够接入所有提供MCP协议的平台、工具等等，使得Agent的能力扩充更加方便。
• 基于A2A的Agent，具备了Agent之间互相通讯、调用的能力。
• 基于A2UI的Agent，统一了Agent的UI渲染格式。

Skill不是让Agent“把书背下来”，而是让Agent“学会查字典”。通过渐进式披露，Agent 平时轻装上阵，只有在需要处理特定任务时，才瞬间加载对应的 Skill。

MCP与Skill区别：

MCP是用来统一工具调用的协议。

Skill可指导Agent如何使用各种工具、各种脚本、完成指定工作流，它把专业知识、工作流融入Agent自身。
Skills包含指令、脚本、资源文件夹，Agent可发现并利用Skills来完成指定任务。

每个Skill包含什么

每个Skill是一个文件夹。Skill文件夹必须包含一个SKILL.md文件，该文件包含元数据（至少包括name和description）以及告诉智能体如何执行特定任务的指令。Skill还可以包括脚本(scripts)、模板/资源(assets)和参考资料(references)。

 skill-name/ ├── SKILL.md          # 必须: 指令 + 元数据 ├── scripts/          # 可选: 可执行代码 ├── references/       # 可选: 文档 └── assets/           # 可选: 模板, 资源

SKILL.md文件

每个Skill必须包含一个SKILL.md文件，该文件包含 YAML 前置信息和 Markdown 内容。

1、前置信息：

 --- name: skill-名称 description: 对这项技能的作用以及何时使用它的描述。 ---

前置信息除了必须包含的name与description字段外，还可以包括以下可选字段：

 license：许可证名称 compatibility：环境要求,最多500个字符。 metadata:  author: linx  version: 0.1 allowed-tools: 预先允许使用的工具

2、Markdown内容
前置信息后的Markdown正文包含技能说明，没有格式限制。写下任何有助于智能体有效执行任务的内容。

下面是一个用于PDF转Word的Skill的SKILL.md文件内容：

---name: pdf-to-worddescription: 将PDF文档转换为Word格式(.docx)。支持文本提取、表格转换和基本格式保留。使用命令行界面进行批量转换或单文件处理。---# PDF转Word转换工具## 快速开始```bash# 单文件转换python scripts/convert.py input.pdf output.docx# 批量转换整个目录python scripts/convert.py --batch input_folder/ output_folder/# 保留原PDF中的图片python scripts/convert.py --keep-images input.pdf output.docx```## 功能说明- **文本转换**：提取PDF中的文本内容并转换为Word格式- **表格处理**：识别并转换PDF中的表格结构- **格式保留**：保留基本的段落格式和字体样式- **批量处理**：支持整个目录的批量转换- **图片保留**：可选保留PDF中的图片元素## 依赖要求- Python 3.8+- pdfplumber（PDF文本提取）- python-docx（Word文档生成）## 安装依赖```bashpip install pdfplumber python-docx```## 使用场景当用户需要：1. 将PDF文档转换为可编辑的Word格式2. 从PDF中提取内容用于后续编辑3. 批量转换多个PDF文件4. 在命令行环境下进行文档格式转换

Skills能做什么

Skills 的核心在于将抽象的任务转化为可执行的标准化流程（SOP）。它不仅仅是工具的集合，更是“专家经验”的代码化。通过定义不同的 Skills，我们可以让 Agent 在不同领域瞬间变身为“熟练工”。

1. 自动化媒体运营 (Content Operations)
   不再需要人工在不同平台间复制粘贴和调整格式。

• 公众号/社群发布 Skill：能够读取 Markdown 草稿，自动进行排版优化（如添加样式、图片自适应），调用 API 推送到微信公众号后台，甚至自动生成摘要和封面图。

• 小红书/社交媒体矩阵 Skill：根据同一份素材，自动改写成适合小红书（Emoji丰富、语气活泼）、LinkedIn（专业商务）等不同平台的文案，并自动完成发布。

2. 研发效能提升 (DevOps & Coding)
   将资深程序员的经验封装给 Agent，处理繁琐的维护工作。

• 代码重构与审查 Skill：不仅仅是“读代码”，而是加载项目的代码规范（Lint规则），对旧代码进行重构，自动修复常见的 Anti-patterns，并生成重构报告。

• 单元测试生成 Skill：扫描指定模块，根据业务逻辑自动编写覆盖率达标的测试用例，并执行测试脚本验证通过率。

• 环境排查 Skill：当开发环境报错时，自动抓取日志、分析依赖树冲突，并给出修复脚本。

3. 数据智能分析 (Data Analysis)
   让 Agent 具备数据分析师的能力，实现从“原始数据”到“决策建议”的闭环。

• 可视化报表 Skill：用户只需上传一个 Excel 或 CSV，Agent 即可调用 Python 脚本（如 Pandas/Matplotlib）进行数据清洗，分析关键指标，并自动生成趋势图、饼图，最终产出一份带图表的分析报告。

• 舆情/竞品分析 Skill：自动抓取指定关键词的网络信息，进行情感分析和关键词提取，生成日报。

4. 本地数字管家 (Digital Housekeeping)
   管理混乱的本地环境，让文件井井有条。

• 智能文件整理 Skill：自动扫描杂乱的“下载文件夹”，根据文件类型（文档、图片、安装包）或内容关键词，将其移动到归档目录，并重命名为标准化格式（如 2026-01-Invoice-项目A.pdf）。

• 会议纪要整理 Skill：读取长录音或会议速记，自动提取 Action Items（待办事项），同步到 Notion 或 Jira 等项目管理软件中。

Agent加载Skill机制：渐进式披露

大模型的上下文窗口是有限制的目前最大的模型上下文也不过100万Tokens，基于大模型的Agent都不掉Context的魔咒，使用了Skills的Agent也不例外。

官方定义了Skill的加载机制：渐进式披露。
大模型上下文越长模型出错的概率就越大，上下文的长度也是有限的，为了避免Context魔咒，Skills定义了其渐进式披露的机制。

Skill定义了三级加载机制：

1、一级：元数据(始终加载)
Agent启动时就会加载SKILL.md文档内的元数据name与description字段，约100 tokens。
Agent通过识别用户消息与Skills元数据来决定是否需要使用Skill。
Agent初始只加载约100 Tokens元数据，也意味着Agent可以包含大量的Skills，不会出现Context魔咒。

2、二级：指令(触发加载)
为整个SKILLS.md文件,Skills触发时就会把整个SKILLS.md加载到Agent上下文，建议SKILL.md少于5000 tokens。

Agent识别到需要触发Skills时就会将该Skills所属的SKILLS.md文件加载到上下文。

3、三级：资源(脚本/引用/资源，动态加载)
资源包括：脚本代码(Scripts Code)、引用文档、资源、子Skills等。
这几类资源只有在触发Skills后Agent加载SKILLS.md文件到上下文，Agent才会根据实际需要加载此类资源(脚本文件不会加载到上下文，只会将脚本执行结果加载到上下文)。

Skills通过渐进式披露，尽可能的控制Context魔咒的出现，但还是无法避免此问题出现，加载过多Skills还是会导致Agent上下文爆炸或Agent准确率下降。

Skills如何使用

Claude Code对Skills的支持最好，现在越来越多工具也开始支持Skills除了Claude Code外还可以使用Codex、Cursor、opencode、Antigravity等等。
将Agent Skills融合到自己开发的Agents中。

Skills安装

手动安装

下载需要的Skills，如anthropics官方提供的Skills(https://github.com/anthropics/skills)，对于Claude Code：

 全局Skills：C:\Users\XXX\.claude\skills   项目Skills：项目路径\.claude\skills  

自动安装

将需要安装的Skills丢给Claude Code让它帮你安装即可。

安装完成后退出重新登录Claude Code即可，新版本已支持热加载。

 /skills 查看当前所有Skills

Skills使用

在使用Skills可以通过Skills名称指定使用哪个Skills也可以，让Agents自己去决策需要使用哪个Skills。

1、怎么开发一个法律法规应用，需要先进行头脑风暴，触发了brainstorming SKills(头脑风暴技能)。

2、把文件 @"Attention Is All You Need.pdf" 转为word文件，触发PDF-Word转换Skills。

3、直接输入/即可调用对应技能，例如：/pdf-word-converter 把XXX PDF文件转为Word文件。

编写一个Skills

一个最简单的Skills只需要在一个符合Skills命名规则的文件夹里创建一个SKILL.md文件，该文件需要包含 YAML 前置信息和 Markdown 内容。将该文件夹移动到C:\Users\xxx.claude\skills\demo-skills目录，重启Claude Code即可。

创建如下目录及文件：

demo-skills/SKILL.md

SKILL.md文件内容：

 --- name: demo-skills description: 一个Skills介绍工具。简单描述Agent Skills，以及怎么创建最简单的Skills。适用于介绍Skiils等场景。 --- # Skills介绍工具 用于Agent Skills的简单描述。   ## Skills是什么 Skill可指导Agent如何使用各种工具、各种脚本、完成指定工作流，它把专业知识、工作流融入Agent自身。   ## Skills如何创建 一个最简单的Skills只需要在一个符合Skills命名规则的文件夹里创建一个SKILL.md文件，该文件包含 YAML 前置信息和 Markdown 内容。   ### SKILL.md文件格式   - 前置信息：       ---      name: skill-名称      description: 对这项技能的作用以及何时使用它的描述。      --- - Markdown内容   前置信息后的Markdown正文包含技能说明，没有格式限制。写下任何有助于智能体有效执行任务的内容。   ### 完整SKILL.md文件内容示例      ---      name: pdf-to-word      description: 将PDF文档转换为Word格式(.docx)。支持文本提取、表格转换和基本格式保留。      ---      # PDF转Word转换工具      ## 脚本使用描述      ```bash      python scripts/convert.py input.pdf output.docx      ``` ## 注意事项 - 本技能只做Skills的简单介绍

Skills能带来什么

如果说 MCP 搭建了 Agent 连接世界的桥梁，那么 Skills 则赋予了 Agent 真正的职业灵魂。
通用大模型什么都懂一点，但落地到具体业务时，往往是“这就触及到我的知识盲区了”。Skill 的出现，是为了解决大模型在垂直场景下的水土不服。

它不再是简单的“喂语料”，而是让 AI 学会“守规矩”。通过 Skill，我们将业务逻辑固化下来，让 AI 的每一步操作都有章可循。

这其实也暴露了大多数组织的脆弱性：我们的流程往往过于依赖人的“灵光一现”。Skill 强迫我们把这些隐性知识显性化。未来，衡量一个团队技术底蕴的，或许不是文档库有多厚，而是你们沉淀了多少好用的 Skills。

参考资料：https://agentskills.io

  模型私有化部署对显卡资源的消耗比较高，对于一个4B模型BF16部署的资源已经达到9GB(4B×2×10⁹ ×1.2≈9 GB)，对于14B模型最少需要32GB显存需求。就算是部署低精度或量化版模型一个基本可用的14B模型也最少需要16GB左右显存。

  对于这种规模的显存需求对于个人或小公司来说同时部署N个全量微调的专家模型似乎有点难。如果部署10个微调的领域专家模型需要的资源是N倍的显存资源(10 * 9GB =90GB)， 这已经是超过一张A100的显存资源也超过3张4049(24GB)卡的资源。

微调

  微调除了全参数微调还有参数高效微调（PEFT），通过高效微调LoRA后根据微调的参数规模适配器的大小只有几十MB到几百MB不等。前面文章我们也介绍过LoRA，这边再简单介绍下LoRA的基本原理。LoRA (Low-Rank Adaptation) 是目前最主流的大模型高效微调（PEFT, Parameter-Efficient Fine-Tuning）技术。它的核心思想是：冻结预训练模型的权重，仅在各层中注入可训练的低秩矩阵（Low-Rank Matrices）。
    W = W₀ + ΔW = W₀ + BA
其中：
  W₀ 是冻结的预训练权重（维度 d x d）。
  B 是 d x r 的矩阵（初始化为 0）。
  A 是 r x d 的矩阵（高斯初始化）。
  r 是秩（Rank），通常远小于 d（通常取8~128）。
优势：
  显存极低： 仅需训练不到 1% 的参数。
  不破坏原模型： 原模型权重不变，LoRA 只是作为一个“外挂”插件。
  便于切换： 同一个基座模型可以加载不同的 LoRA 权重来适应不同任务（如一个负责写代码，一个负责写小说，一个负责法律知识），无需重新加载大模型。
  成本低：不仅可以在训练时显著降低显存占用和训练时间，还保持与全量微调相当的效果。

专家模型

  上面介绍了PEFT微调的一种技术LoRA微调原理，本节主要介绍LoRA技术实际应用。通过LoRA微调后会生成LoRA适配器此适配器的大小与微调时训练的参数规模相关通常几十MB到几百MB不等，LoRA适配器不严谨的可称为专家模型。  LoRA适配器通常有两种使用方式：

1. 静态合并：LoRA适配器合并到基座模型，基座模型参数改变，不可再分离。
2. 动态加载：LoRA适配器单独存储，基座模型参数不变，使用时加载。

  LoRA 动态加载不只是技术选择，还是应对模型快速迭代的最佳经济策略。  LoRA可解决领域细分的颗粒度问题。不单是不同领域行业知识需要分开微调，单一行业(如法律)内部也存在民事、刑事、合同法、涉外法等等差异巨大的子领域，直接哪这些行业知识去微调去全参数微调一个模型或许也能微调好，但工程难度不小，消耗的资源也不少。

  打破“基座更新即重练”的成本诅咒，按目前行业的发展每半年一代新模型发布速度，每当基座模型(Base Model)更新又要投入大量的资源去全参数微调更新专家模型，如果使用的是LoRA专家模型，只需基于新基座快速迁移与微调轻量级的适配器（Adapter）。LoRA 将模型的维护升级成本从“指数级”降低到了“线性级”。

工程实践

  多LoRA架构的核心在于基座共享，插件热拔插。在显存中，我们只保留一份巨大的基座模型权重，而针对不同领域的 LoRA 模块（仅占极小显存）则根据用户请求实时加载或切换。还可以使用基座模型提供通用的知识服务。

  整个多LoRA架构系统像一个现代化的综合医院：

• 应用层（挂号处）： 接收病人（请求）。
• 路由层（分诊台）： 决定病人去哪个科室（选择哪个 LoRA），或者只是去药房买点感冒药（基座直通）。
• 显存管理（调度中心）： 确保医生（LoRA 参数）已经就位。
• 推理引擎（诊疗室）： 医生（LoRA）配合基础医疗设施（基座模型）进行诊断。

注意上图中LoRA适配器是旁路（Sidecar）权重，它是挂在基座模型上的，数据流直接进入“基座+LoRA”的组合体。LoRA 和基座是并联计算（或者说数学上的权重相加），而不是串联处理。

  查看当前大模型推理服务存在多少模型，下面可以看到存在一个基座模型Qwen3，三个LoRA专家模型。

 http://192.168.1.1:13000/v1/models {    "object": "list",    "data": [        {"id": "../../models/Qwen3-4B","object": "model","created": 1765038561,"owned_by": "xxx","root": "../../models/Qwen3-4B","parent": null,"max_model_len": 40960},        {"id": "law_lora","object": "model","created": 1765038561,"owned_by": "xxx","root": "../../lora/LoRA-and-MoE/law/law-lora-model-4B-1206","parent": "../../models/Qwen3-4B","max_model_len": null},        {"id": "starTrek_lora","object": "model","created": 1765038561,"owned_by": "xxx","root": "../../models/Qwen3Guard-StarTrek-Classification-4B","parent": "../../models/Qwen3-4B","max_model_len": null}        {"id": "hn_lora","object": "model","created": 1765038561,"owned_by": "xxx","root": "../../models/hn-lora-Qwen3-4B","parent": "../../models/Qwen3-4B","max_model_len": null}    ]}

在使用时只需要选择某个LoRA模型或不指定LoRA专家模型，直接使用基座模型；

response = client.chat.completions.create(    model="Qwen3-4B",    messages=[        {"role": "user", "content": inference_prompt},    ],    temperature=0,    max_tokens=1024,    #可不使用lora    extra_body={        "lora_path": "law_lora",      })

  现在业内多LoRA部署有多种成熟的方案，多LoRA专家模型部署推理主流方案如下：

• vLLM: 目前最流行的推理框架之一，原生支持 Multi-LoRA serving。它可以在处理请求时动态地为不同请求应用不同的 LoRA 适配器，而无需重新加载基座模型。
• Hugging Face TGI (Text Generation Inference): 提供了对多个 LoRA 适配器的支持。
• LoRAX (LoRA Exchange): 专门为服务数千个 LoRA 模型而设计的推理服务器，优化了 LoRA 的换入换出机制。
• SGLang：原生支持Multi-LoRA serving，请求时动态的为不同应用路由到不同的LoRA适配器。
• LoRAX：号称一个GPU上能部署上百LoRA适配器模型。

未来

未来也未必是未来。
  目前除了已经成熟的基于LoRA外挂适配器权重的多专家模型方案外，还有一中学术界还在探索中没那么成熟的MoE-LoRA方案，混合专家融合的LoRA方案。LoRA微调可以理解为训练了N个独立的LoRA(针对不同数据集)，创造了N个专家。

1. LoRA A：只用代码数据训练（Code Expert）。
2. LoRA B：只用数学数据训练（Math Expert）。
3. LoRA C：只用小说数据训练 (Creative Writing Expert)。

  MoE-LoRA可以理解为把这 N 个 LoRA 塞进一个模型里并使用门控控制。  目前独立LoRA存在一个问题就是需要提前知道任务级或会话级类型。一旦你选定了 LoRA（代码专家），在接下来的生成中，它就无法处理其他领域的知识，不适合复合型任务。

  而MoE-LoRA则不存在上面问题，模型内部有一个 门控(Gating)，针对每一个 Token（词元） 进行决策，可以瞬间切换LoRA专家，一会使用代码专家 LoRA一会使用文学专家LoRA。模型是一个既懂着又懂那的缝合怪天才。一个句子的生成过程中动态调用不同的能力，这是独立 LoRA 绝对做不到的。有一种专家间的软协同能力。

不服？ 来跑个分。

跑分的专业术语是评测、评估。大模型评估对通用大模型很重要，对垂直模型一样很重要，一个垂直模型在其垂直领域内的能力要比通用模型好才有其存在的意义。如一个7B微调的法律模型如其在法律领域能力还比不上7B的通用模型就没有存在的意义。

评估微调模型的能力同样需要进行跑分从一个相对客观的角度评估模型是否达到预先设定的目标。

文章下面先简单介绍大模型评估的一些背景知识，后通过评估Qwen3-0.6B、1.7B、4B、8B以及LawLLM-7B，五个模型中三个为通用模型，一个为基于Qwen2.5-7B经过微调的垂直领域模型。看看不同规模比较新的通用模型能否战胜一个比较老的垂直法律模型。

大模型评估

在大模型领域也比较流行跑分，每次各家厂商发布新模型同时也会公布其在某某榜单的分数，在N个领域基准评估排名是多少。目前行业公认基准评估评测集如下：  MMLU Pro通用知识推理多学科专业级理解（数学、物理、历史等）MMLU升级版，题目更复杂，选项从4个增至10个  GPQA Diamond高级科学推理物理/化学/生物等研究生级问题"Google-proof"设计，防止搜索直接得答案，极难  SWE-bench Verified软件工程解决真实GitHub代码问题人工验证版本，评估工程实践能力而非简单代码补全  MATH-500数学推理500道高难度数学竞赛题需复杂推导和计算，测试数学思维  AIME 2024数学竞赛美国数学邀请赛真题顶级高中数学竞赛，难度极高  LiveCodeBench 代码生成动态更新的算法题与编程任务防数据污染，测试实时编程与算法解决能力

这六个领域是每个头部大模型厂商新模型必跑的分。还有一些其他数据集如MT-Bench、P2L等。还有针对Agent的评估如：AgentBench。

模型竞技场

比较出名的平台有：LMArena、CompassArena等

相对于学术领域基准评测比较容易被针对性“优化”，还有一个业内比较权威的模型评测榜单LMArena。模型竞技场排名与针对领域基准数据集的跑分模式完全不一样，基准数据集是公开的如果模型在训练阶段加入了部分数据就可能会影响到他的跑分结果。

LMArena这类模型竞技场核心是依靠用于进行打分，用于规模越大活跃度越高其越权威。也是局限性就是收到用户群体偏好的影响。

LMArena评测机制：1、双盲对战： 用户提问，平台随机展示两个匿名模型的回答，用户投票选择更优答案，投票结束后才揭示模型身份2、Bradley-Terry统计模型： 将投票率转换为实力得分，控制样本量和匹配次数的偏差3、动态更新： 根据用户投票持续更新

法律领域

目前针对法律领域的模型评估数据集MMLU/MMLU Pro虽然有覆盖法律学科，但这跟国内的法律还不一样。CMMLU、C-Eval 倒是覆盖了国内法律领域知识，但这类综合性的评估数据集覆盖了几十个学科法律只是其小部分数据集，对法律垂直领域内的知识覆盖面不够。目前国内法律领域的专门评测数据集有：LawBench、LAiW，下面将使用LawBench数据集用于模型的评估。

LawBench数据集包括20种不同任务，覆盖三个认知水平：1、法律知识记忆： 包括法律概念、术语、法条和事实。2、法律知识理解： 法律文本中的实体、事件和关系，从而理解法律文本的意义和内涵。3、法律知识应用： 能否正确利用其法律知识、对其进行推理从而解决下游应用中的现实法律任务。

LawBench每类任务包括500个问题，试题类型包括：生成、单选、多选、抽取、回归。五种不同类型的问题。数据集总规模为1W。提供了Zero-Shot(零样本)、One-Shot(单样本)两种类型的数据集。评估的分数计算通常有两种模式。基于规则的评估（Rule-based）：使用确定性规则或脚本自动判断模型输出是否正确。基于LLM Judge的评估（LLM-as-Judge）：使用另一个大语言模型作为"裁判"来评估答案质量。

下面分别使用Qwen3-0.6B、1.7B、4B、8B以及LawLLM-7B评估本数据集，本次使用的是基于规则的评估。LawLLM-7B为基于Qwen2.5微调的法律垂直领域模型。
参数统一为top_k=20,temperature=0.6,top_p=0.95,do_sample=True

评测结果分析

本数据集在19项任务中，13项任务（68%）非思考模式表现更优 ，思考模式仅在6项任务（32%）中效果更好。

思考模式增益公式：Δ = 8B得分 - 8B-no_think得分思考模式真正有效的任务（Δ > 2）| 任务 | Δ值 | 任务类型 | 成功原因 ||------|-----|----------|----------|| 刑事损害赔偿计算 | +25.2 | 数值推理 | 复杂多步计算需逻辑链支撑 || 触发词提取 | +12.7 | 事件理解 | 深度语义理解提升事件边界识别 || 基于事实的法条预测 | +4.5 | 知识推理 | 事实-法条映射需中间推理步骤 || 事件检测 | +4.4 | 内容理解 | 全局上下文分析减少误检 |

非思考模式碾压性优势的任务（Δ < -5）

规模效应真实表现

强正规模效应任务（0.6B→8B提升>50%）

• 基于事实的法条预测：+383%（16.24→78.46）——事实-法律映射能力随参数量爆炸式增长
• 罪名预测：+95%（28.00→54.50）——罪名认定依赖复杂特征学习
• 知识问答：+75%（29.00→50.80）——知识密度与参数规模强相关
• 刑事损害赔偿计算：+53%（61.40→94.00）——数学能力与规模正相关

规模效应饱和任务（4B→8B提升<5%）

• 事件检测：+0.1%（73.36→73.29）——4B已达能力上限
• 阅读理解：+5.5%（71.71→75.65）——边际效益递减
• 基于场景的法条预测：+0.4%（30.82→30.93）——全系列得分停滞，可能是评估分数计算存在缺陷

异常规下降任务

• 刑期预测（有法条）：0.6B→8B持续下降（80.85→78.96），可能是模型复杂化后"过度解读"法条，还可能是评估分数计算存在缺陷

与专业模型（LawLLM-7B）对比

Qwen3-8B反超标杆的任务

1. 刑事损害赔偿计算：94.0 vs 57.2（+64%）——通用模型的数学优势
2. 争议焦点识别：8B-no_think 43.4 vs 27.2（+60%）——非思考模式+规模效应碾压
3. 命名实体识别：8B-no_think 85.2 vs 63.1（+35%）——通用架构的抽取能力被低估
4. 刑期预测：no_think模式全面领先（86.6/86.5 vs 80.5/79.8）

LawLLM-7B护城河任务

1. 案例分析：74.8 vs 37.8（+98%）——法律推理专业化不可替代
2. 知识问答：79.0 vs 50.8（+56%）——法律知识密度差距
3. 事件检测：89.8 vs 73.3（+23%）——专业领域特征工程优势
4. 法条背诵：26.2 vs 19.3（+36%）——专业训练集的记忆优势

现象

现象1：思考模式的"双刃剑"本质

• 适合：触发词提取（+12.7）需深度理解；刑事赔偿计算（+25.2）需多步推理
• 不适合：命名实体识别（-14.9）需快速匹配；案例分析（-16.4）需精准生成

现象2：规模与模式的互斥性

• 小模型（0.6B）：思考模式无害（无法深度思考）
• 大模型（8B）：思考模式分化——推理任务增益 vs 抽取任务受损

现象3：专业模型的"偏科"现象

• LawLLM-7B在案例分析、知识问答领先
• 但在刑事赔偿计算（57.2 vs 94.0）和触发词提取（16.85 vs 58.78）严重弱于通用模型

场景-模型配置决策树

任务是否需要思考模式？├─ 是 → 启用思考模式│   ├─ 数值计算 → 8B-think（刑事赔偿）│   └─ 法条映射 → 8B-think（基于事实的法条预测）└─ 否 → 禁用思考模式    ├─ 信息抽取 → 8B-no_think（NER、论点挖掘）    ├─ 精确判断 → 8B-no_think（争议焦点、刑期预测）    └─ 内容生成 → 8B-no_think（案例分析、咨询）

专业模型 vs 通用模型取舍

• 优先LawLLM-7B：法律文书生成、深度法律咨询、知识密集型问答
• 优先Qwen3-8B-no_think：实体抽取、数值计算、快速焦点判断

总结

专业模型有一定的护城河，在专业领域还保存着优势，但基座模型的更新就可能让专业模型丧失一半优势，微调也是需要持续更新迭代的。模型评估也是一个复杂的工程，也可能新模型又在评测数据集上训练了一遍做了“优化”，可能要更加客观评估大模型还是需要专门定制的评估数据集。

智能体结构

   本文所述极简深度检索智能体包含五个Agent，生成查询Agent、网络搜索Agent、反思Agent、报告生成Agent。

   * 生成查询Agent：根据用户输入的内容提交给大模型，对该原始问题进行查询生成，生成一个或多个多样化的查询。使得在下一步的Agent从能够搜索到更多有用的信息。此Agent生成的是一个或多个查询列表：
   {"query_list":{"query":["子查询"],"rationale":"简要解释这些查询与研究主题的相关性"}}
   此Agent的工作：
   1、发起模型调用生成子查询
   2、根据子查询列表发起N次[网络检索Agent]请求(并发)

   * 网络检索Agent：根据[生成查询Agent]所生成的查询列表调用网络工具进行检索，此处的网络检索工具可以是Tavily、博查或搜索引擎或自己开发的工具等。将网络检索到的网络资料提交到大模型，生成关于在 生成查询Agent 阶段所提供问题的研究摘要。
   此Agent的工作：
   1、根据[生成查询Agent]生成的查询列表发起一次或多次网络检索。
   2、针对该[查询列表]生成一份或多份研究摘要。

   * 反思Agent：Agent收到[网络检索Agent]所生成的研究摘要是由N个[网络检索Agent]生成的，并分析其所生成的摘要与用户的[原始问题]是否存在知识缺口或还需要深入探索的领域来决定是否已经满足用户[原始问题]的回答，或还需要返回【网络检索Agent】进行进一步的网络检索。
   此Agent生成：{   "is_sufficient": 是否充分,   "knowledge_gap": 描述缺失或需澄清的信息,   "follow_up_queries": 针对缺口提出的具体问题,   "research_loop_count": 当前循环次数,   "number_of_ran_queries": 子查询个数,   }   此Agent的工作：
   1、判断[网络检索Agent]生成的摘要是否存在知识缺口。
   2、是则返回[网络检索Agent]，否则进入[报告生成Agent]。

   * 报告生成Agent：根据用户[原始问题]以及[网络检索Agent]阶段所生成的摘要，生成最终的研究报告/文章。

智能体实现

   下面是代码为极简深度研究的Agent构建关键代码，创建generate_query、web_research、reflection、finalize_answer节点，以及两条边continue_to_web_research、evaluate_research，用于控制数据的流转。下面是LangGraph的实现代码。

def _build_graph(self):        # 创建 Agent Graph        builder = StateGraph(OverallState, config_schema=Configuration)        # 定义将在循环中使用的节点        builder.add_node("generate_query", generate_query)        builder.add_node("web_research", web_research,        retry=RetryPolicy(max_attempts=3))        builder.add_node("reflection", reflection)        builder.add_node("finalize_answer", finalize_answer)        # 将 generate_query 设置为入口点 即该节点为首个被调用的节点        builder.add_edge(START, "generate_query")        # 添加条件边，在并行分支中继续执行搜索查询        builder.add_conditional_edges(            "generate_query", self._continue_to_web_research, ["web_research"]        )        # 连接网络搜索节点到反思节点        builder.add_edge("web_research", "reflection")        # 评估研究结果        builder.add_conditional_edges(            "reflection", self._evaluate_research, ["web_research", "finalize_answer"]        )        # 最终确定答案        builder.add_edge("finalize_answer", END)        return builder.compile(name="research-agent")  

   continue_to_web_research：[生成查询]与[网络搜索]之间的边，根据查询[生成查询]生成子查询并发起N个[网络检索Agent]请求。
   evaluate_research：[反思Agent]与[网络检索Agent]和[报告生成Agent]之间的边，根据研究循环次数以及子问题的摘要是否充分决定跳转到哪个节点。

   网络检索：这里现在使用的是 Tavily，在Tavily返回数据后再次发起请求获取详细的页面信息，目前看数据质量也不是很好，但也比使用无头浏览器包装一层的的搜索引擎数据质量好不少。

前端

  目前页面只弄了发起Agent的SSE请求，在Agent运行时各Agent节点状态变动时的页面展示以及最后结果输出的展示。

扩展

   目前智能根据网络搜索的结果进行研究报告生成，生成内容的质量取决于搜索结果的质量，可扩展方向包括加入上传文件的检索、网络搜索内容过滤等。

   这里也只是算是一个全栈的智能体示例，虽然这里用的是LangGraph，但个人并不喜欢LangGraph，框架封装过于复杂。目前各类Agent框架很多用哪个全凭个人喜好，或这不用框架自己实现Agent的封装。
   GitHub代码此代码仓库包含了前后端代码。https://github.com/linxin26/Open-DeepResearch
文章首发地址：https://mp.weixin.qq.com/s/Dmx3XBVal7hgiJ7_BP7-5g

智能体描述

   上传课程材料填写课程级别(初级、中级、高级)与课程名称后智能体将能够根据课程材料文本数据自动生成完整的可交互式的网络课程，每个课程都包含多个章节，章节详情可做到根据章节具体内容而生成可视化的交互学习页面。如学习页面包含可交互的组件以及图表。每个章节还会存在多种类型(选择题、判断题、填空题等）的练习题。
   智能体工作主要流程：课程材料>课程信息>课程章节生成>章节详情生成>章节习题生成，具体业务流程如下图所示。

Agent结构

课程信息Agent

   以课程材料、填写的课程级别等信息为上下文生成生成课程简要描述文本以及课程基本信息。

课程章节Agent

   以课程材料为上下文生成课程章节，课程章节包括：章节标题、章节描述、学习时长等。

章节详情Agent

   以课程材料、章节描述信息为上下文生成章节详情，章节内容会根据使用的内容使用文本、可视化图表、交互组件等展示章节内容。

章节代码检查Agent

   检查上个Agent所生成的章节详情页面代码是否包含基本的运行时错误等。

章节习题Agent

   以章节内容为上下文，生成章节习题，习题包括：题干、问题选项、正确答案、习题解析。

章节详情Agent实现

   在这个网课智能体中，所具有看点的应该是本Agent的实现，网课的可交互页面的学习体验也依赖于此Agent。这个环节也是最有可能出错的。智能体的输入为：课程材料、章节详情、React组件。输出为根据章节内容所适配的可交互React代码。下面代码为输出的React可视化示例：

() => {const data = [  { name: '训练集', value: 70 },  { name: '验证集', value: 15 },  { name: '测试集', value: 15 }];return (  <div>    <Recharts.PieChart width={400} height={300}>      <Recharts.Pie        data={data}        cx="50%"        cy="50%"        labelLine={true}        label={({ name, percent }) => `${name}: ${(percent * 100).toFixed(0)}%`}        outerRadius={80}        fill="#8884d8"        dataKey="value"      >        {data.map((entry, index) => (          <Recharts.Cell key={`cell-${index}`} fill={['#4e79a7', '#f28e2c', '#e15759'][index % 3]} />        ))}      </Recharts.Pie>      <Recharts.Tooltip />    </Recharts.PieChart>    <p className="text-center mt-4">测试集、训练集、验证集占整个数据集的比例</p>  </div>);}

提示词如下：

你是负责用 React + JSX 创建引人入胜的可视化讲解的智能体。  你的工作流程如下：1. 你将从规划智能体那里收到一个主题及要点列表2. 你需要为用户创建一个吸引人的解释/演示## Output Format<start of your output>() => {     const [counter,setCounter]=React.useState(0); // by default your code has access to the React object     const increase=()=>{       setCounter(counter+1);     };     return (<>       <button onClick={increase}>+</button>       <span>{'counter : '+ counter}</span>       </>);}<end of your output>重要注意事项请仅输出我指定的组件部分，尤其不要包含：- 代码前后的 ```jsx 标签- <start of your output><end of your output>- 任何关于代码的解释或包围代码的文字你的代码会被立即解析并展示给用户，因此务必避免语法错误!!----风格指南:- 你的首要任务是通过可视化讲解和交互性防止用户感到无聊。- 在此过程中，尽量把概念讲得越清晰越好。- 使用具体示例。- 不要包含练习题，这tester agent的任务。- 确保组件占满其父容器的 100%。- 不要创建幻灯片，而是做成一整页可连续滚动的页面。## 可用库与插件你将可以访问若干库和插件，下面将为你提供它们的文档:

效果展示

扩展

   上面所描述的智能体流程比较简单，还可以进一步完善如引入RAG、试卷、考试等功能，使其达到一个较高的可用度。
在加入RAG的支持后，可通过向量检索实现由用户自定义只生成用户所关心的课程材料中某个主题的网络课程。在完成课程生成后和配套生成整个课程的试卷，试卷可以是一套或者N套。扩充章节内容，目前章节没有细分小节或内容不够长，通常大章节都有会几个小知识点。

   变革才刚刚开始，目前由于模型幻觉、成本等因素智能体现在阶段完全取代网课系统也不现实，加上目前视频生成也不是很成熟，但相信用不了多久的未来无论是图文网课或是视频网课量大量都是由AI Agent自动生成。

##架构设计

     各个行业的合同模版，主要有政府部门、行业组织、公司内部指定的合同模版。
   风险条款库： 覆盖合同常见的风险条款。
   行业法规： 政府部门、行业组织制定的相关法律法规。
   公司政策： 公司根据内部自己指定的合同要求、产品要求政策。

   合同初审： 根据标准模版对合同文本进行初审，输出合同初审报告。
   关键要素审核： 合同双方、标的、金额、有效期、管辖权、违约责任等，输出关键要素审核报告。
   风险评估： 列出各个条款的风险等级(高、中、低)，输出风险评估报告。
   合规性检查： 对合同进行行业法规与公司政策的合规检查，输出合规性检查报告。
   合同修改建议： 最终的合同审核报告。

Agent设计

  本文所述合同审查Agent整体架构如上图所示。
   合同审核Agent： 为主Agent本身并不负责任何的合同审核任务，只负责将合同文本传递给其他Agent。
   五个子Agent： 负责协同完成合同文本的审核任务，各子Agent职责分明，只负责完成自己所规定的任务。
   最终审核报告Agent： 负责整理其他四个子Agent所完成的审核任务，输出最终的合同文本审核报告；

  对于完善的Agent应用还需要有合同审查记录、提供合同调整能力、输出调整后合规合同等功能。
  本文所述Agent交互比较简单，从较好的用户体验角度出发此Agent的Web UI可设计成实时人机交互的。如实时对文本编辑器的合同文本提交给后端Agent进行合同审核，Agent审核返回合同审核结果，可实时对编辑器内的合同文本体现出问题条款、风险等级等。要实现这个效果需要Agent具有较高的实时性输出。
  本文最后提供了农产品采购的问题合同文本，使用本文所开发的合同审查Agent所输出的合同审核报告，仅供参考。

1、问题合同

 合同编号：2025-NCP-001签订地点：微信语音签订时间：2025年8月10日 23:47甲方（供货方）：王老三（微信昵称“田野老王”）身份证号：略地址：某县某镇某村“大概村口第三家”联系电话：微信同号乙方（采购方）：××电子商务有限公司（未加盖公章）法定代表人：李总（签字处空白）地址：以发货地址为准联系电话：客服微信号“XX-Store”鉴于甲方自称拥有大量农副产品，乙方自称需要采购，双方本着“差不多就行”的精神，订立如下合同，并确认均已阅读且看不懂也不问。第一条 标的、数量、价格1.1 标的名称：新鲜农产品（具体品种以发货当天老王地里有的为准）。1.2 数量：大约1000斤左右，可多可少，最终按甲方地磅称重为准（地磅年检过期）。1.3 价格：随行就市，甲方每天在微信群里报一次价，乙方当日未回复“不要”即视为同意。1.4 价格已包含“所有费用”，但如遇油价上涨、天气不好、老王心情差，甲方可临时加5%–20%“辛苦费”。第二条 质量标准2.1 质量等级：目测差不多，新鲜就行，无官方检测报告。2.2 农药残留：甲方承诺“基本不打药”，但如检测超标，双方同意以“农村都这样”为免责理由。2.3 外观缺陷：虫眼、裂果、泥土属正常，乙方不得以此拒收或索赔。第三条 包装方式3.1 包装材料：二手化肥袋、废纸箱或甲方家里现有的编织袋，如需新箱，费用由乙方额外承担。3.2 包装标识：无生产日期、无保质期、无溯源码，仅在外袋上用记号笔写“农产品”三字。第四条 交货时间、地点、方式4.1 交货时间：2025年8月，具体哪天看天气和甲方时间安排。4.2 交货地点：甲方地头；如乙方要求发快递，则默认到付且甲方不保证当天发出。4.3 运输方式：甲方联系“顺路货车”，司机电话保密；运输损耗5%以内属正常，乙方不得异议。4.4 风险转移：货物一旦离开甲方地磅，无论是否装车完毕，风险即转移给乙方。第五条 验收5.1 乙方应在收到货物后5分钟内完成验收，逾期视为合格。5.2 如乙方发现货物腐烂、短斤缺两，必须在收货现场拍照并立即得到司机书面签字确认，否则视为乙方保管不当。5.3 甲方不接受任何退货；乙方坚持退货的，须自行承担来回运费及30%“折腾费”。第六条 结算方式6.1 乙方预付30%“诚意金”到甲方私人微信零钱；剩余货款在甲方发货后48小时内付清，逾期每日加收10%滞纳金。6.2 甲方未发货前可随时涨价或取消订单，诚意金原路退回但不计利息；乙方取消订单则诚意金不予退还。6.3 所有款项仅支持微信红包或现金，不提供发票；如乙方强行索要发票，须自行承担13%税点。第七条 不可抗力7.1 不可抗力包括但不限于：下雨、太阳太大、路不通、老王感冒、村里停电、手机没信号。7.2 发生不可抗力，甲方有权无限期推迟交货且无需通知；乙方不得以此为由解除合同或索赔。第八条 违约责任8.1 任何一方违约，只需在微信群里发一句“不好意思”即可免责。8.2 如乙方拖欠货款，甲方可直接在乙方直播间刷屏“老赖公司”；如甲方未交货，乙方可发一条差评，但不得要求赔偿。第九条 争议解决9.1 合同履行过程中如发生争议，双方同意先找“村里德高望重的王大爷”调解；调解不成的，任一方可向“有关部门”反映，具体部门名称暂不确定。9.2 诉讼管辖：如走法律程序，双方一致同意由甲方所在地镇法庭管辖，且适用法律为“当地惯例”。第十条 其他约定10.1 本合同一式零份，仅以微信聊天记录截图为准，任何打印版本无效。10.2 合同未尽事宜，由甲方单方口头补充，补充内容与本合同具有同等效力。10.3 甲方拥有最终解释权；如条款与国家法律冲突，以甲方理解为准。

2、合同审核报告

 一、合同基本信息项目内容合同编号2025-NCP-001合同名称农副产品买卖合同（非正式）签署日期2025年8月10日 23:47签署地点微信语音甲方（供货方）王老三（微信昵称“田野老王”）乙方（采购方）××电子商务有限公司二、合同主要内容概述本合同为农副产品买卖合同，主要内容包括：标的物：新鲜农产品，品种、数量、价格均不明确；质量标准：以“目测差不多”为准，无检测报告；包装方式：使用二手化肥袋等非标准包装；交货安排：交货时间、地点不确定，风险转移点不合理；验收条款：验收时间过短，举证责任分配不公平；付款方式：微信红包支付，预付30%诚意金，滞纳金过高；不可抗力：范围过于宽泛，包括天气、个人身体状况等；违约责任：仅需在微信群道歉即可免责；争议解决：由村里调解或“有关部门”处理，缺乏法律效力；合同形式：无书面签署页，仅以微信聊天记录为准。三、合同中存在的主要问题和风险点1. 合同主体信息不完整问题描述：甲方身份信息不全，乙方未加盖公章，法律效力存疑。风险评估等级：高合规性分析：根据《电子商务法》第10条，平台需核验经营者身份，但本合同未体现甲方合法资质。乙方未加盖公章，违反公司内部签署流程，不符合公司政策中关于合同签署的规范性要求。合规检查结果：不合规2. 标的物约定不明确问题描述：标的品种、数量、价格机制模糊，缺乏约束。风险评估等级：高合规性分析：《农产品质量安全法》第39条规定，农产品上市须附承诺达标合格证，但本合同未体现。公司政策要求透明定价公示，禁止“临时口头加价”，但合同中允许甲方随时涨价。合规检查结果：不合规3. 质量标准缺失问题描述：无检测报告，免责条款违法。风险评估等级：高合规性分析：《农产品质量安全法》第39条要求农产品上市须附承诺达标合格证，合同中未体现。公司政策要求100%批次自检，但合同中未提及检测要求。免责条款“农村都这样”违反《食品安全法》第4条，企业应确保食品安全。合规检查结果：不合规4. 交货安排不合理问题描述：交货时间地点不确定，风险转移点不合理。风险评估等级：中合规性分析：《民法典》第604条规定，标的物毁损、灭失的风险在交付前由出卖人承担，合同中风险转移点设置不合理。公司政策要求损耗先行赔付，但合同中未体现。合规检查结果：不合规5. 验收条款不合理问题描述：验收时间过短，举证责任不公平。风险评估等级：中合规性分析：《民法典》第621条规定，买受人应在合理期限内检验标的物，合同中5分钟验收时间不合理。公司政策要求48小时内完成赔付，但合同中未体现。合规检查结果：不合规6. 付款条款存在法律风险问题描述：诚意金机制不公平，滞纳金过高。风险评估等级：高合规性分析：《民法典》第585条规定，违约金不得超过实际损失的30%，合同中滞纳金每日10%过高。公司政策要求透明定价公示，但合同中未体现。合规检查结果：不合规7. 争议解决条款无效问题描述：争议解决方式无效，管辖条款不明确。风险评估等级：高合规性分析：《民法典》第470条规定，合同应明确争议解决方式，合同中“村里调解”不具备法律效力。公司政策要求适用法律为中华人民共和国法律，但合同中未明确。合规检查结果：不合规8. 合同形式不合规问题描述：合同形式不规范，甲方拥有最终解释权。风险评估等级：中合规性分析：《民法典》第466条规定，合同应采用书面形式，合同中“一式零份”不符合要求。公司政策要求“就高不就低”原则，但合同中甲方拥有最终解释权违反公平原则。合规检查结果：不合规四、审核意见和建议1. 补充并规范合同主体信息建议：要求甲方提供完整身份证号、详细地址及有效联系方式；乙方必须加盖公章，法定代表人签字确认；双方应提供银行账户信息，避免使用微信红包等非正式支付方式。2. 明确合同标的物信息建议：列明具体农产品品种、规格、数量；明确价格调整机制，禁止无理由涨价；使用经年检合格的地磅，或引入第三方计量机构。3. 完善质量标准条款建议：建立明确的质量等级标准；增加农药残留检测要求，提供检测报告；删除“农村都这样”等免责条款。4. 优化交货与运输条款建议：明确交货时间、地点及运输方式；合理分配运输风险，明确损耗责任；禁止将天气、个人身体状况列为不可抗力。5. 修订验收与退货条款建议：延长验收时间至合理期限（如24小时）；允许乙方在合理期限内提出异议；退货条件应公平合理，避免单方加重乙方责任。6. 规范付款与发票条款建议：提供正规发票，删除“强行索要发票需补税”条款；调整滞纳金比例至合理范围（如每日0.05%）；明确预付款退还机制，避免甲方单方取消订单。7. 完善争议解决条款建议：选择有效的仲裁机构或法院管辖；删除“村里调解”等无效条款；明确适用法律为中华人民共和国法律。8. 规范合同形式与签署建议：采用书面合同形式，一式两份，双方各执一份；删除“甲方拥有最终解释权”条款；所有补充条款需以书面形式确认。审核人：合同审核专员审核日期：2025年8月11日

1、只提取PDF中的位图进行OCR

  此方案通过解析PDF提取其内嵌的图片，只对提取的内嵌图片进行OCR，但可能会由于PDF嵌入的图片质量效果不佳或分辨率较低的问题，即使在原PDF中很清晰的图片提取出来后也是模糊不清，导致OCR准确率大大降低。特别是对于存在数学公式的PDF，提取位图进行OCR准确率极低。对图片进行二次处理如 灰度、放大、二值化、去噪后 OCR效果也不一定很理想。

  上图为PDF中的数学公式，图片为PNG格式，存在一个Alpha 通道，尽管已经分离该透明通道并填充白色背景，但是OCR识别的效果依然不佳，再进行灰度、放大、二值化、去噪后，还是效果不佳。
  提取文本、提取图片进行OCR的结果、提取文本、在提取图片OCR，将文本与OCR的结果进行按原顺序作为该页的文本内容。

[{'save_path': '','data': [{'text': 'p=$26500:(0.905)','confidence': 0.8825955390930176,'text_box_position': [[3, 4], [170, 2], [171, 14], [3, 16]]},{'text': '1.1','confidence': 0.9956590533256531,'text_box_position': [[285, 3], [313, 3], [313, 15], [285, 15]]}]}]

2、整个PDF全页都进行渲染

  将PDF中每一页都进行渲染为高清位图，再对每一页进行OCR。但这将导致计算量飙升，原本800页中只有10%存在图片即需要OCR的只有80页，但这种简单粗暴的方式导致OCR计算量直接翻十倍。极端情况下可能及只有一两页文档存在图片，但此方案还是会将整个文档的每页都提交OCR，导致PDF解析速度严重缓慢，图片DPI为200-300。

3、只对PDF中的“含图页”进行渲染

  在本方案中通过快速扫描PDF定位PDF中哪些页数存在图片，对这些存在图片的当前页进行渲染然后进行OCR。这样将尽可能得平衡OCR的准确率与效率，极大的降低OCR次数，释放更多性能。

  上图为对存在图片的该页渲染后得到的图片，对该图片直接进行OCR得到的结果比使用方案一对位图处理后OCR的结果还要好：

 {'text': 'p = $26 500 (0.905)m', 'confidence': 0.9309449195861816,'text_box_position': [[738, 2136], [1272, 2121], [1275, 2200], [740, 2215]]},    {'text': '(1.1)', 'confidence': 0.9146772623062134, 'text_box_position': [[1593, 2138], [1706, 2138], [1706, 2204], [1593, 2204]]}

  在此方案中由于只整页进行OCR可以直接把OCR结果作为提取到的该页文本内容。而按方案一的方式需要对提取文本、提取图片进行OCR的结果、提取文本、在提取图片OCR，将文本与OCR的结果进行按原顺序作为该页的文本内容。
  本方案的图片肯定会比方案一大很多，但由于OCR的次数是固定一次的，方案一图片可能会小一点但其图片数量比较多其整体性能也不一定会很高。

import fitz  # PyMuPDF                def get_result(self):    """获取pdf文件提取结果    """    t0 = time.perf_counter()    self.extract_text()    self.extract_images()    for inx,item in enumerate(self.text_list):        if str(item).startswith('img_'):            if self.ocr_result:                ocr= self.ocr_result.pop(0)                self.text_list[inx]=ocr                logger.info(f"ocr:{self.ocr_result},images:{len(self.images_list)},txt:{len(self.text_list)}")            elapsed = time.perf_counter() - t0    logger.success(f"全部提取完成，耗时 {elapsed:.2f} 秒")

性能对比

  这里选择了一个使用了**《程序员的数学.pdf》**进行解析提取文档中的文本信息以对比三种方案的性能，整个文档883页这里只解析200页内容用于性能对比。这里渲染出进行OCR的图片大小从500KB到2MB不等。

  由于本文所使用的PDF为数学书籍包含比较多的数学公式、图表等因此包含了大量图片所以方案三和方案二的区别不是特别明显，但在图片很少的场景下两者就会有巨大的差别。存在极端情况PDF是扫描件，全部是图片方案三 退化为方案二，但整体看来方案三性能还是会好过方案二。

一、 架构设计：解构智能体应用

  本文智能体是一个垂直类智能体。系统的核心并非依赖于一个无所不能的“超级智能体”，而是采用了一种“分而治之”的多智能体协作架构。通过此设计模式尽可能智能体的可靠性、稳定性，并为未来的扩展和维护奠定了坚实基础。

1. 核心理念：三层分离式工作流

  整个系统可以被清晰地划分为三个逻辑层次，构成了一个完整的“采集-处理-整合”智能体流水线：

• 采集Agent (Collection Agent)：此层由一个 ParallelAgent 容器和多个并行的“采集智能体”（如 ithome_agent, reddit_agent 等）组成。每个采集智能体专注于一个独立的数据源。

  • 高并发性：所有数据源的获取任务同时启动，极大地缩短了总耗时。
  • 故障隔离：单个数据源的失败（如网站无法访问）不会影响其他智能体的正常工作，增强了系统的鲁棒性。

• 处理Agent (Processing Agent)：这一层实际上内嵌于每个采集智能体之中。在获取原始数据后，智能体利用其内置的 LLM 和指令，立即对数据进行独立的预处理，包括内容摘要、语言翻译、质量筛选等。

  • 分布式处理：将处理压力分散到各个独立的智能体中，避免了中心化的处理瓶颈。
  • 专业化分工：每个智能体可以根据其数据源的特性，应用不同的处理规则（例如，Reddit 的内容需要翻译，而中文内容则不需要），实现了精细化控制。

• 整合Agent (Aggregation Agent)：此层由一个 SequentialAgent 容器中的“整合智能体”（MergerAgent）负责。它作为流水线智能体的最后一环，等待所有采集/处理任务完成后，接收所有中间结果，并执行最终的分类、格式化和报告生成。

  • 关注点分离：整合智能体只关心最终的呈现逻辑，不关心数据从何而来，实现了业务逻辑的清晰分离。
  • 统一出口：所有分散的数据在这里汇集成一个统一、规范的最终产物（HTML报告）。

2. 编排模式：并行与串行结合

  系统通过 并行Agent[ParallelAgent] 和 串型AgentSequentialAgent 的组合，实现了对复杂工作流的优雅编排。系统清晰地定义描述了整个业务流程：首先并行执行所有采集任务，然后串行执行整合任务。这种编排方式兼具效率与逻辑的清晰性。

二、 技术实现：剖析核心组件

  通过多智能体的融合，实现了高效、可靠、灵活的智能体。

1. 核心框架

  LangGraph或类似智能体框架是整个系统的基石。此框架非一个简单的 LLM API 封装，其是一个完整的智能体开发框架，负责处理：

• 状态管理 (CallbackContext)：在不同的智能体和执行轮次之间传递数据（如 _time 变量和各智能体的 output_key 结果）。
• 智能体编排：提供 SequentialAgent 和 ParallelAgent 等高阶智能体，让开发者可以像搭积木一样组合复杂的业务逻辑。

3. 工具与服务的解耦：MCP 的妙用

  MCP服务在系统中充当的是数据源的角色，智能体通过请求某个MCP或MCP中的某个Tool获取资讯信息。

• 智能体只知道它有一个名为 News 的MCP工具集，并可以调用其中的功能。
• 它完全不关心该MCP服务是如何实现资讯抓取的。
• 优势：MCP工具服务可以被独立开发、测试、部署和扩展，甚至可以用完全不同的编程语言实现，极大地提升了系统的模块化程度和可维护性。

4. 提示词工程 (Prompt Engineering)

  如果说 Agent框架 是骨架，那么提示词就是灵魂。该项目展示了多种高级提示词技巧：

• 角色化指令 (Role-based Instruction)：每个智能体都被赋予了清晰的身份、目标和行为准则，确保其输出稳定且符合预期。
• 动态模板注入 (Dynamic State Injection)：提示词中的 {_time} 和 {ithomeResult?} 占位符展示了 Agent框架 的状态注入能力。这使得提示词不再是静态文本，而是能与程序运行时状态交互的动态模板。
• 提示词即模板 (Prompt as Template, PaT)：这是最亮眼的一点。整合智能体直接将一个完整的 HTML 结构作为指令的一部分，要求 LLM 将数据填充进去。这种方法将复杂的 UI 生成逻辑完全委托给了 LLM，极大地简化了代码，开发者无需再使用传统的模板引擎（如 Jinja2），展示了 LLM 在内容生成领域的潜力。

5. 自动化调度：APScheduler

  APScheduler 的引入，完成了从“手动脚本”到“无人值守自动化服务”的最后一跃。AsyncIOScheduler 与 智能体应用 的无缝集成，确保了智能体服务的调度和自动化。

三、 应用价值与未来展望

  目前应用是个人工具类应用智能体或只是一个技术演示智能体，后续可根据需要扩展。

1. 当前应用价值

• 企业情报自动化：可直接应用于市场动态监测、竞品分析、行业新闻聚合等场景，为决策者提供及时、精准的信息支持。
• 高度可定制化：无论是信息源（添加新工具）、处理逻辑（修改提示词），还是输出格式（修改HTML模板），都可以轻松定制，满足不同团队和个人的特定需求。

2. 未来的扩展

• 集成内部系统：除了公开网站，工具集可以扩展为连接企业内部系统，如 gitea、GitLab 、内部OA等，实现内部信息的自动总结与报告。
• 增加决策与行动能力：整合智能体不仅可以生成报告，还可以被赋予更高级的指令，如“分析新闻情绪，如果发现重大负面舆情，则调用 API 发出告警”亦或是“实现公司内部信息的流转”从而实现从“信息处理”到“智能决策与行动”的跨越。
• 引入交互式分析：系统可扩展为一个交互式机器人。用户在收到简报后，可以追问“详细介绍一下关于小米的新闻”，系统会触发特定智能体进行深度信息挖掘，实现人机协同的闭环分析。

总结

  上文展示了如何构建下一代智能应用及其架构。它通过并行、串行、多智能体的组合，诠释了AI工程化的常见模式。本文所述智能体架构可作为后续可扩展、可定制的智能体开发的样板，后续应用开发也将围绕着多智能体的协作与编排而展开。

HITL(人在环中)

       HITL(Human-in-the-Loop)人在环中 ，将人类引入智能体的关键节点从而达到人机协同的闭环。引入HITL的具体原因如下：
       1、风险控制： 人作为最终的决策守门员
       2、知识补充校正： 提供领域知识弥补AI知识盲区
       3、驱动模型迭代进化

      在不同阶段都可引入HITL，在模型训练阶段可以引入HITL对进行数据标注、校正偏见，在执行阶段通过HITL进行输出审核，在决策阶段通过HITL进行风险控制。
      HITL最终能达到的作用包括如下：
      1、抑制幻觉与错误： 通过专家介入纠正模型幻觉
      2、责任清晰化： 如医疗诊断书的签署、法律文书的生成都需要人工去做决策
      3、提升信任度： 流程的关键节点都是有专家参与监督的，而不是完全自动化的

HITL应用

      在这里主要介绍在Workflow中引入HITL对工作流的某些节点输出进行一定程度的干预。HITL在workFLow中的具体实现也会根据业务性质有所不同，这里只简单介绍三种比较简单的HITL应用模式。

      1、在关键流程前插入人工决策节点
      在关键业务流程执行前插入人工决策节点，由领域专家人员决定是否继续执行后续流程或重新开始执行，适用于高风险操作如金融交易、医疗诊断等场景。

      2、对关键输出后插入人工审核节点

      在workflow工作流的某个关键节点后加入人工审核环节，确保结果准确性，适用于内容生成、文档处理、法律文书生成等质量敏感场景。

      3、在节点输出置信度低于某个阈值时请求人工介入
      在workflow工作流中加入置信度检测节点当置信度低于设定阈值时自动请求人工介入，平衡效率与准确性，适用于客服系统、图像识别等AI不确定性较高的场景。

      当然上面只是三个比较简单HITL应用模型，实际场景中应用HITL可能需要详细分析workflow流程才能确定哪个环节需要人工的介入。

基于HITL的文章生成工作流

      如下的流程图画出了AI辅助文章撰写的全流程，包括主题定义、大纲生成、初稿撰写、人工审核及最终润色优化，其中初稿审核也就是我们本文所说的HITL，也就是人工介入的节点。

      这里的文章撰写智能体在用户提供主题后生成大纲、接着编写文章初稿后提示审核或编辑草稿，后再进行风格优化后生成最终文章。这里只在草稿生成后提供了人工介入，只要需要也可以在大纲编写完成后就进行人工介入，对大纲不满意可以打回让模型再生成一次大纲。
      也有人会认为人为介入多了这还算是人工智能？在目前阶段有些AI工作流/智能体应用如果你对质量、可靠性要求非常高就很难做到得完全的0介入。按照自动驾驶的分级来看Agent目前也只是处于L2级别的Agent，距离L3级别Agent还有相当长一段时间。当前汽车也只是辅助驾驶，也做不到完全0介入，国内无驾驶员的示范运营区后台也有着人工在出现问题时介入。

      目前市面上很多此类DIY项目都是服务端基于小智的魔改、小智的设备端固件使用官方开源版本。其ESP32固件使用的是C开发对于不熟悉C的人来二次开发改造说难度太大。

      本文所DIY的语音助手设备端使用的是MicroPython、服务端是Python，对于很多开发者来说MicroPython入门没难度。但其性能、稳定性和C++开发的没法比，对于DIY的小玩具这已经基本够了。下面分别介绍整体架构、设备端流程、服务端流程等。

架构与流程

      基于ESP32 (MicroPython) 开发的固件和 Python服务端，最基本的主要组件有：音频采集、VAD检测、ASR识别、大模型、TTS 服务、WebSocket通讯等。下面将给出设备端与服务端的整体架构图以及整个平台的各个阶段完整数据流程，具体如下图所示。

系统架构图

数据流描述

服务端

系统架构图

      Python服务端提供WebSocket服务，整个架构基于异步编程模型，层次清晰，模块解耦，具有良好的扩展性和维护性。目前除了大模型没有采用流式输出，其他服务调用均采用流式处理技术，实现了低延迟的实时语音交互体验。

流程图

      WebSocket服务层作为最上层，负责网络通信和连接管理，在指定端口提供WebSocket服务，支持双向实时通信和消息路由。
      业务处理层是核心逻辑层，包含三个关键模块：Connection Handler负责管理每个客户端连接的生命周期；消息处理器实现了文本和二进制消息的解析与路由；异步任务管理器则协调各个AI服务的并发调用。
      AI服务集成层整合了四大AI能力：VAD进行语音活动检测；ASR和TTS均采用火山引擎服务，分别负责语音识别和语音合成；LLM使用DeepSeek实现智能对话生成。外部API服务层统一管理第三方服务调用，包括火山引擎API、DeepSeek API和PyTorch Hub。

设备端

      ESP32-S3硬件层包含INMP441麦克风负责音频采集、MAX98357功放实现音频播放、OLED显示屏提供状态反馈。
      驱动层封装了I2S音频接口实现音频数据的读写，异步WebSocket客户端处理网络通信，OLED驱动支持滚动显示功能。
      业务层的VoiceRecorder模块管理音频采集流程，使用deque队列缓冲音频数据，消息处理模块负责协议解析和数据路由。
      应用层通过异步任务管理器协调各模块运行，主控制逻辑处理系统状态和异常。架构充分考虑了嵌入式系统的资源限制，采用异步编程模型提高了系统效率和响应速度。

架构图

流程图

      目前面向个人市场推出此类玩具或助手等最大的难点应该是外观设计与销售渠道，技术实现目前都比较成熟，要推To B靠的就是某些特殊渠道关系了。

ESP32模组

      CPU 和片上存储器
      • 内置 ESP32-S3 系列芯片，Xtensa® 双核 32 位 LX7 微处理器 (支持单精度浮点运算单元)，支持 高达 240 MHz 的时钟频率
      • 384 KB ROM
      • 512 KB SRAM
      • 16 KB RTC SRAM
      • 最大 16 MB PSRAM
      • GPIO、SPI、LCD、Camera 接口、UART、I2C、I2S等

      单买新品目前38块左右，从去年底爆火涨价了。你直接买芯片还没法直接用，还需要自己去打板比较麻烦。普通玩家直接买ESP32开发板就好了，目前市面上各种各样的ESP32开发板，或直接买乐鑫的开发板，当然价格自然也不是三十多块。要成本更低还可以使用更低端的芯片。

烧录

      ESP32烧录固件非常方便直接使用USB将开发板连接到电脑即可通过串口烧录固件。烧录固件有多种方式，除了可以使用官方提供的flash_download_tool与esptool固件烧录工具还可以使用如Thonny、esp-launchpad等第三方烧录工具，这里使用esptool烧录固件。
      现在买的很多开发板都内置了小智的固件，这里刷的是MicroPython 固件。

安装esptoolpip install esptool

      ESP32开发板连接到电脑后在Windows的设备管理器中可以看如下信息，端口(COM和LPT)处可看到连接的串口设备USB-SERIAL CH340(COM4)使用的端口为COM4。此处的端口需要记住，下面刷固件需要用到此端口。

      下载 ESP32S3 的 MicroPython 固件
      https://micropython.org/download/ESP32_GENERIC_S3/

      在Linux中端口是这种形式：/dev/ttyUSB或/dev/ttyACM0，这里是windows所以--port 值是 COM4

      读取ESP32芯片信息，可以看到芯片的PSRAM、频率、支持WIFI、蓝牙、MAC地址等数据。

esptool --chip esp32s3 -p COM4 chip_id

esptool.py v4.8.1Serial port COM4Connecting.....Chip is ESP32-S3 (QFN56) (revision v0.2)Features: WiFi, BLE, Embedded PSRAM 8MB (AP_3v3)Crystal is 40MHzMAC: d8:3b:da:6e:cb:0cUploading stub...Running stub...Stub running...Warning: ESP32-S3 has no Chip ID. Reading MAC instead.MAC: d8:3b:da:6e:cb:0cHard resetting via RTS pin...

读取设备SPI flash信息

esptool --chip esp32s3 --port COM4 flash_idesptool.py v4.8.1Serial port COM4Connecting.....Chip is ESP32-S3 (QFN56) (revision v0.2)Features: WiFi, BLE, Embedded PSRAM 8MB (AP_3v3)Crystal is 40MHzMAC: d8:3b:da:6e:cb:0cUploading stub...Running stub...Stub running...Manufacturer: c8Device: 4018Detected flash size: 16MBFlash type set in eFuse: quad (4 data lines)Flash voltage set by eFuse to 3.3VHard resetting via RTS pin...

在刷固件前先清除板内原有固件

Esptool --chip esp32s3 --port COM4 erase_flash

如有需要还可先备份固件：read_flash <起始地址> <结束地址或大小> <完整备份文件路径> ALL:自动检测闪存大小

esptool --chip esp32s3 --port COM3 read_flash 0x0 ALL C:\path\to\backup\firmware_backup.bin

亮屏

      在https://github.com/AntonVanke/MicroPython-uFont下载中文字体上传到ESP32中，按SSD1306驱动芯片方法轻松点亮屏幕，需要注意的是scl与sda的接线引脚，以及屏幕的分辨率，分辨率对不上可能会导致显示异常。

      亮屏仅仅是第一步，后续怎么能把ESP32玩出花样才是关键。作为所谓AI物联网神器能做的太多。

参考资料：https://docs.espressif.com/projects/esptool/en/latest/esp32s3/esptool/