# Codex Harness Agent Package

本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。

SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。

## 云端 CLI 安装

全局安装：

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

一次性使用：

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

项目内常用命令：

```powershell
harness init
harness doctor
harness verify
harness run
```

`harness init` 优先使用 npm 包内置的 `package-source/` 完成初始化；只有在 npm 包未携带内置 source 时，才回退到 GitHub Release 下载 package source 到 `%USERPROFILE%\.codex\packages\codex-harness\<version>\`。项目级 `.agents/skills/` 与 `.agents/workflows/` 仍只安装到当前项目，不会提升成全局 active surface。

## 本地源码安装

从包含 `agent/` 包目录的项目父目录运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
```

从已安装的 `.agents/` 自更新：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
```

## 安装产物

- 项目根 `AGENTS.md`
- `tools/harness/` 下的 `codex-loop.ps1`、`doctor.ps1`、`verify.ps1`
- `tools/install/` 下的 `bootstrap-codex-harness.ps1`、`env-check.ps1`、安装脚本
- 项目根 `task.json`、`progress.txt`
- `tools/harness/templates/` 下的 `smoke-task.json`、`project-task-template.json`
- `docs/harness/trace.schema.json`
- 项目根 `.codex/`
- 项目根 `.agents/` active surface，包括 skills、workflows 和安装后需要的运行辅助面

说明：

- 默认 `thin project` 安装不会把 `docs/harness/`、`docs/testing/`、`docs/knowledge/` 整包复制到项目根。
- 这些深文档默认位于 `.codex-harness/state/config.json` 里的 `packageRoot` 下；只有显式 `-Mode full` / legacy full 场景才会在项目根保留完整副本。

## 使用顺序

1. 读取项目根 `AGENTS.md`。
2. 如果项目根存在 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*`，直接读取；若是 thin project 且这些文件缺失，则先读 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下读取同路径文件。
3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
4. 将确认后的任务写入 `task.json`。
5. 运行：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1
```

## 验证安装包

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

发布产物会输出到 `dist/release/<version>/`，包含：

- `codex-harness-<version>-win.zip`
- `codex-harness-<version>-win.sha256`
- `release-manifest.json`
