企业官网建设流程全解析

最近一段时间，GitHub 上围绕 AI Agent 的开源项目密度明显变高，几乎每周都有新的 Harness、新的 Skill 脚本、新的多 Agent 协作框架冒出来。这周热点榜单里，DeepSeek Agent Harness、AI 画图 Skill、自进化编程 Agent、团队工作台和可审计语义图谱这几个方向，基本把当前 Agent 工程化的几条主线都覆盖了：如何让模型稳定调用工具、如何沉淀可复用的技能脚本、如何让 Agent 自己改代码、如何让多个 Agent 协作、如何记录整个决策过程。

本文会从这几个热点项目切入，不打算只做新闻式盘点，而是把里面的通用技术点拆开，配合可运行的示例代码，带你把 Agent Harness、Skill 机制、自进化编程循环、多 Agent 协作和语义审计这些概念真正落地一遍。无论你是刚开始接触 AI Agent 开发，还是已经在做相关工程化，这篇文章都能帮你建立一套比较完整的知识框架。

1. 为什么 Agent Harness 和 Skill 突然成为热点

1.1 从“调 API”到“跑 Agent”的转变

过去两年，大多数开发者接触大模型是从 API 调用开始的：把 prompt 发给模型，拿到一段 JSON 或文本。这个阶段的核心是“模型能力”，谁用的模型更强，谁的效果就更好。

但到了 2025 年，事情开始起变化。大家发现，真正难的不是让模型“回答正确”，而是让模型“在一连串操作中保持正确”。一个 Agent 往往需要经历“理解任务 → 拆解步骤 → 调用工具 → 观察结果 → 修正方案 → 再次执行”这样的循环，每一步模型都可能出错，而且错误会不断累积。

GitHub 上这周最热的一批项目，几乎都在应对同一个问题：怎么把模型从“单次问答”里解放出来，放进一个可控、可观测、可恢复的执行框架中。

1.2 Harness、Skill、Agent 三者的关系

很多同学看到 DeepSeek Agent Harness、Codex Harness、Skill 这些词会有点懵，这里先做一个通俗类比。

可以把 Agent 想象成一个“实习生”，模型是他的大脑，而 Harness 是他所在的“工位和作业流程”。Harness 负责定义：

• 任务如何被分解。
• 模型每一步能调用哪些工具。
• 工具返回的结果如何回传给模型。
• 出错时如何重试或上报。

Skill 则像是“岗位手册”，或者说是预置的“技能包”。比如一个画图 Skill，就是一个写好的脚本加一段使用说明，Agent 下次遇到类似任务时，不需要重新发明轮子，直接调用这个 Skill 就能完成任务。

用公式来记就是：

Agent = 模型 + Harness（执行框架）+ 工具集 + Skill（技能包）+ 记忆

1.3 为什么 GitHub 是学习 Agent 开发最好的地方

这类项目迭代速度非常快，官方文档经常跟不上社区实践。GitHub 的优势在于，你能直接看到源代码、issue 里的踩坑记录，以及别人提交的真实用例。不过 GitHub 访问不稳定也是老问题，如果你频繁遇到连接超时，可以先检查本机网络出口是否正常，也可以通过 Gitee 的仓库导入功能拉到国内再浏览。需要说明的是，本文不讨论任何网络代理工具的使用方法，只关注代码层面的技术拆解。

2. 深入拆解 DeepSeek Agent Harness 的核心设计

2.1 Harness 解决的核心问题

DeepSeek Agent Harness 之所以热度高，是因为它把“如何让开源模型稳定地完成多步任务”这件事做成了工程框架。过去你让模型写代码，通常只能拿到一段静态代码；而在 Harness 框架下，模型可以反复执行“生成命令 → 查看输出 → 修改代码 → 重跑测试”的循环，直到任务完成为止。

一个典型的 Agent Harness 至少要包含四个模块：

1. 任务解析器：把用户的自然语言输入转换成内部任务描述。
2. 工具调度器：维护一个工具列表，模型通过特定格式请求调用工具。
3. 执行器：在本地或沙箱中执行工具命令，并捕获输出。
4. 循环控制器：判断任务是否结束，处理上下文截断和错误重试。

