@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/contracts/openapi.yaml

@@ -0,0 +1,182 @@
+openapi: 3.0.3
+info:
+  title: Ticket Views API
+  version: 0.1.0
+  description: Contract-first example for a ticket filter and saved views workflow.
+servers:
+  - url: https://api.example.com
+tags:
+  - name: tickets
+  - name: ticket-views
+paths:
+  /tickets:
+    get:
+      tags: [tickets]
+      summary: List tickets with filters
+      operationId: listTickets
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [open, pending, resolved]
+        - in: query
+          name: priority
+          schema:
+            type: string
+            enum: [low, medium, high]
+        - in: query
+          name: assigneeId
+          schema:
+            type: string
+        - in: query
+          name: page
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - in: query
+          name: pageSize
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        "200":
+          description: Ticket list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketListResponse"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "403":
+          description: Permission denied
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /ticket-views:
+    get:
+      tags: [ticket-views]
+      summary: List saved ticket views
+      operationId: listTicketViews
+      responses:
+        "200":
+          description: Saved ticket views
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TicketView"
+    post:
+      tags: [ticket-views]
+      summary: Create a saved ticket view
+      operationId: createTicketView
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTicketViewRequest"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketView"
+        "400":
+          description: Invalid payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: View name already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+components:
+  schemas:
+    Ticket:
+      type: object
+      required: [id, title, status, priority]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+          nullable: true
+    TicketListResponse:
+      type: object
+      required: [items, page, pageSize, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Ticket"
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        total:
+          type: integer
+    TicketFilter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+    TicketView:
+      type: object
+      required: [id, name, filters]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    CreateTicketViewRequest:
+      type: object
+      required: [name, filters]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/package-source/docs/codex-harness-engineering/templates/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/contracts/prism-usage.md

@@ -0,0 +1,34 @@
+# Prism Usage 模板
+
+## 1. 目标
+
+用 Prism 在真实后端完成前提供:
+
+- mock server
+- request/response contract 验证
+- 异常态联调入口
+
+## 2. 安装
+
+```bash
+npm install -D @stoplight/prism-cli
+```
+
+## 3. 启动 mock server
+
+```bash
+npx prism mock contracts/openapi.yaml -h 0.0.0.0
+```
+
+## 4. 启动 validation proxy
+
+```bash
+npx prism proxy contracts/openapi.yaml https://api.example.com
+```
+
+## 5. 推荐联调顺序
+
+1. 先用 Prism mock 跑前端
+2. 再生成 Orval client / mocks
+3. 前端先围绕 generated client 写页面和测试
+4. 最后切真实后端并跑 Prism proxy

package/package-source/docs/codex-harness-engineering/templates/design/ai-image-brief.md

@@ -0,0 +1,122 @@
+# AI Image Brief 模板
+
+> 目标: 在写前端代码前，先基于完整产品和设计规格，使用 AI 生图/编辑工具生成可评审的前端界面图。图片不是最终实现规范，图片评审通过后才进入图转前端规格。
+
+## 1. 基本信息
+
+- Feature ID:
+- Page ID:
+- 页面名称:
+- 设备 / 画布: Desktop 1440px / Tablet / Mobile 375px / Other
+- 设计来源: Product Spec / Design Brief / Component Map / Screen States / Design Tokens
+- 生成批次:
+- 状态: Draft / Review / Approved / Rejected
+
+## 2. 输入真相源
+
+| 真相源 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Approved / Draft | |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Approved / Draft | |
+| Design Brief | `docs/design/design-brief.md` | Approved / Draft | |
+| Component Map | `docs/design/component-map.md` | Approved / Draft | |
+| Screen States | `docs/design/screen-states.md` | Approved / Draft | |
+| Design Tokens | `docs/design/design-tokens.json` | Approved / Draft | |
+
+## 3. CSS / 视觉要求
+
+| 类别 | 要求 |
+| --- | --- |
+| 颜色 | |
+| 字体 | |
+| 字号层级 | |
+| 间距 | |
+| 圆角 | |
+| 阴影 | |
+| 表格 / 列表密度 | |
+| 表单控件高度 | |
+| 按钮层级 | |
+| 状态色 | |
+| 响应式折叠 | |
+
+## 4. 必须生成的界面状态
+
+| State | 是否生成 | 说明 | 输出图片 |
+| --- | --- | --- | --- |
+| default | Yes | | |
+| empty | Yes | | |
+| loading | Yes | | |
+| error | Yes | | |
+| permission_denied | Yes / No | | |
+| disabled | Yes / No | | |
+| long_content | Yes / No | | |
+| mobile | Yes / No | | |
+
+## 5. 生图提示词
+
+```text
+生成 [页面名称] 的生产级前端 UI 设计图。
+
+页面目标:
+[从 PRD 摘要填写]
+
+用户角色:
+[填写角色]
+
+画布:
+[Desktop 1440px / Mobile 375px 等]
+
+视觉规范:
+- 颜色:
+- 字体:
+- 间距:
+- 圆角:
+- 阴影:
+- 信息密度:
+- 状态色:
+
+页面结构:
+- 顶部:
+- 主内容:
+- 侧边 / 辅助区域:
+- 底部 / 操作区:
+
+组件:
+- [来自 component-map 的组件和职责]
+
+必须体现的状态:
+- [本批次状态]
+
+边界要求:
+- 长文本:
+- 空数据:
+- 错误:
+- 无权限:
+- 移动端:
+
+禁止:
+- 不要添加 Product Spec 没有的功能
+- 不要省略 required state
+- 不要使用与 Design Tokens 冲突的颜色、字号或间距
+```
+
+## 6. 图片编辑提示词
+
+```text
+基于上一版图继续编辑，不改变页面信息架构。
+
+需要修改:
+- [具体差异]
+
+保持不变:
+- [已通过评审的布局/组件/样式]
+
+补充状态:
+- [需要补的状态]
+```
+
+## 7. 输出记录
+
+| Image ID | State | 文件 / 链接 | 生成提示词版本 | 评审状态 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | default | | v1 | Draft |

package/package-source/docs/codex-harness-engineering/templates/design/assets/README.md

@@ -0,0 +1,24 @@
+# Design Assets
+
+本目录用于保存已评审的 UI 设计参考图。
+
+## 工具策略
+
+- 本目录的 AI 生图和图片编辑默认使用 Codex 内置 `image_gen` 工具。
+- 项目绑定图片必须复制或移动到本目录后，任务才允许通过。
+- `manifest.md` 必须为每张最终 PNG 记录 `source_tool: image_gen`、prompt、覆盖页面、覆盖状态、评审结论和实现注意事项。
+- 浏览器截图、Playwright 截图、HTML/CSS 截图、程序化绘图和占位 PNG 只能作为实现证据或临时脚手架，不能满足本目录的设计参考图要求。
+- CLI fallback 或第三方服务必须先获得用户显式确认，并且已配置所需凭据；它们不是本项目默认路径。
+
+## 必需补齐文件
+
+按当前 feature 的页面和状态矩阵补齐参考图，例如：
+
+- `<feature>-<page>-default-reference.png`
+- `<feature>-<page>-empty-reference.png`
+- `<feature>-<page>-error-reference.png`
+- `<feature>-<page>-disabled-reference.png`
+- `<feature>-mobile-reference.png`
+- `manifest.md`
+
+`artifacts/visual-review/` 下的浏览器截图是实现证据，不能替代本目录的设计参考图。

package/package-source/docs/codex-harness-engineering/templates/design/component-map.md

@@ -0,0 +1,31 @@
+# Component Map 模板
+
+> 目标: 明确每个页面由哪些可复用组件组成，防止 Codex 直接生成不可维护的整页代码。
+
+| 页面/模块 | 组件 | 层级 | 责任 | 复用来源 | Props / 数据输入 | 事件输出 | 必备状态 | 测试方式 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| | | page / feature / primitive | | existing / new / generated | | | default, empty, loading, error | story / interaction / e2e / visual |
+
+## 组件状态矩阵
+
+| 组件 | default | empty | loading | error | disabled | permission | long_content | mobile |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| | 是 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 | 是/否 |
+
+## 复用与新增规则
+
+- 优先复用现有组件库，不要为单一页面随意造新组件。
+- 新组件必须说明为什么现有组件不满足。
+- `必备状态` 至少覆盖 `default / empty / loading / error`。
+- `测试方式` 写明 story、interaction test、e2e 或 visual。
+- generated client / types 不作为 UI 组件复用来源。
+- 如果组件依赖接口字段，必须能追溯到 `contracts/openapi.yaml` 或 PRD 数据字典。
+- `primitive` 组件不得依赖业务枚举、权限、API client 或路由。
+- `feature` 组件可以依赖业务字段和权限，但默认不进入通用组件库。
+- 抽到项目级复用层前，必须有两个真实使用场景或明确的架构决策。
+
+## 组件复用决策
+
+| 候选组件 / Hook | 当前用途 | 未来复用场景 | 决策 | 原因 |
+| --- | --- | --- | --- | --- |
+| | | | local / feature / project | |

package/package-source/docs/codex-harness-engineering/templates/design/design-brief.md

@@ -0,0 +1,178 @@
+# Design Brief 模板
+
+> 目标: 把口头设计偏好、设计稿和产品需求翻译成前端可实现、可审查、可回归的设计真相源。
+
+## 1. 基本信息
+
+- 产品名称:
+- Feature ID:
+- 功能主题:
+- 设计来源: Figma / 截图 / AI 视觉探索 / 现有页面延展 / 其他
+- 设计负责人:
+- 当前状态: Draft / Review / Approved / Changed
+- 目标质量等级: P0 / P1 / P2 / P3
+- 最后更新:
+
+## 2. 设计目标
+
+- 这次设计要解决的核心问题:
+- 优先优化的体验指标:
+- 主要用户:
+- 主要使用场景:
+- 本期不优化的体验:
+
+## 3. 信息架构
+
+| 层级 | 内容 / 区域 | 目的 | 优先级 |
+| --- | --- | --- | --- |
+| L1 | | | P0 |
+| L2 | | | P1 |
+
+## 4. 视觉方向
+
+- 主题风格:
+- 品牌气质:
+- 关键词:
+- 避免的风格:
+- 参考页面 / 竞品:
+
+## 4.1 审美验收与反模式
+
+| 项目 | 标准 | 禁止事项 | 验收方式 |
+| --- | --- | --- | --- |
+| 信息层级 | | | visual review |
+| 密度与扫描 | | | screenshot |
+| 主操作识别 | | | interaction / visual |
+| 状态识别 | | | story / visual |
+| 品牌一致性 | | | design review |
+
+## 5. 色彩策略
+
+| Token / 用途 | 值 | 使用场景 | 禁用场景 |
+| --- | --- | --- | --- |
+| primary | | | |
+| background | | | |
+| success | | | |
+| warning | | | |
+| danger | | | |
+
+## 6. 排版与密度
+
+- 字体:
+- 标题层级:
+- 正文层级:
+- 数字 / 数据展示风格:
+- 信息密度:
+- 表格行高:
+- 表单控件高度:
+
+## 7. 布局与组件原则
+
+| 类型 | 原则 | 复用来源 | 禁止事项 |
+| --- | --- | --- | --- |
+| 页面布局 | | | |
+| 表格 / 列表 | | | |
+| 表单 | | | |
+| 弹窗 / 抽屉 | | | |
+| 状态反馈 | | | |
+
+## 8. 交互原则
+
+| 交互 | 行为 | 反馈 | 约束 |
+| --- | --- | --- | --- |
+| 主按钮 | | | |
+| 次按钮 | | | |
+| hover / focus / active | | | |
+| 加载 | | | |
+| 错误 | | | |
+| 空态 | | | |
+| 批量操作 | | | |
+
+## 8.1 UX Writing
+
+| 场景 | 文案原则 | 示例 | 禁止事项 |
+| --- | --- | --- | --- |
+| 空态 | | | |
+| 筛选无结果 | | | |
+| 加载 | | | |
+| 错误 | | | |
+| 权限不足 | | | |
+| 保存成功 / 失败 | | | |
+
+## 9. 动效等级
+
+| 场景 | 动效 | 时长 | easing | reduced motion | 是否必需 |
+| --- | --- | --- | --- | --- | --- |
+| 页面切换 | | | | | 否 |
+| 列表刷新 | | | | | 否 |
+| 弹窗出现 | | | | | 是/否 |
+| 抽屉出现 | | | | | 是/否 |
+| 筛选 chip 增删 | | | | | 是/否 |
+| 骨架屏 / 进度反馈 | | | | | 是 |
+
+动效约束:
+
+- 首选 `transform` 和 `opacity`。
+- 不允许动效隐藏错误、禁用、权限不足或保存失败。
+- 必须说明 reduced motion 下的替代行为。
+
+## 10. 响应式要求
+
+| 断点 | 宽度 | 布局变化 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 必须验证的页面 |
+| --- | --- | --- | --- | --- | --- | --- |
+| Desktop | >= 1200px | | | | | |
+| Tablet | 768-1199px | | | | | |
+| Mobile | < 768px | | | | | |
+
+响应式约束:
+
+- 移动端主要流程不能只依赖横向滚动。
+- 表格转卡片时必须说明字段优先级。
+- 长文本、长数字、长标签必须有截断、换行或 tooltip 规则。
+
+## 11. 可访问性要求
+
+- 对比度要求:
+- 键盘可达性:
+- 焦点顺序:
+- 语义化 / ARIA:
+- 状态提示:
+- 错误提示与屏幕阅读器:
+- 弹窗 / 抽屉 focus trap:
+- reduced motion:
+- 触控目标尺寸:
+
+## 11.1 性能预算
+
+| 风险 | 预算 / 阈值 | 策略 | 验证方式 |
+| --- | --- | --- | --- |
+| 首屏依赖 | | | |
+| 列表 / 表格规模 | | | |
+| 图片 / 图标 | | | |
+| 动效帧率 | | | |
+| 数据刷新频率 | | | |
+
+## 12. 真相源优先级
+
+```text
+设计稿 > Design Brief > Product Spec
+```
+
+冲突处理:
+
+- 视觉细节冲突时以设计稿为准。
+- 视觉稿缺失时以本 Design Brief 为准。
+- 功能逻辑以 Product Spec 为准。
+- 如果 Product Spec 和设计稿表达冲突，先阻塞并更新真相源，不直接编码。
+
+## 13. 交付物清单
+
+- [ ] 设计稿或 Figma 页面
+- [ ] `screen-states.md`
+- [ ] `component-map.md`
+- [ ] `design-tokens.json`
+- [ ] `frontend-architecture.md`
+- [ ] 需要补的 stories 清单
+- [ ] 关键页面 visual regression 清单
+- [ ] 无障碍 / 键盘访问要求
+- [ ] 性能预算与验证方式

package/package-source/docs/codex-harness-engineering/templates/design/design-tokens.json

@@ -0,0 +1,88 @@
+{
+  "color": {
+    "bg": {
+      "default": "#FFFFFF",
+      "subtle": "#F6F7F9",
+      "inverse": "#111827"
+    },
+    "text": {
+      "primary": "#111827",
+      "secondary": "#4B5563",
+      "muted": "#6B7280",
+      "inverse": "#FFFFFF"
+    },
+    "border": {
+      "default": "#D1D5DB",
+      "strong": "#9CA3AF"
+    },
+    "status": {
+      "success": "#15803D",
+      "warning": "#B45309",
+      "danger": "#B91C1C",
+      "info": "#1D4ED8"
+    }
+  },
+  "spacing": {
+    "xs": 4,
+    "sm": 8,
+    "md": 12,
+    "lg": 16,
+    "xl": 24
+  },
+  "radius": {
+    "sm": 4,
+    "md": 8,
+    "lg": 12
+  },
+  "typography": {
+    "fontFamily": {
+      "base": "system-ui, sans-serif",
+      "mono": "Consolas, monospace"
+    },
+    "fontSize": {
+      "sm": 12,
+      "md": 14,
+      "lg": 16,
+      "xl": 20
+    },
+    "fontWeight": {
+      "regular": 400,
+      "medium": 500,
+      "bold": 700
+    },
+    "lineHeight": {
+      "sm": 1.4,
+      "md": 1.5,
+      "lg": 1.6
+    }
+  },
+  "shadow": {
+    "sm": "0 1px 2px rgba(0, 0, 0, 0.08)",
+    "md": "0 4px 12px rgba(0, 0, 0, 0.12)"
+  },
+  "motion": {
+    "duration": {
+      "fast": 120,
+      "base": 160,
+      "slow": 220
+    },
+    "easing": {
+      "standard": "cubic-bezier(0.2, 0, 0, 1)",
+      "exit": "cubic-bezier(0.4, 0, 1, 1)"
+    },
+    "reducedMotion": "respect-user-preference"
+  },
+  "breakpoint": {
+    "mobile": 768,
+    "tablet": 1200
+  },
+  "zIndex": {
+    "dropdown": 20,
+    "drawer": 40,
+    "modal": 50,
+    "toast": 60
+  },
+  "touchTarget": {
+    "min": 44
+  }
+}