Agent Harness：让智能体稳定完成长周期任务的运行框架

失败项：角色移动
复现步骤：
1. 打开 /editor
2. 点击 Preview
3. 按下 ArrowRight

期望结果：
角色向右移动至少 16px。

实际结果：
角色保持不动，控制台无报错。

可能原因：
键盘事件监听绑定在编辑模式容器上，进入预览模式后容器失去焦点。

建议修复：
将 keydown 监听绑定到 window，并在退出预览模式时移除监听。

repo/
├── AGENTS.md
├── docs/
│   ├── architecture.md
│   ├── product-spec.md
│   ├── coding-rules.md
│   ├── decisions/
│   │   ├── 0001-state-management.md
│   │   └── 0002-api-boundary.md
│   └── tech-debt.md
├── harness/
│   ├── progress.md
│   ├── tasks/
│   │   ├── task-001.md
│   │   └── task-002.md
│   ├── evals/
│   │   ├── ui-checklist.md
│   │   └── architecture-checklist.md
│   └── scripts/
│       ├── run_all_checks.sh
│       └── check_dependencies.py
├── src/
├── tests/
└── package.json

# AGENTS.md

你在这个仓库中工作时，必须先阅读以下文件：

- docs/product-spec.md：产品目标和功能范围
- docs/architecture.md：系统架构和模块边界
- docs/coding-rules.md：代码风格、测试要求和提交规则
- harness/progress.md：当前任务进度和未解决问题

工作规则：

1. 不要修改 docs/architecture.md 中标记为 stable 的接口，除非任务明确要求。
2. 每次修改后运行 `npm test` 和 `npm run lint`。
3. 如果新增跨模块依赖，必须运行 `node harness/scripts/check_dependencies.js`。
4. 任务完成前更新 harness/progress.md，记录改动、测试结果和遗留问题。
5. 不能读取 `.env`、`secrets/`、生产数据库配置。

// dependency-rules.js
module.exports = {
  forbidden: [
    {
      name: "ui-cannot-import-db",
      from: { path: "^src/ui" },
      to: { path: "^src/db" },
      severity: "error",
      comment: "UI 层不能直接访问数据库，只能调用 service 层。"
    },
    {
      name: "domain-cannot-import-ui",
      from: { path: "^src/domain" },
      to: { path: "^src/ui" },
      severity: "error",
      comment: "领域层不能依赖 UI。"
    }
  ]
}

# harness/tasks/task-001.md

## 目标

为小游戏编辑器增加预览模式，用户可以从编辑模式切换到预览模式，并控制角色移动。

## 功能要求

- 编辑模式中可以放置角色出生点。
- 点击 Preview 后进入预览模式。
- 预览模式中方向键控制角色移动。
- 点击 Exit Preview 返回编辑模式。
- 返回编辑模式后，地图配置不能丢失。

## 验收标准

- Playwright 测试覆盖模式切换和方向键移动。
- 控制台无运行时错误。
- `npm test` 通过。
- `npm run lint` 通过。

## 不允许修改

- 不修改 `src/domain/map-schema.ts` 的公开类型。
- 不引入新的全局状态库。

#!/usr/bin/env bash
set -euo pipefail

npm run lint
npm test
npm run test:e2e
node harness/scripts/check_dependencies.js

# harness/evals/ui-checklist.md

你是评估 Agent，只判断补丁是否满足任务验收标准。

必须检查：

1. 功能是否完整。
2. 测试是否覆盖关键路径。
3. 是否违反架构约束。
4. 是否出现用户可见的交互问题。
5. 是否留下未说明的 TODO。

输出格式：

- result: pass 或 fail
- failed_items: 失败项列表
- reproduction: 可复现步骤
- evidence: 命令输出、截图描述或日志
- fix_suggestion: 面向生成 Agent 的修复建议

# harness/progress.md

## 当前任务

task-001：增加预览模式。

## 已完成

- 增加 Preview / Exit Preview 按钮。
- 增加 preview 状态。
- 增加角色出生点读取逻辑。

## 测试结果

- npm run lint：通过
- npm test：通过
- npm run test:e2e：失败

## 当前问题

Playwright 测试中，进入预览模式后方向键没有触发角色移动。

## 下一步

检查键盘事件监听绑定位置，优先确认焦点是否停留在 canvas 容器。

from dataclasses import dataclass

@dataclass
class EvalResult:
    passed: bool
    feedback: str

def call_agent(role: str, prompt: str, context: list[str]) -> str:
    """调用指定角色的模型。真实实现中可接入 Claude、Codex 或其他模型。"""
    raise NotImplementedError

def run_checks() -> tuple[bool, str]:
    """运行测试、Linter、类型检查和架构规则。"""
    raise NotImplementedError

def apply_patch(patch: str) -> None:
    """应用模型生成的代码修改。"""
    raise NotImplementedError

def load_context() -> list[str]:
    return [
        read("AGENTS.md"),
        read("docs/product-spec.md"),
        read("docs/architecture.md"),
        read("harness/progress.md"),
    ]

def evaluate(task: str, patch_summary: str, check_output: str) -> EvalResult:
    context = load_context() + [
        read("harness/evals/ui-checklist.md"),
        f"任务：{task}",
        f"补丁说明：{patch_summary}",
        f"检查输出：{check_output}",
    ]

    report = call_agent(
        role="evaluator",
        prompt="判断补丁是否满足验收标准，按固定格式输出。",
        context=context,
    )

    passed = "result: pass" in report.lower()
    return EvalResult(passed=passed, feedback=report)

def run_harness(task: str, max_rounds: int = 5) -> None:
    context = load_context()
    plan = call_agent(
        role="planner",
        prompt=f"把任务拆成可执行步骤，并写出验收标准：{task}",
        context=context,
    )

    write("harness/current-plan.md", plan)

    feedback = ""
    for round_id in range(1, max_rounds + 1):
        context = load_context() + [
            read("harness/current-plan.md"),
            feedback,
        ]

        patch = call_agent(
            role="generator",
            prompt=f"执行第 {round_id} 轮修改，只解决当前任务。",
            context=context,
        )

        apply_patch(patch)

        checks_ok, check_output = run_checks()
        result = evaluate(task, patch_summary=patch, check_output=check_output)

        if checks_ok and result.passed:
            write("harness/progress.md", "任务通过，记录最终修改和测试结果。")
            return

        feedback = result.feedback
        write("harness/progress.md", f"第 {round_id} 轮失败：\n{feedback}")

    raise RuntimeError("达到最大迭代次数，任务仍未通过。")