@pzy560117/codex-harness 0.1.3 → 0.1.4

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

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

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

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

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

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

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

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

@@ -1,88 +0,0 @@
-{
-  "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
-  }
-}