@pzy560117/codex-harness 0.1.4 → 0.1.6

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`
+- 为什么要改
+- 会影响哪些环境
+- 哪些命令必须重跑
+- 回滚方式是什么

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/docs/frontend-quality-rules.md

@@ -0,0 +1,161 @@
+# Frontend Quality Rules
+
+本文件定义前端页面从“能用”到“可交付”的最低质量尺子。它服务于 `spec-to-ui-to-code-workflow.md`、`design-brief.md`、`image-to-frontend-spec.md`、`component-map.md`、`screen-states.md` 和 `visual-parity-review.md`，不替代项目自己的品牌规范或产品需求。
+
+## 1. 质量分级
+
+| 等级 | 定义 | 必备证据 | 不能声称 |
+| --- | --- | --- | --- |
+| P0 可用 | 主路径能完成，关键控件可操作 | 主路径 story 或 E2E，基本截图 | 生产级体验 |
+| P1 完整 | default / loading / empty / error / permission / long content / mobile 有规格和验证 | 状态矩阵、story 覆盖、移动端截图 | 视觉精修完成 |
+| P2 精修 | 视觉层级、响应式、动效、可访问性和文案有明确标准并通过评审 | visual parity、a11y smoke、responsive matrix | 可无限复用 |
+| P3 生产级 | 架构可维护，组件边界清晰，性能预算和回归证据完整 | frontend architecture、performance budget、regression evidence | 无需后续治理 |
+
+`feature_impl` 的前端任务如果没有写明目标等级，默认按 P1 验收；用户可见核心流程默认至少 P2。
+
+## 2. 审美反模式
+
+以下情况出现任意一项，Stage 1 或视觉评审应要求返工，除非 Design Brief 明确说明原因：
+
+- 页面只由大块卡片堆叠组成，缺少信息层级。
+- 全页面灰白无重点，主要操作、危险操作和状态反馈不可区分。
+- 使用无意义渐变、装饰图形或营销式 hero 来包装操作型后台页面。
+- 所有按钮、标签、状态、表格行的视觉权重相同。
+- 表格密度失控：行高、列宽、数字、标签和操作区没有扫描节奏。
+- 移动端只做横向滚动，没有重排、折叠或卡片化策略。
+- loading / empty / error 只是一行临时文案，没有恢复路径。
+- 图标、颜色或动画只起装饰作用，不能帮助识别状态或操作。
+
+## 3. 动效规则
+
+动效必须解释状态变化，不承担主要信息表达。
+
+| 场景 | 推荐动效 | 时长 | 约束 |
+| --- | --- | --- | --- |
+| 弹窗 / 抽屉打开 | opacity + scale 或 translate | 120-180ms | 必须有焦点管理 |
+| 筛选 chip 增删 | opacity + slight translate | 100-160ms | 不得推动整页大范围跳动 |
+| 表格刷新 | skeleton / row fade | 120-220ms | 高频刷新时禁用行级动画 |
+| 空态 / 错误态切换 | opacity | 120-180ms | 文案和恢复操作优先 |
+| 保存成功 / dirty 清除 | button state + inline status | 120-180ms | 不得只依赖 toast |
+
+硬约束：
+
+- 首选 `transform` 和 `opacity`，不得用会持续触发布局的动画属性。
+- 必须支持 `prefers-reduced-motion` 或等价 reduced motion 开关。
+- 动效不能隐藏错误、禁用、权限不足或保存失败。
+- 动效失败时页面仍必须可用。
+
+## 4. 响应式规则
+
+每个用户可见页面都必须写清楚 desktop / tablet / mobile 的布局策略。
+
+| 视口 | 必须说明 | 常见策略 |
+| --- | --- | --- |
+| Desktop >= 1200px | 主内容宽度、侧栏、表格列、操作区位置 | 横向筛选条 + 数据表 + 分页 |
+| Tablet 768-1199px | 筛选换行、列显隐、操作折叠 | 筛选条换行，次要列隐藏 |
+| Mobile < 768px | 筛选入口、表格替代形态、底部操作、触控尺寸 | 筛选抽屉，表格转卡片，分页简化 |
+
+移动端禁止只依赖横向滚动完成主要流程。若表格必须横向滚动，必须说明原因、最小宽度、冻结列或摘要卡片替代方案。
+
+移动端和嵌入式 WebView 额外约束:
+
+- 必须说明 iOS 刘海屏、灵动岛、底部 Home Indicator、Android 状态栏 / 导航栏的安全区策略。
+- 键盘弹起后，输入框、提交按钮和错误提示不得被遮挡。
+- 横竖屏切换后，主流程不能丢失状态或出现不可操作区域。
+
+## 5. 组件复用边界
+
+- `ui primitives`: 只放按钮、输入、弹窗、菜单、表格基础结构等无业务语义组件。
+- `data-table`: 只放排序、筛选、分页、列显隐、空态容器等表格通用行为。
+- `features/<domain>`: 放业务组件、业务 hooks、字段映射、权限逻辑和页面组合。
+- `api-client`: 放契约生成或手写 API 调用，不直接依赖 UI。
+- `model/schema`: 放类型、枚举、表单校验和 URL query 解析。
+
+复用准入：
+
+- 新通用组件必须至少有两个明确使用场景，或是基础 primitive。
+- 业务语义不稳定时留在 feature 内，不提前抽到 `packages/ui`。
+- 通用组件必须有 props 契约、状态矩阵、story 和可访问性说明。
+- generated types 可以作为数据输入类型，不能决定 UI primitive 的命名和职责。
+- 修改 existing 公共组件时，必须列出受影响调用方、兼容策略和回归测试；不能为了一个页面直接改坏全局行为。
+- 优先通过 wrapper、variant、slot、可选 props 扩展现有组件，不直接破坏旧 props 契约。
+
+## 6. 交互与文案规则
+
+每个关键操作必须定义：
+
+- 触发条件、禁用条件、加载反馈、成功反馈、失败反馈。
+- inline error、toast、modal confirm 的使用边界。
+- dirty 状态如何产生、如何保存、何时清除。
+- 重试、取消、关闭、返回是否保留用户输入。
+- 空态文案、错误文案、权限文案、按钮文案和长文本截断规则。
+
+表单体验至少补充：
+
+- 校验触发时机：blur / submit / input
+- 错误字段聚焦策略
+- submitting 与 disabled 的区分
+- 防重复提交策略
+- 输入格式与键盘类型策略
+- 成功 / 失败后的恢复或保留输入策略
+
+空态必须区分“系统没有数据”和“筛选后没有结果”。错误态必须包含用户可执行的恢复路径。
+
+状态不是给评审看的页面说明。`loading / empty / error / disabled / permission / mobile` 等状态必须由真实状态源驱动，例如 API 请求状态、权限结果、空数据集合、表单 dirty/valid 状态、路由或 query 参数、feature flag、响应式断点、story controls 或可控 mock。页面可以有用户可见文案，但不能出现“这里是 loading 状态”“权限态展示如下”等占位说明来冒充实现。
+
+每个 P0/P1 状态都必须能在代码和证据中追溯到：
+
+- 状态源：store、query、hook、props、fixture、mock response、viewport 或权限判断。
+- 渲染分支：组件条件分支、状态组件、disabled 属性、error boundary、empty renderer 或 responsive layout。
+- 触发路径：用户操作、API 响应、测试 seed、story control、query 参数、mock scenario 或 viewport。
+- 复验证据：story、interaction test、E2E 步骤、截图矩阵或 visual parity finding。
+
+除 `loading / empty / error / disabled / permission / mobile` 外，如场景存在，还应显式覆盖：
+
+- `submitting`
+- `retry`
+- `offline`
+
+## 7. 可访问性规则
+
+前端规格至少覆盖：
+
+- 键盘路径和焦点顺序。
+- 弹窗、抽屉、菜单的 focus trap 和关闭方式。
+- 表单错误与输入控件的关联。
+- 加载、保存成功、失败的屏幕阅读器提示。
+- 色彩不能作为唯一信息来源。
+- 移动端触控目标不小于 44x44px，除非平台规范另有说明。
+
+## 8. 性能预算
+
+前端设计阶段必须说明是否存在以下风险：
+
+- 首屏依赖过多组件、图标、图表或动画库。
+- 表格超过 100 行、复杂筛选、虚拟滚动或服务端分页需求。
+- 图片、头像、缩略图或远程媒体影响布局稳定。
+- 动效或重排可能影响滚动和输入响应。
+
+如果页面包含复杂表格、图表或列表，必须在 `frontend-architecture.md` 或 DEV-PLAN 中写明 client/server 分界和性能验证方式。
+
+## 9. 证据要求
+
+前端任务完成声明至少包含：
+
+- story / interaction / E2E 中的对应状态覆盖。
+- desktop 和 mobile 的真实浏览器截图。
+- visual parity 结论。
+- 可访问性 smoke 结论或明确豁免。
+- 性能风险检查结论；复杂页面需附性能预算验证。
+
+## 10. State Surface Gate
+
+前端任务进入实现前，必须把状态暴露方式写进 plan 或当前 task 的 `state_surface`。可接受的状态表面包括：
+
+- Storybook / story 文件：适合组件、页面片段、状态矩阵和视觉回归。
+- 真实 route + query / fixture：适合页面级状态、权限态和深链路复现。
+- Mock scenario / MSW / API fixture：适合 loading、empty、error、权限和异常返回。
+- E2E seed / test data：适合跨页面流程、保存、删除、批量操作和副作用验证。
+- Viewport matrix：适合响应式、移动端重排和触控行为。
+
+每个 P0/P1 状态至少要有一个可运行入口，并写明评审看哪里、回归跑什么、失败证据放哪里。状态只存在于设计稿、截图或聊天说明中时，Stage 1 应要求补状态表面，而不是让实现任务继续猜。

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

@@ -0,0 +1,47 @@
+# 回归规则
+
+| 风险 | 约束 |
+| --- | --- |
+| 误改文件 | Git 工作区清洁检查、task 边界、owned paths |
+| 漏测 | 每个任务必须运行 `test_command` |
+| 伪完成 | `passes=true` 必须建立在 fresh evidence 上 |
+| 文档漂移 | 规则、模板、命令改动后同步更新对应文档 |
+
+## 基本要求
+
+- 文档改动至少运行 `git diff --check`。
+- 代码改动必须运行与任务风险匹配的验证命令。
+- 不允许在未验证的情况下手工把任务标记为通过。
+
+## 需求到验证的左移规则
+
+- 测试从需求收敛阶段开始介入，不允许等代码完成后才第一次补测试范围。
+- 任何 P0/P1 需求进入实现前，至少要有 Requirement ID、业务规则、正向示例、异常示例、测试层级映射、测试数据说明和证据路径。
+- 任何 P0/P1 或高风险测试进入脚本实现前，必须先定义测试意图和 Oracle；写操作、权限、状态机、异步链路必须包含副作用或无副作用验证。
+- 创建或重建 `task.json` 时必须一次性补齐完整 QA 合约；后续不得依赖人工逐项补 `requirement_ids`、测试数据、Oracle、开发验证、最终验收验证、证据路径或整链路验证。
+- `docs/testing/TRACEABILITY_MATRIX.md`、验收示例和验证矩阵属于实现前 truth source；缺失时应优先补齐，而不是继续猜测实现。
+- 修改业务代码时必须同时检查测试影响；相关测试缺失时，先补测试骨架或测试计划，再继续实现。
+- Stage 2 必须拦截假测试，包括只断言 200 / truthy、只测 happy path、mock 被测逻辑、缺少业务断言、缺少执行证据或缺少来源绑定的测试。
+
+## 完成定义
+
+- 对外部系统、既定开源栈、第三方平台或真实环境的集成型需求，完成定义至少包含：真实依赖接上、真实请求走通、成功态证据、失败态证据。
+- 页面能打开、本地接口能返回、单元测试通过，都不足以声称正式 `FR-*` 已完成。
+- 每个 `feature_impl` 必须同时具备两段证据：编码过程中的 `development_validation`，以及代码写完后从用户 / 业务闭环视角重新运行的 `acceptance_validation`。
+- 每个 `feature_impl` 至少需要故事级完整链路验收证据；只跑单元测试、局部 smoke、affected tests、静态检查或 `git diff --check` 不足以完成任务。
+- 如果当前只是原型 / spike / exploratory 路径，不要把演示性交付直接标成正式 `FR-*` 完成；应改用 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 等单独标识，或在 spec / plan 中显式记录该 FR 仍处于未完成集成态。
+- 单元测试只能证明本地逻辑；集成型需求还必须补环境 smoke、E2E、真实下游连通性验证和验收证据 note。
+- Release 完成必须有发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证；不得把各子任务局部测试简单相加当作整测。
+- Stage 17 只负责 fresh evidence、affected tests 和 P0/P1 回归确认，不负责第一次定义需求测试范围。
+- 重构任务必须显式声明行为不变约束；接口、用户路径、数据结构和兼容逻辑不能在未说明时被顺手改变。
+- 重构结束前应按声明范围清理无用变量、无用函数、无用组件、无用类型、无用 import、临时代码和过期注释。
+
+## 技术栈验证基线
+
+| 改动类型 | 最小验证 |
+| --- | --- |
+| 文档 | `git diff --check` |
+| JSON | `ConvertFrom-Json` |
+| PowerShell | Parser 语法检查 |
+| TypeScript / 前端 | lint、typecheck、build |
+| API 或业务流程 | 单元测试、集成测试或 E2E，按风险选择 |

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

@@ -0,0 +1,86 @@
+# Trace Format 模板
+
+## 1. 文件命名
+
+```text
+traces/<task-id>-<yyyyMMdd-HHmmss>.json
+```
+
+## 2. 必需字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `task_id` | string | 当前任务 id |
+| `agent` | string | 执行代理，如 `codex` |
+| `started_at` | string | ISO 8601 开始时间 |
+| `ended_at` | string | ISO 8601 结束时间 |
+| `status` | enum | `passed`、`failed`、`blocked` |
+| `commands` | array | 执行命令和退出码 |
+| `stage1_review` | object | Stage 1 审查 verdict、退出码和摘要 |
+| `stage2_review` | object | Stage 2 审查 verdict、退出码和摘要 |
+
+## 3. 推荐字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `task_session_id` | string | 当前 task 的 fresh session id |
+| `task_kind` | string | 任务类型，例如 `harness`、`smoke`、`feature_impl` |
+| `gate_profile` | string | 本任务启用的 gate 强度 |
+| `schema_version` | string | trace schema 版本 |
+| `session_dir` | string | 当前 task session 的持久日志目录 |
+| `events_file` | string/null | implementation 阶段主 Codex JSONL 事件流文件；review JSONL 如有保留，仍记录在 `log_files` / `logs` |
+| `log_files` | array | implementation / review / test output 等日志文件路径 |
+| `evidence_files` | array | 与当前任务关联的额外证据附件 |
+| `role` | string | 当前 Agent 的角色，例如 `frontend`、`backend`、`reviewer` |
+| `model` | string | 实际使用的模型 |
+| `reasoning_effort` | enum | 实际使用的思考深度: `none`、`low`、`medium`、`high`、`xhigh` |
+| `model_policy` | object | 模型策略来源，例如 policy 文件和 role 覆盖路径 |
+| `required_truth_sources` | array | 本任务必须满足的 truth source 类型 |
+| `files_changed` | array | Git 检测到的文件 |
+| `blocked_reason` | string/null | 阻塞原因 |
+| `final_message` | string | Codex 最终消息摘要 |
+| `test_command` | string | 当前任务验证命令 |
+| `qa_evidence` | object/null | 测试用例、Oracle、证据文件、副作用断言、假测试检测和失败复现摘要 |
+| `failed_stage` | string/null | 失败发生在哪个 gate |
+| `unexpected_paths` | array | commit path ownership gate 阻断时记录超出 `owned_paths` / runtime allowlist 的路径 |
+| `review_context` | object | Stage 1 / Stage 2 对照的真相源文件集合 |
+| `truth_source_state` | array | truth source 满足情况、已找到路径和缺失项 |
+| `knowledge_references` | array | 当前任务读取并实际使用的知识条目 |
+| `knowledge_outputs` | array | 当前任务新增、更新或建议归档的知识条目 |
+| `archive_summary` | object/null | 归档阶段对知识引用、知识产出和成熟度变化的摘要 |
+| `logs` | object | implementation / stage review / test output 的日志文件路径 |
+
+## 3.1 `qa_evidence` 推荐结构
+
+```json
+{
+  "case_ids": ["TC-ORDER-CANCEL-007"],
+  "requirement_ids": ["REQ-ORDER-003"],
+  "oracles": ["response", "database", "event", "audit", "no_side_effect"],
+  "evidence_files": ["artifacts/tests/order-cancel-007.json"],
+  "side_effect_checks": ["db_snapshot_before_after", "event_not_emitted"],
+  "anti_fake_checks": {
+    "has_semantic_assertion": true,
+    "verifies_side_effect": true,
+    "source_bound": true,
+    "target_path_proven": true
+  },
+  "failure_repro": null
+}
+```
+
+## 4. 校验
+
+使用 `docs/harness/trace.schema.json` 校验 trace。CI 中可以用任意 JSON Schema validator 执行。
+
+## 5. 可观测性最低要求
+
+如果任务涉及 API、异步链路、外部系统、权限、支付、删除、上传或关键业务闭环，相关证据中至少应能回答：
+
+- 请求 ID 是什么
+- 用户 ID / actor 是什么
+- 接口路径或业务入口是什么
+- 失败原因是什么
+- 耗时是多少
+- 是否存在审计记录
+- 是否有对应告警或失败通知

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放产品素材模板文档的镜像副本。
+
+## 结构索引
+
+- `prd-lite.md`、`acceptance-criteria.md`、`page-inventory.md`、`difficulty-research.md` 等产品模板镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/product/*`。
+- 当前默认安装主线如果仍以 `spec/*` 为主，这里更应视为上游素材镜像。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/product/prd-lite.md

