@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,177 @@
+---
+name: orchestrate
+description: Workflow skill from orchestrate.md
+---
+
+# Orchestrate Command
+
+Sequential agent workflow for complex tasks.
+
+## Usage
+
+`/orchestrate [workflow-type] [task-description]`
+
+## Workflow Types
+
+### feature
+Full feature implementation workflow:
+```
+planner -> tdd-guide -> code-reviewer -> security-reviewer
+```
+
+### bugfix
+Bug investigation and fix workflow:
+```
+explorer -> tdd-guide -> code-reviewer
+```
+
+### refactor
+Safe refactoring workflow:
+```
+architect -> code-reviewer -> tdd-guide
+```
+
+### security
+Security-focused review:
+```
+security-reviewer -> code-reviewer -> architect
+```
+
+## Execution Pattern
+
+For each agent in the workflow:
+
+1. **Invoke agent** with context from previous agent
+2. **Collect output** as structured handoff document
+3. **Pass to next agent** in chain
+4. **Aggregate results** into final report
+
+## Handoff Document Format
+
+Between agents, create handoff document:
+
+```markdown
+## HANDOFF: [previous-agent] -> [next-agent]
+
+### Context
+[Summary of what was done]
+
+### Findings
+[Key discoveries or decisions]
+
+### Files Modified
+[List of files touched]
+
+### Open Questions
+[Unresolved items for next agent]
+
+### Recommendations
+[Suggested next steps]
+```
+
+## Example: Feature Workflow
+
+```
+/orchestrate feature "Add user authentication"
+```
+
+Executes:
+
+1. **Planner Agent**
+   - Analyzes requirements
+   - Creates implementation plan
+   - Identifies dependencies
+   - Output: `HANDOFF: planner -> tdd-guide`
+
+2. **TDD Guide Agent**
+   - Reads planner handoff
+   - Writes tests first
+   - Implements to pass tests
+   - Output: `HANDOFF: tdd-guide -> code-reviewer`
+
+3. **Code Reviewer Agent**
+   - Reviews implementation
+   - Checks for issues
+   - Suggests improvements
+   - Output: `HANDOFF: code-reviewer -> security-reviewer`
+
+4. **Security Reviewer Agent**
+   - Security audit
+   - Vulnerability check
+   - Final approval
+   - Output: Final Report
+
+## Final Report Format
+
+```
+ORCHESTRATION REPORT
+====================
+Workflow: feature
+Task: Add user authentication
+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
+
+SUMMARY
+-------
+[One paragraph summary]
+
+AGENT OUTPUTS
+-------------
+Planner: [summary]
+TDD Guide: [summary]
+Code Reviewer: [summary]
+Security Reviewer: [summary]
+
+FILES CHANGED
+-------------
+[List all files modified]
+
+TEST RESULTS
+------------
+[Test pass/fail summary]
+
+SECURITY STATUS
+---------------
+[Security findings]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## Parallel Execution
+
+For independent checks, run agents in parallel:
+
+```markdown
+### Parallel Phase
+Run simultaneously:
+- code-reviewer (quality)
+- security-reviewer (security)
+- architect (design)
+
+### Merge Results
+Combine outputs into single report
+```
+
+## Arguments
+
+$ARGUMENTS:
+- `feature <description>` - Full feature workflow
+- `bugfix <description>` - Bug fix workflow
+- `refactor <description>` - Refactoring workflow
+- `security <description>` - Security review workflow
+- `custom <agents> <description>` - Custom agent sequence
+
+## Custom Workflow Example
+
+```
+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
+```
+
+## Tips
+
+1. **Start with planner** for complex features
+2. **Always include code-reviewer** before merge
+3. **Use security-reviewer** for auth/payment/PII
+4. **Keep handoffs concise** - focus on what next agent needs
+5. **Run verification** between agents if needed

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/page-spec-template/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: page-spec-template
+description: 页面规格模板
+---
+
+# 页面规格模板
+
+每个页面必须包含以下内容，评审前必须完整填写。
+
+## 页面规格：[页面名称]
+
+### 基本信息
+| 属性 | 值 |
+|------|-----|
+| 页面名称 | |
+| 页面路径 | /module/page |
+| 所属模块 | |
+| 关联需求 | Req-XXX |
+| 页面类型 | 列表页/详情页/表单页/仪表盘 |
+
+### 状态覆盖 ⚠️ 必填
+
+| 状态 | 是否需要 | 设计稿链接 | 备注 |
+|------|----------|------------|------|
+| 正常态（有数据） | ✅ | | |
+| 空态（无数据） | ✅/❌ | | 空态引导文案 |
+| 加载态 | ✅/❌ | | 骨架屏/spinner |
+| 错误态 | ✅/❌ | | 错误提示+重试 |
+| 部分加载态 | ✅/❌ | | 列表加载更多 |
+| 禁用态 | ✅/❌ | | 无权限时 |
+| 编辑态 | ✅/❌ | | 表单编辑中 |
+| 提交中态 | ✅/❌ | | 按钮loading |
+
+### 交互状态 ⚠️ 必填
+
+| 元素 | hover | focus | active | disabled | selected |
+|------|-------|-------|--------|----------|----------|
+| 主按钮 | ✅ | ✅ | ✅ | ✅ | - |
+| 次按钮 | ✅ | ✅ | ✅ | ✅ | - |
+| 输入框 | - | ✅ | - | ✅ | - |
+| 下拉框 | ✅ | ✅ | - | ✅ | ✅ |
+| 表格行 | ✅ | - | ✅ | - | ✅ |
+
+### 边界场景 ⚠️ 必填
+
+| 场景 | 处理方式 | 具体规则 |
+|------|----------|----------|
+| 文本超长 | 截断+省略号 | 最多显示N字符，hover显示tooltip |
+| 数据超多 | 分页 | 每页10/20/50条，默认10 |
+| 数据为空 | 空态组件 | 显示图标+文案+操作按钮 |
+| 网络超时 | 错误提示 | "网络异常，请重试"+重试按钮 |
+| 权限不足 | 隐藏/禁用 | 无权限时不显示或禁用 |
+
+### 响应式设计（如需支持）
+
+| 断点 | 屏幕宽度 | 布局变化 |
+|------|----------|----------|
+| 大屏 | ≥1440px | 默认布局 |
+| 桌面 | 1200-1439px | 侧边栏收窄 |
+| 平板 | 768-1199px | 侧边栏折叠 |
+| 手机 | <768px | 单列布局 |
+
+### 字段规格 ⚠️ 必填
+
+| 字段名 | 显示名 | 类型 | 格式 | 校验规则 | 错误提示 | 必填 |
+|--------|--------|------|------|----------|----------|------|
+| name | 名称 | string | - | 2-50字符 | "名称长度2-50字符" | ✅ |
+| status | 状态 | enum | 标签 | - | - | ✅ |
+| createTime | 创建时间 | datetime | YYYY-MM-DD HH:mm | - | - | - |
+| amount | 金额 | number | ¥0.00 | ≥0 | "金额格式不正确" | ✅ |
+
+### 操作反馈 ⚠️ 必填
+
+| 操作 | 成功反馈 | 失败反馈 | 需要确认 | 确认文案 |
+|------|----------|----------|----------|----------|
+| 新建 | toast "创建成功" | toast 错误信息 | ❌ | - |
+| 删除 | toast "删除成功" | toast 错误信息 | ✅ | "确认删除？" |
+| 提交 | toast "提交成功" | toast 错误信息 | ✅ | "确认提交？" |
+
+### 权限视图 ⚠️ 必填
+
+| 角色 | 可见元素 | 可操作 | 差异说明 |
+|------|----------|--------|----------|
+| 管理员 | 全部 | 全部 | - |
+| 普通用户 | 隐藏删除按钮 | 只能编辑自己的 | |
+| 游客 | 公开数据 | 无 | 显示登录引导 |
+
+### 页面间跳转
+
+| 触发元素 | 目标页面 | 跳转方式 | 携带参数 |
+|----------|----------|----------|----------|
+| 列表行点击 | 详情页 | 当前页跳转 | id |
+| 新建按钮 | 新建页 | 当前页跳转 | - |
+| 返回按钮 | 列表页 | 返回上一页 | - |
+

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

@@ -0,0 +1,116 @@
+---
+name: pdf
+description: PDF 文件处理指南
+---
+
+# PDF 文件处理指南
+
+## 触发条件
+生成 PDF、PDF 解析、PDF 合并、报表导出
+
+## 推荐库
+
+### 生成 PDF
+- **pdf-lib** (推荐): 纯 JS，支持创建和修改
+- **pdfkit**: Node.js 原生，功能强大
+- **puppeteer**: HTML 转 PDF，适合复杂排版
+
+### 解析 PDF
+- **pdf-parse**: 提取文本内容
+- **pdfjs-dist**: Mozilla 官方库
+
+## 生成 PDF (pdf-lib)
+
+```typescript
+import { PDFDocument, rgb, StandardFonts } from 'pdf-lib';
+import * as fs from 'fs';
+
+/**
+ * 创建简单 PDF
+ */
+async function createPDF() {
+  const pdfDoc = await PDFDocument.create();
+  const page = pdfDoc.addPage([595, 842]); // A4 尺寸
+  const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
+
+  page.drawText('Hello World', {
+    x: 50,
+    y: 750,
+    size: 24,
+    font,
+    color: rgb(0, 0, 0),
+  });
+
+  const pdfBytes = await pdfDoc.save();
+  fs.writeFileSync('output.pdf', pdfBytes);
+}
+```
+
+## HTML 转 PDF (Puppeteer)
+
+```typescript
+import puppeteer from 'puppeteer';
+
+/**
+ * HTML 转 PDF，适合复杂排版
+ */
+async function htmlToPDF(html: string, outputPath: string) {
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.setContent(html, { waitUntil: 'networkidle0' });
+  
+  await page.pdf({
+    path: outputPath,
+    format: 'A4',
+    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' },
+    printBackground: true,
+  });
+  
+  await browser.close();
+}
+```
+
+## 解析 PDF
+
+```typescript
+import pdf from 'pdf-parse';
+import * as fs from 'fs';
+
+/**
+ * 提取 PDF 文本
+ */
+async function extractText(pdfPath: string): Promise<string> {
+  const dataBuffer = fs.readFileSync(pdfPath);
+  const data = await pdf(dataBuffer);
+  return data.text;
+}
+```
+
+## 合并 PDF
+
+```typescript
+import { PDFDocument } from 'pdf-lib';
+
+/**
+ * 合并多个 PDF 文件
+ */
+async function mergePDFs(pdfPaths: string[]): Promise<Uint8Array> {
+  const mergedPdf = await PDFDocument.create();
+  
+  for (const pdfPath of pdfPaths) {
+    const pdfBytes = fs.readFileSync(pdfPath);
+    const pdf = await PDFDocument.load(pdfBytes);
+    const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices());
+    pages.forEach(page => mergedPdf.addPage(page));
+  }
+  
+  return mergedPdf.save();
+}
+```
+
+## 最佳实践
+- 中文支持需嵌入字体文件
+- 复杂排版优先用 HTML + Puppeteer
+- 大文件处理注意内存占用
+- 敏感文档考虑加密和权限设置
+

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

@@ -0,0 +1,169 @@
+---
+name: performance
+description: Performance Skill
+---
+
+# Performance Skill
+
+前后端性能优化策略和最佳实践。
+
+## 前端性能优化
+
+### 资源加载优化
+
+```html
+<!-- 预加载关键资源 -->
+<link rel="preload" href="/fonts/main.woff2" as="font" crossorigin>
+<link rel="preconnect" href="https://api.example.com">
+<link rel="dns-prefetch" href="https://cdn.example.com">
+
+<!-- 异步加载非关键脚本 -->
+<script src="analytics.js" async></script>
+<script src="widget.js" defer></script>
+```
+
+### 图片优化
+```html
+<!-- 响应式图片 -->
+<picture>
+  <source srcset="image.webp" type="image/webp">
+  <source srcset="image.avif" type="image/avif">
+  <img src="image.jpg" loading="lazy" decoding="async" alt="description">
+</picture>
+
+<!-- 尺寸提示防止布局偏移 -->
+<img src="image.jpg" width="800" height="600" alt="description">
+```
+
+### 代码分割
+```javascript
+// React 懒加载
+const Dashboard = React.lazy(() => import('./Dashboard'));
+
+// Vue 异步组件
+const Dashboard = () => import('./Dashboard.vue');
+
+// 路由级分割
+{
+  path: '/dashboard',
+  component: () => import('./views/Dashboard.vue')
+}
+```
+
+### 缓存策略
+```javascript
+// Service Worker 缓存
+self.addEventListener('fetch', event => {
+  event.respondWith(
+    caches.match(event.request).then(response => {
+      return response || fetch(event.request);
+    })
+  );
+});
+```
+
+## 后端性能优化
+
+### 缓存层级
+```
+┌─────────────────────────────────────────┐
+│  浏览器缓存 (Cache-Control)              │
+├─────────────────────────────────────────┤
+│  CDN 缓存                                │
+├─────────────────────────────────────────┤
+│  应用缓存 (Redis/Memcached)              │
+├─────────────────────────────────────────┤
+│  数据库查询缓存                          │
+└─────────────────────────────────────────┘
+```
+
+### Redis 缓存模式
+```python
+# 缓存穿透防护
+def get_user(user_id):
+    cache_key = f"user:{user_id}"
+    cached = redis.get(cache_key)
+    
+    if cached == "NULL":  # 空值缓存
+        return None
+    if cached:
+        return json.loads(cached)
+    
+    user = db.query(User).get(user_id)
+    if user:
+        redis.setex(cache_key, 3600, json.dumps(user.to_dict()))
+    else:
+        redis.setex(cache_key, 300, "NULL")  # 缓存空值
+    return user
+```
+
+### 数据库优化
+```sql
+-- 只查询需要的字段
+SELECT id, name, email FROM users WHERE status = 1;
+
+-- 避免 SELECT *
+-- 使用覆盖索引
+-- 合理使用 LIMIT
+```
+
+### 异步处理
+```python
+# 耗时任务异步化
+from celery import Celery
+
+@celery.task
+def send_email(user_id, template):
+    # 异步发送邮件
+    pass
+
+# 调用时不阻塞
+send_email.delay(user_id, 'welcome')
+```
+
+## 性能指标
+
+### Core Web Vitals
+| 指标 | 良好 | 需改进 | 差 |
+|------|------|--------|-----|
+| LCP (最大内容绘制) | ≤2.5s | ≤4s | >4s |
+| FID (首次输入延迟) | ≤100ms | ≤300ms | >300ms |
+| CLS (累积布局偏移) | ≤0.1 | ≤0.25 | >0.25 |
+
+### 监控工具
+```javascript
+// 性能监控
+const observer = new PerformanceObserver((list) => {
+  for (const entry of list.getEntries()) {
+    console.log(entry.name, entry.startTime, entry.duration);
+  }
+});
+observer.observe({ entryTypes: ['largest-contentful-paint'] });
+```
+
+## 常见性能问题
+
+### 内存泄漏
+```javascript
+// ❌ 未清理的事件监听
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+}, []);
+
+// ✅ 清理副作用
+useEffect(() => {
+  window.addEventListener('resize', handleResize);
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+```
+
+### 重复渲染
+```javascript
+// ❌ 每次渲染创建新对象
+<Component style={{ color: 'red' }} />
+
+// ✅ 使用 useMemo
+const style = useMemo(() => ({ color: 'red' }), []);
+<Component style={style} />
+```
+

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

@@ -0,0 +1,114 @@
+---
+name: plan
+description: Restate requirements, assess risks, and create step-by-step implementation plan. WAIT for user CONFIRM before touching any code.
+---
+
+# Plan Command
+
+This command invokes the **planner** agent to create a comprehensive implementation plan before writing any code.
+
+## What This Command Does
+
+1. **Restate Requirements** - Clarify what needs to be built
+2. **Identify Risks** - Surface potential issues and blockers
+3. **Create Step Plan** - Break down implementation into phases
+4. **Wait for Confirmation** - MUST receive user approval before proceeding
+
+## When to Use
+
+Use `/plan` when:
+- Starting a new feature
+- Making significant architectural changes
+- Working on complex refactoring
+- Multiple files/components will be affected
+- Requirements are unclear or ambiguous
+
+## How It Works
+
+The planner agent will:
+
+1. **Analyze the request** and restate requirements in clear terms
+2. **Break down into phases** with specific, actionable steps
+3. **Identify dependencies** between components
+4. **Assess risks** and potential blockers
+5. **Estimate complexity** (High/Medium/Low)
+6. **Present the plan** and WAIT for your explicit confirmation
+
+## Example Usage
+
+```
+User: /plan I need to add real-time notifications when markets resolve
+
+Agent (planner):
+# Implementation Plan: Real-Time Market Resolution Notifications
+
+## Requirements Restatement
+- Send notifications to users when markets they're watching resolve
+- Support multiple notification channels (in-app, email, webhook)
+- Ensure notifications are delivered reliably
+- Include market outcome and user's position result
+
+## Implementation Phases
+
+### Phase 1: Database Schema
+- Add notifications table with columns: id, user_id, market_id, type, status, created_at
+- Add user_notification_preferences table for channel preferences
+- Create indexes on user_id and market_id for performance
+
+### Phase 2: Notification Service
+- Create notification service in lib/notifications.ts
+- Implement notification queue using BullMQ/Redis
+- Add retry logic for failed deliveries
+- Create notification templates
+
+### Phase 3: Integration Points
+- Hook into market resolution logic (when status changes to "resolved")
+- Query all users with positions in market
+- Enqueue notifications for each user
+
+### Phase 4: Frontend Components
+- Create NotificationBell component in header
+- Add NotificationList modal
+- Implement real-time updates via Supabase subscriptions
+- Add notification preferences page
+
+## Dependencies
+- Redis (for queue)
+- Email service (SendGrid/Resend)
+- Supabase real-time subscriptions
+
+## Risks
+- HIGH: Email deliverability (SPF/DKIM required)
+- MEDIUM: Performance with 1000+ users per market
+- MEDIUM: Notification spam if markets resolve frequently
+- LOW: Real-time subscription overhead
+
+## Estimated Complexity: MEDIUM
+- Backend: 4-6 hours
+- Frontend: 3-4 hours
+- Testing: 2-3 hours
+- Total: 9-13 hours
+
+**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
+```
+
+## Important Notes
+
+**CRITICAL**: The planner agent will **NOT** write any code until you explicitly confirm the plan with "yes" or "proceed" or similar affirmative response.
+
+If you want changes, respond with:
+- "modify: [your changes]"
+- "different approach: [alternative]"
+- "skip phase 2 and do phase 3 first"
+
+## Integration with Other Commands
+
+After planning:
+- Use `/tdd` to implement with test-driven development
+- Use `/build-and-fix` if build errors occur
+- Use `/code-review` to review completed implementation
+
+## Related Agents
+
+This command invokes the `planner` agent located at:
+`~/.claude/agents/planner.md`