@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/config/rules/harness.rules

@@ -0,0 +1,29 @@
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\verify.ps1"],
+    decision = "allow",
+    justification = "verify.ps1 is the project harness verification entrypoint.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\env-check.ps1"],
+    decision = "allow",
+    justification = "env-check.ps1 is a harness environment readiness check.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\codex-loop.ps1"],
+    decision = "prompt",
+    justification = "codex-loop.ps1 may edit files, update task state, write traces, and commit.",
+)
+
+prefix_rule(
+    pattern = ["pwsh", "-NoProfile", "-Command"],
+    decision = "prompt",
+    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-Command"],
+    decision = "prompt",
+    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
+)

package/package-source/docs/codex-harness-engineering/templates/config/rules/patterns.md

@@ -0,0 +1,59 @@
+---
+trigger: always_on
+---
+
+# Common Patterns
+
+## API Response Format
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+  meta?: {
+    total: number
+    page: number
+    limit: number
+  }
+}
+```
+
+## Custom Hooks Pattern
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value)
+
+  useEffect(() => {
+    const handler = setTimeout(() => setDebouncedValue(value), delay)
+    return () => clearTimeout(handler)
+  }, [value, delay])
+
+  return debouncedValue
+}
+```
+
+## Repository Pattern
+
+```typescript
+interface Repository<T> {
+  findAll(filters?: Filters): Promise<T[]>
+  findById(id: string): Promise<T | null>
+  create(data: CreateDto): Promise<T>
+  update(id: string, data: UpdateDto): Promise<T>
+  delete(id: string): Promise<void>
+}
+```
+
+## Skeleton Projects
+
+When implementing new functionality:
+1. Search for battle-tested skeleton projects
+2. Use parallel agents to evaluate options:
+   - Security assessment
+   - Extensibility analysis
+   - Relevance scoring
+   - Implementation planning
+3. Clone best match as foundation
+4. Iterate within proven structure

package/package-source/docs/codex-harness-engineering/templates/config/rules/safety.rules

@@ -0,0 +1,35 @@
+prefix_rule(
+    pattern = ["git", "reset", "--hard"],
+    decision = "forbidden",
+    justification = "Never discard user or agent work without explicit human direction outside automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "checkout", "--"],
+    decision = "forbidden",
+    justification = "Destructive checkout can overwrite user work and is not allowed in harness automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "clean"],
+    decision = "forbidden",
+    justification = "Git clean can delete untracked user files and generated evidence.",
+)
+
+prefix_rule(
+    pattern = ["rm", "-rf"],
+    decision = "forbidden",
+    justification = "Recursive deletion is not allowed from agent automation.",
+)
+
+prefix_rule(
+    pattern = ["Remove-Item", "-Recurse"],
+    decision = "forbidden",
+    justification = "Recursive deletion must not run from broad agent automation.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-Command", "Remove-Item"],
+    decision = "prompt",
+    justification = "PowerShell deletion must be reviewed because inline commands can be broad or destructive.",
+)

package/package-source/docs/codex-harness-engineering/templates/config/rules/testing.md

@@ -0,0 +1,34 @@
+---
+trigger: always_on
+---
+
+# Testing Requirements
+
+## Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** - Individual functions, utilities, components
+2. **Integration Tests** - API endpoints, database operations
+3. **E2E Tests** - Critical user flows (Playwright)
+
+## Test-Driven Development
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test - it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test - it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+## Troubleshooting Test Failures
+
+1. Use **tdd-guide** agent
+2. Check test isolation
+3. Verify mocks are correct
+4. Fix implementation, not tests (unless tests are wrong)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
+- **e2e-runner** - Playwright E2E testing specialist

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

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放项目导航层和当前任务 / 计划上下文模板，对应安装后项目的 `docs/ai/*`。
+
+## 结构索引
+
+- `repo-map.md`：代码地图和规则索引。
+- `architecture-brief.md`：架构摘要。
+- `CURRENT_TASK.md`：当前任务最小事实。
+- `PROJECT_CONTEXT.md` / `DECISIONS.md` / `KNOWN_ISSUES.md`：扩展上下文。
+- `API_MAP.md` / `DB_SCHEMA.md`：接口与数据面索引。
+- `dev-plan.md` / `feature-pack.md`：计划和跨会话语义包。
+
+## 修改规则
+
+- 保持“短事实、可导航、可续跑”，不要把长篇 PRD 或实现细节堆进 context 模板。
+- 与 `docs/`、`product/`、`spec/`、`testing/` 的 truth source 分工必须清楚。

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

