@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/context/feature-pack.md

@@ -0,0 +1,101 @@
+# Feature Pack 模板
+
+## 1. 基本信息
+
+- `feature_id`: `FEAT-000`
+- `title`: `示例：工单筛选与保存视图`
+- `source`: `issue / requirement doc / incident / cron`
+- `owner`: `Hermes / PM / Engineer`
+- `risk_level`: `L1`
+- `auto_merge_allowed`: `false`
+
+## 2. 业务目标
+
+- 这次变更要解决什么问题？
+- 成功后的业务结果如何判断？
+- 本期不解决什么问题？
+- 哪些开放问题会阻塞后续阶段？
+
+## 3. 影响范围
+
+- 页面:
+- 接口:
+- 目录:
+- 数据表:
+- 权限:
+- 外部系统:
+
+## 4. 需求分析真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Draft / Approved / N/A | |
+| Page Inventory | `docs/product/page-inventory.md` | Draft / Approved / N/A | |
+| State Matrix | `docs/product/state-matrix.yaml` | Draft / Approved / N/A | |
+| Acceptance Criteria | `docs/product/acceptance-criteria.md` | Draft / Approved / N/A | |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Draft / Approved / N/A | |
+| Difficulty Research | `docs/product/difficulty-research.md` | Draft / Approved / N/A | |
+
+## 5. 设计真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| Design Brief | `docs/design/design-brief.md` | Draft / Approved / N/A | |
+| Component Map | `docs/design/component-map.md` | Draft / Approved / N/A | |
+| Screen States | `docs/design/screen-states.md` | Draft / Approved / N/A | |
+| Design Tokens | `docs/design/design-tokens.json` | Draft / Approved / N/A | |
+| AI Image Brief | `docs/design/ai-image-brief.md` | Draft / Approved / N/A | |
+| UI Image Review | `docs/design/ui-image-review.md` | Draft / Approved / N/A | |
+| Image To Frontend Spec | `docs/design/image-to-frontend-spec.md` | Draft / Approved / N/A | |
+
+## 6. 先决条件
+
+- 已存在的能力:
+- 依赖功能:
+- 环境要求:
+
+## 7. 状态矩阵
+
+- `default`:
+- `empty`:
+- `loading`:
+- `error`:
+- `disabled`:
+- `permission_denied`:
+- `long_content`:
+- `responsive/mobile`:
+
+## 8. 变更边界
+
+- 允许修改:
+- 禁止修改:
+- 生成代码目录:
+- 手写代码目录:
+
+## 9. 验收标准
+
+- [ ] 用户可以完成核心流程
+- [ ] 异常流有明确行为
+- [ ] 文档、contract、代码一致
+
+## 10. 验证命令
+
+```powershell
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## 11. 输出要求
+
+- 需要更新的文档:
+- 需要补充的测试:
+- 需要生成的 client/types/mock:
+- 需要提交的 PR / issue / trace:
+
+## 12. 升级条件
+
+- 哪些情况必须 BLOCKED:
+- 哪些情况必须人工审批:
+- 哪些情况禁止自动合并:

package/package-source/docs/codex-harness-engineering/templates/context/repo-map.md

@@ -0,0 +1,102 @@
+# Repo Map
+
+更新时间: 2026-05-20
+维护责任: Harness package maintainer
+
+## 1. 仓库目标
+
+- 项目一句话描述: Codex Harness 安装实现包，用于把 AGENTS、driver、rules、prompts、skills、hooks、testing truth source 和 package docs 安装到目标项目。
+- 主要用户: 在 Windows / PowerShell 环境中使用 Codex CLI 的项目维护者和自动化执行 agent。
+- 核心业务域: driver-first 任务执行、安装包分发、规则治理、测试左移、知识沉淀、agent 能力同步。
+
+## 2. 从哪里开始读
+
+- 第一步先读: `AGENTS.md`
+- 第二步再读: `docs/ai/architecture-brief.md`
+- 第三步按任务进入:
+  - 安装链路: `tools/install/install-agent.ps1`, `tools/install/bootstrap-codex-harness.ps1`
+  - driver 链路: `tools/harness/codex-loop.ps1`, `.codex/prompts/*`
+  - 分发同步: `refresh-agent-package.ps1`, `.ai-sync.yml`
+  - 规则治理: `docs/harness/rule-governance.md`
+  - 包文档: `docs/codex-harness-engineering/*`
+
+## 2.1 上下文索引最小字段
+
+- 代码入口: 关键命令、路由、脚本或页面入口
+- 上游调用方: 谁会触发这个入口
+- 下游依赖: 入口继续调用哪些模块、脚本或接口
+- 类型/契约入口: 类型定义、contract、schema 或导出面
+- 测试入口: 关联测试、验证命令或证据目录
+- 配置入口: `.codex/*`、环境变量、配置文件、manifest
+- 风险入口: 权限、状态流转、安装升级、同步、数据边界
+- 禁改区: 当前任务默认不要碰的区域
+
+## 3. 关键目录
+
+| 路径 | 用途 | 可修改性 | 备注 |
+| --- | --- | --- | --- |
+| repo root | 当前安装包包根 | 可改 | 新项目安装时主要来源 |
+| `.agents/` | 当前仓库活跃 package / skills 镜像 | 可改 | skills 以这里为活跃 canonical |
+| `.codex/` | 当前仓库 Codex roles、prompts、rules | 可改 | active role rules 以 `.codex/rules/agents.md` 为 canonical |
+| `docs/harness/` | driver、规则、知识、回归等深文档 | 可改 | root truth source |
+| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
+| `docs/ai/` | AI 导航索引和架构摘要 | 可改 | 大型项目导航层 |
+| `docs/codex-harness-engineering/templates/` | 安装模板源 | 可改 | 会影响新项目 bootstrap |
+| `docs/codex-harness-engineering/templates/package-assets/` | 安装到目标 `.agents/` 的能力包 | 可改 | 需同步 `.agents` 镜像 |
+| `scripts/` | 辅助验证和同步脚本 | 谨慎 | 修改后做 PowerShell parser 检查 |
+
+## 4. 关键依赖关系
+
+- root runtime -> `refresh-agent-package.ps1` -> templates / package-assets mirrors。
+- root docs -> `templates/package-assets/docs/codex-harness-engineering/` -> 目标项目 `.agents/docs/...`。
+- `.agents/skills/<name>` -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` -> package-assets skill mirrors。
+- `tools/install/bootstrap-codex-harness.ps1` -> 目标项目根 runtime、`.codex/`、`docs/harness/`、`docs/testing/`、`docs/ai/`。
+
+## 5. 常用命令
+
+```powershell
+git status --short
+git diff --check
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+## 6. 禁改区
+
+- 禁止手工伪造 `task.json` 的 `passes=true`；应让 driver 验证后写回。
+- 禁止跳过 package mirrors：涉及 `.agents/`、templates、package-assets、skills 的改动必须按同步矩阵刷新。
+- 禁止把 token、cookie、私钥、密码写入 docs、trace、prompt 或 package。
+- 禁止在未确认时使用破坏性 Git 命令或递归删除。
+
+## 7. 任务入口
+
+- Feature plan 所在位置: `task.json` 或 `tools/harness/templates/project-task-template.json`
+- Product docs 所在位置: `docs/product/` 或 `docs/requirement-prep-kit/`
+- Design docs 所在位置: `docs/codex-harness-engineering/templates/design/`
+- Contract 所在位置: `docs/codex-harness-engineering/templates/contracts/`
+
+## 7.1 调用链与影响面提示
+
+- 关键调用链:
+  - 安装: `tools/install/*` -> `docs/codex-harness-engineering/templates/*` / `package-assets/*`
+  - driver: `tools/harness/codex-loop.ps1` -> `.codex/prompts/*` -> `task.json` / `docs/testing/*`
+  - 同步: `refresh-agent-package.ps1` -> `.agents/*` / templates / package-assets
+- 影响面分析时至少回答:
+  - 入口在哪里
+  - 上游是谁
+  - 下游是谁
+  - 受影响文件有哪些
+  - 受影响测试和验证命令有哪些
+
+## 8. 子目录规则索引
+
+| 路径 | 本地规则 | 触发场景 |
+| --- | --- | --- |
+| repo root | `AGENTS.md` | 验证安装包入口规则和可分发文件 |
+| `.agents/` | `.agents/AGENTS.md` | 修改活跃 skills / workflows 镜像 |
+
+## 9. 维护规则
+
+- 新增安装时应落地的模板文件时，同时检查 `tools/install/bootstrap-codex-harness.ps1` 和 `.ai-sync.yml`。
+- 新增 package docs 时，同时更新 `docs/codex-harness-engineering/README.md` 和 package-assets 镜像。
+- 更新 skills 时，以 `.agents/skills/<name>` 为 canonical，再同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 package-assets。

package/package-source/docs/codex-harness-engineering/templates/context/service-dependency-matrix.yaml

@@ -0,0 +1,25 @@
+version: 1
+status: draft
+usage: "Optional truth source for multi-service, multi-repo, contract, or external-system work. Set status to not_applicable when the project has no cross-service dependency surface."
+services:
+  - service_id: "replace-with-service-or-app-id"
+    repo_path: "replace-with-repo-or-local-path"
+    owner: "replace-with-owner"
+    status: "needs-confirmation"
+    entrypoints:
+      - type: "replace-with-http|grpc|graphql|mq|cli|ui-route|package-api|worker|file-format|none"
+        path: "replace-with-entrypoint"
+    contracts:
+      - type: "replace-with-openapi|protobuf|graphql|typed-api|schema|event|file-format|none"
+        source: "replace-with-contract-path-or-not_applicable"
+        compatibility: "replace-with-backward-compatible|breaking|not_applicable|needs-confirmation"
+    upstream:
+      - "replace-with-caller-or-not_applicable"
+    downstream:
+      - "replace-with-dependency-or-not_applicable"
+    change_gates:
+      - "replace-with-contract-diff-or-api-test"
+      - "replace-with-affected-regression"
+    rollback:
+      strategy: "replace-with-feature-flag|revert|schema-rollback|not_applicable|needs-confirmation"
+      evidence: "replace-with-runbook-or-evidence-path"

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

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放契约优先相关模板，覆盖 OpenAPI、mock、client 生成和联调说明。
+
+## 结构索引
+
+- `openapi.yaml`：契约主文件模板。
+- `orval.config.ts`：client 生成配置。
+- `prism-usage.md`：mock / 联调说明。
+- `README.md`：契约目录使用说明。
+
+## 修改规则
+
+- 契约字段、错误码、分页和统一响应结构应与 `context/API_MAP.md`、`design/frontend-architecture.md` 保持一致。
+- 改动契约模板时，不要忘记 client 生成链路和 mock 使用说明。

package/package-source/docs/codex-harness-engineering/templates/contracts/README.md

@@ -0,0 +1,24 @@
+# Contracts Templates Guide
+
+本目录提供 contract-first 开发的最小模板组合。
+
+## 推荐文件
+
+- `openapi.yaml`: 前后端共享真相源的 OpenAPI 样例
+- `orval.config.ts`: 生成 types / client / mocks 的 Orval 配置模板
+- `prism-usage.md`: 本地 mock server 和 validation proxy 的 Prism 用法模板
+
+## 推荐顺序
+
+1. 先完善 `openapi.yaml`
+2. 再配置 `orval.config.ts`
+3. 生成 client / mocks
+4. 用 `prism-usage.md` 跑本地 mock 与 contract 验证
+
+## 最低契约要求
+
+- 请求入口统一通过 generated client 或项目约定的 `apiClient/httpClient`，不要在页面里直接拼 `fetch/axios/baseURL`。
+- 分页字段默认统一为 `page/pageSize`；如果项目另有约定，必须在 contract 和 API_MAP 中明确。
+- 响应结构必须统一，例如 `code/message/data` 或项目定义的等价结构；不要让前端猜 `res.data` 还是 `res.result`。
+- 错误模型必须显式定义，至少覆盖校验失败、权限失败、冲突和服务错误。
+- 前端类型优先从 contract 生成，不手写猜测字段。

package/package-source/docs/codex-harness-engineering/templates/contracts/openapi.yaml

@@ -0,0 +1,182 @@
+openapi: 3.0.3
+info:
+  title: Ticket Views API
+  version: 0.1.0
+  description: Contract-first example for a ticket filter and saved views workflow.
+servers:
+  - url: https://api.example.com
+tags:
+  - name: tickets
+  - name: ticket-views
+paths:
+  /tickets:
+    get:
+      tags: [tickets]
+      summary: List tickets with filters
+      operationId: listTickets
+      parameters:
+        - in: query
+          name: status
+          schema:
+            type: string
+            enum: [open, pending, resolved]
+        - in: query
+          name: priority
+          schema:
+            type: string
+            enum: [low, medium, high]
+        - in: query
+          name: assigneeId
+          schema:
+            type: string
+        - in: query
+          name: page
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - in: query
+          name: pageSize
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 20
+      responses:
+        "200":
+          description: Ticket list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketListResponse"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "403":
+          description: Permission denied
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /ticket-views:
+    get:
+      tags: [ticket-views]
+      summary: List saved ticket views
+      operationId: listTicketViews
+      responses:
+        "200":
+          description: Saved ticket views
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [items]
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/TicketView"
+    post:
+      tags: [ticket-views]
+      summary: Create a saved ticket view
+      operationId: createTicketView
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTicketViewRequest"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TicketView"
+        "400":
+          description: Invalid payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: View name already exists
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+components:
+  schemas:
+    Ticket:
+      type: object
+      required: [id, title, status, priority]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+          nullable: true
+    TicketListResponse:
+      type: object
+      required: [items, page, pageSize, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Ticket"
+        page:
+          type: integer
+        pageSize:
+          type: integer
+        total:
+          type: integer
+    TicketFilter:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [open, pending, resolved]
+        priority:
+          type: string
+          enum: [low, medium, high]
+        assigneeId:
+          type: string
+    TicketView:
+      type: object
+      required: [id, name, filters]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    CreateTicketViewRequest:
+      type: object
+      required: [name, filters]
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 100
+        filters:
+          $ref: "#/components/schemas/TicketFilter"
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/package-source/docs/codex-harness-engineering/templates/contracts/orval.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "orval";
+
+export default defineConfig({
+  ticketApi: {
+    input: "./contracts/openapi.yaml",
+    output: {
+      target: "./packages/api-client/generated/ticket-api.ts",
+      schemas: "./packages/api-client/generated/model",
+      client: "react-query",
+      mock: true,
+      mode: "split",
+      override: {
+        mutator: {
+          path: "./packages/api-client/http-client.ts",
+          name: "httpClient",
+        },
+      },
+    },
+  },
+});

package/package-source/docs/codex-harness-engineering/templates/contracts/prism-usage.md

@@ -0,0 +1,41 @@
+# Prism Usage 模板
+
+## 1. 目标
+
+用 Prism 在真实后端完成前提供:
+
+- mock server
+- request/response contract 验证
+- 异常态联调入口
+
+## 2. 安装
+
+```bash
+npm install -D @stoplight/prism-cli
+```
+
+## 3. 启动 mock server
+
+```bash
+npx prism mock contracts/openapi.yaml -h 0.0.0.0
+```
+
+## 4. 启动 validation proxy
+
+```bash
+npx prism proxy contracts/openapi.yaml https://api.example.com
+```
+
+## 5. 推荐联调顺序
+
+1. 先用 Prism mock 跑前端
+2. 再生成 Orval client / mocks
+3. 前端先围绕 generated client 写页面和测试
+4. 最后切真实后端并跑 Prism proxy
+
+## 6. 联调检查点
+
+- request 参数名是否和 contract 一致，例如 `page/pageSize`
+- response 包装层是否和 contract 一致，例如 `code/message/data`
+- 错误响应是否都能命中 `ErrorResponse` 或项目定义的统一错误模型
+- 前端是否已经切到 generated client，而不是继续手写一套 request schema

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

@@ -0,0 +1,21 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放前端先行、图转前端和视觉评审链路的模板。
+
+## 结构索引
+
+- `design-brief.md`：设计约束说明。
+- `component-map.md`：组件映射。
+- `screen-states.md`：状态矩阵。
+- `image-to-frontend-spec.md`：图转前端规格。
+- `frontend-architecture.md`：前端实现边界。
+- `ui-image-review.md` / `visual-parity-review.md`：视觉评审模板。
+- `design-tokens.json`：视觉 token。
+- `assets/`：设计资产说明。
+
+## 修改规则
+
+- 这个目录关注“可编码设计真相源”，不是品牌展示稿仓库。
+- 页面状态、移动端、安全区、组件复用和视觉证据要求要与 `testing/`、`docs/frontend-quality-rules.md` 对齐。

package/package-source/docs/codex-harness-engineering/templates/design/ai-image-brief.md

@@ -0,0 +1,122 @@
+# AI Image Brief 模板
+
+> 目标: 在写前端代码前，先基于完整产品和设计规格，使用 AI 生图/编辑工具生成可评审的前端界面图。图片不是最终实现规范，图片评审通过后才进入图转前端规格。
+
+## 1. 基本信息
+
+- Feature ID:
+- Page ID:
+- 页面名称:
+- 设备 / 画布: Desktop 1440px / Tablet / Mobile 375px / Other
+- 设计来源: Product Spec / Design Brief / Component Map / Screen States / Design Tokens
+- 生成批次:
+- 状态: Draft / Review / Approved / Rejected
+
+## 2. 输入真相源
+
+| 真相源 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Approved / Draft | |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Approved / Draft | |
+| Design Brief | `docs/design/design-brief.md` | Approved / Draft | |
+| Component Map | `docs/design/component-map.md` | Approved / Draft | |
+| Screen States | `docs/design/screen-states.md` | Approved / Draft | |
+| Design Tokens | `docs/design/design-tokens.json` | Approved / Draft | |
+
+## 3. CSS / 视觉要求
+
+| 类别 | 要求 |
+| --- | --- |
+| 颜色 | |
+| 字体 | |
+| 字号层级 | |
+| 间距 | |
+| 圆角 | |
+| 阴影 | |
+| 表格 / 列表密度 | |
+| 表单控件高度 | |
+| 按钮层级 | |
+| 状态色 | |
+| 响应式折叠 | |
+
+## 4. 必须生成的界面状态
+
+| State | 是否生成 | 说明 | 输出图片 |
+| --- | --- | --- | --- |
+| default | Yes | | |
+| empty | Yes | | |
+| loading | Yes | | |
+| error | Yes | | |
+| permission_denied | Yes / No | | |
+| disabled | Yes / No | | |
+| long_content | Yes / No | | |
+| mobile | Yes / No | | |
+
+## 5. 生图提示词
+
+```text
+生成 [页面名称] 的生产级前端 UI 设计图。
+
+页面目标:
+[从 PRD 摘要填写]
+
+用户角色:
+[填写角色]
+
+画布:
+[Desktop 1440px / Mobile 375px 等]
+
+视觉规范:
+- 颜色:
+- 字体:
+- 间距:
+- 圆角:
+- 阴影:
+- 信息密度:
+- 状态色:
+
+页面结构:
+- 顶部:
+- 主内容:
+- 侧边 / 辅助区域:
+- 底部 / 操作区:
+
+组件:
+- [来自 component-map 的组件和职责]
+
+必须体现的状态:
+- [本批次状态]
+
+边界要求:
+- 长文本:
+- 空数据:
+- 错误:
+- 无权限:
+- 移动端:
+
+禁止:
+- 不要添加 Product Spec 没有的功能
+- 不要省略 required state
+- 不要使用与 Design Tokens 冲突的颜色、字号或间距
+```
+
+## 6. 图片编辑提示词
+
+```text
+基于上一版图继续编辑，不改变页面信息架构。
+
+需要修改:
+- [具体差异]
+
+保持不变:
+- [已通过评审的布局/组件/样式]
+
+补充状态:
+- [需要补的状态]
+```
+
+## 7. 输出记录
+
+| Image ID | State | 文件 / 链接 | 生成提示词版本 | 评审状态 |
+| --- | --- | --- | --- | --- |
+| IMG-001 | default | | v1 | Draft |

package/package-source/docs/codex-harness-engineering/templates/design/assets/README.md

@@ -0,0 +1,24 @@
+# Design Assets
+
+本目录用于保存已评审的 UI 设计参考图。
+
+## 工具策略
+
+- 本目录的 AI 生图和图片编辑默认使用 Codex 内置 `image_gen` 工具。
+- 项目绑定图片必须复制或移动到本目录后，任务才允许通过。
+- `manifest.md` 必须为每张最终 PNG 记录 `source_tool: image_gen`、prompt、覆盖页面、覆盖状态、评审结论和实现注意事项。
+- 浏览器截图、Playwright 截图、HTML/CSS 截图、程序化绘图和占位 PNG 只能作为实现证据或临时脚手架，不能满足本目录的设计参考图要求。
+- CLI fallback 或第三方服务必须先获得用户显式确认，并且已配置所需凭据；它们不是本项目默认路径。
+
+## 必需补齐文件
+
+按当前 feature 的页面和状态矩阵补齐参考图，例如：
+
+- `<feature>-<page>-default-reference.png`
+- `<feature>-<page>-empty-reference.png`
+- `<feature>-<page>-error-reference.png`
+- `<feature>-<page>-disabled-reference.png`
+- `<feature>-mobile-reference.png`
+- `manifest.md`
+
+`artifacts/visual-review/` 下的浏览器截图是实现证据，不能替代本目录的设计参考图。