程序员技术小站 - 最近更改 [zh-cn]

构建自己的Harness系统--基于Kimi2.5大模型

Admin — Wed, 08 Apr 2026 05:04:50 GMT

创建页面，内容为“本文基于前文的Harness系统原理介绍，实现了基于Kimi2.5大模型的简单agent模型，重点在于学习和了解Harness的系统的实现原理。同时也做到了国内大模型的开箱即用。<syntaxhighlight lang="python3" line="1"> #!/usr/bin/env python3 # Harness: all mechanisms combined -- the complete cockpit for the model. """ s_full.py - Full Reference Agent Capstone implementation combining every mechanism from s01-s11. Session s…”

显示更改

分类:AI

Admin — Wed, 08 Apr 2026 05:00:37 GMT

←上一版本		2026年4月8日 (三) 05:00的版本
第1行：		第1行：
			[[构建自己的Harness系统--基于Kimi2.5大模型]]

	[[多智能体协作实践：从单打独斗到团队作战（构建自己的AI Agent)]]		[[多智能体协作实践：从单打独斗到团队作战（构建自己的AI Agent)]]

多智能体协作实践：从单打独斗到团队作战（构建自己的AI Agent)

Admin — Mon, 23 Mar 2026 05:04:36 GMT

创建页面，内容为“<blockquote>"任务太大一个人干不完，要能分给队友" —— 持久化队友 + JSONL 邮箱。</blockquote>前面的子智能体是一次性的：生成、干活、返回摘要、消亡。没有身份，没有跨调用的记忆。真正的团队协作需要三样东西： # '''能跨多轮对话存活的持久智能体''' # '''身份和生命周期管理''' # '''智能体之间的通信通道''' == 一、团队架构 == <code>Teammate lifecycle…”

新页面

<blockquote>"任务太大一个人干不完，要能分给队友" —— 持久化队友 + JSONL 邮箱。</blockquote>前面的子智能体是一次性的：生成、干活、返回摘要、消亡。没有身份，没有跨调用的记忆。

真正的团队协作需要三样东西：

# '''能跨多轮对话存活的持久智能体'''
# '''身份和生命周期管理'''
# '''智能体之间的通信通道'''

== 一、团队架构 ==
<code>Teammate lifecycle:
spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN

Communication:
.team/
config.json <- 团队名册 + 状态
inbox/
alice.jsonl <- 追加式，读取即清空
bob.jsonl
lead.jsonl

+--------+ send("alice","bob","...") +--------+
| alice | -----------------------------> | bob |
| loop | bob.jsonl << {json_line} | loop |
+--------+ +--------+
^ |
| BUS.read_inbox("alice") |
+---- alice.jsonl -> read + drain ---------+</code>

== 二、核心组件 ==

=== 1. TeammateManager ===
通过 <code>config.json</code> 维护团队名册：
<code>class TeammateManager:
def __init__(self, team_dir: Path):
self.dir = team_dir
self.dir.mkdir(exist_ok=True)
self.config_path = self.dir / "config.json"
self.config = self._load_config()
self.threads = {}</code>

=== 2. 生成队友 ===
<code>spawn()</code> 创建队友并在线程中启动 Agent 循环：
<code>def spawn(self, name: str, role: str, prompt: str) -> str:
member = {
"name": name,
"role": role,
"status": "working"
}
self.config["members"].append(member)
self._save_config()

thread = threading.Thread(
target=self._teammate_loop,
args=(name, role, prompt),
daemon=True
)
thread.start()
return f"Spawned teammate '{name}' (role: {role})"</code>

=== 3. MessageBus ===
追加式 JSONL 收件箱：

* <code>send()</code> 追加一行
* <code>read_inbox()</code> 读取全部并清空

<code>class MessageBus:
def send(self, sender, to, content,
msg_type="message", extra=None):
msg = {
"type": msg_type,
"from": sender,
"content": content,
"timestamp": time.time()
}
if extra:
msg.update(extra)
with open(self.dir / f"{to}.jsonl", "a") as f:
f.write(json.dumps(msg) + "\n")

def read_inbox(self, name):
path = self.dir / f"{name}.jsonl"
if not path.exists():
return "[]"
msgs = [json.loads(l) for l in
path.read_text().strip().splitlines() if l]
path.write_text("") ''# drain''
return json.dumps(msgs, indent=2)</code>

=== 4. 队友循环 ===
每个队友在每次 LLM 调用前检查收件箱：
<code>def _teammate_loop(self, name, role, prompt):
messages = [{"role": "user", "content": prompt}]
for _ in range(50):
''# 检查收件箱''
inbox = BUS.read_inbox(name)
if inbox != "[]":
messages.append({
"role": "user",
"content": f"<inbox>{inbox}</inbox>"
})
messages.append({
"role": "assistant",
"content": "Noted inbox messages."
})

''# 调用 LLM''
response = client.messages.create(...)

if response.stop_reason != "tool_use":
break
''# 执行工具，追加结果...''

self._find_member(name)["status"] = "idle"</code>

== 三、试一试 ==
<code>cd learn-claude-code
python agents/s09_agent_teams.py</code>
试试这些 prompt：

# <code>Spawn alice (coder) and bob (tester). Have alice send bob a message.</code>
# <code>Broadcast "status update: phase 1 complete" to all teammates</code>
# <code>Check the lead inbox for any messages</code>

也可以使用快捷命令：

* <code>/team</code> 查看团队名册和状态
* <code>/inbox</code> 手动检查领导的收件箱

== 四、团队协作模式 ==

=== 模式 1：领导指派 ===
<code>Leader: Spawn alice (coder) and bob (reviewer)
Leader: Send alice "Implement user authentication"
Alice: (works on task)
Alice: Send leader "Task complete, needs review"
Leader: Send bob "Review alice's auth implementation"
Bob: (reviews code)
Bob: Send leader "Review complete, 2 issues found"</code>

