跳转至

Harness 工程

提示词工程

提示词工程（Prompt Engineering）：通过人工设计输入模板来引导模型输出，暴露“提示-响应”模式的局限性（~2025年）。

  • 意图偏移：模型难以通过单⼀指令准确捕捉复杂业务背后的真实意图。
  • ⻓程记忆缺失：在⻓对话或多轮交互中，模型容易丢失初始任务⽬标。
  • 逻辑断层：⾯对多步骤、跨领域的复杂任务时，模型往往因缺乏结构化引导⽽导致输出失控。

ReAct

ReAct（Reasoning and Acting，推理与⾏动，2023年）范式的本质，其实就是⼀个动态构建与丰富对话上下⽂的过程。LLM 的每⼀次决策都极度依赖当前步产⽣的观察（Observation）并将其整合进上下⽂，从⽽驱动下⼀轮的推理。

react

当时，单Agent系统⼤多停留在演示（Demo）或实验阶段，尚未⼤规模应⽤于复杂真实场景，⻓程复杂交互引发的问题并未充分暴露。

上下文工程

上下文工程（Context Engineering）：如何系统化地构建、管理并动态演化LLM的输⼊语境？

  • 通过整合业务意图、任务需求、⼯具回调及历史记忆等多维信息，确保进⼊模型上下⽂窗⼝（Context Window）的数据具备精准性与结构化特征。

上下⽂⼯程的本质：它并⾮单纯的提示词润⾊，⽽是⼀套对信息进⾏系统化采集、过滤与组合的技术范式。通过⼯程化⼿段，将⽤户模糊、简略的原始提示（如“×××怎么样？”）转换为富含精准上下⽂的⾼质量输⼊。

“上下⽂”是输⼊模型的核⼼语义载体，⽽“⼯程”则是通过程序化、系统化的⼿段对这些载体进⾏动态构建与持续优化。承担这⼀⼯程化任务的核⼼载体正是Agent，即由Agent驱动的智能上下⽂构建。

核⼼逻辑模块

Agent（上下文工程）核⼼逻辑始终围绕感知、规划、执⾏、反思这四⼤模块展开：

  • 感知模块：意图识别，将⾮结构化的⾃然语⾔提问转换为结构化的任务描述，并理解其核⼼意图，从⽽路由到合适的处理模块。如 Claude Code 根据⽤户意图匹配最合适的模型。
  • 规划模块：⽣成解决问题的思维链，如何通过合理的步骤设计来完成⽤户的任务。Code Agent 一般都支持 ReAct 和 PlanAct 模式（如 pi agent）。
  • ReAct模式：通过“推理-⾏动-观察”的闭环，实现上下⽂的动态演进。
  • PlanAct模式：预先⽣成完整计划或由⼈⼯注⼊标准作业程序（Standard Operating Procedure，SOP），驱动LLM按序执⾏。
  • Sequential Thinking：这是⼀个开源的MCP（Model Context Protocol，模型上下⽂协议）Server，可以帮助LLM实现多轮⾃主规划与反思，显著提升复杂任务 的处理成功率。
  • 执行模块：通过调⽤外部 API 或运⾏代码 Agent（如Code Agent），获取物理世界的实时数据。
  • 反思模块：会对规划和执⾏模块的结果进⾏反思，检查是否存在错误或者不完善的地⽅，进⽽提出改正意⻅并重新引导规划模块进⾏新⼀轮的规划。
  • ⼯程化层⾯，既可以⾃⾏通过反思，提示词的设计为Agent提供返思能⼒，也可以借助Sequential Thinking⼯具完成从规划到反思的全部过程

上下文管理

上下⽂窗⼝有限：记忆管理和上下⽂卸载（Context Offloading）。

记忆管理：通过短期记忆和⻓期记忆相结合，确保在对话或任务中能记住之前的交互内容，避免重复提问或上下⽂断裂；维护⽤户的⻓期偏好、历史⾏为，以及从外部检索到的专业知识等信息。

上下⽂卸载：保留当前任务最相关的关键信息，上下⽂并⾮越多越好。例如，将详尽的分析结果写⼊独⽴的Markdown⽂件，⽽在当前对话窗⼝中仅保留⽂件路径和摘要；或者按需加载的⽅式避免了将太多暂时⽤不到的⼯具描述等信息加载到模型上下⽂中。