@@ -0,0 +1,18 @@
+# API_MAP
+
+记录当前项目的接口面。没有真实业务 API 时，也可以先记录命令入口、路由入口、合同文件和 SDK/client 生成位置。
+
+## 建议结构
+
+| 接口 | 位置 | 作用 | 上游 | 下游 |
+| --- | --- | --- | --- | --- |
+
+## 建议补充
+
+- 认证方式
+- 错误模型
+- contract 位置
+- mock / prism / SDK 生成位置
+- 统一请求入口（例如 `apiClient` / generated client）
+- 分页字段约定（例如 `page/pageSize`）
+- 统一响应包装（例如 `code/message/data`）

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

@@ -0,0 +1,11 @@
+# CHANGELOG_AI
+
+记录会影响 agent 阅读顺序、导航方式、安装输出面或治理规则的摘要变更。
+
+## 建议结构
+
+### YYYY-MM-DD
+
+- 变更:
+- 影响面:
+- 相关真相源:

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

@@ -0,0 +1,114 @@
+# CURRENT_TASK
+
+记录当前任务的最小必要事实，不要把完整 PRD 或长篇讨论直接堆进这里。
+
+## 建议填写项
+
+- 任务目标:
+- 任务性质（bugfix / feature / refactor / chore）:
+- 验收标准:
+- 当前阶段:
+- owned paths:
+- 这个功能属于哪个模块:
+- 项目里有没有类似实现:
+- 类似页面:
+- 类似接口:
+- 类似组件:
+- 类似状态管理:
+- 当前状态分层决策（URL / remote cache / global store / local state / form）:
+- 哪些状态禁止重复存放:
+- 缓存失效或刷新规则:
+- 设计系统 / token 约束:
+- 移动端安全区 / 键盘遮挡处理:
+- 表单校验与提交流程策略:
+- Controller / Handler 边界:
+- Service 边界:
+- Repository / DAO 边界:
+- 事务 / 幂等策略:
+- 异常处理与错误码策略:
+- 权限校验边界（角色 / 资源 / 本人 / 租户）:
+- 输入校验边界（类型 / 长度 / 枚举 / 金额 / 日期 / 文件）:
+- 敏感信息脱敏策略（响应 / 日志 / trace / 审计）:
+- 风控 / 限流策略:
+- 类似测试:
+- 本轮 development_validation:
+- 本轮 acceptance_validation:
+- 未运行测试 / 豁免及原因:
+- 假测试风险提示:
+- 复用决定:
+- 不复用理由:
+- 如果修改公共组件，组件名称:
+- 如果修改公共组件，受影响页面 / 模块:
+- 如果修改公共组件，props 兼容性影响:
+- 如果修改公共组件，样式 / 交互回归风险:
+- 如果修改公共组件，需要补哪些组件测试 / E2E:
+- 是否新增目录:
+- 新目录名称:
+- 为什么现有目录不能放:
+- 新目录未来会放什么:
+- 是否符合当前目录结构:
+- 是否需要补子目录 `AGENTS.md`:
+- 需要改哪些文件:
+- 本任务涉及的业务名词统一叫法:
+- 禁止混用的同义词:
+- 新增 / 修改文件命名模式:
+- 新增函数 / hook / handler 命名约定:
+- 新增类型命名边界（Entity / DTO / Response / FormValues / ViewModel 等）:
+- 行为不变约束（接口 / 用户路径 / 数据结构 / 兼容逻辑）:
+- 允许清理的死代码 / 临时代码:
+- 不允许删除的兼容逻辑 / 历史入口:
+- 可能影响哪些调用方:
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 回归范围:
+- 前端性能预算:
+- 后端性能策略（索引 / 缓存 / 分页 / N+1）:
+- 弱网 / 离线 / 大数据量策略:
+- 日志 / trace 字段要求:
+- 观测指标 / 告警策略:
+- 需要跑哪些测试:
+- 风险点:
+- 依赖的真相源:
+- 关键验证命令:
+- 必需环境变量 / Secret:
+- 受影响配置文件（.env / package.json / Dockerfile / CI / nginx / k8s / config）:
+- 构建 / 部署影响:
+- 回滚配置策略:
+- 需要同步更新的文档:
+- schema / migration 是否变更:
+- migration 文件 / 目录:
+- 历史数据兼容 / 回填策略:
+- 第三方服务 / SDK 依赖:
+- 第三方回调 / Webhook / 验签策略:
+- 凭据 / Secret 注入位置:
+- 上传约束（大小 / 类型 / 扫描 / 权限 / CDN）:
+- 平台差异（iOS / Android / H5 / 小程序）:
+- 权限申请与拒绝回退:
+- 生命周期 / 中断恢复策略:
+- 设备 / 系统版本验证矩阵:
+- 交付验收报告路径:
+- 逐条需求完成情况:
+- 本轮已完成内容:
+- 本轮未完成内容 / 剩余问题:
+- 本轮修改文件:
+- 为什么这样改 / 关键决策:
+- 已通过测试与证据:
+- 未运行测试与原因:
+- 下一个 Agent 建议起点:
+- 本轮避免并行修改的文件 / 目录:
+- 暂时不要动的区域:
+- 当前入口文件 / 页面 / 命令:
+- 相关类型 / 契约入口:
+- 相关配置 / 环境变量入口:
+
+## 使用规则
+
+- 新任务开始时更新。
+- 任务切换时清空旧事实。
+- 长会话续跑前先确认这里是否仍与当前任务一致。
+- 每轮会话结束前至少刷新“已完成内容 / 未完成内容 / 修改文件 / 测试结果 / 下一步”。
+- 下一个 Agent 续跑前先核对这里记录的修改文件、未跑测试和禁止并行修改路径。
+- 多 Agent 协作时，用这里声明文件边界；不要让多个 Agent 同时写同一组文件。
+- 可复用经验进入 `docs/knowledge/*`，不要长期堆在这里。

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