=== 模式 2：广播通知 ===
<code>Leader: Broadcast "Phase 1 complete, starting Phase 2"
Alice: (receives broadcast)
Bob: (receives broadcast)</code>

=== 模式 3：点对点协作 ===
<code>Alice: Send bob "Can you check the API spec?"
Bob: (checks spec)
Bob: Send alice "Spec says POST /api/v1/users"</code>

== 五、进阶：自治智能体 ==
s09 的队友只在被明确指派时才动。领导得给每个队友写 prompt。

在 s11 中，我们将升级到'''自治智能体'''：<blockquote>"队友自己看看板，有活就认领"</blockquote>队友自己扫描任务看板，认领没人做的任务，做完再找下一个。

=== 空闲阶段轮询 ===
<code>def _idle_poll(self, name, messages):
for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):
time.sleep(POLL_INTERVAL)

''# 检查收件箱''
inbox = BUS.read_inbox(name)
if inbox:
messages.append({
"role": "user",
"content": f"<inbox>{inbox}</inbox>"
})
return True

''# 扫描未认领任务''
unclaimed = scan_unclaimed_tasks()
if unclaimed:
claim_task(unclaimed[0]["id"], name)
messages.append({
"role": "user",
"content": f"<auto-claimed>Task #{unclaimed[0]['id']}</auto-claimed>"
})
return True

return False ''# timeout -> shutdown''</code>

=== 自组织工作流 ===
<code>1. 创建任务看板
2. 生成多个队友
3. 队友自动扫描看板
4. 认领可执行任务
5. 完成后继续扫描
6. 60秒空闲后自动关闭</code>
'''不需要领导逐个分配，真正的自组织。'''

== 六、试一试（自治版） ==
<code>cd learn-claude-code
python agents/s11_autonomous_agents.py</code>
试试这些 prompt：

# <code>Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.</code>
# <code>Spawn a coder teammate and let it find work from the task board itself</code>
# <code>Create tasks with dependencies. Watch teammates respect the blocked order.</code>

快捷命令：

* <code>/tasks</code> 查看带 owner 的任务看板
* <code>/team</code> 监控谁在工作、谁在空闲

== 七、设计哲学 ==
'''多模型，通过文件协调。'''

这是 Harness 工程的精髓：

* 不共享内存，避免竞态条件
* 通过文件系统通信，天然持久化
* JSONL 格式简单、可扩展
* 每个 Agent 独立运行，松耦合

这种模式不仅适用于编程，也适用于：

* '''客服团队'''：不同专长的 Agent 处理不同类型的工单
* '''研究团队'''：文献检索、实验设计、数据分析分工协作
* '''创意团队'''：头脑风暴、方案评估、细节执行分层处理

== 八、总结 ==
从单 Agent → 子 Agent → 多 Agent 团队 → 自治 Agent，Harness 的复杂度逐步提升，但核心原则不变：

'''Harness 提供机制，模型决定策略。'''

* Harness 提供 spawn、send、inbox 工具
* 模型决定什么时候生成队友、给谁发消息
* 模型决定认领哪个任务、如何协作

'''优秀的 Harness 工程师是环境设计师'''——创造能让智能高效协作的基础设施。
----''Bash 就够了。真正的 Agent 是宇宙所需要的全部。''

分类:AI

Admin — Mon, 23 Mar 2026 05:04:07 GMT

