@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/example-skill/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: Example Skill
+description: 一个示例技能，展示如何创建和使用技能文件
+---
+
+# Example Skill - 示例技能
+
+## 概述
+
+这是一个示例技能，用于演示如何创建一个标准的 Skill 文件。技能文件遵循特定的结构和约定，以便 AI 助手能够理解并执行相关任务。
+
+## 何时使用此技能
+
+- 当你需要执行某种特定类型的任务时
+- 当你需要遵循特定的工作流程时
+- 当你需要使用特定的工具或方法时
+
+## 技能结构
+
+每个技能都应该包含以下部分：
+
+### 1. YAML Frontmatter
+```yaml
+---
+name: 技能名称
+description: 简短描述此技能的用途
+---
+```
+
+### 2. 概述部分
+简要说明此技能的目的和适用场景。
+
+### 3. 使用说明
+详细的步骤和指导。
+
+### 4. 示例（可选）
+实际使用的例子。
+
+### 5. 注意事项（可选）
+需要特别注意的事项。
+
+## 使用步骤
+
+### 步骤 1: 准备工作
+
+在开始之前，确保你已经：
+- 了解任务需求
+- 准备好必要的工具和资源
+- 阅读相关文档
+
+### 步骤 2: 执行任务
+
+按照以下步骤执行：
+
+1. **分析需求**：明确要解决的问题
+2. **制定计划**：设计解决方案
+3. **实施方案**：编写代码或执行操作
+4. **验证结果**：确保输出符合预期
+
+### 步骤 3: 验证和优化
+
+完成后应该：
+- 检查输出质量
+- 运行测试
+- 优化性能
+- 记录经验教训
+
+## 配置选项
+
+此技能支持以下配置：
+
+- **模式**: `strict` | `flexible`
+  - `strict`: 严格遵循所有规则
+  - `flexible`: 允许一定程度的灵活性
+
+- **输出格式**: `json` | `yaml` | `markdown`
+  - 根据需求选择合适的输出格式
+
+## 示例
+
+### 示例 1: 基本使用
+
+```python
+# 示例代码
+def example_function():
+    """这是一个示例函数"""
+    print("Hello from Example Skill!")
+    return True
+```
+
+### 示例 2: 高级用法
+
+```python
+# 高级示例
+class ExampleClass:
+    def __init__(self, config):
+        self.config = config
+    
+    def process(self, data):
+        """处理数据"""
+        # 实现逻辑
+        return processed_data
+```
+
+## 最佳实践
+
+1. **保持简洁**: 技能文档应该清晰简洁，避免冗余
+2. **结构化**: 使用清晰的标题和章节组织内容
+3. **实用性**: 提供实际可用的示例和模板
+4. **可维护**: 定期更新和维护技能文档
+
+## 常见问题
+
+**Q: 如何选择合适的配置？**
+A: 根据具体任务需求和环境约束来选择。
+
+**Q: 可以自定义技能吗？**
+A: 可以，你可以根据项目需要调整和扩展此技能。
+
+## 相关资源
+
+- `scripts/`: 辅助脚本目录
+- `examples/`: 更多示例
+- `resources/`: 相关资源文件
+
+## 注意事项
+
+> [!IMPORTANT]
+> 使用此技能时请确保：
+> - 已阅读完整文档
+> - 理解每个步骤的目的
+> - 根据实际情况调整参数
+
+> [!WARNING]
+> 注意以下限制：
+> - 某些操作可能需要特定权限
+> - 配置错误可能导致意外结果
+
+## 更新日志
+
+- **2026-01-22**: 创建初始版本

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/example-skill/examples/usage.md