@@ -0,0 +1,14 @@
+# DB_SCHEMA
+
+记录当前项目的重要数据结构。没有数据库时，也可以先记录关键 JSON、状态文件、缓存结构或 trace 结构。
+
+## 建议结构
+
+| 实体 / 文件 | 位置 | 关键字段 | 约束 | 风险 |
+| --- | --- | --- | --- | --- |
+
+## 建议补充
+
+- 主外键或关联关系
+- 状态字段
+- 高风险一致性约束

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

@@ -0,0 +1,12 @@
+# DECISIONS
+
+用于记录项目级决策摘要。长期稳定、可复用且需要成熟度管理的决策，建议同步沉淀到 `docs/knowledge/decisions/*`。
+
+## 建议结构
+
+### D-001 标题
+
+- 结论:
+- 原因:
+- 影响:
+- 相关真相源:

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

@@ -0,0 +1,12 @@
+# KNOWN_ISSUES
+
+记录值得优先提醒 agent 的已知问题、高风险区域和容易误判的边界。
+
+## 建议结构
+
+### K-001 标题
+
+- 风险:
+- 触发条件:
+- 规避方式:
+- 相关真相源:

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

@@ -0,0 +1,14 @@
+# PROJECT_CONTEXT
+
+用一句话说明目标项目是什么，再补充系统边界、核心业务域和默认协作口径。
+
+## 建议结构
+
+- 项目定位:
+- 主要用户:
+- 核心业务域:
+- 系统边界:
+- 不负责的范围:
+- 关键目录:
+- 默认运行链路:
+- 关键真相源:

package/package-source/docs/codex-harness-engineering/templates/context/architecture-brief.md

