@pzy560117/codex-harness 0.1.4 → 0.1.6

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/goal-templates.md

@@ -0,0 +1,380 @@
+# `/goal` 目标启动模板库
+
+## 1. 先说结论
+
+这里不是“自由目标文案库”，而是 **`/goal` 启动模板库**。
+
+原因很简单：
+
+- 真正定义“做什么”的，不是 `/goal`。
+- 真正定义“怎么拆任务”的，不是 `/goal`。
+- 真正定义“能不能完成”的，也不是 `/goal`。
+
+在当前 Harness 体系里，这三件事分别由下面几层承担：
+
+| 层 | 负责什么 |
+| --- | --- |
+| spec / PRD / design / testing truth source | 定义目标、范围、验收、风险、非目标 |
+| `task.json` | 定义可执行任务队列、依赖、owned paths、验证命令 |
+| `/goal` | 只负责外层长期目标保持、持续推进和人机 steering |
+
+所以这里的模板，更准确的名字应该理解成：
+
+- **goal launch profiles**
+- **goal wrappers**
+- **goal control prompts**
+
+而不是“随便写一个长期目标让它自己跑”。
+
+## 2. `/goal` 和 spec / task.json 的区别
+
+### 2.1 spec / truth source 解决什么问题
+
+spec、设计、测试真相源回答的是：
+
+- 为什么要做
+- 做到什么算完成
+- 不做什么
+- 哪些路径高风险
+- 哪些证据必须存在
+
+### 2.2 `task.json` 解决什么问题
+
+`task.json` 回答的是：
+
+- 先做哪个任务
+- 哪些任务有依赖
+- 哪个任务接管哪些路径
+- 每个任务要跑什么验证命令
+
+### 2.3 `/goal` 解决什么问题
+
+`/goal` 回答的是：
+
+- 在长时间运行里，系统持续朝哪个方向推进
+- 用户暂停、恢复、修改目标时，外层控制面怎么表达
+- 遇到 stop hook / failed trace / triage 结果时，是继续、保守、还是停下等人
+
+所以它本质上是：
+
+```text
+持续运行控制模板
+```
+
+不是：
+
+```text
+需求模板
+```
+
+也不是：
+
+```text
+任务模板
+```
+
+## 3. 使用前提
+
+任何 `/goal` 模板启用前，都要先确认下面这些已经存在：
+
+### 最小前提
+
+1. `task.json` 已经是真实任务队列，不是 smoke 占位。
+2. 已有 `docs/ai/repo-map.md` 或等价导航文件。
+3. 已有基本 testing truth source：
+   - `ACCEPTANCE_EXAMPLES.md`
+   - `TRACEABILITY_MATRIX.md`
+   - `TEST_DATA_MATRIX.md`
+   - `verify-matrix.md`
+
+### 高风险用户可见任务额外前提
+
+4. 已有 `docs/testing/e2e-plan.md`
+5. 已明确 `failure-triage.md`
+
+### 运行前检查
+
+6. `tools/harness/doctor.ps1` 通过
+7. `tools/harness/verify.ps1` 通过
+8. 工作区不是未解释的脏状态
+
+如果这些前提不成立，不要直接开 `/goal`。
+
+## 4. 模板字段说明
+
+下面每个模板都建议显式包含 6 类信息：
+
+### A. 目标对象
+
+- 当前 feature / release / recovery scope
+
+### B. 依赖的真实真相源
+
+- `AGENTS.md`
+- `docs/ai/repo-map.md`
+- `docs/testing/*`
+- `task.json`
+
+### C. 执行动作
+
+- 通过 `tools/harness/codex-loop.ps1 -RunUntilDone` 推进
+
+### D. 停止条件
+
+- 没有 runnable task
+- stop hook block
+- failed trace
+- 人工 blocker
+
+### E. 禁止事项
+
+- 不绕过 `task.json`
+- 不绕过 `test_command`
+- 不绕过 review / trace / commit gate
+
+### F. 失败处理
+
+- 优先读取 `failure-triage` 结果
+
+## 5. 模板 01：标准持续推进
+
+### 适用场景
+
+- 已有明确 spec
+- 已有真实任务队列
+- 需要连续推进多个任务
+
+### 启动模板
+
+```text
+持续推进当前项目的 Harness 任务队列，直到 task.json 中没有 runnable task、出现真实人工阻塞，或 stop hook / review / test / trace 明确要求暂停。
+
+强制约束：
+1. 先遵守 AGENTS.md、docs/ai/repo-map.md、docs/harness/*、docs/testing/*。
+2. 通过 tools/harness/codex-loop.ps1 -RunUntilDone 推进任务，不绕过 task.json。
+3. 不跳过 test_command、Stage 1、Stage 2、trace 或 commit gate。
+4. 测试失败时先查看 failure-triage 结果，再决定下一步。
+5. 缺少 truth source、e2e-plan、权限或外部依赖时，明确报告 BLOCKED，不自行猜测。
+```
+
+### 适合的跟进消息
+
+```text
+继续按当前任务队列推进，不新增范围。优先完成已经 runnable 的任务。
+```
+
+## 6. 模板 02：夜间长跑
+
+### 适用场景
+
+- 白天人工确认过状态
+- 夜间希望继续推进
+- 更关注稳态而不是速度
+
+### 启动模板
+
+```text
+在无人值守时持续推进当前 Harness 项目，但只允许在 driver 和 stop hook 都认为可以继续时前进。
+
+运行原则：
+1. 优先执行 task.json 中下一个 runnable task。
+2. 任何 dirty workspace、governance drift、failed trace、truth source 缺失都视为暂停信号。
+3. 不要为追求连续运行而弱化测试、跳过 review 或绕过 stop hook。
+4. 每次停下时总结：当前任务、最近证据、failure-triage 结果、是否需要人工。
+```
+
+### 适合的跟进消息
+
+```text
+进入保守夜间模式：如果同一 blocker 连续出现，不要反复重试，直接停下并报告。
+```
+
+## 7. 模板 03：高风险用户可见功能
+
+### 适用场景
+
+- 路由
+- 表单
+- 权限
+- 状态流转
+- 关键 UI 主流程
+
+### 启动模板
+
+```text
+持续推进当前高风险用户可见功能，但必须先确认 docs/testing/e2e-plan.md、验收示例、追溯矩阵和 repo-map 已齐备。
+
+额外约束：
+1. 没有 e2e-plan 时不进入实现，先补测试计划。
+2. 先从 docs/ai/repo-map.md 进入代码结构，再做局部文件修改。
+3. 测试失败时先按 TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY 分类。
+4. 不允许用 mock、fixture、local-only adapter 冒充真实交付路径。
+```
+
+### 适合的跟进消息
+
+```text
+先确认 e2e-plan 和影响面，不要为了前进速度绕过用户可见路径的测试计划。
+```
+
+## 8. 模板 04：恢复性目标
+
+### 适用场景
+
+- 上一轮 stop hook 强制继续
+- 早上接手夜间运行
+- 测试刚失败，需要恢复执行链
+
+### 启动模板
+
+```text
+恢复并继续当前 Harness 执行链。先判断上次停止是正常 allow stop、stop hook continuation、review 失败、test_command 失败还是真实 BLOCKED。
+
+执行顺序：
+1. 读取最新 progress.txt、latest trace、failure-triage 报告。
+2. 确认当前 runnable task 和最近失败阶段。
+3. 如果 stop hook / driver 允许继续，则继续推进。
+4. 如果仍然 blocked，输出需要人工处理的最小动作，不要空转。
+```
+
+### 适合的跟进消息
+
+```text
+先恢复上下文，不要直接重跑实现；先解释最近一次失败和当前是否真的可继续。
+```
+
+## 9. 模板 05：Release 收口
+
+### 适用场景
+
+- 多个故事已完成
+- 进入 P0/P1 回归
+- 需要收口而不是再发散实现
+
+### 启动模板
+
+```text
+持续推进当前 release 收口，但不新增新功能范围。目标是完成当前 task.json 中与 release 相关的 runnable task，并输出 fresh evidence。
+
+约束：
+1. 优先处理 P0/P1 回归、契约验证、e2e/视觉证据和 failure-triage。
+2. 不新增新的 feature 实现任务，除非任务队列本身已经声明。
+3. 如果发现问题，优先归因到现有 story 或 release blocker，不要模糊扩写需求。
+4. 没有 fresh evidence 就不要声称 release 完成。
+```
+
+### 适合的跟进消息
+
+```text
+收口优先，不再扩 scope。失败项先归因到现有 blocker，再决定是否需要 repair。
+```
+
+## 10. 模板 06：治理修复
+
+### 适用场景
+
+- stop hook 被 governance drift 卡住
+- rules / prompts / docs / mirrors 漂移
+- 需要先修 Harness 面再继续业务开发
+
+### 启动模板
+
+```text
+当前目标不是继续业务功能，而是先修复 Harness 治理面，使 driver 和 stop hook 能重新进入稳定运行状态。
+
+约束：
+1. 优先读取 AGENTS.md、docs/harness/governance-auto-repair.md、docs/harness/rule-governance.md、.codex/rules/agents.md。
+2. 只修与当前治理失败直接相关的 runtime/docs/template/package-assets 面。
+3. 业务实现不是当前目标，除非治理修复明确要求一起同步。
+4. 修复完成后重新运行 verify / doctor，再决定是否恢复原目标。
+```
+
+### 适合的跟进消息
+
+```text
+优先恢复治理面，不继续业务功能。只处理当前 stop hook / verify 报出的直接问题。
+```
+
+## 11. 模板 07：人工旁路保守模式
+
+### 适用场景
+
+- 人工希望介入更多
+- 不希望系统自由选择太多 repair 动作
+- 高风险上线前夕
+
+### 启动模板
+
+```text
+持续推进当前 Harness 项目，但进入人工旁路保守模式。
+
+规则：
+1. 只推进 task.json 中已经 runnable 的任务。
+2. 遇到同一 blocker 或 triage 分类不清时，立即停下请求人工确认。
+3. 不自行扩大范围，不自行改写目标，不自行新增 repair 分支。
+4. 每轮仅报告：当前任务、最近验证、failure-triage 分类、是否建议继续。
+```
+
+### 适合的跟进消息
+
+```text
+进入人工旁路模式：遇到需要策略判断的地方，不要自己选，直接停下问我。
+```
+
+## 12. 这些模板和 spec / task.json 的区别
+
+这是最容易混淆的一点：
+
+### spec / truth source 是“内容层”
+
+定义：
+
+- 业务目标
+- 验收
+- 约束
+- 风险
+
+### `task.json` 是“执行层”
+
+定义：
+
+- 任务顺序
+- 依赖
+- owned paths
+- test_command
+
+### `/goal` 模板是“控制层”
+
+定义：
+
+- 如何持续推进
+- 什么时候停
+- 什么时候保守
+- 遇到失败怎么先归因
+
+所以这里的模板库价值不在“重复写需求”，而在：
+
+- 减少使用 `/goal` 时的外层控制失误
+- 保证 `/goal` 不压过 Harness driver
+
+## 13. 推荐命名
+
+如果后续继续扩充，建议把这一类文案统一叫：
+
+- `goal launch profiles`
+- `goal control templates`
+
+不要叫：
+
+- feature goal specs
+- long-running task specs
+
+因为它们不是在定义业务目标本身。
+
+## 14. 推荐下一步
+
+如果后面还要继续完善，最值得补的不是“更多空泛模板”，而是：
+
+1. 基于真实 Harness 场景补更多 launch profiles。
+2. 补一个“如何从 stop hook / failed trace 自动挑选合适 goal 模板”的决策表。
+3. 如果未来 `user` 安装层正式支持 `/goal`，再把这套模板库明确挂到 user 模式文档里。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 这是 `ticket-filter-demo` 示例工程说明的 package-assets 镜像。
+
+## 结构索引
+
+- `README.md`：示例说明。
+
+## 修改规则
+
+- 示例 canonical 在 `docs/codex-harness-engineering/examples/ticket-filter-demo/`。
+- 这里默认只作为镜像副本，不要先改。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/README.md

