Agent Harness、约束与工具路径

1. 核心判断

好的约束不是为了限制 AI，而是为了减少无效探索，让 AI 更快进入正确动作空间。

SOUL.md 这类文件如果只是放进上下文，本质上是软约束。它适合做人类可读的规范、审计依据和策略声明，但不能单独保证不访问 PII、不删除文件、不调用高危 API 或不泄露密钥。

真正可靠的约束需要落到执行层：

• 文件系统 sandbox。

• API allowlist / denylist。

• 权限审批。

• secret 隔离。

• 网络访问控制。

• 资源限制。

• 工具调用审计。

更准确的表达是：

SOUL.md 是策略声明，不是强制执行机制。
它需要 runtime、tool gateway 和 policy engine 配合，才能变成可靠的安全边界。

2. 搜索视角

无约束 agent 很像裸 DFS：它会沿着某条看起来可行的路径一路深入，但可能陷入无关分支、错误假设或循环尝试。

更好的 agent 应该像：

DFS + 剪枝 + 启发式排序 + 回溯 + 验证

对应关系：

Agent      = 搜索器
Goal       = 目标状态
State      = 当前世界状态 / 上下文状态
Tools      = 可扩展边
Tool call  = 沿着某条边走一步
Plan       = 从 State 到 Goal 的路径
Constraints = 剪枝条件
Memory     = visited set
Evaluator  = 验证函数
Approval   = 高风险边的人工判定

真正高效的 agent，不是想得更多，而是少搜索错误空间。

3. 工具是边

工具可以建模为从一个状态到另一个状态的有向边，并且每条边都有成本、前置条件和副作用。

read_file:
  precondition: path exists
  effect: context += file_content
  cost: tokens + time
  risk: low

delete_file:
  precondition: path exists
  effect: filesystem -= file
  cost: low
  risk: high
  requires_approval: true

run_tests:
  precondition: deps installed
  effect: confidence += test_result
  cost: time
  risk: low / medium

所以工具不是孤立能力，而是状态图里的可执行边。

4. Harness 是搜索控制器

Harness 的角色不是简单调用工具，而是帮助 agent 在巨大、动态、部分未知的状态图中找到一条足够好的路径。

它负责：

• 枚举当前可用工具。

• 根据约束剪枝。

• 根据成本、风险、收益排序。

• 执行工具调用。

• 观察状态变化。

• 判断是否接近目标。

• 必要时回溯或换策略。

• 在完成、失败、预算耗尽或需要人工输入时停止。

可以抽象为：

candidate_actions = policy(state, goal)
valid_actions = filter(candidate_actions, constraints)
next_action = rank(valid_actions, cost, risk, expected_gain)
new_state = execute(next_action)
score = evaluate(new_state, goal)

Harness 不一定能找到全局最优路径。真实目标通常是：

找到一条足够好、足够安全、成本可接受、可验证的路径。

5. 与复杂度的关系

Agent 执行不能直接等同于一个 NP 完全问题。

某些子问题可以是 NP-hard，甚至更难：

• 经典 planning：很多形式是 PSPACE-complete。

• constraint satisfaction：常见 NP-complete。

• scheduling / routing：常见 NP-hard。

• program synthesis：很多变体非常难，甚至不可判定。

• POMDP：部分可观测决策，复杂度更高。

但真实 agent 任务不是一个干净的判定问题，因为它包含自然语言目标、动态外部状态、不完整观测、工具副作用、不确定成本和不总是明确的验证函数。

更准确的总结是：

Agent 执行不是在求形式化 NP 完全问题的最优解，
而是在巨大、动态、部分未知的状态空间里，
用约束、启发式、验证器和工具执行，
寻找一条可行且足够好的路径。

6. 追踪性

追踪性可以理解为：最后的结果能倒查回来，知道它从哪里来、经过了哪些动作、为什么这么做。

它不需要记录所有 token 或完整思考过程，而是记录外部可观察的执行链：

Goal -> Step -> Tool Call -> Observation -> State Delta -> Next Decision -> Artifact

追踪性主要包含两类：

• 内容追踪：答案里的结论能追到来源材料。例如某个判断来自会话讨论、截图、本地笔记或飞书文档中的某一节。

