🐋 CetusDuo

CetusDuo 是 SkyCetus 天鲸之城定义的碳硅协作协议。

它不依赖 WebSocket、不依赖 HTTP 长连接、不依赖共享内存——只依赖文件系统的原子读写。

核心理念：File-as-API。Agent 和人类通过 JSON 文件在共享目录中交换任务和结果。

零依赖，零配置，零端口占用。对 Windows 兼容性最好。

前置条件

┌─────────────────────────────────────────────────────────────┐
│ CetusDuo 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ JSON files ┌─────────────┐ │
│ │ AI Agent │ ←──────────────────────→ │ Human Node │ │
│ │ (Generic) │ task / result │ (Hermes) │ │
│ │ │ │ │ │
│ │ GenericAgent│ │ Robin/Spark │ │
│ │ OpenClaw │ │ / Lucas │ │
│ │ (xiaok, │ │ (Operator) │ │
│ │ Kai, etc) │ │ │ │
│ └──────────────┘ └──────┬───────┘ │
│ │ │ │
│ │ ┌────────────────────────┐ │ │
│ │ │ shared/ │ │ │
│ │ │ ┌────────────────┐ │ │ │
│ └──────────→│ │ agent-to-human/│ │←─────┘ │
│ │ │ task_001.json │ │ │
│ ←───────────┤ │ result_001.json│ │ │
│ │ └────────────────┘ │ │
│ │ ┌────────────────┐ │ │
│ │ │ human-to-agent/│ │ │
│ │ │ task_002.json │ │ │
│ │ └────────────────┘ │ │
│ └────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Bridge Layer (bridge.py) │ │
│ │ • send-task : 投递任务 → agent-to-human/ │ │
│ │ • check-inbox : 收取结果 ← human-to-agent/ │ │
│ │ • status : 查询队列状态 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Worker Layer (worker.py) │ │
│ │ • poll 30s : 轮询任务目录 │ │
│ │ • execute : 调用 LLM 处理 │ │
│ │ • write : 只写文件，不执行命令 │ │
│ │ • 无父进程超时 : 独立进程，不会被 SIGKILL │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘ 

三层分离：

• Agent 层（硅基）—— AI 代理实例，通过 GenericAgent 框架或 OpenClaw 接入。负责需求拆解、任务投递、结果验证、部署执行。当前接入：GenericAgent (github.com/lsdefine/GenericAgent)、OpenClaw (小K 等)
• Bridge 层（协议）—— 文件路由，管理任务队列、状态机、错误重试
• Worker 层（硅基）—— 独立进程，调用 LLM，只写文件，不执行系统命令

CetusDuo 不限制 Agent 的实现框架，任何能读写文件的 AI 代理都可以接入。

已接入的 Agent 框架

Agent 身份标识

每个 Agent 在 CetusDuo 中有唯一标识：

node_id: xiaok_agent, GenericAgent, 1.0, write_file, generate_code, create_markdown, web_search, file" // 通过文件通信，无 HTTP 端口

未来扩展

任何符合以下条件的 Agent 都可以接入 CetusDuo：

• 能读写 JSON 文件到共享目录
• 遵循 Write-Only 原则（不直接执行系统命令）
• 在 task 文件中声明 framework 和 capabilities
• 支持 check-inbox 轮询或回调机制

GenericAgent 是当前主力，但未来可能有更多框架接入——LangChain、AutoGPT、MetaGPT 等，只要它们能读写文件就能协作。 

任务文件格式 (task_xxx.json)

task_id: task-20260507-001, xiaok_agent, hermes_worker, code_generation, high, 2026-05-07T08:00:00+08:00", topic: 生成 Fibonacci 函数, Python 3.10+, 带类型注解, 含单元测试, utils/fibonacci.py, "写一个 Python fibonacci 函数，要求：...", 15, "deepseek-v3

结果文件格式 (result_xxx.json)

task_id: task-20260507-001, hermes_worker, xiaok_agent, completed, 2026-05-07T08:01:30+08:00", files_created: utils/fibonacci.py", , "已生成带类型注解的 Fibonacci 函数和 pytest 单元测试, input": 450, 320 , 0.001, "deepseek-v3

状态文件 (status.json)

updated_at: 2026-05-07T08:02:00+08:00", pending": 3, 1, 47, 2 , status: running, 2026-05-07T08:01:55+08:00, task-20260507-002

1. 克隆 CetusDuo 仓库

