Package Exports

@humanclaw/humanclaw
@humanclaw/humanclaw/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@humanclaw/humanclaw) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

HumanClaw

异步物理节点编排框架 —— 将人类抽象为分布式 Worker 节点

English | 中文

文档站点

概述

HumanClaw 是一个基于「物理世界异步 I/O」的单层分布式任务编排框架。系统将真实人类抽象为 Agent（物理节点），将现实中的任务派发与结果收集抽象为进程的挂起（Suspend）与恢复（Resume），最终将物理节点产生的结构化结果组装并提交给上游数字系统（如 OpenClaw），完成赛博世界与物理世界的闭环。

核心架构

┌─────────────┐     Dispatch      ┌──────────────┐
│             │ ──────────────►   │              │
│   Master    │     trace_id      │  HumanAgent  │
│  (老板/PM)  │ ◄──────────────   │  (碳基算力)   │
│             │   Resume + Result │              │
└─────┬───────┘                   └──────────────┘
      │
      │  Aggregate
      ▼
┌─────────────┐
│  OpenClaw   │
│  (数字生命)  │
└─────────────┘

Master 节点：解析需求，拆解为无依赖的扁平 TODO 列表，分发给物理节点
**Worker 节点 (HumanAgent)**：接收带 trace_id 的独立任务，在物理世界异步执行
状态机与存储：SQLite 本地持久化，保存上下文快照，释放系统内存

快速开始

安装

npm install -g @humanclaw/humanclaw

启动服务

humanclaw serve
# 服务运行在 http://localhost:2026
# Dashboard 看板：http://localhost:2026

注册物理节点

humanclaw agent add
# 交互式录入：节点名称、技能标签

查看算力池

humanclaw agent list

查看任务状态

humanclaw status

API 接口

方法	路径	说明
`GET`	`/api/v1/nodes/status`	碳基算力池状态
`POST`	`/api/v1/nodes`	注册物理节点
`PATCH`	`/api/v1/nodes/:id/status`	更新节点状态
`POST`	`/api/v1/jobs/create`	创建并分发任务
`GET`	`/api/v1/jobs/active`	获取看板数据
`POST`	`/api/v1/tasks/resume`	提交交付物，触发恢复
`POST`	`/api/v1/tasks/reject`	打回重做
`POST`	`/api/v1/jobs/:id/sync`	聚合结果同步至 OpenClaw

创建任务示例

curl -X POST http://localhost:2026/api/v1/jobs/create \
  -H "Content-Type: application/json" \
  -d '{
    "original_prompt": "完成首页重构",
    "openclaw_callback": "",
    "tasks": [
      {
        "assignee_id": "emp_xxxxxxxx",
        "todo_description": "实现响应式导航栏",
        "deadline": "2026-03-28T18:00:00Z"
      }
    ]
  }'

提交交付物

curl -X POST http://localhost:2026/api/v1/tasks/resume \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "TK-9527",
    "result_data": { "text": "导航栏已完成，支持移动端适配" }
  }'

Dashboard 看板

Web 看板包含三个核心视图：

碳基算力池监控 — 实时查看物理节点状态（🟢空闲 🟡忙碌 🔴离线 🟣崩溃）
异步编排大盘 — 任务 Kanban（已分发 / 已超时 / 已交付）+ Job 进度条
I/O 交付终端 — 输入 trace_id 和交付载荷，触发系统恢复

核心工作流

镜像封装 — 录入物理成员信息，构建碳基算力池
拆分分发 — Master 拆解任务，绑定 Agent，生成 trace_id
挂起快照 — 上下文序列化持久化，主控进入休眠
异步恢复 — 物理节点提交产出物，系统唤醒 Job
聚合闭环 — 所有子任务完成后，打包提交 OpenClaw

数据模型

interface HumanAgent {
  agent_id: string;       // emp_xxxxxxxx
  name: string;           // "前端老李"
  capabilities: string[]; // ["UI/UX", "前端开发"]
  status: AgentStatus;    // IDLE | BUSY | OFFLINE | OOM
}

interface HumanTask {
  trace_id: string;       // TK-9527
  job_id: string;
  assignee_id: string;
  todo_description: string;
  deadline: string;
  status: TaskStatus;     // PENDING | DISPATCHED | RESOLVED | OVERDUE
  result_data: unknown;
}

interface OrchestrationJob {
  job_id: string;
  original_prompt: string;
  openclaw_callback: string;
}

开发

git clone https://github.com/humanclaw/humanclaw.git
cd humanclaw
npm install
npm run dev        # 启动开发服务器
npm test           # 运行测试
npm run lint       # 类型检查

技术栈

Runtime: Node.js 22+, TypeScript (ESM, strict)
API: Express v5
Storage: SQLite (better-sqlite3, WAL mode)
CLI: Commander.js + @clack/prompts
Dashboard: Vite + Vanilla TS
Testing: Vitest (32 tests)

License

MIT