大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



最近学习了这个项目，很经典，对于agent以及harness又有了更近一步的了解。

项目地址：https://github.com/shareAI-lab/learn-claude-code/blob/main/README-zh.md

模型对于agent很重要，但是工程设计对于agent也同等重要，本质还是看对于系统设计的理解。

经典观点总结如下：

1.Agent 产品 = 模型 + Harness

Harness 是 agent 在特定领域工作所需要的一切：

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

Tools: 文件读写、Shell、网络、数据库、浏览器 Knowledge: 产品文档、领域资料、API 规范、风格指南 Observation: git diff、错误日志、浏览器状态、传感器数据 Action: CLI 命令、API 调用、UI 交互 Permissions: 沙箱隔离、审批流程、信任边界 

模型做决策。Harness 执行。模型做推理。Harness 提供上下文。模型是驾驶者。Harness 是载具。

2.Claude Code 本质：

Claude Code = 一个 agent loop

 + 工具 (bash, read, write, edit, glob, grep, browser...) + 按需 skill 加载 + 上下文压缩 + 子 agent 派生 + 带依赖图的任务系统 + 异步邮箱的团队协调 + worktree 隔离的并行执行 + 权限治理

3.agent模式

 THE AGENT PATTERN

 ================= User --> messages[] --> LLM --> response | stop_reason == "tool_use"? / yes no | | execute tools return text append results loop back -----------------> messages[] 这是最小循环。每个 AI Agent 都需要这个循环。 模型决定何时调用工具、何时停止。 代码只是执行模型的要求。 本仓库教你构建围绕这个循环的一切 -- 让 agent 在特定领域高效工作的 harness。

“One loop & Bash is all you need” – 一个工具 + 一个循环 = 一个 Agent。

Harness 层: 循环 – 模型与真实世界的第一道连接。

+——–+ +——-+ +———+ | User | —> | LLM | —> | Tool | | prompt | | | | execute | +——–+ +—+—+ +—-+—-+

 ^ | | tool_result | +----------------+ (loop until stop_reason != "tool_use")

“加一个工具, 只加一个 handler” – 循环不用动, 新工具注册进 dispatch map 就行。

Harness 层: 工具分发 – 扩展模型能触达的边界。

+——–+ +——-+ +——————+ | User | —> | LLM | —> | Tool Dispatch | | prompt | | | | { | +——–+ +—+—+ | bash: run_bash |

 ^ | read: run_read | | | write: run_wr | +-----------+ edit: run_edit | tool_result | } | +------------------+ 

The dispatch map is a dict: {tool_name: handler_function}. One lookup replaces any if/elif chain.

“没有计划的 agent 走哪算哪” – 先列步骤再动手, 完成率翻倍。

Harness 层: 规划 – 让模型不偏航, 但不替它画航线。

+——–+ +——-+ +———+ | User | —> | LLM | —> | Tools | | prompt | | | | + todo | +——–+ +—+—+ +—-+—-+

 ^ | | tool_result | +----------------+ | +-----------+-----------+ | TodoManager state | | [ ] task A | | [>] task B <- doing | | [x] task C | +-----------------------+ | if rounds_since_todo >= 3:

“大任务拆小, 每个小任务干净的上下文” – Subagent 用独立 messages[], 不污染主对话。

Harness 层: 上下文隔离 – 守护模型的思维清晰度。

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.

“用到什么知识, 临时加载什么知识” – 通过 tool_result 注入, 不塞 system prompt。

Harness 层: 按需知识 – 模型开口要时才给的领域专长。

System prompt (Layer 1 – always present): +————————————–+ | You are a coding agent. | | Skills available: | | - git: Git workflow helpers | ~100 tokens/skill | - test: Testing best practices | +————————————–+

When model calls load_skill(“git”): +————————————–+ | tool_result (Layer 2 – on demand): | | | | Full git workflow instructions… | ~2000 tokens | Step 1: … | | | +————————————–+

“上下文总会满, 要有办法腾地方” – 三层压缩策略, 换来无限会话。

Harness 层: 压缩 – 干净的记忆, 无限的会话。

Every turn: +——————+ | Tool call result | +——————+

 | v 

Layer 1: micro_compact Replace tool_result > 3 turns old with “[Previous: used {tool_name}]”

 | v 

