@pzy560117/codex-harness 0.1.3 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/docs/demo-readme.md

@@ -1,73 +0,0 @@
-# Demo 交付记录
-
-**项目 / 功能：** `<feature-name>`
-**任务 ID：** `DEMO-001`
-**更新时间：** `YYYY-MM-DD`
-**定位：** 可运行、可点击、可评审的前端 Demo；不是生产交付。
-
-## 1. 启动方式
-
-```powershell
-# 安装依赖
-<install-command>
-
-# 启动 Demo
-<dev-command>
-```
-
-**本地地址：** `<http://localhost:xxxx>`
-
-## 2. 可点击主流程
-
-| 流程 | 路径 / 页面 | 操作 | 预期结果 | 状态 |
-| --- | --- | --- | --- | --- |
-| P0 主流程 1 | `<route>` | `<click / input>` | `<result>` | `pass / fail / blocked` |
-| P0 主流程 2 | `<route>` | `<click / input>` | `<result>` | `pass / fail / blocked` |
-| P1 辅助流程 | `<route>` | `<click / input>` | `<result>` | `pass / fail / blocked` |
-
-## 3. Mock 数据边界
-
-| 数据 | 来源 | 覆盖场景 | 不覆盖内容 |
-| --- | --- | --- | --- |
-| `<products/users/orders>` | `<file / fixture / inline>` | `<normal / empty / error>` | `<real API / payment / auth>` |
-
-## 4. 人工介入点
-
-| 类别 | 当前 Demo 处理方式 | 后续正式验证要求 |
-| --- | --- | --- |
-| 登录 / 权限 | mock 用户或本地状态 | 接真实登录、权限、会话过期 |
-| 支付 / 订单 | mock 支付结果 | 接真实支付、签名、回调、失败重试 |
-| 推送 / 短信 | 页面提示或 mock 通知 | 接真实设备、权限、厂商通道 |
-| 数据库 / 接口 | mock 数据 | 接真实 API、错误码、分页、并发 |
-| 设备兼容 | 桌面和移动视口检查 | 真机、系统版本、浏览器兼容 |
-| 安全合规 | 不处理真实隐私数据 | 隐私、授权、数据存储、日志脱敏 |
-
-## 5. 验证记录
-
-```powershell
-<lint-command>
-<typecheck-command>
-<build-command>
-<test-command>
-```
-
-| 检查项 | 结果 | 证据 |
-| --- | --- | --- |
-| 本地启动 | `pass / fail / blocked` | `<log / screenshot / trace>` |
-| P0 流程点击 | `pass / fail / blocked` | `<path>` |
-| 移动端视口 | `pass / fail / blocked` | `<screenshot>` |
-| 空态 / 错误态 | `pass / fail / blocked` | `<path>` |
-
-## 6. 已知问题
-
-| ID | 问题 | 影响 | 下一步 |
-| --- | --- | --- | --- |
-| DEMO-GAP-001 | `<description>` | `<impact>` | `<task / doc / owner>` |
-
-## 7. 进入正式实现前必须确认
-
-- [ ] 用户或负责人已经体验 Demo。
-- [ ] P0 主流程可以打开、点击并完成。
-- [ ] Demo 暴露的问题已经回写到产品、设计、测试或任务队列。
-- [ ] 真实接口、支付、推送、登录、设备兼容和安全合规边界已经列明。
-- [ ] foundation / domain / verify 任务依赖 `DEMO-001`，不会跳过 Demo 直接进入生产级实现。

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

@@ -1,138 +0,0 @@
-# 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/docs/governance-auto-repair.md

@@ -1,80 +0,0 @@
-# Governance Auto Repair
-
-本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。
-
-## 写入来源
-
-Stop hook 会调用：
-
-```powershell
-scripts/harness/harness-governance-check.ps1 -WriteExperience
-```
-
-该脚本只做两类写入：
-
-- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
-- 创建本文件的基础结构。
-
-它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
-
-## 经验提升规则
-
-每条自动记录的经验都必须经过复验后再提升：
-
-| 情况 | 提升目标 |
-| --- | --- |
-| 重复出现的规则分层、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/docs/harness-architecture.md