这其实和测试框架很像。写单元测试时，你用 pytest 管理用例、断言、setup 和 teardown；Agent Harness 则是用同样的工程思维管理“模型的思考过程和工具调用过程”。

2.2 DeepSeek 模型在 Harness 中的角色

DeepSeek 这类模型通常作为 Harness 的“推理内核”。目前 DeepSeek 官方提供了 OpenAI 兼容的 API 接口，这意味着你可以用标准openaiSDK 直接接入，也可以把手头的 Codex CLI 之类工具切换到 DeepSeek 的接口地址。

下面是一个最小接入示例，展示如何用 DeepSeek 模型完成一次带工具调用的对话：

# 文件路径：examples/deepseek_harness_basic.py """ 最小示例：演示如何通过 OpenAI 兼容接口接入 DeepSeek 模型。 说明： - 本文示例不对齐任何特定版本的 SDK，实际使用时请根据你的依赖版本调整。 - 模型名需要替换为你实际可用的模型 ID。 """ from openai import OpenAI client = OpenAI( api_key="你的 API Key", base_url="https://api.deepseek.com" ) response = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个擅长 Python 开发的助手，回答时给出完整可运行的代码。"}, {"role": "user", "content": "写一个函数，输入整数列表，返回所有偶数的平方之和，并附上简单测试。"} ], temperature=0.7, stream=False ) print(response.choices[0].message.content)

如果你只是想验证 DeepSeek API 是否能通，这个例子就够了。但真实 Harness 不会把工具调用结果简单拼接进对话，而是要经过“结构化抽取 → 执行 → 回填 → 再请求”的循环。

2.3 一个极简 Harness 的执行循环

为了理解这点，我们手写一个简化版 Harness。

# 文件路径：examples/simple_harness_loop.py """ 演示一个极简的 Agent 执行循环： 1. 用户输入任务 2. 模型选择调用哪个工具 3. 执行器运行工具 4. 把结果回传给模型 5. 模型判断是否完成 """ import json from openai import OpenAI # 定义一个除法工具 def divide(a: float, b: float) -> str: if b == 0: return "错误：除数不能为 0" return str(a / b) # 工具注册表：工具名 -> 函数 TOOLS = { "divide": divide, } client = OpenAI( api_key="你的 API Key", base_url="https://api.deepseek.com" ) def run_agent(prompt: str, max_rounds: int = 3): messages = [ {"role": "system", "content": "你是一个简单计算 Agent。如果需要工具，请按 JSON 格式输出：{\"name\": \"工具名\", \"args\": {}}，不要输出其他文字。"}, {"role": "user", "content": prompt}, ] for round_idx in range(max_rounds): response = client.chat.completions.create( model="deepseek-chat", messages=messages, temperature=0, ) content = response.choices[0].message.content.strip() # 尝试解析为工具调用 try: tool_call = json.loads(content) tool_name = tool_call["name"] tool_args = tool_call["args"] result = TOOLS[tool_name](**tool_args) # 把工具结果回传给模型 messages.append({"role": "assistant", "content": content}) messages.append({"role": "tool", "content": result, "name": tool_name}) print(f"[Round {round_idx}] 调用工具: {tool_name}({tool_args}) -> {result}") except json.JSONDecodeError: # 模型不再输出工具调用，说明任务完成 return content return "达到最大轮数，任务结束" if __name__ == "__main__": result = run_agent("请帮我计算 10 除以 4 的结果") print("最终回答：", result)

这个例子比较粗糙，但骨架是对的。生产中会在这个基础上增加：

• 工具返回的 token 控制，避免上下文无限膨胀。
• 异常重试机制，模型输出格式不合法时自动让模型修正。
• 沙箱执行，避免 Agent 在宿主机上执行危险命令。
• 审计日志，记录每一轮的模型输出、工具输入输出。

3. AI 画图 Skill 到底是怎么实现的

3.1 Skill 的最小结构

Skills 之所以流行，是因为它把“能力复用”从代码层面提升到了“描述 + 脚本 + 元数据”的层面。一个 Skill 通常包含：

