Harness Kit
Tính năngFeatures Trình tạo CLICLI Builder Luồng hoạt độngHow it Works Cài đặtInstallation Tích hợp IDEIDE Integration Học HarnessLearn Harness GitHub
Chỉ dùng thư viện chuẩn Standard Library Only

Xây dựng Tác nhân AI Lập trình
Có Kiến trúc Vững chắc & Bền bỉ Build Secure, Resilient,
and Persistent AI Coding Agents

Harness Kit cung cấp bộ khung (Harness) gá lắp tác nhân AI siêu nhẹ bằng Python chỉ sử dụng thư viện chuẩn. Giúp Cursor, Claude Code, Antigravity chạy vòng lặp an toàn, bảo mật và lưu vết tuyệt đối. Harness Kit provides a lightweight standard-library-only Python Agent Harness implementation. It guides AI agents on running secure, highly resilient, and persistent execution loops (such as Cursor, Claude Code, Antigravity).

Sử dụng Trình tạo CLI Use CLI Builder Tìm hiểu các thành phần Explore Subsystems
bash - harness-kit-demo
$ git clone https://github.com/nguyenanh92/harness-kit.git
Đã thêm skill 'nguyenanh92/harness-kit' thành công. Added skill 'nguyenanh92/harness-kit' successfully.
$ py -m skills.scripts.scaffold_harness --target harness
Scaffolding Python Harness into: .\harness-kit\harness Created: harness.py Created: context_manager.py Created: tool_registry.py Created: persistence.py Created: hooks.py Created: subagent.py Created: prompt_assembly.py ---------------------------------------- Hoàn thành khởi tạo. Đã sao chép 7 tệp mẫu.Scaffolding complete. Copied: 7 templates.
$ py -m harness.harness --mock --goal "Create Calculator"
Initializing Agent Harness in mock mode... -> [Pre-Hook] Intercepting call: spawn_subagent [SUB-AGENT] 'explorer' successfully completed task. -> [Post-Hook] Logged execution of write_file [Agent] Goal achieved! Exiting loop.
Kiến trúc Cốt lõi Core Architecture

5 Phân Hệ (Subsystems) và 9 Thành phần 5 Subsystems and 9 Components

Instructions (Chỉ dẫnGuidelines)

Lắp ráp prompt động thân thiện với prompt cache. Tự động quét tìm file chỉ dẫn (CLAUDE.md, AGENTS.md) từ thư mục dự án và cha để nạp luật cho AI. Caching-friendly dynamic guidelines aggregator. Walks ancestor directories to find instruction files (CLAUDE.md, AGENTS.md) and injects them under the static prompt.

prompt_assembly.py

State (Trạng tháiState Preservation)

Ghi log trạng thái append-only JSONL bền bỉ và tự động nén token thông minh (Context Compaction) khi đạt 80% ngưỡng nhằm chống bùng nổ ngữ cảnh. Manages token budget with reactive context compaction when exceeding 80% limit. Preserves durability via append-only JSONL event logs flushed instantly.

persistence.py & context_manager.py

Verification (Xác minhVerification)

Tích hợp sẵn các primitives (hành động cơ bản) để chạy tự động kiểm tra biên dịch cú pháp hoặc các suite thử nghiệm (init.sh / init.bat) để bảo đảm an toàn. Standard primitives to execute syntax compilation checks (py_compile) and auto-test commands (init.sh, init.bat) to verify code health before exit.

built-in primitives

Scope (Phạm vi & An toànScope & Security)

Bộ quản trị quyền lực: phân quyền đọc/ghi, phân loại câu lệnh shell động để cảnh báo trước mã nguy hại, cô lập và quản lý tác nhân con (Sub-agent) đơn cấp. Enforces permission boundaries (read-only, write, full), dynamically classifies shell commands to prevent dangerous execution, and runs isolated sub-agents.

tool_registry.py & subagent.py

Lifecycle (Vòng đờiLifecycle)

Điều phối vòng lặp execution loop chính, hỗ trợ đăng ký pre-tool hook (để chặn/sửa đổi đối số) và post-tool hook (để audit telemetry) an toàn. Orchestrates the outer while execution loop, triggering customizable pre-tool hooks (for security filtering) and post-tool hooks (for auditing).

harness.py & hooks.py
Trình dựng CLI CLI Builder

Sinh Câu Lệnh Thiết Lập Dự Án Động Generate Setup Commands Dynamically

Cấu hình tham số Configure Parameters

