@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,45 @@
+# 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 | |
+
+## 公共组件改动影响面
+
+如果本次不是新增组件，而是修改 `existing` 公共组件，至少补这张表：
+
+| 公共组件 | 受影响页面 / 模块 | 兼容性策略 | 风险 | 需要补的验证 |
+| --- | --- | --- | --- | --- |
+| | | 保持旧 props / 新增可选 props / 包装层兼容 | 样式 / 交互 / 权限 / 数据 | story / interaction / e2e / visual |
+
+规则:
+
+- 不允许为了单个页面直接破坏现有 props 契约。
+- 能通过新增可选 props、slot、variant 或 wrapper 解决时，不直接改旧行为。
+- 如果必须改旧行为，必须列出所有受影响调用方和回归验证。

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

@@ -0,0 +1,183 @@
+# 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 | | | |
+| 加载 | | | |
+| submitting | | | |
+| 错误 | | | |
+| retry | | | |
+| offline | | | |
+| 空态 | | | |
+| 批量操作 | | | |
+
+## 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
+  }
+}

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

@@ -0,0 +1,165 @@
+# Frontend Architecture 模板
+
+> 目标: 在前端实现前声明页面、feature、组件、状态、API、样式和测试边界，防止把整页逻辑堆到一个组件里。
+
+## 1. 基本信息
+
+- Feature ID:
+- 页面 / 模块:
+- 关联需求:
+- 关联路由:
+- 目标质量等级: P0 / P1 / P2 / P3
+- 设计真相源:
+- Contract 真相源:
+- 最后更新:
+
+## 2. 架构目标
+
+- 本次前端架构要解决的问题:
+- 需要支持的用户流程:
+- 本期不处理的能力:
+- 主要风险:
+
+## 3. 分层与目录
+
+| 层级 | 建议路径 | 职责 | 禁止事项 |
+| --- | --- | --- | --- |
+| Page / Route | `app/...` / `pages/...` | 路由、布局组合、数据预取入口 | 写业务细节和 UI primitive |
+| Feature | `features/<domain>/` | 业务组件、业务 hooks、权限、字段映射 | 放跨业务通用组件 |
+| UI primitives | `packages/ui/` / `components/ui/` | 无业务语义的基础组件 | 依赖 API、权限或业务枚举 |
+| Data table / List | `packages/ui/data-table/` 或 feature 内 | 排序、筛选、分页、列显隐 | 混入具体业务字段文案 |
+| API client | `packages/api-client/` / `features/<domain>/api/` | HTTP 调用、契约生成 client | 直接操作 UI 状态 |
+| Model / Schema | `features/<domain>/model/` | 类型、枚举、校验、URL query 解析 | 把展示样式写进 schema |
+
+## 4. 组件树
+
+```text
+<Page>
+  <FeatureShell>
+    <Toolbar />
+    <FilterBar />
+    <Content />
+    <Pagination />
+    <DialogOrDrawer />
+  </FeatureShell>
+</Page>
+```
+
+| 组件 | 层级 | 职责 | 数据输入 | 事件输出 | 可复用范围 |
+| --- | --- | --- | --- | --- | --- |
+| | Page / Feature / Primitive | | | | local / feature / project |
+
+## 5. 状态管理
+
+| 状态 | 所属层级 | 来源 | 持久化方式 | 变化事件 | 测试方式 |
+| --- | --- | --- | --- | --- | --- |
+| URL filters | Page / Feature | query string | URL | filter change / reset | e2e |
+| Remote data | Feature | API client | cache / none | fetch / refetch | mock + e2e |
+| Form state | Component | user input | local | submit / cancel | interaction |
+| UI state | Component | user interaction | local | open / close | story |
+
+规则:
+
+- 可分享、可回退、影响查询结果的状态优先进入 URL。
+- 远程数据状态不得散落在多个展示组件中。
+- 表单 dirty、提交中、提交失败必须有明确状态来源。
+- 权限状态必须能追溯到 PRD、auth context 或 contract。
+- 同一业务条件只能有一个主状态来源；不要同时放在 URL、store、本地 state 和 form 中。
+- 页面级临时 UI 状态默认留在本地，不要为了方便提升到全局 store。
+- 远程数据、缓存 key、失效时机和 refetch 触发条件必须写清。
+
+## 5.1 缓存与失效策略
+
+| 数据 | 缓存层 | key / query 标识 | 失效触发条件 | 手动刷新入口 | 验证方式 |
+| --- | --- | --- | --- | --- | --- |
+| | query cache / local cache / browser storage / none | | create / update / delete / permission change / timeout | | unit / integration / e2e |
+
+规则:
+
+- 写操作完成后，必须明确哪些列表、详情、统计或徽标需要失效或同步更新。
+- 如果存在 optimistic update、回滚或离线缓存，必须说明失败恢复策略。
+- 不允许只写“自动刷新”而不写状态来源、key 或触发条件。
+
+## 6. API 与数据边界
+
+| UI 需求 | API / Contract | 字段 | 错误态 | 前端兜底 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+规则:
+
+- UI 字段必须能追溯到 contract 或 PRD 数据字典。
+- 展示组件不得拼接 HTTP URL 或处理响应状态码。
+- API client 抛出的错误必须映射到用户可理解的错误态。
+- mock 数据必须覆盖 default / empty / error / long_content / permission。
+- 页面或组件中不得直接手写 `fetch/axios/baseURL/token/error` 处理逻辑，统一走项目 API client。
+- 如果 contract 已生成 types / client，前端不得再手写一套重复 request/response schema。
+
+## 7. 响应式架构
+
+| 视口 | 结构 | 筛选策略 | 列表 / 表格策略 | 操作区策略 | 必需截图 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop >= 1200px | | | | | |
+| Tablet 768-1199px | | | | | |
+| Mobile < 768px | | | | | |
+
+规则:
+
+- 移动端主要流程不能只依赖横向滚动。
+- 表格转卡片时必须说明字段优先级。
+- 操作区折叠时必须保留主操作可见或一跳可达。
+
+## 8. 动效与可访问性
+
+| 组件 / 场景 | 动效 | reduced motion 行为 | 焦点 / 键盘规则 | ARIA / 语义 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+规则:
+
+- 动效只用于状态解释，不用于隐藏加载或错误。
+- 弹窗、抽屉、菜单必须定义焦点进入、循环、关闭和恢复。
+- 状态变化、错误和保存结果必须有屏幕阅读器可感知的反馈。
+
+## 9. 性能预算
+
+| 风险 | 阈值 / 预算 | 处理策略 | 验证方式 |
+| --- | --- | --- | --- |
+| 列表行数 | | client / server / virtualized | |
+| 首屏依赖 | | lazy / split / avoid | |
+| 图片 / 图标 | | optimize / sprite / lazy | |
+| 动效 | | transform / opacity | |
+
+## 10. Story 与测试矩阵
+
+| 状态 / 场景 | Story | Interaction | E2E | Visual | A11y | Performance |
+| --- | --- | --- | --- | --- | --- | --- |
+| default | | | | | | |
+| loading | | | | | | |
+| empty | | | | | | |
+| error | | | | | | |
+| permission | | | | | | |
+| long_content | | | | | | |
+| mobile | | | | | | |
+
+## 11. 复用决策
+
+| 候选组件 / Hook | 复用范围 | 是否抽象 | 原因 | 约束 |
+| --- | --- | --- | --- | --- |
+| | local / feature / project | Yes / No | | |
+
+抽象规则:
+
+- 基础 primitive 可以直接进入通用层。
+- 业务组件默认留在 feature 内。
+- 只有当第二个真实使用场景出现或 DEV-PLAN 明确要求时，才抽项目级复用组件。
+- 修改既有公共组件时，必须先列出受影响调用方、兼容策略和回归验证，不允许为单页需求直接破坏旧 props 或旧样式语义。
+
+## 12. 完成标准
+
+- [ ] 组件分层与目录边界已明确。
+- [ ] 状态来源、持久化和事件已明确。
+- [ ] API 字段和错误态已追溯到 contract 或 PRD。
+- [ ] 响应式结构有 desktop / tablet / mobile 策略。
+- [ ] 动效、reduced motion、键盘和可访问性规则已定义。
+- [ ] Story / E2E / visual / a11y / performance 证据路径已定义。

