@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/config/codex-readme.md

@@ -4,9 +4,9 @@
 
 ## 文件职责
 
-- `config.toml`: Codex 项目配置、少量稳定子代理注册、profile 模板。
+- `config.toml`: Codex 项目配置、少量稳定子代理注册、profile 模板。
 - `hooks.json`: Codex lifecycle hooks 增强层。driver 仍以 PowerShell 脚本为主链路。
-- `task-run-profile.json`: `tools/harness/codex-loop.ps1` 读取的任务会话、子代理和工作区策略。
+- `task-run-profile.json`: `tools/harness/codex-loop.ps1` 读取的任务会话、子代理和工作区策略。
 - `agents/`: 少量可长期复用的辅助角色，包含只读分析角色和 scoped writer roles。
 - `prompts/`: driver、worker-role、review、failure triage 使用的提示词模板。
 
@@ -44,11 +44,11 @@
 - `backend-worker`: API、数据模型、校验、权限和后端测试写入。
 - `test-runner`: 验证证据、测试报告和 failure findings 写入。
 
-执行型工作仍应优先走 `task.json` + `tools/harness/codex-loop.ps1` 的单任务 driver 流程。只有当 controller / 主会话遇到非 driver 的落盘任务时，才转给匹配的 writer 子代理；reviewer、researcher、planner 之类角色仍保持只读。
+执行型工作仍应优先走 `task.json` + `tools/harness/codex-loop.ps1` 的单任务 driver 流程。只有当 controller / 主会话遇到非 driver 的落盘任务时，才转给匹配的 writer 子代理；reviewer、researcher、planner 之类角色仍保持只读。
 
-## Profile 使用
-
-当前项目模板默认启用 `features.goals = true`，这样 Codex app 可以显示 `/goal`。这只是在产品层打开长期目标控制面，不改变 Harness 的主执行协议；仓库推进仍应回到 `task.json + tools/harness/codex-loop.ps1 + stop hook`。
+## Profile 使用
+
+当前项目模板默认启用 `features.goals = true`，这样 Codex app 可以显示 `/goal`。这只是在产品层打开长期目标控制面，不改变 Harness 的主执行协议；仓库推进仍应回到 `task.json + tools/harness/codex-loop.ps1 + stop hook`。
 
 包内 `profiles.*` 是安装后的推荐配置模板，不保证 `codex -C <path> -p <profile>` 在所有调用场景都会自动读取项目 `.codex/config.toml`。
 

package/package-source/docs/codex-harness-engineering/templates/config/env-check.ps1

@@ -1,40 +1,44 @@
-param(
-  [string[]]$RequiredCommands = @("git", "codex"),
-  [string[]]$RequiredEnvVars = @()
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
-
-function Assert-CommandExists {
-  <#
-    检查命令是否存在。
-  #>
-  param([string]$Name)
-
-  if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
-    throw "缺少必需命令: $Name"
-  }
-}
-
-function Assert-EnvVarExists {
-  <#
-    检查环境变量是否存在且非空。
-  #>
-  param([string]$Name)
-
-  $value = [Environment]::GetEnvironmentVariable($Name)
-  if ([string]::IsNullOrWhiteSpace($value)) {
-    throw "缺少必需环境变量: $Name"
-  }
-}
-
-foreach ($command in $RequiredCommands) {
-  Assert-CommandExists -Name $command
-}
-
-foreach ($envVar in $RequiredEnvVars) {
-  Assert-EnvVarExists -Name $envVar
-}
-
-Write-Output "Environment check passed."
+param(
+  [string[]]$RequiredCommands = @("git", "codex"),
+  [string[]]$RequiredEnvVars = @()
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+function Assert-CommandExists {
+  <#
+    检查命令是否存在。
+  #>
+  param([string]$Name)
+
+  if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+    throw "缺少必需命令: $Name"
+  }
+}
+
+function Assert-EnvVarExists {
+  <#
+    检查环境变量是否存在且非空。
+  #>
+  param([string]$Name)
+
+  $value = [Environment]::GetEnvironmentVariable($Name)
+  if ([string]::IsNullOrWhiteSpace($value)) {
+    throw "缺少必需环境变量: $Name"
+  }
+}
+
+foreach ($command in $RequiredCommands) {
+  Assert-CommandExists -Name $command
+}
+
+foreach ($envVar in $RequiredEnvVars) {
+  Assert-EnvVarExists -Name $envVar
+}
+
+Write-Output "Environment check passed."
+
+# 约束说明:
+# - 这里只检查“变量是否存在”，不承载变量语义。
+# - 变量用途、环境差异、部署注入方式和回滚策略应记录在 `docs/harness/env-and-deployment-template.md`。

