# 新项目 Codex Harness 使用指南

本文面向刚创建或刚接入 Harness 的项目。当前版本先跑通单 driver 闭环，不再提供额外执行工作区或外部 worker 编排流程；主控会话负责判断和派发，不直接写仓库文件，需要落盘时转给包内匹配的 writer 子代理。

## 使用路线总览

| 场景 | 推荐入口 | 说明 |
| --- | --- | --- |
| 第一次接入 Harness | `tools\install\init-project.ps1` | 初始化 `AGENTS.md`、`tools/harness/*`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/`、`docs/testing/`、`docs/harness/`、`docs/knowledge/` 和 `docs/requirement-prep-kit/` |
| spec / plan 已确认，准备切主控 | `tools\harness\templates\project-task-template.json` -> `task.json` -> `tools\harness\codex-loop.ps1 -RunUntilDone` | 交互模式在这里结束，后续默认由 driver 接管 |
| 单个需求串行实现 | `tools\harness\codex-loop.ps1 -RunUntilDone` | 一个 Git 工作区里按 `task.json` 优先级逐个完成任务 |
| 需要沉淀项目经验 | `docs/knowledge/knowledge-catalog.md` -> `ARCHIVE-001` | 任务结束后把可复用经验归档为知识条目 |
| 既有项目冷启动知识库 | `docs/harness/knowledge-import.md` | 从 README、docs、代码结构、issue/review 中提取 draft 条目 |
| 维护知识库健康 | `docs/harness/knowledge-lint.md` | 检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目 |
| 连接团队知识库 | `docs/harness/team-knowledge-sync.md` | 把 verified/proven 跨项目候选输出到独立团队知识库的贡献暂存区 |

## 安装模式

安装包由 `install-manifest.json` 声明输出面，治理规则见 `docs/harness/install-manifest-governance.md`。

| 模式 | 命令入口 | 输出内容 |
| --- | --- | --- |
| `project` | `tools\install\init-project.ps1` / `tools\install\install-agent.ps1 -ProjectRoot . -Scope project` | 新默认项目入口，安装项目运行所需 truth source、工程文档模板和 active surface，不复制完整 vendor 镜像 |
| `full` | `tools\install\install-agent.ps1 -Mode full` | 显式 legacy full 入口，同时安装项目 runtime、`.agents/` vendor 包和共享资源 |
| `vendor` | `tools\install\install-agent.ps1 -Mode vendor` / `tools\install\install-agent.ps1 -Scope vendor` | 只复制 `.agents/` vendor 包，适合离线或强隔离场景 |
| `user` | `tools\install\install-user.ps1` / `tools\install\install-agent.ps1 -Scope user` | 只写入 `%USERPROFILE%/.codex/packages/codex-harness/` 下的 package source 和 user lock |

`full` 行为作为显式 legacy 兼容入口保留。当前包已经提供 package lock、只读升级/卸载计划、安全 `-Upgrade` 和 vendor `-Uninstall`。新分层入口优先使用 wrapper 或等价 `-Scope user|project|vendor` 命令：`tools\install\install-user.ps1` 等价于 `tools\install\install-agent.ps1 -Scope user`，`tools\install\init-project.ps1` 等价于 `tools\install\install-agent.ps1 -ProjectRoot . -Scope project`。当前不提供 `harness install-user` 子命令。当前不提供 `harness init-project` 子命令。Windows PowerShell 主链路请直接运行这两个 wrapper，避免误以为存在独立 CLI。`-Scope project` 与无参数 `tools\install\install-agent.ps1 -ProjectRoot .` 等价，默认会安装项目所需 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/ai/`、`docs/architecture/constraints.md`、`docs/spec/01..14`、`docs/testing/`、`docs/harness/`、`docs/knowledge/`、`docs/requirement-prep-kit/` 和 `tools/`，但仍不复制完整 vendor 镜像或 `.agents/` package root 文档源。`-Scope user` 只安装用户级 package source 并写入用户级 lock。

如果你是通过全局 npm CLI 执行 `harness init`，当前实现会先检查 `%USERPROFILE%/.codex/packages/codex-harness/` 的 user package cache；发现缺失或版本落后时，会自动执行等价于 `install-user.ps1` 的刷新，再继续项目初始化。只有在 `harness init --plan` 下，这层缓存不会被改写。

## `docs/ai/` 导航层

初始化后的项目，`docs/ai/` 应作为默认导航层，而不是长期知识库：

