Harness Engineering

Intake pipeline：User Request → Intent Classification → Risk Pre-Assessment → Parameter Extraction → Missing Parameter Gate → Task Structuring → Boundary Setting → Approval Decision → Structured Task

风险预分级由系统根据请求特征自动判定（写入操作、外部系统、生产环境、敏感数据、范围模糊、不可逆），不采信用户声明。缺失影响安全或业务结果的参数时必须反问用户。

基于 OpenTelemetry 的 trace + metric + log 三位一体，加入 agent 特有维度（token cost、tool call、permission check、human approval）。

关键指标：

推荐技术栈：Langfuse（tracing + agent graphs + sessions + dashboard + prompt management）、Prometheus + Grafana（指标聚合）、ELK / Loki（日志）。至少两个 dashboard：运营 dashboard（实时任务状态）和复盘 dashboard（7/30天趋势、失败原因分布）。

上下文层的目标不是"给模型更多信息"，而是给模型正确、可追溯、可压缩的信息。

上下文分区：

System Policy     永久规则，短而硬
Developer Policy  应用规则、团队规范
Task Context      当前用户任务
Retrieved Context 检索资料
Working State     当前步骤状态
Tool Results      工具调用结果
Memory            长期偏好或历史经验
Output Schema     输出格式

设计原则：

• 每段上下文带 source id
• 检索结果按可信度和相关性排序
• 大资料先摘要再进入 prompt
• 工具结果与检索结果分开
• 过期资料要标注时间
• 冲突资料不能静默合并

反模式：

• 把所有文档塞进 system prompt
• 把长期记忆当事实来源
• 没有来源 ID 的事实写入正式结果
• 不区分用户偏好和客观事实

工具层的目标是给 agent 动作能力，同时限制副作用。

工具定义模板：

{
  "name": "tool_name",
  "description": "工具做什么，不做什么",
  "input_schema": {},
  "output_schema": {},
  "permission_level": "L1",
  "side_effect": "none|filesystem_write|external_api|production_change",
  "timeout_sec": 30,
  "retry": 1,
  "approval_required": false,
  "audit": true
}

工具包装原则：

• 不暴露原始 shell，优先暴露具体动作
• SQL 默认 read-only，写库必须审批
• 文件写入默认写草稿区
• 外部 API 调用必须记录 request id
• 浏览器访问和本地控制面要隔离

工具输出原则：

{
  "ok": true,
  "artifact_id": "draft_001",
  "summary": "创建草稿",
  "path": "drafts/note.md",
  "diff": "...",
  "warnings": []
}

执行层的目标是让 agent 任务可恢复、可重试、可复盘。

任务状态：

created → planning → running → waiting_for_approval → verifying → completed / failed / rolled_back

Step 记录：

{
  "step_id": "extract_claims",
  "status": "completed",
  "input_artifacts": ["source_001"],
  "output_artifacts": ["claims_001"],
  "tool_calls": [],
  "verification": "pass"
}

Retry 策略：

白名单化（不自动接入所有 MCP server）：

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "permission_level": "L2",
      "allowed_paths": ["/workspace/drafts", "/workspace/notes"],
      "forbidden_paths": ["/workspace/secrets", "/workspace/production"]
    }
  }
}

权限检查在 MCP Client 层：

1. MCP server 是否在白名单？
2. 调用的 tool 是否在允许列表？
3. 参数是否在允许范围内？
4. 是否需要审批？
5. 是否超过频率限制？
6. 是否在变更窗口内？

不要一开始做完全自由 agent。推荐固定流程 + 局部自主：

Intake → Classify → Extract → Synthesize → Verify → Approval → Commit

每一步都有输入、输出、失败处理。不要暴露底层任意权限，推荐工具：searchDocs、readSource、createDraft、patchDraft、runValidation、requestApproval、commitDraft。每个工具都定义 name、description、input/output schema、permission level、side effect、timeout、audit。

上下文包：policy、task、retrieved_context、memory、tool_results、output_schema。每段资料必须有 source_id、title、url/path、timestamp、trust_level。

默认策略：读资料自动、写草稿自动、修改正式文件展示 diff 后确认、删除/批量改名强确认、发布/部署/发邮件必须人工确认。

按应用选验证：

每次 run 保存：run_id、task、status、steps、artifacts、tool_calls、verification、rollback。每次写操作保存 before snapshot、patch diff、after snapshot、rollback command。

至少记录：trace、tool calls、latency、token cost、model output、verification result、human approval result、failure reason。建立 eval set：简单任务、复杂任务、边界任务、恶意输入、历史失败任务。

推荐技术栈：前端 Next.js/React；后端 FastAPI/NestJS；Agent OpenAI SDK/LangGraph/Claude Agent SDK/Temporal；存储 Postgres/pgvector/Redis；观测 OpenTelemetry/Langfuse；沙箱 Docker/E2B/Firecracker。