Thay đổi các lựa chọn bên dưới để sinh lệnh chạy mẫu chính xác cho nền tảng của bạn. Adjust configuration variables below to generate commands mapped to your workspace. 

Loading...
Loading...
1. LLM API Output Loop Stateful Loop
2. Hook Gating & Shell Classifier tool_registry.py
3. Execution & Compactor persistence.py

Luồng Chạy Tự Động Bền Bỉ Robust, Durable Execution Flow

Mỗi lượt hành động của AI Agent được kiểm soát thông qua một cơ chế gá lái chặt chẽ: Every action in the execution loop is controlled by a secure gating harness:

  • All-or-Nothing Hook: Nếu không tin cậy thư mục làm việc, toàn bộ hook mở rộng của bên thứ ba sẽ bị ngắt tự động để tránh chạy code lén lút. All-or-Nothing Hook: If the workspace is marked as untrusted, all dynamic third-party hooks are automatically skipped to guarantee zero arbitrary code execution.
  • Dynamic Classification: Phân loại động lệnh shell thời gian thực. Bắt buộc dừng xin xác nhận người dùng (`input()`) đối với các lệnh tháo dỡ hệ thống (`rm`, `sudo`). Dynamic Classification: Classifies shell commands at runtime. Halts execution and triggers interactive prompts for dangerous commands like `rm` and `sudo`.
  • JSONL Durability: Ghi trạng thái lập tức xuống đĩa đệm. Trong trường hợp sập tiến trình, chỉ cần replay logs để dựng lại 100% ngữ cảnh cũ. JSONL Durability: Flushes session logs to disk immediately. Replays event logs sequentially to reconstruct 100% of the conversation context after a crash.
Hướng Dẫn Lắp Đặt Installation Guide

Lựa chọn giải pháp cài đặt tối ưu Choose the Optimal Setup Method

Step 1

Tải kỹ năng bằng CLI Add Skill via CLI

Chạy lệnh bên dưới tại thư mục gốc dự án của bạn bằng terminal. Thao tác này sẽ tải bộ kỹ năng về thư mục kỹ năng tác nhân cục bộ: Run the command below at your project root. This fetches the harness-kit skill templates into your local agent skills path: 

git clone https://github.com/nguyenanh92/harness-kit.git
# or copy skills/ into your existing skill path
Step 2

Khởi tạo các file mẫu vào dự án Scaffold Harness Files

Chạy tệp python vừa tải xuống để tạo ra khung sườn code cho Harness của bạn: Run the scaffolding script to generate standard-library-only harness templates in your project: 

py .agents/skills/harness-kit/scripts/scaffold_harness.py --target harness
Step 1

Tải thư mục kỹ năng Download Skill Directory

Tải hoặc clone dự án từ GitHub và sao chép trực tiếp thư mục `skills/` vào thư mục `skills/` trong dự án của bạn. Download or clone this repository and manually copy the `skills/` folder into your target project's `skills/` directory.

Step 2

Sử dụng python package chạy scaffolding Run Scaffolding via Python Module

Mã nguồn có thể khởi tạo trực tiếp thông qua module Python nội bộ: Scaffold template files using Python module execution syntax: 

py -m skills.scripts.scaffold_harness --target harness
Step 1

Clone và chạy cục bộ Clone and Enter Directory

Nếu bạn muốn chỉnh sửa, đóng góp mã nguồn hoặc phát triển cục bộ trong harness-kit: Clone the repository to make local changes, debug, or contribute to harness-kit development: 

git clone https://github.com/nguyenanh92/harness-kit.git
cd harness-kit
Step 2

Khởi tạo và chạy test cục bộ Initialize and Validate Locally

Bạn có thể tạo ra các thư mục test để thử nghiệm trực tiếp: Create test folders and perform structural harness scoring to inspect changes locally: 

py skills/scripts/scaffold_harness.py --target test_run
py skills/scripts/validate_harness.py --target test_run
Tích Hợp Với IDE IDE Integration

Cài đặt cho Claude Code, Cursor, Antigravity, OpenAI Codex Install for Claude Code, Cursor, Antigravity, OpenAI Codex

Mỗi IDE đọc skill theo cách riêng. Bảng dưới chỉ rõ đường dẫn cài đặt, lệnh sao chép, và cách kích hoạt cho từng môi trường. Each IDE discovers skills differently. The tabs below show the exact install path, copy command, and how each environment picks up the harness-kit.