←上一版本		2026年3月23日 (一) 05:04的版本
（未显示同一用户的1个中间版本）
第1行：		第1行：
			[[多智能体协作实践：从单打独斗到团队作战（构建自己的AI Agent)]]

	[[任务系统与依赖管理：让目标超越对话(构建自己的AI Agent）]]		[[任务系统与依赖管理：让目标超越对话(构建自己的AI Agent）]]

任务系统与依赖管理：让目标超越对话(构建自己的AI Agent）

Admin — Mon, 23 Mar 2026 05:02:35 GMT

创建页面，内容为“<blockquote>"大目标要拆成小任务，排好序，记在磁盘上" —— 文件持久化的任务图，为多 Agent 协作打基础。</blockquote>前面的 TodoManager 是内存中的扁平清单：没有顺序、没有依赖、状态只有做完没做完。真实的目标是有结构的——任务 B 依赖任务 A，任务 C 和 D 可以并行，任务 E 要等 C 和 D 都完成。没有显式的关系，Agent 分不清什么能做、什么被卡…”

新页面

<blockquote>"大目标要拆成小任务，排好序，记在磁盘上" —— 文件持久化的任务图，为多 Agent 协作打基础。</blockquote>前面的 TodoManager 是内存中的扁平清单：没有顺序、没有依赖、状态只有做完没做完。

真实的目标是有结构的——任务 B 依赖任务 A，任务 C 和 D 可以并行，任务 E 要等 C 和 D 都完成。

没有显式的关系，Agent 分不清什么能做、什么被卡住、什么能同时跑。

== 一、从清单到图 ==
我们需要把扁平清单升级为'''持久化到磁盘的任务图'''。
<code>.tasks/
task_1.json {"id":1, "status":"completed"}
task_2.json {"id":2, "blockedBy":[1], "status":"pending"}
task_3.json {"id":3, "blockedBy":[1], "status":"pending"}
task_4.json {"id":4, "blockedBy":[2,3], "status":"pending"}

任务图 (DAG):
+----------+
+--> | task 2 | --+
| | pending | |
+----------+ +----------+ +--> +----------+
| task 1 | | task 4 |
| completed| --> +----------+ +--> | blocked |
+----------+ | task 3 | --+ +----------+
| pending |
+----------+

顺序: task 1 必须先完成, 才能开始 2 和 3
并行: task 2 和 3 可以同时执行
依赖: task 4 要等 2 和 3 都完成
状态: pending -> in_progress -> completed</code>
这个任务图是后续所有机制的协调骨架：后台执行、多 Agent 团队、工作区隔离都读写这同一个结构。

== 二、核心能力 ==
任务图随时回答三个问题：

# '''什么可以做？''' —— 状态为 <code>pending</code> 且 <code>blockedBy</code> 为空的任务
# '''什么被卡住？''' —— 等待前置任务完成的任务
# '''什么做完了？''' —— 状态为 <code>completed</code> 的任务，完成时自动解锁后续任务

== 三、核心机制 ==

=== 1. TaskManager ===
每个任务一个 JSON 文件，支持 CRUD + 依赖图：
<code>class TaskManager:
def __init__(self, tasks_dir: Path):
self.dir = tasks_dir
self.dir.mkdir(exist_ok=True)
self._next_id = self._max_id() + 1

def create(self, subject, description=""):
task = {
"id": self._next_id,
"subject": subject,
"status": "pending",
"blockedBy": [],
"blocks": [],
"owner": ""
}
self._save(task)
self._next_id += 1
return json.dumps(task, indent=2)</code>

=== 2. 依赖解除 ===
完成任务时，自动将其 ID 从其他任务的 <code>blockedBy</code> 中移除：
<code>def _clear_dependency(self, completed_id):
for f in self.dir.glob("task_*.json"):
task = json.loads(f.read_text())
if completed_id in task.get("blockedBy", []):
task["blockedBy"].remove(completed_id)
self._save(task)</code>

=== 3. 状态变更 + 依赖关联 ===
<code>update</code> 处理状态转换和依赖边：
<code>def update(self, task_id, status=None,
add_blocked_by=None, add_blocks=None):
task = self._load(task_id)
if status:
task["status"] = status
if status == "completed":
self._clear_dependency(task_id)
self._save(task)</code>

=== 4. 工具集成 ===
四个任务工具加入调度映射：
<code>TOOL_HANDLERS = {
''# ...基础工具...''
"task_create": lambda **kw: TASKS.create(kw["subject"]),
"task_update": lambda **kw: TASKS.update(
kw["task_id"], kw.get("status")
),
"task_list": lambda **kw: TASKS.list_all(),
"task_get": lambda **kw: TASKS.get(kw["task_id"]),
}</code>

== 四、实际工作流程 ==
<code>1. 创建任务
task_create: "Setup project"
task_create: "Write code"
task_create: "Write tests"
task_create: "Deploy"

2. 设置依赖
task_update: task 2, add_blocked_by=[1]
task_update: task 3, add_blocked_by=[1]
task_update: task 4, add_blocked_by=[2,3]

3. 查看可执行任务
task_list -> [task 1] (pending, no blockedBy)

4. 开始执行
task_update: task 1, status="in_progress"
# ... work ...
task_update: task 1, status="completed"
# 自动解锁 task 2 和 3

5. 并行执行
task_update: task 2, status="in_progress"
task_update: task 3, status="in_progress"
# ... work ...
task_update: task 2, status="completed"
task_update: task 3, status="completed"
# 自动解锁 task 4

6. 完成
task_update: task 4, status="completed"</code>

== 五、试一试 ==
<code>cd learn-claude-code
python agents/s07_task_system.py</code>
试试这些 prompt：

# <code>Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.</code>
# <code>List all tasks and show the dependency graph</code>
# <code>Complete task 1 and then list tasks to see task 2 unblocked</code>
# <code>Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse</code>

== 六、与 TodoManager 的区别 ==
{| class="wikitable"
!特性
!TodoManager (s03)
!TaskManager (s07)
|-
|存储
|内存
|磁盘 (JSON 文件)
|-
|结构
|扁平清单
|依赖图 (DAG)
|-
|依赖
|无
|<code>blockedBy</code> + <code>blocks</code>
|-
|并行
|不支持
|支持
|-
|持久化
|重启丢失
|跨会话保存
|-
|适用场景
|单次会话快速清单
|复杂多步目标
|}
从 s07 起，任务图是多步工作的默认选择。s03 的 Todo 仍可用于单次会话内的快速清单。

== 七、设计哲学 ==
'''持久化任务比任何一次对话都长命。'''

这是 Harness 工程的核心原则：

* 对话会结束，但目标可能延续
* 上下文可能被压缩，但任务状态始终完整
* 多个 Agent 可以协作同一个任务图
* 重启后可以从断点继续

== 八、进阶应用 ==
任务系统是以下高级功能的基础：

* '''后台执行 (s08)'''：任务在后台运行，Agent 继续思考
* '''Agent 团队 (s09+)'''：多个 Agent 协作处理任务图
* '''自治 Agent (s11)'''：Agent 自己扫描看板、认领任务
* '''工作区隔离 (s12)'''：每个任务在自己的目录执行

'''没有任务系统，就没有真正的多 Agent 协作。'''
----''Bash 就够了。真正的 Agent 是宇宙所需要的全部。''

'''延伸阅读'''：learn-claude-code 开源项目，12 个渐进式教程，完整教授 Harness 工程。

分类:AI

Admin — Mon, 23 Mar 2026 05:02:04 GMT

←上一版本		2026年3月23日 (一) 05:02的版本
（未显示同一用户的1个中间版本）
第1行：		第1行：
			[[任务系统与依赖管理：让目标超越对话(构建自己的AI Agent）]]

	[[子智能体与上下文隔离：保持思维清晰的关键]]		[[子智能体与上下文隔离：保持思维清晰的关键]]

子智能体与上下文隔离：保持思维清晰的关键

Admin — Mon, 23 Mar 2026 05:00:00 GMT

创建页面，内容为“<blockquote>"大任务拆小，每个小任务干净的上下文" —— 子智能体用独立 messages[]，不污染主对话。</blockquote>随着 Agent 工作，messages 数组越来越胖。每次读文件、跑命令的输出都永久留在上下文里。 '''"这个项目用什么测试框架？"''' 这个问题可能需要读 5 个文件，但父智能体只需要一个词：'''"pytest"'''。如何把探索的细节隔离，只把结论带回？ ==…”

新页面

<blockquote>"大任务拆小，每个小任务干净的上下文" —— 子智能体用独立 messages[]，不污染主对话。</blockquote>随着 Agent 工作，messages 数组越来越胖。每次读文件、跑命令的输出都永久留在上下文里。

'''"这个项目用什么测试框架？"''' 这个问题可能需要读 5 个文件，但父智能体只需要一个词：'''"pytest"'''。

如何把探索的细节隔离，只把结论带回？

== 一、问题：上下文膨胀 ==
想象这个场景：

父 Agent 正在做大型重构，上下文里已经累积了：

* 20 个文件的读取结果
* 10 次测试运行输出
* 5 次 Git 状态检查
* 各种中间文件的 diff

现在它想知道：'''" utils.py 里的 <code>parse_data</code> 函数是做什么的？"'''

为此它需要：

# 读取 utils.py
# 查看相关依赖
# 分析函数逻辑
# 返回结论

这些探索过程会进一步膨胀父 Agent 的上下文，稀释真正重要的信息。

== 二、解决方案：子智能体 ==
<code>Parent agent Subagent
+------------------+ +------------------+
| messages=[...] | | messages=[] | <-- fresh
| | dispatch | |
| tool: task | ----------> | while tool_use: |
| prompt="..." | | call tools |
| | summary | append results |
| result = "..." | <---------- | return last text |
+------------------+ +------------------+

Parent context stays clean. Subagent context is discarded.</code>
父智能体有一个 <code>task</code> 工具。子智能体运行自己的循环，只有最终文本返回给父智能体。

== 三、核心机制 ==

=== 1. 工具分离 ===
父智能体拥有所有基础工具 + <code>task</code>：
<code>PARENT_TOOLS = CHILD_TOOLS + [
<nowiki> </nowiki> {
<nowiki> </nowiki> "name": "task",
<nowiki> </nowiki> "description": "Spawn a subagent with fresh context.",
<nowiki> </nowiki> "input_schema": {
<nowiki> </nowiki> "type": "object",
<nowiki> </nowiki> "properties": {"prompt": {"type": "string"}},
<nowiki> </nowiki> "required": ["prompt"],
<nowiki> </nowiki> }
<nowiki> </nowiki> },
]</code>
子智能体拥有除 <code>task</code> 外的所有基础工具（禁止递归生成）。

=== 2. 独立循环 ===
子智能体以 <code>messages=[]</code> 启动，运行自己的循环：
<code>def run_subagent(prompt: str) -> str:
sub_messages = [{"role": "user", "content": prompt}]
for _ in range(30): ''# 安全限制''
response = client.messages.create(
model=MODEL, system=SUBAGENT_SYSTEM,
messages=sub_messages,
tools=CHILD_TOOLS, max_tokens=8000,
)
sub_messages.append({
"role": "assistant",
"content": response.content
})
if response.stop_reason != "tool_use":
break
results = []
for block in response.content:
if block.type == "tool_use":
handler = TOOL_HANDLERS.get(block.name)
output = handler(**block.input)
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(output)[:50000],
})
sub_messages.append({"role": "user", "content": results})

''# 只返回摘要文本''
return "".join(
b.text for b in response.content if hasattr(b, "text")
) or "(no summary)"</code>

=== 3. 上下文隔离 ===
子智能体可能跑了 30+ 次工具调用，但'''整个消息历史直接丢弃'''。父智能体收到的只是一段摘要文本，作为普通 <code>tool_result</code> 返回。

== 四、使用场景 ==

=== 场景 1：信息检索 ===
<code>父 Agent：这个项目用什么测试框架？
↓
子 Agent（独立上下文）：
- 读取 pytest.ini
- 读取 setup.py
- 检查测试目录结构
- 分析依赖
↓
返回："pytest"</code>
父 Agent 的上下文保持干净，只有结论。

=== 场景 2：多文件分析 ===
<code>父 Agent：分析所有 Python 文件的依赖关系
↓
子 Agent：
- 遍历所有 .py 文件
- 提取 import 语句
- 构建依赖图
- 生成报告
↓
返回：精简的依赖关系摘要</code>

=== 场景 3：代码生成 ===
<code>父 Agent：创建一个数据处理模块
↓
子 Agent：
- 设计 API
- 实现核心函数
- 添加错误处理
- 编写测试
↓
返回：模块完成确认 + 文件路径</code>

== 五、试一试 ==
<code>cd learn-claude-code
python agents/s04_subagent.py</code>
试试这些 prompt：

# <code>Use a subtask to find what testing framework this project uses</code>
# <code>Delegate: read all .py files and summarize what each one does</code>
# <code>Use a task to create a new module, then verify it from here</code>

观察父 Agent 如何派发子任务，子 Agent 独立工作，最后只返回简洁的结果。

== 六、对比无隔离 vs 有隔离 ==
{| class="wikitable"
!场景
!无子智能体
!有子智能体
|-
|探索性任务
|上下文膨胀，主任务迷失
|探索细节隔离，主任务清晰
|-
|多文件分析
|所有文件内容留在上下文
|只保留分析结论
|-
|长对话
|后期上下文窗口溢出
|定期清理，保持高效
|}

== 七、进阶：递归与层级 ==
本文的子智能体是单层的。更复杂的系统可以支持：

* '''递归子智能体'''：子智能体也可以派发孙智能体
* '''层级架构'''：父-子-孙三级结构，每层有不同职责
* '''并行子智能体'''：同时派发多个子任务，聚合结果

但要注意：'''层级越深，协调成本越高'''。对于多数场景，单层子智能体已经足够。

== 八、Harness 层的职责 ==
'''守护模型的思维清晰度'''——这是 Harness 的核心职责之一。

* 子智能体隔离是机制
* 模型决定什么时候用、用来做什么
* Harness 保证隔离的执行

这种设计模式不仅适用于编程 Agent，也适用于任何需要复杂推理的场景：

* '''研究 Agent'''：主 Agent 协调，子 Agent 深入具体领域
* '''客服 Agent'''：主 Agent 处理对话，子 Agent 查询知识库
* '''创意 Agent'''：主 Agent 把控方向，子 Agent 探索具体方案

'''好的 Harness 像一个好的工作环境——提供清晰的边界，让智能高效运转。'''
----''Bash 就够了。真正的 Agent 是宇宙所需要的全部。''

分类:AI

Admin — Mon, 23 Mar 2026 04:59:34 GMT

←上一版本		2026年3月23日 (一) 04:59的版本
第1行：		第1行：
			[[子智能体与上下文隔离：保持思维清晰的关键]]

	[[让AI Agent不再迷失：规划的艺术]]		[[让AI Agent不再迷失：规划的艺术]]

让AI Agent不再迷失：规划的艺术

Admin — Mon, 23 Mar 2026 04:58:23 GMT

创建页面，内容为“<blockquote>"没有计划的 Agent 走哪算哪" —— 先列步骤再动手，完成率翻倍。</blockquote>在前面文章中，我们构建了最简单的 Agent 循环。今天我们来解决一个实际问题：'''多步任务中，Agent 会丢失进度'''。重复做过的事、跳步、跑偏——对话越长越严重。一个 10 步重构可能做完 1-3 步就开始即兴发挥，因为 4-10 步已经被挤出注意力了。 == 一、问题：长…”

新页面

<blockquote>"没有计划的 Agent 走哪算哪" —— 先列步骤再动手，完成率翻倍。</blockquote>在前面文章中，我们构建了最简单的 Agent 循环。今天我们来解决一个实际问题：'''多步任务中，Agent 会丢失进度'''。

重复做过的事、跳步、跑偏——对话越长越严重。一个 10 步重构可能做完 1-3 步就开始即兴发挥，因为 4-10 步已经被挤出注意力了。

== 一、问题：长对话中的迷失 ==
想象一下这个场景：

你让 Agent 重构一个项目：

# 添加类型注解
# 补充文档字符串
# 添加主函数保护
# 运行测试验证
# 提交更改

Agent 开始工作，读取文件、修改代码、运行测试...但到第 4 步时，上下文已经被工具结果填满，系统提示的影响力逐渐被稀释。Agent "忘记"了还有第 5 步，或者以为第 2 步还没做，又做了一遍。

'''这不是模型的错，是 Harness 的问题。'''

== 二、解决方案：TodoManager ==
给 Agent 一个带状态的待办清单，并强制它定期更新进度。
<code>+--------+ +-------+ +---------+
| User | ---> | LLM | ---> | Tools |
| prompt | | | | + todo |
+--------+ +---+---+ +----+----+
^ |
| tool_result |
+----------------+
|
+-----------+-----------+
| TodoManager state |
| [ ] task A |
| [>] task B <- doing |
| [x] task C |
+-----------------------+
|
if rounds_since_todo >= 3:
inject <reminder> into tool_result</code>

== 三、核心机制 ==

=== 1. 状态管理 ===
同一时间只允许一个 <code>in_progress</code>：
<code>class TodoManager:
def update(self, items: list) -> str:
validated, in_progress_count = [], 0
for item in items:
status = item.get("status", "pending")
if status == "in_progress":
in_progress_count += 1
validated.append({
"id": item["id"],
"text": item["text"],
"status": status
})
if in_progress_count > 1:
raise ValueError("Only one task can be in_progress")
self.items = validated
return self.render()</code>
'''"同时只能有一个 in_progress"''' 强制顺序聚焦。

=== 2. 工具集成 ===
<code>todo</code> 工具和其他工具一样加入调度映射：
<code>TOOL_HANDLERS = {
''# ...基础工具...''
"todo": lambda **kw: TODO.update(kw["items"]),
}</code>

=== 3. 提醒机制（Nag Reminder） ===
模型连续 3 轮以上不调用 <code>todo</code> 时，系统主动注入提醒：
<code>if rounds_since_todo >= 3 and messages:
last = messages[-1]
if last["role"] == "user" and isinstance(last.get("content"), list):
last["content"].insert(0, {
"type": "text",
"text": "<reminder>Update your todos.</reminder>",
})</code>
'''问责压力'''——你不更新计划，系统就追着你问。

== 四、实际效果 ==
对比无规划 vs 有规划的 Agent：
{| class="wikitable"
!场景
!无规划
!有规划
|-
|10步重构
|经常重复或遗漏步骤
|按顺序完成，状态清晰
|-
|多文件编辑
|上下文混乱
|每一步聚焦单一目标
|-
|长对话
|后期偏离主题
|始终围绕待办清单
|}

== 五、完整示例 ==
<code>''# Agent 首先创建计划''
todo.update([
{"id": 1, "text": "读取并分析当前代码", "status": "in_progress"},
{"id": 2, "text": "添加类型注解", "status": "pending"},
{"id": 3, "text": "补充文档字符串", "status": "pending"},
{"id": 4, "text": "添加主函数保护", "status": "pending"},
{"id": 5, "text": "运行测试验证", "status": "pending"},
])

''# 完成第一步后更新''
todo.update([
{"id": 1, "text": "读取并分析当前代码", "status": "completed"},
{"id": 2, "text": "添加类型注解", "status": "in_progress"},
''# ...其他不变''
])

''# 如此继续，直到全部完成''</code>

== 六、试一试 ==
<code>cd learn-claude-code
python agents/s03_todo_write.py</code>
试试这些 prompt：

# <code>Refactor the file hello.py: add type hints, docstrings, and a main guard</code>
# <code>Create a Python package with __init__.py, utils.py, and tests/test_utils.py</code>
# <code>Review all Python files and fix any style issues</code>

观察 Agent 如何先创建待办清单，然后一步步执行，定期更新进度。

== 七、设计哲学 ==
'''Harness 层应该提供规划结构，但不替模型画航线。'''

* Harness 提供 Todo 工具和管理器
* 模型自己决定任务是什么、如何排序
* Harness 强制"一次只做一件事"和"定期更新"
* 但不规定具体怎么做

这种'''约束与自由'''的平衡是关键：

* 太松：模型迷失在细节中
* 太紧：模型变成脚本执行器

== 八、进阶思考 ==
TodoManager 是内存中的扁平清单，适合单次会话。对于更复杂的场景，我们需要：

* '''依赖关系'''：任务 B 依赖任务 A
* '''并行执行'''：任务 C 和 D 可以同时进行
* '''持久化'''：跨会话保存任务状态

这将在后续文章中介绍，进化成完整的'''任务系统（Task System）'''。

但即使在那之前，简单的 Todo 已经能大幅提升 Agent 的可靠性。'''先列步骤再动手，完成率翻倍'''。
----''Bash 就够了。真正的 Agent 是宇宙所需要的全部。''

分类:AI

Admin — Mon, 23 Mar 2026 04:57:58 GMT

←上一版本		2026年3月23日 (一) 04:57的版本
第1行：		第1行：
			[[让AI Agent不再迷失：规划的艺术]]

	[[30行代码构建你的第一个AI Agent]]		[[30行代码构建你的第一个AI Agent]]

30行代码构建你的第一个AI Agent

Admin — Mon, 23 Mar 2026 04:56:27 GMT

创建页面，内容为“<blockquote>"One loop & Bash is all you need" —— 一个工具 + 一个循环 = 一个智能体。</blockquote>在前一篇文章中，我们理解了 Agent 的本质：'''Agent 是模型，Harness 是框架'''。今天，让我们动手构建最简单的 Agent Harness。只需要 30 行 Python 代码，你就能拥有一个真正能与现实世界交互的 AI Agent。 == 一、问题：模型被困在象牙塔里 == 大语言模型能推理代码，但…”

新页面

<blockquote>"One loop & Bash is all you need" —— 一个工具 + 一个循环 = 一个智能体。</blockquote>在前一篇文章中，我们理解了 Agent 的本质：'''Agent 是模型，Harness 是框架'''。今天，让我们动手构建最简单的 Agent Harness。

只需要 30 行 Python 代码，你就能拥有一个真正能与现实世界交互的 AI Agent。

== 一、问题：模型被困在象牙塔里 ==
大语言模型能推理代码，但碰不到真实世界——不能读文件、跑测试、看报错。

没有循环，每次工具调用你都得手动把结果粘回去。'''你自己就是那个循环。'''

这既不优雅，也不可扩展。我们需要让模型能够自主地与工具交互，形成一个闭环。

== 二、解决方案：Agent 循环 ==
核心思想很简单：
<code>+--------+ +-------+ +---------+
| User | ---> | LLM | ---> | Tool |
| prompt | | | | execute |
+--------+ +---+---+ +----+----+
^ |
| tool_result |
+----------------+
(loop until stop_reason != "tool_use")</code>
一个退出条件控制整个流程。循环持续运行，直到模型不再调用工具。

== 三、工作原理 ==

=== 1. 用户 prompt 作为第一条消息 ===
<code>messages.append({"role": "user", "content": query})</code>

=== 2. 将消息和工具定义一起发给 LLM ===
<code>response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)</code>

=== 3. 追加助手响应，检查 stop_reason ===
<code>messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
return</code>
如果模型没有调用工具，任务完成。

=== 4. 执行每个工具调用，收集结果，作为 user 消息追加，回到第 2 步 ===
<code>results = []
for block in response.content:
if block.type == "tool_use":
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})</code>