Agent 路线

Agent的概念于2023年开始受到业界⼴泛关注：开始探索如何赋予LLM与外部环境交互的能⼒，即让模型不仅具备思考能⼒，还能主动通过调⽤外部⼯具（如数据库、API、搜索引擎等）获取最新、最具相关性的外部信息，并将这些信息融⼊模型的推理过程，进⽽显著提升回答的准确性、时效性与实⽤性。

简单调用Agent

Function Calling

2023年6⽉，模型⼚商OpenAI正式推出Function Calling（函数调⽤）技术，在模型预训练或微调阶段，引⼊结构化的⼯具交互数据，使模型学会在适当情境下触发⼯具调⽤。训练样本如下：

[
    {"role": "user", "content": "查询北京明天天⽓"},
    {"role": "assistant", 
     "tool_calls": [{"name": "get_weather", "arguments": {"location": "北京"}}]
    },
    {"role": "tool", "name": "get_weather", "content": "{\"temperature\": 22}"},
    {"role": "assistant", "content": "北京明天⽓温22℃"}
]

LLM在决策过程中的内部推理逻辑，如“为何选择此⼯具⽽⾮彼⼯具”等关键思考步骤，对开发者⽽⾔仍然是⼀个⿊盒。

ReAct

ReAct: Synergizing Reasoning and Acting in Language Models.

主流方案：ReAct 循环 + Function Calling 做 Action 输出。

ReAct的核⼼优势在于其零训练依赖：通过精⼼设计的提示词即可引导LLM在推理过程中交替执⾏思考（Reasoning）与⾏动（Acting），且LLM在推理阶段的思考内容，会在对话返回中与⼯具调⽤指令⼀起输出。

  • 开发者只需构造⼀段包含任务⽬标、可⽤⼯具列表及交互格式的上下⽂模板，模型便能在运⾏时⾃主完成5个步骤的循环（见论文）。

ReAct范式虽然在初期展示了其灵活性和易⽤性，但也暴露出若⼲局限性。

  • 对LLM⾃身能⼒的⾼度依赖：LLM的逻辑推理能⼒、指令遵循能⼒或格式化输出能⼒；
  • 执⾏效率问题：串⾏的“思考-⾏动”循环可能导致较⾼的总耗时和费⽤；

  • 提示词的脆弱性：建立在精⼼设计的提示词模板，且并⾮所有模型都能持续稳定地遵循预设格式；

  • Agent可能陷⼊局部最优：步进式的决策模式意味着缺乏全局视⻆和⻓远规划。

深度思考Agent

新的设计模式

Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models

CodeAct模式：核⼼思想是将⼯具抽象为代码（Python/JS/Shell）执⾏器，⽽⾮预定义的业务API。LLM 生成可执行的代码片段，作为参数传递给代码执行器运行。

计划-执⾏（Plan-Act）模式：引入分段决策机制，先拆解问题，生成结构化的多步执行计划，Agent 严格按照步骤调⽤⼯具、收集反馈并推进任务。解决应对复杂任务中推理深度不⾜的问题，减少了因局部决策失误导致的整体失败⻛险。

反思（Reflection）模式：事后校验与⾃我修正机制。独⽴的反思Agent会对其输出结果进⾏评估：检查是否存在逻辑漏洞、信息遗漏、⼯具误⽤或格式错误等问题。若发现问题，系统可触发重试、补充查询或调整策略，从⽽形成闭环优化。

⼈机协作（Human-In-the-Loop）模式：在流程中嵌⼊⼈⼯⼲预点，允许⼈类在必要时审核、修正或确认Agent的⾏为。

深度思考

深度思考型Agent（Deep- Thinking Agent，2025）：多种设计模式的出现，更希望Agent能够⾃主进⾏⻓达⼏⼗分钟甚⾄⼏⼩时的任务执⾏，从⽽深⼊地完成⼀项任务。

通过融合Agent设计模式，构建⼀个持续迭代、⾃我修正的认知闭环，从⽽实现对复杂问题的系统性拆解与深度研究。以 Goggle 的 DeepResearch为例：

flowchart TD
    A[查询] --> B[生成多样性查询]
    B --> C[并行联网搜索]
    C --> D[反思]
    D -->|需要搜索更多的内容| C
    D -->|不需要进行进一步搜索| E[整合答案]
    E --> F[输出报告]

