my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	# 🔄 Complete Development Workflow
#2
#3	> Comprehensive guide to the entire agent lifecycle: from creation → translation → build → deployment
#4
#5	---
#6
#7	## 📋 Table of Contents
#8
#9	- [Overview](#overview)
#10	- [Quick Reference](#quick-reference)
#11	- [Architecture](#architecture)
#12	- [Full Workflow](#full-workflow)
#13	- [Local Development](#local-development)
#14	- [CI/CD Pipeline](#cicd-pipeline)
#15	- [Domain Management](#domain-management)
#16	- [For Contributors](#for-contributors)
#17	- [For Fork Maintainers](#for-fork-maintainers)
#18
#19	---
#20
#21	## Overview
#22
#23	This repository uses an automated workflow that takes agent definitions and:
#24
#25	1. ✅ Translates them to 18 languages
#26	2. ✅ Builds a CDN-ready index
#27	3. ✅ Deploys to GitHub Pages
#28	4. ✅ Preserves custom domains automatically
#29
#30	Key Principle: Submit in English, everything else is automatic.
#31
#32	---
#33
#34	## Quick Reference
#35
#36	### For Contributors
#37
#38	```bash
#39	# 1. Create agent
#40	echo '{ ... }' > src/my-agent.json
#41
#42	# 2. Submit PR
#43	git add src/my-agent.json
#44	git commit -m "feat: Add My Agent"
#45	git push
#46
#47	# Done! CI handles translation + deployment
#48	```
#49
#50	### For Maintainers
#51
#52	```bash
#53	# Setup
#54	git clone https://github.com/yourusername/defi-agents
#55	cd defi-agents
#56	bun install
#57	echo "OPENAI_API_KEY=sk-xxx" > .env
#58
#59	# Development cycle
#60	bun run format # Translate agents
#61	bun run build # Build public index
#62	bun run test # Validate everything
#63
#64	# Deploy (automatic on push to main)
#65	git push origin main
#66	```
#67
#68	---
#69
#70	## Architecture
#71
#72	### Directory Structure
#73
#74	```
#75	defi-agents/
#76	├── CNAME # Your custom domain (optional)
#77	├── .env # Local environment variables (gitignored)
#78	│ └── OPENAI_API_KEY=sk-xxx
#79	│
#80	├── src/ # 📝 Agent source files (English only)
#81	│ ├── agent-1.json
#82	│ ├── agent-2.json
#83	│ └── clawd-dashboard.json
#84	│
#85	├── locales/ # 🌍 18-language translations (auto-generated)
#86	│ ├── agent-1/
#87	│ │ ├── index.json # en-US (default)
#88	│ │ ├── index.zh-CN.json # Chinese
#89	│ │ ├── index.es-ES.json # Spanish
#90	│ │ └── ... (18 total)
#91	│ └── agent-2/
#92	│ └── ... (18 files)
#93	│
#94	├── public/ # 🚀 Build output (gitignored, generated)
#95	│ ├── CNAME # Copied from root during build
#96	│ ├── index.json # Main agent index
#97	│ ├── index.zh-CN.json # Localized indexes
#98	│ ├── agent-1.json # Individual agents
#99	│ ├── agent-1.zh-CN.json # Localized agents
#100	│ └── schema/
#101	│ └── clawdAgentSchema_v1.json
#102	│
#103	├── .github/workflows/
#104	│ └── release.yml # CI/CD automation
#105	│
#106	└── scripts/
#107	├── commands/
#108	│ ├── format.ts # Translation engine
#109	│ └── build.ts # Build engine
#110	└── builders/
#111	└── agent-builder.ts # Includes CNAME copy logic
#112	```
#113
#114	### Data Flow
#115
#116	```
#117	┌─────────────────────────────────────────────────────────────┐
#118	│ DEVELOPMENT CYCLE │
#119	└─────────────────────────────────────────────────────────────┘
#120
#121	1. CREATE AGENT
#122	└─ Write src/agent-name.json (English only)
#123
#124	2. TRANSLATE (bun run format)
#125	├─ Validate JSON schema
#126	├─ Generate missing fields (category, examples)
#127	├─ Call OpenAI API (GPT-4)
#128	├─ Translate to 18 languages
#129	└─ Create locales/agent-name/*.json (18 files)
#130
#131	3. BUILD (bun run build)
#132	├─ Merge src + locales
#133	├─ Generate public index files
#134	├─ Copy CNAME to public/ (if exists)
#135	└─ Create CDN-ready distribution
#136
#137	4. DEPLOY (automatic on push)
#138	├─ GitHub Actions triggers
#139	├─ Runs format → build
#140	├─ Deploys public/ to gh-pages branch
#141	└─ GitHub Pages serves at your domain
#142
#143	┌─────────────────────────────────────────────────────────────┐
#144	│ LIVE WEBSITE │
#145	└─────────────────────────────────────────────────────────────┘
#146	https://yourdomain.com/index.json
#147	└─ Agents available in 18 languages
#148	```
#149
#150	---
#151
#152	## Full Workflow
#153
#154	### Step 1: Create Agent Source
#155
#156	Create a new agent in `src/`:
#157
#158	```bash
#159	# Create agent file
#160	touch src/my-defi-agent.json
#161	```
#162
#163	```json
#164	{
#165	"author": "your-github-username",
#166	"config": {
#167	"systemRole": "You are a DeFi expert specializing in...",
#168	"openingMessage": "Hello! I can help you with...",
#169	"openingQuestions": ["What's the best yield strategy?", "How do I minimize impermanent loss?"]
#170	},
#171	"createdAt": "2024-12-21",
#172	"examples": [
#173	{
#174	"role": "user",
#175	"content": "Explain DeFi yield farming"
#176	},
#177	{
#178	"role": "assistant",
#179	"content": "Yield farming is..."
#180	}
#181	],
#182	"homepage": "https://github.com/nirholas/AI-Agents-Library",
#183	"identifier": "my-defi-agent",
#184	"meta": {
#185	"title": "My DeFi Agent",
#186	"description": "Expert DeFi advisor for yield optimization",
#187	"avatar": "🌾",
#188	"tags": ["defi", "yield", "optimization"],
#189	"category": "trading"
#190	},
#191	"schemaVersion": 1
#192	}
#193	```
#194
#195	### Step 2: Run Translation
#196
#197	```bash
#198	# Set API key (first time only)
#199	echo "OPENAI_API_KEY=sk-your-key" > .env
#200
#201	# Run translation
#202	bun run format
#203	```
#204
#205	What happens:
#206
#207	- ✅ Validates JSON structure
#208	- ✅ Calls OpenAI GPT-4 for translation
#209	- ✅ Creates `locales/my-defi-agent/` with 18 files
#210	- ✅ Takes \~2-5 minutes depending on agent complexity
#211
#212	Output:
#213
#214	```
#215	locales/
#216	my-defi-agent/
#217	├── index.json # en-US (default)
#218	├── index.ar.json # Arabic
#219	├── index.zh-CN.json # Simplified Chinese
#220	└── ... (18 total)
#221	```
#222
#223	### Step 3: Build Public Index
#224
#225	```bash
#226	bun run build
#227	```
#228
#229	What happens:
#230
#231	- ✅ Merges `src/` + `locales/`
#232	- ✅ Generates `public/index.json` with all agents
#233	- ✅ Creates localized indexes (index.zh-CN.json, etc.)
#234	- ✅ Copies CNAME from root to public/ (if exists)
#235	- ✅ Generates schema files
#236
#237	Output:
#238
#239	```
#240	public/
#241	├── CNAME # Your custom domain
#242	├── index.json # Main index (en-US)
#243	├── index.zh-CN.json # Chinese index
#244	├── my-defi-agent.json # Your agent (en-US)
#245	├── my-defi-agent.zh-CN.json # Your agent (Chinese)
#246	└── ... (58 agents × 18 languages = 1,044 files)
#247	```
#248
#249	### Step 4: Test Locally (Optional)
#250
#251	```bash
#252	# Serve locally to test
#253	npx serve public
#254
#255	# Open http://localhost:3000/index.json
#256	```
#257
#258	### Step 5: Commit and Push
#259
#260	```bash
#261	# Add source + translations
#262	git add src/ locales/
#263
#264	# Commit (do NOT add public/ - it's gitignored)
#265	git commit -m "feat: Add My DeFi Agent"
#266
#267	# Push to trigger CI/CD
#268	git push origin main
#269	```
#270
#271	### Step 6: Automatic Deployment
#272
#273	GitHub Actions automatically:
#274
#275	1. ✅ Runs `bun run format` (translates)
#276	2. ✅ Runs `bun run build` (builds)
#277	3. ✅ Deploys `public/` to `gh-pages` branch
#278	4. ✅ GitHub Pages serves your site
#279
#280	Live in \~5 minutes at:
#281
#282	- Default: `https://yourusername.github.io/defi-agents/index.json`
#283	- Custom: `https://yourdomain.com/index.json`
#284
#285	---
#286
#287	## Local Development
#288
#289	### First-Time Setup
#290
#291	```bash
#292	# 1. Clone repository
#293	git clone https://github.com/yourusername/defi-agents
#294	cd defi-agents
#295
#296	# 2. Install dependencies
#297	bun install
#298
#299	# 3. Configure OpenAI API key
#300	echo "OPENAI_API_KEY=sk-xxx" > .env
#301	```
#302
#303	### Development Commands
#304
#305	```bash
#306	# Format & translate agents
#307	bun run format
#308
#309	# Build public distribution
#310	bun run build
#311
#312	# Run tests
#313	bun run test
#314
#315	# Validate translations
#316	bun run i18n:validate
#317
#318	# Clean invalid translations
#319	bun run i18n:clean
#320
#321	# Lint markdown docs
#322	bun run lint:md
#323
#324	# Format all code
#325	bun run prettier
#326
#327	# Full release pipeline (format + build + update README)
#328	bun run awesome
#329	```
#330
#331	### Typical Development Loop
#332
#333	```bash
#334	# 1. Create or edit agent
#335	vim src/my-agent.json
#336
#337	# 2. Translate
#338	bun run format
#339
#340	# 3. Build
#341	bun run build
#342
#343	# 4. Test
#344	bun run test
#345
#346	# 5. Commit
#347	git add src/ locales/
#348	git commit -m "feat: Add my agent"
#349
#350	# 6. Push (triggers CI/CD)
#351	git push origin main
#352	```
#353
#354	---
#355
#356	## CI/CD Pipeline
#357
#358	### GitHub Actions Workflow
#359
#360	File: `.github/workflows/release.yml`
#361
#362	Triggers: Every push to `main` branch
#363
#364	Steps:
#365
#366	1. Checkout - Fetch repository
#367	2. Install Bun - Setup runtime
#368	3. Install Dependencies - `bun install`
#369	4. Run Tests - Validate agents
#370	5. Format & Translate - `bun run format` (uses OPENAI_API_KEY secret)
#371	6. Update README - `bun run awesome`
#372	7. Lint & Prettier - Code formatting
#373	8. Commit Changes - Auto-commit translations
#374	9. Deploy to GitHub Pages - Deploy `public/` to `gh-pages` branch
#375
#376	### Required Secrets
#377
#378	Set in Repository Settings → Secrets and variables → Actions:
#379
#380	- `OPENAI_API_KEY` - OpenAI API key for translations (required)
#381	- `OPENAI_PROXY_URL` - Custom OpenAI endpoint (optional)
#382	- `GITHUB_TOKEN` - Automatically provided by GitHub
#383
#384	### Build Process Details
#385
#386	The build step (`bun run build`) calls `agent-builder.ts` which:
#387
#388	1. Builds Schema
#389	- Generates JSON schema from Zod definitions
#390	- Writes to `schema/` and `public/schema/`
#391
#392	2. Builds Agents (for each of 18 languages)
#393	- Reads `src/*.json` (English source)
#394	- Reads `locales/agent-name/index.[locale].json`
#395	- Merges source + translation
#396	- Writes to `public/agent-name.[locale].json`
#397
#398	3. Generates Indexes (for each of 18 languages)
#399	- Collects all agents
#400	- Extracts metadata
#401	- Calculates tag frequencies
#402	- Writes to `public/index.[locale].json`
#403
#404	4. Copies CNAME
#405	- Checks if `CNAME` exists in root
#406	- Copies to `public/CNAME` (if exists)
#407	- Ensures custom domain persists
#408
#409	Code Reference: `scripts/builders/agent-builder.ts`
#410
#411	```typescript
#412	run = async () => {
#413	this.buildSchema(); // Generate schema
#414	await this.buildFullLocaleAgents(); // Build all languages
#415	this.copyCNAME(); // Copy CNAME
#416	};
#417	```
#418
#419	---
#420
#421	## Domain Management
#422
#423	### Option 1: Use Default GitHub Pages Domain
#424
#425	For: Personal projects, testing, forks
#426
#427	```bash
#428	# Delete CNAME file
#429	rm CNAME
#430	git add CNAME
#431	git commit -m "Use default GitHub Pages domain"
#432	git push
#433	```
#434
#435	Your site: `https://username.github.io/defi-agents/`
#436
#437	### Option 2: Use Custom Domain
#438
#439	For: Production, branded deployments
#440
#441	```bash
#442	# 1. Update CNAME file
#443	echo "yourdomain.com" > CNAME
#444	git add CNAME
#445	git commit -m "Set custom domain"
#446	git push
#447
#448	# 2. Configure DNS (in your domain registrar)
#449	# Add CNAME record: yourdomain.com → username.github.io
#450
#451	# 3. Enable HTTPS in GitHub
#452	# Settings → Pages → Enforce HTTPS (after DNS propagates)
#453	```
#454
#455	Your site: `https://yourdomain.com/`
#456
#457	### CNAME Handling Details
#458
#459	Why it works:
#460
#461	1. CNAME file is stored in repository root
#462	2. Build process (`agent-builder.ts`) copies it to `public/CNAME`
#463	3. GitHub Actions deploys `public/` directory (including CNAME)
#464	4. GitHub Pages reads `CNAME` and serves site at custom domain
#465
#466	For forks:
#467
#468	- Original repo has `clawd.click` in CNAME
#469	- Fork maintainer updates CNAME to `their-domain.com`
#470	- Build automatically copies their CNAME
#471	- Their domain works without any code changes
#472
#473	Implementation: `scripts/builders/agent-builder.ts`
#474
#475	```typescript
#476	copyCNAME = () => {
#477	const cnamePath = resolve(root, 'CNAME');
#478	const publicCNAMEPath = resolve(publicDir, 'CNAME');
#479
#480	if (existsSync(cnamePath)) {
#481	copyFileSync(cnamePath, publicCNAMEPath);
#482	Logger.success('CNAME 文件已复制到 public 目录');
#483	}
#484	};
#485	```
#486
#487	---
#488
#489	## For Contributors
#490
#491	### Submitting a New Agent
#492
#493	1. Fork the repository
#494	2. Create agent: `src/your-agent.json`
#495	3. Submit PR (translation happens in CI)
#496
#497	You do NOT need to:
#498
#499	- ❌ Translate manually
#500	- ❌ Run `bun run format` locally
#501	- ❌ Create locale files
#502	- ❌ Build the public index
#503
#504	CI will automatically:
#505
#506	- ✅ Translate to 18 languages
#507	- ✅ Build and deploy
#508	- ✅ Update the marketplace
#509
#510	### PR Review Process
#511
#512	1. Maintainer reviews `src/your-agent.json`
#513	2. If approved, PR is merged to main
#514	3. CI runs format + build + deploy
#515	4. Agent appears at marketplace within 5 minutes
#516
#517	---
#518
#519	## For Fork Maintainers
#520
#521	### Initial Setup
#522
#523	```bash
#524	# 1. Fork on GitHub
#525	# Click "Fork" button
#526
#527	# 2. Clone your fork
#528	git clone https://github.com/yourusername/defi-agents
#529	cd defi-agents
#530
#531	# 3. Set up custom domain (optional)
#532	echo "yourdomain.com" > CNAME
#533	# Or delete CNAME for default GitHub Pages URL
#534
#535	# 4. Configure GitHub secrets
#536	# Go to Settings → Secrets → Actions
#537	# Add: OPENAI_API_KEY
#538
#539	# 5. Enable GitHub Pages
#540	# Settings → Pages → Source: gh-pages branch
#541
#542	# 6. Push to trigger first deployment
#543	git add CNAME # or git rm CNAME
#544	git commit -m "Configure domain"
#545	git push origin main
#546	```
#547
#548	### Maintaining Your Fork
#549
#550	Keep agents in sync with upstream:
#551
#552	```bash
#553	# Add upstream remote
#554	git remote add upstream https://github.com/nirholas/defi-agents
#555
#556	# Sync with upstream
#557	git fetch upstream
#558	git merge upstream/main
#559
#560	# Rebuild with your agents
#561	bun run format
#562	bun run build
#563
#564	# Push
#565	git push origin main
#566	```
#567
#568	Add your own agents:
#569
#570	```bash
#571	# Create agent
#572	vim src/my-custom-agent.json
#573
#574	# Commit and push (CI handles rest)
#575	git add src/my-custom-agent.json
#576	git commit -m "feat: Add my custom agent"
#577	git push origin main
#578	```
#579
#580	---
#581
#582	## Summary
#583
#584	Complete Lifecycle:
#585
#586	```
#587	Developer → Create agent.json → Push to GitHub
#588	↓
#589	GitHub Actions CI/CD
#590	↓
#591	format (translate to 18 languages)
#592	↓
#593	build (generate public index + copy CNAME)
#594	↓
#595	deploy (push to gh-pages branch)
#596	↓
#597	GitHub Pages CDN
#598	↓
#599	Live at your domain in 18 languages
#600	```
#601
#602	Key Files:
#603
#604	- `src/*.json` - Source agents (English)
#605	- `locales//index..json` - Translations (18 languages)
#606	- `public/` - Build output (gitignored, generated)
#607	- `CNAME` - Custom domain (optional)
#608	- `.github/workflows/release.yml` - CI/CD automation
#609	- `scripts/builders/agent-builder.ts` - Build logic
#610
#611	Key Commands:
#612
#613	- `bun run format` - Translate agents
#614	- `bun run build` - Build index (includes CNAME copy)
#615	- `bun run test` - Validate everything
#616	- `git push origin main` - Trigger deployment
#617
#618	---
#619
#620	## Related Documentation
#621
#622	- [I18N Workflow](./I18N_WORKFLOW.md) - Translation system details
#623	- [Deployment Guide](./DEPLOYMENT.md) - Domain setup, DNS config
#624	- [Contributing](./CONTRIBUTING.md) - Agent submission guidelines
#625	- [Agent Guide](./AGENT_GUIDE.md) - Writing effective agents
#626	- [API Reference](./API.md) - Using the agent index
#627	- [Troubleshooting](./TROUBLESHOOTING.md) - Common issues
#628
#629	---
#630
#631	Questions? Open an issue or check the [FAQ](./FAQ.md).
#632
#633	---
#634
#635	## Alternative: Vercel Deployment
#636
#637	If GitHub Actions are disabled or you prefer Vercel's features (CORS control, analytics, rate limiting):
#638
#639	### Quick Setup
#640
#641	1. Import to Vercel: [vercel.com/new](https://vercel.com/new)
#642	2. Configure build:
#643	- Build Command: `bun run build`
#644	- Output Directory: `public`
#645	3. Add environment variable: `OPENAI_API_KEY`
#646	4. Deploy!
#647
#648	### Manual Local Build for Vercel
#649
#650	```bash
#651	# Install
#652	bun install
#653
#654	# Translate agents (requires OpenAI API key)
#655	export OPENAI_API_KEY=sk-your-key
#656	bun run format
#657
#658	# Build
#659	bun run build
#660
#661	# Or use the convenience script
#662	./scripts/local-release.sh
#663	```
#664
#665	### When to Use Vercel vs GitHub Pages
#666
#667	\| Use Case \| Recommendation \|
#668	\|----------\|---------------\|
#669	\| GitHub Actions enabled \| GitHub Pages (automatic) \|
#670	\| GitHub Actions disabled \| Vercel \|
#671	\| Need CORS control \| Vercel \|
#672	\| Need rate limiting \| Vercel \|
#673	\| Need analytics \| Vercel \|
#674	\| Simple, free hosting \| Either works \|
#675
#676	See [Deployment Guide](./DEPLOYMENT.md) for complete details.
#677
#678
#679

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public