== 四、完整代码 ==
组装为一个完整函数：
<code>def agent_loop(query):
messages = [{"role": "user", "content": query}]
while True:
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
messages.append({"role": "assistant", "content": response.content})

if response.stop_reason != "tool_use":
return

results = []
for block in response.content:
if block.type == "tool_use":
output = run_bash(block.input["command"])
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output,
})
messages.append({"role": "user", "content": results})</code>
'''不到 30 行，这就是整个智能体。'''

后面所有复杂的机制（规划、子 Agent、任务系统、团队协作）都是在这个循环上叠加的——'''循环本身始终不变'''。

== 五、核心组件 ==
{| class="wikitable"
!组件
!作用
|-
|Agent loop
|<code>while True</code> + <code>stop_reason</code> 检查
|-
|Tools
|从 <code>bash</code> 开始，单一工具足矣
|-
|Messages
|累积式消息列表，记录完整对话历史
|-
|Control flow
|<code>stop_reason != "tool_use"</code> 决定退出
|}

== 六、试一试 ==
<code>git clone <nowiki>https://github.com/shareAI-lab/learn-claude-code</nowiki>
cd learn-claude-code
python agents/s01_agent_loop.py</code>
试试这些 prompt：

# <code>Create a file called hello.py that prints "Hello, World!"</code>
# <code>List all Python files in this directory</code>
# <code>What is the current git branch?</code>
# <code>Create a directory called test_output and write 3 files in it</code>

