# Repo Map

更新时间: 2026-05-20
维护责任: Harness package maintainer

## 1. 仓库目标

- 项目一句话描述: Codex Harness 安装实现包，用于把 AGENTS、driver、rules、prompts、skills、hooks、testing truth source 和 package docs 安装到目标项目。
- 主要用户: 在 Windows / PowerShell 环境中使用 Codex CLI 的项目维护者和自动化执行 agent。
- 核心业务域: driver-first 任务执行、安装包分发、规则治理、测试左移、知识沉淀、agent 能力同步。

## 2. 从哪里开始读

- 第一步先读: `AGENTS.md`
- 第二步再读: `docs/ai/architecture-brief.md`
- 第三步按任务进入:
  - 安装链路: `tools/install/install-agent.ps1`, `tools/install/bootstrap-codex-harness.ps1`
  - driver 链路: `tools/harness/codex-loop.ps1`, `.codex/prompts/*`
  - 分发同步: `refresh-agent-package.ps1`, `.ai-sync.yml`
  - 规则治理: `docs/harness/rule-governance.md`
  - 包文档: `docs/codex-harness-engineering/*`

## 2.1 上下文索引最小字段

- 代码入口: 关键命令、路由、脚本或页面入口
- 上游调用方: 谁会触发这个入口
- 下游依赖: 入口继续调用哪些模块、脚本或接口
- 类型/契约入口: 类型定义、contract、schema 或导出面
- 测试入口: 关联测试、验证命令或证据目录
- 配置入口: `.codex/*`、环境变量、配置文件、manifest
- 风险入口: 权限、状态流转、安装升级、同步、数据边界
- 禁改区: 当前任务默认不要碰的区域

## 3. 关键目录

| 路径 | 用途 | 可修改性 | 备注 |
| --- | --- | --- | --- |
| repo root | 当前安装包包根 | 可改 | 新项目安装时主要来源 |
| `.agents/` | 当前仓库活跃 package / skills 镜像 | 可改 | skills 以这里为活跃 canonical |
| `.codex/` | 当前仓库 Codex roles、prompts、rules | 可改 | active role rules 以 `.codex/rules/agents.md` 为 canonical |
| `docs/harness/` | driver、规则、知识、回归等深文档 | 可改 | root truth source |
| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
| `docs/ai/` | AI 导航索引和架构摘要 | 可改 | 大型项目导航层 |
| `docs/codex-harness-engineering/templates/` | 安装模板源 | 可改 | 会影响新项目 bootstrap |
| `docs/codex-harness-engineering/templates/package-assets/` | 安装到目标 `.agents/` 的能力包 | 可改 | 需同步 `.agents` 镜像 |
| `scripts/` | 辅助验证和同步脚本 | 谨慎 | 修改后做 PowerShell parser 检查 |

## 4. 关键依赖关系

- root runtime -> `refresh-agent-package.ps1` -> templates / package-assets mirrors。
- root docs -> `templates/package-assets/docs/codex-harness-engineering/` -> 目标项目 `.agents/docs/...`。
- `.agents/skills/<name>` -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` -> package-assets skill mirrors。
- `tools/install/bootstrap-codex-harness.ps1` -> 目标项目根 runtime、`.codex/`、`docs/harness/`、`docs/testing/`、`docs/ai/`。

## 5. 常用命令

```powershell
git status --short
git diff --check
powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
```

## 6. 禁改区

- 禁止手工伪造 `task.json` 的 `passes=true`；应让 driver 验证后写回。
- 禁止跳过 package mirrors：涉及 `.agents/`、templates、package-assets、skills 的改动必须按同步矩阵刷新。
- 禁止把 token、cookie、私钥、密码写入 docs、trace、prompt 或 package。
- 禁止在未确认时使用破坏性 Git 命令或递归删除。

## 7. 任务入口

- Feature plan 所在位置: `task.json` 或 `tools/harness/templates/project-task-template.json`
- Product docs 所在位置: `docs/product/` 或 `docs/requirement-prep-kit/`
- Design docs 所在位置: `docs/codex-harness-engineering/templates/design/`
- Contract 所在位置: `docs/codex-harness-engineering/templates/contracts/`

## 7.1 调用链与影响面提示

- 关键调用链:
  - 安装: `tools/install/*` -> `docs/codex-harness-engineering/templates/*` / `package-assets/*`
  - driver: `tools/harness/codex-loop.ps1` -> `.codex/prompts/*` -> `task.json` / `docs/testing/*`
  - 同步: `refresh-agent-package.ps1` -> `.agents/*` / templates / package-assets
- 影响面分析时至少回答:
  - 入口在哪里
  - 上游是谁
  - 下游是谁
  - 受影响文件有哪些
  - 受影响测试和验证命令有哪些

## 8. 子目录规则索引

| 路径 | 本地规则 | 触发场景 |
| --- | --- | --- |
| repo root | `AGENTS.md` | 验证安装包入口规则和可分发文件 |
| `.agents/` | `.agents/AGENTS.md` | 修改活跃 skills / workflows 镜像 |

## 9. 维护规则

- 新增安装时应落地的模板文件时，同时检查 `tools/install/bootstrap-codex-harness.ps1` 和 `.ai-sync.yml`。
- 新增 package docs 时，同时更新 `docs/codex-harness-engineering/README.md` 和 package-assets 镜像。
- 更新 skills 时，以 `.agents/skills/<name>` 为 canonical，再同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 package-assets。