Code Agent

Code Agent != Coding Agent(Claude Code/Cusor)

Code Agent：⼀种以⽣成并执⾏代码为核⼼决策⼿段的Agent范式，与传统的ReAct Agent（通过解析JSON触发⼯具）有着本质的区别。

以下是简单案例的对比：Agent配置⼀个加法⼯具函数 calc()，并要求其计算从1加到100的结果

  • ReAct Agent，每⼀轮仅执⾏⼀次 calc() 函数，需要进⾏99轮对话交互，极易因⻓程推理疲劳导致计数错误。

react_vs_code_agent

多 Agent

SubAgent：被称为⼦Agent或专家Agent，意指在 AI 系统中专⻔负责某⼀特定⼦任务或领域知识的专项 Agent。拥有⼲净、聚焦的上下⽂（仅包含与其任务相关的⼯具、规则与记忆）。

典型的多Agent系统（Multi-Agent System，MAS）通常由多个SubAgent与⼀个协调者Agent（Manager Agent）构成。后者负责任务分解、调度分发、冲突仲裁与结果整合，⽽前者则专注于各⾃领域的⾼效执⾏。

MAS的本质在于解决上下⽂污染（Context Pollution）问题：单Agent架构上下⽂会不可避免地混杂多种异构信息，包括问题的推理轨迹、可⽤⼯具的描述、⼯具调⽤的中间结果、多轮历史交互记录以及⽤户的原始意图等

  • 单Agent 架构引⼊了⼤量认知噪声，导致上下⽂窗⼝迅速耗尽，在处理多步骤、⻓周期任务时达到Token上限⽽被迫截断上下⽂。

上下文的“元驱动”

感知模块（意图识别）

Agent 落地的问题：

  • ⽤户提问⾼度⾃由甚⾄随⼼所欲，通过意图识别机制在⼊⼝处及时拦截，防⽌系统被滥⽤或引发法律隐患；
  • ⽤户输⼊普遍存在语义模糊性，可以从多个维度进行解答；
  • 针对⽤户的提问选择合适的模型进⾏处理：每个模型都针对不同的优势、⻛格或延迟与成本特性进⾏优化；

⼀个成熟的Agent系统必须融合当前对话上下⽂、⽤户画像、历史交互记录等多维信号，对表层语句背后的深层需求进⾏精准推断，从⽽⽣成相关、准确且安全的响应。

从技术本质上看，意图识别的⽬标是让 LLM 能够判断⽤户问题所属的预设类别，并输出对应的标签。

  • 采⽤提示词⼯程，通过精⼼设计的指令引导LLM进⾏分类。
  • 训练专⽤的轻量级路由模型，独⽴于主LLM完成意图判断。
  • 通过对1.5B、3B、6B等⼩模型进⾏领域微调，使这些模型在特定业务场景下具备⾼精度的分类能⼒

领域通用型Arch-Router

《Arch-Router: Aligning LLM Routing with Human Preferences》

示例和使用代码：[TODO LINK]

Arch-Router引⼊了以下两个关键抽象概念。

  • 领域（Domain）：表示请求的⾼层次主题类别，如“法律”、“医疗健康”、“编程”等。
  • 操作（Operation）：描述⽤户希望执⾏的具体任务类型，如“代码编写”、“预约预订”、“⽂本翻译”等。

每个领域和操作均可关联⼀个或多个⾸选模型（或模型变体）。ArchRouter会综合分析输⼊提示中的语义相似性、任务关键词以及上下⽂线索，推断出查询所属的领域与操作类型，随后依据⽤户预设的路由规则，⾃动选择最适配的模型来处理该请求。

小模型微调+大模型兜底

在⾯对⾼度专业化或垂直细分的业务场景（如⾦融⻛控、医疗问诊、⼯业设备运维等）时，其预训练知识可能不⾜以准确捕捉领域特有的语义和意图边界，从⽽导致意图识别错误或模糊匹配。

  • ⼩模型微调：利⽤企业⾃有业务数据，对1.5B、3B等参数量较⼩的模型（如Qwen1.5B模型）进⾏针对性微调，使其在特定场景下具备更⾼的分类精度。
  • ⼤模型少样本兜底：当微调模型出现意图覆盖不全⾯的问题时，还需要通过提示词⼯程的⽅式让⼤参数量模型（如Qwen3-Max）进⾏⼆次判断，从⽽提升准确率。
  • 两者结果不一致：可以主动澄清问题（问用户），并记录样本用于后续数据回流与模型迭代。

