@humanclaw/humanclaw 1.1.4 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +48 -41
  2. package/README_EN.md +47 -40
  3. package/dist/index.js +221 -73
  4. package/dist/index.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -4,7 +4,6 @@
4
4
 
5
5
  **碳基节点编排框架 —— 将人类抽象为分布式 Worker 节点**
6
6
 
7
- [![CI](https://github.com/humanclaw/humanclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/humanclaw/humanclaw/actions/workflows/ci.yml)
8
7
  [![npm](https://img.shields.io/npm/v/@humanclaw/humanclaw)](https://www.npmjs.com/package/@humanclaw/humanclaw)
9
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
10
9
 
@@ -18,7 +17,9 @@
18
17
 
19
18
  ## 概述
20
19
 
21
- HumanClaw 是一个碳基节点编排框架。系统将真实人类抽象为 Agent（碳基节点），将现实中的任务派发与结果收集抽象为进程的**挂起（Suspend）**与**恢复（Resume）**，最终将碳基节点产生的结构化结果组装并提交给上游数字系统（如 OpenClaw），完成赛博世界与碳基世界的闭环。
20
+ HumanClaw 是一个碳基节点编排框架。系统将真实人类抽象为 Agent（碳基节点），将现实中的任务派发与结果收集抽象为进程的**挂起（Suspend）**与**恢复（Resume）**。
21
+
22
+ 核心流程：输入自然语言需求 → 选人 → AI 自动规划（拆任务 + 生成话术 + 设 DDL）→ 确认分发 → 收交付物 → AI 聚合审查。
22
23
 
23
24
  ## 核心架构
24
25
 
@@ -30,17 +31,17 @@ HumanClaw 是一个碳基节点编排框架。系统将真实人类抽象为 Age
30
31
  │ │ Resume + Result │ │
31
32
  └─────┬───────┘ └──────────────┘
32
33
  │
33
- │ Aggregate
34
+ │ AI Review
34
35
  ▼
35
36
  ┌─────────────┐
36
- │ OpenClaw │
37
- │ (数字生命) │
37
+ │ LLM 审查 │
38
+ │ (Claude/GPT)│
38
39
  └─────────────┘
39
40
  ```
40
41
 
41
- - **Master 节点**：解析需求，拆解为无依赖的扁平 TODO 列表，分发给碳基节点
42
+ - **Master 节点**：输入需求，AI 自动拆解为独立子任务，分发给碳基节点
42
43
  - **Worker 节点 (HumanAgent)**：接收带 `trace_id` 的独立任务，在碳基世界异步执行
43
- - **状态机与存储**：SQLite 本地持久化，保存上下文快照，释放系统内存
44
+ - **AI 审查**：所有任务完成后，LLM 自动审查交付质量并生成报告
44
45
 
45
46
  ## 快速开始
46
47
 
@@ -65,16 +66,17 @@ humanclaw agent add
65
66
  # 交互式录入：节点名称、技能标签
66
67
  ```
67
68
 
68
- ### 查看算力池
69
+ ### AI 规划任务
69
70
 
70
71
  ```bash
71
- humanclaw agent list
72
+ humanclaw plan "完成首页重构，包括导航栏和页脚的响应式改版"
73
+ # AI 自动拆解任务、匹配碳基节点、生成话术和 DDL
72
74
  ```
73
75
 
74
- ### 查看任务状态
76
+ ### 查看算力池
75
77
 
76
78
  ```bash
77
- humanclaw status
79
+ humanclaw agent list
78
80
  ```
79
81
 
80
82
  ## API 接口
@@ -84,28 +86,21 @@ humanclaw status
84
86
  | `GET` | `/api/v1/nodes/status` | 碳基算力池状态 |
85
87
  | `POST` | `/api/v1/nodes` | 注册碳基节点 |
86
88
  | `PATCH` | `/api/v1/nodes/:id/status` | 更新节点状态 |
89
+ | `POST` | `/api/v1/jobs/plan` | AI 智能规划（不分发） |
87
90
  | `POST` | `/api/v1/jobs/create` | 创建并分发任务 |
88
91
  | `GET` | `/api/v1/jobs/active` | 获取看板数据 |
89
92
  | `POST` | `/api/v1/tasks/resume` | 提交交付物，触发恢复 |
90
93
  | `POST` | `/api/v1/tasks/reject` | 打回重做 |
91
- | `POST` | `/api/v1/jobs/:id/sync` | 聚合结果同步至 OpenClaw |
94
+ | `POST` | `/api/v1/jobs/:id/review` | AI 聚合审查交付质量 |
95
+ | `GET` | `/api/v1/config` | 获取 LLM 配置 |
96
+ | `PUT` | `/api/v1/config` | 更新 LLM 配置 |
92
97
 
93
- ### 创建任务示例
98
+ ### AI 规划示例
94
99
 
95
100
  ```bash
96
- curl -X POST http://localhost:2026/api/v1/jobs/create \
101
+ curl -X POST http://localhost:2026/api/v1/jobs/plan \
97
102
  -H "Content-Type: application/json" \
98
- -d '{
99
- "original_prompt": "完成首页重构",
100
- "openclaw_callback": "",
101
- "tasks": [
102
- {
103
- "assignee_id": "emp_xxxxxxxx",
104
- "todo_description": "实现响应式导航栏",
105
- "deadline": "2026-03-28T18:00:00Z"
106
- }
107
- ]
108
- }'
103
+ -d '{ "prompt": "完成首页重构" }'
109
104
  ```
110
105
 
111
106
  ### 提交交付物
@@ -115,7 +110,7 @@ curl -X POST http://localhost:2026/api/v1/tasks/resume \
115
110
  -H "Content-Type: application/json" \
116
111
  -d '{
117
112
  "trace_id": "TK-9527",
118
- "result_data": { "text": "导航栏已完成，支持移动端适配" }
113
+ "result_data": { "text": "https://github.com/org/repo/pull/42" }
119
114
  }'
120
115
  ```
121
116
 
@@ -123,17 +118,34 @@ curl -X POST http://localhost:2026/api/v1/tasks/resume \
123
118
 
124
119
  Web 看板包含三个核心视图：
125
120
 
126
- - **碳基算力池监控** — 实时查看碳基节点状态（🟢空闲 🟡忙碌 🔴离线 🟣崩溃）
127
- - **碳基编排大盘** — 任务 Kanban（已分发 / 已超时 / 已交付）+ Job 进度条
121
+ - **碳基算力池** — 实时查看碳基节点状态（🟢空闲 🟡忙碌 🔴离线 🟣崩溃），一键添加/删除节点
122
+ - **碳基编排大盘** — AI 智能规划 + 任务 Kanban + 可交互任务卡片（点击直接提交交付/打回）+ AI 聚合审查
128
123
  - **I/O 交付终端** — 输入 trace_id 和交付载荷，触发系统恢复
129
124
 
125
+ ### AI 功能
126
+
127
+ - **智能规划** — 输入需求，AI 自动拆任务、匹配碳基节点、生成布置话术、设 DDL（可调）
128
+ - **聚合审查** — 全部交付后，AI 审查每个交付物质量（支持 GitHub PR/Commit/Issue URL），生成评分报告
129
+ - **可配置 LLM** — 支持 Claude / OpenAI，可自定义 Base URL 接入私有模型服务（vLLM / Ollama / Azure）
130
+
130
131
  ## 核心工作流
131
132
 
132
- 1. **镜像封装** — 录入物理成员信息，构建碳基算力池
133
- 2. **拆分分发** — Master 拆解任务，绑定 Agent，生成 trace_id
134
- 3. **挂起快照** — 上下文序列化持久化，主控进入休眠
135
- 4. **异步恢复** — 碳基节点提交产出物，系统唤醒 Job
136
- 5. **聚合闭环** — 所有子任务完成后，打包提交 OpenClaw
133
+ 1. **镜像封装** — 录入碳基成员信息，构建碳基算力池
134
+ 2. **AI 规划** — 输入需求，AI 拆解任务、匹配节点、生成话术和 DDL
135
+ 3. **确认分发** — 预览规划结果，调整 DDL，确认后一键分发
136
+ 4. **异步恢复** — 碳基节点提交交付物（支持 GitHub URL），系统唤醒 Job
137
+ 5. **AI 审查** — 所有子任务完成后，LLM 审查交付质量并生成报告
138
+
139
+ ## 环境变量
140
+
141
+ | 变量 | 默认值 | 说明 |
142
+ |------|--------|------|
143
+ | `HUMANCLAW_LLM_PROVIDER` | `claude` | LLM 提供商：`claude` 或 `openai` |
144
+ | `HUMANCLAW_LLM_API_KEY` | - | LLM API Key（使用 AI 功能时必填） |
145
+ | `HUMANCLAW_LLM_MODEL` | 按 provider | 可选覆盖模型名 |
146
+ | `HUMANCLAW_LLM_BASE_URL` | 官方地址 | 自定义 API 地址（私有部署） |
147
+
148
+ > Dashboard 设置面板也可以配置以上参数，优先级高于环境变量。
137
149
 
138
150
  ## 数据模型
139
151
 
@@ -154,12 +166,6 @@ interface HumanTask {
154
166
  status: TaskStatus; // PENDING | DISPATCHED | RESOLVED | OVERDUE
155
167
  result_data: unknown;
156
168
  }
157
-
158
- interface OrchestrationJob {
159
- job_id: string;
160
- original_prompt: string;
161
- openclaw_callback: string;
162
- }
163
169
  ```
164
170
 
165
171
  ## 开发
@@ -178,9 +184,10 @@ npm run lint # 类型检查
178
184
  - **Runtime**: Node.js 22+, TypeScript (ESM, strict)
179
185
  - **API**: Express v5
180
186
  - **Storage**: SQLite (better-sqlite3, WAL mode)
187
+ - **LLM**: Claude / OpenAI（原生 fetch，零依赖）
181
188
  - **CLI**: Commander.js + @clack/prompts
182
- - **Dashboard**: Vite + Vanilla TS
183
- - **Testing**: Vitest (32 tests)
189
+ - **Dashboard**: 内联 HTML（无需构建）
190
+ - **Testing**: Vitest (40 tests)
184
191
 
185
192
  ## License
186
193
 
package/README_EN.md CHANGED
@@ -4,7 +4,6 @@
4
4
 
5
5
  **Carbon-Based Node Orchestration Framework — Humans as Distributed Worker Nodes**
6
6
 
7
- [![CI](https://github.com/humanclaw/humanclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/humanclaw/humanclaw/actions/workflows/ci.yml)
8
7
  [![npm](https://img.shields.io/npm/v/@humanclaw/humanclaw)](https://www.npmjs.com/package/@humanclaw/humanclaw)
9
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
10
9
 
@@ -18,7 +17,9 @@
18
17
 
19
18
  ## Overview
20
19
 
21
- HumanClaw is a carbon-based node orchestration framework. The system abstracts real humans as Agents (carbon-based nodes), models task dispatch and result collection as process **Suspend** and **Resume**, and ultimately assembles structured results from carbon-based nodes to submit to upstream digital systems (e.g., OpenClaw), closing the loop between the cyber world and the carbon-based world.
20
+ HumanClaw is a carbon-based node orchestration framework. The system abstracts real humans as Agents (carbon-based nodes), models task dispatch and result collection as process **Suspend** and **Resume**.
21
+
22
+ Core flow: natural language input → select people → AI auto-plans (breaks down tasks + generates briefings + sets deadlines) → confirm dispatch → collect deliverables → AI aggregated review.
22
23
 
23
24
  ## Core Architecture
24
25
 
@@ -30,17 +31,17 @@ HumanClaw is a carbon-based node orchestration framework. The system abstracts r
30
31
  │ │ Resume + Result │ │
31
32
  └─────┬───────┘ └──────────────┘
32
33
  │
33
- │ Aggregate
34
+ │ AI Review
34
35
  ▼
35
36
  ┌─────────────┐
36
- │ OpenClaw │
37
- │ (Digital AI)│
37
+ │ LLM Review │
38
+ │ (Claude/GPT)│
38
39
  └─────────────┘
39
40
  ```
40
41
 
41
- - **Master Node**: Parses requirements, breaks them into flat, independent TODOs, and dispatches to carbon-based nodes
42
+ - **Master Node**: Input requirements, AI auto-breaks them into independent sub-tasks, dispatches to carbon-based nodes
42
43
  - **Worker Node (HumanAgent)**: Receives independent tasks with a `trace_id`, executes asynchronously in the carbon-based world
43
- - **State Machine & Storage**: SQLite local persistence, saves context snapshots, frees system memory
44
+ - **AI Review**: After all tasks complete, LLM reviews deliverable quality and generates a report
44
45
 
45
46
  ## Quick Start
46
47
 
@@ -65,16 +66,17 @@ humanclaw agent add
65
66
  # Interactive prompts for: node name, capability tags
66
67
  ```
67
68
 
68
- ### View Compute Pool
69
+ ### AI Task Planning
69
70
 
70
71
  ```bash
71
- humanclaw agent list
72
+ humanclaw plan "Rebuild the homepage with responsive navbar and footer"
73
+ # AI auto-breaks tasks, matches nodes, generates briefings and deadlines
72
74
  ```
73
75
 
74
- ### Check Task Status
76
+ ### View Compute Pool
75
77
 
76
78
  ```bash
77
- humanclaw status
79
+ humanclaw agent list
78
80
  ```
79
81
 
80
82
  ## API Endpoints
@@ -84,28 +86,21 @@ humanclaw status
84
86
  | `GET` | `/api/v1/nodes/status` | Carbon compute pool status |
85
87
  | `POST` | `/api/v1/nodes` | Register carbon-based node |
86
88
  | `PATCH` | `/api/v1/nodes/:id/status` | Update node status |
89
+ | `POST` | `/api/v1/jobs/plan` | AI task planning (does not dispatch) |
87
90
  | `POST` | `/api/v1/jobs/create` | Create and dispatch job |
88
91
  | `GET` | `/api/v1/jobs/active` | Get kanban data |
89
92
  | `POST` | `/api/v1/tasks/resume` | Submit deliverable, trigger resume |
90
93
  | `POST` | `/api/v1/tasks/reject` | Reject and retry |
91
- | `POST` | `/api/v1/jobs/:id/sync` | Aggregate results and sync to OpenClaw |
94
+ | `POST` | `/api/v1/jobs/:id/review` | AI aggregated review of deliverables |
95
+ | `GET` | `/api/v1/config` | Get LLM configuration |
96
+ | `PUT` | `/api/v1/config` | Update LLM configuration |
92
97
 
93
- ### Create Job Example
98
+ ### AI Planning Example
94
99
 
95
100
  ```bash
96
- curl -X POST http://localhost:2026/api/v1/jobs/create \
101
+ curl -X POST http://localhost:2026/api/v1/jobs/plan \
97
102
  -H "Content-Type: application/json" \
98
- -d '{
99
- "original_prompt": "Rebuild the homepage",
100
- "openclaw_callback": "",
101
- "tasks": [
102
- {
103
- "assignee_id": "emp_xxxxxxxx",
104
- "todo_description": "Implement responsive navbar",
105
- "deadline": "2026-03-28T18:00:00Z"
106
- }
107
- ]
108
- }'
103
+ -d '{ "prompt": "Rebuild the homepage" }'
109
104
  ```
110
105
 
111
106
  ### Submit Deliverable
@@ -115,7 +110,7 @@ curl -X POST http://localhost:2026/api/v1/tasks/resume \
115
110
  -H "Content-Type: application/json" \
116
111
  -d '{
117
112
  "trace_id": "TK-9527",
118
- "result_data": { "text": "Navbar complete, mobile-responsive" }
113
+ "result_data": { "text": "https://github.com/org/repo/pull/42" }
119
114
  }'
120
115
  ```
121
116
 
@@ -123,17 +118,34 @@ curl -X POST http://localhost:2026/api/v1/tasks/resume \
123
118
 
124
119
  The web dashboard includes three core views:
125
120
 
126
- - **Carbon Compute Pool Monitor** — Real-time carbon-based node status (🟢Idle 🟡Busy 🔴Offline 🟣OOM)
127
- - **Carbon Orchestration Pipeline** — Task Kanban (Dispatched / Overdue / Resolved) + Job progress bars
121
+ - **Carbon Compute Pool** — Real-time carbon-based node status (🟢Idle 🟡Busy 🔴Offline 🟣OOM), add/remove nodes
122
+ - **Carbon Orchestration Pipeline** — AI planning + Task Kanban + interactive task cards (click to submit/reject) + AI review
128
123
  - **I/O Resolution Terminal** — Input trace_id and payload to trigger system resume
129
124
 
125
+ ### AI Features
126
+
127
+ - **Smart Planning** — Input requirements, AI auto-breaks tasks, matches nodes, generates briefings, sets adjustable deadlines
128
+ - **Aggregated Review** — After all deliveries, AI reviews each deliverable (supports GitHub PR/Commit/Issue URLs), generates quality report
129
+ - **Configurable LLM** — Supports Claude / OpenAI, custom Base URL for private deployments (vLLM / Ollama / Azure)
130
+
130
131
  ## Core Workflow
131
132
 
132
133
  1. **Agent Encapsulation** — Register human members, build the carbon compute pool
133
- 2. **Dispatch** — Master breaks down tasks, binds Agents, generates trace_ids
134
- 3. **Suspend & Snapshot** — Serialize context to persistence, main process hibernates
135
- 4. **Async Resume** — Carbon-based nodes submit deliverables, system wakes up the Job
136
- 5. **Aggregation** — When all sub-tasks complete, package and submit to OpenClaw
134
+ 2. **AI Planning** — Input requirements, AI breaks tasks, matches nodes, generates briefings and deadlines
135
+ 3. **Confirm Dispatch** — Preview plan, adjust deadlines, one-click dispatch
136
+ 4. **Async Resume** — Carbon-based nodes submit deliverables (supports GitHub URLs), system wakes up the Job
137
+ 5. **AI Review** — When all sub-tasks complete, LLM reviews deliverable quality and generates a report
138
+
139
+ ## Environment Variables
140
+
141
+ | Variable | Default | Description |
142
+ |----------|---------|-------------|
143
+ | `HUMANCLAW_LLM_PROVIDER` | `claude` | LLM provider: `claude` or `openai` |
144
+ | `HUMANCLAW_LLM_API_KEY` | - | LLM API Key (required for AI features) |
145
+ | `HUMANCLAW_LLM_MODEL` | per provider | Optional model override |
146
+ | `HUMANCLAW_LLM_BASE_URL` | official | Custom API URL (private deployments) |
147
+
148
+ > Dashboard settings panel can also configure these, with higher priority than env vars.
137
149
 
138
150
  ## Data Models
139
151
 
@@ -154,12 +166,6 @@ interface HumanTask {
154
166
  status: TaskStatus; // PENDING | DISPATCHED | RESOLVED | OVERDUE
155
167
  result_data: unknown;
156
168
  }
157
-
158
- interface OrchestrationJob {
159
- job_id: string;
160
- original_prompt: string;
161
- openclaw_callback: string;
162
- }
163
169
  ```
164
170
 
165
171
  ## Development
@@ -178,9 +184,10 @@ npm run lint # Type check
178
184
  - **Runtime**: Node.js 22+, TypeScript (ESM, strict)
179
185
  - **API**: Express v5
180
186
  - **Storage**: SQLite (better-sqlite3, WAL mode)
187
+ - **LLM**: Claude / OpenAI (native fetch, zero dependencies)
181
188
  - **CLI**: Commander.js + @clack/prompts
182
- - **Dashboard**: Vite + Vanilla TS
183
- - **Testing**: Vitest (32 tests)
189
+ - **Dashboard**: Inline HTML (no build step)
190
+ - **Testing**: Vitest (40 tests)
184
191
 
185
192
  ## License
186
193