@pzy560117/codex-harness 0.1.4 → 0.1.5

package/README.md

@@ -103,7 +103,7 @@ harness init --plan
 ### 钉住远程版本初始化
 
 ```powershell
-npx @pzy560117/codex-harness init --version 0.1.4
+npx @pzy560117/codex-harness init --version 0.1.5
 ```
 
 适合 release smoke 或回滚到某个已发布版本。

package/package-source/AGENTS.md

@@ -0,0 +1,48 @@
+## 模板优先
+
+- 需要影响新项目 bootstrap、生成物结构、默认导航层、默认 prompt、默认规则、默认技能、默认上下文模板时，先修改模板 canonical：
+  - `docs/codex-harness-engineering/templates/`
+  - `tools/harness/templates/`
+  - `docs/codex-harness-engineering/templates/package-assets/`
+- 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
+- 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。
+
+## 目录级规则
+
+- 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
+  - 目录有独立模块职责或技术栈
+  - 目录存在与全仓不同的架构边界
+  - 目录有独立入口文件、测试命令或验证方式
+  - 目录反复出现相同 review 问题、坑点或禁止事项
+- 子目录 `AGENTS.md` 应重点写：
+  - 该目录负责什么 / 不负责什么
+  - 入口文件和核心文件
+  - 修改前必须先看的文件
+  - 本目录的局部架构规则和复用模式
+  - 测试 / 构建 / 验证命令
+  - 常见坑和禁止事项
+- `docs/ai/repo-map.md` 及模板中的 repo-map 应维护“子目录规则索引”，明确哪些路径已有本地规则、适用于什么场景。
+
+## 必读索引
+
+如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。
+
+- Harness 分层分析索引：`harness-analysis/README.md`
+- Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.md`
+- Codex 宿主自动加载机制：`docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
+- Codex 自动加载优化清单：`harness-analysis/10-codex-autoload-optimization-checklist.md`
+- Harness 架构：`docs/harness/architecture.md`
+- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
+- 新项目使用：`docs/harness/new-project-usage.md`
+- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
+- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
+- 回归与验证策略：`docs/harness/regression-rules.md`
+- Trace 格式：`docs/harness/trace-format.md`
+- 权限策略：`docs/harness/sandbox-policy.md`
+- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`
+
+## 当前在做的事情
+
+- 正在持续分析当前仓库里的 Codex 宿主层、Harness 控制层、安装工程和桥接层。
+- 当前重点是把“哪些内容会被 Codex 自动加载到上下文、哪些只是运行配置、哪些是 Harness runtime 二次读取”彻底拆清。
+- 所有新增分析文档统一落在 `harness-analysis/`，方法论和模板级说明补充到 `docs/codex-harness-engineering/`。

package/package-source/PACKAGE.md

@@ -0,0 +1,49 @@
+# Codex Harness Package
+
+## Mode Policy
+
+当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
+
+保留的入口：
+
+- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
+- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
+- `-Scope vendor`：显式 vendor 入口，只复制项目内 `.agents/` vendor 包，适合离线或强隔离项目。
+- `-Mode full`：显式 legacy full 兼容入口，同时输出项目 runtime、完整 `.agents/` vendor 包和 legacy docs。
+- `-Mode project|vendor|user`：保留旧兼容入口；新项目优先使用 `-Scope user|project|vendor`。
+
+默认 thin project 不会自动删除旧项目已有 `.agents/` 或 legacy docs。旧项目迁移前先运行 `-MigratePlan`，确认后再运行 `-MigrateApply -Confirm`；也可以显式保留 `-Scope vendor` / `-Mode full`。
+
+## Install
+
+新项目默认安装：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+```
+
+显式 thin project：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope project
+```
+
+显式 legacy full：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
+```
+
+显式 vendor：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor
+```
+
+## Smoke
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
+```
+
+该 smoke 覆盖默认 thin project、显式 legacy full、`-Scope project`、`-Scope vendor`、`-Scope user` 和 legacy plan 兼容入口。

package/package-source/README.md

@@ -0,0 +1,85 @@
+# 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`

package/package-source/docs/codex-harness-engineering/templates/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+## 作用范围
+
+- 本文件适用于 `docs/codex-harness-engineering/templates/` 整个模板树。
+- 进入子目录后，继续读取该子目录自己的 `AGENTS.md`。
+
+## 目录作用
+
+- 这里是当前仓库最重要的模板 canonical 源。
+- 影响 bootstrap、driver、docs、rules、prompt、truth source、package-assets 的改动，默认都先发生在这里。
+
+## 结构索引
+
+- `README.md`：模板目录总览。
+- `bootstrap-codex-harness.ps1`：模板安装 / 复制主入口。
+- `ci/`：CI 工作流模板。
+- `config/`：配置示例、rules、agent 定义。
+- `context/`：`docs/ai/*` 和计划上下文模板。
+- `contracts/`：契约优先模板。
+- `design/`：前端设计与图转前端规格模板。
+- `docs/`：会复制到 `docs/harness/` 的说明文档模板。
+- `governance/`：治理策略、风险分级、保护清单。
+- `hooks/`：hook 模板。
+- `knowledge/`：知识层模板。
+- `package-assets/`：镜像到目标项目 `.agents/` 或相关文档面的资产。
+- `product/`：产品预研 / 测试左移素材模板。
+- `prompts/`：driver、review、worker prompt 模板。
+- `runtime/`：driver、task、verify、doctor 等运行面模板。
+- `scripts/`：辅助脚本模板。
+- `spec/`：默认 `docs/spec/*` 规格模板。
+- `testing/`：测试真相源模板。
+- `tools/`：内容门禁脚本模板。
+- `trace/`：trace schema 和样例。
+
+## 特殊说明
+
+- `runtime/AGENTS.md` 已经是“安装到目标项目根目录的 AGENTS 模板内容”，不要把它改造成目录级导航文件。
+- `config/global-AGENTS.md` 是全局规则示例，不是本目录本地规则。
+
+## 修改前先看
+
+- `README.md`
+- `bootstrap-codex-harness.ps1`
+- `../doc-update-map.md`
+
+## 修改规则
+
+- 改动模板时，优先确认是否还需要同步当前仓库活跃副本、`tools/install/bootstrap-codex-harness.ps1`、`docs/harness/*` 或 package-assets 镜像。
+- 不要只修某个镜像副本而漏掉模板 canonical。
+- 如果一个目录已经有交付用同名文件（例如 `runtime/AGENTS.md`），目录规则写在上级 `AGENTS.md`，不要覆写交付模板。