@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/HOW_TO_USE_SKILLS.md

@@ -0,0 +1,91 @@
+# Skills 使用指南
+
+## Skill 已加载
+
+当前项目的 skill package 位于：`.agents/skills/`
+
+当前目录约定：
+
+- `.agents/skills/`：active skill package
+- `.agents/workflows/`：独立 workflow 文档
+- `.agents/archive/workflows/skill-mirrors/`：已归档的 workflow 镜像副本
+
+## 如何使用Skill
+
+### 1. 自动识别
+AI会根据任务需求自动判断并使用相关skill：
+- 任务描述中包含skill相关的关键词
+- AI判断某个skill适用于当前任务
+
+### 2. 明确指定
+您可以直接要求使用某个skill：
+```
+"使用 example-skill 来处理这个任务"
+"按照 example-skill 的步骤执行"
+"使用 harness-surface-sync 检查并同步 harness 流程"
+"用 harness-surface-sync 扫一遍 testing-left-shift 文档和镜像"
+"使用 auto-commit 检查当前改动、补齐同步并提交推送"
+"用 auto-commit，如果没有 GitHub 仓库就用 gh 创建后再推送"
+```
+
+### 3. 浏览可用 Skills
+查看所有可用的skills：
+```
+"显示所有可用的skills"
+"列出项目中的skills"
+```
+
+## 当前可用的Skills
+
+### Harness Surface Sync
+- **位置**: `.agents/skills/harness-surface-sync/`
+- **说明**: 一次性检查并同步 harness runtime、docs/testing、templates、workflows、config、package-assets 和 skills 镜像
+- **适用场景**:
+  - 规则、prompt、task 模板或 testing-left-shift 真相源刚改过
+  - 需要继续扫旧流程表述并补齐镜像同步
+  - 需要把新的 repo-local skill 一并打进 package-assets
+
+### Auto Review and Commit
+- **位置**: `.agents/skills/auto-commit/`
+- **说明**: 一次性检查当前工作区、补齐必要同步、生成提交并推送；如果没有远程仓库，默认用 GitHub CLI 创建私有仓库
+- **适用场景**:
+  - 当前改动已经完成，准备收尾提交
+  - 当前仓库有 `.agents` / `agent` / `templates` / `package-assets` 镜像，需要提交前补齐同步
+  - 当前本地仓库还没有 `origin`，希望直接建 GitHub 仓库再推送
+
+### AI Config Git Sync
+- **位置**: `.agents/skills/ai-config-git-sync/`
+- **说明**: 维护共享 AI workflow/config 到多个 Git 项目的同步链路，支持读状态、写配置、建同步分支、push 和开 PR
+- **适用场景**:
+  - 需要更新 `.ai-sync.yml`、`sync-targets.json` 或多项目同步脚本
+  - 需要把 root AI 配置改动 fan-out 到多个项目仓库
+  - 需要检查 drift、manifest、lock 或同步分支/PR 状态
+
+### Example Skill
+- **位置**: `.agents/skills/example-skill/`
+- **说明**: 一个示例技能，展示如何创建和使用技能文件
+- **包含**: 
+  - SKILL.md: 主文档
+  - scripts/: 辅助脚本
+  - examples/: 使用示例
+  - resources/: 配置模板
+
+## Skill开发
+
+创建新的skill：
+1. 在 `.agents/skills/` 下创建新文件夹
+2. 在文件夹中创建 `SKILL.md` 文件
+3. 添加YAML frontmatter和详细说明
+4. （可选）添加scripts、examples、resources等目录
+
+## 系统级Skills
+
+如果想让skill在所有项目中可用，可以复制到：
+```
+~/.gemini/antigravity/skills/
+```
+
+Windows路径：
+```
+C:\Users\<用户名>\.gemini\antigravity\skills\
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/academic-mermaid-diagrams/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: academic-mermaid-diagrams
+description: 学术规范的 Mermaid 渲染与图表生成指南。用于生成符合学术论文标准的架构图、时序图、ER 图等，具有清晰层次、标准符号和黑白黑白极简配色的特点。
+---
+
+# 学术化 Mermaid 图形生成指南
+
+> 本工作流/技能指南规定了如何使用 Mermaid 代码生成符合严格学术论文要求的高质量、专业化机制图与架构图，彻底替代复杂的手工图像编辑过程。
+
+## 触发场景
+- 当用户要求在技术文档、开题报告、毕业设计或学术论文中补充插图时。
+- 当系统需要生成清晰严谨的“系统总体架构图”、“业务时序图”、“ER实体关系图”、“状态机生命周期图”时。
+- 当现有的系统图显得过于随意（带有鲜艳主题色、排版混乱、标注不清）而需要转为学术格式时。
+
+---
+
+## 核心设计规范与约束
+
+符合学术标准的 Mermaid 图表**必须**严格遵守以下 5 项特征：
+
+### 1. 黑白配色，简洁专业
+- **禁止**使用 Mermaid 默认的蓝/黄/绿鲜艳配色。
+- **配置注入**：必须在图首行注入 `%%{init: {'theme': 'base'... }}%%` 指令，强制图表为白底、黑边框、黑字、黑线、可选的极简浅灰底色。
+
+### 2. 清晰的层次分隔（虚线分隔各层）
+- 使用 `subgraph` 划分逻辑层次（如：展示层、业务层、数据层）。
+- 辅以 `classDef stroke-dasharray` 将分层包裹框修改为规范的**虚线框**，避免包裹框抢夺主体模块的视觉焦点。
+
+### 3. 标准化图形符号
+- **模块/组件**：使用标准的矩形 `[组件名称]` 或圆角矩形 `(组件名称)`。
+- **数据源/存储媒介**：强制使用学术通用的圆柱体符号 `[(数据库名称)]` 标识持久化层。
+- **网关/网关节点**：菱形或平滑多边形。
+
+### 4. 规范的箭头连接
+- 数据/控制流动：统一采用标准实线的黑侧单向箭头 `-->`。
+- 异步消息/弱依赖/缓存击穿：使用虚线箭头 `-.->`。
+- 避免箭头飞线交叉，必要时通过增加隐式排版节点或控制树的深入方向（`graph TD` 俯视或 `graph LR` 平视）进行梳理。
+
+### 5. 层次标签明确标注
+- 每个层次（子图）的左上/中上部必须有明确功能定位的标注，如 `[表现层 presentation layer]`。
+- 模块名应直指系统功能或组件专名，杜绝无意义的代称。
+
+---
+
+## 学术级图表实战模板库
+
+在响应用户“生成一篇符合论文要求的图（如架构图）”的请求时，应当直接套用或变体下方模板生成代码。
+
+### 模板 A：分层架构拓扑图 (系统总体架构)
+
+典型的四层结构架构视图，实现了规范的虚线图层框与黑白学术风：
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#ffffff', 'primaryBorderColor': '#000000', 'primaryTextColor': '#000000', 'lineColor': '#000000', 'clusterBkg': 'none', 'clusterBorder': '#333333'}}}%%
+graph TD
+    classDef layerBox fill:none,stroke:#333,stroke-dasharray: 5 5,stroke-width:1.5px;
+    classDef standardBox fill:#fff,stroke:#000,stroke-width:1px;
+    classDef db fill:#fff,stroke:#000,stroke-width:1px;
+
+    subgraph Layer_Presentation [前端展示层]
+        Web[Web 管理后台]:::standardBox
+        App[移动端客户端]:::standardBox
+    end
+
+    subgraph Layer_Business [后端业务处理层]
+        Gateway[API 路由网关]:::standardBox
+        subgraph Core_Modules [核心服务集群]
+            AuthSvc[安全认证服务]:::standardBox
+            OrderSvc[订单流转服务]:::standardBox
+            RuleSvc[业务规则引擎]:::standardBox
+        end
+    end
+
+    subgraph Layer_Data [数据存储层]
+        DB[(MySQL 业务主库)]:::db
+        Redis[(Redis 缓存/锁)]:::db
+    end
+
+    Web --> Gateway
+    App --> Gateway
+    Gateway --> AuthSvc
+    AuthSvc --> OrderSvc
+    AuthSvc --> RuleSvc
+    
+    OrderSvc --> DB
+    OrderSvc -.-> Redis
+    
+    %% 应用层边界虚线样式
+    class Layer_Presentation,Layer_Business,Layer_Data layerBox;
+    class Core_Modules layerBox;
+```
+
+### 模板 B：E-R 数据实体关系图
+
+学术 E-R 图更侧重关系基数与实体属性。学术版需要强制白底黑字。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#000', 'textColor': '#000'}}}%%
+erDiagram
+    USERS ||--o{ ORDERS : "1:N (发起)"
+    PHOTOGRAPHERS ||--o{ ORDERS : "1:N (承接)"
+    ORDERS ||--|| PAYMENTS : "1:1"
+
+    USERS {
+        BigInt user_id PK "用户主键"
+        String email UK "邮箱"
+    }
+    ORDERS {
+        BigInt order_id PK "订单主键"
+        Int status "生命周期状态"
+    }
+    PAYMENTS {
+        BigInt pay_id PK "流水号"
+        Decimal amount "数额"
+    }
+```
+
+### 模板 C：系统级生命周期状态图 (状态机)
+
+用于表现严格的状态转换，在“流转引擎”、“事务处理状态闭环”类论文章节必备。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fff', 'primaryBorderColor': '#000', 'lineColor': '#000', 'textColor': '#000'}}}%%
+stateDiagram-v2
+    classDef stateNode fill:#fff,stroke:#000,stroke-width:1px;
+    
+    [*] --> 待审核 : 提交发布
+    待审核 --> 已生效 : 人工审核通过
+    待审核 --> 驳回 : 人工审核拒绝
+    
+    已生效 --> [*] : 服务结束/停用
+    驳回 --> [*] : 废弃
+```
+
+### 模板 D：规范预约时序图 (序列交互图)
+
+用于描述涉及三方组件、微服务内部、或者核心交易机制的同步/异步过程交互。
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'actorBkg': '#fff', 'actorBorder': '#000', 'actorTextColor': '#000', 'signalColor': '#000', 'signalTextColor': '#000', 'noteBkg': '#f9f9f9', 'noteBorder': '#000'}}}%%
+sequenceDiagram
+    autonumber
+    participant Client as 客户端界面
+    participant API as 后端聚合服务
+    participant DB as MySQL持久层
+    participant Remote as 外部支付平台
+
+    Client->>API: 1. 发起订单支付请求
+    activate API
+    API->>DB: 2. 校验订单并发隔离锁
+    DB-->>API: 3. 约束校验通过
+    API->>Remote: 4. 调用三方支付网关接口
+    
+    rect rgb(245, 245, 245)
+        note right of Remote: 【关键网关节点】异步验签
+        Remote-->>API: 5. 返回支付凭证(Token)
+    end
+    
+    API-->>Client: 6. 重定向至安全支付页
+    deactivate API
+```
+
+## AI 执行要求
+在应用此 Skill 时，AI 需要执行以下动作：
+1. **抓取原始述求**：仔细提取用户代码或文字中提炼模块（前、后、数据等）、实体关系或调用路径。
+2. **选择渲染图格式**：根据描述类型，判定属于组件图结构(graph TD) 还是 控制流 (sequence/state)。
+3. **强制混入 CSS 层**：把 `%%{init: ...}%%` 学术模板投喂到代码的最前沿。
+4. **验证符合论文 5 准则**：检查 `[]` (实体), `[()]` (DB圆柱), `虚线`, `单色视觉` 分离呈现状况后再进行输出。
+5. **强制全态 AI 生图策略 (PNG 生成)**：在用户明确要求使用 `generate_image` 工具直接生成带有实际文字内容的图表时，请遵循以下最新策略，绝对不允许退避并生成“无字纯几何图形”：
+   - **提取凝练文本短词**：由于模型在渲染复杂长句容易发生文字错乱，构思提示词时，必须将模块名称进行最精简凝练（支持提供中文字符，必要时加上简短精准的英文辅助），如把“订单状态生命周期”精简为“订单流转(Order State)”。
+   - **强硬注入文本指令**：提示词中必须直接且强硬地规定：“图内的核心方框或节点上，必须要端正地渲染写出下列文字，绝不能省略或留白”。
+   - **放宽容错与多次试错**：系统理解模型写字时可能会有瑕疵或拼写失误，但必须迎难而上。为了获得更好效果，允许且推荐在同一次需求中运用工具并行**多次声成**（提供多样化候选给用户选择），从而选出文本更清晰准确、排版最具论文范儿的一张图。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/ai-config-git-sync/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: ai-config-git-sync
+description: 审计、更新并 fan-out 共享 AI workflow/config 到多个 Git 项目。Use when Claude needs to read or edit `.ai-sync.yml`, `sync-targets.json`, managed mirrors, drift status, sync branches, pushes, or pull requests across multiple repositories.
+---
+
+# AI Config Git Sync
+
+## Overview
+
+这个 skill 用于维护“中央 AI 配置仓库 -> 多个项目仓库”的同步链路，支持只读审计和实际写入两种模式。
+
+默认目标：
+
+1. 找到当前变更的 canonical source。
+2. 更新 root 脚本、`.ai-sync.yml` 或 package 文档，而不是直接改目标仓库里的 managed 文件。
+3. 先把 当前仓库包根和 package-assets 镜像刷齐。
+4. 再按 `sync-targets.json` 把改动 fan-out 到多个 Git 项目。
+5. 默认走“同步分支 + push + 可选 PR”，不要直推目标仓库主分支。
+
+先读 [references/command-recipes.md](references/command-recipes.md)。
+
+## Repo Canonical Rules
+
+- 共享同步脚本以 repo root 为 canonical：
+  - `tools/install/ai-workflow/check-ai-sync-drift.ps1`
+  - `scripts/ai-workflow/sync-ai-config-to-targets.ps1`
+  - `scripts/ai-workflow/sync-targets.example.json`
+- `.ai-sync.yml` 是 当前仓库包根的同步声明源。
+- `.agents/skills/<name>` 是 repo-local skill 的 canonical source。
+- `docs/codex-harness-engineering/templates/...`、`docs/codex-harness-engineering/templates/package-assets/...`、`docs/codex-harness-engineering/templates/package-assets/skills/...` 都是镜像或发行面，不应先手工改。
+
+## Workflow
+
+### 1. Snapshot
+
+先确认当前仓库状态：
+
+```powershell
+git status --short
+git branch --show-current
+```
+
+如果只是读状态，停在审计模式；如果用户要真正更新多个项目，再进入写模式。
+
+### 2. Decide the mode
+
+`Audit mode` 适用于：
+
+- 检查 `.ai-sync.yml` / manifest / lock 是否漂移
+- 看哪些项目需要同步
+- 预览目标列表、verify 命令和 PR 策略
+
+`Write mode` 适用于：
+
+- 更新 root 同步脚本或 skill
+- 刷新 当前仓库包根
+- 更新 `sync-targets.json`
+- 对目标仓库建分支、提交、push、开 PR
+
+### 3. Update canonical source first
+
+如果需求涉及同步逻辑本身：
+
+1. 先改 repo root 的 `scripts/ai-workflow/*`
+2. 如果新增 skill，先改 `.agents/skills/<skill-name>`
+3. 如果改 `agent` 包声明，再改 `.ai-sync.yml`
+
+不要先改这些路径里的 managed 副本：
+
+- `tools/install/ai-workflow/*`
+- `docs/codex-harness-engineering/templates/package-assets/skills/*`
+- `docs/codex-harness-engineering/templates/package-assets/*`
+
+### 4. Refresh the package mirrors
+
+root canonical 改完后，先刷新当前仓库自己的包面：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -CheckOnly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+如果新增/更新的是 skill，还要确认：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\check-ai-sync-drift.ps1
+```
+
+### 5. Prepare or update sync-targets.json
+
+默认从示例开始：
+
+```powershell
+Copy-Item .\scripts\ai-workflow\sync-targets.example.json .\scripts\ai-workflow\sync-targets.json
+```
+
+然后补齐：
+
+- `source.repo`
+- `source.ref`
+- `defaults.baseBranch`
+- `defaults.pushBranch`
+- `defaults.createPullRequest`
+- 每个 `targets[*]` 的 `repo` 或 `localPath`
+- 每个目标的 `syncConfigPath`
+
+如果只是本地演练，优先使用 `localPath`、`-NoPush`、`-NoPullRequest`。
+
+### 6. Run fan-out
+
+标准执行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\scripts\ai-workflow\sync-targets.json
+```
+
+常用变体：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\scripts\ai-workflow\sync-targets.json -OnlyTargets your-org/project-a
+
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\scripts\ai-workflow\sync-targets.json -NoPullRequest
+
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\scripts\ai-workflow\sync-targets.json -NoPush -NoPullRequest
+```
+
+只有在用户明确接受源仓库未提交状态时，才加：
+
+```powershell
+-AllowDirtySource
+```
+
+### 7. Validate and report
+
+至少汇报：
+
+- 改了哪些 canonical source
+- 是否已刷新 当前仓库包根
+- 跑了哪些 drift / verify
+- 同步了哪些目标仓库
+- 建了哪些分支
+- 是否 push
+- 是否开 PR
+
+## Guardrails
+
+- 不要直接编辑目标仓库中的 managed 文件来“修同步”。
+- 默认不要直推目标仓库 `main` / `master`。
+- 源仓库或目标仓库脏工作区默认视为阻塞，除非用户明确要求继续。
+- `sync-targets.json` 和 `.ai-sync.yml` 当前按 JSON 兼容格式处理；不要写成只能 YAML 解析器识别、但 `ConvertFrom-Json` 读不了的内容。
+- 如果用户只要查看状态，不要顺手 push 或开 PR。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/ai-config-git-sync/references/command-recipes.md

@@ -0,0 +1,92 @@
+# Command Recipes
+
+## 1. 检查当前 当前仓库包根是否已同步
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -CheckOnly
+```
+
+## 2. 检查已安装包的 managed 漂移
+
+在目标项目根目录：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\ai-workflow\check-ai-sync-drift.ps1
+```
+
+在当前仓库检查 shared package source：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\check-ai-sync-drift.ps1
+```
+
+## 3. 刷新当前仓库的 当前仓库包根
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+## 4. 生成多项目同步配置
+
+```powershell
+Copy-Item .\tools\install\ai-workflow\sync-targets.example.json .\tools\install\ai-workflow\sync-targets.json
+```
+
+最小配置骨架：
+
+```json
+{
+  "source": {
+    "repo": "your-org/ai-workflow-kit",
+    "ref": "main"
+  },
+  "defaults": {
+    "baseBranch": "main",
+    "branchPrefix": "chore/ai-kit-sync",
+    "pushBranch": true,
+    "createPullRequest": true,
+    "syncConfigPath": ".ai-sync.yml"
+  },
+  "targets": [
+    {
+      "repo": "your-org/project-a",
+      "baseBranch": "main",
+      "syncConfigPath": ".ai-sync.yml"
+    }
+  ]
+}
+```
+
+## 5. Fan-out 到多个目标仓库
+
+标准模式：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\tools\install\ai-workflow\sync-targets.json
+```
+
+只跑单个目标：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\tools\install\ai-workflow\sync-targets.json -OnlyTargets your-org/project-a
+```
+
+只建分支和提交，不开 PR：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\tools\install\ai-workflow\sync-targets.json -NoPullRequest
+```
+
+本地演练，不 push：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\ai-workflow\sync-ai-config-to-targets.ps1 -ConfigPath .\tools\install\ai-workflow\sync-targets.json -NoPush -NoPullRequest
+```
+
+## 6. 常见判断
+
+- 要改同步逻辑：先改 root `scripts/ai-workflow/*`
+- 要改 skill：先改 `.agents/skills/<name>`
+- 要改安装包映射：改 `.ai-sync.yml`
+- 要把改动发到多个项目：先 `refresh-agent-package.ps1`，再 `sync-ai-config-to-targets.ps1`