package/package-source/docs/codex-harness-engineering/templates/config/env.example

@@ -1,12 +1,13 @@
-# Codex 自动化环境变量模板
-# 复制为 `.env.local`、CI secret 或 runner 环境变量，禁止提交真实密钥。
-
-OPENAI_API_KEY=
-CODEX_API_KEY=
-FIGMA_OAUTH_TOKEN=
-GITHUB_TOKEN=
-
-# 项目自定义
-DATABASE_URL=
-REDIS_URL=
-APP_BASE_URL=http://localhost:3000
+# Codex 自动化环境变量模板
+# 复制为 `.env.local`、CI secret 或 runner 环境变量，禁止提交真实密钥。
+# 每个变量的用途、是否必填、环境差异和示例值，补充到 `docs/harness/env-and-deployment-template.md`。
+
+OPENAI_API_KEY=
+CODEX_API_KEY=
+FIGMA_OAUTH_TOKEN=
+GITHUB_TOKEN=
+
+# 项目自定义
+DATABASE_URL=
+REDIS_URL=
+APP_BASE_URL=http://localhost:3000

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

@@ -1,40 +1,40 @@
-# Global AGENTS.md
-
-## 通用工作原则
-
-- 默认使用简体中文输出。
-- 在没有验证证据前，不要声称任务已完成。
-- 先阅读代码和文档，再修改文件。
-- 开始实现前，先确认验收标准、测试入口和完成证据路径。
-- 尽量保持改动范围小且可审计。
-
-## 工具与命令规则
-
-- 先用 `Get-Command` 检查命令是否存在。
-- 命令不存在时优先使用已知绝对路径，不盲目重装工具。
-- 搜索文件优先使用 `rg` 或 `rg --files`。
-- 不要用内联脚本绕过正常文件和脚本结构。
-
-## Git 规则
-
-- dirty workspace 默认视为阻塞，除非用户明确说明哪些改动属于当前任务。
-- 禁止在未确认时使用破坏性命令，如 `git reset --hard`、`git checkout --`、递归删除。
-- 提交前必须有 fresh verification evidence。
-
-## 安全规则
-
-- 不把 token、cookie、私钥、密码写入仓库、trace 或文档。
-- 不在不可信环境使用高权限 sandbox。
-- 对外部输入保持最小权限原则。
-
-## 分层规则
-
-- 跨项目稳定习惯放全局 `~/.codex/AGENTS.md`。
-- 当前仓库规则放项目根 `AGENTS.md`。
-- 长文档放项目 `docs/`，不要把所有细节塞进入口文件。
-
-## 不应放在全局的内容
-
-- `task.json`、`progress.txt`、`tools/harness/codex-loop.ps1` 的项目 workflow。
-- 某个仓库专属的提交规则、目录结构、接口名称。
-- 某个产品专属业务规则。
+# Global AGENTS.md
+
+## 通用工作原则
+
+- 默认使用简体中文输出。
+- 在没有验证证据前，不要声称任务已完成。
+- 先阅读代码和文档，再修改文件。
+- 开始实现前，先确认验收标准、测试入口和完成证据路径。
+- 尽量保持改动范围小且可审计。
+
+## 工具与命令规则
+
+- 先用 `Get-Command` 检查命令是否存在。
+- 命令不存在时优先使用已知绝对路径，不盲目重装工具。
+- 搜索文件优先使用 `rg` 或 `rg --files`。
+- 不要用内联脚本绕过正常文件和脚本结构。
+
+## Git 规则
+
+- dirty workspace 默认视为阻塞，除非用户明确说明哪些改动属于当前任务。
+- 禁止在未确认时使用破坏性命令，如 `git reset --hard`、`git checkout --`、递归删除。
+- 提交前必须有 fresh verification evidence。
+
+## 安全规则
+
+- 不把 token、cookie、私钥、密码写入仓库、trace 或文档。
+- 不在不可信环境使用高权限 sandbox。
+- 对外部输入保持最小权限原则。
+
+## 分层规则
+
+- 跨项目稳定习惯放全局 `~/.codex/AGENTS.md`。
+- 当前仓库规则放项目根 `AGENTS.md`。
+- 长文档放项目 `docs/`，不要把所有细节塞进入口文件。
+
+## 不应放在全局的内容
+
+- `task.json`、`progress.txt`、`tools/harness/codex-loop.ps1` 的项目 workflow。
+- 某个仓库专属的提交规则、目录结构、接口名称。
+- 某个产品专属业务规则。