@@ -0,0 +1,64 @@
+# Ticket Filter Demo
+
+这个 demo 不是完整可运行应用，而是一个**最小可读的真相源链路示例**，用来说明下面这条工作流在实际目录里应该长什么样：
+
+```text
+Product Spec
+  -> Requirement Interface Matrix + Difficulty Research
+  -> Design Brief
+  -> Frontend Architecture + Frontend Quality Rules
+  -> AI Image Brief
+  -> UI Image Review
+  -> Image To Frontend Spec
+  -> DEV-PLAN
+  -> OpenAPI Contract
+```
+
+适用场景:
+
+- 想快速理解 `spec-to-ui-to-code-workflow.md`
+- 想看模板填完之后实际应该长什么样
+- 想给新项目做第一版 feature skeleton
+
+## 目录
+
+- `docs/product/`: 需求、页面、状态矩阵、需求-界面追溯、前置难点研究
+- `docs/design/`: 设计 brief、前端架构、AI 生图 brief、图片评审、图转前端规格、组件映射、屏幕状态
+- `plans/features/`: DEV-PLAN
+- `contracts/`: OpenAPI 样例
+- `contracts/orval.config.ts`: Orval 配置样例
+- `packages/ui/`: 最小前端组件样例
+- `stories/`: 最小 Storybook 状态样例
+- `packages/api-client/generated/`: 最小 generated client 样例
+- `task.json`: 最小任务队列样例
+- `traces/`: 最小 trace 样例
+- `tools/harness/verify.ps1`: fake verify 链路样例
+
+## 怎么用
+
+1. 先读 `docs/product/prd-lite.md`
+2. 再读 `docs/product/requirement-interface-matrix.md` 与 `docs/product/difficulty-research.md`
+3. 再读 `docs/design/design-brief.md`
+4. 再读 `docs/design/frontend-architecture.md`
+5. 再读 `docs/design/ai-image-brief.md`、`docs/design/ui-image-review.md` 与 `docs/design/image-to-frontend-spec.md`
+6. 再读 `docs/design/component-map.md` 与 `docs/design/screen-states.md`
+7. 再读 `plans/features/ticket-filter.dev-plan.md`
+8. 最后读 `contracts/openapi.yaml`
+9. 如需检查 demo 资产是否齐全，运行:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+10. 如果想看 driver 闭环最小输入输出，再看：
+
+- `task.json`
+- `traces/DEMO-TICKET-FILTER-001-20260422-120000.json`
+
+## 这个 demo 刻意没有做什么
+
+- 没有放完整后端实现
+- 没有放真实 Playwright / visual baseline 资产
+- 没有接真实构建配置
+
+目的不是提供业务代码，而是提供**项目开始前的真相源样例**。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/contracts/openapi.yaml