[Check: tokens > 50000?] | | no yes | | v v continue [Layer 2: auto_compact]

 Save transcript to .transcripts/ LLM summarizes conversation. Replace all messages with [summary]. | v [Layer 3: compact tool] Model calls compact explicitly. Same summarization as auto_compact.

“大目标要拆成小任务, 排好序, 记在磁盘上” – 文件持久化的任务图, 为多 agent 协作打基础。

Harness 层: 持久化任务 – 比任何一次对话都长命的目标。

把扁平清单升级为持久化到磁盘的任务图。每个任务是一个 JSON 文件, 有状态、前置依赖 (blockedBy)。任务图随时回答三个问题:

• 什么可以做? – 状态为 pending 且 blockedBy 为空的任务。
• 什么被卡住? – 等待前置任务完成的任务。
• 什么做完了? – 状态为 completed 的任务, 完成时自动解锁后续任务。

.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

“慢操作丢后台, agent 继续想下一步” – 后台线程跑命令, 完成后注入通知。

Harness 层: 后台执行 – 模型继续思考, harness 负责等待。

Main thread Background thread +—————–+ +—————–+ | agent loop | | subprocess runs | | … | | … | | [LLM call] <—+——- | enqueue(result) | | ^drain queue | +—————–+ +—————–+

Timeline: Agent –[spawn A]–[spawn B]–[other work]—-

 | | v v [A runs] [B runs] (parallel) | | +-- results injected before next LLM call --+

“任务太大一个人干不完, 要能分给队友” – 持久化队友 + JSONL 邮箱。

Harness 层: 团队邮箱 – 多个模型, 通过文件协调。

Teammate lifecycle: spawn -> WORKING -> IDLE -> WORKING -> … -> SHUTDOWN

Communication: .team/

config.json <- team roster + statuses inbox/ alice.jsonl <- append-only, drain-on-read bob.jsonl lead.jsonl +--------+ send("alice","bob","...") +--------+ | alice | -----------------------------> | bob | | loop | bob.jsonl << {json_line} | loop | +--------+ +--------+ ^ | | BUS.read_inbox("alice") | +---- alice.jsonl -> read + drain ---------+

“队友之间要有统一的沟通规矩” – 一个 request-response 模式驱动所有协商。

Harness 层: 协议 – 模型之间的结构化握手。

Shutdown Protocol Plan Approval Protocol ================== ======================

Lead Teammate Teammate Lead | | | | |–shutdown_req–>| |–plan_req——>| | {req_id:“abc”} | | {req_id:“xyz”} | | | | | |<–shutdown_resp-| |<–plan_resp—–| | {req_id:“abc”, | | {req_id:“xyz”, | | approve:true} | | approve:true} |

Shared FSM: [pending] –approve–> [approved] [pending] –reject—> [rejected]

Trackers: shutdown_requests = } plan_requests = {req_id: {from, plan, status}}

“队友自己看看板, 有活就认领” – 不需要领导逐个分配, 自组织。

Harness 层: 自治 – 模型自己找活干, 无需指派。

Teammate lifecycle with idle cycle:

+——-+ | spawn | +—+—+

| v 

+——-+ tool_use +——-+ | WORK | <————- | LLM | +—+—+ +——-+

| | stop_reason != tool_use (or idle tool called) v 

+——–+ | IDLE | poll every 5s for up to 60s +—+—-+

| +---> check inbox --> message? ----------> WORK | +---> scan .tasks/ --> unclaimed? -------> claim -> WORK | +---> 60s timeout ----------------------> SHUTDOWN 

Identity re-injection after compression: if len(messages) <= 3:

messages.insert(0, identity_block)

“各干各的目录, 互不干扰” – 任务管目标, worktree 管目录, 按 ID 绑定。

Harness 层: 目录隔离 – 永不碰撞的并行执行通道。

Control plane (.tasks/) Execution plane (.worktrees/) +——————+ +————————+ | task_1.json | | auth-refactor/ | | status: in_progress <——> branch: wt/auth-refactor | worktree: “auth-refactor” | task_id: 1 | +——————+ +————————+ | task_2.json | | ui-login/ | | status: pending <——> branch: wt/ui-login | worktree: “ui-login” | task_id: 2 | +——————+ +————————+

 | index.json (worktree registry) events.jsonl (lifecycle log) 

State machines: Task: pending -> in_progress -> completed Worktree: absent -> active -> removed | kept

按照原工程中总结下来，彻彻底底的系统设计，分布式协同，协议，异步等，要想设计好agent系统还是主要看系统工程能力。