@pzy560117/codex-harness 0.1.4 → 0.1.6

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/context/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放 `context/*` 模板文档的镜像副本。
+
+## 结构索引
+
+- `CURRENT_TASK.md`、`repo-map.md`、`architecture-brief.md` 等上下文模板镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/context/*`。
+- 这里是镜像层，不要先改。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/context/API_MAP.md

@@ -0,0 +1,18 @@
+# API_MAP
+
+记录当前项目的接口面。没有真实业务 API 时，也可以先记录命令入口、路由入口、合同文件和 SDK/client 生成位置。
+
+## 建议结构
+
+| 接口 | 位置 | 作用 | 上游 | 下游 |
+| --- | --- | --- | --- | --- |
+
+## 建议补充
+
+- 认证方式
+- 错误模型
+- contract 位置
+- mock / prism / SDK 生成位置
+- 统一请求入口（例如 `apiClient` / generated client）
+- 分页字段约定（例如 `page/pageSize`）
+- 统一响应包装（例如 `code/message/data`）

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/context/CURRENT_TASK.md

@@ -0,0 +1,89 @@
+# CURRENT_TASK
+
+记录当前任务的最小必要事实，不要把完整 PRD 或长篇讨论直接堆进这里。
+
+## 建议填写项
+
+- 任务目标:
+- 任务性质（bugfix / feature / refactor / chore）:
+- 验收标准:
+- 当前阶段:
+- owned paths:
+- 这个功能属于哪个模块:
+- 项目里有没有类似实现:
+- 类似页面:
+- 类似接口:
+- 类似组件:
+- 类似状态管理:
+- 当前状态分层决策（URL / remote cache / global store / local state / form）:
+- 哪些状态禁止重复存放:
+- 缓存失效或刷新规则:
+- 设计系统 / token 约束:
+- 移动端安全区 / 键盘遮挡处理:
+- 表单校验与提交流程策略:
+- Controller / Handler 边界:
+- Service 边界:
+- Repository / DAO 边界:
+- 事务 / 幂等策略:
+- 异常处理与错误码策略:
+- 权限校验边界（角色 / 资源 / 本人 / 租户）:
+- 输入校验边界（类型 / 长度 / 枚举 / 金额 / 日期 / 文件）:
+- 敏感信息脱敏策略（响应 / 日志 / trace / 审计）:
+- 风控 / 限流策略:
+- 类似测试:
+- 本轮 development_validation:
+- 本轮 acceptance_validation:
+- 未运行测试 / 豁免及原因:
+- 假测试风险提示:
+- 复用决定:
+- 不复用理由:
+- 如果修改公共组件，组件名称:
+- 如果修改公共组件，受影响页面 / 模块:
+- 如果修改公共组件，props 兼容性影响:
+- 如果修改公共组件，样式 / 交互回归风险:
+- 如果修改公共组件，需要补哪些组件测试 / E2E:
+- 是否新增目录:
+- 新目录名称:
+- 为什么现有目录不能放:
+- 新目录未来会放什么:
+- 是否符合当前目录结构:
+- 是否需要补子目录 `AGENTS.md`:
+- 需要改哪些文件:
+- 本任务涉及的业务名词统一叫法:
+- 禁止混用的同义词:
+- 新增 / 修改文件命名模式:
+- 新增函数 / hook / handler 命名约定:
+- 新增类型命名边界（Entity / DTO / Response / FormValues / ViewModel 等）:
+- 行为不变约束（接口 / 用户路径 / 数据结构 / 兼容逻辑）:
+- 允许清理的死代码 / 临时代码:
+- 不允许删除的兼容逻辑 / 历史入口:
+- 可能影响哪些调用方:
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 回归范围:
+- 前端性能预算:
+- 后端性能策略（索引 / 缓存 / 分页 / N+1）:
+- 弱网 / 离线 / 大数据量策略:
+- 日志 / trace 字段要求:
+- 观测指标 / 告警策略:
+- 需要跑哪些测试:
+- 风险点:
+- 依赖的真相源:
+- 关键验证命令:
+- 必需环境变量 / Secret:
+- 受影响配置文件（.env / package.json / Dockerfile / CI / nginx / k8s / config）:
+- 构建 / 部署影响:
+- 回滚配置策略:
+- 暂时不要动的区域:
+- 当前入口文件 / 页面 / 命令:
+- 相关类型 / 契约入口:
+- 相关配置 / 环境变量入口:
+
+## 使用规则
+
+- 新任务开始时更新。
+- 任务切换时清空旧事实。
+- 长会话续跑前先确认这里是否仍与当前任务一致。
+- 可复用经验进入 `docs/knowledge/*`，不要长期堆在这里。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/context/dev-plan.md

@@ -0,0 +1,166 @@
+# DEV-PLAN 模板
+
+## 1. 基本信息
+
+- `feature_id`:
+- `title`:
+- `owner`:
+- `source_docs`:
+  - `docs/product/...`
+  - `docs/design/...`
+  - `contracts/...`
+
+## 2. 目标与完成定义
+
+- 业务目标:
+- 技术目标:
+- Done 定义:
+
+## 3. 真相源
+
+- Product Spec:
+- PRD-Lite:
+- Page Inventory:
+- State Matrix:
+- Acceptance Criteria:
+- Acceptance Examples:
+- Requirement Interface Matrix:
+- Traceability Matrix:
+- Difficulty Research:
+- Design Brief:
+- 设计稿 / Figma:
+- Component Map:
+- Screen States:
+- Design Tokens:
+- AI Image Brief:
+- UI Image Review:
+- Image To Frontend Spec:
+- Visual Parity Review:
+- Contract:
+- Test Matrix:
+- E2E Plan:
+- Test Data Plan:
+- Test Data Matrix:
+- Risk Based Test Plan:
+- Regression Plan:
+- Evidence Protocol:
+- Failure Triage:
+- Coverage Policy:
+- Verify Matrix:
+- Repo map:
+
+## 4. 阶段闸门
+
+| 阶段 | 进入条件 | 输出 | 未满足时处理 |
+| --- | --- | --- | --- |
+| Product Readiness | 原始需求已澄清，P0/P1 需求已补齐验收标准、验收示例和追溯入口 | `docs/product/*`, `ACCEPTANCE_CRITERIA.md`, `ACCEPTANCE_EXAMPLES.md`, `TRACEABILITY_MATRIX.md` | BLOCKED 或补需求 |
+| Design Readiness | Product Readiness 通过 | `docs/design/*` | BLOCKED 或补设计 |
+| UI Image Readiness | CSS/视觉规范完整，AI 生图已评审 | `ai-image-brief.md`, `ui-image-review.md`, `image-to-frontend-spec.md` | BLOCKED 或重生成/编辑图片 |
+| Visual Parity Readiness | 前端页面已实现并可在浏览器打开 | `artifacts/visual-review/*`, `visual-parity-review.md` | BLOCKED 或修复 UI 后重新截图 |
+| Test Readiness | P0/P1 需求已映射到测试层级、测试数据、affected tests、evidence path 和回归范围；affected tests 与回归范围必须可追溯 | `test-matrix.md`, `TEST_DATA_MATRIX.md`, `RISK_BASED_TEST_PLAN.md`, `REGRESSION_PLAN.md`, `failure-triage.md` | BLOCKED 或补测试计划 |
+| Contract Readiness | API / 数据变化已明确 | `contracts/openapi.yaml` | BLOCKED 或豁免说明 |
+| Implementation | Product、Design、Plan、Testing 真相源齐全，Requirement IDs 已可追溯 | 代码、测试、trace | 禁止实现 |
+
+## 5. Phase 划分
+
+### Phase 1
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 2
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 3
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+## 6. Task 拆分规则
+
+- 每个 Task 只处理一个明确目标。
+- 每个 Task 必须能在 fresh session 中完成。
+- 每个 Task 必须有自己的验证命令。
+- 每个实现 Task 必须声明 Requirement IDs、owned paths、affected tests 和 evidence expectation。
+- 每个实现 Task 还必须写明 evidence path 和回归范围，不能只写测试命令。
+- 不允许把“实现 + 修所有 bug + 补所有测试”混成一个任务。
+
+## 7. 当前 Task 队列
+
+| Task ID | Phase | 目标 | 依赖 | 验证命令 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| T001 | P1 | | | | todo |
+
+## 8. 评审与修复闭环
+
+```text
+实现
+  -> Stage 1 review（Spec / 设计稿 / DEV-PLAN 一致性）
+  -> 浏览器截图与设计参考图视觉还原对比
+  -> 修复偏差
+  -> Stage 2 review（代码质量 / 测试 / 风险）
+  -> 修复问题
+  -> verify + fresh evidence
+  -> 才允许完成
+```
+
+## 9. 验证矩阵
+
+- 类型检查:
+- Lint:
+- Acceptance / Examples:
+- Traceability:
+- 单元测试:
+- 组件 / Story 测试:
+- Contract 测试:
+- API integration:
+- 集成测试:
+- E2E:
+- Affected Tests:
+- P0/P1 Regression:
+- Visual regression:
+- Visual parity screenshots:
+- Contract validation:
+- Coverage:
+- Verify matrix:
+- Backend layering check:
+- 事务 / 幂等验证:
+- 异常处理 / 错误码验证:
+
+## 10. BLOCKED 条件
+
+- 缺少设计稿或状态矩阵
+- 缺少 PRD-Lite、页面清单或验收标准
+- 缺少可执行验收示例
+- 缺少需求到界面的完整追溯矩阵
+- 缺少 `TRACEABILITY_MATRIX.md` 或 Requirement IDs 无法落到代码/测试
+- 高风险难点没有研究结论
+- 缺少 Design Brief、Component Map、Screen States 或 Design Tokens
+- AI 生成界面图未评审通过
+- 图片未转换成前端可实现规格
+- 前端 UI 缺少真实浏览器截图和设计参考图对比报告
+- Contract 未冻结
+- Controller / Service / Repository 边界未声明
+- 事务、幂等或异常处理策略未声明
+- P0/P1 需求缺少 `test-matrix.md` 映射
+- P0/P1 需求缺少 `TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md` 或 affected tests
+- E2E 缺少 seed 或账号数据
+- 测试失败没有 failure class 和 owner hint
+- 把 Stage 17 当成第一次定义测试范围的入口
+- 依赖任务未完成
+- 关键环境不可用
+- 需要人工决策
+
+## 11. 跨 Session 接续规则
+
+- 新 session 开始时先读本文件。
+- 进入新 Phase 前先重新读取真相源文档。
+- 如果设计稿、Product Spec、Contract 有变更，先更新本计划再编码。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/contracts/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放契约模板文档的镜像副本。
+
+## 结构索引
+
+- `README.md`：契约模板说明。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/contracts/*`。
+- 这里默认只用于镜像分发。

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

@@ -0,0 +1,24 @@
+# Contracts Templates Guide
+
+本目录提供 contract-first 开发的最小模板组合。
+
+## 推荐文件
+
+- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
+- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
+- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板
+
+## 推荐顺序
+
+1. 先完善 `openapi.yaml`
+2. 再配置 `orval.config.ts`
+3. 生成 client / mocks
+4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证
+
+## 最低契约要求
+
+- 请求入口统一通过 generated client 或项目约定的 `apiClient/httpClient`，不要在页面里直接拼 `fetch/axios/baseURL`。
+- 分页字段默认统一为 `page/pageSize`；如果项目另有约定，必须在 contract 和 API_MAP 中明确。
+- 响应结构必须统一，例如 `code/message/data` 或项目定义的等价结构；不要让前端猜 `res.data` 还是 `res.result`。
+- 错误模型必须显式定义，至少覆盖校验失败、权限失败、冲突和服务错误。
+- 前端类型优先从 contract 生成，不手写猜测字段。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/contracts/prism-usage.md

@@ -0,0 +1,41 @@
+# 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
+
+## 6. 联调检查点
+
+- request 参数名是否和 contract 一致，例如 `page/pageSize`
+- response 包装层是否和 contract 一致，例如 `code/message/data`
+- 错误响应是否都能命中 `ErrorResponse` 或项目定义的统一错误模型
+- 前端是否已经切到 generated client，而不是继续手写一套 request schema

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放设计模板文档的镜像副本。
+
+## 结构索引
+
+- `design-brief.md`、`component-map.md`、`screen-states.md`、`image-to-frontend-spec.md`、`frontend-architecture.md` 等设计模板镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/design/*`。
+- 修改设计模板默认先改上游，不先改这里。

package/package-source/docs/codex-harness-engineering/templates/package-assets/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/package-assets/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 清单
+- [ ] 无障碍 / 键盘访问要求
+- [ ] 性能预算与验证方式