• 行为追踪：最终状态能追到工具调用路径。例如先搜索本地仓库，再创建本地笔记，再搜索飞书，再创建飞书文档，最后读取校验。

真正有用的 trace 不是流水账，而是执行路径的有向图。除了记录时间顺序，还要记录因果关系：

因为本地没有 harness 目录
所以创建 docs/harness-agent-constraints.md

因为飞书搜索没有找到明确的 harness 知识库节点
所以创建新的飞书文档

因为创建后需要验证同步成功
所以 fetch 飞书文档确认内容完整

最小可用的事件结构可以是：

{
  "run_id": "run_20260603_001",
  "goal": "沉淀 harness 笔记并同步飞书",
  "event_id": "evt_004",
  "type": "tool_call",
  "tool": "lark.docs.create",
  "input_summary": {
    "title": "Agent Harness、约束与工具路径",
    "parent": "my_library"
  },
  "caused_by": ["evt_003"],
  "reason": "飞书搜索未找到明确的 harness 知识库节点，需要创建新文档",
  "constraint_checks": [
    "user_authorized_lark_docs_write",
    "not_high_risk_delete",
    "content_source_available"
  ],
  "result": {
    "status": "success",
    "artifact": "https://..."
  }
}

最小字段集合：

• goal：这次会话要达成什么。

• event_id：每个动作的唯一 ID。

• event_type：观察、决策、工具调用、验证、产物创建。

• caused_by：这个动作由哪些前置事件导致。

• reason：为什么做这个动作。

• tool 和 input_summary：用了什么工具，以及关键输入是什么。

• output_summary：关键输出是什么。

• state_delta：世界状态发生了什么变化。

• artifact_refs：文件、URL、PR、文档等产物。

• constraint_checks：哪些约束被检查或触发。

• timestamp：事件发生时间。

用前面的图模型说：

Trace = agent 从初始 State 走到 Goal 的路径记录

因此，harness 需要记录会话中的关键操作、状态变化、产物，以及它们之间的因果边。这样系统才能审计、回放、解释、回滚和优化 agent 的执行路径。

7. 类比区块链交易账本

Agent trace 有点像区块链里每笔交易都可追踪。

可以把 agent trace 理解成一种执行账本：

区块链交易：账户 A -> 账户 B，金额 X，交易哈希 H，前序区块 PrevHash
Agent trace：状态 A -> 状态 B，动作 X，事件 ID，前序事件 caused_by

相似点：

• 每次操作都有记录。

• 每条记录能追到前序记录。

• 记录之间形成链或 DAG。

• 最终状态可以倒推出由哪些步骤造成。

• 出问题时可以定位是哪一笔“交易”引入的。

差异也很重要：

区块链追踪的是资产状态变化。
Agent trace 追踪的是任务执行状态变化。

区块链更强调：

• 不可篡改。

• 共识。

• 去中心化。

• 全网可验证。

Agent harness 更强调：

• 可解释。

• 可审计。

• 可回放。

• 可回滚。

• 可优化。

• 可追责。

• 可做安全策略检查。

所以 agent trace 不一定需要真的上链，也不一定需要强共识。很多时候，普通数据库、事件日志、append-only log 或 hash chain 就够了。

更准确的类比是：

Agent trace = 面向 AI 执行过程的 transaction log

每次工具调用都像一笔交易：

{
  "event_id": "evt_007",
  "prev": ["evt_006"],
  "action": "lark.docs.update",
  "input_summary": "追加第 6 节追踪性",
  "state_delta": "飞书文档 revision 3 -> revision 4",
  "artifact": "https://...",
  "hash": "hash(event_content)"
}

如果想做得更强，可以加入：

• prev_hash：防止中间记录被悄悄改掉。

• state_hash：记录执行前后状态摘要。

• artifact_hash：记录文件或文档内容摘要。

• signature：证明是哪一个 agent、user 或 tool gateway 执行的。

• policy_result：证明当时哪些约束通过了。

因此，agent trace 的目的不是金融级不可篡改，而是让 AI 的执行路径从黑盒行动变成可检查的操作历史。这对 agent 系统非常关键。