你会看到 Agent 自主地调用 Bash 工具，执行命令，读取结果，然后决定下一步做什么，直到任务完成。

== 七、关键洞察 ==
'''模型决定什么时候调用工具，什么时候停止。'''

代码只是执行模型要求做的事。这个循环属于 Agent，机制属于 Harness。

这个看似简单的循环是所有现代 AI Agent（包括 Claude Code、Devin、OpenCode）的基础。无论 Agent 多复杂，核心都是这个循环：
<code>messages[] --> LLM --> response
|
stop_reason == "tool_use"?
/ \
yes no
| |
执行工具返回文本
追加结果
循环回去 ----------> messages[]</code>

== 八、下一步 ==
这只是一个开始。在这个基础上，我们将逐步添加：

* '''工具扩展'''：不只 Bash，还有文件读写、代码编辑、搜索
* '''规划能力'''：让 Agent 列步骤再执行
* '''子 Agent'''：大任务拆小，上下文隔离
* '''知识加载'''：按需注入领域知识
* '''上下文压缩'''：处理长对话
* '''任务系统'''：持久化的目标管理
* '''团队协作'''：多 Agent 并行工作

但在那之前，'''先掌握这个循环'''。理解它，你就理解了 Agent 的本质。
----''Bash 就够了。真正的 Agent 是宇宙所需要的全部。''

