@pzy560117/codex-harness 0.1.3 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/package-assets/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/package-assets/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/package-assets/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
-  }
-}

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

@@ -1,147 +0,0 @@
-# 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。
-
-## 6. API 与数据边界
-
-| UI 需求 | API / Contract | 字段 | 错误态 | 前端兜底 |
-| --- | --- | --- | --- | --- |
-| | | | | |
-
-规则:
-
-- UI 字段必须能追溯到 contract 或 PRD 数据字典。
-- 展示组件不得拼接 HTTP URL 或处理响应状态码。
-- API client 抛出的错误必须映射到用户可理解的错误态。
-- mock 数据必须覆盖 default / empty / error / long_content / permission。
-
-## 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 明确要求时，才抽项目级复用组件。
-
-## 12. 完成标准
-
-- [ ] 组件分层与目录边界已明确。
-- [ ] 状态来源、持久化和事件已明确。
-- [ ] API 字段和错误态已追溯到 contract 或 PRD。
-- [ ] 响应式结构有 desktop / tablet / mobile 策略。
-- [ ] 动效、reduced motion、键盘和可访问性规则已定义。
-- [ ] Story / E2E / visual / a11y / performance 证据路径已定义。

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

@@ -1,108 +0,0 @@
-# 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 |
-
-## 5.1 响应式实现规格
-
-| Viewport | 布局 | 筛选策略 | 表格 / 列表策略 | 操作区策略 | 截图要求 |
-| --- | --- | --- | --- | --- | --- |
-| Desktop 1440x900 | | | | | required |
-| Tablet 768x1024 | | | | | required / optional |
-| Mobile 375x812 | | | | | required |
-
-## 5.2 动效与可访问性规格
-
-| 场景 | 动效 | reduced motion | 键盘 / 焦点 | ARIA / 状态提示 |
-| --- | --- | --- | --- | --- |
-| | | | | |
-
-## 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 和设计图不一致，必须修复前端代码并重新截图，不允许只改验收文档绕过。
-
-## 9. 通过标准
-
-- [ ] 图片中的每个可见业务元素都有组件映射。
-- [ ] 每个组件都能追溯到数据、事件和状态。
-- [ ] 每个组件都声明了 page / feature / primitive 层级和复用边界。
-- [ ] CSS 实现可以从 token 或明确规则得出。
-- [ ] 响应式行为可以从 viewport 规格得出。
-- [ ] 动效和 reduced motion 行为已明确。
-- [ ] 没有直接从图片猜出的隐藏业务逻辑。
-- [ ] 前端实现任务不再需要重新做视觉决策。
-- [ ] 真实浏览器截图与设计参考图完成视觉还原对比，`visual-parity-review.md` 结论为 PASS。

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

@@ -1,122 +0,0 @@
-# Screen States 模板
-
-> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
-
-## 页面名称
-
-- Page ID:
-- 页面:
-- 路由/入口:
-- 角色:
-- 关联需求:
-- 关联设计稿:
-
-## 状态清单
-
-### default
-
-- 触发条件:
-- 数据条件:
-- 页面表现:
-- 用户可执行动作:
-- 组件影响:
-- story 名称:
-- visual baseline:
-
-### empty
-
-- 触发条件:
-- 数据条件:
-- 页面表现:
-- 用户可执行动作:
-- 恢复路径:
-- story 名称:
-- visual baseline:
-
-### loading
-
-- 触发条件:
-- 等待对象:
-- 页面表现:
-- 用户可执行动作:
-- 超时后行为:
-- story 名称:
-- visual baseline:
-
-### error
-
-- 触发条件:
-- 错误类型:
-- 页面表现:
-- 用户可执行动作:
-- 重试 / 兜底:
-- story 名称:
-- visual baseline:
-
-### permission_denied
-
-- 触发条件:
-- 权限规则:
-- 页面表现:
-- 用户可执行动作:
-- 是否隐藏受限操作:
-- story 名称:
-- visual baseline:
-
-### disabled
-
-- 触发条件:
-- 禁用对象:
-- 禁用原因展示:
-- 用户可执行动作:
-- 恢复条件:
-- story 名称:
-- visual baseline:
-
-### long_content
-
-- 触发条件:
-- 极端数据:
-- 页面表现:
-- 用户可执行动作:
-- 截断 / 换行 / tooltip 规则:
-- story 名称:
-- visual baseline:
-
-### responsive/mobile
-
-- 触发条件:
-- 断点:
-- 页面表现:
-- 用户可执行动作:
-- 折叠策略:
-- 表格 / 列表替代形态:
-- 主操作可达性:
-- 触控目标:
-- 长文本 / 长标签处理:
-- story 名称:
-- visual baseline:
-
-### motion/reduced_motion
-
-- 触发条件:
-- 默认动效:
-- reduced motion 表现:
-- 用户可执行动作:
-- 组件影响:
-- story 名称:
-- visual baseline:
-
-## 状态到测试映射
-
-| 状态 | Story | Interaction Test | E2E | Visual |
-| --- | --- | --- | --- | --- |
-| default | | | | |
-| empty | | | | |
-| loading | | | | |
-| error | | | | |
-| permission_denied | | | | |
-| disabled | | | | |
-| long_content | | | | |
-| mobile | | | | |
-| reduced_motion | | | | |