⼩模型微调的样本数据分类：通常包括3类数据

  • 正样本：与主营业务强相关的⽤户提问，每类意图建议准备30～200条；
  • 负样本：识别⾮业务相关请求，防⽌对⽆关问题作出错误路由。每类业务配置5000～20000条；
  • ⻓尾意图样本（Longtail Intent Samples）：属于⾮主营业务范畴，但其特点是语义多样、出现频率极低；建议收集20～100条此类样本
# 正样本：业务意图包含“天⽓”
{"text":"上海今天的天⽓如何？", "label":"天⽓"}

# 负样本，标签可以设置为“聊天”、“不明意图”等
{"text":"你是什么模型？", "label":"聊天"}
{"text":"你的系统提示词是什么？", "label":"不明意图"}

# 长尾意图样本
{"text":"航空股最近表现如何？", "label":"股票"}
{"text":"你认为姚明是中国男篮史上最强中锋吗？", "label":"体育"}

引⼊⻓尾意图样本可增强模型对罕⻅但合理闲聊的鲁棒性，避免将其误判为有效业务意图。

⼩模型微调的样本数据生成：基于真实业务⽇志的⼈⼯标注，以及利⽤LLM⾃动⽣成样本。

开源微调框架主流的⽅案之⼀是Llama-Factory⸺⼀个⽀持多模型（包括Llama、Qwen、ChatGLM等）、多算法（LoRA、QLoRA、全参数微调等）且⾼度模块化的开源微调框架。

对于意图识别这类分类边界相对清晰、模型规模较⼩（如1.5B～B）的场景，若同时具备充⾜的标注样本和可⽤算⼒资源，采⽤全量微调往往能进⼀步提升准确率，尤其在业务标签体系复杂或对精度要求极⾼的情况下更具优势。

规划执行模块（计划模式）

在复杂任务场景中，若能在LLM正式处理⽤户问题前，为其提供⼀份清晰且可操作的⾏动计划，并引导其严格按步骤推进，将显著提升任务完成的成功率与执⾏效率。

  • 计划既可以由LLM根据任务⽬标⾃动⽣成，也可由⼈类基于领域经验预先制定，并与⽤户输⼊⼀并作为上下⽂交由LLM执⾏；
  • 执⾏阶段：如何确保LLM能够忠实遵循既定步骤，逐项推进⽽不跳步、不偏离，需要在提示词设计、状态管理或⼯作流控制等⽅⾯进⾏精⼼编排。

计划模块对语义理解与推理能⼒要求较⾼，可选⽤理解⼒更强的模型；执⾏模块主要承担确定性操作，可选⽤响应更快、成本更低的模型。

复杂的计划模式体现在执⾏模块对于任务的执⾏跟踪。

  • Plan Agent：所有的步骤 + 已完成的步骤名和结果的列表 => 剩余的步骤，如果没有剩余步骤则结束；
  • Execute Agent：根据剩余的步骤，仅执行第一个步骤 =>已完成的步骤名和结果的列表；

反思模式

反思模式的架构分为⽣成模块与反思模块两个部分：

  • ⽣成模块可以采⽤多种形式，例如，基于Function Calling的简单⼯具调⽤器、具备多轮推理能⼒的ReAct Agent，或是计划-执⾏型Agent。
  • 反思模块会对执⾏模块的输出进⾏系统性审查意⻅，审查意见会将作为反馈信号重新注⼊执⾏模块，触发新⼀轮的优化迭代；或者判断无需优化，则结束。

CodeAct模式

将整个编程语⾔视为⼀个通⽤、开放的⼯具空间。只要模型具备⾜够的代码⽣成能⼒，它就能在任意时刻构造出满⾜当前需求的“临时⼯具”，实现⾼度灵活的任务求解。适⽤于⼯具集未知、任务多变或需要组合多个操作的复杂场景。

代码执⾏器：通常采⽤容器化沙箱（如Docker）、受限解释器或专⽤执⾏服务来保障安全性。

  • 可以通过生成文件（write_file）和运行脚本（bash）两个命令作为基本的实现方式。

