Author: Wang Guo (@wangguode)
Source Repository: https://github.com/wangguode/zhishu-agent
Stack: Java 17 (Spring Boot 3.3) Full-Stack Studio + Python 3.9+ Zero-Dependency Pattern Engine
1. The Production Dilemma: Models Set the Ceiling, Harness Sets the Floor
When developers first experiment with autonomous coding agents (Claude Code, OpenAI Swarm, Cursor, Devin-style bots), they are mesmerized by the demos. The LLM writes a Python function, creates a test file, and seemingly finishes the task.
However, once you deploy an agent into enterprise codebases with 50,000+ lines of legacy code, the agent quickly collapses into one of three fatal failure modes:
- The "Optimistic Surrender": The agent edits a source file, hallucinates that the change worked without ever compiling or executing unit tests, and presents an enthusiastic message: "All done! I have fixed the bug for you."
- The Runaway Context Death: After 6 rounds of command line errors, compiler stack traces consume 40,000 tokens of raw bash dumps. The prompt context blows up, rate limits hit, and the agent hallucinates randomly because the original task intent was pushed out of the attention window.
-
The Unsafe Tool Invocation: Given a bash tool, the agent runs
rm -rf /or pipes uncontrolled strings intoeval(), or accidentally echoes production API keys (sk-...) into unmasked logs.
At Zhishu Agent (知枢智能体), we built an open-source enterprise harness architecture to solve these problems. Our core realization is simple:
The model sets the ceiling of what is theoretically possible, but the Harness (马具工程) determines the floor of operational reliability.
2. Anatomy of the Self-Healing Loop
A production-grade coding agent cannot be a simple while-loop of model.generate() -> tool.call(). It must be structured as a convergent state machine:
+--------------------------------------------------------------------------+
| Zhishu Agentic Harness Loop |
+--------------------------------------------------------------------------+
│
▼
[1. User Intent Intake]
│
▼
┌─────────────────── [2. Reason & Plan] ◄──────────────────┐
│ │ │
│ ▼ │
│ [3. Tool Interception Guard] │
│ (PreToolUse: AST Lint & Perms) │
│ │ │
│ ▼ │
│ [4. Ephemeral Workspace Exec] │
│ (Git Worktree / Sandbox) │
│ │ │
│ ▼ │
│ [5. Test-Driven Verification] │
│ (Run Maven / Pytest Harness) │
│ │ │
│ ┌────────────────┴────────────────┐ │
│ ▼ ▼ │
│ [Tests Pass] [Tests Fail] │
│ │ │ │
│ │ ▼ │
│ │ [6. Stack Trace Parsing] │
│ │ (AST Error Isolation) │
│ │ │ │
│ │ ▼ │
│ │ [7. Context Compression] │
│ │ (/compact Pruning -85%) │
│ │ │ │
│ │ └───────────┘
▼ ▼
[8. PostToolUse: Secret Masking]
│
▼
[9. Human-in-the-Loop Release]
The 5-Step Convergence Guarantee:
-
Isolated Worktrees: The agent never operates directly on the
mainbranch. It works in an isolated Git worktree or ephemeral container directory. -
Pre-Tool Interceptors: Before executing any command, the harness passes the shell payload through an AST validator. Dangerous actions (
rm,dd,drop table) are hard-blocked in under 1ms. -
Automated Assertion Harness: When modifying code, the harness forces a verification phase (
pytest -qormvn test). The agent is not permitted to declare completion until the test suite returns exit code 0. - Structured Failure Injection: If the test fails, raw stderr is not dumped into context. Instead, the harness isolates the specific failed assertion, line number, and diff, feeding only high-signal diagnostic delta back into the agent's prompt.
- Loop Convergence Limiter: If the loop does not converge after 4 attempts, the harness raises a graceful escalation checkpoint rather than burning tokens in an infinite repair hallucination.
3. Dynamic Context Compression (/compact Protocol)
One of the biggest reasons coding agents fail during multi-file refactoring is context saturation. When bash outputs, stack traces, and 500-line source files accumulate, the prompt exceeds 30k tokens. The LLM loses track of early constraints.
In zhishu-agent, we implemented a Two-Stage /compact Context Compression Engine:
-
Stage 1 (Ephemeral Tool Output Pruning): Once a unit test run or file read has been analyzed and acted upon, its raw multi-kilobyte text is purged from memory, leaving only a 1-line metadata tombstone:
[Output pruned: 1,420 bytes, test failed on assertion line 42]. -
Stage 2 (Structured Milestone Checkpointing): When token utilization crosses 75% of window capacity, the harness synthesizes a structured checkpoint:
- Goal: What was the user asking?
- Decisions Made: Which files were already modified?
- Current Blocker: What is the immediate test failure?
- Next Step: What action is scheduled next?
This reduces token consumption by over 85% and allows agents to run continuously across 20+ iterations without degradation.
4. MCP (Model Context Protocol) Implementation
Standardizing tool calling across multiple vendors (Anthropic, OpenAI, DeepSeek, Local Ollama) has historically required custom wrapper code.
zhishu-agent adopts the MCP JSON-RPC 2.0 protocol, implementing clean handlers for:
-
initialize: Capability negotiation and protocol version handshake. -
tools/list: Three-tier progressive disclosure (metadata -> schema -> execution), preventing hundreds of enterprise microservices from bloating the system prompt. -
tools/call: Strongly typed JSON-RPC invocation with strict timeout boundaries andCompletableFutureasynchronous non-blocking dispatch.
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "run_test_suite",
"arguments": {
"path": "src/test/java/com/zhishu/service/PaymentTest.java",
"timeoutMs": 5000
}
},
"id": "zhishu-req-104"
}
5. Dual-Engine Open-Source Implementation
To make this immediately practical for engineers, we provide two complete, production-grade implementations in the repository:
-
Java 17 + Spring Boot 3.3 (WG-Harness-Studio):
- Complete visual Web GUI built for enterprise teams.
- Non-blocking reactive pipeline with CompletableFuture HITL approval gates.
- Built-in zero-key simulation mode + single-line configuration for DeepSeek, Qwen, or OpenAI models.
-
Python 3.9+ Zero-Dependency Library (WG-Harness-CLI):
- Single-file, standalone zero-dependency reference patterns.
- Clean, readable implementation of the 8 core harness patterns that you can read and understand in 5 minutes.
6. Explore the Code & Run Locally
Everything is 100% open-source under the MIT license:
- 💻 GitHub Repository: https://github.com/wangguode/zhishu-agent
- 📖 Full Architectural Specification: See
docs/architecture-light.svganddocs/HARNESS_PATTERNS.mdin the repo.
Would love feedback from engineers building autonomous agents, coding assistants, and production harnesses! Star the repo if you find the patterns useful! ⭐
Top comments (0)