git clone https://github.com/skycetus/cetusduo.git agent-bridge
cd agent-bridge

2. 创建目录结构

mkdir -p shared/agent-to-human
mkdir -p shared/human-to-agent
mkdir -p shared/completed
mkdir -p shared/failed
mkdir -p logs

3. 配置模型提供商

配置文件：config.toml

# 方案 A：阿里云百炼（国内推荐）
model
provider = "alibaba"
model_id = "qwen3.5-plus"
api_key = "你的百炼API Key"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" # 方案 B：MiniMax
model
provider = "anthropic"
model_id = "MiniMax-M2.7"
api_key = "你的MiniMax API Key"
base_url = "https://api.minimaxi.com/anthropic/v1" # 方案 C：通用 OpenAI 兼容
model
provider = "auto"
model_id = "你的模型名"
api_key = "你的API Key"
base_url = "https://你的端点/v1"

4. 验证配置

python -m cetusduo test --prompt "say hello"
# 预期：Worker 响应，日志显示 token 用量

Bridge API

Worker 运行方式

# 方式 1：前台运行（开发调试）
python worker.py --poll 30 --verbose # 方式 2：后台守护（推荐）
nohup python worker.py --poll 30 > logs/worker.log 2>&1 & # 方式 3：Windows 计划任务（最稳定）
schtasks /create /tn "CetusDuoWorker" /tr "python worker.py" /sc onstart /ru SYSTEM

 NSSM 在 Windows Server 上有已知状态管理 bug，容易进入 SERVICE_PAUSED 死状态。schtasks 是操作系统原生机制，不会挂死。 

这四个原则是 CetusDuo 的不可违背协议。

违反任何一条都会导致协作断裂。


        
原则 1：原子任务
        
核心 每个任务只写一个文件。
        
不要投递"帮我写一整个项目"这种大任务。
拆分成：写配置文件 → 写主模块 → 写测试 → 写 README。Worker 一次只处理一个原子任务，Agent 负责组装。

        
 反例："写一个完整的电商网站" → Worker 输出混乱，无法验证
 正例："写 user.py 的 User 模型类，含 SQLAlchemy 定义" → 清晰可验证 

        
原则 2：上下文预加载
        
核心 Prompt 中提供所有信息，不要让 Worker 读文件。

        
Worker 是 Write-Only 的，它不应该读取外部文件获取上下文。
所有需要的代码片段、API 文档、示例都应该在 prompt 中直接提供。
        
# 好的 prompt
"基于以下 User 模型定义，写一个 CRUD API：
 python
class User(BaseModel): id: int name: str email: str
 要求：FastAPI 路由，含 Pydantic 校验，返回 JSON" # 坏的 prompt
"写一个 User 的 CRUD API，参考 models/user.py" ← Worker 不会读文件！




        
原则 3：Write-Only
        
红线 Worker 只负责写文件，Agent 负责验证和部署。

        
Worker 被禁止执行系统命令（terminal_tool 禁用）、禁止运行代码（execute_code 禁用）、禁止网络请求。Worker 的唯一输出方式是写文件到指定目录。
        

            
Worker 能做的事
Worker 不能做的事
            
✅ 写 .py / .html / .md / .json 文件
❌ 执行 python script.py
            
✅ 生成代码注释和文档
❌ 运行 pip install
            
✅ 输出结构化数据
❌ 调用外部 API
            
✅ 返回文本分析结果
❌ 修改系统配置
        

        
原则 4：信任路由
        
安全 只路由到已验证能力，禁用未验证能力。


        
Worker 的能力白名单由 Agent 管理。新能力必须先通过沙箱测试，确认不会破坏系统后，才能加入白名单。
        
# worker_config.json
allowed_tools: write_file, generate_code, create_markdown, terminal_tool, execute_code, network_request, 1MB, .py, .html, .md, .json, .sql"

    

以下陷阱全部来自天鲸之城团队的实战踩坑，每个都花了至少 30 分钟才定位。

🕳️ 坑 1：同步调用 = 必死

🕳️ 坑 2：Windows PTY stdout 黑洞

🕳️ 坑 3：PowerShell 多行文本展开

🕳️ 坑 4：provider 配置陷阱

🕳️ 坑 5：NSSM 服务死锁

🕳️ 坑 6：GBK 编码地狱

🕳️ 坑 7：SSL 代理黑洞

🕳️ 坑 8：本地 vs 远程的「路径幻觉」

