# Agent Harness 配套实践

十五篇正文以同一份虚构订单报告串联原理、实战和四个开源项目。代码包含中文说明，区分模拟模型、真实文件动作和可选模型调用。
本轮没有执行示例、安装依赖、测试、构建、模型调用、启动服务或预览。以下命令供读者使用，不是已运行记录。

## 正文入口

- [Agent Harness 是什么：模型之外，谁在推动任务完成](/posts/agent_runtime/6.harness/01-harness-and-agent-loop/)
- [指令与 Skill 怎样生效：从规则文件到一次模型请求](/posts/agent_runtime/6.harness/02-instructions-and-skills/)
- [Workspace 怎样设计：让输入、修改和交付物都有明确位置](/posts/agent_runtime/6.harness/03-workspace-and-artifacts/)
- [Harness 怎样控制执行：工具、命令、反馈与停止条件](/posts/agent_runtime/6.harness/04-execution-and-feedback/)
- [Sandbox 为什么必要：文件、进程、网络与资源怎样隔离](/posts/agent_runtime/6.harness/05-sandbox-boundaries/)
- [权限与凭证怎样分配：让一次动作只获得需要的能力](/posts/agent_runtime/6.harness/06-permissions-and-credentials/)
- [怎样判断任务真的完成：Artifact、Verifier 与修复循环](/posts/agent_runtime/6.harness/07-verification-and-completion/)
- [长任务怎样持续推进：计划、进度记录、快照与恢复](/posts/agent_runtime/6.harness/08-progress-and-resume/)
- [子 Agent 怎样协作：委派、隔离、并行与结果合并](/posts/agent_runtime/6.harness/09-delegation-and-isolation/)
- [生产中的 Harness 怎样设计：从单进程到可管理的任务系统](/posts/agent_runtime/6.harness/10-production-harness/)
- [从头实现一个 Harness：把指令、工具、工作区与验证串起来](/posts/agent_runtime/6.harness/11-harness-in-practice/)
- [读懂 Pi Agent：一个精简的 Coding Harness 怎样工作](/posts/agent_runtime/6.harness/12-learning-from-pi/)
- [读懂 Deep Agents：规划、文件与子 Agent 怎样组成工作系统](/posts/agent_runtime/6.harness/13-learning-from-deepagents/)
- [读懂 DeepSeek Harness：怎样用插件构建 Agent 运行环境](/posts/agent_runtime/6.harness/14-learning-from-deepseek-harness/)
- [读懂 AgentScope Java Harness：工作区、Skill 与会话状态怎样连接](/posts/agent_runtime/6.harness/15-learning-from-agentscope/)

## 核心文件与运行

Python 3.11+，标准库，无需安装第三方包。将以下文件放在同一目录：

- [contracts.py](python/contracts.py)：教学事实、Schema 和内容摘要。
- [verifier.py](python/verifier.py)：字段、类型、来源与政策校验。
- [runtime_core.py](python/runtime_core.py)：工具入口、工作区、累计预算、恢复与导出。
- [harness_demo.py](python/harness_demo.py)：固定错误与修复轨迹。

```bash
# 新任务必须使用不存在的路径；不会覆盖已有普通目录。
python harness_demo.py /tmp/order-harness-demo --pause-after-draft
# 使用同一路径恢复，读取候选后重新验证，最后导出。
python harness_demo.py /tmp/order-harness-demo
```

输入固定为 A1042 已签收十天、质量未核验、政策 P7-v2。第一次故意写 paid，恢复后修正为 delivered，
运费结论保持 pending_verification。这个行为由驱动代码预设，不是模型实测输出。

工作区会保留 inputs、outputs、export、manifest.json 和 state.json。完成后自行管理保留与清理。
目录应由可信单进程独占；没有 OS 沙箱、多文件事务、多 Worker 租约、生产身份认证或真实上传。

## 独立机制

- [instruction_manifest.py](python/instruction_manifest.py)：显式任务分类与指令清单，依赖 contracts。
- [workspace_manifest.py](python/workspace_manifest.py)：查看已有目录清单，依赖核心文件，参数为工作区路径。
- [permission_gate.py](python/permission_gate.py)：可信审批记录、参数绑定与撤权，依赖 contracts，不执行上传。
- [feedback_budget.py](python/feedback_budget.py)：重复失败与单进程额度，依赖 contracts。
- [delegation_contract.py](python/delegation_contract.py)：两个确定性检查并行，依赖 contracts 和 verifier，不创建模型子 Agent。

这些文件可在准备好依赖的同目录用 `python 文件名.py` 运行。工作区查看器需要提供已有任务路径。

## 可选真实模型入口

[model_driver.py](python/model_driver.py)复用核心文件，另需 instruction_manifest。配置自己的 ANTHROPIC_API_KEY 和 HARNESS_MODEL，
使用 `python model_driver.py /tmp/order-harness-model-demo` 运行。它发送真实 Claude Messages 请求，会产生费用。
本轮未调用；没有自动重试、流式处理或硬墙钟取消。工具与模型调用额度跨恢复累计，模型未完成交付时明确报未完成。

## 开源解读与扩展

- [Pi 查询扩展](typescript/pi/order-tool.ts)、[Pi bash 拦截](typescript/pi/block-bash.ts)：需要固定提交对应的 TypeScript 依赖与 Pi 环境。
- [DeepSeek 工具插件](typescript/deepseek/order-tool.ts)、[结果观察插件](typescript/deepseek/tool-observer.ts)、[最小注册配置](typescript/deepseek/cordis.yml)：注册层示例，配置不包含模型循环。
- [Deep Agents 示例](python/deepagents_report.py)：需要独立安装固定源码依赖，运行会调用模型。提交结果为进程内存记录。
- [Java 工程](java/README.md)：保留 2.0.1 历史接入，详细区分正文快照版本。

精确提交、源码路径和环境说明见 [SOURCES.md](SOURCES.md)，机器可读索引为 [source-map.json](source-map.json)。

## 迁移说明

原学习路线与四层边界进入第 1 篇，Instructions 与 Skill 合并到第 2 篇；Workspace、Sandbox、权限、Verifier、恢复和委派分别由对应主题承接。
新增执行控制、生产设计、完整实战与四篇源码解读。旧 URL 已配置主要去向，但本轮未构建或发布跳转页面。