- `repo-map.md`
- `architecture-brief.md`
- `CURRENT_TASK.md`
- `PROJECT_CONTEXT.md`
- `DECISIONS.md`
- `API_MAP.md`
- `DB_SCHEMA.md`
- `KNOWN_ISSUES.md`
- `CHANGELOG_AI.md`

推荐顺序：

1. 先裁剪 `repo-map.md` 和 `architecture-brief.md`
2. 再补 `CURRENT_TASK.md`
3. 复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`
4. 把长期可复用经验沉淀到 `docs/knowledge/*`，不要长期堆在 `docs/ai/*`

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-user.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\init-project.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor
```

直接运行 `tools\install\bootstrap-codex-harness.ps1` 或旧 `-Mode project` 仍使用 legacy profile，适合需要保留完整 harness 文档包的旧项目；新项目默认使用 `tools\install\init-project.ps1` 或等价 `-ProjectRoot . -Scope project`。

`tools\harness\doctor.ps1` 会按 `installScope=project` 检查项目输出：缺少 `.codex-harness/manifests/install-manifest.json` 会提示 warning，snapshot JSON 非法、`docs/architecture/constraints.md` 或 `docs/spec/01..14` 缺失会失败；`docs/harness/`、`docs/testing/`、`docs/knowledge/` 和 `docs/requirement-prep-kit/` 现在属于 project scope 正常输出，不再作为 legacy residue warning。

Phase 7 切换门禁先看 doctor 的 readiness 汇总：

- `Readiness gate: PASS` 且 `ProjectShape: thin-project`：项目已满足 thin 前置条件。
- `ProjectShape: thin-project-missing-user-package`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-user.ps1`，再重新运行 `tools\harness\doctor.ps1`。
- `ProjectShape: thin-project-with-legacy-residue` 或 `legacy-full-project`：先运行 `-MigratePlan` 查看分类，再按报告决定是否运行 `-MigrateApply -Confirm`。
- `ProjectShape: vendor-project`：保留 vendor 模式时运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor` 或重新运行 `tools\harness\doctor.ps1` 复核 drift。
- `ProjectShape: not-installed`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\init-project.ps1`。

readiness gate 只读；它只报告阻断项和 `FixCommand`，不会自动安装、迁移、删除或覆盖项目文件。

已有 legacy `.agents/` 项目不要直接清理目录。先运行只读迁移计划：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -MigratePlan
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -MigrateApply
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -MigrateApply -Confirm
```

操作顺序固定为：

- 先跑 `-MigratePlan`，拿到 `adopt-vendor-managed`、`blocked-user-drift`、`missing-vendor-file`、`unknown-legacy-file`、`manual-review` 分类报告。
- 再跑 `-MigrateApply` 做 dry-run，确认计划写入和阻断原因；此时 `actualWrites` 必须为空。
- 只有确认没有阻断项且接受计划写入时，才用显式确认开关执行 `-MigrateApply -Confirm`。

迁移执行默认只允许写 `.codex-harness/locks/package.lock.json` 和必要 `.codex-harness` config/install metadata，不会自动删除 `.agents`，不会覆盖用户文档，也不会处理 legacy docs 自动删除。`adopt-vendor-managed` 只有在确认后才会写入 `managedFiles`；`missing-vendor-file` 只记录缺失，不会凭空安装或删除；`blocked-user-drift`、`unknown-legacy-file`、`manual-review` 都会阻断自动执行。确认结果后再选择保留 `-Scope vendor`，或重新以 `-Scope project` 初始化 thin 输出并手工迁出需要保留的内容。

`-MigratePlan` 和 `-MigrateApply` 的职责要分开理解：前者只做只读分类和报告，后者只做确认式应用。不要把 `-MigrateApply` 当成默认 full 迁移，也不要在没有 `-Confirm` 的情况下期待它写 lock。

如果 `-MigrateApply` 输出 `status=blocked`，先按 `blockedReasons` 处理，再重新跑 `-MigratePlan` 复核分类是否变化。不要把阻断项当成临时 warning 忽略，也不要直接改写 `.agents/` 来规避 drift 分类。

默认安装已在 Phase 7 切到 thin project；迁移执行仍然只处理确认式落锁，不会自动清理 `.agents` 或 legacy docs。后续扩展迁移能力时，必须继续以 `-MigratePlan` 分类结果作为输入语义来源。

## 升级和卸载

已安装项目先用只读计划判断风险：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -UpgradePlan
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -UninstallPlan
```

计划中没有 `blocked-user-drift` 时，才执行写入命令：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Upgrade
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Uninstall
```

`-Upgrade` 只覆盖 lock 记录中未发生用户 drift 的不可变文件，并刷新 `.codex-harness/locks/package.lock.json`。`-Uninstall` 只删除 lock 中 `scope=vendor` 的 managed files，保留 project scope 和 user scope。

如果输出 `blocked-user-drift`，先人工对比目标文件、lock hash 和当前包内容；需要保留的修改应手工合并或迁出，需要放弃的修改应恢复后再重新执行计划。

## 迁移失败处理

`-MigratePlan` 或 `-MigrateApply` 只要出现以下情况，就按失败处理并暂停自动执行：

- `blocked-user-drift`
- `unknown-legacy-file`
- `manual-review`
- `status=blocked`
- `actualWrites` 在 dry-run 阶段非空

处理顺序建议如下：

1. 先看 `blockedReasons` 和 `summaryCounts`，确认阻断来自哪类文件或哪类 drift。
2. 如果是用户改动，先人工迁出或合并，再重新跑 `-MigratePlan`。
3. 如果是 legacy 未分类文件，保留现状，等后续独立任务补逐项确认机制。
4. 如果 dry-run 出现非空 `actualWrites`，说明执行边界异常，停止继续操作并回退到计划阶段排查。

## 1. 初始化

```powershell
git status --short
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\init-project.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\doctor.ps1
```

## 2. 创建任务

```powershell
Copy-Item .\tools\harness\templates\project-task-template.json .\task.json
```

建议 `runtime.git` 使用：

```json
{
  "require_clean_workspace": true,
  "non_blocking_dirty_paths": []
}
```

## 3. 运行 Driver

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

### 3.1 内容门禁怎么配

建议在项目 `task.json` 里显式写出默认门禁档位：

```json
{
  "runtime": {
    "content_gates": {
      "default_mode": "core"
    }
  }
}
```

门禁分层：

- `core`：默认档位，适合新项目冷启动
- `recommended`：适合团队已经稳定维护文档和测试 truth source 的项目
- `full`：只适合非常重治理的项目，不建议作为新项目默认值
- `risk_tags`：只给高风险任务启用专项门禁，例如 `security`、`data`、`integration`、`mobile`

示例：

```json
{
  "id": "ORDER-001",
  "task_kind": "feature_impl",
  "risk_tags": ["security", "data"]
}
```

- `.codex/agents/*.toml` 同时提供只读辅助子代理和写入型 worker 子代理。
- 这些子代理开始前必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`、`.codex/rules/agents.md` 和对应 `.agents/skills/*/SKILL.md`（如存在）。
- 如果是被 stop hook 拦下后继续执行的下一轮，也先按上面这组文档重读一遍，再决定是否启用子代理。
- 如果主控需要更新 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*`、prompt 或其他非 driver 内容，必须委派 `harness-writer`、`docs-worker` 或匹配的实现 worker，不能由主控会话自己写。
- 目标项目的 `.agents/` 默认不再复制项目运行时用的 `.codex/` 或 `docs/harness/`；这些内容直接安装到项目根。为了支持安装后的再次 bootstrap，`.agents/docs/codex-harness-engineering/templates/` 会保留模板复制源。
- `docs/ai/` 是项目导航层；默认先读 `repo-map.md`、`architecture-brief.md`、`CURRENT_TASK.md`，再决定是否进入 `docs/harness/*`、`docs/knowledge/*` 或外部知识。
- `docs/knowledge/` 是项目级知识层；实现会话按 `knowledge-catalog.md`、`catalog.md`、具体条目的顺序按需读取，归档任务负责更新索引。
- 已有项目接入时，可先按 `docs/harness/knowledge-import.md` 冷启动 5-13 条 draft 知识；导入过程用 `import-state.json` 或导入报告记录 processed/pending/skipped/low_confidence 来源和 resume cursor，后续任务通过引用和验证逐步提升成熟度。
- 每隔一段任务后，按 `docs/harness/knowledge-lint.md` 检查索引一致、重复、冲突和长期未引用条目。
- 如果团队维护独立知识库，按 `docs/harness/team-knowledge-sync.md` 把跨项目候选写入 `contributions/pending/`；该同步失败只能降级为候选报告，不能阻塞本地实现验证。
- 如果需要接入 MCP、外部文档或代码语义工具，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`，避免把查询结果直接升级为项目规则。

## 4. UI 项目要求

- 保存设计参考图。
- 保存真实浏览器截图。
- 输出视觉对比报告。
