内容
# AI 智能体套件
一个与项目无关的套件，为任何 AI 编程智能体（Claude Code、GitHub Copilot、Codex、Cursor、Gemini 等）提供一致的操作合约：加载内容、执行顺序、迭代直到完成 — 以及自主的、基于指标的自我改进循环，可以在本地 LLM 上运行，以及实时的指标仪表盘。
从一个干净、可重用的套件中提取。参见 [`CREDITS.md`](CREDITS.md) 了解其所依赖的先前工作，以及 [`HARNESS_CARD.md`](HARNESS_CARD.md) 了解一页纸的控制/代理/运行时设计摘要。
## 安装
该套件作为 [Agent Skill](https://agentskills.io/) 和 Claude Code 插件打包，因此可以安装到 70 多个智能体（Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Cline 等）中，而无需手动复制文件夹。
```bash
# 70 多个智能体，通过开放的 Agent Skills CLI（-g 全局安装）：
npx skills add <owner>/harness-kit -g
# 特定智能体（或多个）：
npx skills add <owner>/harness-kit -g -a github-copilot -a claude-code
# 或从本地克隆的套件：
npx skills add ./harness-kit --list # 发现，然后添加 --skill harness 进行安装
```
```text
# Claude Code，通过原生插件市场（自动更新）：
/plugin marketplace add <owner>/harness-kit
/plugin install harness-kit
```
**两层，刻意为之。** 上述技能是 **剧本** — 它教会智能体套件合约（阶段、门控、循环、内存），足以在任何仓库中提供指导。**可运行引擎**（`scripts/harness/*.mjs` 循环运行器、仪表盘和 MCP 服务器）与套件文件一起提供；可以通过安装 Claude Code **插件**（捆绑所有内容）或按照 [`SETUP.md`](SETUP.md) 采用套件脚手架获取。替换 `<owner>/harness-kit` 为发布此套件的位置。
对于 **GitHub Copilot 应用内的仓库**，脚手架还提供 `.github/copilot-instructions.md`。一旦套件存在于仓库中，Copilot 就可以直接从该文件加载套件入口。
## 内容
| 功能 | 位置 | 备注 |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **工作流阶段机** | [`.github/harness/HARNESS.md`](.github/harness/HARNESS.md), [`.github/instructions/`](.github/instructions/) | 了解 → 设计 → 实现 → 审查（广度+深度）→ 反馈，带有 5 个架构门控 |
| **GitHub Copilot 应用入口** | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) | 仓库级引导，指向套件合约 |
| **收敛循环** | [`.github/harness/loops/`](.github/harness/loops/), [`run-loop.mjs`](scripts/harness/run-loop.mjs) | 迭代直到检查（lint/type/build/test）通过 |
| **工作流循环** | 相同 | 基于评分的通过（审查-修复、功能循环、CI 绿色） |
| **实验循环（自动研究风格）** | [`run-experiment.mjs`](scripts/harness/run-experiment.mjs), [`experiment-loop.mjs`](scripts/harness/experiment-loop.mjs) | 攀升数值指标；如果改进则保留，否则恢复 |
| **本地 LLM 智能体** | [`ollama-agent.mjs`](scripts/harness/ollama-agent.mjs), [`ollama-apply-agent.mjs`](scripts/harness/ollama-apply-agent.mjs) | 通过 **Ollama** 或 **LM Studio** 驱动循环（ `--provider`） |
| **内存** | [`.github/harness/memory/`](.github/harness/memory/) | 已提交的经验教训 + 架构简介（仅结构 — 无经验教训） |
| **知识图** | [`graph-refresh-loop.mjs`](scripts/harness/graph-refresh-loop.mjs) | 可选的结构化内存（需要 Understand-Anything 插件） |
| **MCP 服务器** | [`mcp-server.mjs`](scripts/harness/mcp-server.mjs) | 通过 MCP 暴露 15 个图/内存/向量 + 循环/报告工具（`.vscode/mcp.json` 注册它） |
| **仪表盘** | [`report-server.mjs`](scripts/harness/report-server.mjs) | 始终在线的 HTML 指标仪表盘 |
## 三种循环类型
```text
收敛 运行直到通过/失败检查均为绿色 （构建修复、测试修复）
工作流 运行基于评分的通过到终端状态 （审查修复、功能循环、CI 绿色）
实验 攀升数值指标，如果改进则保留 （lint 债务实验） ← 自动研究风格
```
## 快速开始
```bash
# 1. 将套件指向项目的命令。
cp harness.config.json harness.config.json # 然后编辑：项目名称 + 命令
node -e "JSON.parse(require('fs').readFileSync('harness.config.json','utf8'))" # 健全性检查
# 可选：预览仓库的套件路由和操作员移交计划。
# PowerShell：单独运行每个 npm 包装器命令，而不是用分号连接包装器。
npm run harness:route -- --task "修复身份验证中间件竞争"
npm run harness:feature -- --task "交付联邦审计强化"
npm run harness:handoff:review -- --task "审查缓存失效更改"
# 2. 列出和运行收敛循环（使用已配置的命令）。
npm run harness:loops
node scripts/harness/run-loop.mjs build-fix --agent "<your agent CLI>"
# 3. 记录实验指标的基线（无需智能体）。
node scripts/harness/run-experiment.mjs lint-debt-experiment --measure-only
# 4. 查看仪表盘。
npm run harness:report # 写入 .github/harness/runs/report.html
npm run dashboard:up # 或在 http://localhost:8099 上始终在线
# 可选：委员会风格的并行审查综合（保持阶段机完整）
npm run harness:council:review -- --mode review --prompt "审查此更改集"
# 可选：目录预设（安全固定键）
npm run harness:council:review -- --mode review --prompt-key review
# 或从 stdin 导入提示内容（PowerShell）
Get-Content .github/harness/memory/briefs/EXAMPLE.md -Raw | npm run harness:council:review -- --mode review --prompt-stdin
# 向后兼容性：旧提示文件调用者现在仅解析令牌（无文件读取）
npm run harness:council:review -- --mode review --prompt-file review.md
# 可选：工作区内存的瞬时 JSONL
npm run harness:workspace-memory -- append --mode review --text "捕获审查者分歧"
npm run harness:workspace-memory -- list --last 20
# 可选：记录具有显式待处理批准标记的工作流运行
node scripts/harness/record-run.mjs --loop review-fix --state blocked --approval-required --approval-status pending --approval-note "等待审查者签名" --fail "Gate 3 所有权未解决"
```
仪表盘的 **待处理批准** 部分非常严格：它仅显示具有显式日志标记的运行（`approval.required=true` 和 `approval.status=pending`）。它不会从简要状态或阻止/卡住的终端状态推断待处理批准。
现在，生成的 CLI 命令的安全强化集中在 `scripts/harness/command-validation.mjs` 中，并在关键的 shell 启动点强制执行（`run-loop`、`run-experiment`、`plan-review`）。它允许已知可执行文件并拒绝 shell 元字符有效载荷。
Webview 命令界面和 WSL 特定执行适配器在此套件版本中故意可选/延迟。继续使用脚本优先的编排，除非您的环境需要专用 UI 或跨 shell 适配器。
要规范历史数据集，请为遗留运行日志添加显式默认批准标记：
```bash
npm run harness:migrate:approvals -- --dry-run
npm run harness:migrate:approvals
```
此迁移仅更新缺少 `approval` 对象的循环日志，默认为 `required=false` 和 `status=not-required`。
完整采用指南：[`SETUP.md`](SETUP.md)。循环协议：[`.github/harness/LOOPS.md`](.github/harness/LOOPS.md)。
## 提示路由策略
该套件在 [`scripts/harness/prompt-router.mjs`](scripts/harness/prompt-router.mjs) 中提供了一个仓库本地提示路由器。它本身不会拦截编辑器提示；相反，它为操作员提供了一个确定的路由和基于 [`harness.config.json`](harness.config.json) 的阶段/模型移交计划。
- `harness:route` 将提示分类为微不足道或非微不足道。
- `harness:feature` 和 `harness:handoff:feature` 打印完整的功能交付移交：了解 → 设计 → 实现 → 审查广度 → 审查深度 → 反馈。
- `harness:handoff:review` 打印独立的审查移交：了解 → 审查广度 → 审查深度 → 反馈。
- `harness:prompt-pack` 在 `.github/harness/runs/prompt-packs/` 下生成一个 gitignored 提示包，包含一个编排器提示、规范阶段提示、循环内存脚手架和可选的侦察/挑战者侧车。
- `harness:review` 运行审查工作流以保持向后兼容性。
默认情况下，提供的环境策略将执行和判断分开：
- `gpt-5.3-codex` 用于实现和修复循环。
- `claude-opus-4.8` 用于了解、设计、审查广度、审查深度和反馈。
## 使用本地模型进行自动研究
与 **Ollama** （默认，`:11434`）或 **LM Studio** （OpenAI 兼容，`:1234`）合作 — 使用 `--provider` 或 `HARNESS_LLM_PROVIDER` 进行选择。
```bash
# 一个有边界的实验，由本地模型驱动，实际上会重写目标文件：
node scripts/harness/run-experiment.mjs lint-debt-experiment \
--agent "node scripts/harness/ollama-apply-agent.mjs --model qwen2.5-coder:14b"
# 通过 LM Studio（首先加载模型）：
node scripts/harness/run-experiment.mjs lint-debt-experiment \
--agent "node scripts/harness/ollama-apply-agent.mjs --provider lmstudio --model <loaded-model-id>"
# 连续的夜间爬坡，提交每次改进：
npm run harness:experiment:ollama -- --commit # 或：harness:experiment:lmstudio
```
应用代理仅编辑实验的单个声明 `target`；运行器重新测量并恢复任何不符合指标的更改 — 因此允许小型本地模型重写文件是安全的。通过构造。共享适配器 [`llm-provider.mjs`](scripts/harness/llm-provider.mjs) 处理两个运行时（聊天 + 嵌入）；`vector-search.mjs` 也支持 `--provider`。
## MCP 集成
套件提供了一个一流的 MCP stdio 服务器，暴露 **15 个读取/观察工具** — 知识图（7）、内存（3）、向量搜索（3），加上循环发现（`harness-loops`）和指标（`harness-report`）。 [`.vscode/mcp.json`](.vscode/mcp.json) 为 VS Code 注册它；对于 Claude Code / Cursor，请在 MCP 配置中使用相同的 `command`/`args`。
```bash
node scripts/harness/mcp-tools.mjs list-tools # 检查工具目录
npm run harness:mcp:server # 直接运行_stdio 服务器
```
循环 **执行** 故意保持 CLI 独家：循环调用智能体并运行数分钟，因此将其公开为自动调用 MCP 工具（当 MCP 客户端 _是_ 智能体时）会递归并超时。MCP 界面用于发现和上下文，而不是用于驱动循环。
## 要求
- Node.js ≥ 20（使用内置的 `fetch`；核心循环无需安装）。
- 可选：Docker（仪表盘/侧车）、Ollama 或 LM Studio（本地 LLM 循环）、Understand-Anything 插件（知识图）。
对于 `graph-refresh` 侧车，插件依赖项引导现在默认强化。当插件安装在 `/opt/understand-plugin` 时，循环会复制它到可写的运行时路径并运行 `corepack pnpm install --frozen-lockfile`，然后刷新。这样可以避免只读挂载或主机/容器链接器不匹配的回归。通过以下方式覆盖：
- `GRAPH_REFRESH_BOOTSTRAP_PLUGIN=false` 禁用引导。
- `GRAPH_REFRESH_FORCE_BOOTSTRAP=true` 强制运行时复制/安装，即使源插件已经具有 `node_modules`。
- `GRAPH_REFRESH_RUNTIME_PLUGIN_ROOT=/custom/path` 更改运行时复制位置（默认：`/workspace/.cache/understand-plugin-runtime`）。
- `GRAPH_REFRESH_BOOTSTRAP_INSTALL_TIMEOUT_MS=120000` 限制安装等待时间并快速失败。
您也可以在启动循环之前手动运行确定性的预飞行：
```bash
node scripts/harness/graph-refresh-loop.mjs --preflight-only --plugin-root <plugin-root>
```
组合侧车现在首先运行此预飞行，并在缺少先决条件时退出并带有可操作的错误。
## 许可证
MIT — 参见 [`LICENSE`](LICENSE) 和 [`CREDITS.md`](CREDITS.md)。