@@ -0,0 +1,166 @@
+# PRD-Lite 模板
+
+> 目标: 把原始需求收敛成 Codex 可以直接消费的产品真相源。未填完整前，不应进入设计或实现阶段。
+
+## 1. 基本信息
+
+- Feature ID:
+- Feature 名称:
+- 来源: issue / 会议纪要 / 事故复盘 / 业务需求 / 其他
+- 负责人:
+- 相关方:
+- 当前状态: Draft / Review / Approved / Changed
+- 最后更新:
+
+## 2. 背景与问题
+
+- 业务背景:
+- 当前问题:
+- 为什么现在做:
+- 不做的影响:
+- 现有替代方案:
+
+## 3. 目标与非目标
+
+### 目标
+
+| 目标 ID | 目标描述 | 衡量方式 | 优先级 |
+| --- | --- | --- | --- |
+| G-001 | | | P0 |
+
+### 非目标
+
+| 非目标 ID | 本期明确不做 | 原因 | 后续处理 |
+| --- | --- | --- | --- |
+| NG-001 | | | |
+
+## 4. 用户与角色
+
+| 角色 | 使用场景 | 核心诉求 | 权限差异 | 优先级 |
+| --- | --- | --- | --- | --- |
+| | | | | P0 |
+
+## 5. 范围边界
+
+| 范围 | 内容 |
+| --- | --- |
+| In scope | |
+| Out of scope | |
+| 允许变更 | |
+| 禁止变更 | |
+| 依赖前置条件 | |
+
+## 6. 业务流程
+
+### 主流程
+
+```mermaid
+flowchart TD
+  A[开始] --> B[核心步骤]
+  B --> C[完成]
+```
+
+### 异常流程
+
+| 场景 ID | 异常场景 | 触发条件 | 预期行为 | 兜底策略 |
+| --- | --- | --- | --- | --- |
+| E-001 | | | | |
+
+## 7. 页面 / 流程 / 接口影响
+
+| 类型 | 名称 | 影响说明 | 对应真相源 |
+| --- | --- | --- | --- |
+| 页面 | | | `page-inventory.md` |
+| 状态 | | | `state-matrix.yaml` |
+| 接口 | | | `contracts/openapi.yaml` |
+| 权限 | | | 本文权限矩阵 |
+
+## 8. 功能需求
+
+| 需求 ID | 用户故事 / 能力 | 优先级 | 关联页面 | 关联状态 | 验收入口 |
+| --- | --- | --- | --- | --- | --- |
+| FR-001 | As a [角色], I want [能力], so that [价值] | P0 | | | `acceptance-criteria.md` |
+
+## 9. 需求到界面追溯
+
+| 需求 ID | 关联页面 / 视图 | 页面状态 | UI 元素 / 操作 | 依赖字段 | 依赖接口 | 验收标准 | 追溯状态 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| FR-001 | page-001 | default / empty / loading / error | | | | AC-001 | Pending |
+
+> 完整追溯矩阵维护在 `docs/product/requirement-interface-matrix.md`。所有 P0/P1 需求必须完成映射。
+
+## 10. 前置难点研究
+
+| 难点 ID | 难点 / 不确定点 | 关联需求 | 影响界面 / 接口 | 风险等级 | 研究结论 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| DR-001 | | FR-001 | page-001 / API | High / Medium / Low | | Open |
+
+> 详细研究记录维护在 `docs/product/difficulty-research.md`。高风险难点未关闭前，不进入实现阶段。
+
+## 11. 业务规则
+
+| 规则 ID | 规则描述 | 触发时机 | 校验逻辑 | 不满足时行为 |
+| --- | --- | --- | --- | --- |
+| BR-001 | | | | |
+
+至少覆盖：
+
+- 状态流转规则
+- 权限拒绝规则
+- 幂等 / 重复提交规则
+- 外部依赖失败或超时后的兜底规则
+- 对金额、库存、次数、唯一性等关键不变量的保护规则
+
+## 12. 权限矩阵
+
+| 操作 | 角色 A | 角色 B | 角色 C | 备注 |
+| --- | --- | --- | --- | --- |
+| 查看 | 允许 | 只读 | 禁止 | |
+
+## 13. 数据与字段
+
+| 字段 | 中文名 | 类型 | 来源 | 必填 | 取值范围 / 枚举 | 边界规则 |
+| --- | --- | --- | --- | --- | --- | --- |
+| | | | | | | |
+
+## 14. 非功能需求
+
+| 类型 | 要求 | 指标 / 标准 | 优先级 | 验证方式 |
+| --- | --- | --- | --- | --- |
+| 性能 | | | P0 | |
+| 安全 | | | P0 | |
+| 可用性 | | | P1 | |
+| 可访问性 | | | P1 | |
+| 兼容性 | | | P1 | |
+
+## 15. 成功标准
+
+| 指标 ID | 成功标准 | 目标值 | 衡量方式 |
+| --- | --- | --- | --- |
+| SC-001 | | | |
+
+## 16. 风险、假设与待确认
+
+### 风险
+
+| 风险 ID | 风险描述 | 影响 | 概率 | 缓解措施 | 负责人 |
+| --- | --- | --- | --- | --- | --- |
+| R-001 | | 高/中/低 | 高/中/低 | | |
+
+### 假设
+
+| 假设 ID | 假设内容 | 验证方式 | 失效影响 |
+| --- | --- | --- | --- |
+| A-001 | | | |
+
+### 待确认
+
+| 问题 ID | 问题 | 相关方 | 截止日期 | 状态 |
+| --- | --- | --- | --- | --- |
+| Q-001 | | | | 待确认 |
+
+## 17. 变更记录
+
+| 版本 | 日期 | 变更内容 | 影响范围 | 评审人 |
+| --- | --- | --- | --- | --- |
+| v0.1 | | 初稿 | | |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/product/state-matrix.yaml