@@ -0,0 +1,76 @@
+# Example Skill - 使用示例
+
+## 示例 1: 简单任务处理
+
+假设你需要处理一个文本文件：
+
+```python
+# 读取文件
+with open('data.txt', 'r', encoding='utf-8') as f:
+    content = f.read()
+
+# 使用helper函数处理
+from scripts.helper import helper_function
+result = helper_function(content)
+
+# 输出结果
+print(result)
+```
+
+## 示例 2: 批量处理
+
+处理多个文件：
+
+```python
+import os
+from scripts.helper import helper_function
+
+files = ['file1.txt', 'file2.txt', 'file3.txt']
+
+for file in files:
+    with open(file, 'r', encoding='utf-8') as f:
+        content = f.read()
+        processed = helper_function(content)
+        
+    # 保存处理结果
+    output_file = f'output_{file}'
+    with open(output_file, 'w', encoding='utf-8') as f:
+        f.write(processed)
+```
+
+## 示例 3: 配置化处理
+
+使用配置文件：
+
+```yaml
+# config.yaml
+mode: strict
+output_format: json
+options:
+  uppercase: true
+  trim_whitespace: true
+```
+
+```python
+import yaml
+
+# 加载配置
+with open('config.yaml', 'r') as f:
+    config = yaml.safe_load(f)
+
+# 根据配置处理
+if config['options']['uppercase']:
+    result = helper_function(data)
+```
+
+## 运行示例
+
+要运行这些示例：
+
+```bash
+# 运行简单示例
+python scripts/helper.py
+
+# 或者直接导入使用
+python -c "from scripts.helper import helper_function; print(helper_function('test'))"
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/example-skill/resources/config.json

@@ -0,0 +1,21 @@
+{
+  "skill_name": "Example Skill",
+  "version": "1.0.0",
+  "templates": [
+    {
+      "name": "basic_template",
+      "description": "基础模板",
+      "content": "这是一个基础模板示例"
+    },
+    {
+      "name": "advanced_template",
+      "description": "高级模板",
+      "content": "这是一个高级模板示例"
+    }
+  ],
+  "constants": {
+    "DEFAULT_TIMEOUT": 30,
+    "MAX_RETRIES": 3,
+    "OUTPUT_DIR": "./output"
+  }
+}

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/example-skill/scripts/helper.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""
+示例辅助脚本
+用于演示如何在skill中包含可执行脚本
+"""
+
+def helper_function(data):
+    """
+    一个辅助函数示例
+    
+    Args:
+        data: 输入数据
+        
+    Returns:
+        处理后的数据
+    """
+    print(f"Processing: {data}")
+    return data.upper()
+
+
+if __name__ == "__main__":
+    # 示例用法
+    result = helper_function("hello skill")
+    print(f"Result: {result}")

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/exception-handling-spec/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: exception-handling-spec
+description: 异常处理规格模板
+---
+
+# 异常处理规格模板
+
+## 并发请求处理 ⚠️ 必填
+
+| 场景 | 处理策略 | 实现方式 | 用户反馈 |
+|------|----------|----------|----------|
+| 快速重复点击 | 防重复提交 | 按钮loading+禁用 | 按钮显示加载状态 |
+| 多次搜索 | 取消前次请求 | AbortController | 只显示最新结果 |
+| 分页快速切换 | 取消前次请求 | AbortController | 只显示当前页 |
+| 表单多次提交 | 幂等键 | X-Idempotency-Key | 返回首次结果 |
+
+## 请求生命周期 ⚠️ 必填
+
+| 场景 | 处理策略 | 说明 |
+|------|----------|------|
+| 页面切换时有未完成请求 | 取消请求 | 组件卸载时取消 |
+| 请求超时 | 自动重试1次 | 超时时间10秒 |
+| 请求失败 | 显示错误+重试按钮 | 用户可手动重试 |
+| 网络断开 | 显示离线提示 | 恢复后自动重试 |
+
+## Token/登录态处理 ⚠️ 必填
+
+| 场景 | 检测方式 | 处理策略 | 用户体验 |
+|------|----------|----------|----------|
+| Token过期 | 401响应 | 尝试刷新Token | 静默刷新，用户无感 |
+| 刷新Token失败 | 刷新接口失败 | 跳转登录页 | 保存当前页面URL |
+| 操作中Token过期 | 401响应 | 弹窗提示重新登录 | "登录已过期，请重新登录" |
+| 多标签页登出 | storage事件 | 同步登出 | 所有标签页跳转登录 |
+| 账号被踢 | WebSocket推送 | 强制登出 | "账号在其他设备登录" |
+
+## 网络异常处理 ⚠️ 必填
+
+| 网络状态 | 检测方式 | 处理策略 | 用户提示 |
+|----------|----------|----------|----------|
+| 断网 | navigator.onLine | 显示离线banner | "网络已断开" |
+| 恢复网络 | online事件 | 自动重试失败请求 | "网络已恢复" |
+| 弱网 | 请求耗时>3秒 | 显示加载进度 | 显示加载百分比 |
+| 请求超时 | 超时10秒 | 提示重试 | "请求超时，请重试" |
+
+## 浏览器行为处理 ⚠️ 必填
+
+| 场景 | 处理策略 | 实现方式 |
+|------|----------|----------|
+| 页面刷新 | 恢复状态 | 关键状态存localStorage |
+| 浏览器后退 | 确认提示 | beforeunload事件 |
+| 关闭标签页 | 确认提示 | beforeunload事件 |
+| 前进/后退 | 恢复滚动位置 | scrollRestoration |
+
+### 表单未保存提示
+```
+触发条件：表单有修改且未保存
+提示文案："您有未保存的更改，确定要离开吗？"
+按钮：[取消] [离开]
+```
+
+## 多标签页同步 ⚠️ 必填
+
+| 数据类型 | 同步策略 | 实现方式 |
+|----------|----------|----------|
+| 登录状态 | 实时同步 | storage事件监听 |
+| 用户信息 | 实时同步 | storage事件监听 |
+| 主题设置 | 实时同步 | storage事件监听 |
+| 业务数据 | 不同步 | 各标签页独立 |
+
+## 错误边界处理 ⚠️ 必填
+
+| 错误类型 | 捕获方式 | 处理策略 | 用户体验 |
+|----------|----------|----------|----------|
+| 组件渲染错误 | ErrorBoundary | 显示降级UI | "页面出错，请刷新" |
+| JS运行时错误 | window.onerror | 上报+提示 | toast提示 |
+| Promise未捕获 | unhandledrejection | 上报+静默 | 不打扰用户 |
+| 资源加载失败 | error事件 | 重试/降级 | 显示占位图 |
+
+## 降级策略 ⚠️ 必填
+
+| 功能 | 降级条件 | 降级方案 |
+|------|----------|----------|
+| 图片加载 | 加载失败 | 显示占位图 |
+| 字体加载 | 加载失败 | 使用系统字体 |
+| 第三方服务 | 服务不可用 | 隐藏相关功能 |
+| WebSocket | 连接失败 | 降级为轮询 |
+| 本地存储 | 存储已满 | 清理旧数据 |
+

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/find-skill/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: find-skill
+description: 搜索和安装 Agent Skills。使用 npx skills 生态系统，从 GitHub 发现并安装 SKILL.md 格式的 Agent Skills，兼容 Claude Code、Cursor、Copilot、Gemini CLI、Antigravity 等多个 AI 工具。
+---
+
+# Find & Install Agent Skills
+
+## 概述
+
+使用 `npx skills` CLI 工具从开放的 Agent Skills 生态系统中搜索、发现和安装技能包。技能会自动安装到项目对应的 `.agents/skills/` 或 `.claude/skills/` 目录下。
+
+## 核心命令
+
+### 1. 搜索技能
+
+```bash
+npx skills find <关键词>
+```
+
+示例：
+```bash
+npx skills find frontend
+npx skills find security
+npx skills find testing
+npx skills find code-review
+```
+
+### 2. 安装技能
+
+从 GitHub 仓库安装整个技能集合：
+```bash
+npx skills add <owner>/<repo>
+```
+
+安装仓库中的特定技能：
+```bash
+npx skills add <owner>/<repo> --skill <skill-name>
+```
+
+示例：
+```bash
+# 安装 Vercel 官方技能集合
+npx skills add vercel-labs/agent-skills
+
+# 安装社区技能集合
+npx skills add VoltAgent/awesome-agent-skills
+
+# 安装特定技能
+npx skills add anthropics/claude-code --skill frontend-design
+```
+
+### 3. 更新已安装技能
+
+```bash
+npx skills update
+```
+
+### 4. 创建新技能
+
+```bash
+npx skills init <skill-name>
+```
+
+## 推荐技能仓库
+
+| 仓库 | 说明 |
+|:---|:---|
+| `vercel-labs/agent-skills` | Vercel 官方技能集 |
+| `VoltAgent/awesome-agent-skills` | 社区精选技能合集 |
+| `anthropics/skills` | Anthropic 官方技能 |
+| `davepoon/buildwithclaude` | Claude Skills Hub（2.5k⭐）|
+
+## 兼容平台
+
+- ✅ Claude Code
+- ✅ Cursor
+- ✅ GitHub Copilot
+- ✅ Gemini CLI
+- ✅ Antigravity IDE
+- ✅ OpenCode / Codex
+
+## 使用流程
+
+1. **搜索**：`npx skills find <关键词>` 发现相关技能
+2. **评估**：查看技能的 `SKILL.md` 内容，确认安全性
+3. **安装**：`npx skills add <owner>/<repo>` 安装到项目
+4. **使用**：AI Agent 会自动发现并读取已安装的 SKILL.md
+
+## 在线目录
+
+更多技能可在 [https://skills.sh](https://skills.sh) 浏览发现。
+
+## 安全提醒
+
+> ⚠️ Agent Skills 本质上是可执行指令，安装前务必审查内容，避免 Prompt 注入或恶意代码。

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/fixing-accessibility/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: fixing-accessibility
+description: Audit and fix HTML accessibility issues including ARIA labels, keyboard navigation, focus management, color contrast, and form errors. Use when adding interactive controls, forms, dialogs, or reviewing WCAG compliance.
+---
+
+# fixing-accessibility
+
+Fix accessibility issues.
+
+## how to use
+
+- `/fixing-accessibility`
+  Apply these constraints to any UI work in this conversation.
+
+- `/fixing-accessibility <file>`
+  Review the file against all rules below and report:
+  - violations (quote the exact line or snippet)
+  - why it matters (one short sentence)
+  - a concrete fix (code-level suggestion)
+
+Do not rewrite large parts of the UI. Prefer minimal, targeted fixes.
+
+## when to apply
+
+Reference these guidelines when:
+- adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns
+- building forms, validation, error states, helper text
+- implementing keyboard shortcuts or custom interactions
+- working on focus states, focus trapping, or modal behavior
+- rendering icon-only controls
+- adding hover-only interactions or hidden content
+
+## rule categories by priority
+
+| priority | category | impact |
+|----------|----------|--------|
+| 1 | accessible names | critical |
+| 2 | keyboard access | critical |
+| 3 | focus and dialogs | critical |
+| 4 | semantics | high |
+| 5 | forms and errors | high |
+| 6 | announcements | medium-high |
+| 7 | contrast and states | medium |
+| 8 | media and motion | low-medium |
+| 9 | tool boundaries | critical |
+
+## quick reference
+
+### 1. accessible names (critical)
+
+- every interactive control must have an accessible name
+- icon-only buttons must have aria-label or aria-labelledby
+- every input, select, and textarea must be labeled
+- links must have meaningful text (no “click here”)
+- decorative icons must be aria-hidden
+
+### 2. keyboard access (critical)
+
+- do not use div or span as buttons without full keyboard support
+- all interactive elements must be reachable by Tab
+- focus must be visible for keyboard users
+- do not use tabindex greater than 0
+- Escape must close dialogs or overlays when applicable
+
+### 3. focus and dialogs (critical)
+
+- modals must trap focus while open
+- restore focus to the trigger on close
+- set initial focus inside dialogs
+- opening a dialog should not scroll the page unexpectedly
+
+### 4. semantics (high)
+
+- prefer native elements (button, a, input) over role-based hacks
+- if a role is used, required aria attributes must be present
+- lists must use ul or ol with li
+- do not skip heading levels
+- tables must use th for headers when applicable
+
+### 5. forms and errors (high)
+
+- errors must be linked to fields using aria-describedby
+- required fields must be announced
+- invalid fields must set aria-invalid
+- helper text must be associated with inputs
+- disabled submit actions must explain why
+
+### 6. announcements (medium-high)
+
+- critical form errors should use aria-live
+- loading states should use aria-busy or status text
+- toasts must not be the only way to convey critical information
+- expandable controls must use aria-expanded and aria-controls
+
+### 7. contrast and states (medium)
+
+- ensure sufficient contrast for text and icons
+- hover-only interactions must have keyboard equivalents
+- disabled states must not rely on color alone
+- do not remove focus outlines without a visible replacement
+
+### 8. media and motion (low-medium)
+
+- images must have correct alt text (meaningful or empty)
+- videos with speech should provide captions when relevant
+- respect prefers-reduced-motion for non-essential motion
+- avoid autoplaying media with sound
+
+### 9. tool boundaries (critical)
+
+- prefer minimal changes, do not refactor unrelated code
+- do not add aria when native semantics already solve the problem
+- do not migrate UI libraries unless requested
+
+## common fixes
+
+```html
+<!-- icon-only button: add aria-label -->
+<!-- before --> <button><svg>...</svg></button>
+<!-- after -->  <button aria-label="Close"><svg aria-hidden="true">...</svg></button>
+
+<!-- div as button: use native element -->
+<!-- before --> <div onclick="save()">Save</div>
+<!-- after -->  <button onclick="save()">Save</button>
+
+<!-- form error: link with aria-describedby -->
+<!-- before --> <input id="email" /> <span>Invalid email</span>
+<!-- after -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>
+```
+
+## review guidance
+
+- fix critical issues first (names, keyboard, focus, tool boundaries)
+- prefer native HTML before adding aria
+- quote the exact snippet, state the failure, propose a small fix
+- for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/fixing-metadata/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: fixing-metadata
+description: >
+  Audit and fix HTML metadata including page titles, meta descriptions, canonical URLs, Open Graph
+  tags, Twitter cards, favicons, JSON-LD structured data, and robots directives. Use when adding
+  SEO metadata, fixing social share previews, reviewing Open Graph tags, setting up canonical URLs,
+  or shipping new pages that need correct meta tags.
+license: MIT
+---
+
+## Workflow
+
+1. Identify pages with missing or incorrect metadata (titles, descriptions, canonical, OG tags)
+2. Audit against the priority rules below — fix critical issues (duplicates, indexing) first
+3. Ensure title, description, canonical, and og:url all agree with each other
+4. Verify social cards render correctly on a real URL, not localhost
+5. Keep diffs minimal and scoped to metadata only — do not refactor unrelated code
+## when to apply
+
+Reference these guidelines when:
+- adding or changing page titles, descriptions, canonical, robots
+- implementing Open Graph or Twitter card metadata
+- setting favicons, app icons, manifest, theme-color
+- building shared SEO components or layout metadata defaults
+- adding structured data (JSON-LD)
+- changing locale, alternate languages, or canonical routing
+- shipping new pages, marketing pages, or shareable links
+
+## rule categories by priority
+
+| priority | category | impact |
+|----------|----------|--------|
+| 1 | correctness and duplication | critical |
+| 2 | title and description | high |
+| 3 | canonical and indexing | high |
+| 4 | social cards | high |
+| 5 | icons and manifest | medium |
+| 6 | structured data | medium |
+| 7 | locale and alternates | low-medium |
+| 8 | tool boundaries | critical |
+
+## quick reference
+
+### 1. correctness and duplication (critical)
+
+- define metadata in one place per page, avoid competing systems
+- do not emit duplicate title, description, canonical, or robots tags
+- metadata must be deterministic, no random or unstable values
+- escape and sanitize any user-generated or dynamic strings
+- every page must have safe defaults for title and description
+
+### 2. title and description (high)
+
+- every page must have a title
+- use a consistent title format across the site
+- keep titles short and readable, avoid stuffing
+- shareable or searchable pages should have a meta description
+- descriptions must be plain text, no markdown or quote spam
+
+### 3. canonical and indexing (high)
+
+- canonical must point to the preferred URL for the page
+- use noindex only for private, duplicate, or non-public pages
+- robots meta must match actual access intent
+- previews or staging pages should be noindex by default when possible
+- paginated pages must have correct canonical behavior
+
+### 4. social cards (high)
+
+- shareable pages must set Open Graph title, description, and image
+- Open Graph and Twitter images must use absolute URLs
+- prefer correct image dimensions and stable aspect ratios
+- og:url must match the canonical URL
+- use a sensible og:type, usually website or article
+- set twitter:card appropriately, summary_large_image by default
+
+### 5. icons and manifest (medium)
+
+- include at least one favicon that works across browsers
+- include apple-touch-icon when relevant
+- manifest must be valid and referenced when used
+- set theme-color intentionally to avoid mismatched UI chrome
+- icon paths should be stable and cacheable
+
+### 6. structured data (medium)
+
+- do not add JSON-LD unless it clearly maps to real page content
+- JSON-LD must be valid and reflect what is actually rendered
+- do not invent ratings, reviews, prices, or organization details
+- prefer one structured data block per page unless required
+
+### 7. locale and alternates (low-medium)
+
+- set the html lang attribute correctly
+- set og:locale when localization exists
+- add hreflang alternates only when pages truly exist
+- localized pages must canonicalize correctly per locale
+
+### 8. tool boundaries (critical)
+
+- prefer minimal changes, do not refactor unrelated code
+- do not migrate frameworks or SEO libraries unless requested
+- follow the project's existing metadata pattern (Next.js metadata API, react-helmet, manual head, etc.)
+
+## review guidance
+
+- fix critical issues first (duplicates, canonical, indexing)
+- ensure title, description, canonical, and og:url agree
+- verify social cards on a real URL, not localhost
+- prefer stable, boring metadata over clever or dynamic
+- keep diffs minimal and scoped to metadata only