248 lines
9.5 KiB
Markdown
248 lines
9.5 KiB
Markdown
# PROJECT KNOWLEDGE BASE
|
|
|
|
**Generated:** 2026-03-08
|
|
**Updated:** 2026-03-08 (SEO Multi-Channel Skills Added)
|
|
**Type:** OpenCode Skills Collection - PDPA-Compliant Website Generator with Auto-Deploy + SEO Multi-Channel Marketing
|
|
|
|
---
|
|
|
|
## OVERVIEW
|
|
|
|
Personal collection of OpenCode skills for AI-powered terminal coding assistant. **INCLUDES:**
|
|
|
|
### **Core Features:**
|
|
- ✅ **Auto-deploy system** - Gitea + Easypanel integration
|
|
- ✅ **Unified credentials** - Single .env for all skills
|
|
- ✅ **PDPA compliance** - Thai law-compliant websites
|
|
- ✅ **Image skills** - Python scripts wrapping Chutes AI APIs
|
|
- ✅ **Deployment automation** - Easypanel integration
|
|
|
|
### **NEW: SEO Multi-Channel Marketing (2026-03-08):**
|
|
- ✅ **Multi-channel content** - Facebook, Facebook Ads, Google Ads, Blog, X/Twitter
|
|
- ✅ **Thai language support** - Full PyThaiNLP integration
|
|
- ✅ **Analytics integration** - Umami, GA4, GSC, DataForSEO
|
|
- ✅ **Image integration** - Auto-generate/edit images for content
|
|
- ✅ **Auto-publish** - Direct write to Astro content collections
|
|
|
|
---
|
|
|
|
## STRUCTURE
|
|
|
|
```
|
|
opencode-skill/
|
|
├── .env.example # Unified credentials template (ALL skills)
|
|
├── .env # ⚠️ Gitignored - contains actual credentials
|
|
├── scripts/
|
|
│ └── install-skills.sh # Auto-updated for unified .env
|
|
└── skills/
|
|
# Website & Deployment
|
|
├── gitea-sync/ # Auto-create Gitea repos & push code
|
|
├── easypanel-deploy/ # Full Python implementation
|
|
└── website-creator/ # Astro builder with auto-deploy
|
|
|
|
# Image Skills
|
|
├── image-analyze/ # Vision AI analysis
|
|
├── image-edit/ # AI image editing
|
|
└── image-generation/ # Text-to-image generation
|
|
|
|
# SEO Multi-Channel Marketing (NEW)
|
|
├── seo-multi-channel/ # Generate content for Facebook, Ads, Blog, X
|
|
├── seo-analyzers/ # Thai keyword density, readability, quality scoring
|
|
├── seo-data/ # Analytics: Umami, GA4, GSC, DataForSEO
|
|
├── seo-context/ # Per-project context file management
|
|
└── umami/ # Umami Analytics integration (username/password auth)
|
|
|
|
# Utility
|
|
└── skill-creator/ # Scaffold new skills
|
|
```
|
|
|
|
## WHERE TO LOOK
|
|
|
|
| Task | Location | Notes |
|
|
|------|----------|-------|
|
|
| Install all skills | `scripts/install-skills.sh` | Uses unified .env, copies to `~/.config/opencode/` |
|
|
| Add new skill | `skills/skill-creator/` | Use create_skill.py to scaffold |
|
|
| Generate website (AUTO-DEPLOY) | `skills/website-creator/scripts/create_astro_website.py` | ✅ Auto-syncs to Gitea, auto-deploys to Easypanel |
|
|
| Sync to Gitea (standalone) | `skills/gitea-sync/scripts/sync.py` | Create/update repos, push code |
|
|
| Deploy to Easypanel (standalone) | `skills/easypanel-deploy/scripts/deploy.py` | Uses username/password auth |
|
|
| Image generation | `skills/image-generation/scripts/image_gen.py` | Chutes AI wrapper |
|
|
| Image editing | `skills/image-edit/scripts/image_edit.py` | Chutes AI wrapper |
|
|
| Image analysis | `skills/image-analyze/scripts/analyze_image.py` | Vision AI |
|
|
| **SEO Multi-Channel** | `skills/seo-multi-channel/scripts/generate_content.py` | ✅ Facebook, Ads, Blog, X |
|
|
| **SEO Analytics** | `skills/seo-data/scripts/data_aggregator.py` | ✅ Umami, GA4, GSC, DataForSEO |
|
|
| **SEO Analysis** | `skills/seo-analyzers/scripts/` | ✅ Thai keyword, readability, quality |
|
|
| **SEO Context** | `skills/seo-context/scripts/context_manager.py` | ✅ Per-project config |
|
|
| **Umami Integration** | `skills/umami/scripts/umami_client.py` | ✅ Username/password auth |
|
|
| Unified credentials | `.env` (repo root) | Contains Gitea + Easypanel + other credentials |
|
|
| API documentation | `skills/*/API_ENDPOINTS.md` | Extracted from OpenAPI specs |
|
|
|
|
## SKILL PATTERN
|
|
|
|
Each skill follows this structure:
|
|
|
|
```
|
|
skills/<name>/
|
|
├── SKILL.md # Required: YAML frontmatter + docs
|
|
└── scripts/
|
|
├── <name>.py # Main executable script
|
|
├── .env # API credentials (gitignored)
|
|
├── .env.example # Template for credentials
|
|
└── requirements.txt # Python deps (usually just requests)
|
|
```
|
|
|
|
**SKILL.md Frontmatter:**
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: Brief description. Use when user wants to [action].
|
|
---
|
|
```
|
|
|
|
## CONVENTIONS
|
|
|
|
### Credential Management (UPDATED 2026-03-08)
|
|
- **Unified .env:** Single file at repo root (`/.env`)
|
|
- **Copied to:** `~/.config/opencode/.env` on install
|
|
- **Contains:** Gitea, Easypanel, and all skill credentials
|
|
- **Per-website config:** Umami credentials in each website's `.env` (not global)
|
|
- **NEVER commit:** `.env` files are gitignored
|
|
|
|
### Skill Naming
|
|
- lowercase, hyphens only, 1-64 chars, no consecutive hyphens
|
|
|
|
### Env Loading
|
|
- Unified .env loaded from `~/.config/opencode/.env` (production)
|
|
- Each skill can also load from own directory (development)
|
|
|
|
### Output Format
|
|
- `Result: filename [id]` to stdout, `Error: message` to stderr
|
|
|
|
### Images
|
|
- Saved locally as PNG/JPG, never returned as base64 (memory)
|
|
|
|
### Script Pattern
|
|
- All Python scripts use `#!/usr/bin/env python3`
|
|
- Load `.env` from same directory (or unified .env)
|
|
- Use `argparse` for CLI
|
|
|
|
### API Handling
|
|
- Check `Content-Type` header — binary image OR JSON with base64
|
|
|
|
### Credential Safety
|
|
- Chutes API: `CHUTES_API_TOKEN` environment variable
|
|
- Gitea: `GITEA_API_TOKEN`, `GITEA_USERNAME`, `GITEA_URL`
|
|
- Easypanel: `EASYPANEL_USERNAME`, `EASYPANEL_PASSWORD` (auto-generates session token)
|
|
- All loaded from `.env` (gitignored)
|
|
## ANTI-PATTERNS
|
|
|
|
- **NEVER** commit `.env` files (credentials)
|
|
- **NEVER** return images as base64 in context (save to file instead)
|
|
- **NEVER** use data URI prefix for base64 when API expects plain base64
|
|
- **NEVER** hardcode credentials in scripts (always use .env)
|
|
- **NEVER** skip error handling in auto-deploy workflows
|
|
- **NEVER** use old separate .env files (use unified .env only)
|
|
|
|
## UNIQUE STYLES
|
|
|
|
### Auto-Deploy System (NEW 2026-03-08)
|
|
- **Always on:** website-creator auto-deploys by default (no flag needed)
|
|
- **Gitea sync:** Creates/updates repos, pushes code automatically
|
|
- **Easypanel deploy:** Uses username/password → auto-generates session token
|
|
- **Monitoring:** Checks deployment status 3 times
|
|
- **Auto-fix:** Triggers redeploy if deployment fails
|
|
- **Output:** Returns both Gitea repo URL and Easypanel deployment URL
|
|
|
|
### Unified Credentials (NEW 2026-03-08)
|
|
- Single `/.env` file for ALL skills
|
|
- install-skills.sh prompts once, copies to `~/.config/opencode/.env`
|
|
- Skills read from unified .env in production
|
|
|
|
### API Integration Style
|
|
- **Easypanel:** Uses tRPC format `POST /api/trpc/endpoint` with `{"json": {...}}`
|
|
- **Gitea:** Standard REST API with token auth
|
|
- **Authentication:** Extract session tokens, use Bearer in Authorization header
|
|
|
|
### Binary Response Handling
|
|
- Check `Content-Type` header - API may return raw binary OR JSON with base64
|
|
|
|
### Chutes API
|
|
- All image skills use `CHUTES_API_TOKEN` environment variable
|
|
|
|
### Skill Categories
|
|
- **Full implementation:** gitea-sync, easypanel-deploy, website-creator, image-*
|
|
- **Docs-only:** None (all skills now have scripts)
|
|
|
|
## COMMANDS
|
|
|
|
### Website Generation (with Auto-Deploy)
|
|
```bash
|
|
# Generate website - automatically syncs to Gitea and deploys to Easypanel
|
|
python3 skills/website-creator/scripts/create_astro_website.py \
|
|
--name "my-website" \
|
|
--output "./my-website"
|
|
```
|
|
|
|
### Standalone Operations
|
|
```bash
|
|
# Install all skills (uses unified .env)
|
|
./scripts/install-skills.sh
|
|
|
|
# Create new skill
|
|
python3 skills/skill-creator/scripts/create_skill.py my-skill "Description here"
|
|
|
|
# Sync existing code to Gitea
|
|
python3 skills/gitea-sync/scripts/sync.py \
|
|
--repo my-repo \
|
|
--path ./my-code
|
|
|
|
# Deploy to Easypanel
|
|
python3 skills/easypanel-deploy/scripts/deploy.py \
|
|
--project my-project \
|
|
--service my-service \
|
|
--git-url https://git.moreminimore.com/user/repo.git
|
|
|
|
# Generate image
|
|
python3 skills/image-generation/scripts/image_gen.py "prompt here"
|
|
|
|
# Edit image
|
|
python3 skills/image-edit/scripts/image_edit.py "edit prompt" image.jpg
|
|
|
|
# Analyze image
|
|
python3 skills/image-analyze/scripts/analyze_image.py image.jpg "Describe this"
|
|
```
|
|
|
|
## NOTES
|
|
|
|
### Project Structure
|
|
- No package.json, tsconfig, or linter configs - pure Python project
|
|
- `.ruff_cache/` present (Python linter cache)
|
|
|
|
### Skill Installation
|
|
- Skills install to `~/.config/opencode/skills/` (global) or `./.opencode/skills/` (project)
|
|
- Unified .env copied to `~/.config/opencode/.env`
|
|
- install-skills.sh handles unified credentials
|
|
|
|
### Development vs Production
|
|
- **Development:** Scripts load .env from own directory
|
|
- **Production:** Scripts load from `~/.config/opencode/.env`
|
|
|
|
### Auto-Deploy Workflow
|
|
1. Generate website → 2. Sync to Gitea → 3. Deploy to Easypanel → 4. Monitor → 5. Auto-fix if needed
|
|
|
|
### API Endpoints
|
|
- **Easypanel:** https://panelwebsite.moreminimore.com/api/openapi.json
|
|
- **Gitea:** https://git.moreminimore.com/api/v1
|
|
- See `skills/*/API_ENDPOINTS.md` for detailed documentation
|
|
|
|
### Testing
|
|
- No formal test suite - scripts are simple wrappers around API calls
|
|
- Manual testing: Run script with --help to verify it loads
|
|
- All scripts tested on 2026-03-08 (13/13 tests passed)
|
|
|
|
### LSP Errors
|
|
- Some Python scripts show LSP errors (TypeScript in f-strings)
|
|
- These are false positives - scripts run correctly
|
|
- Ignore LSP warnings about backticks and unbound variables in try/except blocks
|
|
|
|
### No `__init__.py` Files
|
|
- Scripts are standalone CLI tools, not importable packages |