• SKILL.md：告诉模型这个技能什么时候用、怎么用、参数是什么。
• 若干脚本：真正执行任务的可运行代码。
• requirements.txt或等价物：依赖声明。

当 Agent 收到一个“画一张春天的花园”的任务时，它会先检索 Skill 目录，匹配到“AI 画图 Skill”，读取SKILL.md，然后按说明调用脚本生成图片。

3.2 画图 Skill 完整示例

下面我们实现一个最简画图 Skill。它不依赖外部绘画 API，而是用 Python 的 Pillow 库生成图片，适合用来理解 Skill 的组装思路。

# 文件路径：skills/draw_skill/requirements.txt pillow>=10.0.0

# 文件路径：skills/draw_skill/SKILL.md # AI 画图 Skill ## 用途 当用户要求生成简单的几何图形、渐变背景或基础插画时使用。 此 Skill 不擅长生成写实照片。 ## 参数说明 - title: 图片标题，显示在底部 - color1: 起始颜色，格式为 RGB 元组 - color2: 结束颜色，格式为 RGB 元组 ## 输出 生成一张 800x600 的 PNG 图片，保存到 output 目录。

# 文件路径：skills/draw_skill/draw.py """ Simple drawing skill implemented with Pillow. Usage: python draw.py --title "Spring Garden" --color1 "135,206,250" --color2 "124,252,0" """ import argparse from PIL import Image, ImageDraw, ImageFilter def parse_args(): parser = argparse.ArgumentParser(description="Generate a gradient image with title") parser.add_argument("--title", type=str, default="Untitled") parser.add_argument("--color1", type=str, default="135,206,250") parser.add_argument("--color2", type=str, default="124,252,0") parser.add_argument("--output", type=str, default="output.png") return parser.parse_args() def hex_to_rgb(value: str) -> tuple: """将 '135,206,250' 字符串转为 RGB 元组。""" parts = [int(p.strip()) for p in value.split(",")] if len(parts) != 3: raise ValueError("颜色格式应为 r,g,b，例如 135,206,250") return tuple(parts) def create_gradient(width: int, height: int, color1: tuple, color2: tuple) -> Image.Image: """生成一个自上而下的渐变背景。""" base = Image.new("RGB", (1, height)) draw = ImageDraw.Draw(base) for y in range(height): ratio = y / max(height - 1, 1) r = int(color1[0] * (1 - ratio) + color2[0] * ratio) g = int(color1[1] * (1 - ratio) + color2[1] * ratio) b = int(color1[2] * (1 - ratio) + color2[2] * ratio) draw.line([(0, y), (0, y)], fill=(r, g, b)) return base.resize((width, height)) def add_title(image: Image.Image, title: str) -> Image.Image: """在图片底部添加白色标题。""" draw = ImageDraw.Draw(image) # 简单文本，不依赖中文字体文件时使用默认字体 text_width = 12 * len(title) x = (image.width - text_width) // 2 y = image.height - 60 draw.text((x, y), title, fill=(255, 255, 255)) return image def main(): args = parse_args() color1 = hex_to_rgb(args.color1) color2 = hex_to_rgb(args.color2) image = create_gradient(800, 600, color1, color2) image = add_title(image, args.title) image = image.filter(ImageFilter.GaussianBlur(1)) import os os.makedirs(os.path.dirname(args.output) or ".", exist_ok=True) image.save(args.output) print(f"图片已生成：{args.output}") if __name__ == "__main__": main()

运行方式：

python skills/draw_skill/draw.py \ --title "Spring Garden" \ --color1 "135,206,250" \ --color2 "124,252,0" \ --output output.png

这个 Skill 的亮点不在于画图效果，而在于它体现了工程结构：模型不需要理解 Pillow 的每个 API，只要读懂SKILL.md，就能正确组装参数并调用脚本。

3.3 怎么把 Skill 注册进 Agent

注册动作通常发生在 Harness 初始化阶段。Harness 会扫描指定目录下的 Skill 清单，把名称、描述、参数解析到 JSON Schema 中，然后注入到模型的 system prompt 或工具列表中。