🕳️ 坑 9：nginx 静态文件缓存

🕳️ 坑 10：C: mp 文件消失

实战验证的好处

1. File-as-API 模式很聪明

不走 HTTP，不走 WebSocket，就是文件读写。零依赖，零配置，零端口占用。对 Windows 兼容性最好。

2. Write-Only 原则是对的

Worker 只负责写文件，Agent 负责验证和部署。

职责清晰，出问题容易定位。避免了 Worker 在 Windows 上执行命令的各种 PTY 问题。

3. 多模型路由的灵活性

百炼、MiniMax、通用 API 可以按任务类型选模型——这正是四象飞轮 → 已演化为 五行飞轮 的三模型编排思路：

• 🐉 青龙（假设生成）→ 百炼/QWEN 发散
• 🐦 朱雀（证据搜集）→ MiniMax thinking
• 👁️ 谛听（逻辑审计）→ QWEN/Kimi 校验
• 🐅 白虎（红队攻击）→ DeepSeek 对抗
• 🐢 玄武（残差提取）→ Kimi 收敛

4. 原子任务设计对飞轮的启发

"每个任务只写一个文件" → 对应认知 API 的单一职责。"上下文预加载" → 对应飞轮的认知记忆层。"Agent 来验证" → 对应白虎评估层。

场景 1：代码生成流水线

Agent 收到需求 ↓ 拆分成文件级任务 ↓ 逐个投递给 Worker ↓ 收取结果 ↓ 组装验证 ↓ 部署上线 示例：
task_1: 写 models/user.py（SQLAlchemy 模型）
task_2: 写 routes/user.py（FastAPI 路由）
task_3: 写 tests/test_user.py（pytest 单元测试）
task_4: 写 README.md（API 文档）

场景 2：文档/报告生成

Agent 分析数据 ↓ 投递 "生成 HTML 报告" ↓ Worker 写 HTML ↓ Agent 部署到 skycetus.cn/reports/ ↓ 邮件通知用户

场景 3：工具扩展

Agent 需要新工具 ↓ 投递 "写一个 xxx.py" ↓ Worker 生成 ↓ Agent 验证使用 ↓ 加入工具库

场景 4：多 Worker 协作

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Worker #1 │ │ Worker #2 │ │ Worker #3 │
│ (DeepSeek) │ │ (QWEN) │ │ (Kimi) │
│ 青龙·发散 │ │ 朱雀·搜集 │ │ 玄武·收敛 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ └───────────────────┼───────────────────┘ │ ┌───────▼───────┐ │ Agent 合成 │ │ 白虎·评估 │ └───────────────┘

多个 Worker 并行处理不同元素，Agent 负责合成和对抗验证。

这就是五行飞轮在 CetusDuo 协议中的工程实现。

CetusDuo 不是终点，而是五飞轮机制的协作层基础设施。

🔀 v2.0 双通道冗余通信

CetusDuo v2.0 引入双通道架构：ACP 实时通道 为主路径，File Bridge 冗余通道 为备份。

心跳检测自动切换，零数据丢失。

Agent A ←══ ACP实时通道 (主路径, ~100ms) ══→ Agent B ↕ JSON-RPC / SSE ↕ └──→ File Bridge冗余 (~30s轮询) ←──┘ 心跳检测ACP状态 断线自动切换 记录=审计日志

ACP 通道（主路径）

# ACP bind模式 — 持续对话
/acp spawn hermes --bind here # ACP spawn模式 — 单任务派发 sessions_spawn(task="生成landing page HTML", agentId="hermes")

File Bridge 通道（冗余路径）

# File Bridge 目录结构
shared/
├── agent-a-to-agent-b/ # A→B 消息队列
│ ├── task_001.json # 任务文件
│ └── task_002.json
├── agent-b-to-agent-a/ # B→A 响应队列
│ ├── result_001.json
│ └── result_002.json
└── heartbeat.json # 心跳状态

自动切换机制

def send_message(msg, channel="auto"): if channel == if acp_health_check(): # 心跳检测 (每30s) return acp_send(msg) # 主路径: ACP else: log.warn("ACP down, falling back to File Bridge") return file_bridge_send(msg) # 冗余路径 elif channel == return acp_send(msg) elif channel == return file_bridge_send(msg)

何时用哪个通道

📎 相关链接

• 天鲸之城首页
• 协同协议
• 五行飞轮引擎
• 共享知识库
• CetusDuo GitHub