@@ -0,0 +1,116 @@
+version: "1.0"
+feature_id: "FEAT-000"
+required_states:
+  - default
+  - empty
+  - loading
+  - error
+  - permission_denied
+  - disabled
+  - long_content
+  - mobile
+pages:
+  - page_id: "page-001"
+    title: "示例页面"
+    route: "/example"
+    actor: "primary-user"
+    related_requirements:
+      - "FR-001"
+    states:
+      default:
+        required: true
+        description: "展示主要数据和默认可执行操作"
+        trigger: "用户进入页面且数据加载成功"
+        expected_ui:
+          - "主要内容可见"
+          - "主要操作入口可见"
+        user_actions:
+          - "执行核心操作"
+        acceptance_refs:
+          - "AC-001"
+      empty:
+        required: true
+        description: "无数据或筛选后无结果"
+        trigger: "查询结果为空"
+        expected_ui:
+          - "空态提示"
+          - "恢复或创建入口"
+        user_actions:
+          - "重置条件"
+          - "创建数据"
+        acceptance_refs:
+          - "AC-E001"
+      loading:
+        required: true
+        description: "数据请求或提交尚未完成"
+        trigger: "请求未完成"
+        expected_ui:
+          - "骨架屏、spinner 或按钮 loading"
+        user_actions:
+          - "等待"
+        acceptance_refs:
+          - "AC-E002"
+      error:
+        required: true
+        description: "接口报错、超时或数据解析失败"
+        trigger: "请求失败"
+        expected_ui:
+          - "错误提示"
+          - "重试入口"
+        user_actions:
+          - "重试"
+        acceptance_refs:
+          - "AC-E002"
+      permission_denied:
+        required: true
+        description: "当前角色无权查看或操作"
+        trigger: "权限校验失败"
+        expected_ui:
+          - "权限不足提示"
+          - "受限操作隐藏或禁用"
+        user_actions:
+          - "返回"
+        acceptance_refs:
+          - "AC-E003"
+        related_business_rules:
+          - "BR-REPLACE-PERMISSION"
+      disabled:
+        required: false
+        not_applicable_reason: ""
+        description: "操作因状态、权限或前置条件不足而不可用"
+        trigger: "操作前置条件不满足"
+        expected_ui:
+          - "禁用态"
+          - "原因说明"
+        user_actions:
+          - "查看原因"
+        acceptance_refs: []
+        related_business_rules:
+          - "BR-REPLACE-DISABLED"
+      long_content:
+        required: true
+        description: "字段超长、列表项较多或极端数据"
+        trigger: "数据超过常规长度或数量"
+        expected_ui:
+          - "文本不溢出容器"
+          - "可通过 tooltip、换行或截断查看"
+        user_actions:
+          - "查看完整内容"
+        acceptance_refs: []
+      mobile:
+        required: true
+        description: "小屏或窄容器访问"
+        trigger: "视口宽度小于移动端断点"
+        expected_ui:
+          - "布局可用"
+          - "关键操作不被遮挡"
+        user_actions:
+          - "完成核心流程"
+        acceptance_refs: []
+
+business_rule_checklist:
+  - "是否存在状态机或状态流转限制"
+  - "是否存在权限拒绝且无副作用的规则"
+  - "是否存在重复提交 / 幂等保护"
+  - "是否存在外部依赖失败、超时或中断兜底"
+  - "是否存在关键不变量，例如金额、库存、次数、唯一性"

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

@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放 prompt 模板说明的镜像副本。
+
+## 结构索引
+
+- `controller-loop.md`、`review-*`、`failure-triage.md`、`implement-one-task.md` 等 prompt 镜像。
+
+## 修改规则
+
+- 上游 canonical 在 `docs/codex-harness-engineering/templates/prompts/*`。
+- 这里仅用于镜像分发。