人机协作

Interrupt（中断）+ Checkpoint（状态快照）+ Resume（恢复）：当LLM判断当前阶段需要⼈⼯介⼊时，⼯作流/Agent将主动中断，并将当前的运⾏状态、上下⽂信息等关键数据持久化保存⾄检查点。⼀旦⽤户完成交互，⼯作流/Agent便会从检查点中恢复先前保存的状态，并继续执⾏后续任务。

  • 强制⼈类介⼊：将“⼈类节点”显式嵌⼊⼯作流的特定关键步骤中（固定节点）。
  • ⾃主触发⼈类介⼊：LLM在运⾏过程中动态判断是否需要⼈类介⼊，并在必要时触发中断请求。（询问用户信息被注册为工具，由 LLM 返回是否需要调用，问题是什么）

human_in_loop.png

核心实现：以 LangChain 的 概念为例

  • interrupt（中断）：主动挂起当前正在执⾏的⼯作流。
  • memory（记忆）：保存⼯作流在中断时刻的上下⽂信息。
  • checkpointer（检查点）：记录⼯作流的执⾏进度和中断位置。
  • thread_id（线程ID）：⼀次会话或任务的唯⼀标识符，不同值对应彼此隔离的状态空间。

LangChain 的实现中，针对human node 的interrupt函数代码（对于thread_id），第一次返回异常，框架捕获处理后，用户输入后，继续调用图执行，重新执行 human node，第二次执行interrupt时不会抛出异常。

DeepResearch

路线： RAG -> WAG ->主动规划、多轮搜索与迭代验证能⼒的深度思考型Agent

检索增强⽣成（Retrieval Augmented Generation，RAG），⽹络增强⽣成（Web Augmented Generation，WAG）

RAG：2025年之前，提升LLM回答准确性的主流⽅案是RAG，其构建通常分为以下两个阶段：

  • 数据索引阶段：将原始⽂档进⾏切分（Chunking），利⽤嵌⼊模型（Embedding Model）转换为向量数据，并持久化存储⾄向量数据库；
  • 检索⽣成阶段：系统将提问请求向量化，并在向量数据库中进⾏相似性搜索。匹配出的相似⽂档⽚段将作为上下⽂补充，随原始⽤户提问⼀同发送给LLM，

rag.png在实际⼯程中，RAG经常⾯临召回率（Recall) 低下的问题。即便数据库中存在相关信息，也可能因⽤户语义表达模糊或向量空间偏移导致检索失败。查询重写（Query Rewriting)或Agentic RAG等多轮检索验证优化⼿段，本质上仍属于被动检索，难以根据已知信息动态调整搜索策略，导致获取的信息往往局限于表⾯，缺乏深度与系统性。

WAG：2025年年初，主流⼤模型应⽤普及了联网搜索功能。LLM通过理解⽤户意图，将其拆解为多个关键词并调⽤搜索引擎API，系统抓取多个⽹⻚内容进⾏汇总，最终⽣成带有来源参考的回答。也称为DeepSearch。

DeepResearch：从单次检索转向了⾃主迭代，模拟人类工作模式：任务拆解→持续探索→批判反思→结构化输出。核⼼是⼀个由提示词⼯程驱动的深度思考型Agent，包括：

  • 思考与决策模块：负责逻辑推理、任务拆解与结果反思。
  • 信息搜索模块：负责执⾏联⽹检索及⽹⻚内容提取。
  • 报告输出模块：负责将多轮搜集的信息整合为结构化⽂档。

其细化流程拆分为：初始探索（首轮信息采集） -> 状态评估（分析当前信息） -> 策略制定（是否追加搜索） -> 迭代执行（继续初始探索）/循环终止（整合输出报告）。

SequentialThinking

作为 mcp server 提供，包含⼀个轻量级的状态管理器，⽤于存储历史步骤和当前计划步骤执⾏状态的管理器。

工具描述会送入 LLM 上下文，作为工具使用指南，但不属于 system prompt。它是软引导而非强制指令，配合顶层 system prompt，引导模型调用 sequential_thinking；依靠 MCP 把思考记录追加回消息历史，从而形成「假设→验证→修正→下一步」的迭代推理闭环。

深度研究（Deep Research）的核⼼：允许LLM推翻之前的结论。

记忆工程