@@ -1,78 +0,0 @@
-# Harness 架构
-
-## 目标
-
-Harness 的目标是把 Codex 的执行过程固定成可重复、可验证、可追踪、可沉淀知识的工程闭环。
-
-## 核心链路
-
-```text
-task.json
-  -> tools/harness/codex-loop.ps1
-  -> codex exec
-  -> verify / lint / build / test
-  -> progress.txt + traces/*.json
-  -> docs/knowledge/ 引用与归档
-  -> task.json passes=true
-  -> git commit
-```
-
-## 分层
-
-- 规则层：`AGENTS.md`
-- 任务层：`task.json`
-- 执行层：`tools/harness/codex-loop.ps1`
-- 配置层：`.codex/task-run-profile.json`
-- 证据层：`progress.txt`、`traces/`
-- 验证层：`tools/harness/verify.ps1` 与任务内 `test_command`
-- 知识层：`docs/knowledge/knowledge-catalog.md`、分类索引和知识条目
-- 治理层：`docs/harness/rule-governance.md`、`docs/harness/knowledge-architecture.md`、`docs/harness/knowledge-import.md`、`docs/harness/knowledge-lint.md`、`docs/harness/team-knowledge-sync.md`
-- 拓扑层：`.service-matrix/dependencies.yaml` 与 `docs/harness/service-dependency-matrix.md`，仅在多服务、多仓库、契约或外部系统项目启用。
-
-## 原则
-
-- 任何完成声明都必须有验证证据。
-- 任何任务推进都必须回到可验证的 `task.json`、`progress.txt` 或 `traces/` 证据链上。
-- 任何复用过的项目经验都应在 trace 中留下 `knowledge_references`，避免知识只停留在对话上下文。
-- 任何可复用的新经验都应在归档任务中沉淀到 `docs/knowledge/`，初始成熟度默认是 `draft`。
-- 任何会影响服务拓扑、公开契约、上游 / 下游调用、IDL、schema 或外部系统的任务，都必须先能从 `.service-matrix/dependencies.yaml` 或等价 truth source 找到影响面；找不到时先 BLOCKED。
-- 既有项目接入时，知识冷启动只生成 draft 条目；成熟度提升必须来自后续引用和验证证据。
-- 知识库需要定期 lint，检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目。
-- 团队知识库是可选上层能力，只同步 verified/proven 级别的跨项目候选；外部知识库不可用时不应阻塞本地 driver。
-- `progress.txt`、`traces/` 和 Git 状态由 runtime 脚本落盘；其他需要新增或修改的仓库内容必须委派给匹配的 writer 子代理，主控会话自身不直接写文件。
-- 默认只在当前 Git 工作区内执行，不创建额外执行目录。
-
-## 任务控制面
-
-Harness 不要求所有任务都走相同重量。判断标准是影响面和复用价值：
-
-| 类型 | 适用场景 | 最小要求 |
-| --- | --- | --- |
-| 轻量任务 | 单文件、小修、验证明确、无跨模块影响 | `task.json` 中明确 scope、owned paths、test_command 和验收；允许 `gate_profile: lightweight` |
-| 标准任务 | 有真实交付、测试、文档或评审要求 | 完整 plan、truth source、qa_contract、trace 和 commit |
-| 企业级任务 | 多服务、多仓库、契约、数据迁移、权限、外部系统 | 额外启用服务依赖矩阵、契约 gate、失败/回滚验证和多维 review |
-
-轻量任务可以少写文档，但不能绕过验证、trace、owned paths 和完成证据。
-
-## 多维 Review
-
-Stage 2 默认可以由单个 reviewer 执行；当任务满足企业级任务条件时，应拆成多个只读审查维度并聚合：
-
-| 维度 | 检查重点 |
-| --- | --- |
-| 设计一致性 | 实现是否符合 spec、design、architecture truth source |
-| 复杂度 | 是否过度抽象、职责混杂、文件过大或难以维护 |
-| 并发与状态 | 锁、幂等、竞态、异步边界、前端状态源是否正确 |
-| 错误处理 | 失败路径、重试、回滚、用户反馈、日志和恢复策略 |
-| 安全 | 权限、输入、secrets、外部调用、危险命令和数据泄露 |
-| 契约一致性 | API / IDL / schema / event / generated code 是否同步 |
-| 追溯性 | Requirement ID、测试用例、证据和改动路径是否可追踪 |
-| 辅助检查 | lint、类型、格式、构建、脚本、hook 和 runtime 漂移 |
-
-多维 review 是可选强化，不是第二套状态机。所有结论仍回到当前 task 的 trace、review gate 和修复队列。
-
-## 外层控制台集成
-
-- Multica 可作为 Harness 的外层任务控制台，但 Harness 的完成状态仍以 `tools/harness/codex-loop.ps1`、`test_command`、review gate、trace 和 commit gate 为准。
-- 当前项目优先使用 Multica Docker 自部署版做集成试验；桌面版仅适合快速体验和个人使用。
-- 详细决策见 `docs/harness/multica-integration.md`。