'''延伸阅读'''：learn-claude-code 开源项目，12 个渐进式教程，从简单循环到隔离式自主执行。

分类:AI

Admin — Mon, 23 Mar 2026 04:55:49 GMT

←上一版本		2026年3月23日 (一) 04:55的版本
第1行：		第1行：
			[[30行代码构建你的第一个AI Agent]]

	'''[[什么是真正的 AI Agent？模型即智能体的深度解析]]'''		'''[[什么是真正的 AI Agent？模型即智能体的深度解析]]'''

首页

Admin — Mon, 23 Mar 2026 04:54:30 GMT

←上一版本		2026年3月23日 (一) 04:54的版本
第3行：		第3行：
	[[分类:Linux操作系统]]		[[分类:Linux操作系统]]
	[[分类:算法]]		[[分类:算法]]

			[[什么是真正的 AI Agent？模型即智能体的深度解析]]

	[[软件工程师必知的软件架构模式]]		[[软件工程师必知的软件架构模式]]

什么是真正的 AI Agent？模型即智能体的深度解析

Admin — Mon, 23 Mar 2026 04:53:38 GMT

显示更改

什么是真正的 AI Agent？模型即智能体的深度解析

Admin — Mon, 23 Mar 2026 04:50:49 GMT

创建页面，内容为“> "Agent 是模型，不是框架，不是提示链，不是拖拽式工作流。" 过去一年，AI 领域最热的词莫过于 "Agent"。但当你听到这个词时，你想到的是什么？是 LangChain 的流程图？是扣子（Coze）的节点编排？还是各种 "AI Agent 开发平台" 的可视化界面？如果你的答案是以上任何一种，那么这篇文章将彻底改变你的认知。 '''## 一、Agent 是什么？''' 让我们回到…”

