zclaw_openfang/docs/superpowers/specs/2026-04-01-zclaw-next-phase-strategy.md

ZCLAW 下一阶段战略设计：双轨增长计划

日期: 2026-04-01 状态: Review (Addressing feedback) 范围: 90 天双轨推进（产品力 + 商业化）

---

先决条件

本 90 天计划的 Day 1 以下列 pre-launch 门槛为前提：

• docker compose up 完整启动成功
• Admin V2 > 10 个测试通过
• Desktop > 5 个 store 测试通过
• Scheduler 是真实实现（非 stub）
• 零个 TypeScript/Rust 编译错误
• 反向代理 + 限流修复到位

当前状态：大部分已完成（参见 pre-launch dual-track design 2026-03-31）。若有个别未完成项，纳入 Day 1 的首批修复工作。

---

资源假设

• 开发模式：AI 辅助开发（Claude Code + Claude Agent SDK），人力非瓶颈
• 并行能力：Track A 和 Track B 可完全并行推进
• 工程量估算：见每阶段后附的预估时间
• 依赖关系：Track B 的 B3（上线验证）条件性依赖 Track A 的 A1（Hand 验证）完成

---

Context

ZCLAW 技术基础设施已建成 ~90%（11 个 Rust crate + Tauri 桌面端 + SaaS 后端），但商业变现路径从 0→1 尚未打通。当前系统拥有 9 个已启用 Hands（另有 2 个已禁用）、75 个 SKILL.md 技能定义、Pipeline DSL、完整的安全体系和 SaaS 后端——但这些能力尚未串联成一个让用户愿意付费的产品体验。

核心问题：技术基建完善，但用户无法在首次使用中体验到 ZCLAW 的核心价值（AI 真正干活），且缺乏从免费到付费的转化路径。

---

1. 战略定位

1.1 产品定义

ZCLAW = 面向中文知识工作者的 AI Agent OS

不是"又一个 ChatGPT 套壳"，而是"AI 真正帮你干活的操作系统"。

1.2 目标用户

三大目标群体（按优先级排序）：

群体一：教育行业（老师、教培机构）

• 场景：Quiz 生成、课件制作（Slideshow）、学生答疑、教案研究
• 痛点：重复性备课工作量大，个性化教学内容制作耗时
• 付费驱动力：提效降本，提升教学质量差异化
• 适配功能：Quiz Hand + Slideshow Hand + Researcher Hand + Pipeline 模板（教研→课件→测验）

群体二：医疗行业（行政管理工作为主）

• 场景：政策文件解读、会议纪要整理、数据报告生成、制度合规检查
• 痛点：行政文书工作繁重，政策更新频繁需快速跟进
• 付费驱动力：合规效率、减少人工错误、提升行政响应速度
• 适配功能：Collector Hand + Researcher Hand + 记忆系统 + Pipeline 模板（政策→摘要→报告）

群体三：设计行业（汕头特色产业：制衣、玩具的设计相关工作）

• 场景：竞品调研、趋势分析、设计素材收集、客户沟通辅助
• 痛点：信息分散，趋势追踪耗时，设计素材管理混乱
• 付费驱动力：加快设计决策，集中管理灵感来源，提升客户沟通效率
• 适配功能：Browser Hand + Collector Hand + Researcher Hand + Pipeline 模板（趋势→素材→方案）

共同特征：

• 对价格敏感但愿意为效率工具付费
• 发现工具的路径：同行推荐 > 社群分享 > 搜索
• 需要"开箱即用"的体验，不愿折腾技术配置

1.3 核心差异化

差异点	ZCLAW	竞品
性能	Rust 原生 ~40MB RAM	Electron 400MB+
自主能力	9 个已启用 Hands 真正执行任务	纯对话
工作流	Pipeline DSL 12 种 Action	无
中文生态	27+ LLM Provider 含国产模型	主要支持海外模型
安全	16 层防御，渗透测试通过	基础安全

