Files

chenqi 8afeb2e4d9 fix(security): 添加VITE_PAYMENT_URL环境变量配置

2026-06-18 21:29:41 +08:00

6.6 KiB

Raw Blame History

name, description

name	description
harness-engineering	Master methodology for designing AI Agent work environments. Use when designing constraints, feedback loops, control planes, quality gates, or durable execution for Codex agents. Encodes the full Harness Engineering paradigm.

Harness Engineering — 核心方法论

Harness = 约束 + 反馈 + 控制平面 + 持久执行

🔧 四大核心组件

1. 约束系统 (Constraints)

定义 Agent 行为边界和输出质量。四层金字塔：

层级	内容	本项目落地
L1 架构约束	接口合约、包结构、命名规范、禁止模式	AGENTS.md 铁律、全链路清单
L2 代码质量	圈复杂度、代码风格、类型提示、文档要求	编译门禁 + 语法检查
L3 安全约束	敏感信息检测、权限检查、输入验证	配置文件不可硬编码
L4 业务规则	领域逻辑、数据一致性、事务边界	全链路数据流验证

关键原则：

约束越底层越自动（编译检查），越上层越需要人工裁决
约束冲突时：安全 > 架构 > 质量 > 业务
约束应随信任度动态调整（信任度模型见下文）

2. 反馈系统 (Feedback Loop)

测试 → 失败 → Agent 修复 → 重测。分三层：

层级	速度	覆盖范围	失败处理
L1 编译检查	<30 秒	语法、类型、签名	立即阻断，Agent 自行修复
L2 数据流验证	<5 分钟	全链路字段、Mapper XML、DTO	Agent 修复，必要时上报
L3 人工审查	10-30 分钟	架构、设计、业务正确性	驳回 / 指导 / 批准

反馈设计铁律：

反馈必须可行动（指出：文件 + 行号 + 错误类型 + 修复方向）
反馈越及时越好（L1 即时 → L2 分钟 → L3 小时）
失败后先回滚到最近检查点，再重试

3. 控制平面 (Control Plane)

任务调度和 Agent 协调的核心机制：

┌─────────────────────────────────────────────┐
│  控制平面三层架构                            │
│                                             │
│  战略层（人类主导）                          │
│  ├── 设定目标、审批关键决策                   │
│  └── 异常升级处理                            │
│                                             │
│  战术层（Control Plane 主导）                 │
│  ├── 任务分解 + 规划                        │
│  ├── update_plan / checklist_write           │
│  └── 依赖协调 + 资源分配                     │
│                                             │
│  执行层（Agent 自主）                        │
│  ├── 代码生成、测试执行                      │
│  ├── apply_patch / exec_command              │
│  └── 错误恢复 + 检查点保存                   │
└─────────────────────────────────────────────┘

4. 持久执行 (Durable Execution)

长时任务的检查点恢复机制（详见 $durable-execution 技能）：

每个关键步骤保存检查点（update_plan 进度）
失败后从最新检查点恢复，不从头开始
幂等设计：同一操作重复执行结果一致

📋 工作流程

标准工作流：Plan → Generate → Validate → Review

收到任务
  │
  ├→ 1. 计划（Plan）
  │   ├── 分解步骤（checklist_write + update_plan）
  │   ├── 评估复杂度 / 风险
  │   └── 设定检查点里程碑
  │
  ├→ 2. 生成（Generate）
  │   ├── 并行探索（spawn_agent × N）
  │   ├── 约束优先：先加载 AGENTS.md 和相关规则
  │   └── 增量修改：只动必要文件
  │
  ├→ 3. 验证（Validate）
  │   ├── L1 编译检查（mvn compile / python3 -c py_compile）
  │   ├── L2 数据流验证（全链路检查清单）
  │   └── L3 人工审查（提交 diff 给人类）
  │
  └→ 4. 审查（Review）
      ├── 提交前 self-review（对照约束逐条检查）
      ├── 生成变更摘要
      └── 提交 / 推送

异常流程

编译失败 → 分析错误 → 撤销本次修改 → 从检查点恢复 → 重试
持续失败（3次） → 上报人类 → 等待指导

🎯 质量门禁（Quality Gates）

门禁	触发时机	通过条件	失败动作
L1 编译	每次修改后	编译通过	立即修复
L2 全链路	提交前	数据流完整	Agent 修复
L3 审查	PR 提交	人类批准	驳回/指导
L4 回归	合并后	无回归	紧急修复

🔐 分层信任模型

信任等级	特征	自动化程度
L1 怀疑	Agent 错误率高，人工逐行审查	<20% 自动
L2 试探	Agent 稳定，抽样审查	40-60% 自动
L3 信任	Agent 可靠，关注结果	70-85% 自动
L4 委托	Agent 成为伙伴，人类管战略	90%+ 自动

当前项目状态： L2 试探级（编译门禁自动 + 全链路验证 + 人工终审）

📐 约束设计模式

1. 肯定模式 — 必须遵守的规则

必须实现 XXX 接口
代码覆盖率必须 > 90%
每个公共方法必须有类型提示

2. 否定模式 — 禁止的行为

禁止直接操作数据库（必须通过 Repository）
禁止硬编码密码/密钥
禁止使用 eval()

3. 边界模式 — 限制范围

圈复杂度 <= 10
每函数行数 <= 50
单文件修改 <= 5 个

4. 优先级模式 — 冲突处理

安全 > 架构 > 质量 > 性能 > 便利

⚠️ 常见陷阱

陷阱	表现	解决
过度约束	Agent 被束缚，效率低	从最少约束开始，按需增加
约束冲突	多个规则互相矛盾	确定优先级顺序
反馈延迟	编译太慢，Agent 等待	分层测试，快速失败
控制不足	Agent 自由度过高	增加检查点和门禁
跳过验证	直接提交未验证代码	门禁自动化，阻塞提交

📚 相关技能

$durable-execution — 检查点、幂等性、事件溯源
$closed-loop-testing — 质量门禁、测试策略、反馈循环
$constraint-design — DSL 设计、策略模式、约束编排
$review-audit — 审查工作流、审计追踪、合规检查
$full-chain-fix — 全链路数据流修复（已安装）
$karpathy-guidelines — 减少 LLM 编码错误（已安装）

6.6 KiB Raw Blame History Unescape Escape