@scemoon/cdh 1.0.8 → 1.0.9-beta.2

package/ai-dlc-skill/providers/tcb/services/cloud-run.md

@@ -0,0 +1,285 @@
+# CloudBase Run (CaaS)
+
+## When to Use CloudBase Run
+
+**Use CloudBase Run when:**
+- Long-running processes (> 60s timeout)
+- Need persistent state or connections
+- Require GPU or large memory (> 1536MB)
+- Custom runtime not supported by Functions
+- Container-based microservices architecture
+- WebSocket connections that persist
+
+**Do NOT use CloudBase Run when:**
+- Short, stateless functions → Use CloudBase Functions
+- Event-driven, bursty workloads → Use CloudBase Functions
+- Simple HTTP endpoints → Use CloudBase Functions (cheaper)
+- Serverless is requirement → Use CloudBase Functions
+
+## Agent Decision Guide
+
+```
+Need compute?
+├── Short tasks (<60s), stateless → CloudBase Functions
+├── Long-running (>60s) → CloudBase Run
+├── Custom container image → CloudBase Run
+├── GPU workload → CloudBase Run
+└── WebSocket server → CloudBase Run
+```
+
+## CloudBase Run vs CloudBase Functions
+
+| Criteria | CloudBase Functions | CloudBase Run |
+|----------|---------------------|---------------|
+| Max timeout | 60s | 3600s |
+| Max memory | 1536MB | 4096MB |
+| Cold start | 100-500ms | 1-5s |
+| Pricing | Per invocation | Per CPU-second + memory |
+| Container | No (managed runtime) | Yes (Docker) |
+| SSH access | No | No (but logs available) |
+| Persistent disk | No | No (stateless containers) |
+| WebSocket | Yes | Yes |
+| GPU | No | Yes |
+
+## Container Deployment
+
+### Dockerfile Example
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --only=production
+
+COPY . .
+
+EXPOSE 8080
+
+CMD ["node", "server.js"]
+```
+
+### Server Example (Express)
+
+```javascript
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: Date.now() });
+});
+
+app.post('/api/process', async (req, res) => {
+  const { data } = req.body;
+  // Long running task
+  const result = await processLongTask(data);
+  res.json({ result });
+});
+
+const PORT = process.env.PORT || 8080;
+app.listen(PORT, () => {
+  console.log(`Server running on port ${PORT}`);
+});
+```
+
+## Deployment
+
+### Deploy Container
+
+```bash
+tcb run deploy --name my-service --image myregistry.azurecr.io/myapp:latest --env $TCB_ENV_ID
+```
+
+### Deploy from Local Build
+
+```bash
+# Build and push to TCB registry
+tcb run deploy --name my-service --dockerfile ./Dockerfile --dir ./ --env $TCB_ENV_ID
+```
+
+### Scale Configuration
+
+```bash
+# Set min/max instances
+tcb run update --name my-service --min-instances 1 --max-instances 10 --env $TCB_ENV_ID
+
+# Set CPU and memory
+tcb run update --name my-service --cpu 1 --memory 2 --env $TCB_ENV_ID
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `tcb run deploy --name <name> --image <image> --env <envId>` | Deploy service |
+| `tcb run list --env <envId>` | List services |
+| `tcb run update --name <name> --min-instances <n> --max-instances <n>` | Update scaling |
+| `tcb run logs --name <name> --env <envId>` | View logs |
+| `tcb run delete --name <name> --env <envId>` | Delete service |
+| `tcb run detail --name <name> --env <envId>` | Get service details |
+
+## Service Configuration
+
+### cloudbaserc.json
+
+```json
+{
+  "container": {
+    "my-service": {
+      "image": "myregistry.azurecr.io/myapp:latest",
+      "port": 8080,
+      "minInstances": 1,
+      "maxInstances": 10,
+      "cpu": 1,
+      "memory": 2,
+      "envVars": {
+        "NODE_ENV": "production",
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+## Access Patterns
+
+### HTTP Endpoint
+
+```bash
+# Get service URL
+curl https://{service}-{env-id}.tcb-preview.com/health
+```
+
+### WebSocket
+
+```javascript
+const ws = new WebSocket('wss://{service}-{env-id}.tcb-preview.com');
+
+// Or from functions
+const result = await app.callFunction({
+  name: 'call-run-service',
+  data: { service: 'my-service', path: '/api/data' }
+});
+```
+
+### Internal Communication
+
+Services in the same environment can communicate internally:
+
+```javascript
+// From CloudBase Function to CloudBase Run service
+const response = await fetch('http://my-service:8080/api/internal', {
+  method: 'POST',
+  headers: {
+    'X-Internal-Token': process.env.INTERNAL_TOKEN
+  },
+  body: JSON.stringify({ data })
+});
+```
+
+## Scaling
+
+### Auto-scaling Configuration
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| CPU | > 70% | Scale up |
+| Memory | > 80% | Scale up |
+| Request count | > 100/min | Scale up |
+| Idle | < 5 min | Scale down to min |
+
+### Manual Scaling
+
+```bash
+# Scale immediately
+tcb run update --name my-service --instances 5 --env $TCB_ENV_ID
+
+# Scale to zero (cost saving)
+tcb run update --name my-service --instances 0 --env $TCB_ENV_ID
+```
+
+## Limits and Quotas
+
+| Limit | Value |
+|-------|-------|
+| Max timeout | 3600s |
+| Max CPU | 4 cores |
+| Max memory | 8GB |
+| Max instances | 20 |
+| Min instances | 0 (scale to zero) |
+| Concurrent requests | 1000 per instance |
+| Max container size | 10GB |
+
+## Best Practices
+
+1. **Graceful shutdown** - Handle SIGTERM for clean shutdown
+2. **Health checks** - Implement `/health` endpoint
+3. **Logging** - Use structured JSON logging
+4. **Environment variables** - Don't hardcode secrets
+5. **Connection pooling** - Reuse DB connections
+6. **Startup time** - Keep container startup under 30s
+7. **Stateless design** - Even with persistent storage, keep compute stateless
+
+### Graceful Shutdown Example
+
+```javascript
+let isShuttingDown = false;
+
+app.use((req, res, next) => {
+  if (isShuttingDown) {
+    res.status(503).json({ error: 'Service is restarting' });
+    return;
+  }
+  next();
+});
+
+process.on('SIGTERM', () => {
+  console.log('SIGTERM received, starting graceful shutdown');
+  isShuttingDown = true;
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+```
+
+## Cost Optimization
+
+### Scale to Zero
+
+For services not always needed:
+
+```bash
+# Scale down when not in use
+tcb run update --name my-service --min-instances 0 --env $TCB_ENV_ID
+```
+
+### Right-size Resources
+
+- Monitor actual CPU/memory usage
+- Don't over-provision for peak
+- Use auto-scaling to handle spikes
+
+### Cost Comparison
+
+| Service | Use Case | Approximate Cost |
+|---------|----------|------------------|
+| CloudBase Functions | 100k invocations, 128MB, 100ms | ~$0.05/day |
+| CloudBase Run | 1 core, 1GB, 24h | ~$0.50/day |
+
+CloudBase Run is more predictable but can be more expensive for sporadic workloads.
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Container fails to start | Image error, port issue | Check logs: `tcb run logs` |
+| 503 errors | Container overloaded | Scale up instances |
+| Slow response | Cold start, resource limits | Increase memory, enable min instances |
+| Out of memory | Memory limit exceeded | Increase memory allocation |
+| Connection refused | Service not ready | Add health check, delay start |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/services/cloud-storage.md

@@ -0,0 +1,245 @@
+# CloudBase Storage (COS)
+
+## When to Use CloudBase Storage
+
+**Use COS (Cloud Object Storage) when:**
+- Store files (images, videos, documents)
+- Host static assets for CDN delivery
+- Store user-generated content
+- Backup and archive data
+- Store function deployment packages
+
+**Do NOT use COS when:**
+- Need database-like queries → Use DocDB
+- Need to store < 1KB metadata → Use DocDB field
+- Hot data requiring instant retrieval → Consider Tencent Cloud Redis
+
+## Agent Decision Guide
+
+```
+Need to store files?
+├── User uploads (images, videos) → COS
+├── Function code packages → COS (automatic with --deployMode cos)
+├── Static website assets → COS + CloudBase Hosting
+└── Temporary files during processing → COS with lifecycle policy
+```
+
+## Storage Structure
+
+```
+Bucket: {env-id}-cos-{region}
+├── /uploads/           # User uploaded files
+├── /avatars/           # User profile images
+├── /documents/         # Document storage
+└── /backups/           # Database backups
+```
+
+## File Operations
+
+### Upload File
+
+```bash
+tcb storage upload --local ./file.txt --remote /uploads/file.txt --env $TCB_ENV_ID
+```
+
+### Download File
+
+```bash
+tcb storage download --local ./download.txt --remote /uploads/file.txt --env $TCB_ENV_ID
+```
+
+### List Files
+
+```bash
+tcb storage list --path /uploads --env $TCB_ENV_ID
+```
+
+### Delete File
+
+```bash
+tcb storage delete --remote /uploads/file.txt --env $TCB_ENV_ID
+```
+
+### Get File URL
+
+```bash
+tcb storage url --remote /uploads/file.txt --env $TCB_ENV_ID
+# Returns: https://{bucket}.cos.{region}.myqcloud.com/uploads/file.txt
+```
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `tcb storage list --path <path> --env <envId>` | List files in path |
+| `tcb storage upload --local <path> --remote <path> --env <envId>` | Upload file |
+| `tcb storage download --local <path> --remote <path> --env <envId>` | Download file |
+| `tcb storage delete --remote <path> --env <envId>` | Delete file |
+| `tcb storage url --remote <path> --env <envId>` | Get file URL (with signature) |
+| `tcb storage createFolder --path <path> --env <envId>` | Create folder |
+| `tcb storage deleteFolder --path <path> --env <envId>` | Delete folder |
+
+## Access Control
+
+### Public vs Private Buckets
+
+| Type | Access | Use Case |
+|------|--------|----------|
+| Public | Anyone with URL | Static assets, public downloads |
+| Private | Requires signature | User uploads, private documents |
+
+### Signed URLs (for private files)
+
+Private files require a signed URL with expiration:
+
+```javascript
+// Generate signed URL (valid for 1 hour)
+const signedUrl = await app.getTempFileURL({
+  filePath: '/uploads/private.pdf',
+  maxAge: 3600
+});
+```
+
+### File Permissions
+
+```javascript
+// Make file publicly readable
+await app.uploadFile({
+  cloudPath: '/uploads/public.txt',
+  filePath: './local.txt',
+  onUploadProgress: (progress) => {
+    console.log(`Uploaded: ${progress.loaded}/${progress.total}`);
+  }
+});
+
+// Or set ACL via SDK
+const cos = app.uploadFile({
+  // ...
+});
+```
+
+## Upload from Functions
+
+### Direct Upload (small files < 5MB)
+
+```javascript
+const tcb = require('@cloudbase/node-sdk');
+const fs = require('fs');
+
+const app = tcb.init({
+  env: process.env.TCB_ENV_ID
+});
+
+exports.main = async (event, context) => {
+  // event.fileContent is base64 encoded for small files
+  const buffer = Buffer.from(event.fileContent, 'base64');
+
+  const result = await app.uploadFile({
+    cloudPath: '/uploads/' + event.filename,
+    fileContent: buffer
+  });
+
+  return { fileID: result.fileID };
+};
+```
+
+### Server-Side Upload (recommended for large files)
+
+```javascript
+// Get upload credentials from TCB
+exports.main = async (event, context) => {
+  const { fileName, contentType } = event;
+
+  // Get upload parameters
+  const uploadData = await app.uploadFile({
+    cloudPath: '/uploads/' + fileName
+  });
+
+  // Frontend uses these to upload directly to COS
+  return {
+    url: uploadData.url,           // Upload to this URL
+    token: uploadData.token,       // Upload token
+    fileId: uploadData.fileID,     // TCB file ID
+    cloudPath: uploadData.cloudPath
+  };
+};
+```
+
+### Frontend Upload Example
+
+```javascript
+// Get upload credentials from function
+const { url, token } = await callFunction({
+  name: 'get-upload-params',
+  data: { fileName: 'avatar.jpg', contentType: 'image/jpeg' }
+});
+
+// Upload directly to COS
+const formData = new FormData();
+formData.append('key', 'uploads/avatar.jpg');
+formData.append('token', token);
+formData.append('file', fileInput.files[0]);
+
+await fetch(url, {
+  method: 'POST',
+  body: formData
+});
+```
+
+## Storage in CloudBase Hosting
+
+Files in COS are served through CDN for CloudBase Hosting:
+
+```
+User Request → CDN Edge → COS Origin → Static File
+                      ↓ (cache)
+              First request caches result
+```
+
+CDN automatically caches:
+- Static assets (`.js`, `.css`, `.jpg`, etc.)
+- Configurable cache duration
+
+## Limits and Quotas
+
+| Limit | Value |
+|-------|-------|
+| Max file size | 50GB (single file) |
+| Max bucket size | Unlimited |
+| Max files per folder | 1000 (recommend pagination) |
+| Upload speed | Limited by function memory |
+| Download speed | Limited by CDN带宽 |
+
+## Lifecycle Policies
+
+Set automatic deletion or transition for old files:
+
+```javascript
+// Via TCB console or API
+// Examples:
+// - Delete temp files after 7 days
+// - Move logs to archive storage after 30 days
+// - Clean up failed upload chunks
+```
+
+## Best Practices
+
+1. **Use meaningful paths** - `/uploads/{userId}/{timestamp}_{filename}`
+2. **Implement cleanup** - Delete old temporary files
+3. **Use content type** - Set correct `Content-Type` for browser display
+4. **Compress images** - Resize on upload to save storage
+5. **Use CDN** - Enable CDN for frequently accessed files
+6. **Handle duplicates** - Check if file exists before upload
+7. **Secure uploads** - Validate file types, scan for malware
+
+## Troubleshooting
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Upload fails | File too large | Use server-side upload flow |
+| 403 Forbidden | Private bucket | Use signed URL |
+| File not found | Wrong path | Check path is case-sensitive |
+| Slow download | Not cached | Enable CDN caching |
+| Upload timeout | Slow connection | Increase function timeout |
+
+For detailed troubleshooting → `../best-practices/troubleshooting.md`

package/ai-dlc-skill/providers/tcb/services/overview.md

@@ -0,0 +1,174 @@
+# TCB Platform Overview
+
+## What is Tencent CloudBase
+
+Tencent CloudBase (TCB) is a serverless cloud development platform that provides a complete cloud-native backend infrastructure. It eliminates the need to manage servers while providing database, storage, computing, and hosting capabilities.
+
+## Core Services
+
+| Service | Type | Description | Limits |
+|---------|------|-------------|--------|
+| CloudBase Functions | FaaS | Event-driven serverless functions | 60s timeout, 1536MB memory, 100 max instances |
+| CloudBase Run | CaaS | Container-based hosting | 3600s timeout, 4096MB memory |
+| CloudBase Database | NoSQL | Document database (JSON-like) | 2GB storage per env |
+| MySQL | RDBMS | Relational database | 20GB storage per env |
+| COS | Object Storage | File storage | 50GB per env |
+| CloudBase Hosting | Static | Static website + SSR support | 2GB per site |
+
+## Agent Decision Guide
+
+### When to Use Each Service
+
+```
+Need to run code in response to events?
+├── Yes → CloudBase Functions (FaaS)
+└── No → Continue
+
+Need long-running process or persistent state?
+├── Yes → CloudBase Run (CaaS)
+└── No → Continue
+
+Need to store structured data?
+├── JSON-like documents → CloudBase Database (DocDB)
+├── Relational data with SQL → MySQL
+└── Key-value cache → Use memory/redis pattern
+
+Need to store files?
+└── COS (Cloud Object Storage)
+
+Need to host a website?
+└── CloudBase Hosting (static + optional SSR)
+
+Need all of the above?
+└── TCB Environment (all services integrated)
+```
+
+### Service Comparison
+
+| Criteria | CloudBase Functions | CloudBase Run |
+|----------|---------------------|---------------|
+| Billing | Per invocation | Per resource usage |
+| Cold start | 100-500ms | 1-5s (if image not warm) |
+| Max timeout | 60s | 3600s |
+| Memory | 128-1536MB | Up to 4096MB |
+| Stateless | Yes (encouraged) | Yes (persistence optional) |
+| WebSocket | Yes (with --ws) | Full support |
+| Persistent connection | No | Yes |
+| GPU support | No | Yes |
+
+### Database Selection
+
+| Criteria | DocDB (NoSQL) | MySQL (RDBMS) |
+|----------|---------------|---------------|
+| Schema flexibility | Dynamic (no schema) | Fixed schema required |
+| Query language | Mongoose-like filters | SQL |
+| Transactions | Limited | Full ACID |
+| Joins | No (denormalize) | Yes |
+| Scaling | Horizontal | Vertical + Read replicas |
+| Use when | Rapid iteration, flexible schema | Complex queries, relations, data integrity |
+
+## Environment Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     TCB Environment                          │
+│  env-xxxxx                                                    │
+├──────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │  Functions  │  │  Database   │  │   Storage   │          │
+│  │  Namespace  │  │  (DocDB)    │  │    (COS)    │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
+│  │ Cloud Run   │  │   MySQL     │  │  Hosting    │          │
+│  │  Services   │  │             │  │  (CDN)      │          │
+│  └─────────────┘  └─────────────┘  └─────────────┘          │
+├──────────────────────────────────────────────────────────────┤
+│               Shared: CDN, SSL, Custom Domain                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Region Selection
+
+| Region ID | Region Name | Use Case |
+|-----------|-------------|----------|
+| `ap-shanghai` | Shanghai | China mainland (default) |
+| `ap-beijing` | Beijing | China mainland alternative |
+| `ap-guangzhou` | Guangzhou | China mainland alternative |
+| `ap-singapore` | Singapore | Southeast Asia |
+
+## Pricing Model
+
+| Service | Billing | Notes |
+|---------|---------|-------|
+| CloudBase Functions | Per invocation + traffic | Free tier: 100k invocations/month |
+| CloudBase Run | Per CPU-second + memory | More predictable than FaaS |
+| DocDB | Included in environment | Storage included |
+| COS | Per GB stored + traffic | First 50GB free |
+| Hosting | Included | CDN traffic may incur cost |
+
+## Agent Interaction Patterns
+
+### Pattern 1: Event-Driven Function
+```javascript
+// Triggered by HTTP request
+exports.main = async (event, context) => {
+  // event contains request data
+  // context contains TCB info
+  return { message: "Hello" };
+}
+```
+
+### Pattern 2: Background Processing
+```javascript
+// Triggered by timer or queue
+exports.main = async (event) => {
+  // Process in background
+  // Return result (or don't wait)
+}
+```
+
+### Pattern 3: API Gateway
+```javascript
+// Deployed as HTTP function
+// Accessible at: https://{env-id}.tcb-preview.com/{path}
+```
+
+### Pattern 4: Full-Stack with Hosting
+```
+Web App (Hosting) → API Functions → Database
+     ↓
+Static assets (COS CDN)
+```
+
+## Common Architectures
+
+### Architecture 1: Serverless Web App
+```
+Browser → CloudBase Hosting (SPA) → API Functions → DocDB/MySQL
+                                    ↓
+                              COS (file storage)
+```
+
+### Architecture 2: Mini-Program Backend
+```
+WXA/MYA/TTA → TCB API Gateway → CloudBase Functions → DocDB
+                                       ↓
+                                   COS (media storage)
+```
+
+### Architecture 3: Long-Running Service
+```
+Internet → CloudBase Run (Container) → DocDB/MySQL + COS
+              ↓
+         Persistent connections
+         Background workers
+         GPU workloads
+```
+
+## Next Steps
+
+- For function development → `services/cloud-functions.md`
+- For container workloads → `services/cloud-run.md`
+- For data storage → `services/cloud-database.md`
+- For file storage → `services/cloud-storage.md`
+- For static hosting → `services/cloud-hosting.md`