1.4 混合战略路径

阶段 1 (0-3月): 产品力验证 + 计费闭环
    → 证明 Hands 真实可用 + 用户愿意付费

阶段 2 (3-6月): 规模化获客 + Token 加价
    → SaaS 网关做增量收入 + 知识工作者社区渗透

阶段 3 (6-12月): 生态构建
    → 技能市场 + Pipeline 模板社区 + 开发者平台

---

2. 6 个月目标

2.1 产品目标

• 用户首次 Hand 执行成功率 > 80%
• 7 天留存率 > 40%
• NPS > 30
• 5 个 Hands 通过 20+ 真实场景验证
• 20 个面向知识工作者的 Pipeline 模板

2.2 商业目标

• 免费→付费转化率 > 5%
• 10 个付费客户
• 首月 MRR 覆盖服务器成本
• 3 层订阅上线（Free / Pro / Team）

---

3. 90 天双轨工作计划

Track A：产品力（让用户"啊"的一刻可靠发生）

阶段 A1（Day 1-30）：首 60 秒体验

目标：新用户下载后 60 秒内看到 Hand 执行真实任务。 预估工程量：~40-50 小时

#	工作项	具体内容	关键文件	预估
A1.1	Hand 真实场景验证	验证 Researcher/Collector/Browser 在 20+ 真实场景下的执行成功率，记录失败模式	crates/zclaw-hands/src/hands/researcher.rs, collector.rs, browser.rs	15h
A1.2	引导式 Onboarding 串联	串联 AgentOnboardingWizard → SaaS 注册 → 首次 Hand 执行	desktop/src/components/AgentOnboardingWizard.tsx, desktop/src/components/FirstConversationPrompt.tsx	10h
A1.3	首次对话优化	FirstConversationPrompt 从闲聊提示改为可执行的 Hand 任务触发（如"帮我研究这个话题"）	desktop/src/components/FirstConversationPrompt.tsx	5h
A1.4	关键路径排错	消灭从安装到首次 Hand 执行链路上的所有崩溃和错误	全栈	10-20h

"成功率"定义：Hand 执行无错误完成，且生成符合预期 schema 的非空输出。

阶段 A2（Day 31-60）：让魔法可重复

目标：用户能独立完成端到端任务，记忆系统开始产生价值。 预估工程量：~35-45 小时

#	工作项	具体内容	关键文件	预估
A2.1	Hand 场景扩展	验证 Twitter/Slideshow/Clip 三个 Hand 的真实场景覆盖	crates/zclaw-hands/src/hands/twitter.rs, slideshow.rs, clip.rs	10h
A2.2	Pipeline 模板库	构建 10 个面向目标群体的模板：教育（教研→课件→测验、学情分析→报告）×3、医疗（政策→摘要→合规报告、会议→纪要→待办）×3、设计汕头（趋势→素材→方案、竞品→分析→推荐）×4	pipelines/ 目录扩展	8h
A2.3	记忆检索质量	Fact 提取 → 检索相关性的端到端优化，增加基准测试	crates/zclaw-growth/src/retrieval/, crates/zclaw-memory/src/fact.rs	10h
A2.4	Pipeline 结果预览	输出格式化打磨（图表/文档/幻灯片渲染）	desktop/src/components/pipeline/（待创建完善组件）	8-12h

注意：crates/zclaw-kernel/src/export/ 当前仅支持 Classroom（幻灯片）导出。Pipeline 输出导出需要扩展该模块。

阶段 A3（Day 61-90）：增长飞轮

目标：外部用户验证，收集真实反馈，启动增长循环。 预估工程量：~25-30 小时（不含 Beta 运营时间）

