@pzy560117/codex-harness 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Codex Harness CLI
 
-Thin CLI for downloading a Codex Harness package source and invoking the PowerShell runtime/install scripts.
+Thin CLI for invoking the PowerShell runtime/install scripts. Published npm packages embed the package source directly and only fall back to GitHub Release downloads when the embedded package source is unavailable.
 
 ## Commands
 

package/lib/commands/init.js

@@ -23,8 +23,13 @@ function getLocalPackageRoot() {
   return path.resolve(import.meta.dirname, "..", "..", "..");
 }
 
+function getCliPackageRoot() {
+  return path.resolve(import.meta.dirname, "..", "..");
+}
+
 export async function initCommand(options) {
   const localPackageRoot = getLocalPackageRoot();
+  const embeddedPackageRoot = path.join(getCliPackageRoot(), "package-source");
   const projectRoot = detectProjectRoot(options.projectRoot);
   const userProfile = process.env.USERPROFILE;
   if (!userProfile) {
@@ -33,6 +38,7 @@ export async function initCommand(options) {
 
   const packageRoot = resolvePackageSourceRoot({
     packageRoot: localPackageRoot,
+    embeddedRoot: embeddedPackageRoot,
     cachedRoot: "",
     fsLike: { existsSync: fileExists }
   });
@@ -87,7 +93,7 @@ export async function initCommand(options) {
     args.push("-Force");
   }
 
-  if (options.initGit) {
+  if (options.initGit !== false) {
     args.push("-InitGitIfNeeded");
   }
 

package/lib/release/resolve-package-source.js

@@ -1,12 +1,17 @@
 import path from "node:path";
 
-export function resolvePackageSourceRoot({ packageRoot, cachedRoot, fsLike }) {
+export function resolvePackageSourceRoot({ packageRoot, embeddedRoot = "", cachedRoot, fsLike }) {
   const existsSync = fsLike?.existsSync ?? (() => false);
   const localScript = path.win32.join(packageRoot, "tools", "install", "install-agent.ps1");
   if (existsSync(localScript)) {
     return packageRoot;
   }
 
+  const embeddedScript = path.win32.join(embeddedRoot, "tools", "install", "install-agent.ps1");
+  if (embeddedRoot && existsSync(embeddedScript)) {
+    return embeddedRoot;
+  }
+
   const cachedScript = path.win32.join(cachedRoot, "tools", "install", "install-agent.ps1");
   if (existsSync(cachedScript)) {
     return cachedRoot;

package/package-source/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+本文件只保留每次会话都必须知道的 Harness 入口规则。细节按需读取下方深文档，不把长期协议全部塞进入口文件。
+
+## 核心入口
+
+- 本仓库默认采用 `driver-first`：真实任务进入 `task.json`，由 `tools/harness/codex-loop.ps1` 逐个执行。
+- `single task` 是当前唯一自动执行模式；每轮 driver 只处理一个 `passes: false` 且依赖已通过的任务。
+- 交互开发模式只负责需求收敛、分析、规划和任务输入；方案确认后，默认回到 `task.json -> tools/harness/codex-loop.ps1`。
+- 主控会话不直接维护仓库状态文件；`task.json`、`progress.txt`、`traces/` 和 Git 提交由 runtime 链路推进。
+- 需要落盘规则、任务、文档、前端、后端或测试内容时，先确认 truth source，再委派匹配的 writer 子代理或进入 driver 任务。
+
+## 硬约束
+
+- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务；可再生运行产物只能通过 `runtime.git.non_blocking_dirty_paths` 列白名单。
+- 不要伪造完成状态：不得手工把未验证任务标记为 `passes: true`，不得绕过 `test_command`、review gate 或 commit gate。
+- 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
+- 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
+- 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
+- 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
+- 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
+- `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。
+- Stage 1 Review 先审声明的架构约束符合性，再审业务规格；仅当任务要求架构门禁且约束缺失或实现冲突时 FAIL。
+- 阻塞时追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。
+
+## 阶段更新规则
+
+- Stage 01 初始化：更新 `task.json`、`AGENTS.md`、项目路径和验证命令。
+- Stage 02 需求收敛：更新 `docs/product/`、Requirement IDs、验收标准和可执行验收示例。
+- Stage 03 追溯与架构约束：更新架构约束 truth source、测试追溯矩阵和证据协议。
+- Stage 09 DEV-PLAN / 任务拆分：把架构约束、禁止实现和验证命令写入每个相关 `feature_impl`。
+- Stage 10-14 实现与集成：只更新任务 owned paths 内的实现、测试和证据。
+- Stage 15-16 Review：保持只读审查，输出 findings、证据和 repair queue。
+- Stage 17 Verify / Regression：刷新验证证据，不在本阶段第一次补需求或测试范围。
+- Archive：更新 `docs/knowledge/`、索引和可复用经验，不升级一次性结论为全局规则。
+
+## 必读索引
+
+- 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,81 @@
+# 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/`
+- 项目根 `docs/harness/`、`docs/testing/`
+- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
+
+## 使用顺序
+
+1. 读取项目根 `AGENTS.md`。
+2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
+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/README.md

@@ -0,0 +1,20 @@
+# Templates README
+
+当前模板集只保留单工作区、单 driver 的最小闭环。
+
+## 主要目录
+
+- `runtime/`: 项目根运行入口、driver、doctor、任务队列、运行策略、验证脚本
+- `config/`: 全局与项目级配置示例
+- `docs/`: 会复制到项目 `docs/harness/` 的文档模板，也包含 `project-agents-template.md` 这种按项目事实生成 `AGENTS.md` 的通用规则模板
+- `design/`: 前端先行链路的设计 brief、图转前端规格、组件映射、状态矩阵、视觉评审、前端架构和 design tokens 模板
+- `testing/`: 测试左移模板，包含验收标准、验收示例、追溯矩阵、测试数据、回归计划、失败归因和 verify 矩阵
+- `prompts/`: driver、review、visual、failure、repair 使用的提示词模板
+- `trace/`: trace 与 schema 示例
+- `package-assets/`: 会复制到目标项目 `.agents/` 的能力包与安装入口镜像
+
+已移除：
+
+- 额外执行工作区脚本
+- 外部 worker 编排模板
+- 控制面状态模板