@pzy560117/codex-harness 0.1.3 → 0.1.5

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

@@ -1,122 +1,157 @@
-# 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 | | | | |
+# Screen States 模板
+
+> 目标: 把每个页面状态写成可实现、可做 story、可做 visual regression 的状态规格。
+
+## 页面名称
+
+- Page ID:
+- 页面:
+- 路由/入口:
+- 角色:
+- 关联需求:
+- 关联设计稿:
+
+## 状态清单
+
+### default
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 组件影响:
+- story 名称:
+- visual baseline:
+
+### empty
+
+- 触发条件:
+- 数据条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复路径:
+- story 名称:
+- visual baseline:
+
+### loading
+
+- 触发条件:
+- 等待对象:
+- 页面表现:
+- 用户可执行动作:
+- 超时后行为:
+- story 名称:
+- visual baseline:
+
+### error
+
+- 触发条件:
+- 错误类型:
+- 页面表现:
+- 用户可执行动作:
+- 重试 / 兜底:
+- story 名称:
+- visual baseline:
+
+### submitting
+
+- 触发条件:
+- 提交对象:
+- 页面表现:
+- 用户可执行动作:
+- 防重复提交策略:
+- story 名称:
+- visual baseline:
+
+### retry
+
+- 触发条件:
+- 失败来源:
+- 页面表现:
+- 用户可执行动作:
+- 重试限制 / 节流:
+- story 名称:
+- visual baseline:
+
+### offline
+
+- 触发条件:
+- 网络条件:
+- 页面表现:
+- 用户可执行动作:
+- 恢复后行为:
+- 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 | | | | |
+| submitting | | | | |
+| retry | | | | |
+| offline | | | | |
+| permission_denied | | | | |
+| disabled | | | | |
+| long_content | | | | |
+| mobile | | | | |
+| reduced_motion | | | | |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/design/visual-parity-review.md

@@ -41,13 +41,13 @@ artifacts/visual-review/<feature>/<page>/
 | --- | --- | --- | --- | --- | --- | --- |
 | | default | Desktop 1440x900 | | | | Yes |
 | | empty | Desktop 1440x900 | | | | Yes / N/A |
-| | loading | Desktop 1440x900 | | | | Yes / N/A |
-| | error | Desktop 1440x900 | | | | Yes / N/A |
-| | permission | Desktop 1440x900 | | | | Yes / N/A |
-| | long_content | Desktop 1440x900 | | | | Yes / N/A |
-| | default | Tablet 768x1024 | | | | Yes / N/A |
-| | default | Mobile 375x812 | | | | Yes / N/A |
-| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
+| | loading | Desktop 1440x900 | | | | Yes / N/A |
+| | error | Desktop 1440x900 | | | | Yes / N/A |
+| | permission | Desktop 1440x900 | | | | Yes / N/A |
+| | long_content | Desktop 1440x900 | | | | Yes / N/A |
+| | default | Tablet 768x1024 | | | | Yes / N/A |
+| | default | Mobile 375x812 | | | | Yes / N/A |
+| | reduced_motion | Desktop 1440x900 | | | | Yes / N/A |
 
 ## 5. 浏览器截图命令示例
 
@@ -77,11 +77,11 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 - 字体、字号、字重、行高、间距、圆角、阴影、边框、颜色是否明显偏离。
 - 商品图、图标、按钮、标签、价格、状态文本等业务元素是否缺失或多出。
 - 空态、加载态、错误态、移动端状态是否符合设计图和 screen-states。
-- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
-- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
-- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
-
-输出：
+- 是否有文字溢出、遮挡、错位、重叠、响应式破版。
+- 动效、reduced motion、focus、hover、disabled 是否符合规格或有截图 / 录像证据。
+- 移动端触控目标、折叠策略、表格替代形态是否符合 screen-states 和 frontend architecture。
+
+输出：
 - Verdict: PASS / FAIL
 - 主要差异清单
 - 必须修复项
@@ -96,11 +96,11 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 | 字体与字号 | | | PASS / FAIL | |
 | 间距与密度 | | | PASS / FAIL | |
 | 颜色与状态色 | | | PASS / FAIL | |
-| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
-| 业务元素完整性 | | | PASS / FAIL | |
-| 响应式 | | | PASS / FAIL / N/A | |
-| 动效 / reduced motion | | | PASS / FAIL / N/A | |
-| 可访问性可见状态 | | | PASS / FAIL / N/A | |
+| 组件圆角 / 阴影 / 边框 | | | PASS / FAIL | |
+| 业务元素完整性 | | | PASS / FAIL | |
+| 响应式 | | | PASS / FAIL / N/A | |
+| 动效 / reduced motion | | | PASS / FAIL / N/A | |
+| 可访问性可见状态 | | | PASS / FAIL / N/A | |
 
 ## 8. 失败处理
 
@@ -115,10 +115,10 @@ npx playwright screenshot --viewport-size=1440,900 "$env:VISUAL_BASE_URL/pets" "
 ## 9. 通过标准
 
 - [ ] 每个 required UI state 都有参考图或明确豁免。
-- [ ] 每个 required UI state 都有真实浏览器截图。
-- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
-- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
-- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
+- [ ] 每个 required UI state 都有真实浏览器截图。
+- [ ] mobile required viewport 有真实浏览器截图或明确豁免。
+- [ ] 可访问性、focus、reduced motion 的可见状态已有截图、录像或报告证据。
+- [ ] 截图 viewport、测试数据和页面状态与参考图一致。
 - [ ] 图片对比报告存在，并给出 `Verdict: PASS`。
 - [ ] 所有 FAIL 差异都已修复并重新截图。
 - [ ] Stage 1 Review 能读取参考图路径、实拍图路径和对比报告。

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放会进入 `docs/harness/*` 的文档模板镜像。
+
+## 结构索引
+
+- `new-project-usage.md`、`task-session-strategy.md`、`frontend-quality-rules.md`、`architecture-constraints.md` 等方法论文档镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/docs/*`。
+- 这里不是文档模板第一真相源。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/docs/env-and-deployment-template.md

@@ -0,0 +1,60 @@
+# 环境变量与部署模板
+
+这份模板承载第16章“配置与环境问题”的项目级真相源。它不替代 `.env.example`，而是把变量含义、构建命令、部署入口和风险写清楚。
+
+## 1. 环境变量清单
+
+| 变量名 | 用途 | 必填 | 默认值 | dev/test/prod 差异 | 示例 |
+| --- | --- | --- | --- | --- | --- |
+| `APP_BASE_URL` | | 是/否 | | | |
+| `DATABASE_URL` | | 是/否 | | | |
+| `REDIS_URL` | | 是/否 | | | |
+
+规则:
+
+- 不把真实密钥写入仓库。
+- 每个变量都要说明“谁读取它”“在什么阶段生效”“缺失时会怎样”。
+- 若变量只属于某一部署环境，必须写明该环境的注入方式。
+
+## 2. 构建与运行命令
+
+| 场景 | 命令 | 预期结果 | 失败时常见原因 |
+| --- | --- | --- | --- |
+| 开发 | | | |
+| 构建 | | | |
+| Lint | | | |
+| Typecheck | | | |
+| Test | | | |
+| Docker build | | | |
+
+规则:
+
+- `dev/build/lint/test/typecheck` 至少列出存在与否和替代命令。
+- 如果某个命令本地能跑但 CI 不能跑，必须记录差异来源。
+
+## 3. CI / CD 入口
+
+| 入口 | 文件位置 | 用途 | 依赖变量 / Secret | 失败影响 |
+| --- | --- | --- | --- | --- |
+| GitHub Action / CI | | | | |
+| Dockerfile | | | | |
+| nginx / ingress | | | | |
+| k8s / compose | | | | |
+
+## 4. 健康检查与发布约束
+
+| 项目 | 约束 | 验证方式 | 失败处理 |
+| --- | --- | --- | --- |
+| 健康检查 | | | |
+| 端口 / host | | | |
+| 日志路径 | | | |
+| 迁移 / seed | | | |
+| 灰度 / 回滚 | | | |
+
+## 5. 配置变更前必须说明
+
+- 改了哪些配置文件：`.env*` / `package.json` / `Dockerfile` / `nginx` / `k8s yaml` / `CI workflow` / `tsconfig` / `vite/next config`
+- 为什么要改
+- 会影响哪些环境
+- 哪些命令必须重跑
+- 回滚方式是什么