新页面

> "Agent 是模型，不是框架，不是提示链，不是拖拽式工作流。"

过去一年，AI 领域最热的词莫过于 "Agent"。但当你听到这个词时，你想到的是什么？

是 LangChain 的流程图？是扣子（Coze）的节点编排？还是各种 "AI Agent 开发平台" 的可视化界面？

如果你的答案是以上任何一种，那么这篇文章将彻底改变你的认知。

'''## 一、Agent 是什么？'''

让我们回到源头。

'''**Agent（智能体）是一个神经网络**'''——Transformer、RNN，或者任何通过梯度更新训练出来的函数。它通过数十亿次在动作序列数据上的训练，学会了感知环境、推理目标并采取行动。

Agent 这个词在 AI 领域一直就是这个意思：

- '''**人类是 Agent**''' —— 生物神经网络，经过数百万年进化训练，通过感官感知世界，通过大脑推理，通过身体行动

- '''**DQN 是 Agent**''' —— 2013 年 DeepMind 的单个神经网络，仅凭原始像素和游戏分数，学会了玩 7 款雅达利游戏，超越所有先前算法

- '''**OpenAI Five 是 Agent**''' —— 五个神经网络，通过 10 个月内 45,000 年的自我对战，击败 Dota 2 世界冠军

- '''**AlphaStar 是 Agent**''' —— 在《星际争霸 II》中达到宗师段位，超越 90,000 名玩家中的前 0.15%

这些里程碑共享同一个真理：'''**"Agent" 从来不是周围的代码，Agent 永远是模型本身。**'''

'''## 二、Agent 不是什么？'''

不幸的是，"Agent" 这个词已经被一整个提示工程产业劫持了。

拖拽式工作流构建器。低代码 "AI Agent" 平台。提示链编排库。它们共享同一个幻觉：认为用 if-else 分支、节点图和硬编码路由逻辑把 LLM API 调用串联起来，就是在 "构建 Agent"。

'''**这不是在构建 Agent，这是在搭建鲁布·戈德堡机械**'''——一种过度工程化、脆弱的程序化规则管道，把一个 LLM 塞进作为华丽文本补全节点的位置。

提示工程 "Agent" 是不会训练模型的人的幻想。他们试图通过堆砌程序化逻辑来暴力破解智能——庞大的规则树、节点图、提示链瀑布——祈祷足够多的胶水代码能以某种方式涌现出自主行为。

'''**这是死路一条**'''：脆弱、不可扩展、从根本上无法泛化。这是 GOFAI（经典人工智能）的现代复活——几十年前该领域就已经抛弃的符号规则系统，现在只是喷了一层 LLM 的漆。

'''## 三、心智转变：从"开发 Agent"到开发 Harness'''

当有人说"我在开发 Agent"时，他们只可能指两件事之一：

'''### 1. 训练模型'''

通过强化学习、微调、RLHF 或其他基于梯度的方法调整权重。收集任务过程数据——真实领域中感知、推理和动作的实际序列——并用它来塑造模型行为。