#	工作项	具体内容	关键文件	预估
A3.1	20 人外部 Beta	真实用户全流程验证（见 Beta 计划附录）	—	运营工作
A3.2	结果导出/分享	Pipeline 输出生成可分享页面或 PDF（扩展 export 模块）	crates/zclaw-kernel/src/export/	10h
A3.3	轻量配额提示	基于 usage_quotas 的用量追踪，接近配额时友好提示	crates/zclaw-saas/src/telemetry/ + billing/quotas.rs	5h
A3.4	失败模式迭代	收集 Beta 失败场景，定向修复最高频问题	—	10-15h

Beta 招募计划：

• 渠道：教育（教师社群、教培机构直推）× 8 人 + 医疗（医院行政科室直推）× 6 人 + 设计汕头（制衣/玩具设计公司直推）× 6 人
• Onboarding：使用 A1.2 构建的新用户引导流程
• 数据收集：Telemetry 自动采集 + 结束后 NPS 问卷（1-10 分 + 开放反馈）
• 成功标准：> 12/20 人评分 ≥ 7 + 提出具体改进建议

Track B：商业化（SaaS 从成本中心变成利润中心）

阶段 B1（Day 1-30）：计费基础设施

目标：数据库和后端支持订阅、计费、配额。 预估工程量：~60-80 小时（Track B 的关键路径，复杂度最高）

#	工作项	具体内容	关键文件	预估
B1.1	计费表结构	新增 5 张表 + 索引 + 种子数据	crates/zclaw-saas/src/db.rs + migration	8h
B1.2	支付宝/微信支付集成	Webhook 回调处理（含签名验证和幂等性）、支付订单创建、支付状态查询、退款	新增 crates/zclaw-saas/src/billing/（7 个文件）	30-40h
B1.3	配额中间件	Relay 请求前检查订阅状态和配额，未订阅/超限则拒绝	crates/zclaw-saas/src/relay/service.rs	10h
B1.4	计划定义 API	CRUD for subscription plans, 与 RBAC 权限联动	crates/zclaw-saas/src/auth/	8h
B1.5	用量聚合 Worker	从 usage_records 聚合到 usage_quotas 的后台任务	crates/zclaw-saas/src/workers/ 新增	5h

⚠️ 关键路径警告：B1.2（Stripe 集成）是整个 Track B 的瓶颈。建议优先完成 B1.1 表结构后立即开始 B1.2，与 B1.3/B1.4 并行。

阶段 B2（Day 31-60）：付费前端

目标：桌面端和 Web 端都能完成订阅购买和管理。

#	工作项	具体内容	关键文件
B2.1	定价页 + 结账	桌面端内的订阅购买体验（嵌入式 Stripe Checkout）	desktop/src/components/ 新增
B2.2	订阅管理	扩展 SaaS Settings 组件，显示当前计划、用量、账单历史	desktop/src/components/ SaaS 相关组件
B2.3	Admin 用量分析	Admin Dashboard 增加 Usage 分析、收入追踪	admin-v2/src/pages/Usage.tsx 扩展
B2.4	14 天试用流程	注册即开 Pro 功能，14 天后降级	crates/zclaw-saas/src/auth/ + 桌面端

阶段 B3（Day 61-90）：上线验证

目标：真实付费验证，获取第一批付费客户。

#	工作项	具体内容	关键文件
B3.1	3 层订阅上线	Free / Pro / Team 三层定价正式发布	—
B3.2	10 个付费 Beta	定向邀请 + 折扣价验证付费意愿	—
B3.3	转化分析	追踪哪些功能驱动付费转化，优化漏斗	crates/zclaw-saas/src/telemetry/
B3.4	发票生成	月度自动发票，支持中文发票信息	crates/zclaw-saas/src/billing/

---

4. 三层定价设计

4.1 订阅层级

层级	月价	年价（8折）	包含
Free	¥0	¥0	本地模型对话 + 2 个 Hand (Quiz/Speech) + 3 个 Pipeline 模板 + 基础记忆
Pro	¥49	¥470	SaaS Relay 代理 + 所有 Hands + 无限 Pipeline + 记忆系统 + 优先模型 + 14 天试用
Team	¥199/人	¥1,900/人	Pro 全部 + 多人管理 + Admin 面板 + API Key 统管 + 优先支持 + 团队共享模板

