@pzy560117/codex-harness 0.1.3 → 0.1.5

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

@@ -1,122 +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 |
+# 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/component-map.md

@@ -1,31 +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 | |
+# 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 解决时，不直接改旧行为。
+- 如果必须改旧行为，必须列出所有受影响调用方和回归验证。