@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,452 @@
+---
+name: doc-updater
+description: Documentation and codemap specialist. Use PROACTIVELY for updating codemaps and documentation. Runs /update-codemaps and /update-docs, generates docs/CODEMAPS/*, updates READMEs and guides.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Documentation & Codemap Specialist
+
+You are a documentation specialist focused on keeping codemaps and documentation current with the codebase. Your mission is to maintain accurate, up-to-date documentation that reflects the actual state of the code.
+
+## Core Responsibilities
+
+1. **Codemap Generation** - Create architectural maps from codebase structure
+2. **Documentation Updates** - Refresh READMEs and guides from code
+3. **AST Analysis** - Use TypeScript compiler API to understand structure
+4. **Dependency Mapping** - Track imports/exports across modules
+5. **Documentation Quality** - Ensure docs match reality
+
+## Tools at Your Disposal
+
+### Analysis Tools
+- **ts-morph** - TypeScript AST analysis and manipulation
+- **TypeScript Compiler API** - Deep code structure analysis
+- **madge** - Dependency graph visualization
+- **jsdoc-to-markdown** - Generate docs from JSDoc comments
+
+### Analysis Commands
+```bash
+# Analyze TypeScript project structure
+npx ts-morph
+
+# Generate dependency graph
+npx madge --image graph.svg src/
+
+# Extract JSDoc comments
+npx jsdoc2md src/**/*.ts
+```
+
+## Codemap Generation Workflow
+
+### 1. Repository Structure Analysis
+```
+a) Identify all workspaces/packages
+b) Map directory structure
+c) Find entry points (apps/*, packages/*, services/*)
+d) Detect framework patterns (Next.js, Node.js, etc.)
+```
+
+### 2. Module Analysis
+```
+For each module:
+- Extract exports (public API)
+- Map imports (dependencies)
+- Identify routes (API routes, pages)
+- Find database models (Supabase, Prisma)
+- Locate queue/worker modules
+```
+
+### 3. Generate Codemaps
+```
+Structure:
+docs/CODEMAPS/
+├── INDEX.md              # Overview of all areas
+├── frontend.md           # Frontend structure
+├── backend.md            # Backend/API structure
+├── database.md           # Database schema
+├── integrations.md       # External services
+└── workers.md            # Background jobs
+```
+
+### 4. Codemap Format
+```markdown
+# [Area] Codemap
+
+**Last Updated:** YYYY-MM-DD
+**Entry Points:** list of main files
+
+## Architecture
+
+[ASCII diagram of component relationships]
+
+## Key Modules
+
+| Module | Purpose | Exports | Dependencies |
+|--------|---------|---------|--------------|
+| ... | ... | ... | ... |
+
+## Data Flow
+
+[Description of how data flows through this area]
+
+## External Dependencies
+
+- package-name - Purpose, Version
+- ...
+
+## Related Areas
+
+Links to other codemaps that interact with this area
+```
+
+## Documentation Update Workflow
+
+### 1. Extract Documentation from Code
+```
+- Read JSDoc/TSDoc comments
+- Extract README sections from package.json
+- Parse environment variables from .env.example
+- Collect API endpoint definitions
+```
+
+### 2. Update Documentation Files
+```
+Files to update:
+- README.md - Project overview, setup instructions
+- docs/GUIDES/*.md - Feature guides, tutorials
+- package.json - Descriptions, scripts docs
+- API documentation - Endpoint specs
+```
+
+### 3. Documentation Validation
+```
+- Verify all mentioned files exist
+- Check all links work
+- Ensure examples are runnable
+- Validate code snippets compile
+```
+
+## Example Project-Specific Codemaps
+
+### Frontend Codemap (docs/CODEMAPS/frontend.md)
+```markdown
+# Frontend Architecture
+
+**Last Updated:** YYYY-MM-DD
+**Framework:** Next.js 15.1.4 (App Router)
+**Entry Point:** website/src/app/layout.tsx
+
+## Structure
+
+website/src/
+├── app/                # Next.js App Router
+│   ├── api/           # API routes
+│   ├── markets/       # Markets pages
+│   ├── bot/           # Bot interaction
+│   └── creator-dashboard/
+├── components/        # React components
+├── hooks/             # Custom hooks
+└── lib/               # Utilities
+
+## Key Components
+
+| Component | Purpose | Location |
+|-----------|---------|----------|
+| HeaderWallet | Wallet connection | components/HeaderWallet.tsx |
+| MarketsClient | Markets listing | app/markets/MarketsClient.js |
+| SemanticSearchBar | Search UI | components/SemanticSearchBar.js |
+
+## Data Flow
+
+User → Markets Page → API Route → Supabase → Redis (optional) → Response
+
+## External Dependencies
+
+- Next.js 15.1.4 - Framework
+- React 19.0.0 - UI library
+- Privy - Authentication
+- Tailwind CSS 3.4.1 - Styling
+```
+
+### Backend Codemap (docs/CODEMAPS/backend.md)
+```markdown
+# Backend Architecture
+
+**Last Updated:** YYYY-MM-DD
+**Runtime:** Next.js API Routes
+**Entry Point:** website/src/app/api/
+
+## API Routes
+
+| Route | Method | Purpose |
+|-------|--------|---------|
+| /api/markets | GET | List all markets |
+| /api/markets/search | GET | Semantic search |
+| /api/market/[slug] | GET | Single market |
+| /api/market-price | GET | Real-time pricing |
+
+## Data Flow
+
+API Route → Supabase Query → Redis (cache) → Response
+
+## External Services
+
+- Supabase - PostgreSQL database
+- Redis Stack - Vector search
+- OpenAI - Embeddings
+```
+
+### Integrations Codemap (docs/CODEMAPS/integrations.md)
+```markdown
+# External Integrations
+
+**Last Updated:** YYYY-MM-DD
+
+## Authentication (Privy)
+- Wallet connection (Solana, Ethereum)
+- Email authentication
+- Session management
+
+## Database (Supabase)
+- PostgreSQL tables
+- Real-time subscriptions
+- Row Level Security
+
+## Search (Redis + OpenAI)
+- Vector embeddings (text-embedding-ada-002)
+- Semantic search (KNN)
+- Fallback to substring search
+
+## Blockchain (Solana)
+- Wallet integration
+- Transaction handling
+- Meteora CP-AMM SDK
+```
+
+## README Update Template
+
+When updating README.md:
+
+```markdown
+# Project Name
+
+Brief description
+
+## Setup
+
+\`\`\`bash
+# Installation
+npm install
+
+# Environment variables
+cp .env.example .env.local
+# Fill in: OPENAI_API_KEY, REDIS_URL, etc.
+
+# Development
+npm run dev
+
+# Build
+npm run build
+\`\`\`
+
+## Architecture
+
+See [docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md) for detailed architecture.
+
+### Key Directories
+
+- `src/app` - Next.js App Router pages and API routes
+- `src/components` - Reusable React components
+- `src/lib` - Utility libraries and clients
+
+## Features
+
+- [Feature 1] - Description
+- [Feature 2] - Description
+
+## Documentation
+
+- [Setup Guide](docs/GUIDES/setup.md)
+- [API Reference](docs/GUIDES/api.md)
+- [Architecture](docs/CODEMAPS/INDEX.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+```
+
+## Scripts to Power Documentation
+
+### scripts/codemaps/generate.ts
+```typescript
+/**
+ * Generate codemaps from repository structure
+ * Usage: tsx scripts/codemaps/generate.ts
+ */
+
+import { Project } from 'ts-morph'
+import * as fs from 'fs'
+import * as path from 'path'
+
+async function generateCodemaps() {
+  const project = new Project({
+    tsConfigFilePath: 'tsconfig.json',
+  })
+
+  // 1. Discover all source files
+  const sourceFiles = project.getSourceFiles('src/**/*.{ts,tsx}')
+
+  // 2. Build import/export graph
+  const graph = buildDependencyGraph(sourceFiles)
+
+  // 3. Detect entrypoints (pages, API routes)
+  const entrypoints = findEntrypoints(sourceFiles)
+
+  // 4. Generate codemaps
+  await generateFrontendMap(graph, entrypoints)
+  await generateBackendMap(graph, entrypoints)
+  await generateIntegrationsMap(graph)
+
+  // 5. Generate index
+  await generateIndex()
+}
+
+function buildDependencyGraph(files: SourceFile[]) {
+  // Map imports/exports between files
+  // Return graph structure
+}
+
+function findEntrypoints(files: SourceFile[]) {
+  // Identify pages, API routes, entry files
+  // Return list of entrypoints
+}
+```
+
+### scripts/docs/update.ts
+```typescript
+/**
+ * Update documentation from code
+ * Usage: tsx scripts/docs/update.ts
+ */
+
+import * as fs from 'fs'
+import { execSync } from 'child_process'
+
+async function updateDocs() {
+  // 1. Read codemaps
+  const codemaps = readCodemaps()
+
+  // 2. Extract JSDoc/TSDoc
+  const apiDocs = extractJSDoc('src/**/*.ts')
+
+  // 3. Update README.md
+  await updateReadme(codemaps, apiDocs)
+
+  // 4. Update guides
+  await updateGuides(codemaps)
+
+  // 5. Generate API reference
+  await generateAPIReference(apiDocs)
+}
+
+function extractJSDoc(pattern: string) {
+  // Use jsdoc-to-markdown or similar
+  // Extract documentation from source
+}
+```
+
+## Pull Request Template
+
+When opening PR with documentation updates:
+
+```markdown
+## Docs: Update Codemaps and Documentation
+
+### Summary
+Regenerated codemaps and updated documentation to reflect current codebase state.
+
+### Changes
+- Updated docs/CODEMAPS/* from current code structure
+- Refreshed README.md with latest setup instructions
+- Updated docs/GUIDES/* with current API endpoints
+- Added X new modules to codemaps
+- Removed Y obsolete documentation sections
+
+### Generated Files
+- docs/CODEMAPS/INDEX.md
+- docs/CODEMAPS/frontend.md
+- docs/CODEMAPS/backend.md
+- docs/CODEMAPS/integrations.md
+
+### Verification
+- [x] All links in docs work
+- [x] Code examples are current
+- [x] Architecture diagrams match reality
+- [x] No obsolete references
+
+### Impact
+🟢 LOW - Documentation only, no code changes
+
+See docs/CODEMAPS/INDEX.md for complete architecture overview.
+```
+
+## Maintenance Schedule
+
+**Weekly:**
+- Check for new files in src/ not in codemaps
+- Verify README.md instructions work
+- Update package.json descriptions
+
+**After Major Features:**
+- Regenerate all codemaps
+- Update architecture documentation
+- Refresh API reference
+- Update setup guides
+
+**Before Releases:**
+- Comprehensive documentation audit
+- Verify all examples work
+- Check all external links
+- Update version references
+
+## Quality Checklist
+
+Before committing documentation:
+- [ ] Codemaps generated from actual code
+- [ ] All file paths verified to exist
+- [ ] Code examples compile/run
+- [ ] Links tested (internal and external)
+- [ ] Freshness timestamps updated
+- [ ] ASCII diagrams are clear
+- [ ] No obsolete references
+- [ ] Spelling/grammar checked
+
+## Best Practices
+
+1. **Single Source of Truth** - Generate from code, don't manually write
+2. **Freshness Timestamps** - Always include last updated date
+3. **Token Efficiency** - Keep codemaps under 500 lines each
+4. **Clear Structure** - Use consistent markdown formatting
+5. **Actionable** - Include setup commands that actually work
+6. **Linked** - Cross-reference related documentation
+7. **Examples** - Show real working code snippets
+8. **Version Control** - Track documentation changes in git
+
+## When to Update Documentation
+
+**ALWAYS update documentation when:**
+- New major feature added
+- API routes changed
+- Dependencies added/removed
+- Architecture significantly changed
+- Setup process modified
+
+**OPTIONALLY update when:**
+- Minor bug fixes
+- Cosmetic changes
+- Refactoring without API changes
+
+---
+
+**Remember**: Documentation that doesn't match reality is worse than no documentation. Always generate from source of truth (the actual code).

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

@@ -0,0 +1,216 @@
+---
+name: docker
+description: Docker Skill
+---
+
+# Docker Skill
+
+容器化最佳实践和 Docker 配置规范。
+
+## Dockerfile 最佳实践
+
+### 多阶段构建
+```dockerfile
+# 构建阶段
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+
+# 运行阶段
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+# 非 root 用户运行
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 appuser
+
+COPY --from=builder --chown=appuser:nodejs /app/dist ./dist
+COPY --from=builder --chown=appuser:nodejs /app/node_modules ./node_modules
+
+USER appuser
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+### 层缓存优化
+```dockerfile
+# ✅ 依赖文件先复制，利用缓存
+COPY package*.json ./
+RUN npm ci
+
+# 源码后复制
+COPY . .
+RUN npm run build
+
+# ❌ 避免这样写
+COPY . .
+RUN npm ci && npm run build
+```
+
+### 镜像精简
+```dockerfile
+# 使用 Alpine 基础镜像
+FROM python:3.11-alpine
+
+# 清理缓存
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 合并 RUN 命令
+RUN apk add --no-cache \
+    gcc \
+    musl-dev \
+    && pip install --no-cache-dir -r requirements.txt \
+    && apk del gcc musl-dev
+```
+
+## Docker Compose
+
+### 开发环境配置
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - .:/app
+      - /app/node_modules
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+    depends_on:
+      - db
+      - redis
+
+  db:
+    image: postgres:15-alpine
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: ${DB_USER}
+      POSTGRES_PASSWORD: ${DB_PASSWORD}
+      POSTGRES_DB: ${DB_NAME}
+    ports:
+      - "5432:5432"
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+  redis_data:
+```
+
+### 生产环境配置
+```yaml
+version: '3.8'
+
+services:
+  app:
+    image: myapp:${VERSION:-latest}
+    restart: always
+    deploy:
+      replicas: 2
+      resources:
+        limits:
+          cpus: '0.5'
+          memory: 512M
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## 安全配置
+
+### 非 root 用户
+```dockerfile
+# 创建专用用户
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+USER appuser
+```
+
+### 只读文件系统
+```yaml
+services:
+  app:
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /var/run
+```
+
+### 敏感信息管理
+```yaml
+# 使用 secrets
+services:
+  app:
+    secrets:
+      - db_password
+      - api_key
+
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+  api_key:
+    external: true
+```
+
+## .dockerignore
+```
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.*
+Dockerfile*
+docker-compose*
+README.md
+.vscode
+.idea
+coverage
+dist
+build
+*.log
+```
+
+## 常用命令
+
+```bash
+# 构建镜像
+docker build -t myapp:v1.0 .
+
+# 查看镜像层
+docker history myapp:v1.0
+
+# 清理未使用资源
+docker system prune -a
+
+# 查看容器日志
+docker logs -f --tail 100 container_name
+
+# 进入容器调试
+docker exec -it container_name sh
+
+# 导出镜像
+docker save myapp:v1.0 | gzip > myapp-v1.0.tar.gz
+```
+