@@ -0,0 +1,25 @@
+openapi: 3.0.3
+info:
+  title: Ticket Filter Demo API
+  version: 0.1.0
+paths:
+  /tickets:
+    get:
+      summary: List tickets with filters
+      operationId: listTickets
+      responses:
+        "200":
+          description: OK
+  /ticket-views:
+    get:
+      summary: List saved views
+      operationId: listTicketViews
+      responses:
+        "200":
+          description: OK
+    post:
+      summary: Create saved view
+      operationId: createTicketView
+      responses:
+        "201":
+          description: Created

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/contracts/orval.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "orval";
+
+export default defineConfig({
+  ticketApi: {
+    input: "./contracts/openapi.yaml",
+    output: {
+      target: "./packages/api-client/generated/ticket-api.ts",
+      schemas: "./packages/api-client/generated/model",
+      client: "react-query",
+      mock: true,
+      mode: "split",
+      override: {
+        mutator: {
+          path: "./packages/api-client/http-client.ts",
+          name: "httpClient",
+        },
+      },
+    },
+  },
+});

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/ai-image-brief.md

@@ -0,0 +1,44 @@
+# AI Image Brief
+
+## 1. 基本信息
+
+- Feature ID: DEMO-TICKET-FILTER
+- Page ID: ticket-list
+- 页面名称: 工单列表筛选页
+- 设备 / 画布: Desktop 1440px
+- 设计来源: PRD-Lite / Requirement Interface Matrix / Design Brief / Component Map / Screen States / Design Tokens
+- 生成批次: v1
+- 状态: Approved
+
+## 2. CSS / 视觉要求
+
+| 类别 | 要求 |
+| --- | --- |
+| 颜色 | 蓝灰背景、白色主内容面板、橙色强调高优先级和保存视图按钮 |
+| 字体 | 系统无衬线字体，后台管理密度 |
+| 字号层级 | 页面标题 20px，表格主体 14px，辅助说明 12px |
+| 间距 | 筛选控件 8px 间距，页面主间距 24px |
+| 圆角 | 控件 6px，面板 8px |
+| 表格 / 列表密度 | 每行 48px，高密度但不拥挤 |
+| 状态色 | open 蓝色，pending 橙色，resolved 绿色，error 红色 |
+
+## 3. 必须生成的界面状态
+
+| State | 是否生成 | 说明 | 输出图片 |
+| --- | --- | --- | --- |
+| default | Yes | 显示筛选条、保存视图、10 条工单 | IMG-001 |
+| empty | Yes | 无结果空态和清除筛选入口 | IMG-002 |
+| loading | Yes | 表格骨架屏和禁用操作 | IMG-003 |
+| error | Yes | 内联错误和重试入口 | IMG-004 |
+| permission_denied | Yes | 客服角色不显示保存视图按钮 | IMG-005 |
+| mobile | Yes | 筛选条折叠为抽屉入口 | IMG-006 |
+
+## 4. 生图提示词摘要
+
+```text
+生成工单列表筛选页的生产级后台 UI 设计图，Desktop 1440px。
+页面包含顶部标题、筛选条、保存视图按钮、已保存视图列表入口、工单表格和分页。
+使用蓝灰背景、白色内容面板、橙色 CTA，高密度企业后台风格。
+必须覆盖 default / empty / loading / error / permission_denied / mobile。
+不要添加导出、共享视图、图表分析等 PRD 未要求功能。
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/component-map.md

@@ -0,0 +1,17 @@
+# Component Map
+
+| 页面/模块 | 组件 | 层级 | 责任 | 复用来源 | 必备状态 | 测试方式 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 工单列表页 | `TicketFilterBar` | feature | 展示状态、优先级、负责人筛选条件 | 业务组件 | default / dirty / permission / mobile | story + e2e |
+| 工单列表页 | `TicketFilterDrawer` | feature | 移动端筛选抽屉 | 业务组件 | mobile / dirty / disabled | story + e2e + a11y |
+| 工单列表页 | `SavedViewModal` | feature | 输入名称并保存当前筛选视图 | 业务组件 | default / validation-error / permission-denied / saving | story + unit + a11y |
+| 工单列表页 | `TicketTable` | feature | 展示工单结果列表 | 表格基础组件 | default / empty / loading / error / long_content | story + visual |
+| 通用表格 | `DataTableShell` | primitive | 提供表格容器、分页、空态槽位和列显隐 | new reusable | default / empty / loading | story + visual |
+
+## 复用决策
+
+| 候选组件 / Hook | 决策 | 原因 |
+| --- | --- | --- |
+| `DataTableShell` | 抽到项目级复用 | 分页、空态、列显隐是后台表格通用能力 |
+| `TicketFilterBar` | 留在 feature | 工单字段和权限语义强 |
+| `SavedViewModal` | 留在 feature | 保存视图依赖当前 filter schema |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/examples/ticket-filter-demo/docs/design/design-brief.md

@@ -0,0 +1,58 @@
+# Design Brief
+
+## 1. 设计目标
+
+- 功能主题: 工单后台筛选体验
+- 要解决的问题: 信息密度高但不能压迫，筛选操作要快，批量管理感要强
+- 目标质量等级: P2，必须覆盖响应式、动效、可访问性和视觉一致性证据
+
+## 2. 视觉方向
+
+- 主题风格: 企业后台、克制、专业
+- 品牌气质: 高密度但清晰、可信赖
+- 避免: 营销 landing page 风格、过多插画、过强渐变
+- 审美验收: 表格和筛选区要有清晰主次；高优先级、错误、保存 dirty 状态必须一眼可辨；不能只堆叠灰白卡片
+
+## 3. 色彩策略
+
+- 主色: 蓝灰系
+- 强调色: 橙色用于高优先级和 CTA
+- 错误色: 红色
+
+## 4. 布局与组件原则
+
+- 页面布局: 顶部筛选条 + 主数据表
+- 筛选条应支持标签化回显
+- 保存视图使用小型弹窗，不要切走主页面
+- desktop 使用横向筛选条；tablet 允许换行；mobile 使用筛选抽屉并把表格转为卡片列表
+
+## 5. 交互原则
+
+- 主按钮: 保存视图
+- 次按钮: 清空筛选
+- 加载态: 表格骨架屏 + 按钮禁用
+- 错误态: 内联错误提示 + 重试
+- dirty 状态: 通过筛选 chip、保存按钮和状态文案同时反馈，保存成功后清除 dirty
+
+## 6. 动效与响应式
+
+- 弹窗: opacity + scale，160ms；reduced motion 下直接显示。
+- 移动端筛选抽屉: translateX + opacity，180ms；必须有 focus trap。
+- 筛选 chip 增删: opacity + slight translate，120ms；不能推动整页大范围跳动。
+- 表格刷新: skeleton + row fade，160ms；高频刷新时禁用行级动画。
+- mobile: 筛选进入抽屉，表格转卡片，分页简化为上一页 / 下一页。
+- long content: 工单标题两行截断，负责人姓名超长时 tooltip，状态标签不换行。
+
+## 7. 可访问性与性能
+
+- 所有筛选控件必须有可见 label 或 aria-label。
+- 弹窗和抽屉必须支持 Esc 关闭、焦点恢复和键盘遍历。
+- 颜色不能作为优先级和错误的唯一表达，必须有文本标签。
+- 单页超过 100 行时不得继续纯客户端完整渲染，需服务端分页或虚拟滚动。
+- 搜索输入 debounce 300ms，避免每个字符触发请求。
+
+## 8. 真相源优先级
+
+```text
+设计稿 > Design Brief > Product Spec
+```