这是 DeepMind、OpenAI、腾讯 AI Lab 和 Anthropic 在做的事。这是最严格意义上的 Agent 开发。

'''### 2. 构建 Harness（控制框架）'''

编写代码，给模型一个在特定领域运作的环境。这是大多数人（包括你）在做的事，也是本文的重点。

'''**Harness = 工具 + 知识 + 观察 + 动作接口 + 权限**'''

- '''**工具**'''：文件 I/O、Shell、网络、数据库、浏览器

- '''**知识**'''：产品文档、领域参考资料、API 规范、风格指南

- '''**观察**'''：Git diff、错误日志、浏览器状态、传感器数据

- '''**动作**'''：CLI 命令、API 调用、UI 交互

- '''**权限**'''：沙箱、审批工作流、信任边界

'''**模型做决定，Harness 执行。**'''

'''**模型推理，Harness 提供上下文。**'''

'''**模型是司机，Harness 是车。**'''

'''## 四、Harness 工程师的真正工作'''

如果你正在阅读这篇文章，你很可能是 Harness 工程师——而这是一件很有力量的事。

你的真正工作是：

'''**1. 实现工具**'''

给 Agent 手。文件读写、Shell 执行、API 调用、浏览器控制、数据库查询。每个工具都是 Agent 可以在环境中采取的动作。设计它们时要原子化、可组合、描述清晰。

'''**2. 整理知识**'''

给 Agent 领域专长。产品文档、架构决策记录、风格指南、监管要求。按需加载（而不是预加载）。Agent 应该知道有什么可用，并在需要时拉取。

'''**3. 管理上下文**'''

给 Agent 干净的记忆。子 Agent 隔离防止噪音泄漏。上下文压缩防止历史压垮。任务系统让目标超越单次对话。

'''**4. 控制权限**'''

给 Agent 边界。沙箱文件访问。破坏性操作需要审批。强制执行 Agent 和外部系统之间的信任边界。这是安全工程与 Harness 工程的交汇点。

'''**5. 收集任务过程数据**'''

Agent 在你的 Harness 中执行的每个动作序列都是训练信号。真实部署中的感知-推理-动作痕迹是微调下一代 Agent 模型的原材料。

'''**你不是在编写智能，你是在构建智能栖息的世界。**'''

这个世界的质量——Agent 能多么清晰地感知、能多么精确地行动、可用知识有多丰富——直接决定了智能能多么有效地表达自己。

构建伟大的 Harness，Agent 会完成剩下的事。

'''## 五、Claude Code：Harness 工程的杰作'''

为什么我们要专门研究 Claude Code？

因为 Claude Code 是我们见过的最优雅、最完全实现的 Agent Harness。不是因为某个巧妙的技巧，而是因为它'''**不做什么**'''：它不试图成为 Agent，它不强加刚性工作流，它不用精心设计的决策树来质疑模型。

它给模型提供工具、知识、上下文管理和权限边界——然后让开。

看看 Claude Code 的本质：

```

Claude Code = 一个 Agent 循环

+ 工具（Bash、Read、Write、Edit、Glob、Grep、Browser...）

+ 按需技能加载

+ 上下文压缩

+ 子 Agent 生成

+ 带依赖图的任务系统

+ 带异步邮箱的团队协调

+ 用于并行执行的工作区隔离

+ 权限治理

```

就这些。这就是整个架构。

每个组件都是 Harness 机制——为 Agent 栖息而构建的世界的一部分。Agent 本身？是 Claude。一个由 Anthropic 训练、基于人类全部推理和代码的模型。Harness 并没有让 Claude 变聪明，Claude 本来就聪明。Harness 给了 Claude 手、眼睛和工作空间。

这就是 Claude Code 是理想教学对象的原因：它展示了当你信任模型并专注于 Harness 工程时会发生什么。

'''## 六、愿景：让宇宙中充满真正的 Agent'''

这不仅仅是关于编程 Agent。

'''**每个领域，只要人类执行复杂、多步骤、需要判断的工作，Agent 就可以在正确的 Harness 下运作。**'''

本文中的模式是通用的：

- '''**房地产管理 Agent**''' = 模型 + 房产传感器 + 维护工具 + 租户沟通

- '''**农业 Agent**''' = 模型 + 土壤/天气数据 + 灌溉控制 + 作物知识

- '''**酒店运营 Agent**''' = 模型 + 预订系统 + 客户渠道 + 设施 API

- '''**医学研究 Agent**''' = 模型 + 文献搜索 + 实验室仪器 + 协议文档

- '''**制造业 Agent**''' = 模型 + 生产线传感器 + 质量控制 + 物流

- '''**教育 Agent**''' = 模型 + 课程知识 + 学生进度 + 评估工具

循环永远相同。工具改变。知识改变。权限改变。'''**Agent——模型——泛化。**'''

每个阅读本文的 Harness 工程师都在学习远远超越软件工程的模式。你在学习构建智能化、自动化未来的基础设施。每个在真实领域部署的精心设计的 Harness，都是 Agent 可以感知、推理和行动的另一个地方。

'''**先从车间开始。然后是农场、医院、工厂。然后是城市。然后是整个星球。**'''

---

''*Bash 就够了。真正的 Agent 是宇宙所需要的全部。*''

分类:AI

Admin — Mon, 23 Mar 2026 04:50:01 GMT

←上一版本		2026年3月23日 (一) 04:50的版本
第1行：		第1行：
			'''[[什么是真正的 AI Agent？模型即智能体的深度解析]]'''

	[[Transformer架构如何驱动现代大语言模型：深入解析AI核心技术]]		[[Transformer架构如何驱动现代大语言模型：深入解析AI核心技术]]

	[[大语言模型评估指南]]		[[大语言模型评估指南]]