@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/code-style-and-naming.md

@@ -0,0 +1,116 @@
+# 项目级命名词典与边界模板
+
+这份文档不是固定规则入口。固定不变的第五章规则已经放进 always-on 的 `coding-style.md`。
+
+这里专门承载项目特有、会随业务变化的内容：
+
+- 业务词典
+- 历史别名兼容
+- 某些目录的命名例外
+- 类型后缀禁用表和替代方案
+- 当前项目的文件命名分层表
+
+## 1. 适用原则
+
+- 先读规则文件 `coding-style.md`，这里不重复抄固定规则。
+- 这里的每一项都应当是“当前项目特有事实”，不是通用工程常识。
+- 如果某项约束对所有项目都成立，应上收回规则文件，而不是继续堆在本文。
+
+## 2. 业务词典
+
+先维护“一个概念一个名字”的项目词典。
+
+| 业务概念 | 统一名称 | 禁止混用的别名 | 说明 |
+| --- | --- | --- | --- |
+| 用户 | `user` | `member`、`customer`、`client` | 如果确实是不同角色，拆成独立概念 |
+| 商品 | `product` | `goods`、`item`、`commodity` | 只保留业务正式名词 |
+| 订单 | `order` | `bill`、`trade` | 支付单可单独定义 `paymentOrder` |
+| 优惠券 | `coupon` | `voucher`、`ticket` | 如果有券模板，再单独定义 `couponTemplate` |
+
+补齐项目自己的业务词典时，至少回答：
+
+- 这个概念在页面、接口、数据库、测试里是否同名。
+- 是否已经存在历史别名；如果有，兼容层放在哪里。
+- 新增同义词时，是新概念还是旧概念的脏别名。
+
+## 3. 项目文件命名分层表
+
+先按目录层级声明规则，再允许新增文件。
+
+| 路径 / 资产类型 | 命名规则 | 示例 | 禁止情况 |
+| --- | --- | --- | --- |
+| React / Vue 页面组件 | `PascalCase` | `UserProfilePage.tsx` | 与同层 `user-profile-page.tsx` 混用 |
+| 通用 hooks | `camelCase` 且以 `use` 开头 | `useUserProfile.ts` | `userHook.ts`、`getUserHook.ts` |
+| 纯工具函数 | `camelCase` | `formatPrice.ts` | `dealData.ts`、`tool.ts` |
+| 测试文件 | 跟随被测对象 + `.test` / `.spec` | `formatPrice.test.ts` | `test1.ts` |
+| 文档模板 | `kebab-case` | `code-style-and-naming.md` | `codeStyle.md`、`code_style.md` |
+
+新增文件前必须回答：
+
+- 这个文件属于页面、feature、shared、contract、testing 还是 scripts。
+- 同目录现有文件使用什么规则。
+- 如果要破例，为什么不能沿用当前目录规则。
+
+## 4. 项目特有命名例外
+
+这里只记录项目例外，不重复写通用函数命名原则。
+
+- 哪些历史目录仍在使用旧命名风格：
+- 哪些生成代码目录允许例外：
+- 哪些第三方契约文件不按项目规则命名：
+- 哪些 legacy 字段名必须保留原样：
+
+## 5. 类型命名边界
+
+同一个项目里，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 这些后缀必须先定义边界。
+
+| 类型后缀 | 用途 | 不该承载什么 |
+| --- | --- | --- |
+| `Entity` | 持久化模型 / 数据库实体 | 前端展示字段 |
+| `Dto` / `DTO` | 服务边界输入输出 | ORM 细节、UI 状态 |
+| `Response` | API 返回结构 | 表单临时状态 |
+| `Request` | API 请求参数 | 数据库存储字段 |
+| `FormValues` | 表单输入态 | 服务端完整实体 |
+| `ViewModel` | 页面展示聚合模型 | 持久化约束 |
+
+如果项目不使用这些后缀中的某些项，要在这里明确写：
+
+- 禁止使用哪些后缀。
+- 统一替代方案是什么。
+- 历史遗留命名如何兼容。
+
+## 6. 新增命名前必须确认
+
+实现前先确认这 5 件事：
+
+1. 这个名词是否已在业务词典中定义。
+2. 同类文件在当前目录如何命名。
+3. 这个函数名是否表达了主动作和对象。
+4. 这个类型属于哪一层边界，是否需要后缀。
+5. 是否会和历史别名、旧接口字段或数据库字段冲突。
+
+## 7. 自动化与人工门禁
+
+建议自动化命令：
+
+```text
+lint
+typecheck
+format
+test
+git diff --check
+```
+
+Harness 侧至少保留两层约束：
+
+- `coding-style.md` 默认自动加载固定规则。
+- `CURRENT_TASK.md` 和本文记录当前项目 / 当前任务的特有词典与边界。
+- `style-lint.ps1` 同时检查规则文件和项目级模板是否完整。
+
+## 8. 评审检查单
+
+- 同一业务概念是否出现多个别名。
+- 同层文件是否混用了多套命名风格。
+- 新函数名是否仍然依赖 `do/process/check` 这类模糊词。
+- `User`、`UserInfo`、`UserData`、`UserModel` 之类类型是否有明确边界。
+- 新增字段、接口、测试数据、文档是否与统一名词同步。

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