4.2 Token 用量计费（叠加在 Pro/Team 上）

• Relay 代理的 Token 用量按模型定价元数据（models.pricing_input / pricing_output）计算
• 每月包含基础额度（Pro: 100 万 input tokens）
• 超出部分按成本 + 20% 加价
• 用量实时追踪，接近额度时提醒

4.3 Free → Pro 转化策略

• 注册即开 14 天 Pro 试用（无需信用卡）
• 试用期内体验完整功能
• 到期前 3 天 + 1 天发送提醒
• 降级后保留数据，仅限制功能访问
• Free 用户在触发 Pro 功能时显示升级提示（非阻断）

4.4 Free 层功能限制执行策略

核心问题：Hands 在 Tauri 桌面端本地执行，SaaS 后端无法直接拦截。需采用客户端许可证检查策略。

执行方案：桌面端 SaaS 许可证检查

1. 启动时验证：桌面端启动时调用 SaaS API /api/v1/account/subscription 获取当前订阅状态
2. 本地缓存：订阅状态缓存在本地（TTL 24 小时），离线时使用缓存
3. 功能门控：根据订阅计划的 features JSONB 字段决定哪些 Hands/Pipeline 可用
4. 不阻断本地模型：Free 用户可使用本地模型（Ollama）和所有本地功能，仅限制 SaaS 依赖功能
5. 信任模型：初期采用"软限制"——功能标记 + 提示升级，不做硬阻断。硬限制仅对 SaaS Relay 请求执行

具体限制矩阵：

功能	Free	Pro	Team
本地模型对话	✅ 无限	✅ 无限	✅ 无限
SaaS Relay 代理	❌ 硬限制	✅ 含额度	✅ 含额度
Hands（本地执行）	2 个（Quiz/Speech），其余软限制提示	✅ 全部	✅ 全部
Pipeline 模板	3 个基础模板	✅ 无限	✅ 无限 + 团队共享
记忆系统	基础（最近 30 天）	✅ 完整	✅ 完整
Admin 面板	❌	❌	✅

4.5 试用期降级行为

场景	行为
试用期间创建的 Pro 数据（Pipeline、Agent 模板）	降级后变为只读（可查看不可编辑），升级后恢复
试用期间执行的 Hand 结果	永久保留，不删除
用户注册后从未登录	14 天后试用到期，下次登录看到 Free 体验 + 升级提示
用户卸载重装	试用期绑定 account（非 device），不可重复获取
用户信用卡被拒	7 天宽限期（past_due），之后降级为 Free

---

5. 技术架构变更

5.1 新增数据库表

金额单位约定：所有金额以人民币分（1/100 CNY）存储。人民币为双小数货币。 迁移命名约定：遵循现有格式 YYYYMMDDHHMMSS_name.sql（如 20260402000001_billing_tables.sql）。

-- 订阅计划
CREATE TABLE plans (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(50) NOT NULL UNIQUE,     -- free, pro, team
    display_name VARCHAR(100) NOT NULL,
    price_monthly INTEGER NOT NULL,        -- 单位：人民币分
    price_yearly INTEGER NOT NULL,         -- 单位：人民币分，舍入规则：向上取整到分
    features JSONB NOT NULL,               -- {"hands": ["quiz","speech"], "pipelines": 3, "memory": false, "relay": false}
    token_quota_monthly BIGINT,            -- 每月 Token 额度（null = 无限）
    hand_limit INTEGER,                    -- 可用 Hand 数量（null = 全部）
    pipeline_limit INTEGER,                -- 可用 Pipeline 模板数（null = 无限）
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 用户订阅
CREATE TABLE subscriptions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id),
    plan_id UUID NOT NULL REFERENCES plans(id),
    status VARCHAR(20) NOT NULL,           -- active, trialing, past_due, canceled
    stripe_customer_id VARCHAR(100),
    stripe_subscription_id VARCHAR(100),
    current_period_start TIMESTAMPTZ,
    current_period_end TIMESTAMPTZ,
    trial_end TIMESTAMPTZ,
    canceled_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- 防止同一用户多个活跃订阅