# 文件路径：examples/skill_registry.py """ 如何将一个 Skill 脚本注册到 Agent 工具列表。 """ SKILLS = [ { "name": "draw_image", "description": "生成带渐变背景和标题的简单图片", "command": ["python", "skills/draw_skill/draw.py"], "parameters": { "type": "object", "properties": { "title": {"type": "string"}, "color1": {"type": "string"}, "color2": {"type": "string"}, }, "required": ["title"], }, } ] def get_tool_schemas(): """把 Skill 列表转成 OpenAI function calling 格式。""" tools = [] for skill in SKILLS: tools.append({ "type": "function", "function": { "name": skill["name"], "description": skill["description"], "parameters": skill["parameters"], } }) return tools if __name__ == "__main__": import json print(json.dumps(get_tool_schemas(), ensure_ascii=False, indent=2))

有了这段代码，你的 Agent 就能在对话中主动请求调用“draw_image”这个工具，再由 Harness 在本地执行对应的 Python 命令。

4. 自进化编程 Agent：让模型自己修自己的代码

4.1 什么是“自进化”编程 Agent

“自进化编程 Agent”听起来玄乎，拆开看其实是一个很经典的控制循环：

生成代码 -> 运行测试 -> 收集失败信息 -> 把失败信息反馈给模型 -> 模型修改代码 -> 再次运行测试

关键在于，反馈给模型的不是“代码写得不好”这种模糊评价，而是具体的测试失败堆栈、编译错误和被断言打倒的期望值。模型基于这些信号迭代，直到测试通过或达到最大轮数。

4.2 完整实现：一个自进化编码循环

# 文件路径：examples/self_evolving_agent.py """ 自进化编程 Agent 最小实现。 模型根据测试失败信息反复修改代码，直到全部通过。 """ import subprocess import tempfile import os from openai import OpenAI client = OpenAI( api_key="你的 API Key", base_url="https://api.deepseek.com" ) SYSTEM_PROMPT = """你是一名 Python 工程师。用户会给你任务描述，并附上测试代码。 你只能输出的代码，不要输出解释，代码需要能直接复制到文件里运行。""" def ask_model(messages: list) -> str: """调用 DeepSeek 模型，返回文本输出。""" response = client.chat.completions.create( model="deepseek-chat", messages=messages, temperature=0.2, ) return response.choices[0].message.content def run_test(code_path: str, test_path: str): """运行 pytest，返回 (returncode, stdout+stderr)。""" result = subprocess.run( ["python", "-m", "pytest", test_path, "-x", "--tb=short"], capture_output=True, text=True, cwd=os.path.dirname(code_path), ) return result.returncode, result.stdout + result.stderr def build_messages(task: str, test_code: str, feedback: str | None = None): messages = [{"role": "system", "content": SYSTEM_PROMPT}] user_content = f"任务：{task}\n\n测试代码：\n```python\n{test_code}\n```" if feedback: user_content += f"\n\n上一次运行测试失败，请根据错误信息修改代码：\n{feedback}" messages.append({"role": "user", "content": user_content}) return messages def main(): task = "实现一个函数 fib(n)，返回第 n 个斐波那契数，n 从 0 开始计数。" test_code = ''' import pytest from solution import fib def test_fib_start(): assert fib(0) == 0 assert fib(1) == 1 def test_fib_large(): assert fib(10) == 55 ''' with tempfile.TemporaryDirectory() as tmpdir: test_path = os.path.join(tmpdir, "test_solution.py") code_path = os.path.join(tmpdir, "solution.py") with open(test_path, "w", encoding="utf-8") as f: f.write(test_code) # 初始让模型生成代码 messages = build_messages(task, test_code) code = ask_model(messages) with open(code_path, "w", encoding="utf-8") as f: f.write(code) # 迭代循环 for i in range(4): returncode, output = run_test(code_path, test_path) print(f"\n===== 第 {i+1} 轮，测试通过: {returncode == 0} =====") if returncode == 0: print("自进化成功，最终代码：\n", code) return # 失败时把错误回传给模型 messages = build_messages(task, test_code, feedback=output) code = ask_model(messages) with open(code_path, "w", encoding="utf-8") as f: f.write(code) print("达到最大迭代轮数仍未通过测试，请人工介入。") if __name__ == "__main__": main()