主流LLM在设计上是⽆状态的，每次API调⽤都是独⽴的计算过程，模型不会⾃动保留历史对话信息。

  • 上下⽂丢失、个性化缺失、学习能力受限、逻辑一致性难维持；

上下⽂注⼊，即将历史对话记录重新封装进新的请求中。

短期记忆，通过占⽤模型上下⽂窗⼝实现的临时信息存储，其受限于模型的最大 Token 长度。

  • 滑动窗⼝：保留最近N轮对话或通过算法剔除⽆关⽚段来精简上下⽂；
  • 上下⽂摘要（压缩）：包括对话概况（提取决策点和关键事实），偏好提取（记录⽤户的⾏为模式）；

上下文压缩机制：Agent 中一般采用三级压缩策略

  • 在每⼀轮对话开始前，针对旧的⼯具调⽤及其返回结果进⾏压缩；

  • 核⼼策略是对历史⼯具调⽤结果进⾏“微缩”：如保留最近n个⼯具调⽤（同时返回长度大于100）的完整返回结果，超出范围的替换为精简点占位符（如"[Previous: used {tool_name}]"）。

  • 当上下⽂Token数量超过预设阈值时，将当前完整的对话历史保存到磁盘，并调⽤LLM对这段历史进⾏摘要⽣成；

  • 利⽤当前时间戳⽣成唯⼀的JSONL⽂件名，将内存中完整的messages列表逐⾏写⼊磁盘；

  • 截断消息（防止超出上下文限制），构建提示词，调用 LLM 返回摘要信息；
  • 构建精简对话列表（仅单个user和 assistant消息）；
