@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,57 +0,0 @@
-# Harness Mode Matrix
-
-## 1. Summary
-
-当前安装体系同时保留 `user`、`project`、`vendor`、`full` 四种模式，但它们暴露的是不同层能力，不应混成一个概念：
-
-| 模式 | 主要定位 |
-| --- | --- |
-| `user` | 用户级共享能力层，更适合全局技能、规则和类似 `/goal` 的外层长期目标控制习惯 |
-| `project` | 项目根 runtime + truth source，适合 driver-first、stop hook、trace、verify 闭环 |
-| `vendor` | 离线 / 隔离环境下的完整 package 镜像复制 |
-| `full` | `project` runtime + 完整 `.agents/` package assets，适合长期驻留的完整 Harness 项目 |
-
-其中：
-
-- **外层目标控制** 更适合放在 `user` 层使用。
-- **仓库级持续执行与治理** 更适合放在 `project` / `full` 层使用。
-
-| 字段 | user | project | vendor | full |
-| --- | --- | --- | --- | --- |
-| 适用场景 | 全局规则、共享技能、外层长期目标控制 | 目标项目最小 driver-first 闭环 | 离线 / 隔离复制完整包 | 长期业务项目的完整 Harness 工程 |
-| 状态源 | 用户环境 | `task.json` | 以复制的 package 为主 | `task.json` |
-| 执行入口 | 用户级 Codex / CLI / App | `tools/harness/codex-loop.ps1` | 按目标环境决定 | `tools/harness/codex-loop.ps1` |
-| 提交责任 | 不负责项目提交 | driver | 不默认承担项目提交 | driver |
-| trace 责任 | 无项目级 trace 保证 | driver 写 `traces/*.json` | 取决于目标环境 | driver 写 `traces/*.json` |
-| 验证入口 | 用户自定义 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` | 取决于目标环境 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
-| 持续运行定位 | 可承载 `/goal` 这类外层长期目标控制 | stop hook + driver continuation | 取决于复制后的目标环境 | 同时具备 `project` 执行面和 `.agents/` 能力包 |
-| 禁区 | 不应假装拥有项目级 gate | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 | 不应误当作项目执行协议本身 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |
-
-## 2. Installation Outputs
-
-| 模式 | 必备安装产物 |
-| --- | --- |
-| user | 共享 package assets、全局规则/技能入口，不要求目标项目先具备完整 runtime |
-| project | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`docs/ai/*` |
-| vendor | `.agents/` 下的完整 package 镜像、模板和 skills/workflows |
-| full | `project` runtime 产物 + `.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` 等完整能力包 |
-
-## 3. Ownership Rules
-
-| 字段 | project / full |
-| --- | --- |
-| 当前任务边界 | `task.json` 当前 task 的 `owned_paths`、`dependencies`、`test_command` |
-| 提交者 | `tools/harness/codex-loop.ps1` 或任务收尾流程 |
-| 失败记录 | `progress.txt` + `traces/*.json` |
-| 允许的运行产物 | `task.json`、`progress.txt`、`traces/`、显式 `non_blocking_dirty_paths` |
-
-`user` 和 `vendor` 模式本身不应宣称拥有上述项目级 ownership gate；它们更多提供共享控制面或分发面。
-
-## 4. SpecKit Usage
-
-SpecKit 仍用于生成或完善 `spec.md`、`plan.md`、testing truth sources 和任务拆解输入。方案确认后，应把结果转成 `tools/harness/templates/project-task-template.json` / `task.json`，再交给 `tools/harness/codex-loop.ps1` 执行。
-
-如果未来要把 Codex `/goal` 纳入长期运行体验，推荐分层是：
-
-- `user` 层承载 `/goal` 这类长期目标控制习惯
-- `project` / `full` 层承载 driver-first 的仓库执行协议

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/project-agents-template.md

@@ -1,154 +0,0 @@
-# Project AGENTS.md Template
-
-本文是生成项目根 `AGENTS.md` 的通用模板，不应原样复制后长期保留占位符。生成时先分析项目事实，再按项目类型裁剪章节。
-
-## 使用原则
-
-- `AGENTS.md` 是给编码 Agent 的入口规则，不是 README 的复刻。
-- 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
-- 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
-- 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
-- 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
-- 规则从 Bad Case 迭代：重复 review 问题、线上事故、新人必踩坑、Agent 反复犯错，才升级为入口规则。
-- `project_doc_fallback_filenames` 只在目录缺少 `AGENTS.md` 时生效；生成了根 `AGENTS.md` 的项目，不要再依赖 fallback 文件作为额外入口。
-- 不用 `developer_instructions` 或 `model_instructions_file` 承载普通项目规则；这些是 config 层上下文入口，默认应保持为空。
-
-## 生成前事实扫描
-
-先收集这些事实，再填模板：
-
-| 事实 | 来源 |
-| --- | --- |
-| 项目类型 | README、目录结构、启动脚本、部署文件 |
-| 技术栈 | `package.json`、`pyproject.toml`、`go.mod`、`pom.xml`、Dockerfile |
-| 常用命令 | scripts、Makefile、CI、现有 docs |
-| 架构边界 | `src/`、`apps/`、`packages/`、`services/`、`docs/architecture*` |
-| 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
-| 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
-| 自动化检查 | linter、formatter、typecheck、CI、hooks |
-| 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
-| Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
-
-## 根 AGENTS.md 模板
-
-```markdown
-# AGENTS.md
-
-本文件只保留当前项目中每次编码会话都必须知道的规则。更详细的背景、接口、测试和部署说明见下方索引。
-
-## 项目边界
-
-- 项目类型：<应用 / 库 / monorepo / harness / 模板 / 服务端 / 前端 / 全栈>
-- 主要技术栈：<只列非默认且会影响实现选择的技术>
-- 真实入口：<启动、构建、测试、driver 或任务系统入口>
-- 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
-- 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
-
-## 常用命令
-
-| 场景 | 命令 | 说明 |
-| --- | --- | --- |
-| 安装 | `<command>` | <必要前提或包管理器> |
-| 开发 | `<command>` | <端口 / 环境变量 / mock 说明> |
-| 测试 | `<command>` | <默认测试范围> |
-| 类型 / lint | `<command>` | <失败时处理方式> |
-| 构建 | `<command>` | <产物路径或限制> |
-
-## 架构与目录规则
-
-| 场景 | 应使用 | 不要使用 |
-| --- | --- | --- |
-| <例如 API 入口> | `<path/helper>` | <禁止路径或绕路方式> |
-| <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
-| <例如数据访问> | `<repository/service>` | <不要跨层调用> |
-
-## 项目硬约束
-
-- <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
-- <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
-- <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
-
-## 测试与完成定义
-
-- 修改 <模块/路径> 后至少运行 `<command>`。
-- 涉及 <API/业务流/权限/支付/外部系统> 时，必须补充 <单元/集成/E2E/契约/真实环境 smoke> 证据。
-- 完成声明必须包含实际运行过的命令和结果；不要只说“应该可以”。
-
-## 工作区与提交
-
-- 开始前检查 `git status --short`；不要覆盖用户未说明的改动。
-- 只修改与当前任务相关的文件。
-- 禁止使用破坏性 Git 命令，除非用户明确要求。
-- 提交前运行与改动匹配的验证命令。
-
-## 深文档索引
-
-- 架构：`<docs/architecture.md>`
-- 代码地图：`<docs/ai/repo-map.md>`
-- API / 契约：`<docs/api.md>`
-- 测试策略：`<docs/testing.md>`
-- 部署 / 运维：`<docs/deploy.md>`
-- 历史坑 / 项目知识：`<docs/knowledge/>`
-```
-
-## 子目录 AGENTS.md 模板
-
-只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
-
-````markdown
-# <path> AGENTS.md
-
-## 作用范围
-
-- 本文件只适用于 `<path>/` 下的改动。
-- 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
-
-## 本目录约束
-
-- 技术栈 / 框架：<目录特定信息>
-- 入口文件：<真实入口>
-- 测试命令：<目录级验证命令>
-
-## 决策表
-
-| 场景 | 应使用 | 不要使用 |
-| --- | --- | --- |
-| <场景> | <本目录模式> | <禁止做法> |
-
-## 代码示例
-
-```<language>
-// 3-10 行真实项目代码，展示应该复用的模式
-```
-````
-
-## CLAUDE.md 组合模板
-
-仅当团队主要使用 Claude Code 且需要 Claude 专属能力时添加。通用规则仍放 `AGENTS.md`。
-
-```markdown
-# CLAUDE.md
-
-@AGENTS.md
-
-## Claude Code 专属规则
-
-- 使用 hooks / commands / memory 的项目约定：<只写 Claude Code 独有内容>。
-- 个人本地偏好放 `CLAUDE.local.md`，不要提交。
-- 不要在这里重复 `AGENTS.md` 已有规则。
-```
-
-## 裁剪检查
-
-生成后逐条检查：
-
-| 检查项 | 处理 |
-| --- | --- |
-| 是否超过 120 行 | 下沉细节到深文档，只保留索引 |
-| 是否复制 README 项目介绍 | 删除，改为 README 链接 |
-| 是否包含通用编码常识 | 删除 |
-| 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
-| 禁令是否没有替代方案 | 补替代方案或降级为风险 |
-| 是否引用不存在的命令或路径 | 修正或删除 |
-| 自动化可检查的内容是否只写文字 | 补充脚本 / hook / CI / verify 入口 |
-| 深文档是否无法从入口发现 | 加入索引 |

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/spec-to-ui-to-code-workflow.md

@@ -1,196 +0,0 @@
-# Spec To UI To Code Workflow 模板
-
-## 1. 工作流目标
-
-- 当前 feature:
-- 当前设计来源:
-- 当前 contract 来源:
-- 当前需要打通的主流程:
-
-## 2. 顺序
-
-```text
-Product Skeleton
-  -> page-inventory draft + requirement-interface-matrix draft + page-rules-draft
-  -> early-ai-image-brief
-  -> AI 生成 / 编辑第一轮界面方向图
-  -> early-ui-review
-  -> PRD / 页面 / 状态 / 字段 / 验收反哺
-  -> Product Spec
-  -> acceptance-criteria + acceptance-examples
-  -> requirement-interface-matrix + traceability-matrix + difficulty-research
-  -> test-matrix + risk-based-test-plan + regression-plan + test-data-plan + test-data-matrix
-  -> Design Brief
-  -> Frontend Quality Rules + Frontend Architecture
-  -> CSS / tokens / component / motion / responsive rules
-  -> AI image brief
-  -> AI 生成 / 编辑前端界面图
-  -> UI image review
-  -> image-to-frontend-spec
-  -> component-map + screen-states + design-tokens
-  -> frontend stories / components / pages
-  -> browser screenshot + visual parity review
-  -> OpenAPI contract
-  -> generated client + mock server
-  -> integration + e2e + visual regression
-  -> failure triage + repair/retest loop
-  -> knowledge archive + catalog update
-```
-
-## 3. 真相源
-
-- Product Spec:
-- Product Skeleton:
-- Page Rules Draft:
-- Early AI Image Brief:
-- Early UI Review:
-- Acceptance Criteria:
-- Acceptance Examples:
-- Traceability Matrix:
-- Test Strategy:
-- Risk Based Test Plan:
-- Regression Plan:
-- Evidence Protocol:
-- Design Brief:
-- Frontend Quality Rules:
-- Frontend Architecture:
-- 设计稿:
-- Component Map:
-- Screen States:
-- Design Tokens:
-- DEV-PLAN:
-- OpenAPI:
-- Verify Matrix:
-- Knowledge Catalog:
-
-## 4. 每阶段交付物
-
-### Phase 1A: Product Skeleton
-
-- [ ] `prd-lite.md` 初稿，至少包含目标、非目标、范围边界和角色。
-- [ ] `page-inventory.md` 初稿，至少覆盖所有 P0 页面。
-- [ ] `requirement-interface-matrix.md` 轻量版，至少把每条 P0/P1 需求映射到页面、区域、字段、操作和状态。
-- [ ] `docs/design/page-rules-draft.md`，写清页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。
-- [ ] P0 页面已有主任务、核心字段、主要操作和异常/空/加载/权限状态草案。
-
-### Phase 1B: Early AI Image Direction
-
-- [ ] `docs/design/early-ai-image-brief.md`。
-- [ ] 第一轮 AI 生成 / 编辑的界面方向图，保存到 `artifacts/ai-images/early/`。
-- [ ] `docs/design/early-ui-review.md`。
-- [ ] `early-ui-review.md` 已检查：每条 P0/P1 需求是否能在图中找到界面证据，图片是否暴露页面数量、字段过载、路径过长、后台表格密度、移动端状态和权限视图问题。
-- [ ] `early-ui-review.md` 的结论已回填到 `prd-lite.md`、`page-inventory.md`、`state-matrix.yaml` 和 `requirement-interface-matrix.md`。
-
-### Phase 1C: Product Spec Completion
-
-- [ ] `prd-lite.md`
-- [ ] `page-inventory.md`
-- [ ] `state-matrix.yaml`
-- [ ] `acceptance-criteria.md`
-- [ ] `ACCEPTANCE_CRITERIA.md`
-- [ ] `ACCEPTANCE_EXAMPLES.md`
-- [ ] `requirement-interface-matrix.md`
-- [ ] `TRACEABILITY_MATRIX.md`
-- [ ] `difficulty-research.md`
-- [ ] `TEST_STRATEGY.md`
-- [ ] `test-matrix.md`
-- [ ] `RISK_BASED_TEST_PLAN.md`
-- [ ] `REGRESSION_PLAN.md`
-- [ ] `test-data-plan.md`
-- [ ] `TEST_DATA_MATRIX.md`
-- [ ] `EVIDENCE_PROTOCOL.md`
-- [ ] `failure-triage.md`
-- [ ] 目标、非目标、范围边界
-- [ ] 角色与权限矩阵
-- [ ] 异常流程、风险、假设、待确认点
-- [ ] 每条 P0/P1 需求都映射到界面、状态、字段、接口和验收
-- [ ] 每条 P0/P1 需求都映射到测试层级、测试数据、owner 和 evidence path
-- [ ] 每条 P0/P1 需求都映射到 affected tests 和回归范围
-- [ ] 每条 P0/P1 需求至少包含一个正向验收示例和一个异常示例
-- [ ] 高风险难点已有前置研究结论
-- [ ] 完整 Product Spec 没有绕过 Phase 1B 的早期视觉方向图和反哺记录
-
-### Phase 2: Design Brief
-
-- [ ] `design-brief.md`
-- [ ] `docs/harness/frontend-quality-rules.md` 已读取，目标质量等级已声明
-- [ ] `frontend-architecture.md` 或等价架构说明
-- [ ] 信息架构
-- [ ] 布局、交互、响应式、动效和可访问性规则
-- [ ] CSS / token 要求
-- [ ] 审美反模式和禁止事项
-- [ ] UX writing、空态、错误态、权限文案规则
-- [ ] 性能预算和复杂列表 / 表格处理策略
-- [ ] 默认态、加载态、空态、错误态、权限态、极端数据态、移动端状态
-
-### Phase 3: Final AI Image Maker
-
-- [ ] `ai-image-brief.md`
-- [ ] 基于 `early-ui-review.md` 和 Design Brief 生成 / 编辑的多状态前端界面图
-- [ ] `ui-image-review.md`
-
-### Phase 4: Image To Frontend Spec
-
-- [ ] `component-map.md`
-- [ ] `screen-states.md`
-- [ ] `design-tokens.json`
-- [ ] `frontend-architecture.md`
-- [ ] `image-to-frontend-spec.md`
-- [ ] `visual-parity-review.md` 截图矩阵已定义
-- [ ] stories / interaction / e2e / visual / a11y / performance 映射
-- [ ] 稳定测试选择器和关键视觉断言
-- [ ] 每个关键状态都写清状态源、渲染分支、触发路径和复验证据，禁止用页面说明文案冒充状态实现
-- [ ] desktop / tablet / mobile 响应式行为已写成可验证规格
-- [ ] 动效和 reduced motion 规则已写成可验证规格
-
-### Phase 5: Frontend
-
-- [ ] 组件实现
-- [ ] 页面实现
-- [ ] stories
-- [ ] 相关测试已新增或更新
-- [ ] 真实浏览器截图保存到 `artifacts/visual-review/`
-- [ ] 设计参考图与浏览器实拍图对比 PASS
-
-### Phase 6: Contract First
-
-- [ ] `contracts/openapi.yaml`
-- [ ] generated client
-- [ ] mock server
-- [ ] contract / schema / negative examples
-
-### Phase 7: Regression
-
-- [ ] Stage 1 review
-- [ ] Stage 2 review
-- [ ] verify
-- [ ] affected tests 与 P0/P1 regression 已运行
-- [ ] 契约验证、回归计划和 evidence protocol 已按本次变更刷新
-- [ ] `verify-matrix.md` 中必需项都有 fresh evidence
-- [ ] 若测试失败，`failure-findings.json` 已生成并进入 repair/retest loop
-
-### Phase 8: Knowledge Archive
-
-- [ ] `docs/knowledge/knowledge-catalog.md` 已存在
-- [ ] `docs/knowledge/catalog.md` 已按新增或更新条目刷新
-- [ ] 可复用 decision / guideline / pitfall / process / model 已归档
-- [ ] trace 或最终报告中的 `knowledge_references` 已被处理
-- [ ] 新增条目默认 maturity 为 `draft`，不得把单次经验直接提升为 `proven`
-
-## 5. 闸门
-
-- 不能完成 Product Skeleton: 缺 P0 页面清单、需求-界面轻量映射或 `docs/design/page-rules-draft.md`。
-- 不能完成 Product Spec: 缺第一轮 AI 界面方向图、`docs/design/early-ui-review.md`，或 early review 结论未反哺到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。
-- 不能进入 Design Brief: Product Spec 缺目标、非目标、范围、角色、页面、可执行验收示例、TRACEABILITY_MATRIX、需求-界面追溯矩阵或早期视觉评审结论。
-- 不能进入 AI Image Maker: Design Brief 缺视觉、CSS/tokens、布局、交互、响应式、动效、可访问性、文案或质量等级规则；高风险难点未研究。
-- 不能进入 Image To Frontend Spec: UI 图片未评审通过。
-- 不能进入前端实现: 缺 `image-to-frontend-spec.md`、`component-map.md`、`screen-states.md`、`design-tokens.json`、`frontend-architecture.md`、稳定测试选择器、响应式规格、动效规格或关键视觉断言。
-- 不能通过前端实现: 缺浏览器截图、缺移动端截图、缺设计参考图对比报告、缺 a11y smoke 结论，或 `visual-parity-review.md` Verdict 不是 PASS。
-- 不能通过前端实现: `loading / empty / error / disabled / permission / mobile` 等状态只作为界面说明文案出现，缺少真实状态源、渲染分支、触发路径或复验证据。
-- 不能进入联调: API / 数据变化没有 contract 或明确豁免。
-- 不能结束任务: 缺 Stage 1、Stage 2、verify、affected tests、P0/P1 regression 或 P0/P1 test matrix 的 fresh evidence。
-- 不能完成归档: 知识索引与条目不一致，或把一次性结论升级成全局规则却没有 evidence。
-
-## 6. 前端质量参考
-
-前端任务默认读取 `docs/harness/frontend-quality-rules.md`。如项目已有更具体的品牌、设计系统或平台规范，以项目规范为准，但不得低于本流程的状态覆盖、响应式、可访问性、证据和完成声明要求。