78 lines
2.3 KiB
Markdown
78 lines
2.3 KiB
Markdown
---
|
||
title: "Minimum Viable Harness"
|
||
type: concept
|
||
tags:
|
||
- "harness-engineering"
|
||
- "agentic-ai"
|
||
- "quick-start"
|
||
sources:
|
||
- "Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog"
|
||
last_updated: 2026-04-20
|
||
---
|
||
|
||
## Overview
|
||
Minimum Viable Harness——Day 1 即可构建的 4 个核心组件，使 Agent 能够优雅失败，为后续增加智能赢得权利。
|
||
|
||
## The 4 Components
|
||
|
||
### 1. `state.json`
|
||
单一结构化文件跟踪任务状态——如果进程死亡，可以从上次停止的地方继续。
|
||
```json
|
||
{
|
||
"task_id": "report-001",
|
||
"steps": {
|
||
"fetch_competitor_a": "COMPLETED",
|
||
"fetch_competitor_b": "IN_PROGRESS",
|
||
"compare": "PENDING"
|
||
},
|
||
"last_updated": "2026-04-20T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
### 2. Retry Wrapper
|
||
每个工具调用包装 try/catch，至少一次自动重试 + 指数退避：
|
||
```python
|
||
def tool_call_with_retry(func, max_attempts=3):
|
||
for attempt in range(max_attempts):
|
||
try:
|
||
return func()
|
||
except (TimeoutError, APIError) as e:
|
||
if attempt < max_attempts - 1:
|
||
sleep(exponential_backoff(attempt))
|
||
else:
|
||
raise
|
||
```
|
||
|
||
### 3. Schema Validator
|
||
每个 LLM 输出在接收前必须通过 JSON Schema 验证。格式不符触发重试，不触发崩溃：
|
||
```python
|
||
def validate_and_retry(llm_output, schema):
|
||
try:
|
||
validated = jsonschema.validate(llm_output, schema)
|
||
return validated
|
||
except ValidationError:
|
||
return retry_with_error_feedback(llm_output, schema)
|
||
```
|
||
|
||
### 4. Tool Output Truncation
|
||
每个工具 payload 硬性上限固定 token 预算——context window 内的静默截断是幻觉最常见原因之一：
|
||
```python
|
||
MAX_TOOL_TOKENS = 3000 # 保守上限
|
||
|
||
def truncate_tool_output(raw_output, max_tokens=MAX_TOOL_TOKENS):
|
||
tokens = encode(raw_output)
|
||
if len(tokens) > max_tokens:
|
||
return decode(tokens[:max_tokens]) + "\n[TRUNCATED]"
|
||
return raw_output
|
||
```
|
||
|
||
## Philosophy
|
||
> 你可以忍受不完美的提示词。你可以忍受天真的工具集成。但是你无法忍受一个失败时破坏自己状态或静默吞噬错误的 Agent。
|
||
|
||
## Source
|
||
- [[Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog]]
|
||
|
||
## See Also
|
||
- [[Harness-Engineering]] — 完整学科框架
|
||
- [[7-Layer-Harness-Stack]] — 完整 7 层实现
|