@@ -0,0 +1,58 @@
+# Architecture Brief
+
+## 1. 系统概览
+
+- 系统边界: 本仓库维护 Codex Harness 安装包和当前仓库运行时，不承载具体业务应用。
+- 核心服务: `tools/harness/codex-loop.ps1` driver、`tools/install/bootstrap-codex-harness.ps1` 安装初始化、`refresh-agent-package.ps1` 包同步、`.codex/prompts/*` 执行提示、`.agents/skills/*` 可复用技能。
+- 主要数据流: `task.json` -> driver -> `codex exec` -> 验证命令 -> `progress.txt` / trace -> Git commit。
+
+## 2. 分层职责
+
+| 层 | 职责 | 主要目录 |
+| --- | --- | --- |
+| Runtime 层 | 任务选择、执行、验证、trace、提交 | `tools/harness/codex-loop.ps1`, `task.json`, `.codex/` |
+| Package 层 | 当前仓库包根与可分发 package-assets | repo root |
+| Template 层 | 新项目 bootstrap 模板 | `docs/codex-harness-engineering/templates/` |
+| Knowledge 层 | 深文档、规则治理、测试真相源、知识沉淀 | `docs/harness/`, `docs/testing/`, `docs/knowledge/` |
+| Skill 层 | 可复用流程和专用能力 | `.agents/skills/`, `docs/codex-harness-engineering/templates/package-assets/skills/` |
+
+## 3. 真相源
+
+- 产品真相源: `docs/requirement-prep-kit/` 或任务声明。
+- 设计真相源: `docs/codex-harness-engineering/templates/design/`。
+- Contract 真相源: `docs/codex-harness-engineering/templates/contracts/`。
+- 类型真相源: PowerShell scripts、JSON schema、task template。
+- 测试真相源: `docs/testing/*`。
+
+## 4. 关键模块
+
+| 模块 | 责任 | 上游 | 下游 | 风险 |
+| --- | --- | --- | --- | --- |
+| `tools/harness/codex-loop.ps1` | driver-first 自动执行 | `task.json`, `.codex/prompts/*` | trace、progress、commit | 状态伪造、验证缺失 |
+| `tools/install/bootstrap-codex-harness.ps1` | 初始化目标项目 runtime/docs/config | templates | 目标项目根目录 | 漏装关键 truth source |
+| `refresh-agent-package.ps1` | 刷新当前仓库 package 面和 manifest | root truth source | templates / ai-sync | 镜像漂移 |
+| `.agents/skills/` | 活跃技能 canonical | skill authors | `docs/codex-harness-engineering/templates/package-assets/skills`, package-assets | 只改一处导致分发缺失 |
+| `docs/codex-harness-engineering/` | 安装包方法论和模板 | root docs / package docs | package-assets docs | 文档和安装行为不一致 |
+
+## 5. 关键约束
+
+- 修改安装行为时，先改 root runtime 或模板 canonical，再同步 `.agents/`、templates 和 package-assets。
+- 修改 skills 时，以 `.agents/skills/<name>` 为 canonical。
+- 修改 active role rules 时，以 `.codex/rules/agents.md` 为 canonical。
+- 文档改动至少运行 `git diff --check`；脚本改动还要做 PowerShell parser 检查。
+
+## 6. 高风险区域
+
+- `task.json` 状态写回。
+- Git dirty workspace 检查。
+- package mirrors 和 manifest / lock。
+- hooks 与 driver 职责边界。
+- 外部 MCP、token、cookie、私钥、密码。
+
+## 7. 建议阅读顺序
+
+1. `AGENTS.md`
+2. `docs/ai/repo-map.md`
+3. `docs/harness/architecture.md`
+4. `docs/harness/rule-governance.md`
+5. `docs/codex-harness-engineering/README.md`

package/package-source/docs/codex-harness-engineering/templates/context/dev-plan.md

