@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/project-context-template/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: project-context-template
+description: 项目上下文文档模板，通过 #project-context-template 引用
+---
+
+# 项目上下文文档模板
+
+> 新项目启动时使用此模板生成上下文文档
+
+---
+
+## 使用方法
+
+在开始新项目时，复制以下模板并填写相关信息，作为项目的 `CONTEXT.md` 文件。
+
+---
+
+## 模板
+
+```markdown
+# 项目上下文文档
+
+## 1. 项目概要
+
+### 项目名称
+[项目名称]
+
+### 项目背景
+[为什么要做这个项目？解决什么问题？]
+
+### 目标与目的
+[项目要达成的具体目标]
+
+### 非目标
+[明确不做什么，避免范围蔓延]
+
+---
+
+## 2. 范围定义
+
+### 当前范围
+- [功能1]
+- [功能2]
+- [功能3]
+
+### 非本次范围
+- [暂不实现的功能1]
+- [暂不实现的功能2]
+
+### 约束条件
+- [技术约束]
+- [时间约束]
+- [资源约束]
+
+---
+
+## 3. 关键实体与关系
+
+### 核心实体
+| 实体 | 职责 |
+|:---|:---|
+| [实体1] | [职责描述] |
+| [实体2] | [职责描述] |
+
+### 实体关系
+[描述实体之间的关系，可用 Mermaid 图]
+
+---
+
+## 4. 功能模块
+
+### 模块列表
+| 模块 | 输入 | 输出 | 核心逻辑 |
+|:---|:---|:---|:---|
+| [模块1] | [输入] | [输出] | [逻辑] |
+| [模块2] | [输入] | [输出] | [逻辑] |
+
+### 典型用户场景
+1. [场景1描述]
+2. [场景2描述]
+
+---
+
+## 5. 技术方向
+
+### 技术栈
+- 语言：[Python/TypeScript/...]
+- 框架：[FastAPI/React/...]
+- 数据库：[PostgreSQL/SQLite/...]
+- 其他：[...]
+
+### 数据流
+```
+[数据源] → [处理模块] → [存储] → [输出]
+```
+
+### 已做技术决策
+1. [决策1及原因]
+2. [决策2及原因]
+
+### 可替代方案
+- [方案A]：[优缺点]
+- [方案B]：[优缺点]
+
+---
+
+## 6. 依赖库（胶水编程）
+
+### 核心依赖
+| 库名 | 用途 | 版本 | 文档链接 |
+|:---|:---|:---|:---|
+| [库1] | [用途] | [版本] | [链接] |
+| [库2] | [用途] | [版本] | [链接] |
+
+### 依赖关系图
+```
+[你的代码] → [库A] → [库B]
+           → [库C]
+```
+
+---
+
+## 7. 目录结构
+
+```
+project/
+├── README.md
+├── requirements.txt
+├── .env.example
+├── src/
+│   ├── core/          # 核心业务逻辑
+│   ├── glue/          # 胶水代码
+│   └── utils/         # 工具函数
+├── tests/
+└── docs/
+```
+
+---
+
+## 8. 当前进展
+
+### 已确认事实
+- [x] [已完成事项1]
+- [x] [已完成事项2]
+
+### 未解决问题
+- [ ] [待解决问题1]
+- [ ] [待解决问题2]
+
+---
+
+## 9. 后续计划
+
+### 待讨论主题
+1. [主题1]
+2. [主题2]
+
+### 潜在风险
+- [风险1]：[应对策略]
+- [风险2]：[应对策略]
+
+---
+
+## 10. 交互约定
+
+### AI 输出风格
+- 结构清晰、层级明确、工程化表达
+- 统一使用 Markdown
+- 必要时使用伪代码或列表
+
+### 用户特殊偏好
+[按需填写]
+```
+
+---
+
+## 快速启动提示词
+
+```
+请帮我创建一个项目上下文文档。
+
+项目目标：[一句话描述]
+技术栈偏好：[Python/TypeScript/...]
+时间约束：[...]
+
+请按照项目上下文文档模板的格式输出。
+```

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