package/package-source/docs/codex-harness-engineering/templates/config/global-config.toml

@@ -1,19 +1,19 @@
-model = "gpt-5.4"
-model_reasoning_effort = "medium"
-personality = "pragmatic"
-sandbox_mode = "workspace-write"
-approvals_reviewer = "user"
-
-[approvals]
-approval_policy = "on-request"
-
-[shell_environment_policy]
-inherit = "all"
-ignore_default_excludes = true
-
-[features]
-# 默认启用 hooks 作为 stop-gate 增强层；driver 仍是主链路。
-codex_hooks = true
-
-# 在这里放跨项目稳定设置，不放项目特有 MCP、env 或 trust。
-# 项目特有内容建议放到 `<repo>/.codex/config.toml`。
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+personality = "pragmatic"
+sandbox_mode = "workspace-write"
+approvals_reviewer = "user"
+
+[approvals]
+approval_policy = "on-request"
+
+[shell_environment_policy]
+inherit = "all"
+ignore_default_excludes = true
+
+[features]
+# 默认启用 hooks 作为 stop-gate 增强层；driver 仍是主链路。
+codex_hooks = true
+
+# 在这里放跨项目稳定设置，不放项目特有 MCP、env 或 trust。
+# 项目特有内容建议放到 `<repo>/.codex/config.toml`。

package/package-source/docs/codex-harness-engineering/templates/config/rules/agents.md

