kunthawat/opencode-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

Cleanup: remove old status files, update AGENTS.md and README

Browse Source
This commit is contained in:
Kunthawat Greethong
2026-03-27 17:35:25 +07:00
parent a5fef9dbdc
commit 4e92ef953b
29 changed files with 103 additions and 7016 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
AGENTS.md
View File

@@ -1,20 +1,20 @@
# PROJECT KNOWLEDGE BASE
**Generated:** 2026-03-08
**Updated:** 2026-03-10 (Smart Migration + Dockerfile Fixes)
**Type:** OpenCode Skills Collection - PDPA-Compliant Website Generator with Auto-Deploy + SEO Multi-Channel Marketing
**Updated:** 2026-03-27 (AlphaEar Finance + Cleanup)
**Type:** OpenCode Skills Collection - Website Generator + SEO + Finance AI
---
## OVERVIEW
Personal collection of OpenCode skills for AI-powered terminal coding assistant. **INCLUDES:**
Personal collection of OpenCode skills for AI-powered terminal coding assistant. **60 SKILLS TOTAL.**
### **Core Features:**
- ✅ **Auto-deploy system** - Gitea + Easypanel integration (Dockerfile)
- ✅ **Unified credentials** - Single .env for all skills
- ✅ **PDPA compliance** - Thai law-compliant websites with legal templates
- ✅ **Image skills** - Python scripts wrapping Chutes AI APIs
- ✅ **MiniMax API** - TTS, Music, Video, Image generation
- ✅ **Deployment automation** - Easypanel with Docker containers
- ✅ **Working cookie consent** - Actually blocks/enables cookies based on user choice
@@ -23,26 +23,17 @@ Personal collection of OpenCode skills for AI-powered terminal coding assistant.
- ✅ **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
### **Latest Updates (2026-03-10):**
- ✅ **Smart Migration Workflow** - Detect, Plan, Preserve, Convert, Rebuild, Enhance, Test
- ✅ **Tech Stack Detection** - Auto-detects Astro, Tailwind, CSS frameworks
- ✅ **Migration Planning** - Risk assessment before migration
- ✅ **Content Preservation** - Keeps ALL inline CSS and content exactly
- ✅ **Dockerfile** - Uses npm install (not npm ci), port 80 only
- ✅ **Website Creator** - Reverted to Dockerfile deployment
- ✅ **Thai Legal Templates** - PDPA-compliant Privacy Policy & Terms of Service
- ✅ **Cookie Consent** - Working implementation (blocks cookies until consent)
- ✅ **Template Structure** - Consistent structure for all websites
- ✅ **Build Testing** - Test build before deployment
### **Previous Updates (2026-03-09):**
- ✅ **Website Creator** - Reverted to Dockerfile deployment
- ✅ **Thai Legal Templates** - PDPA-compliant Privacy Policy & Terms of Service
- ✅ **Cookie Consent** - Working implementation (blocks cookies until consent)
- ✅ **Template Structure** - Consistent structure for all websites
- ✅ **Build Testing** - Test build before deployment
### **Finance AI (AlphaEar):**
- ✅ **alphaear-news** - Real-time finance news (10+ sources)
- ✅ **alphaear-stock** - A-Share/HK/US stock data
- ✅ **alphaear-sentiment** - FinBERT/LLM sentiment analysis
- ✅ **alphaear-predictor** - Kronos time-series forecasting
- ✅ **alphaear-signal-tracker** - Signal evolution tracking
- ✅ **alphaear-logic-visualizer** - Draw.io XML finance diagrams
- ✅ **alphaear-reporter** - Professional financial reports
- ✅ **alphaear-search** - Web search + local RAG
- ✅ **alphaear-deepear-lite** - DeepEar Lite API integration
---
@@ -52,284 +43,105 @@ Personal collection of OpenCode skills for AI-powered terminal coding assistant.
opencode-skill/
├── .env.example # Unified credentials template (ALL skills)
├── .env # ⚠️ Gitignored - contains actual credentials
├── README.md # Quick start guide
├── AGENTS.md # This file
├── scripts/
│ └── install-skills.sh # Auto-updated for unified .env
└── skills/
│ └── install-skills.sh # Installs skills to ~/.config/opencode/
└── skills/ # 60 skills total
# Website & Deployment
├── gitea-sync/ # Auto-create Gitea repos & push code
├── easypanel-deploy/ # Full Python implementation
└── website-creator/ # Astro builder with auto-deploy
├── easypanel-deploy/ # Full Python implementation
└── thai-frontend-dev/ # Astro builder with PDPA templates
# 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)
# SEO Multi-Channel
├── seo-master/ # Master SEO skill (merged)
├── seo-multi-channel/ # Generate content for Facebook, Ads, Blog, X
├── seo-analyzers/ # Thai keyword, readability, quality
├── seo-data/ # Analytics: Umami, GA4, GSC, DataForSEO
├── seo-context/ # Per-project context file management
├── seo-geo/ # AI search optimization
└── umami/ # Umami Analytics integration
# Utility
└── skill-creator/ # Scaffold new skills
# Finance AI (AlphaEar)
├── alphaear-news/ # Real-time finance news
├── alphaear-stock/ # A-Share/HK/US stock data
├── alphaear-sentiment/ # FinBERT/LLM sentiment
├── alphaear-predictor/ # Kronos forecasting
├── alphaear-signal-tracker/
├── alphaear-logic-visualizer/
├── alphaear-reporter/
├── alphaear-search/
└── alphaear-deepear-lite/
# Development Skills
├── frontend-dev/ # Full-stack frontend
├── fullstack-dev/ # Backend + frontend
├── android-native-dev/ # Android development
├── ios-application-dev/ # iOS development
├── skill-creator/ # Scaffold new skills
├── testing-master/ # TDD, E2E, Playwright
├── testing-patterns/ # JS/Python testing patterns
├── security-auditor/ # Vulnerability scanning
├── security-coder/ # Secure coding
├── pentesting/ # SQL injection, SSRF, etc.
├── architecture/ # C4, ADRs, system design
├── backend-architect/ # API design, microservices
├── database-architect/ # Schema modeling
└── ... (30+ more 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 |
| **Migrate Existing Website** | `skills/website-creator/scripts/migrate_existing_website.py` | ✅ Smart migration with tech detection |
| **Website Templates** | `skills/website-creator/scripts/templates/` | ✅ Thai legal templates, cookie consent |
| 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 (Dockerfile) |
| **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].
## CREDENTIALS
### Required
| Variable | Description |
|----------|-------------|
| `MINIMAX_API_KEY` | TTS, Music, Video, Image generation |
### Optional
| Variable | Description |
|----------|-------------|
| `GITEA_*` | Git sync features |
| `EASYPANEL_*` | Auto-deployment |
| `UMAMI_*` | Analytics |
| `GA4_*`, `GSC_*` | Google analytics |
| `DATAFORSEO_*` | Competitor analysis |
| `JINA_API_KEY` | Content extraction (free tier: 20 req/min without key) |
| `LLM_*` | AlphaEar LLM config (MiniMax default) |
---
```
## 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
- MiniMax API: `MINIMAX_API_KEY` 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
- **Build method:** Dockerfile (npm install, port 80 only)
### Thai Legal Compliance (NEW 2026-03-09)
- **Privacy Policy:** PDPA-compliant template (Thai Personal Data Protection Act)
- **Terms of Service:** Thai Consumer Protection Act compliant
- **Cookie Consent:** Actually blocks cookies until user consent
- **Consent Logging:** Database tracks user consent choices
- **DPO Requirements:** Template includes DPO contact section
- **PDPC Complaints:** Template includes complaint procedures
### Smart Migration Workflow (NEW 2026-03-10)
For migrating existing websites safely:
1. **DETECT** - Auto-detects tech stack (Astro, Tailwind, CSS)
2. **PLAN** - Creates detailed migration plan with risks
3. **PRESERVE** - Keeps ALL inline CSS and content exactly
4. **CONVERT** - Converts CSS frameworks (Tailwind v3→v4)
5. **REBUILD** - Fresh Astro install with preserved content
6. **ENHANCE** - Adds new features (cookie consent, PDPA)
7. **TEST** - Comprehensive testing before deployment
**Usage:**
```bash
# Create migration plan first
python3 skills/website-creator/scripts/migrate_existing_website.py \
--input "./existing-website" \
--output "./migrated-website" \
--plan-only
# Review plan, then proceed with migration
python3 skills/website-creator/scripts/migrate_existing_website.py \
--input "./existing-website" \
--output "./migrated-website"
```
**Benefits:**
- ✅ No more broken CSS
- ✅ No more failed deployments
- ✅ All inline styles preserved
- ✅ All routes preserved
- ✅ Plan before migrating (safe!)
### 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
### MiniMax API
- TTS, Music, Video, Image generation use `MINIMAX_API_KEY` environment variable
### Skill Categories
- **Full implementation:** gitea-sync, easypanel-deploy, thai-frontend-dev, minimax-*
- **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
# Uses Dockerfile for deployment (not nixpacks)
# Includes: PDPA templates, cookie consent, build testing
python3 skills/website-creator/scripts/create_astro_website.py \
--name "my-website" \
--output "./my-website"
```
### Website Templates
```bash
# Legal templates (Thai law compliant):
skills/website-creator/scripts/templates/
├── thai-privacy-policy-template.md # PDPA-compliant privacy policy
├── thai-terms-of-service-template.md # Thai Consumer Protection Act
└── admin-consent-logs.astro # Cookie consent tracker
```
### Testing Requirements
Before deployment, the skill tests:
1. ✅ Docker build process
2. ✅ Cookie consent functionality (actually blocks cookies)
3. ✅ Legal page accessibility
4. ✅ Backend features (forms, databases)
5. ✅ Mobile responsiveness
### Standalone Operations
```bash
# Install all skills (uses unified .env)
# Install all skills
./scripts/install-skills.sh
# Create new skill
python3 skills/skill-creator/scripts/create_skill.py my-skill "Description here"
python3 skills/skill-creator/scripts/create_skill.py my-skill "Description"
# Sync existing code to Gitea
python3 skills/gitea-sync/scripts/sync.py \
--repo my-repo \
--path ./my-code
# Generate website (auto-deploys)
python3 skills/thai-frontend-dev/scripts/create_astro_website.py --name "my-site"
# 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
python3 skills/easypanel-deploy/scripts/deploy.py --project x --service y --git-url z
```
---
## ANTI-PATTERNS
- **NEVER** commit `.env` files
- **NEVER** return images as base64 (save to file)
- **NEVER** hardcode credentials (use .env)
- **NEVER** skip error handling in deploy workflows
---
## 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
### Cookie Consent Implementation (NEW 2026-03-09)
- **Real functionality:** Cookies are actually blocked until user consents
- **Granular control:** User can accept/reject necessary, performance, marketing cookies
- **Consent logging:** All consent choices logged in Astro DB
- **No pre-consent tracking:** Analytics scripts don't load until accepted
- **Respects choice:** User preference saved across sessions
### Testing
- Manual testing: Run script with --help to verify it loads
- All scripts tested on 2026-03-08 (13/13 tests passed)
- Build testing: Docker build tested before deployment
- Cookie consent: Tested to verify cookies are blocked
- Legal compliance: Templates reviewed for PDPA compliance
### 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
## ✅ IMPLEMENTATION STATUS
**All Skills Complete:**
- ✅ website-creator (Dockerfile, PDPA templates, cookie consent)
- ✅ seo-multi-channel (5 channels, Thai support)
- ✅ seo-analyzers (Thai keyword, readability, quality)
- ✅ seo-data (GA4, GSC, DataForSEO, Umami)
- ✅ seo-context (Per-project config)
- ✅ umami (Username/password auth)
- ✅ All image skills (generation, edit, analyze)
- ✅ gitea-sync, easypanel-deploy, skill-creator
**100% Production Ready!** 🎉
- All 60 skills have scripts (no docs-only skills)
- AlphaEar skills use MiniMax by default (OpenAI compatible)
- Embedding models run offline (no API calls)
- Jina content extraction works without API key (rate limited)