Cheat Sheet مرجع سريع
العربية

اللغة

مرجع سريع

هندسة Agent Harness وبنية وقت التشغيل ورقة غش

دليل مرجعي شامل لهندسة AI Agent Harness وهياكل وقت التشغيل: مقارنة النماذج المجردة بالوكلاء، والأركان الستة للبنية، وسير عمل إصلاح الأخطاء مغلق الحلقة في 10 خطوات.

· تاريخ النشر

في أنظمة الذكاء الاصطناعي الإنتاجية، يمثل Harness (هيكل وهيكل وقت التشغيل للوكيل) بمثابة نظام التشغيل وهيكل التنفيذ الذي يغلف نماذج LLM التأسيسية لتحويلها إلى منفذين ذاتيين للمهام الواقعية.

Production Agent = Frontier LLM (Brain) + Domain Skills (SOPs) + Robust Harness (Execution Chassis)

🔗 Agent Skills · Claude Code · LLM & Agent Concepts · Always-on Agents

1. مقارنة بين النموذج المجرد (Bare LLM) والوكيل المجهز (Harnessed Agent)

flowchart LR
  subgraph Bare ["Bare LLM (Stateless Brain)"]
    direction TB
    P1["User Prompt"] --> M1["Raw LLM Weights"]
    M1 --> O1["Static Text / Code Block
(Cannot Run, Cannot Verify)"]
  end

  subgraph Harnessed ["Harnessed Agentic System"]
    direction TB
    P2["High-Level Goal"] --> H1["Context Assembler"]
    H1 --> M2["LLM Planner"]
    M2 --> E1["Sandboxed Execution Engine
(Bash, File System, MCP)"]
    E1 --> V1["Verification & Error Feedback Loop"]
    V1 -- "Tests Fail (Reflect & Retry)" --> H1
    V1 -- "Tests Pass" --> O2["Production Ready Deliverable
(Git Commit / Verified PR)"]
  end

  style Bare fill:#fef2f2,stroke:#f87171,stroke-width:1px;
  style Harnessed fill:#f0fdf4,stroke:#22c55e,stroke-width:2px;
Dimension Bare LLM Harnessed Agent
Execution Environment Isolated cloud sandbox, zero local system access Sandboxed shell, containerized OS, or local CLI runner
State & Memory Transient conversation history; forgotten on reset Working scratchpads, persistent project files, vector stores
Tool Capabilities Restricted to vendor plugins or simple web search Full tool harness: filesystem traversal, bash commands, MCP servers
Feedback Loop Open-loop: user manually copy-pastes errors back Closed-loop: agent captures stdout/stderr, detects errors, iterates
Error Recovery Passive: relies entirely on operator guidance Active: self-reflective evaluation, branch rollback, iterative refinement
Task Scope Single snippet generation, question answering Multi-file refactoring, end-to-end bug resolution (SWE-bench)

2. الأركان الستة الأساسية لهيكل Harness الصناعي

1. Dynamic Context Engineering (Input Layer)

  • Token Budget Manager: Dynamically allocates context tokens across system prompts, conversation history, project trees, and active file buffers.
  • Hierarchical Context Compaction: Automatically trims verbose tool returns, converts stack traces into concise signatures, and maintains sliding summaries.
  • Project Awareness Anchors: Ingests project-level metadata (CLAUDE.md, .cursorrules, repository tree, active git status) into the initial system prompt.

2. Sandboxed Tool Execution Engine (Action Layer)

  • Containerized Isolation: Runs bash commands inside lightweight container environments (Docker, Podman, gVisor) or isolated host subshells.
  • Deterministic File Primitives: Dedicated hunk-based diff editors and structured file search tools (grep, glob, AST parsing) rather than brittle line overwrites.
  • Model Context Protocol (MCP): Standardized dynamic discovery and protocol binding for databases, dev tools, and external APIs.

3. Verification & Guardrail Engine (Feedback Layer)

  • Automated Test Runners: Executes unit and integration test suites automatically after code modifications.
  • Output Validation: Validates compiler and linter diagnostics before declaring completion.
  • Destructive Action Gates: Blocks catastrophic shell commands (rm -rf /, DROP TABLE, uncommitted hard resets) and requests explicit human confirmation.

4. Working Memory & Scratchpad (State Layer)

  • Working Scratchpad: A dedicated markdown buffer or persistent scratchpad file where the agent drafts step-by-step plans, hypotheses, and diagnostic traces.
  • Checkpoint & Rollback Manager: Records git branch commits or filesystem snapshots prior to multi-file refactoring passes.

5. Multi-Agent Delegation & Swarms (Collaboration Layer)

  • Hierarchical Orchestration: The lead planner agent spawns specialized subagents (e.g., Code Researcher, Database Specialist) with scoped permissions.
  • Baton-Passing Loops: Independent subagents execute bounded assignments in isolated workspaces and return structured summaries to the orchestrator.

6. Observability & Telemetry (Operations Layer)

  • Structured Trace Logging: Records full token costs, model latency, tool invocation parameters, and exit codes into queryable JSONL transcripts.
  • Cost & Loop Quotas: Hard circuit-breakers preventing runaway infinite reasoning loops and catastrophic API token consumption.

3. سير عمل حل الأخطاء مغلق الحلقة في 10 خطوات (SWE-bench)

Phase Step Objective Primary Harness Tooling Success Metric
01 Ingestion Parse issue description and failure logs Issue Tracker / Transcript Parser Concrete failure signature identified
02 Exploration Search repository tree and locate modules file_search, code_grep Minimal set of candidate source files isolated
03 Reproduction Write a reproduction test script write_file, run_command Test fails as expected with reproduced defect
04 Localization Pinpoint precise lines causing failure read_file, AST Inspector Root cause identified at function/line level
05 Hypothesis Plan the minimal behavioral patch Scratchpad / Inner Monologue Clear design that avoids collateral side-effects
06 Patching Apply code modifications edit_file (hunk-based diff) Patch applies cleanly without syntax corruption
07 Verification Re-run reproduction test run_command Reproduction test passes cleanly
08 Regression Run entire repository test suite run_command (e.g. pytest) Zero regressions in existing test suite
09 Housekeeping Remove scratch scripts, restore configs delete_file, git checkout git status shows only intentional modifications
10 Hand-off Commit changes and present summary git commit, Summary Generator Clean diff with descriptive commit message

4. مكونات النظام الأساسية داخل Harness الصناعي

┌──────────────────────────────────────────────────────────────┐
│                    Harness Runtime Core                      │
├──────────────────────────────┬───────────────────────────────┤
│ Context Engine               │ Execution Engine              │
│ - CLAUDE.md / Rules Loader   │ - Sandboxed Shell (gVisor/OS) │
│ - Token Budget Allocator     │ - Hunk-based Diff Editor      │
│ - Transcripts / Summarizer   │ - Model Context Protocol (MCP)│
├──────────────────────────────┼───────────────────────────────┤
│ Verification & Guardrails    │ Memory & State Store          │
│ - Test Runner & Parser       │ - Scratchpad & Checkpointer   │
│ - Human Approval Gateway     │ - Local Symbol / Ctags Cache  │
│ - Cost & Loop Limiters       │ - Trace Logger (JSONL)        │
└──────────────────────────────┴───────────────────────────────┘

5. مقارنة تطبيقات Harness الصناعية الرائدة

Metric / Feature Claude Code (Anthropic) Devin (Cognition) SWE-agent (Princeton) OpenHands (All-Hands AI)
Deployment Form CLI terminal binary Hosted web workspace Python CLI benchmark Web UI + Headless Docker
Sandbox Architecture Local subshell with opt-in approval Dedicated cloud VM Docker container Docker container
Context Strategy Compact CLI prompts + CLAUDE.md Persistent session tree Custom ACI Modular agent prompts
Editor Primitive Custom hunk-based str_replace Browser-based IDE editor Line-number based patch tool Custom file-editing tools
Extensibility Model Context Protocol (MCP) Proprietary integrations Custom python actions Micro-agents & custom tools
Primary Strength Developer ergonomics, instant CLI Complex end-to-end web tasks Academic SWE-bench tests Open-source customization

6. القواعد الذهبية الخمس لهندسة Harness

Rule 1: Optimize the Agent-Computer Interface (ACI)
        Standard UNIX tools are designed for humans. Agent tools must return structured,
        noise-free outputs with clear error signatures and line numbers.

Rule 2: Never Let Context Become the Bottleneck
        Compress verbose tool outputs aggressively. Truncate long build logs to the relevant
        compiler warnings and the final 20 lines of stack traces.

Rule 3: Enforce Small, Verifiable Iteration Loops
        Discourage the agent from making massive multi-file changes in a single turn. Enforce
        an edit-test-verify cycle on each atomic change.

Rule 4: Provide Checkpoints and Fast Rollbacks
        If an agent introduces a cascading syntax regression, rolling back via git checkout
        is far cheaper and more reliable than prompting the model to untangle its own mistakes.

Rule 5: Build Explicit Guardrails Around Destructive Actions
        Enforce strict permission gates for out-of-sandbox writes, network requests, and
        irreversible database commands. Safe environments enable higher autonomy.

موضوعات ذات صلة

#ai-agent#agent-harness#software-engineering#llm-runtime#system-design#cheat-sheet