CREATE UNIQUE INDEX idx_subscriptions_one_active
    ON subscriptions (account_id) WHERE status IN ('active', 'trialing');

-- 发票
CREATE TABLE invoices (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id),
    subscription_id UUID REFERENCES subscriptions(id),
    stripe_invoice_id VARCHAR(100),
    amount INTEGER NOT NULL,               -- 单位：人民币分
    currency VARCHAR(3) DEFAULT 'CNY',
    status VARCHAR(20) NOT NULL,           -- draft, open, paid, void, refunded
    billing_period_start TIMESTAMPTZ,
    billing_period_end TIMESTAMPTZ,
    -- 中文发票信息 schema: {"title": "公司名", "tax_id": "税号", "email": "接收邮箱", "address": "地址", "phone": "电话"}
    invoice_data JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 支付记录
CREATE TABLE payments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    invoice_id UUID NOT NULL REFERENCES invoices(id),
    stripe_payment_intent_id VARCHAR(100),
    amount INTEGER NOT NULL,               -- 单位：人民币分
    method VARCHAR(20),                    -- card, alipay, wechat_pay
    status VARCHAR(20) NOT NULL,           -- pending, succeeded, failed, refunded
    refund_amount INTEGER,                 -- 退款金额（分），null = 未退款
    paid_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- 用量配额追踪（按自然月聚合，数据源：usage_records）
-- 注意：period_start 统一使用 UTC 当月 1 日 00:00:00
CREATE TABLE usage_quotas (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    account_id UUID NOT NULL REFERENCES accounts(id),
    period_start TIMESTAMPTZ NOT NULL,     -- UTC 当月 1 日 00:00:00
    period_end TIMESTAMPTZ NOT NULL,       -- UTC 下月 1 日 00:00:00
    input_tokens_used BIGINT DEFAULT 0,    -- 从 usage_records 聚合
    output_tokens_used BIGINT DEFAULT 0,
    relay_calls_used INTEGER DEFAULT 0,
    hand_executions_used INTEGER DEFAULT 0,
    UNIQUE(account_id, period_start)
);

与现有系统的数据流关系：

usage_records (per-request telemetry)
    → Worker 聚合 → usage_quotas (per-month aggregation for billing)
    → 配额中间件检查 usage_quotas vs plans.token_quota_monthly

5.2 新增 SaaS 模块

crates/zclaw-saas/src/billing/
├── mod.rs              -- 模块入口
├── alipay.rs           -- 支付宝 API 集成
├── wechat_pay.rs       -- 微信支付 API 集成
├── plans.rs            -- 计划定义和管理
├── subscriptions.rs    -- 订阅生命周期管理
├── invoices.rs         -- 发票生成和管理
├── quotas.rs           -- 配额检查和追踪
└── callback.rs         -- 支付回调处理（统一支付宝/微信通知）

5.3 中间件链变更

在 Relay 请求处理链中新增配额检查中间件：

请求 → Rate Limit → Auth → Subscription Check → Quota Check → Relay Proxy → Usage Record

现有 relay/service.rs 的 StreamBridge 处理逻辑中，在 proxy_request 前增加订阅和配额验证步骤。

---

6. 关键决策记录

6.1 为什么选择知识工作者而非开发者作为首批用户

• Hands（Researcher/Collector/Twitter/Slideshow）天然面向内容创作者
• 开发者市场已有 Cursor/Copilot，差异化空间小
• 知识工作者对 AI 自主能力的需求更迫切，付费意愿验证更快