package/package-source/docs/codex-harness-engineering/templates/design/image-to-frontend-spec.md

@@ -0,0 +1,120 @@
+# Image To Frontend Spec 模板
+
+> 目标: 把评审通过的 UI 图片转换成可实现的前端规格。前端编码只能依据本规格、Design Tokens、Component Map 和 Screen States，不直接凭图片猜实现。
+
+## 1. 输入图片
+
+| Image ID | Page ID | State | 图片路径 / 链接 | 评审结论 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | page-001 | default | | PASS |
+
+## 2. 页面布局规格
+
+| 区域 | 位置 | 尺寸 / 约束 | 内容 | 响应式行为 |
+| --- | --- | --- | --- | --- |
+| Header | | | | |
+| Main | | | | |
+| Aside | | | | |
+| Footer / Action Bar | | | | |
+
+## 3. 组件实现映射
+
+| 图片元素 | 前端组件 | 层级 | 复用来源 | Props / 数据 | 事件 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | page / feature / primitive | existing / new | | | default |
+
+## 4. CSS / Token 映射
+
+| 图片表现 | Token / CSS 变量 | 值 | 备注 |
+| --- | --- | --- | --- |
+| 主背景 | `--color-bg-default` | | |
+| 主文字 | `--color-text-primary` | | |
+| 间距 | `--space-*` | | |
+| 圆角 | `--radius-*` | | |
+
+## 5. 状态实现规格
+
+| State | 数据条件 | UI 行为 | 组件变化 | 动效 | 测试 |
+| --- | --- | --- | --- | --- | --- |
+| default | | | | | story / e2e / visual |
+| empty | | | | | story / e2e / visual |
+| loading | | | | | story / visual |
+| error | | | | | story / e2e / visual |
+| disabled | | | | | story / interaction / visual |
+| submitting | | | | | story / interaction / e2e |
+| retry | | | | | story / interaction / e2e |
+| offline | | | | | story / e2e / visual |
+
+## 5.1 响应式实现规格
+
+| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
+| --- | --- | --- | --- | --- | --- |
+| Desktop 1440x900 | | | | | required |
+| Tablet 768x1024 | | | | | required / optional |
+| Mobile 375x812 | | | | | required |
+
+## 5.2 动效与可访问性规格
+
+| 场景 | 动效 | reduced motion | 键盘 / 焦点 | ARIA / 状态提示 |
+| --- | --- | --- | --- | --- |
+| | | | | |
+
+### 5.3 表单与安全区规格
+
+| 场景 | 校验时机 | 错误提示 | 提交中策略 | 键盘类型 / 输入限制 | 安全区 / 键盘遮挡处理 |
+| --- | --- | --- | --- | --- | --- |
+| | blur / submit / input | inline / summary / toast | disabled / spinner / optimistic | | |
+
+## 6. Mock 数据
+
+| 场景 | 数据文件 / 生成方式 | 覆盖状态 |
+| --- | --- | --- |
+| default | | |
+| empty | | |
+| error | | |
+| long_content | | |
+
+## 7. 实现任务输入
+
+- 必读:
+  - `docs/product/requirement-interface-matrix.md`
+  - `docs/harness/frontend-quality-rules.md`
+  - `docs/design/frontend-architecture.md`
+  - `docs/design/component-map.md`
+  - `docs/design/screen-states.md`
+  - `docs/design/design-tokens.json`
+  - 本文件
+- 必须输出:
+  - 前端组件 / 页面
+  - stories
+  - mock 数据
+  - visual baseline 或截图证据
+  - a11y smoke 和 responsive 截图证据
+
+## 8. 视觉还原验证计划
+
+| Page ID | State | Viewport | Route / URL | 数据准备 | 参考图 | 实拍截图 | 对比报告 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| page-001 | default | Desktop 1440x900 | | | `docs/design/assets/.../reference.png` | `artifacts/visual-review/.../actual.png` | `artifacts/visual-review/.../review.md` |
+
+规则:
+
+- 前端实现完成后，必须启动真实浏览器访问页面并截图。
+- 截图必须保存到 `artifacts/visual-review/<feature>/<page>/`。
+- 参考图必须来自已通过 `ui-image-review.md` 的设计图。
+- 对比过程使用 `visual-parity-review.md`，结论为 `PASS` 才能通过 Stage 1。
+- 如果 UI 和设计图不一致，必须修复前端代码并重新截图，不允许只改验收文档绕过。
+- 如果 `复用来源 = existing`，实现任务必须在 `component-map.md` 或 `frontend-architecture.md` 里写清 props 兼容策略和受影响调用方。
+
+## 9. 通过标准
+
+- [ ] 图片中的每个可见业务元素都有组件映射。
+- [ ] 每个组件都能追溯到数据、事件和状态。
+- [ ] 每个组件都声明了 page / feature / primitive 层级和复用边界。
+- [ ] CSS 实现可以从 token 或明确规则得出。
+- [ ] 响应式行为可以从 viewport 规格得出。
+- [ ] 动效和 reduced motion 行为已明确。
+- [ ] 表单校验、submitting、retry、offline 和安全区处理已明确。
+- [ ] 没有直接从图片猜出的隐藏业务逻辑。
+- [ ] 前端实现任务不再需要重新做视觉决策。
+- [ ] 真实浏览器截图与设计参考图完成视觉还原对比，`visual-parity-review.md` 结论为 PASS。