xiaokeer.agent.harness 0.1.0

Agent-first Python CLI harness for xiaokeer solution projects.

xiaokeer-agent-harness

xiaokeer-agent-harness is an agent-first Python CLI harness for building small, focused xiaokeer solution projects without rebuilding infrastructure every time.

It has no business domain. The included workflow commands are a generic, no-op state machine that demonstrates the reusable contracts: JSON output, doctor, plan/execute/resume, manifest persistence, explicit --execute, tests, packaging, GitHub CI, and PyPI publishing.

Identity

Item	Value
GitHub repository	xiaokeer-agent-harness
PyPI package	xiaokeer.agent.harness
Python import namespace	xiaokeer.agent.harness
CLI command	xharness
Initial version	0.1.0
License	MIT

What This Is

Use this repository as the base for future agent-friendly CLI solutions.

Examples:

• copy it to create an Excel processing solution
• copy it to create a small local file server
• copy it to create a file upload receiver
• copy it to create a device, cloud, or filesystem operation tool

The point is to keep future agents focused on business behavior instead of repeatedly designing CLI output, manifests, tests, packaging, and release flow.

Non-Goals

This project is not a business solution, web framework, GUI, TUI, Excel processor, upload server, Android tool, or long-running service.

It does not prescribe which business domain a future project must implement.

Install

After PyPI publication:

pip install xiaokeer.agent.harness

Recommended global CLI install:

pipx install xiaokeer.agent.harness

Local source install:

cd /Users/chongwen002/project/xiaokeer-agent-harness
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .

Commands

xharness --version
xharness doctor
xharness workflow plan
xharness workflow inspect --manifest /path/to/manifest.json
xharness workflow execute --manifest /path/to/manifest.json --execute
xharness workflow resume --manifest /path/to/manifest.json --execute

Agent Workflow

Check readiness:

xharness doctor

Create a no-business plan:

xharness workflow plan --label future-solution

Execute only the created manifest:

xharness workflow execute --manifest /path/to/manifest.json --execute

Resume safely:

xharness workflow resume --manifest /path/to/manifest.json --execute

Agents should read JSON output, exit codes, and manifest state. They should not parse human prose for workflow state.

Default Output

Operational commands default to JSON.

Example doctor shape:

{
  "ok": true,
  "tool": "xiaokeer.agent.harness",
  "tool_version": "0.1.0",
  "checks": [
    {
      "name": "python_version",
      "ok": true,
      "detail": "3.12.0"
    }
  ],
  "next_action": {
    "type": "run_workflow_plan"
  },
  "summary": "doctor_completed"
}

Example plan shape:

{
  "ok": true,
  "tool": "xiaokeer.agent.harness",
  "tool_version": "0.1.0",
  "manifest_path": "/path/to/HarnessRun-20260605-120000/manifest.json",
  "run_dir": "/path/to/HarnessRun-20260605-120000",
  "summary": "plan_created",
  "next_action": {
    "type": "execute_workflow",
    "command": "xharness workflow execute --manifest /path/to/manifest.json --execute"
  }
}

Exit Codes

Code	Meaning
0	success
1	generic error
2	environment or external dependency unavailable
3	empty input, no matching items, or no-op plan
4	copy/write/create failure
5	verification or validation failure
6	destructive action failure
7	manifest or argument mismatch
8	required capability missing

Manifest

The manifest is a stable public contract and uses schema version 1.

Generic run directory shape:

HarnessRun-YYYYMMDD-HHMMSS/
  manifest.json

The current no-business workflow stores:

• schema_version
• tool
• tool_version
• run_id
• created_at
• state
• selection
• destination
• items
• errors
• warnings

Future solution projects may extend the manifest while preserving schema compatibility or explicitly introducing a new schema version.

Development

cd /Users/chongwen002/project/xiaokeer-agent-harness
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip build twine
python -m pip install -e .
python -m unittest discover tests -v
python -m build
python -m twine check dist/*

Automated tests use fakeable boundaries and must not require real external systems.