@@ -0,0 +1,350 @@
+---
+name: project-guidelines-example
+description: Example project-specific skill template with architecture, patterns, and deployment workflow.
+---
+
+# Project Guidelines Skill (Example)
+
+This is an example of a project-specific skill. Use this as a template for your own projects.
+
+Based on a real production application: [Zenith](https://zenith.chat) - AI-powered customer discovery platform.
+
+---
+
+## When to Use
+
+Reference this skill when working on the specific project it's designed for. Project skills contain:
+- Architecture overview
+- File structure
+- Code patterns
+- Testing requirements
+- Deployment workflow
+
+---
+
+## Architecture Overview
+
+**Tech Stack:**
+- **Frontend**: Next.js 15 (App Router), TypeScript, React
+- **Backend**: FastAPI (Python), Pydantic models
+- **Database**: Supabase (PostgreSQL)
+- **AI**: Claude API with tool calling and structured output
+- **Deployment**: Google Cloud Run
+- **Testing**: Playwright (E2E), pytest (backend), React Testing Library
+
+**Services:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         Frontend                            │
+│  Next.js 15 + TypeScript + TailwindCSS                     │
+│  Deployed: Vercel / Cloud Run                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                         Backend                             │
+│  FastAPI + Python 3.11 + Pydantic                          │
+│  Deployed: Cloud Run                                       │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+        ┌──────────┐   ┌──────────┐   ┌──────────┐
+        │ Supabase │   │  Claude  │   │  Redis   │
+        │ Database │   │   API    │   │  Cache   │
+        └──────────┘   └──────────┘   └──────────┘
+```
+
+---
+
+## File Structure
+
+```
+project/
+├── frontend/
+│   └── src/
+│       ├── app/              # Next.js app router pages
+│       │   ├── api/          # API routes
+│       │   ├── (auth)/       # Auth-protected routes
+│       │   └── workspace/    # Main app workspace
+│       ├── components/       # React components
+│       │   ├── ui/           # Base UI components
+│       │   ├── forms/        # Form components
+│       │   └── layouts/      # Layout components
+│       ├── hooks/            # Custom React hooks
+│       ├── lib/              # Utilities
+│       ├── types/            # TypeScript definitions
+│       └── config/           # Configuration
+│
+├── backend/
+│   ├── routers/              # FastAPI route handlers
+│   ├── models.py             # Pydantic models
+│   ├── main.py               # FastAPI app entry
+│   ├── auth_system.py        # Authentication
+│   ├── database.py           # Database operations
+│   ├── services/             # Business logic
+│   └── tests/                # pytest tests
+│
+├── deploy/                   # Deployment configs
+├── docs/                     # Documentation
+└── scripts/                  # Utility scripts
+```
+
+---
+
+## Code Patterns
+
+### API Response Format (FastAPI)
+
+```python
+from pydantic import BaseModel
+from typing import Generic, TypeVar, Optional
+
+T = TypeVar('T')
+
+class ApiResponse(BaseModel, Generic[T]):
+    success: bool
+    data: Optional[T] = None
+    error: Optional[str] = None
+
+    @classmethod
+    def ok(cls, data: T) -> "ApiResponse[T]":
+        return cls(success=True, data=data)
+
+    @classmethod
+    def fail(cls, error: str) -> "ApiResponse[T]":
+        return cls(success=False, error=error)
+```
+
+### Frontend API Calls (TypeScript)
+
+```typescript
+interface ApiResponse<T> {
+  success: boolean
+  data?: T
+  error?: string
+}
+
+async function fetchApi<T>(
+  endpoint: string,
+  options?: RequestInit
+): Promise<ApiResponse<T>> {
+  try {
+    const response = await fetch(`/api${endpoint}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...options?.headers,
+      },
+    })
+
+    if (!response.ok) {
+      return { success: false, error: `HTTP ${response.status}` }
+    }
+
+    return await response.json()
+  } catch (error) {
+    return { success: false, error: String(error) }
+  }
+}
+```
+
+### Claude AI Integration (Structured Output)
+
+```python
+from anthropic import Anthropic
+from pydantic import BaseModel
+
+class AnalysisResult(BaseModel):
+    summary: str
+    key_points: list[str]
+    confidence: float
+
+async def analyze_with_claude(content: str) -> AnalysisResult:
+    client = Anthropic()
+
+    response = client.messages.create(
+        model="claude-sonnet-4-5-20250514",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": content}],
+        tools=[{
+            "name": "provide_analysis",
+            "description": "Provide structured analysis",
+            "input_schema": AnalysisResult.model_json_schema()
+        }],
+        tool_choice={"type": "tool", "name": "provide_analysis"}
+    )
+
+    # Extract tool use result
+    tool_use = next(
+        block for block in response.content
+        if block.type == "tool_use"
+    )
+
+    return AnalysisResult(**tool_use.input)
+```
+
+### Custom Hooks (React)
+
+```typescript
+import { useState, useCallback } from 'react'
+
+interface UseApiState<T> {
+  data: T | null
+  loading: boolean
+  error: string | null
+}
+
+export function useApi<T>(
+  fetchFn: () => Promise<ApiResponse<T>>
+) {
+  const [state, setState] = useState<UseApiState<T>>({
+    data: null,
+    loading: false,
+    error: null,
+  })
+
+  const execute = useCallback(async () => {
+    setState(prev => ({ ...prev, loading: true, error: null }))
+
+    const result = await fetchFn()
+
+    if (result.success) {
+      setState({ data: result.data!, loading: false, error: null })
+    } else {
+      setState({ data: null, loading: false, error: result.error! })
+    }
+  }, [fetchFn])
+
+  return { ...state, execute }
+}
+```
+
+---
+
+## Testing Requirements
+
+### Backend (pytest)
+
+```bash
+# Run all tests
+poetry run pytest tests/
+
+# Run with coverage
+poetry run pytest tests/ --cov=. --cov-report=html
+
+# Run specific test file
+poetry run pytest tests/test_auth.py -v
+```
+
+**Test structure:**
+```python
+import pytest
+from httpx import AsyncClient
+from main import app
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(app=app, base_url="http://test") as ac:
+        yield ac
+
+@pytest.mark.asyncio
+async def test_health_check(client: AsyncClient):
+    response = await client.get("/health")
+    assert response.status_code == 200
+    assert response.json()["status"] == "healthy"
+```
+
+### Frontend (React Testing Library)
+
+```bash
+# Run tests
+npm run test
+
+# Run with coverage
+npm run test -- --coverage
+
+# Run E2E tests
+npm run test:e2e
+```
+
+**Test structure:**
+```typescript
+import { render, screen, fireEvent } from '@testing-library/react'
+import { WorkspacePanel } from './WorkspacePanel'
+
+describe('WorkspacePanel', () => {
+  it('renders workspace correctly', () => {
+    render(<WorkspacePanel />)
+    expect(screen.getByRole('main')).toBeInTheDocument()
+  })
+
+  it('handles session creation', async () => {
+    render(<WorkspacePanel />)
+    fireEvent.click(screen.getByText('New Session'))
+    expect(await screen.findByText('Session created')).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Deployment Workflow
+
+### Pre-Deployment Checklist
+
+- [ ] All tests passing locally
+- [ ] `npm run build` succeeds (frontend)
+- [ ] `poetry run pytest` passes (backend)
+- [ ] No hardcoded secrets
+- [ ] Environment variables documented
+- [ ] Database migrations ready
+
+### Deployment Commands
+
+```bash
+# Build and deploy frontend
+cd frontend && npm run build
+gcloud run deploy frontend --source .
+
+# Build and deploy backend
+cd backend
+gcloud run deploy backend --source .
+```
+
+### Environment Variables
+
+```bash
+# Frontend (.env.local)
+NEXT_PUBLIC_API_URL=https://api.example.com
+NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+
+# Backend (.env)
+DATABASE_URL=postgresql://...
+ANTHROPIC_API_KEY=sk-ant-...
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_KEY=eyJ...
+```
+
+---
+
+## Critical Rules
+
+1. **No emojis** in code, comments, or documentation
+2. **Immutability** - never mutate objects or arrays
+3. **TDD** - write tests before implementation
+4. **80% coverage** minimum
+5. **Many small files** - 200-400 lines typical, 800 max
+6. **No console.log** in production code
+7. **Proper error handling** with try/catch
+8. **Input validation** with Pydantic/Zod
+
+---
+
+## Related Skills
+
+- `coding-standards.md` - General coding best practices
+- `backend-patterns.md` - API and database patterns
+- `frontend-patterns.md` - React and Next.js patterns
+- `tdd-workflow/` - Test-driven development methodology

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

@@ -0,0 +1,134 @@
+---
+name: project-planning
+description: 项目计划工作流，通过 #project-planning 引用
+---
+
+# 项目计划工作流
+
+> 将需求转化为层级化计划文档
+
+---
+
+## 工作流程
+
+```
+需求收集 → 深入分析 → 生成计划文档 → 审查确认
+```
+
+---
+
+## 阶段 1：需求收集
+
+### 必须澄清的问题
+
+1. **项目目标**：核心功能？解决什么问题？
+2. **功能模块**：分为哪几个主要模块？
+3. **技术栈**：语言、框架、库的偏好？
+4. **数据流向**：数据从哪来？到哪去？
+5. **环境依赖**：外部服务、数据库、API？
+6. **验收标准**：如何判断完成？
+7. **约束条件**：时间、资源、技术限制？
+
+### 需求总结格式
+
+```markdown
+## 目标
+一句话描述要实现什么
+
+## 非目标
+明确不做什么
+
+## 功能清单
+1. [功能1]
+2. [功能2]
+
+## 技术约束
+- [约束1]
+- [约束2]
+```
+
+---
+
+## 阶段 2：计划文档结构
+
+### 文件命名规范
+
+- 格式：`plan_XX_任务名.md`
+- 编号：从 01 开始连续递增
+- plan_01 必须是"总体计划"（1级）
+
+### 层级结构
+
+```
+plan/
+├── plan_01_总体计划.md      # 1级
+├── plan_02_[模块名].md      # 2级
+├── plan_03_[子任务名].md    # 3级
+├── plan_04_[子任务名].md    # 3级
+├── plan_05_[模块名].md      # 2级
+└── ...
+```
+
+### 层级说明
+
+| 层级 | 内容 | 详细程度 |
+|:---|:---|:---|
+| 1级 | 总体计划 | 概要 |
+| 2级 | 模块计划 | 适中 |
+| 3级 | 具体任务 | 详细 |
+
+---
+
+## 阶段 3：可视化要求
+
+每个层级需包含匹配的可视化：
+
+- **1级**：系统逻辑图、模块关系矩阵、里程碑时间线
+- **2级**：模块流程图、接口协作图、资源分配表
+- **3级**：任务流程图、风险监控表
+
+---
+
+## 计划文档 YAML 头
+
+```yaml
+---
+level: 1/2/3              # 层级
+file_id: plan_XX          # 文件编号
+parent: plan_XX           # 父任务编号
+children: [plan_XX, ...]  # 子任务编号
+status: pending           # 状态
+created: YYYY-MM-DD HH:mm # 创建时间
+estimated_time: XX分钟     # 预估耗时
+---
+```
+
+---
+
+## 关键原则
+
+### 必须遵守
+
+1. 只生成计划，不编写实际代码
+2. 使用抽象描述和占位符
+3. 确保计划文档信息完整可执行
+4. 严格遵循层级结构
+5. 连续编号不跳号
+
+### 禁止行为
+
+1. 不要编写实际代码
+2. 不要使用具体的文件名示例
+3. 不要使用具体的函数名示例
+4. 只生成 plan_XX.md 文件
+
+---
+
+## 完成检查清单
+
+- [ ] 需求已完全澄清
+- [ ] 层级结构清晰
+- [ ] 编号连续无跳号
+- [ ] 每个文档包含可视化
+- [ ] 依赖关系已标注
+- [ ] 验收标准已定义