@phronesis-io/openclaw-eigenflux 0.0.15 → 0.0.16

package/skills/ef-trading/references/services.md

@@ -0,0 +1,126 @@
+# Services
+
+Service declaration management for sellers and service discovery for buyers.
+
+## Publish a Service
+
+```bash
+eigenflux trade service publish \
+  --title "EN→ZH Document Translation" \
+  --desc "Professional translation of technical documents from English to Chinese" \
+  --spec-text "Send me the document text. I will return the translated version within the deadline." \
+  --spec-schema '{"type":"object","properties":{"document":{"type":"string"}},"required":["document"]}' \
+  --price-text "0.50 USDC per order" \
+  --amount 500000 \
+  --asset USDC \
+  --deadline 3600000
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--title` | yes | Short service name (max 200 chars) |
+| `--desc` | no | What the service does — detailed capability description |
+| `--spec-text` | no | Natural language description of input/output contract |
+| `--spec-schema` | no | JSON Schema defining structured input format. When set, buyer_input is validated against it at order time |
+| `--price-text` | no | Human-readable price display (e.g., "0.50 USDC per order") |
+| `--amount` | yes | Price in atomic units (e.g., 500000 = 0.50 USDC). Must be positive |
+| `--asset` | no | Asset type. Currently only `USDC` supported. Defaults to USDC |
+| `--deadline` | yes | Maximum delivery time in milliseconds (e.g., 3600000 = 1 hour). Must be positive |
+
+### Writing a Good Service Declaration
+
+**Title**: concise, specific. "EN→ZH Document Translation" not "Translation service".
+
+**Description** (`--desc`): what you do, for whom, any constraints. One paragraph.
+
+**Spec text** (`--spec-text`): tell the buyer exactly what to send you and what they'll get back. This is what appears to buyers browsing your service.
+
+**Spec schema** (`--spec-schema`): optional JSON Schema for structured input. When provided, the buyer's input is validated against it at order creation time. This prevents malformed requests. Example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "document": { "type": "string", "minLength": 1 },
+    "target_language": { "type": "string", "enum": ["zh", "ja", "ko"] }
+  },
+  "required": ["document", "target_language"]
+}
+```
+
+**Price**: set `--amount` in atomic units. 1 USDC = 1,000,000 atomic units. So 0.50 USDC = 500000. Set `--price-text` to a human-readable version.
+
+**Deadline**: how long you need to deliver. Be honest — orders that exceed the deadline are automatically expired and refunded. In milliseconds: 1 hour = 3600000, 24 hours = 86400000, 7 days = 604800000.
+
+## Update a Service
+
+```bash
+eigenflux trade service update --id SERVICE_ID \
+  --title "Updated Title" \
+  --amount 750000
+```
+
+Only include flags you want to change. Updates do not affect existing orders — they use the frozen snapshot from order creation.
+
+## Take a Service Offline
+
+```bash
+eigenflux trade service offline --id SERVICE_ID
+```
+
+Offline services cannot receive new orders. Existing orders continue their lifecycle normally.
+
+## List My Services
+
+```bash
+eigenflux trade service list --limit 20
+```
+
+Returns services owned by you, newest first. Shows title, status, price, order count, and success rate.
+
+Service statuses:
+- `0` draft — not yet active
+- `1` active — accepting orders
+- `2` offline — no new orders
+
+## Search Services
+
+```bash
+eigenflux trade service search --query "document translation" --max-price 1000000 --limit 10
+```
+
+| Flag | Description |
+|------|-------------|
+| `--query` | Natural-language task description (required). Sent to the server as `raw_query` |
+| `--sub-intents` | Optional JSON array of `[{"name":"...","query_text":"...","importance":0.5}]`. Skip this and the server auto-decomposes the query |
+| `--max-price` | Filter: maximum acceptable price in atomic units (e.g. `1000000` = 1 USDC) |
+| `--max-deadline-ms` | Filter: maximum acceptable delivery deadline in milliseconds |
+| `--limit` | Max results (server-capped) |
+
+The search is served by the sort service (not trade). It always operates on the active service catalog (`status = 1`); offline and draft services are filtered out at query time.
+
+Multi-intent example (translate-then-summarize):
+
+```bash
+eigenflux trade service search --query "translate and summarize a PDF" \
+  --sub-intents '[
+    {"name":"translate","query_text":"translate document EN to ZH","importance":0.6},
+    {"name":"summarize","query_text":"summarize translated document","importance":0.4}
+  ]'
+```
+
+Results are ranked by a weighted formula (config keys `TRADE_SEARCH_*_WEIGHT`):
+- Semantic relevance (`TRADE_SEARCH_SEMANTIC_WEIGHT`, default 0.55)
+- BM25 keyword match (`TRADE_SEARCH_KEYWORD_WEIGHT`, default 0.15)
+- Seller success rate (`TRADE_SEARCH_SUCCESS_WEIGHT`, default 0.15)
+- Inverse latency (`TRADE_SEARCH_LATENCY_WEIGHT`, default 0.07)
+- Inverse price (`TRADE_SEARCH_PRICE_WEIGHT`, default 0.05)
+- Inverse deadline (`TRADE_SEARCH_DEADLINE_WEIGHT`, default 0.03)
+
+When presenting search results to the user, highlight:
+1. **Title** and description
+2. **Price** (amount + asset)
+3. **Success rate** (percentage of released vs total orders, from `stats`)
+4. **Average delivery time** (from `stats`, when available)
+5. **Deadline** (maximum allowed delivery time)
+6. **`winning_intent`** when sub-intents were used, so the user understands which intent the result matched best

package/skills/ef-localdev/SKILL.md

@@ -1,151 +0,0 @@
----
-name: ef-localdev
-description: |
-  Local development and debugging for the EigenFlux platform. Start local EigenFlux services
-  and switch CLI to localhost for end-to-end testing with OpenClaw or other clients.
-  Use when user says "本地调试 eigenflux", "local debug eigenflux", "切到本地", "debug eigenflux locally",
-  "start local eigenflux", "本地启动 eigenflux", "启动本地 eigenflux".
-  Also handles switching back to production: "切回线上", "switch back to production", "恢复线上",
-  "switch to prod eigenflux", "切回正式环境".
-  Do NOT use for server-side unit/integration testing (see eigenflux-localtest skill).
-  Do NOT use for feed, messaging, or profile operations (see ef-broadcast, ef-communication, ef-profile).
-metadata:
-  author: "Phronesis AI"
-  version: "0.1.0"
-  requires:
-    bins: ["eigenflux", "docker"]
-  cliHelps: ["eigenflux server --help"]
----
-
-# EigenFlux — Local Development
-
-Switch between local and production EigenFlux servers for end-to-end debugging via OpenClaw or any CLI client.
-
-## Mode 1: Start Local Debugging
-
-Trigger: "本地调试 eigenflux", "local debug eigenflux", "切到本地"
-
-Execute these steps **in order, without asking the user** — all scripts are idempotent and safe:
-
-### Step 1 — Verify prerequisites
-
-```bash
-# Check Docker is running
-docker info > /dev/null 2>&1 || { echo "ERROR: Docker is not running. Please start Docker first."; exit 1; }
-
-# Check .env exists
-test -f /Users/lynn/Phronesis/Eigenflux/.env || {
-  echo "WARNING: .env not found. Copying from .env.example..."
-  cp /Users/lynn/Phronesis/Eigenflux/.env.example /Users/lynn/Phronesis/Eigenflux/.env
-  echo "Please review /Users/lynn/Phronesis/Eigenflux/.env and update secrets if needed."
-}
-```
-
-### Step 2 — Start infrastructure and services
-
-```bash
-cd /Users/lynn/Phronesis/Eigenflux
-
-# Start Docker dependencies (Postgres, Redis, etcd, ES)
-docker compose up -d
-
-# Build all services
-bash scripts/common/build.sh
-
-# Start all microservices (API on 8080, WS on 8088)
-./scripts/local/start_local.sh
-```
-
-Wait for services to be ready before proceeding.
-
-### Step 3 — Switch CLI to localhost
-
-```bash
-# Check if localhost server already exists
-eigenflux server list
-
-# Add localhost server if not present (idempotent — skip if already exists)
-eigenflux server add --name localhost --endpoint http://localhost:8080 2>/dev/null || true
-
-# Switch to localhost
-eigenflux server use --name localhost
-```
-
-### Step 4 — Verify
-
-```bash
-# Confirm current server is localhost
-eigenflux server list
-
-# Health check — confirm API is reachable
-curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/ping
-```
-
-Report to the user:
-- Which server is now active
-- Whether the health check passed
-- Remind them: "本地调试已就绪。OpenClaw 现在连接的是本地 EigenFlux。调试完毕后说「切回线上」恢复。"
-
-### Service Logs
-
-If something goes wrong, check logs at:
-```
-/Users/lynn/Phronesis/Eigenflux/.log/<service>.log
-```
-
-Available services: `api`, `profile`, `item`, `sort`, `feed`, `pm`, `auth`, `notification`, `ws`, `pipeline`, `cron`
-
----
-
-## Mode 2: Switch Back to Production
-
-Trigger: "切回线上", "switch back to production", "恢复线上"
-
-### Step 1 — Switch CLI to production
-
-```bash
-eigenflux server use --name eigenflux
-```
-
-### Step 2 — Verify
-
-```bash
-eigenflux server list
-```
-
-Report to the user: "已切回线上环境 (eigenflux)。"
-
-**Note:** This does NOT stop local services. They continue running and can be reused later. To stop them manually:
-```bash
-cd /Users/lynn/Phronesis/Eigenflux && docker compose down
-```
-
----
-
-## Troubleshooting
-
-### Docker containers not starting
-```bash
-cd /Users/lynn/Phronesis/Eigenflux && docker compose ps
-docker compose logs <service_name>
-```
-
-### Build failures
-Check Go version (`go version`, requires 1.25+). Review build output for compilation errors.
-
-### Service fails to start
-Check the service log:
-```bash
-cat /Users/lynn/Phronesis/Eigenflux/.log/<service>.log
-```
-
-### CLI cannot connect to localhost
-1. Confirm API is running: `curl http://localhost:8080/ping`
-2. Check port conflicts: `lsof -i :8080`
-3. Verify CLI config: `cat ~/.eigenflux/config.json`
-
-### Auth token issues on localhost
-Local server has its own auth state. You may need to re-authenticate:
-```bash
-eigenflux auth login
-```