@harness.farm/whipflow 0.2.11 → 0.2.12

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 (3) hide show
  1. package/README.md +391 -7
  2. package/bin/whipflow +0 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,29 +1,188 @@
1
- # whipflow
1
+ # WhipFlow
2
2
 
3
- AI workflow automation for [harness.farm](https://harness.farm).
3
+ 确定性 AI 工作流引擎 [ClawFirm](https://clawfirm.dev) 的核心运行时
4
4
 
5
- ## Setup
5
+ Deterministic AI Workflow Engine — the core runtime of [ClawFirm](https://clawfirm.dev)
6
+
7
+ ---
8
+
9
+ ## 简介 / About
10
+
11
+ WhipFlow 使用自定义的 `.whip` DSL 编排多 AI agent 协作工作流。它是 ClawFirm「一人公司自动化引擎」中实际执行任务的核心组件。
12
+
13
+ WhipFlow orchestrates multi-agent AI workflows using a custom `.whip` DSL. It is the core execution component of ClawFirm's "one-person company automation engine."
14
+
15
+ **核心能力 / Core Capabilities:**
16
+
17
+ - 多 agent 角色定义(不同模型、不同工具权限) / Multi-agent roles (different models, different tool permissions)
18
+ - 顺序 / 条件 / 循环执行 / Sequential, conditional, and loop execution
19
+ - 变量传递和上下文拼接 / Variable passing and context chaining
20
+ - 自动校验循环(validator agent loop)/ Auto-validation loops
21
+ - JSON-line 事件协议(对接 Tauri 桌面端)/ JSON-line event protocol (Tauri desktop integration)
22
+
23
+ ---
24
+
25
+ ## 安装 / Installation
26
+
27
+ ```bash
28
+ # 全局安装 / Global install
29
+ npm install -g @harness.farm/whipflow
30
+
31
+ # 或通过 ClawFirm 安装全套工具 / Or install via ClawFirm
32
+ npm install -g clawfirm
33
+ clawfirm install
34
+ ```
35
+
36
+ **本地开发 / Local development:**
6
37
 
7
38
  ```bash
8
39
  bun install
40
+ bun run dev # 开发模式 / Dev mode
41
+ bun run build # 编译为单文件 / Compile to single binary
9
42
  ```
10
43
 
11
- ## Run a flow
44
+ ---
45
+
46
+ ## CLI 命令 / CLI Commands
12
47
 
13
48
  ```bash
49
+ <<<<<<< HEAD
14
50
  whipflow run flows/hello.whip
51
+ =======
52
+ whipflow run <file.whip> # 执行工作流 / Execute a workflow
53
+ whipflow validate <file.whip> # 校验语法 / Validate syntax
54
+ whipflow compile <file.whip> # 查看编译结果 / Show compiled form
55
+ whipflow install-skills # 安装 skills 到 Claude Code / Install skills to Claude Code
56
+ whipflow install-skills --force # 强制覆盖 / Force overwrite
57
+ whipflow help # 帮助 / Help
58
+ >>>>>>> b3e30d9 (Update README with comprehensive bilingual project documentation)
59
+ ```
60
+
61
+ ---
62
+
63
+ ## .whip DSL 语法示例 / DSL Syntax Example
64
+
65
+ ```whip
66
+ agent researcher:
67
+ provider: "claude-code"
68
+ model: opus
69
+ tools: ["bash", "read", "write"]
70
+ prompt: "你是一位市场研究专家。"
71
+
72
+ agent writer:
73
+ provider: "claude-code"
74
+ model: sonnet
75
+ tools: ["bash", "write"]
76
+ prompt: "将收到的内容写入指定文件。"
77
+
78
+ agent validator:
79
+ provider: "claude-code"
80
+ model: haiku
81
+ tools: ["bash", "read"]
82
+ prompt: "审核内容质量,输出 APPROVED 或 NEEDS_REVISION: [原因]。"
83
+
84
+ let research = session: researcher
85
+ prompt: "分析目标市场的竞争格局..."
86
+
87
+ let check = session: validator
88
+ prompt: "审核研究报告质量:{research}"
89
+
90
+ loop until **check 包含 APPROVED** (max: 2):
91
+ research = session: researcher
92
+ prompt: "根据审核意见修订:{check}"
93
+ check = session: validator
94
+ prompt: "重新审核:{research}"
95
+
96
+ session: writer
97
+ prompt: "将最终报告写入 docs/report.md:{research}"
15
98
  ```
16
99
 
17
- ## Install skills into Claude Code
100
+ ---
101
+
102
+ ## 项目结构 / Project Structure
103
+
104
+ ```
105
+ whipflow/
106
+ ├── bin/whipflow.ts CLI 入口 / CLI entry point
107
+ ├── commands/ Claude Code skill 命令 / Skill commands
108
+ │ ├── run.md /run 命令 / Run command
109
+ │ └── validate.md /validate 命令 / Validate command
110
+ ├── src/social/ 自媒体自动化引擎 / Social media automation engine
111
+ │ ├── pipeline-orchestrator.ts 12 阶段流水线编排 / 12-stage pipeline orchestrator
112
+ │ ├── scheduler.ts 定时调度器 / Scheduled task runner
113
+ │ ├── content-creator.ts 多平台内容生成 / Multi-platform content creator
114
+ │ ├── publish-orchestrator.ts 发布编排 / Publish orchestrator
115
+ │ ├── cdp-client.ts Chrome DevTools Protocol 客户端 / CDP client
116
+ │ ├── cdp-session.ts 浏览器 Cookie 持久化 / Browser session persistence
117
+ │ ├── yaml-runner.ts YAML 步骤执行器 / YAML step executor
118
+ │ ├── db.ts SQLite 数据层(7 张表)/ SQLite data layer (7 tables)
119
+ │ ├── cli.ts 社媒 CLI 入口 / Social CLI entry
120
+ │ └── ... 20+ 个功能模块 / 20+ functional modules
121
+ ├── adapters/ 平台自动化适配器 / Platform automation adapters
122
+ │ └── x.yaml Twitter 完整适配器 / Twitter full adapter
123
+ ├── client/ Tauri 桌面应用「社媒运营助手」/ Tauri desktop app
124
+ │ ├── src-tauri/ Rust 后端 / Rust backend
125
+ │ └── src/ 前端(Vite + React)/ Frontend
126
+ ├── flows/ .whip 工作流文件 / Workflow files
127
+ ├── skills/ Claude Code skills 定义 / Skill definitions
128
+ │ ├── whipflow/SKILL.md WhipFlow skill
129
+ │ ├── remotion-video/SKILL.md 视频制作 skill / Video production skill
130
+ │ └── WORKFLOW.md 视频流水线编排文档 / Video pipeline doc
131
+ ├── macroflow/ Web 端 monorepo / Web monorepo
132
+ │ ├── packages/web/ Next.js 前端 / Frontend
133
+ │ ├── packages/server/ Fastify 后端 / Backend
134
+ │ └── packages/shared/ 共享模块(news + hyperliquid)/ Shared modules
135
+ ├── demo-video/ Remotion 演示视频项目 / Demo video project
136
+ ├── data/ 运行时数据 / Runtime data
137
+ ├── logs/ 运行日志 / Execution logs
138
+ ├── research-output/ AI 生成的调研文档 / AI-generated research docs
139
+ └── docs/ 品牌 / 竞品 / 内容策略 / Brand & strategy docs
140
+ ```
141
+
142
+ ---
143
+
144
+ ## 业务模块 / Business Modules
145
+
146
+ WhipFlow 为 ClawFirm 的七大业务模块提供工作流定义,每个模块遵循标准 5 文件结构:
147
+
148
+ WhipFlow provides workflow definitions for ClawFirm's seven business modules, each following a standard 5-file structure:
149
+
150
+ | 文件 / File | 职责 / Role | 运行时机 / When |
151
+ |---|---|---|
152
+ | `setup.whip` | 环境检查、API 验证、配置写入 / Env check, API validation, config | 首次 / First-time |
153
+ | `scan.whip` | 数据拉取、信号识别 / Data fetch, signal detection | 手动或定时 / Manual or scheduled |
154
+ | `trade.whip` | 风控检查、执行动作 / Risk check, execute action | 手动或定时 / Manual or scheduled |
155
+ | `monitor.whip` | 持续轮询、状态管理 / Continuous polling, state mgmt | 后台运行 / Background |
156
+ | `report.whip` | 统计指标、分析报告 / Stats, analysis report | 随时 / Anytime |
157
+
158
+ ---
159
+
160
+ ### 模块一览 / Module Overview
161
+
162
+ #### 1. saas — SaaS 软件出海 / SaaS Go-Global
163
+
164
+ 从竞品分析到 Product Hunt 发布的全流程自动化。
165
+
166
+ Full pipeline from competitor analysis to Product Hunt launch.
18
167
 
19
168
  ```bash
169
+ <<<<<<< HEAD
20
170
  whipflow install-skills
171
+ =======
172
+ whipflow run whips/saas/setup.whip # 竞品分析 + GTM 策略 / Competitor analysis + GTM strategy
173
+ whipflow run whips/saas/landing.whip # 英文落地页文案(A/B 版本)/ Landing page copy (A/B variants)
174
+ whipflow run whips/saas/acquire.whip # 多渠道获客 / Multi-channel acquisition
175
+ whipflow run whips/saas/launch.whip # Product Hunt 发布素材 + 小时级计划 / PH launch kit
176
+ whipflow run whips/saas/monitor.whip # 每日反馈监控 / Daily feedback monitoring
177
+ whipflow run whips/saas/report.whip # 增长周报 / Growth weekly report
178
+ >>>>>>> b3e30d9 (Update README with comprehensive bilingual project documentation)
21
179
  ```
22
180
 
23
- Then use `/whipflow` in any Claude Code session.
181
+ **获客渠道 / Acquisition channels:** Reddit, Hacker News, Cold Email, SEO Article
24
182
 
25
- ## Add a new flow
183
+ #### 2. hyperliquid 新闻驱动期货交易 / News-Driven Futures Trading
26
184
 
185
+ <<<<<<< HEAD
27
186
  Create a `.whip` file in `flows/` and run it with:
28
187
 
29
188
  ```bash
@@ -81,3 +240,228 @@ Project-level config in `.whipflow.json`:
81
240
 
82
241
  `defaultProvider` sets the provider for all sessions when not specified on the agent (default: `claude-code`).
83
242
  `conditionProvider` overrides the provider for `discretion` and `choice` evaluation only; falls back to `defaultProvider`.
243
+ =======
244
+ 用 Claude 评估加密货币新闻信号,在 Hyperliquid 自动开多/空。
245
+
246
+ Uses Claude to assess crypto news signals, auto-opens long/short on Hyperliquid.
247
+
248
+ ```bash
249
+ whipflow run whips/hyperliquid/setup.whip
250
+ whipflow run whips/hyperliquid/monitor.whip
251
+
252
+ # 或独立运行 / Or run standalone
253
+ HL_PRIVATE_KEY=0x... node scripts/hl-news-trader.js monitor
254
+ ```
255
+
256
+ **策略参数 / Strategy params:** 最多 4 仓位 / Max 4 positions, 3-5x 杠杆 / leverage, 5% 止损 / SL, 8% 止盈 / TP
257
+
258
+ #### 3. polymarket — 天气预测市场交易 / Weather Prediction Market Trading
259
+
260
+ 用 Open-Meteo 预报计算胜率,与 Polymarket 市场价比较,发现边缘时下单。
261
+
262
+ Calculates win probability via Open-Meteo forecasts, compares with market odds, bets when edge found.
263
+
264
+ ```bash
265
+ whipflow run whips/polymarket/setup.whip
266
+ whipflow run whips/polymarket/monitor.whip
267
+ ```
268
+
269
+ **回测指标 / Backtested:** 胜率 / Win rate 57.26%, Sharpe 3.60, 最大回撤 / Max drawdown 10.87%
270
+
271
+ #### 4. social-media — 社交媒体内容自动化 / Social Media Automation
272
+
273
+ AI 生成内容,自动发布到多个平台。
274
+
275
+ AI-generated content, auto-published to multiple platforms.
276
+
277
+ ```bash
278
+ whipflow run whips/social-media/setup.whip
279
+ whipflow run whips/social-media/daily-content.whip # 每日内容 / Daily content
280
+ whipflow run whips/social-media/daily-publish.whip # 多平台发布 / Multi-platform publish
281
+ whipflow run whips/social-media/comments.whip # 评论互动 / Comment management
282
+ whipflow run whips/social-media/weekly-report.whip # 周报 / Weekly report
283
+ whipflow run whips/social-media/repurpose.whip # 内容改写 / Content repurpose
284
+ ```
285
+
286
+ **平台 / Platforms:** 小红书, 微博, B站, Twitter, Telegram
287
+
288
+ #### 5. arbitrage — 电商跨平台套利 / Cross-Platform E-Commerce Arbitrage
289
+
290
+ 扫描价差,自动采购和上架。目标利润率 > 20%。
291
+
292
+ Scans price gaps, auto-purchases and lists. Target margin > 20%.
293
+
294
+ ```bash
295
+ whipflow run whips/arbitrage/setup.whip
296
+ whipflow run whips/arbitrage/scan.whip
297
+ whipflow run whips/arbitrage/buy.whip
298
+ whipflow run whips/arbitrage/report.whip
299
+ ```
300
+
301
+ **市场 / Markets:** 闲鱼↔拼多多(国内)/ eBay↔Amazon(海外)
302
+
303
+ #### 6. domains — 域名捡漏 / Domain Sniping
304
+
305
+ 扫描过期域名,自动注册,挂牌出售。
306
+
307
+ Scans expiring domains, auto-registers, lists for resale.
308
+
309
+ ```bash
310
+ whipflow run whips/domains/setup.whip
311
+ whipflow run whips/domains/scan.whip
312
+ whipflow run whips/domains/snipe.whip
313
+ whipflow run whips/domains/report.whip
314
+ ```
315
+
316
+ #### 7. amazon-affiliate — 亚马逊联盟营销 / Amazon Affiliate Marketing
317
+
318
+ 关键词研究 → AI 写 SEO 文章 → 自动发布 → 排名监控。
319
+
320
+ Keyword research → AI-written SEO articles → auto-publish → rank monitoring.
321
+
322
+ ```bash
323
+ whipflow run whips/amazon-affiliate/setup.whip
324
+ whipflow run whips/amazon-affiliate/research.whip
325
+ whipflow run whips/amazon-affiliate/write.whip
326
+ whipflow run whips/amazon-affiliate/publish.whip
327
+ whipflow run whips/amazon-affiliate/seo-monitor.whip
328
+ ```
329
+
330
+ ---
331
+
332
+ ## 创建新模块 / Create New Modules
333
+
334
+ `creator` 是 meta-whip,从自然语言描述自动生成完整的 whip 子目录。
335
+
336
+ `creator` is a meta-whip that auto-generates a complete whip subdirectory from a business description.
337
+
338
+ ```bash
339
+ cat > data/current-run.json << 'EOF'
340
+ {
341
+ "run_id": "create-001",
342
+ "name": "my-strategy",
343
+ "description": "监控 Reddit,识别热门话题,自动发布到 Twitter",
344
+ "apis": ["Reddit API", "Twitter API v2"]
345
+ }
346
+ EOF
347
+
348
+ whipflow run whips/creator/create.whip
349
+ # → whips/my-strategy/ (setup / scan / trade / monitor / report)
350
+ ```
351
+
352
+ ---
353
+
354
+ ## 自媒体引擎 / Social Media Engine
355
+
356
+ `src/social/` 包含独立于 .whip 工作流的 TypeScript 自动化引擎,可直接运行或通过 Tauri 桌面应用调用。
357
+
358
+ `src/social/` contains a standalone TypeScript automation engine, runnable directly or via the Tauri desktop app.
359
+
360
+ **12 阶段流水线 / 12-Stage Pipeline:**
361
+
362
+ ```
363
+ env-setup → account-config → competitive-analyst → strategy-planner
364
+ → content-calendar → content-creator → content-validator
365
+ → publish-orchestrator → analytics-collector → insights-engine
366
+ → comment-manager → weekly-reporter
367
+ ```
368
+
369
+ **浏览器自动化 / Browser Automation:**
370
+
371
+ 通过 Chrome DevTools Protocol 直连浏览器,支持 YAML 适配器驱动的自动化操作。
372
+
373
+ Direct browser connection via Chrome DevTools Protocol, with YAML adapter-driven automation.
374
+
375
+ ```bash
376
+ # 社媒 CLI / Social CLI
377
+ bun run src/social/cli.ts x search "claude ai"
378
+ bun run src/social/cli.ts xhs search "独立开发"
379
+ bun run src/social/cli.ts x post "Hello from WhipFlow!"
380
+ bun run src/social/cli.ts x like https://x.com/user/status/123
381
+
382
+ # 定时调度 / Scheduled runner
383
+ tsx src/social/scheduler.ts
384
+
385
+ # Tauri 桌面应用 / Tauri desktop app
386
+ cd client && npm run tauri dev
387
+ ```
388
+
389
+ ---
390
+
391
+ ## Skills 体系 / Skills System
392
+
393
+ WhipFlow 通过 `skillctl` 将 AI skills 同步到 Claude Code,使其在任何会话中可用。
394
+
395
+ WhipFlow syncs AI skills to Claude Code via `skillctl`, making them available in any session.
396
+
397
+ ```bash
398
+ whipflow install-skills
399
+ # 然后在 Claude Code 中使用 /whipflow
400
+ # Then use /whipflow in any Claude Code session
401
+ ```
402
+
403
+ **已有 Skills / Available Skills:**
404
+
405
+ | Skill | 说明 / Description |
406
+ |---|---|
407
+ | `whipflow` | WhipFlow DSL 语法参考和使用指南 / DSL syntax reference and usage guide |
408
+ | `remotion-video` | Remotion 视频制作 / Video production with Remotion |
409
+ | `social-publish/*` | 各平台内容创作(小红书/B站/抖音/Twitter + 算法指南 + 爆文模板)/ Platform-specific content creation |
410
+ | `video-skills/*` | AI 视频全链路(脚本→数字人→场景→TTS→拼接)/ Full video pipeline |
411
+
412
+ ---
413
+
414
+ ## 技术栈 / Tech Stack
415
+
416
+ | 层 / Layer | 技术 / Technology |
417
+ |---|---|
418
+ | 运行时 / Runtime | Bun (primary), Node.js |
419
+ | 语言 / Language | TypeScript |
420
+ | 工作流 DSL | `.whip` (OpenProse) |
421
+ | AI 模型 / AI Models | Claude API (opus / sonnet / haiku) |
422
+ | 数据库 / Database | SQLite (better-sqlite3) |
423
+ | 浏览器自动化 / Browser | Chrome DevTools Protocol (WebSocket) |
424
+ | 桌面 / Desktop | Tauri 2.0 (Rust + WebView) |
425
+ | Web | Next.js + Fastify (macroflow/) |
426
+ | 链上 / On-chain | viem (EVM) |
427
+ | 视频 / Video | Remotion |
428
+ | 密钥 / Secrets | openvault |
429
+ | 部署 / Deploy | Fly.io, Vercel |
430
+
431
+ ---
432
+
433
+ ## 密钥管理 / Secret Management
434
+
435
+ 推荐使用 `openvault` 管理所有密钥:
436
+
437
+ Recommended: use `openvault` for all secrets:
438
+
439
+ ```bash
440
+ openvault set clawfirm/anthropic-api-key
441
+ openvault set clawfirm/hl-private-key
442
+ openvault set clawfirm/polygon-private-key
443
+ # whip 文件自动读取 / whip files read automatically
444
+ ```
445
+
446
+ ---
447
+
448
+ ## 社区 / Community
449
+
450
+ - **Discord:** https://discord.gg/JNXz2utFW8
451
+ - **微信 / WeChat:** PpCiting
452
+ - **GitHub:** https://github.com/npc-live/clawfirm
453
+
454
+ ---
455
+
456
+ ## ⚠️ 免责声明 / Disclaimer
457
+
458
+ 本项目及其所有代码、工作流、策略仅供学习和技术演示之用,**不构成任何投资建议或财务咨询**。交易类模块可能导致本金亏损,使用者自行承担一切风险。项目按"原样"提供,不做任何明示或暗示的保证。
459
+
460
+ This project and all its code, workflows, and strategies are provided solely for educational and technical demonstration purposes. **Nothing constitutes investment advice or financial consulting.** Trading modules may result in loss of capital. Users bear all risks. Provided "AS IS" without warranty of any kind.
461
+
462
+ ---
463
+
464
+ ## License
465
+
466
+ MIT
467
+ >>>>>>> b3e30d9 (Update README with comprehensive bilingual project documentation)
package/bin/whipflow CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@harness.farm/whipflow",
3
- "version": "0.2.11",
3
+ "version": "0.2.12",
4
4
  "description": "AI workflow automation — harness.farm",
5
5
  "publishConfig": {
6
6
  "access": "public"