@pzy560117/codex-harness 0.1.4 → 0.1.5

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

@@ -0,0 +1,73 @@
+# 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/directory-structure-template.md

@@ -0,0 +1,88 @@
+# Directory Structure Template
+
+本文用于给项目补一份明确的目录结构真相源，减少 AI 在文件放置、目录新建和业务域组织上的随意性。
+
+## 适用场景
+
+- 项目目录较大，单靠 `repo-map.md` 不足以约束文件放置。
+- 同一项目中同时存在页面、组件、API、hooks、types、constants、测试等多类资产。
+- 团队已经反复遇到“文件放错位置”“随意新建目录”“按技术类型乱堆而不是按业务域组织”的问题。
+
+## 目标
+
+- 说明已有目录各自负责什么。
+- 说明新文件应该放到哪里。
+- 说明哪些目录名禁止新增。
+- 说明是按业务域组织，还是按技术层组织，或两者混合。
+
+## 目录规范模板
+
+```markdown
+# Directory Structure
+
+## 1. 组织原则
+
+- 当前项目主要按 `<业务域 / 技术层 / 混合模式>` 组织。
+- 业务域优先的模块：`<features/<domain> / packages/<domain> / apps/<domain>>`
+- 技术层优先的共享目录：`<components/common / services / hooks / types / constants>`
+- 当业务域目录与共享目录冲突时，优先规则：`<写清优先级>`
+
+## 2. 顶层目录说明
+
+| 路径 | 用途 | 应放内容 | 不应放内容 |
+| --- | --- | --- | --- |
+| `src/pages/` | 页面 / 路由 | 页面组合、路由入口 | 纯公共组件、HTTP 调用细节 |
+| `src/components/common/` | 通用组件 | 无业务语义组件 | 业务状态、业务权限 |
+| `src/features/` | 业务域模块 | 业务组件、业务 hooks、领域 model | 全局通用 primitive |
+| `src/services/` | API / service | HTTP client、service 封装 | 页面 UI 逻辑 |
+| `src/hooks/` | 通用 hooks | 跨页面复用 hooks | 页面专用临时逻辑 |
+| `src/types/` | 类型 | 通用类型、契约类型 | 页面样式、业务逻辑 |
+| `src/constants/` | 常量 | 枚举、配置常量 | 函数实现 |
+| `tests/` | 测试 | 同构测试、集成测试、E2E | 生产代码 |
+
+## 3. 新文件放置规则
+
+- 页面级组件：放到对应页面目录或 `features/<domain>/components`
+- 可复用业务组件：放到 `features/<domain>/components`
+- 全局公共组件：放到 `components/common`
+- 接口请求：放到 `services/` 或 `features/<domain>/api/`
+- 类型定义：放到 `types/` 或模块内 `model/` / `types/`
+- 测试文件：与源码保持同构，或进入明确的测试目录
+
+## 4. 禁止新增的目录名
+
+- `newFeature/`
+- `featureNew/`
+- `myComponents/`
+- `common2/`
+- `utils2/`
+- `helper/`
+- `temp/`
+- `test-new/`
+
+## 5. 新增目录前必须回答
+
+- 为什么需要新目录？
+- 现有目录为什么不能放？
+- 这个目录未来会放什么？
+- 是否符合当前项目现有结构？
+- 是否需要给该目录补 `AGENTS.md`？
+
+## 6. 业务域组织规则
+
+- 若按业务域组织，推荐域列表：`<domain-a> / <domain-b> / <domain-c>`
+- 新业务代码默认先进对应业务域目录。
+- 只有跨业务复用已被验证后，才允许上提到共享层。
+
+## 7. 测试与索引同步
+
+- 新增目录后，如影响导航，更新 `docs/ai/repo-map.md`
+- 新增目录后，如目录规则明显不同，补该目录 `AGENTS.md`
+- 新增目录后，补充相关测试入口或验证命令
+```
+
+## 使用建议
+
+- 根 `AGENTS.md` 只索引这份文档，不复制全文。
+- `repo-map.md` 负责导航；本文件负责放置规范。
+- 如果项目已有强约束的前端目录规则，优先和 `templates/design/frontend-architecture.md` 对齐。

package/package-source/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/docs/frontend-quality-rules.md

@@ -0,0 +1,165 @@
+# 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 状态栏 / 导航栏的安全区策略。
+- 键盘弹起后，输入框、提交按钮和错误提示不得被遮挡。
+- 横竖屏切换后，主流程不能丢失状态或出现不可操作区域。
+- 必须说明 iOS / 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/docs/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/docs/harness-architecture.md

@@ -0,0 +1,78 @@
+# 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`。