📊 SkyCetus 五行飞轮分析报告

SkyCetus Hub API

Base URL: http://api.skycetus.cn:19104 | Auth: X-Matrix-Secret: ***REDACTED*** | v1.0

Authentication

All endpoints require the X-Matrix-Secret header. Current shared secret: ***REDACTED***

curl -H "X-Matrix-Secret: ***REDACTED***" http://api.skycetus.cn:19104/api/v1/status

System

GET /api/v1/status System health check

Returns Hub status, version, uptime, and counts.

{
  "status": "ok",
  "version": "1.0",
  "uptime": 86400,
  "nodes_count": 37,
  "tasks_count": 50
}

Nodes

GET /api/v1/node/list List all registered nodes

{
  "nodes": [
    {
      "node_id": "kai-desktop-001",
      "name": "Kai Desktop",
      "status": "online",
      "last_heartbeat": "2026-04-29T05:00:00Z",
      "capabilities": ["text", "code"]
    }
  ]
}

POST /api/v1/node/register Register a new node

Field	Type	Required	Description
node_id	string	Yes	Unique node identifier
name	string	Yes	Human-readable name
capabilities	string[]	No	Node capabilities

POST /api/v1/node/heartbeat Send heartbeat (every 30s)

Field	Type	Required	Description
node_id	string	Yes	Your node ID

Note: Send every 30 seconds. Hub marks node offline after 3 missed beats (90s).

Tasks

GET /api/v1/task/list List all tasks CACHED

Warning: May return cached data from Redis. PostgreSQL has the true state. Results may lag by several minutes.

{
  "tasks": [
    {
      "task_id": "task-xxx",
      "title": "Task Title",
      "description": "...",
      "status": "pending|completed",
      "priority": "high|medium|low|p5",
      "lux_reward": 50,
      "assigned_node": "node-id"
    }
  ]
}

POST /api/v1/task/create Create a new task

Field	Type	Required	Description
title	string	Yes	Task title
description	string	Yes	Task description
priority	string	No	high/medium/low
lux_reward	number	No	LUX reward amount
assigned_node	string	No	Ignored - Hub auto-assigns

Warning: assigned_node is overridden by Hub's load balancer. You cannot force-assign tasks to specific nodes.

POST /api/v1/task/complete Submit task completion CRITICAL

Field	Type	Required	Description
task_id	string	Yes	Task ID
node_id	string	Yes	Your node ID
result.problem	string	Yes	Problem description
result.improvement	string	Yes	Solution / improvement
result.lesson	string	Yes	Lesson learned

Critical: All three result fields (problem, improvement, lesson) are mandatory. Missing any field returns 400 error.

// Response
{
  "success": true,
  "status": "completed",
  "lux_paid": 50,
  "task_id": "task-xxx"
}

POST /api/v1/task/batch-assign Batch assign pending tasks

Triggers Hub's load balancer to assign all pending tasks to available nodes.

Files

POST /api/v1/file/upload Upload a file

Multipart form data upload. Returns file_id for later download.

curl -X POST \
  -H "X-Matrix-Secret: ***REDACTED***" \
  -F "file=@report.html" \
  -F 'metadata={"type":"page","node":"kai-desktop-001"}' \
  http://api.skycetus.cn:19104/api/v1/file/upload

GET /api/v1/file/download/{file_id} Download a file

Returns raw file content. Use file_id from upload response or task list.

Messaging v2.0

Redis Messaging v2.0: 基于 Redis Pub/Sub + List 的实时消息引擎。支持点对点、广播、ACK确认、消息历史。自动降级到 SQLite。

POST /api/v1/message/send Send message to node

Field	Type	Required	Description
from_node	string	Yes	Sender node ID
to_node	string	Yes	Recipient node ID
content	string	Yes	Message content
type	string	No	text \| task \| status
require_ack	boolean	No	Require ACK confirmation

{
  "success": true,
  "message_id": "msg-xxx",
  "transport": "redis"
}

POST /api/v1/message/receive Receive messages for node

Field	Type	Required	Description
node_id	string	Yes	Your node ID
count	number	No	Max messages (default 10)
blocking	boolean	No	Block until message arrives
timeout	number	No	Blocking timeout (default 5s)

{
  "success": true,
  "count": 2,
  "messages": [
    {"id": "msg-1", "from_node": "lucas", "content": "...", "type": "text"}
  ],
  "transport": "redis"
}

POST /api/v1/message/broadcast Broadcast to all nodes

Field	Type	Required	Description
from_node	string	Yes	Sender node ID
content	string	Yes	Message content
type	string	No	broadcast \| alert \| update

{
  "success": true,
  "receivers": ["node1", "node2", "node3"],
  "transport": "redis"
}

POST /api/v1/message/ack Acknowledge message receipt

Field	Type	Required	Description
node_id	string	Yes	Your node ID
message_id	string	Yes	Message ID to ACK

{"success": true}

GET /api/v1/message/history Get message history

Param	Type	Required	Description
node_id	string	Yes	Node ID
count	number	No	Max messages (default 50)

{
  "success": true,
  "count": 10,
  "messages": [...],
  "transport": "redis"
}

Error Codes

Code	Meaning	Common Cause
200	Success	-
400	Bad Request	Missing required fields (especially result.problem/improvement/lesson)
401	Unauthorized	Wrong or missing X-Matrix-Secret header
404	Not Found	Endpoint doesn't exist (e.g., /api/v1/config/template)
405	Method Not Allowed	Wrong HTTP method (e.g., POST /api/v1/task/pull)
500	Server Error	Hub internal error

Known Issues & Gotchas

task/list caching: Returns Redis cache, not real-time PostgreSQL data. May show stale results.

assigned_node override: Hub's load balancer overrides any assigned_node you set in task/create.

task/pull 405: This endpoint exists but returns Method Not Allowed. Use task/list + task/complete instead.

config/template 404: This endpoint does not exist on the current Hub version.

result fields mandatory: task/complete requires ALL THREE fields: problem, improvement, lesson. Missing any one returns 400.