# Codex Harness CLI

Thin CLI for initializing and driving a Codex Harness project from npm. The published package embeds its own `package-source/` and only falls back to GitHub Release assets when the embedded package source is unavailable.

## Install

### Use with `npx`

适合一次性初始化或临时验证：

```powershell
npx @pzy560117/codex-harness init
```

### Global install

适合长期在本机重复使用：

```powershell
npm install -g @pzy560117/codex-harness
```

安装后命令名是：

```powershell
harness
```

执行 `harness init` 时如果发现 `%USERPROFILE%\\.codex\\packages\\codex-harness\\` 的用户级 package cache 缺失或版本落后，会先自动刷新这层共享缓存，再继续项目初始化。

## Quick Start

### 1. 初始化当前项目

在目标项目根目录执行：

```powershell
harness init
```

如果当前目录还不是 Git 仓库，CLI 会调用安装器并按默认策略初始化项目所需的 Harness runtime。
如果用户级 package cache 版本落后，CLI 会先自动补齐 `install-user.ps1` 对应的共享缓存。

### 2. 运行 doctor

```powershell
harness doctor
```

这会检查：

- runtime 文件是否齐备
- `task.json` 是否可读
- install manifest / lock / config 是否一致
- PowerShell / prompts / rules / trace schema 是否健康

### 3. 运行 verify

```powershell
harness verify
```

这是包级 sanity check，至少会做 `git diff --check`，并校验 hooks、PowerShell 语法和 package freshness。

### 4. 跑 driver

```powershell
harness run --run-until-done
```

这会转调项目里的：

- `tools/harness/codex-loop.ps1`

主执行链仍然是：

```text
task.json
  -> codex-loop.ps1
  -> review / test / trace / commit
```

## Commands

```powershell
harness init [--version <version>] [--project-root <path>] [--vendor] [--force] [--init-git] [--plan]
harness doctor [--project-root <path>]
harness verify [--project-root <path>]
harness run [--project-root <path>] [--task-file <path>] [--run-until-done]
```

## Common Usage

### 初始化到指定目录

```powershell
harness init --project-root E:\repo\my-project
```

### 只看安装计划，不改文件

```powershell
harness init --plan
```

### 钉住指定版本初始化

```powershell
npx @pzy560117/codex-harness init --version 0.1.14
```

如果要强制使用某个已发布 CLI 版本，推荐直接写成：

```powershell
npx --yes @pzy560117/codex-harness@0.1.14 init
```

适合 release smoke、回滚或验证特定版本的安装语义。

### 对已初始化项目跑检查

```powershell
harness doctor --project-root E:\repo\my-project
harness verify --project-root E:\repo\my-project
```

### 指定任务文件运行

```powershell
harness run --task-file custom-task.json --run-until-done
```

## What `init` installs

默认 `init` 会安装 project scope 的运行面，包括：

- `AGENTS.md`
- `.codex/`
- `tools/harness/`
- `docs/ai/`
- `docs/harness/`
- `docs/spec/`
- `docs/testing/`
- `docs/knowledge/`
- `docs/requirement-prep-kit/`
- `.agents/skills`
- `.agents/workflows`
- `.codex-harness/state|locks|manifests`

安装完成后，建议优先做三件事：

1. 裁剪 `docs/ai/repo-map.md`
2. 裁剪 `docs/ai/architecture-brief.md`
3. 运行 `harness doctor` 和 `harness verify`

## `/goal` usage

如果目标项目准备在 Codex app 中使用 `/goal` 长时间推进，安装完成后优先阅读：

- `docs/codex-harness-engineering/goal-harness-integration-guide.md`
- `docs/codex-harness-engineering/examples/goal-templates.md`

`/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook` 主链。

## Windows notes

- CLI 会优先尝试 `pwsh`，回退到 `powershell`。
- 所有真正的安装/验证/运行动作最后都回到 PowerShell 脚本。
- 如果企业环境限制脚本执行，请优先检查 PowerShell Execution Policy 和企业代理。

## Release Assets

GitHub Release assets are built from the repository package source with:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
```