6.2 为什么 Freemium 而非纯 Token 加价

• 知识工作者对按量计费有心理抗拒（"不知道要花多少钱"）
• 订阅制提供可预期成本，降低决策门槛
• Token 加价作为增量收入叠加在订阅上，而非独立模式

6.3 为什么先做 Hands 验证再做 Marketplace

• 空市场困境：Marketplace 需要用户量，用户量需要产品力
• Hands 真实可用是所有后续价值的前提
• Marketplace 放在三阶段变现的最后阶段

6.4 支付集成策略：微信支付 + 支付宝直连

面向国内客户，直接集成微信支付和支付宝：

• 系统面向国内用户，无需考虑国际支付
• 使用支付宝当面付（Face-to-Face Payment）/ 手机网站支付 API
• 使用微信 Native Pay / JSAPI Pay API
• 用户无需离开应用，直接扫码或调起支付
• 货币单位统一为人民币分（CNY，双小数精度）
• 金额舍入规则：向上取整到分（如 49×12×0.8 = 470.4 → ¥470.40 = 47040 分）
• 异步回调（支付宝/微信均为 POST 回调通知）处理支付结果

技术方案：

• 支付宝：使用 alipay-sdk-rust 或直接 HTTP 调用支付宝开放平台 API
• 微信支付：使用 wechat-pay-rust 或直接 HTTP 调用微信支付 API v3
• 共用 Webhook 模式：统一回调端点 /api/v1/billing/callback/{provider} 处理支付通知
• 签名验证：RSA2 (支付宝) + RSA (微信) 确保回调安全

---

7. 风险与缓解

风险	概率	影响	缓解措施
Hand 执行在真实场景不可靠	高	致命	A1.1 优先验证，每周记录成功率，< 70% 则暂停其他工作
知识工作者不愿付费	中	高	14 天免费试用降低门槛，追踪使用功能→付费转化路径
支付宝/微信支付集成复杂度	中	高	使用 Rust SDK 封装，优先支持扫码支付（最简单）
Billing 模块工期超预期	高	高	B1.2 是关键路径，优先启动；分阶段交付（先订阅后发票）
Free 用户绕过本地 Hand 限制	中	低	初期软限制，核心付费价值在 SaaS Relay 而非本地功能
Beta 揭示基础性 bug	中	高	A1.4 关键路径排错在 Beta 前完成
国产 LLM 提供商 API 变更	中	中	Driver 层抽象隔离，API 变更仅需修改对应 driver
安全漏洞导致用户流失	低	致命	持续安全审计，渗透测试每季度一次
竞品跟进类似 Hands 功能	低	中	先发优势 + 深度场景验证建立壁垒

---

8. 验证方式

8.1 Track A 产品验证

• Researcher Hand 在 20 个真实研究话题中成功率 > 80%
• Collector Hand 在 20 个真实采集场景中成功率 > 80%
• Browser Hand 在 20 个真实网站操作中成功率 > 70%
• 新用户从下载到首次 Hand 执行 < 60 秒
• 20 人 Beta 中 > 12 人认为"比现有工具好"

8.2 Track B 商业验证

• Stripe Checkout 端到端跑通（订阅创建 → Webhook → 数据库更新）→ 改为支付宝/微信支付端到端跑通
• 配额中间件正确拦截超限请求
• Admin Dashboard 显示实时收入和转化数据
• 10 个付费 Beta 中 > 5 人在试用结束后选择续费
• Free → Pro 转化率 > 5%

8.3 回归验证

每次改动后必须验证：

• 聊天 / 流式响应正常
• Store 状态更新正确
• 配置读写持久化
• Hand 触发执行正常
• SaaS Relay 代理正常

# TypeScript 类型检查
pnpm tsc --noEmit

# 单元测试
pnpm vitest run

# Rust 测试
cargo test --workspace

# 启动开发环境
pnpm start:dev