@@ -0,0 +1,166 @@
+# DEV-PLAN 模板
+
+## 1. 基本信息
+
+- `feature_id`:
+- `title`:
+- `owner`:
+- `source_docs`:
+  - `docs/product/...`
+  - `docs/design/...`
+  - `contracts/...`
+
+## 2. 目标与完成定义
+
+- 业务目标:
+- 技术目标:
+- Done 定义:
+
+## 3. 真相源
+
+- Product Spec:
+- PRD-Lite:
+- Page Inventory:
+- State Matrix:
+- Acceptance Criteria:
+- Acceptance Examples:
+- Requirement Interface Matrix:
+- Traceability Matrix:
+- Difficulty Research:
+- Design Brief:
+- 设计稿 / Figma:
+- Component Map:
+- Screen States:
+- Design Tokens:
+- AI Image Brief:
+- UI Image Review:
+- Image To Frontend Spec:
+- Visual Parity Review:
+- Contract:
+- Test Matrix:
+- E2E Plan:
+- Test Data Plan:
+- Test Data Matrix:
+- Risk Based Test Plan:
+- Regression Plan:
+- Evidence Protocol:
+- Failure Triage:
+- Coverage Policy:
+- Verify Matrix:
+- Repo map:
+
+## 4. 阶段闸门
+
+| 阶段 | 进入条件 | 输出 | 未满足时处理 |
+| --- | --- | --- | --- |
+| Product Readiness | 原始需求已澄清，P0/P1 需求已补齐验收标准、验收示例和追溯入口 | `docs/product/*`, `ACCEPTANCE_CRITERIA.md`, `ACCEPTANCE_EXAMPLES.md`, `TRACEABILITY_MATRIX.md` | BLOCKED 或补需求 |
+| Design Readiness | Product Readiness 通过 | `docs/design/*` | BLOCKED 或补设计 |
+| UI Image Readiness | CSS/视觉规范完整，AI 生图已评审 | `ai-image-brief.md`, `ui-image-review.md`, `image-to-frontend-spec.md` | BLOCKED 或重生成/编辑图片 |
+| Visual Parity Readiness | 前端页面已实现并可在浏览器打开 | `artifacts/visual-review/*`, `visual-parity-review.md` | BLOCKED 或修复 UI 后重新截图 |
+| Test Readiness | P0/P1 需求已映射到测试层级、测试数据、affected tests、evidence path 和回归范围；affected tests 与回归范围必须可追溯 | `test-matrix.md`, `TEST_DATA_MATRIX.md`, `RISK_BASED_TEST_PLAN.md`, `REGRESSION_PLAN.md`, `failure-triage.md` | BLOCKED 或补测试计划 |
+| Contract Readiness | API / 数据变化已明确 | `contracts/openapi.yaml` | BLOCKED 或豁免说明 |
+| Implementation | Product、Design、Plan、Testing 真相源齐全，Requirement IDs 已可追溯 | 代码、测试、trace | 禁止实现 |
+
+## 5. Phase 划分
+
+### Phase 1
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 2
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+### Phase 3
+
+- 目标:
+- 交付物:
+- 前置条件:
+- 风险:
+
+## 6. Task 拆分规则
+
+- 每个 Task 只处理一个明确目标。
+- 每个 Task 必须能在 fresh session 中完成。
+- 每个 Task 必须有自己的验证命令。
+- 每个实现 Task 必须声明 Requirement IDs、owned paths、affected tests 和 evidence expectation。
+- 每个实现 Task 还必须写明 evidence path 和回归范围，不能只写测试命令。
+- 不允许把“实现 + 修所有 bug + 补所有测试”混成一个任务。
+
+## 7. 当前 Task 队列
+
+| Task ID | Phase | 目标 | 依赖 | 验证命令 | 状态 |
+| --- | --- | --- | --- | --- | --- |
+| T001 | P1 | | | | todo |
+
+## 8. 评审与修复闭环
+
+```text
+实现
+  -> Stage 1 review（Spec / 设计稿 / DEV-PLAN 一致性）
+  -> 浏览器截图与设计参考图视觉还原对比
+  -> 修复偏差
+  -> Stage 2 review（代码质量 / 测试 / 风险）
+  -> 修复问题
+  -> verify + fresh evidence
+  -> 才允许完成
+```
+
+## 9. 验证矩阵
+
+- 类型检查:
+- Lint:
+- Acceptance / Examples:
+- Traceability:
+- 单元测试:
+- 组件 / Story 测试:
+- Contract 测试:
+- API integration:
+- 集成测试:
+- E2E:
+- Affected Tests:
+- P0/P1 Regression:
+- Visual regression:
+- Visual parity screenshots:
+- Contract validation:
+- Coverage:
+- Verify matrix:
+- Backend layering check:
+- 事务 / 幂等验证:
+- 异常处理 / 错误码验证:
+
+## 10. BLOCKED 条件
+
+- 缺少设计稿或状态矩阵
+- 缺少 PRD-Lite、页面清单或验收标准
+- 缺少可执行验收示例
+- 缺少需求到界面的完整追溯矩阵
+- 缺少 `TRACEABILITY_MATRIX.md` 或 Requirement IDs 无法落到代码/测试
+- 高风险难点没有研究结论
+- 缺少 Design Brief、Component Map、Screen States 或 Design Tokens
+- AI 生成界面图未评审通过
+- 图片未转换成前端可实现规格
+- 前端 UI 缺少真实浏览器截图和设计参考图对比报告
+- Contract 未冻结
+- Controller / Service / Repository 边界未声明
+- 事务、幂等或异常处理策略未声明
+- P0/P1 需求缺少 `test-matrix.md` 映射
+- P0/P1 需求缺少 `TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md` 或 affected tests
+- E2E 缺少 seed 或账号数据
+- 测试失败没有 failure class 和 owner hint
+- 把 Stage 17 当成第一次定义测试范围的入口
+- 依赖任务未完成
+- 关键环境不可用
+- 需要人工决策
+
+## 11. 跨 Session 接续规则
+
+- 新 session 开始时先读本文件。
+- 进入新 Phase 前先重新读取真相源文档。
+- 如果设计稿、Product Spec、Contract 有变更，先更新本计划再编码。