@pzy560117/codex-harness 0.1.3 → 0.1.5

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

@@ -1,64 +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 资产
-- 没有接真实构建配置
-
-目的不是提供业务代码，而是提供**项目开始前的真相源样例**。
+# 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

@@ -1,25 +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
+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

@@ -1,20 +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",
-        },
-      },
-    },
-  },
-});
+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

@@ -1,44 +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 未要求功能。
-```
+# 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

@@ -1,17 +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 |
+# 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

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