@@ -1,115 +1,118 @@
----
-trigger: always_on
----
-
-# 通用 Agent 编排规则
-
-## 作用范围
-
-本文件定义跨项目可复用的 agent 角色、阶段映射和派发规则。这里的 `agent` 是职责角色，不一定要求每个角色都有独立进程；主控可以通过以下三种方式执行角色：
-
-- 通过 `.codex/agents/*.toml` 调起只读辅助子代理或 scoped writer 子代理。
-- 复用现有 skill，例如 `prd-writer`、`architect`、`frontend-design`、`api-design`、`tdd-guide`、`code-reviewer`。
-- 在当前主控会话中按该角色的规则完成窄范围分析，但主控会话只做分析和路由，不直接写仓库文件。
-
-如果某个阶段没有项目专属 agent，按本文的“阶段到默认 Agent 映射”选择默认角色。
-
-## 角色清单
-
-| Agent Role | 主要职责 | 推荐技能 / Prompt | 何时使用 |
-| --- | --- | --- | --- |
-| `controller` | 主控、阶段推进、任务排序、合并决策 | `controller-loop.md` | 全流程常驻，不直接写仓库文件 |
-| `bootstrap-operator` | 新项目接入、模板复制、smoke、环境检查 | `project-setup`, `tools/install/bootstrap-codex-harness.ps1` | Stage 01 初始化 |
-| `product-analyst` | 需求分析、PRD、用户角色、业务规则、验收标准和可执行验收示例 | `prd-writer`, `business-rule-spec`, `requirements-design-template` | Stage 02 需求收敛 |
-| `requirements-trace-analyst` | 需求到页面、状态、字段、接口、测试的追溯 | `consistency-checklist`, `spec-review` | Stage 03 追溯矩阵和缺口分析 |
-| `architect` | 架构边界、数据流、模块拆分、技术风险 | `architect`, `api-design`, `data-flow-spec` | 架构、契约、跨模块影响和高风险决策 |
-| `design-lead` | 设计规范、信息架构、组件规则、视觉 token | `frontend-design`, `ui-ux-pro-max`, `brand-design-md` | Stage 04 设计规范和复杂 UI 决策 |
-| `image-prompt-writer` | AI 生图 brief、页面状态、禁止事项、参考图要求 | `ai-ui-prompts` | Stage 05 生图输入 |
-| `ui-image-reviewer` | 设计图是否满足 PRD 和 Design Brief | `frontend-design`, `spec-based-review` | Stage 07 UI Image Review |
-| `frontend-spec-writer` | 把设计图翻译成组件、状态源、状态分支、事件、测试选择器和视觉断言 | `frontend-first-workflow`, `page-spec-template` | Stage 08 Image To Frontend Spec |
-| `planner` | DEV-PLAN、任务拆分、依赖、验证顺序 | `planner`, `plan` | 实施计划和任务拆解 |
-| `harness-writer` | `AGENTS.md`、任务队列、控制面配置、hook、prompt、harness 文档等编排资产写入 | `harness-writer.md` | 主控遇到非 driver 编排写入时 |
-| `frontend-worker` | 前端页面、组件、样式、stories、前端测试 | `frontend-patterns`, `typescript`, `vue-arco` 或项目栈技能 | 前端实现 |
-| `visual-reviewer` | 浏览器截图和设计图对比、视觉还原报告 | `browser-e2e-testing`, `midscene-fix-review` | Visual Parity |
-| `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
-| `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
-| `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
-| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
-| `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
-| `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
-| `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
-| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
-| `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
-| `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
-| `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
-| `release-manager` | diff 检查、验证证据、提交、push、最终报告 | `auto-commit`, `git-workflow` | 合并、提交和交付 |
-
-## 阶段到默认 Agent 映射
-
-| 阶段 | 主责 Agent | 协作 Agent | 说明 |
-| --- | --- | --- | --- |
-| 01 初始化 | `bootstrap-operator` | `docs-worker` | 接入模板、检查 Git、跑 smoke |
-| 02 需求收敛 | `product-analyst` | `requirements-trace-analyst`, `test-planner` | 把聊天需求转成 PRD、页面清单、状态矩阵、验收标准和可执行验收示例；所有 P0/P1 需求必须通过需求可测试性检查 |
-| 03 追溯与难点预研 | `requirements-trace-analyst` | `test-planner`, `architect` | 建立需求到 UI/API/数据/状态/测试/证据的追溯矩阵，识别高风险路径和测试数据缺口 |
-| 04 Design Brief | `design-lead` | `product-analyst` | 把主观审美变成可编码设计规则 |
-| 05 AI Image Brief | `image-prompt-writer` | `design-lead` | 生成稳定的 AI 生图输入 |
-| 06 UI 设计图 | `design-lead` | `image-prompt-writer` | 生成或编辑页面多状态参考图 |
-| 07 UI Image Review | `ui-image-reviewer` | `product-analyst`, `design-lead` | 设计图不通过时回到上一步 |
-| 08 Image To Frontend Spec | `frontend-spec-writer` | `frontend-worker`, `test-planner`, `visual-reviewer` | 把图片元素映射到组件、数据、事件、状态源、渲染分支、测试选择器、视觉断言和 E2E 场景 |
-| 09 DEV-PLAN / 任务拆分 | `planner` | `controller`, `architect`, `test-planner` | 生成依赖、owned paths、验证顺序和真实任务；每个任务都要携带测试层级、验证命令和证据路径 |
-| 10 Frontend Build | `frontend-worker` | `test-planner` | 先对照验收示例和前端测试规格实现；每个 UI 状态必须有代码状态源、渲染分支和复验入口，不能用界面说明文案冒充状态实现 |
-| 11 Visual Parity | `visual-reviewer` | `frontend-worker` | 除视觉还原外，还检查状态覆盖和关键交互可用性；失败后由原 frontend worker 修 |
-| 12 Contract First | `contract-designer` | `architect`, `backend-worker`, `frontend-worker`, `test-planner` | 先定义 OpenAPI、错误码、mock 和契约测试，再进入后端实现 |
-| 13 Backend / API | `backend-worker` | `contract-designer`, `test-planner` | 按契约实现 API、数据和权限 |
-| 14 Integration | `integration-worker` | `frontend-worker`, `backend-worker`, `test-runner` | mock 切真实接口，跑主流程 |
-| 15 Stage 1 Review | `stage1-reviewer` | `product-analyst`, `design-lead` | 审实现是否符合产品、设计和计划 |
-| 16 Stage 2 Review | `stage2-reviewer` | `security-reviewer`, `test-planner` | 审代码质量、测试缺口和风险 |
-| 17 Verify / Regression | `test-runner` | `controller`, `test-planner` | 运行 fresh evidence、affected tests、P0 regression 和契约验证；不得在本阶段第一次补齐需求测试范围 |
-| 18 修复闭环 | `failure-triage` | `repair-worker`, 原 reviewer/tester | 归因、派修、复验 |
-| 19 合并 / 提交 / Push | `release-manager` | `controller`, `docs-worker` | 只合并本任务改动，提交前检查 diff 和证据 |
-
-## 路由规则
-
-1. 需求分析阶段默认使用 `product-analyst`，不是 `frontend-worker`、`backend-worker` 或 `test-runner`。
-2. 需求追溯阶段默认使用 `requirements-trace-analyst`，测试映射由 `test-planner` 协作。
-3. 架构、契约、数据流、权限、支付、安全、迁移等高风险问题必须加入 `architect` 或 `security-reviewer`。
-4. UI 相关链路按 `design-lead -> image-prompt-writer -> ui-image-reviewer -> frontend-spec-writer -> frontend-worker -> visual-reviewer` 顺序推进。
-5. 实现失败由原实现 agent 修复；评审或测试失败由提出 finding 的原 reviewer/tester 复验。
-6. 前端状态是行为和数据分支，不是说明文字；任何把 `loading / empty / error / disabled / permission / mobile` 只写成页面文案而没有真实状态源、触发路径和渲染分支的实现，必须路由回 `frontend-worker` 修复。
-
-## 并行规则
-
-- Stage 02-08 以真相源稳定为主，可以并行调研，但不能让多个 agent 同时改同一份 PRD、Design Brief 或视觉规格。
-- 同一时刻不要让多个角色写同一组可写路径。
-- 任何并行结论都必须回到 `task.json`、验证命令和证据路径上，不接收口头“已完成”。
-
-## 子代理前置读取规则
-
-- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md` 和本文件。
-- 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
-- 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
-- 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。
-- writer 子代理只能修改父会话明确分配的路径；主控会话自身不直接写仓库文件。
-- `progress.txt`、`traces/` 和 Git 状态默认仍由 runtime 脚本处理；除这些脚本产物外，仓库写入必须通过匹配的 writer 子代理落盘。
-
-## 模型和思考深度
-
-- `product-analyst`、`requirements-trace-analyst`、`architect`、`design-lead`、`visual-reviewer`、`stage1-reviewer`、`stage2-reviewer` 默认使用更强模型和较高思考深度。
-- `frontend-worker`、`backend-worker`、`integration-worker` 默认使用工作型模型，中高思考深度。
-- `docs-worker`、`test-runner` 可以使用较低成本模型，但失败归因和最终验收不得只靠低强度判断。
-
-## 交接格式
-
-```markdown
-Verdict: PASS | FAIL | BLOCKED
-Role: <agent-role>
-Stage: <stage-id>
-Report: <relative/path/to/report.md>
-Changed paths:
-- <path>
-Verification:
-- <command> -> PASS | FAIL | NOT_RUN
-Open issues:
-- <issue or none>
-Next recommended stage: <stage-id>
-```
+---
+trigger: always_on
+---
+
+# 通用 Agent 编排规则
+
+## 作用范围
+
+本文件定义跨项目可复用的 agent 角色、阶段映射和派发规则。这里的 `agent` 是职责角色，不一定要求每个角色都有独立进程；主控可以通过以下三种方式执行角色：
+
+- 通过 `.codex/agents/*.toml` 调起只读辅助子代理或 scoped writer 子代理。
+- 复用现有 skill，例如 `prd-writer`、`architect`、`frontend-design`、`api-design`、`tdd-guide`、`code-reviewer`。
+- 在当前主控会话中按该角色的规则完成窄范围分析，但主控会话只做分析和路由，不直接写仓库文件。
+
+如果某个阶段没有项目专属 agent，按本文的“阶段到默认 Agent 映射”选择默认角色。
+
+## 角色清单
+
+| Agent Role | 主要职责 | 推荐技能 / Prompt | 何时使用 |
+| --- | --- | --- | --- |
+| `controller` | 主控、阶段推进、任务排序、合并决策 | `controller-loop.md` | 全流程常驻，不直接写仓库文件 |
+| `bootstrap-operator` | 新项目接入、模板复制、smoke、环境检查 | `project-setup`, `tools/install/bootstrap-codex-harness.ps1` | Stage 01 初始化 |
+| `product-analyst` | 需求分析、PRD、用户角色、业务规则、验收标准和可执行验收示例 | `prd-writer`, `business-rule-spec`, `requirements-design-template` | Stage 02 需求收敛 |
+| `requirements-trace-analyst` | 需求到页面、状态、字段、接口、测试的追溯 | `consistency-checklist`, `spec-review` | Stage 03 追溯矩阵和缺口分析 |
+| `architect` | 架构边界、数据流、模块拆分、技术风险 | `architect`, `api-design`, `data-flow-spec` | 架构、契约、跨模块影响和高风险决策 |
+| `design-lead` | 设计规范、信息架构、组件规则、视觉 token | `frontend-design`, `ui-ux-pro-max`, `brand-design-md` | Stage 04 设计规范和复杂 UI 决策 |
+| `image-prompt-writer` | AI 生图 brief、页面状态、禁止事项、参考图要求 | `ai-ui-prompts` | Stage 05 生图输入 |
+| `ui-image-reviewer` | 设计图是否满足 PRD 和 Design Brief | `frontend-design`, `spec-based-review` | Stage 07 UI Image Review |
+| `frontend-spec-writer` | 把设计图翻译成组件、状态源、状态分支、事件、测试选择器和视觉断言 | `frontend-first-workflow`, `page-spec-template` | Stage 08 Image To Frontend Spec |
+| `planner` | DEV-PLAN、任务拆分、依赖、验证顺序 | `planner`, `plan` | 实施计划和任务拆解 |
+| `harness-writer` | `AGENTS.md`、任务队列、控制面配置、hook、prompt、harness 文档等编排资产写入 | `harness-writer.md` | 主控遇到非 driver 编排写入时 |
+| `frontend-worker` | 前端页面、组件、样式、stories、前端测试 | `frontend-patterns`, `typescript`, `vue-arco` 或项目栈技能 | 前端实现 |
+| `visual-reviewer` | 浏览器截图和设计图对比、视觉还原报告 | `browser-e2e-testing`, `midscene-fix-review` | Visual Parity |
+| `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
+| `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
+| `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
+| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
+| `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
+| `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
+| `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
+| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
+| `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
+| `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
+| `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
+| `release-manager` | diff 检查、验证证据、提交、push、最终报告 | `auto-commit`, `git-workflow` | 合并、提交和交付 |
+
+## 阶段到默认 Agent 映射
+
+| 阶段 | 主责 Agent | 协作 Agent | 说明 |
+| --- | --- | --- | --- |
+| 01 初始化 | `bootstrap-operator` | `docs-worker` | 接入模板、检查 Git、跑 smoke |
+| 02 需求收敛 | `product-analyst` | `requirements-trace-analyst`, `test-planner` | 把聊天需求转成 PRD、页面清单、状态矩阵、验收标准和可执行验收示例；所有 P0/P1 需求必须通过需求可测试性检查 |
+| 03 追溯与难点预研 | `requirements-trace-analyst` | `test-planner`, `architect` | 建立需求到 UI/API/数据/状态/测试/证据的追溯矩阵，识别高风险路径和测试数据缺口 |
+| 04 Design Brief | `design-lead` | `product-analyst` | 把主观审美变成可编码设计规则 |
+| 05 AI Image Brief | `image-prompt-writer` | `design-lead` | 生成稳定的 AI 生图输入 |
+| 06 UI 设计图 | `design-lead` | `image-prompt-writer` | 生成或编辑页面多状态参考图 |
+| 07 UI Image Review | `ui-image-reviewer` | `product-analyst`, `design-lead` | 设计图不通过时回到上一步 |
+| 08 Image To Frontend Spec | `frontend-spec-writer` | `frontend-worker`, `test-planner`, `visual-reviewer` | 把图片元素映射到组件、数据、事件、状态源、渲染分支、测试选择器、视觉断言和 E2E 场景 |
+| 09 DEV-PLAN / 任务拆分 | `planner` | `controller`, `architect`, `test-planner` | 生成依赖、owned paths、验证顺序和真实任务；每个任务都要携带测试层级、验证命令和证据路径 |
+| 10 Frontend Build | `frontend-worker` | `test-planner` | 先对照验收示例和前端测试规格实现；每个 UI 状态必须有代码状态源、渲染分支和复验入口，不能用界面说明文案冒充状态实现 |
+| 11 Visual Parity | `visual-reviewer` | `frontend-worker` | 除视觉还原外，还检查状态覆盖和关键交互可用性；失败后由原 frontend worker 修 |
+| 12 Contract First | `contract-designer` | `architect`, `backend-worker`, `frontend-worker`, `test-planner` | 先定义 OpenAPI、错误码、mock 和契约测试，再进入后端实现 |
+| 13 Backend / API | `backend-worker` | `contract-designer`, `test-planner` | 按契约实现 API、数据和权限 |
+| 14 Integration | `integration-worker` | `frontend-worker`, `backend-worker`, `test-runner` | mock 切真实接口，跑主流程 |
+| 15 Stage 1 Review | `stage1-reviewer` | `product-analyst`, `design-lead` | 审实现是否符合产品、设计和计划 |
+| 16 Stage 2 Review | `stage2-reviewer` | `security-reviewer`, `test-planner` | 审代码质量、测试缺口和风险 |
+| 17 Verify / Regression | `test-runner` | `controller`, `test-planner` | 运行 fresh evidence、affected tests、P0 regression 和契约验证；不得在本阶段第一次补齐需求测试范围 |
+| 18 修复闭环 | `failure-triage` | `repair-worker`, 原 reviewer/tester | 归因、派修、复验 |
+| 19 合并 / 提交 / Push | `release-manager` | `controller`, `docs-worker` | 只合并本任务改动，提交前检查 diff 和证据 |
+
+## 路由规则
+
+1. 需求分析阶段默认使用 `product-analyst`，不是 `frontend-worker`、`backend-worker` 或 `test-runner`。
+2. 需求追溯阶段默认使用 `requirements-trace-analyst`，测试映射由 `test-planner` 协作。
+3. 架构、契约、数据流、权限、支付、安全、迁移等高风险问题必须加入 `architect` 或 `security-reviewer`。
+4. UI 相关链路按 `design-lead -> image-prompt-writer -> ui-image-reviewer -> frontend-spec-writer -> frontend-worker -> visual-reviewer` 顺序推进。
+5. 实现失败由原实现 agent 修复；评审或测试失败由提出 finding 的原 reviewer/tester 复验。
+6. 前端状态是行为和数据分支，不是说明文字；任何把 `loading / empty / error / disabled / permission / mobile` 只写成页面文案而没有真实状态源、触发路径和渲染分支的实现，必须路由回 `frontend-worker` 修复。
+
+## 并行规则
+
+- Stage 02-08 以真相源稳定为主，可以并行调研，但不能让多个 agent 同时改同一份 PRD、Design Brief 或视觉规格。
+- 同一时刻不要让多个角色写同一组可写路径。
+- 如果需要并行，必须先按任务、目录、文件组、分支或 PR 隔离；不要让两个 agent 同时改同一个文件。
+- 任何并行结论都必须回到 `task.json`、验证命令和证据路径上，不接收口头“已完成”。
+
+## 子代理前置读取规则
+
+- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`（thin project 缺失时改读 `.codex-harness/state/config.json` 里 `packageRoot` 下的同路径文件）和本文件。
+- 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
+- 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
+- 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。
+- writer 子代理只能修改父会话明确分配的路径；主控会话自身不直接写仓库文件。
+- `progress.txt`、`traces/` 和 Git 状态默认仍由 runtime 脚本处理；除这些脚本产物外，仓库写入必须通过匹配的 writer 子代理落盘。
+- 当前轮次结束前，主控必须把 `docs/ai/CURRENT_TASK.md` 中的已完成内容、未完成内容、修改文件、测试结果、风险点和下一步刷新为最新状态。
+- 新一轮续跑前，必须先读 `CURRENT_TASK.md` 的交接字段；如果交接不完整，先补齐再继续实现。
+
+## 模型和思考深度
+
+- `product-analyst`、`requirements-trace-analyst`、`architect`、`design-lead`、`visual-reviewer`、`stage1-reviewer`、`stage2-reviewer` 默认使用更强模型和较高思考深度。
+- `frontend-worker`、`backend-worker`、`integration-worker` 默认使用工作型模型，中高思考深度。
+- `docs-worker`、`test-runner` 可以使用较低成本模型，但失败归因和最终验收不得只靠低强度判断。
+
+## 交接格式
+
+```markdown
+Verdict: PASS | FAIL | BLOCKED
+Role: <agent-role>
+Stage: <stage-id>
+Report: <relative/path/to/report.md>
+Changed paths:
+- <path>
+Verification:
+- <command> -> PASS | FAIL | NOT_RUN
+Open issues:
+- <issue or none>
+Next recommended stage: <stage-id>
+```