这个脚本的运行结果通常能看到模型第一轮写出朴素递归，测试fib(10)时虽然通过，但性能较差；或者第一轮直接通过，不再需要进化。实际生产项目中，你可以把“测试失败信息”换成覆盖率报告、类型检查报告、代码风格报告，让 Agent 具备更全面的自我修正能力。

4.3 自进化编程的风险控制

这类 Agent 最大的风险在于“自动驾驶失控”。模型可能会为了通过测试而写死预期值，比如直接return 55。为了避免这种情况，建议：

• 测试用例要覆盖边界情况和随机输入。
• 用隐藏测试集做最终验证，不要让模型看到全部测试。
• 设置严格的最大迭代轮数和预算上限。
• 保留每一步的代码快照，方便回滚。

5. 团队工作台与可审计语义图谱

5.1 多 Agent 协作中的“团队工作台”

当一个 Agent 不够用时，就需要多个 Agent 协作。团队工作台项目通常提供三件事：

1. 任务黑板（Shared Board）：多个 Agent 共享任务状态和中间产物。
2. 消息总线：Agent 之间通过事件通信，而不是直接修改对方的内部状态。
3. 权限模型：每个 Agent 只能访问自己有权限的资源。

一个简化的多 Agent 协作模型可以这样描述：

用户请求 -> Planner Agent：拆解任务 -> Code Agent：写代码 -> Reviewer Agent：审查代码 -> Test Agent：跑测试 -> 汇总结果返回用户

如果中间某个 Agent 失败，团队工作台会通过重试、降级或告警来处理。

5.2 可审计语义图谱：给 Agent 的行为加上“记忆账本”

可审计语义图谱要解决的是 Agent 行为的“可解释性”和“可追踪性”。它把 Agent 的每一个重要动作转换成三元组（主语、谓语、宾语），存进知识图谱里。例如：

• Agent-A-调用了工具-divide
• divide-返回结果-2.5
• Agent-A-基于结果-生成最终答案

这样的图谱有几个实际用途：

• 复盘：任务失败时，能看到是哪一步决策导致最终结果偏差。
• 审计：合规场景下，可以证明某个结论的来源和推理链路。
• 记忆检索：新任务到来时，Agent 可以从图谱中检索相似经验的完整链路，而不是只检索零散文本。

5.3 用 NetworkX 构建一个最简语义审计图谱

# 文件路径：examples/semantic_audit_graph.py """ 使用 NetworkX 构建 Agent 行为审计图谱的最小示例。 """ import networkx as nx import json def build_audit_graph(): graph = nx.MultiDiGraph() # 记录 Agent 的行为事件 events = [ ("Agent-Code", "调用了工具", "search_web"), ("search_web", "返回结果", "结果片段 #1"), ("Agent-Code", "基于结果", "修改了文件 src/main.py"), ("Agent-Test", "执行测试", "pytest"), ("pytest", "测试结果", "2 passed, 1 failed"), ("Agent-Test", "上报失败", "Agent-Planner"), ] for subj, pred, obj in events: graph.add_edge(subj, obj, predicate=pred, timestamp="2025-01-01T10:00:00Z") return graph def export_audit_log(graph: nx.MultiDiGraph, output_path: str): """将图谱导出为可读的 JSON 审计日志。""" records = [] for subj, obj, data in graph.edges(data=True): records.append({ "subject": subj, "predicate": data.get("predicate"), "object": obj, "timestamp": data.get("timestamp"), }) with open(output_path, "w", encoding="utf-8") as f: json.dump(records, f, ensure_ascii=False, indent=2) print(f"审计日志已导出：{output_path}，共 {len(records)} 条事件") if __name__ == "__main__": graph = build_audit_graph() export_audit_log(graph, "audit_log.json")

运行后得到audit_log.json，这就是最基础的“决策审计溯源”。在真实系统中，三元组的抽取可以由另一个模型负责，存储放进图数据库（如 Neo4j），查询用 Cypher 也能完成。

6. 环境准备与快速上手清单

6.1 基础环境

本文的代码示例主要依赖 Python，建议环境如下：