Yêu cầu:Prerequisite: Claude Code đã cài (npm install -g @anthropic-ai/claude-code) và đã đăng nhập bằng claude. Xem docs.claude.com/en/docs/claude-code. Claude Code installed (npm install -g @anthropic-ai/claude-code) and authenticated via claude. See docs.claude.com/en/docs/claude-code.

Step 1

Sao chép skill vào thư mục Claude Code Copy the skill into the Claude Code skills directory

Claude Code tự phát hiện skill qua frontmatter trong SKILL.md. Cài user-level để mọi project đều dùng được, hoặc project-level cho riêng từng dự án. Claude Code auto-discovers skills via the YAML frontmatter in SKILL.md. Install at the user level so every project can use it, or scope it to a single project. 

# Windows (user-level)
Copy-Item -Recurse "skills" "$env:USERPROFILE\.claude\skills\harness-kit"

# macOS / Linux (user-level)
cp -r skills ~/.claude/skills/harness-kit

# Project-level (any OS)
cp -r skills ./.claude/skills/harness-kit
Step 2

Kích hoạt skill trong chat Activate the skill from chat

Claude Code tự phát hiện skill ngay trong phiên hiện tại — không cần restart (chỉ cần restart nếu thư mục skills/ được tạo mới hoàn toàn). Gõ trigger như "use harness-kit to scaffold a Python agent harness". Claude Code auto-discovers the skill within the current session — no restart needed (only required if the top-level skills/ directory didn't exist at session start). Trigger with a prompt like "use harness-kit to scaffold a Python agent harness".

Step 3

Chạy scaffold ngay trong chat Run scaffolding directly from chat

Claude sẽ gọi script bằng đường dẫn tuyệt đối tới skill đã cài. Bạn cũng có thể chạy thủ công: Claude will invoke the script via the absolute path of the installed skill. You can also run it manually: 

py "$env:USERPROFILE\.claude\skills\harness-kit\scripts\scaffold_harness.py" --target harness

Yêu cầu:Prerequisite: Cursor IDE đã cài (tải tại cursor.com/download hoặc winget install Cursor.Cursor / brew install --cask cursor) và đã đăng nhập. Cursor IDE installed (download from cursor.com/download, or winget install Cursor.Cursor / brew install --cask cursor) and signed in.

Step 1

Tạo Cursor Rule cho project Create a Cursor Rule for the project

Cursor không có "skills" nhưng dùng .cursor/rules/*.mdc để inject hướng dẫn vào agent. Copy nội dung SKILL.md thành một rule: Cursor has no "skills" concept, but it injects guidance via .cursor/rules/*.mdc. Convert SKILL.md into a rule: 

# Windows
New-Item -ItemType Directory -Force .cursor\rules | Out-Null
Copy-Item skills\SKILL.md .cursor\rules\harness-kit.mdc

# macOS / Linux
mkdir -p .cursor/rules
cp skills/SKILL.md .cursor/rules/harness-kit.mdc
Step 2

Thiết lập scope của rule Set the rule's scope

Mở .cursor/rules/harness-kit.mdc và bổ sung frontmatter chuẩn Cursor. Khi alwaysApply: true, Cursor sẽ bỏ qua globs và description — rule áp dụng mọi lúc: Open .cursor/rules/harness-kit.mdc and add the Cursor frontmatter. With alwaysApply: true, Cursor ignores globs and description — the rule applies in every context: 

---
description: Standard-library-only Python agent harness conventions
alwaysApply: true
---

Nếu muốn scope theo file thay vì luôn bật, đặt alwaysApply: false và dùng globs dạng chuỗi phân tách bằng dấu phẩy (không phải YAML array): To scope by file type instead of always-on, set alwaysApply: false and use globs as a comma-separated string (not a YAML array): 

---
description: Standard-library-only Python agent harness conventions
globs: **/*.py, AGENTS.md, feature_list.json, progress.md
alwaysApply: false
---
Step 3

Đồng bộ scaffold vào project Scaffold the templates into the project

Chạy script scaffold để có sẵn các file mẫu Cursor agent có thể đọc/chỉnh: Run the scaffolder so Cursor's agent has the template files to read and edit: 

py skills/scripts/scaffold_harness.py --target harness

Yêu cầu:Prerequisite: Antigravity đã cài (tải tại antigravity.google, có bản cho Windows / macOS / Linux) và đã đăng nhập bằng tài khoản Google. Antigravity installed (download from antigravity.google for Windows / macOS / Linux) and signed in with a Google account.

Step 1

Scaffold AGENTS.md vào gốc dự án Scaffold AGENTS.md into the project root

Antigravity (Google, convention 2026) đọc AGENTS.md ở gốc dự án (chuẩn cross-tool, dùng chung với Cursor / Claude Code / Codex). Scaffold đặt sẵn AGENTS.md, feature_list.json, progress.md, init.sh/init.ps1 ngay ở root: Antigravity (Google, 2026 convention) reads AGENTS.md at the project root as the cross-tool standard (shared with Cursor / Claude Code / Codex). The scaffolder drops AGENTS.md, feature_list.json, progress.md, and init.sh/init.ps1 there: 

py skills/scripts/scaffold_harness.py --target .
Step 2

Bật skill native qua .agents/skills/ Enable native skills via .agents/skills/

Antigravity còn hỗ trợ thư mục native .agents/ gồm agents.md (persona), skills/*.md, và workflows/*.md. Symlink hoặc copy skill harness-kit vào .agents/skills/ để agent có thể gọi như một slash-skill: Antigravity also supports a native .agents/ folder containing agents.md (persona), skills/*.md, and workflows/*.md. Link or copy harness-kit into .agents/skills/ so the agent can invoke it as a slash-skill: 

# Windows
New-Item -ItemType Directory -Force .agents\skills | Out-Null
Copy-Item -Recurse skills .agents\skills\harness-kit

# macOS / Linux
mkdir -p .agents/skills
cp -r skills .agents/skills/harness-kit
Step 3

Kiểm chứng quy trình Verify the workflow

Mở project trong Antigravity, yêu cầu agent: "Đọc AGENTS.md và thực thi feature đang in_progress trong feature_list.json". Agent sẽ chạy init.ps1/init.sh để verify trước khi đánh dấu done. Open the project in Antigravity and prompt: "Read AGENTS.md and execute the in_progress feature from feature_list.json". It will run init.ps1/init.sh for verification before flipping the status to done.

Yêu cầu:Prerequisite: Codex chưa có IDE riêng — Step 1 sẽ cài CLI / extension (đây cũng là consumer đọc skill). Codex has no dedicated IDE — Step 1 installs the CLI / extension, which is also the consumer that reads the skill.

Step 1

Cài Codex CLI hoặc IDE Extension Install the Codex CLI or IDE Extension

OpenAI Codex đọc AGENTS.md ở gốc dự án (và merge cascade từ các thư mục cha), cùng ~/.codex/AGENTS.md cho ghi chú cá nhân toàn cục. Cấu hình runtime nằm ở ~/.codex/config.toml (tách biệt). Extension chính thức của OpenAI hỗ trợ VS Code, Cursor, và Windsurf. OpenAI Codex reads AGENTS.md at the project root (cascading from parent dirs), plus ~/.codex/AGENTS.md for personal global notes. Runtime config lives separately at ~/.codex/config.toml. OpenAI's official IDE extension supports VS Code, Cursor, and Windsurf. 

npm install -g @openai/codex

# Khởi động và đăng nhập bằng ChatGPT Plus / Pro / API key
# Launch and authenticate via ChatGPT Plus / Pro / API key
codex login

# Hoặc cài extension chính thức từ marketplace của:
# Or install the official extension from the marketplace of:
#   - VS Code     (Visual Studio Code Marketplace)
#   - Cursor      (Open VSX)
#   - Windsurf    (Open VSX)

Tham khảo thêm tại developers.openai.com/codex/cli. See developers.openai.com/codex/cli for full setup details.

Step 2

Scaffold AGENTS.md vào root Scaffold AGENTS.md into the root

Giống Antigravity, Codex bắt AGENTS.md ở gốc dự án. Scaffold cài luôn cả governance docs cần cho validator chấm 100/100. Like Antigravity, Codex picks up AGENTS.md from the project root. The scaffolder also drops in the governance docs needed for the validator to score 100/100. 

py skills/scripts/scaffold_harness.py --target .
Step 3

Chạy Codex tại root Launch Codex from the root

Mở terminal tại root dự án, gọi codex. Agent sẽ đọc AGENTS.md và làm theo Definition of Done. Trong VS Code, mở Codex side panel — extension đọc cùng file. Open a terminal at the project root and run codex. The agent reads AGENTS.md and follows the Definition of Done. In VS Code, open the Codex side panel — the extension reads the same file. 

codex   # CLI mode
# or open the Codex side panel inside VS Code