package/package-source/docs/codex-harness-engineering/templates/config/rules/coding-style.md

@@ -1,74 +1,57 @@
----
-trigger: always_on
----
-
-# Coding Style
-
-## Immutability (CRITICAL)
-
-ALWAYS create new objects, NEVER mutate:
-
-```javascript
-// WRONG: Mutation
-function updateUser(user, name) {
-  user.name = name  // MUTATION!
-  return user
-}
-
-// CORRECT: Immutability
-function updateUser(user, name) {
-  return {
-    ...user,
-    name
-  }
-}
-```
-
-## File Organization
-
-MANY SMALL FILES > FEW LARGE FILES:
-- High cohesion, low coupling
-- 200-400 lines typical, 800 max
-- Extract utilities from large components
-- Organize by feature/domain, not by type
-
-## Error Handling
-
-ALWAYS handle errors comprehensively:
-
-```typescript
-try {
-  const result = await riskyOperation()
-  return result
-} catch (error) {
-  console.error('Operation failed:', error)
-  throw new Error('Detailed user-friendly message')
-}
-```
-
-## Input Validation
-
-ALWAYS validate user input:
-
-```typescript
-import { z } from 'zod'
-
-const schema = z.object({
-  email: z.string().email(),
-  age: z.number().int().min(0).max(150)
-})
-
-const validated = schema.parse(input)
-```
-
-## Code Quality Checklist
-
-Before marking work complete:
-- [ ] Code is readable and well-named
-- [ ] Functions are small (<50 lines)
-- [ ] Files are focused (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Proper error handling
-- [ ] No console.log statements
-- [ ] No hardcoded values
-- [ ] No mutation (immutable patterns used)
+---
+trigger: always_on
+---
+
+# Coding Style
+
+## 规则分层
+
+- 这里写跨项目稳定不变、需要默认自动加载的规则。
+- `docs/harness/code-style-and-naming.md` 只补项目特有的业务词典、目录例外和类型边界表，不重复这里的固定规则。
+
+## 不可变性
+
+- 默认使用不可变更新，不直接修改输入对象。
+- 状态更新、缓存更新、测试夹具都遵守同一原则。
+
+## 固定命名规则
+
+- 一个业务概念只用一个主名词，不在同一任务里混用多个同义词。
+- 发现历史别名时，先判断它是独立概念还是遗留脏别名，再决定兼容方式。
+- 项目专属业务词典、别名白名单和历史兼容说明写到 `docs/harness/code-style-and-naming.md`。
+
+## 固定文件命名规则
+
+- 同一层目录只使用一套命名风格。
+- 新文件先跟随同目录已有约定，不自行切换成另一套大小写风格。
+- 测试文件跟随被测对象命名，不用 `test1`、`temp`、`new` 这类临时名。
+
+## 固定函数命名规则
+
+- 函数名使用“动词 + 对象”或明确状态判断。
+- 禁止使用 `doAction`、`processData`、`dealData`、`getInfo`、`check`、`handler` 这类模糊名。
+- 事件处理统一使用 `handleXxx`，布尔判断统一使用 `is/has/can` 前缀。
+
+## 固定类型命名规则
+
+- 类型后缀必须有边界语义，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 不混用。
+- 输入模型、持久化模型、展示模型和接口模型不要共用一个泛名。
+- 如果项目禁用某类后缀，具体禁用表和替代方案写到 `docs/harness/code-style-and-naming.md`。
+
+## 文件组织
+
+- 高内聚、低耦合；按 feature / domain 组织，避免大而杂的工具箱文件。
+- 常规文件建议 200-400 行，超过 800 行应先评估是否拆分。
+
+## 错误处理与输入校验
+
+- 错误处理要保留上下文，不吞异常。
+- 外部输入统一走 schema / validator / contract，不靠隐式假设。
+
+## 完成前检查
+
+- [ ] 命名是否与项目业务词典一致
+- [ ] 同层文件是否遵守同一命名风格
+- [ ] 新函数名是否避开模糊万能词
+- [ ] 新类型名是否符合边界语义
+- [ ] 无 `console.log`、无硬编码临时名、无直接对象突变