@@ -0,0 +1,138 @@
+# 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 | 筛选入口、表格替代形态、底部操作、触控尺寸 | 筛选抽屉，表格转卡片，分页简化 |
+
+移动端禁止只依赖横向滚动完成主要流程。若表格必须横向滚动，必须说明原因、最小宽度、冻结列或摘要卡片替代方案。
+
+## 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 的命名和职责。
+
+## 6. 交互与文案规则
+
+每个关键操作必须定义：
+
+- 触发条件、禁用条件、加载反馈、成功反馈、失败反馈。
+- inline error、toast、modal confirm 的使用边界。
+- dirty 状态如何产生、如何保存、何时清除。
+- 重试、取消、关闭、返回是否保留用户输入。
+- 空态文案、错误文案、权限文案、按钮文案和长文本截断规则。
+
+空态必须区分“系统没有数据”和“筛选后没有结果”。错误态必须包含用户可执行的恢复路径。
+
+状态不是给评审看的页面说明。`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。
+
+## 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/harness/governance-auto-repair.md

@@ -0,0 +1,82 @@
+# Governance Auto Repair
+
+本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。
+
+## 写入来源
+
+Stop hook 会调用：
+
+```powershell
+scripts/harness/harness-governance-check.ps1 -WriteExperience
+```
+
+该脚本只做两类写入：
+
+- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
+- 创建本文件的基础结构。
+- 对受影响目录的子 `AGENTS.md` 刷新自动维护区块，补齐 changed paths、候选入口和验证命令。
+
+它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
+它也不会重写整份子 `AGENTS.md`；自动化只维护受控区块，手写目录规则必须放在区块外。
+
+## 经验提升规则
+
+每条自动记录的经验都必须经过复验后再提升：
+
+| 情况 | 提升目标 |
+| --- | --- |
+| 重复出现的规则分层、fallback、autoload、hook 漂移 | `docs/harness/rule-governance.md` 或 `.codex/rules/*.md` |
+| 命令权限、危险操作、sandbox 误用 | `.codex/rules/*.rules` 或 `docs/harness/sandbox-policy.md` |
+| Stage 1 产品/设计/计划不一致 | 对应 product/design/plan truth source |
+| Stage 2 代码质量、测试缺口、回归风险 | `docs/testing/failure-triage.md` 或测试矩阵 |
+| driver、trace、progress、commit gate 闭环缺口 | `docs/harness/task-session-strategy.md` 或 `trace-format.md` |
+
+## 失败经验分类
+
+Stop hook 写入 failed trace 摘要时，应尽量归入下面的分类，方便后续判断是补 truth source、补 hook、补子代理边界，还是只保留为一次性 trace。
+
+| 分类 | 典型信号 | 优先处理 |
+| --- | --- | --- |
+| `semantic_constraint_lost` | 字段口径、单位、禁止修改范围、兼容性约束只出现在聊天里，后续实现忘记 | 补 product/context/testing truth source 或 task 语义约束包 |
+| `truth_source_missing` | task 声明了需求、架构、测试或数据证据，但对应文件不存在或内容不足 | BLOCKED，先补 truth source |
+| `hook_gap` | 问题可被确定性检查发现，但当前 hook / `.rules` / verify 没拦住 | 补 hook、`.rules` 或 `tools/harness/verify.ps1` 检查 |
+| `subagent_context_overflow` | 主会话读取了大量日志、依赖树、数据样本、完整 Skill 流程，导致上下文污染 | 改为子代理读取并只返回摘要 |
+| `state_file_bloat` | `task.json` / `progress.txt` 过大、格式漂移或被 AI 手工整理 | 交给 `runtime.state_compaction` 或治理修复，不允许手工重排 |
+| `review_gate_gap` | Stage 1 / Stage 2 未覆盖的产品、设计、测试可信度或维护性问题 | 补 review prompt、测试矩阵或 qa contract |
+| `domain_rule_candidate` | 多次出现同类领域规范违规，但还不是通用项目硬规则 | 先沉淀到 domain docs / skill，再决定是否提升 |
+| `service_topology_gap` | 跨服务、契约、IDL、schema、上下游或外部系统影响面靠 AI 搜索和猜测 | 补 `.service-matrix/dependencies.yaml` 或等价拓扑 truth source |
+
+提升前必须回答：
+
+- 这是一次性任务问题，还是会跨任务重复？
+- 能否用 deterministic check 发现？
+- 是否需要进入 instruction chain，还是应下沉到 docs / skill / hook / `.rules`？
+- 是否有复验证据证明修复后不再复现？
+
+## 修复流程
+
+1. Stop hook 发现治理失败或 failed trace。
+2. `harness-governance-check.ps1` 输出 JSON findings，并把 failed trace 摘要写入本文件。
+3. Stop hook 返回 continuation JSON，阻断停止。
+4. 下一轮先读 `AGENTS.md`、本文件、`docs/harness/rule-governance.md`、`.codex/rules/agents.md`。
+5. 由 `harness-writer` 或 driver 修复对应路径。
+6. 运行 `tools/harness/verify.ps1` 和直接相关验证。
+7. 只有复验成立且可复用时，才把经验提升到对应正式文档。
+
+## Self-Refinement 提升路径
+
+Stop hook、review、用户纠正或 failed trace 发现的问题，不应只停留在本轮对话。按下面路径处理：
+
+| 信号 | 首选落点 | 何时升级 |
+| --- | --- | --- |
+| 一次性任务事实 | 当前 trace、`progress.txt`、任务相关 product / testing 文档 | 不升级 |
+| 可复用项目经验 | `docs/knowledge/experience/` 或 `docs/knowledge/guidelines/` | 复验后进入 `ARCHIVE-001` |
+| 反复出现的领域口径 | domain docs、service matrix、project skill | 多次任务引用且有证据 |
+| 可机械化检查 | hook、`.rules`、`tools/harness/verify.ps1`、CI、lint、contract test | 已有确定性失败样本和通过样本 |
+| 每次会话都必须遵守的硬规则 | `AGENTS.md` 或子目录 `AGENTS.md` | proven 级别或 maintainer 明确要求 |
+
+提升前必须保留原始证据路径、复验命令和失败样本。不能把单次用户偏好、一次性修复或未复验猜测直接提升为全局规则。
+
+## 自动记录区
+
+新的 Stop hook 经验会追加在此节之后。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/mcp-knowledge-governance.md

@@ -0,0 +1,24 @@
+# MCP 与外部知识治理
+
+本文定义项目里如何使用 MCP、搜索和外部知识源，避免把“查到的资料”误当成“已经进入项目治理的真相源”。
+
+## 目标
+
+- 先用项目内真相源回答项目内问题
+- 只在需要 freshness 或外部资料时再查 MCP
+- 把外部结论和项目沉淀分开
+
+## 默认顺序
+
+1. `AGENTS.md`
+2. `docs/ai/*`
+3. `docs/harness/*`
+4. `docs/testing/*`
+5. `docs/knowledge/*`
+6. MCP / 外部知识
+
+## 沉淀规则
+
+- 临时查询结果默认不进入规则层
+- 可复用结论先写 `docs/ai/*` 或 `docs/knowledge/*`
+- 稳定治理再升级到 `docs/harness/*`、prompt 或 rules

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/harness/service-dependency-matrix.md

@@ -0,0 +1,55 @@
+# Service Dependency Matrix
+
+本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。
+
+## 适用条件
+
+满足任一条件时，应启用服务依赖矩阵：
+
+- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
+- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
+- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
+- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。
+
+## 维护原则
+
+- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
+- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
+- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
+- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。
+
+## 最小字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `service_id` | 稳定服务、应用、包、worker 或集成名 |
+| `repo_path` | 当前仓库内路径或外部仓库标识 |
+| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
+| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
+| `upstream` | 调用本服务 / 包 / 入口的上游 |
+| `downstream` | 本服务 / 包 / 入口调用的下游 |
+| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
+| `owner` | 维护 owner 或确认人 |
+| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |
+
+## Driver 使用方式
+
+- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
+- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
+- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。
+
+## Review 口径
+
+Stage 1 先检查矩阵是否足以支撑实现计划：
+
+- 受影响服务是否都已列出。
+- 上下游、契约、分支或版本约束是否明确。
+- 是否有未确认依赖被实现任务当成已确认事实。
+- 验证命令是否覆盖矩阵中的 change gates。
+
+Stage 2 再检查代码是否真的遵守矩阵：
+
+- 公开入口、契约、实现、测试和证据是否一致。
+- 是否漏改下游调用、mock、生成代码、schema 或配置。
+- 失败、回滚、兼容性和灰度路径是否有证据。