• Python 3.10 或更高版本。
• openaiSDK（用于调用 DeepSeek API）。
• pillow（用于画图 Skill 示例）。
• pytest（用于自进化编程 Agent 测试）。
• networkx（用于语义图谱示例）。

安装命令：

pip install openai pillow pytest networkx

如果你遇到openai版本接口变化，以官方文档为准，重点掌握client.chat.completions.create这个入口，它目前仍是兼容性最好的调用方式。

6.2 DeepSeek API 准备

你需要一个 DeepSeek 开放平台的 API Key，然后在代码中替换base_url为https://api.deepseek.com。不同模型的 ID 可能调整，建议以官方控制台展示为准。也可以先用curl验证连通性：

curl https://api.deepseek.com \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的_API_Key" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}] }'

6.3 项目结构建议

学习阶段建议按下面的目录组织代码，便于后续扩展：

agent_learning/ ├── examples/ │ ├── deepseek_harness_basic.py │ ├── simple_harness_loop.py │ ├── skill_registry.py │ ├── self_evolving_agent.py │ └── semantic_audit_graph.py ├── skills/ │ └── draw_skill/ │ ├── SKILL.md │ ├── requirements.txt │ └── draw.py └── README.md

7. 常见问题与排查思路

8. 工程化落地时最容易踩的坑

8.1 别把 API Key 写进代码里

这是最基础也最容易被忽略的一点。上述示例为了方便展示，把api_key="你的 API Key"直接写在代码里了。真实项目务必使用环境变量或密钥管理服务：

import os client = OpenAI( api_key=os.environ.get("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" )

启动前执行：

export DEEPSEEK_API_KEY="你的_API_Key"

8.2 上下文窗口不是无限的

Agent 每执行一轮，把工具输出回填给模型，上下文就会变大。项目一旦跑起来，你会发现“上下文爆炸”比模型回答质量更棘手。常用策略包括：

• 对工具输出做长度限制，只回传前 2000 个字符。
• 超过阈值后，用模型对历史内容做摘要压缩。
• 引入向量数据库存长期记忆，少量相关片段动态注入。

8.3 Agent 能在本地执行命令，意味着风险

如果 Harness 允许模型执行 Shell 命令，等于把一个不可完全信任的“实习生”放进了你的服务器。务必要做到：

• 默认拒绝删除、格式化、关闭防火墙等危险命令。
• 所有执行操作放入容器或沙箱。
• 使用白名单工具列表，而不是黑名单。
• 执行前记录审计日志，执行后保留结果快照。

8.4 Skill 也要做版本管理

Skill 本质上是代码，必须纳入版本管理。SKILL.md里的描述如果和脚本实现不一致，模型会无意识地按描述调用接口，导致运行时参数错误。建议每个 Skill 自带测试脚本，合入主分支前至少验证一次“描述与实现一致”。

9. 从热点到生产力的学习路线建议

这周 GitHub 热点项目背后，其实是 Agent 工程化的三个趋势。第一个趋势是 Harness 成为标配，任何严肃的 Agent 项目都不会再让模型裸奔，而是用框架管理工具调用、重试、审计。第二个趋势是 Skill 生态开始量化，类似画图、写作、数据分析这类高频任务会沉淀成标准化插件。第三个趋势是“可观测、可审计”成为刚需，多 Agent 协作越复杂，越需要语义图谱和回滚机制来兜底。

如果你刚入门，建议按下面顺序动手：

1. 先跑通 DeepSeek API 的基础调用，理解消息结构。
2. 复现本文的迷你 Harness 循环，把工具注册、回传、重试吃透。
3. 写一个自己的 Skill，先不追求复杂，哪怕只是“获取当前时间”或“生成随机密码”。
4. 做一次自进化编程实验，让模型修复一个有单测的代码文件。
5. 最后把所有动作接入语义审计图谱，让每一步决策都有迹可循。

真正的 Agent 开发能力，靠读热点文章是学不来的。把今天的代码复制到本地，改一改参数和工具函数，跑通一次完整循环，你就能明显感受到“模型 + 工具循环”和“单次问答”的根本区别。环境差异和版本迭代确实会带来不少坑，但只要你把每个坑的现象、根因和修复方式记录下来，这一套技能就会越来越扎实。