[ 
    {"role": "user", "content": f"[Conversation compressed. Transcript:
{transcript_path}]\n\n{summary}"},
  {"role": "assistant", "content": "Understood. I have the context from the
summary. Continuing."}
]

  • 赋予Agent⼀个Compact⼯具，当LLM⾃主判断需要进⾏压缩时，它可以主动调⽤该⼯具。

  • Agent loop 循环⼊⼝处执⾏⾃动压缩检查（第一级和第二级（预估当前token量））

  • 在⼯具调⽤处理逻辑中响应 Agent的主动压缩请求（LLM 判断需要调用压缩工具时）

⻓期记忆：通过独⽴于模型之外的存储介质实现信息的永久化留存。

  • 外部⽂件持久化：将任务的阶段性成果、冗⻓的原始数据或代码库保存为物理⽂件，仅在上下⽂窗⼝中保留指向这些⽂件的指针或摘要。
  • 基于RAG的语义检索：将历史对话、⽤户画像等信息进⾏向量化处理并存⼊向量数据库。

多层级记忆管理：分为会话层（单个会话的记忆）、用户层（不同用户跨会话的记忆）、角色层（不同用途的Agent的记忆）、组织层（团队知识库记忆）等。

通过⼀套⼯程化的过滤与仲裁逻辑，实现记忆的精准留存（“提取-仲裁-混合存储”的设计范式）。其核⼼处理流程可分为以下3个阶段。

  • 语义提取与事实建模：专门Agent，利⽤LLM充当语义过滤器，捕获结构化事实（如偏好、意图等）。
  • 冲突仲裁与逻辑更新：提取到的新事实与既有记忆库进⾏⽐对进行操作（新增、更新、删除、跳过）；
  • 向量与图的混合存储架构：向量（语义相似度）是语义召回的基础方案，图（关系推理）是记忆关联追踪；

Skills

Skills 通过上下⽂卸载技术，动态按需加载⼯具描述，⽽⾮全量预载，从根本上缓解了上下⽂膨胀问题。

提供了⼀种标准化的结构化格式，允许开发者将解决问题所需的完整上下⽂（包括思考路径、执⾏流程、依赖⼯具、数据来源及输出规范）封装为⼀个独⽴的专家经验包。当类似任务再次出现时，Agent就如同接⼿项⽬的同事，通过解析该经验包，即可稳定地复现原有的⼯作流，从⽽⾼效、⼀致地解决。

结构定义

Skill在物理结构上表现为⼀个⽂件夹，该⽂件夹的名称即为该Skill的名称：

  • SKILL.md⽂件（必选）：定义标签与说明书，以Markdown格式清晰描述该Skill的功能、输⼊输出 规范、调⽤条件、任务执⾏步骤、使⽤示例等关键信息。
  • scripts/⽂件夹（可选）：存放可执⾏的代码脚本（如Python等）；
  • references/⽂件夹（可选）：存放⽀撑该 Skill 运⾏的参考资料，提供领域知识依据，提升输出的专业性与准确性。
  • assets/⽂件夹（可选）：⽤于存储静态资源与模板⽂件，技能需要复制素材时使用。

渐进式加载机制

分成三级渐进式加载：

  • L1：加载Skills标签；L2：读取Skills说明的正⽂；L3：按需加载资源（资料、代码、资源等）

实现渐进式加载的思路：至少具备 Read 和 Bash 两个工具；

  • 初始化阶段：读取 Skills 的目录，每个 SKILL.md 的标签，注入系统提示词；
  • 任务处理阶段：当LLM判断某任务可能匹配某个 Skill 时，触发 Read ⼯具，读取该 Skill 的完整 SKILL.md；若⽂档指示需执⾏脚本或查阅资料，则进⼀步调⽤Bash执⾏代码脚本或Read⼯具获取所需资源。

整个流程天然适配ReAct架构：LLM负责推理与决策，⼯具负责感知与⾏动。

写作指导

⼀份优秀的SKILL.md应包含以下5个关键部分：

  • 定时机：明确该Skill的适⽤情境或触发条件，即在什么上下⽂、⽤户意图或系统状态下，应激活该Skill；助于模型判断何时调⽤该能⼒，避免误⽤或遗漏。
  • 立目标：⼀句简洁、具体的话说明该Skill要解决的核⼼问题，聚焦、可衡量，避免模糊或宽泛的表述；例如，“将⽤户输⼊的⾃然语⾔查询转换为结构化的SQL语句”⽐“帮助⽤户查询数据”更具指导性。
  • 理规则：执⾏逻辑与操作步骤，包括输⼊如何解析、中间如何处理、输出应遵循何种格式等；需条理清晰、逻辑严密，便于模型按步骤推理和执⾏。
  • 给示例：提供典型输⼊-输出对作为参考，最好同时包含正面示例和反面示例（错误或不适合场景）；示例应贴近真实使⽤场景，具有代表性，能有效引导模型⾏为。
  • 划边界：定义能⼒边界与限制条件，如在数据不⾜时返回特定提示、异常情况时用兜底策略等；提升系统的鲁棒性与安全性。

复现Claude Code核⼼设计模式

Harness 是为LLM构建⼀个可以⻓时间稳定、安全运⾏的环境。其核⼼：不直接⼲预模型内部决策，⽽是专注于构建模型边界⽀撑环境。

  • Agent Loop：持续⼯作的前提，仅保留了Read、Write、Glob、Replace、Bash等核⼼⼯具，并赋予模型系统级的操作权限，减少了中间层的损耗；
  • 上下⽂⼯程：解决上下⽂窗⼝限制，支持上下⽂压缩等机制；
  • 持久化与异步：实现跨会话的任务延续；
  • 多Agent系统：多实例同时进⾏协同⼯作

SubAgent

SubAgent模式：通过引⼊SubAgent，主Agent将只负责任务下发与结果验收，⽽具体的执⾏细节、多轮试错由⼦Agent完成。

  • 封装为单独的 Agent 工具函数，当决定调用时，主循环将执行该函数，将控制权暂时移交给⼦代理；
  • SubAgent工具函数是独⽴运⾏的Agent Loop，与主Agent的循环逻辑⾼度相似，但被封装在⼀个⼯具函数内部，并且引入 LLM 最大调用次数的限制，避免无限运行；

持久化与异步

Todo 模式：内存中的扁平化的任务清单，当LLM接收到任务指令后，⾸先会⽣成⼀份待办事项列表（Todo List），并实时追踪每个步骤的执⾏状态。

  • 通过提示词⼯程约束LLM的⾏为，要求其在处理具体任务前，必须优先⽣成执⾏计划。
  • 在随后的计划管理与状态维护环节，将设计⼀个专⽤的计划管理⼯具，赋予LLM根据实际执⾏情况⾃主调⽤该⼯具、完成计划更新等操作的能⼒。

Task System：⼀张有状态的任务图（Task Graph），任务状态持久化存储⾄磁盘，确保了任务的⽣命周期不再受限于单次对话窗⼝，从⽽实现了跨会话的任务追踪与管理。跟 TODO 的区别在于，工具实现的复杂度；

  • 将每⼀个任务抽象为⼀个独⽴的 JSON⽂件，并统⼀存储在指定的系统⽬录中；
  • 数据结构中新增了blockedBy（前置依赖）和blocks（后置依赖）字段，表示任务之间的关联；
  • 跨会话是因为默认1）存储的位置是全局目录；2）管理系统是全局的，多线程、多实例使用会有问题。
task_.json {"id":1, "status":"completed"}
task_.json {"id":2, "blockedBy":[1], "status":"pending"}
task_.json {"id":3, "blockedBy":[1], "status":"pending"}
task_.json {"id":4, "blockedBy":[2,]3, "status":"pending"}

后台任务机制，核⼼思路是：将耗时较⻓的操作移交⾄后台异步执⾏，从⽽释放主线程，确保Agent能够持续进⾏思考与决策。

  • 采⽤多线程模型，由LLM在任务解析阶段识别出潜在的慢操作，随后调⽤相应的⼯具函数，动态创建并启动⼀个后台线程来执⾏该任务。主线程则继续处理后续逻辑，⽆须等待后台任务完成。
  • 全局唯⼀的任务标识，跟踪状态；守护进程，执行超时设置；

Agent在每⼀轮对话中能够及时感知后台任务的状态变化；⼆是赋予LLM通过⼯具调⽤来创建或查询后台任务的能⼒。

  • 后台线程和主线程，采用消息队列进行通信；

Agent Teams

⼀个主Agent充当团队负责⼈（Leader），负责统筹全局、拆解任务、分配⼯作并综合最终结果；⽽各个队友（Teammates）则作为独⽴的执⾏单元，⻓期驻留，拥有各⾃的上下⽂窗⼝，并能直接进⾏相互通信。

  • 需要引⼊⼀个持久化的状态管理机制，如config.json文件记录每个团队的实时状态（如“空闲”,“工作中”）
  • 通信机制⽅⾯，团队负责⼈与各个队友之间，以及队友与队友之间，将采⽤邮箱模式（一对一/广播）进⾏消息传递。

队友的Agent Loop增加⼯具调⽤：注册两个核⼼⼯具

  • ⽤于发送点对点消息的工具和⽤于获取未读消息的工具。

主Agent的Agent Loop()函数进⾏逻辑升级，支持团队管理和通信功能：

  • ⼀是引⼊邮箱检查机制，确保团队负责⼈能够及时响应外部请求；
  • ⼆是注册团队管理相关的⼯具调⽤，赋予团队负责⼈调度团队的能⼒。

附录

工具

Bocha（商业）：专为 AI 应用设计的国产搜索引擎与搜索 API 平台，提供 Web 搜索、AI 搜索、多模态搜索等能力。

SearXNG：开源元搜索引擎，能聚合数十个搜索引擎结果，并去重和重排序，完全本地部署，杜绝数据追踪。

  • 支持免费的网页抓取：支持返回格式 html（原始网页信息）、json（提取标准化结果对象） 等；
  • 支持官方API 调用：如 Bing Search API；

LangGraph

状态（List<Message> + 自定义信息）在节点间流转；节点定义函数，接收并修改状态；节点间由边连接，可以是固定的（A->B，调用完A节点函数后，调用B节点），或者条件式的（通过函数，判断跳到那个节点）。

Streamlit

基于Python的响应式框架，因其能够将复杂的后端逻辑快速转换为简约、专业的Web界⾯，已成为当前⼤模型应⽤开发的⾸选。

Mem0

定位是为LLM应⽤提供⾃我进化的记忆层。提供user_id / agent_id / run_id / app_id 四维标识：

  1. run_id ：会话层，单次任务 / 会话，会话结束可归档或清理
  2. user_id： 用户层，跨会话长期记忆，Mem0 记忆抽取、图记忆、记忆衰减主要作用于这一层
  3. agent_id：角色层，不同的 Agent 实例（如写作助手，代码助手）维护自己的记忆；
  4. app_id ： 组织层，应用 / 组织全局共享知识库

参考文献

1.《Harness工程：从上下文管理到Agent系统构建》，邢云阳，人民邮电出版社。

2.