FinClaw V1 Commercial Signal Instrumentation Design
状态：Accepted Initial Design / §14.7 商业信号采集设计 日期：2026-05-16 项目：FinClaw 文档级别：项目级埋点 / 数据采集设计 上游文档：mvp-product-definition.md §14.7、v1-prd.md §11 / §13、v1-trial-operations-plan.md §8、v1-product-object-and-schema-design.md §8
本文把 MVP §14.7 商业信号验收 与 V1 PRD §11 试运营需求 中的 9 类商业信号转译为可工程化采集的事件 / 漏斗 / 留存指标。它不是定价设计，不是付费功能设计，不创建任何收费承诺。
它只回答两个问题：
- 试运营期间，FinClaw 该采集哪些行为事件来回答「用户是否在产生商业价值」？
- 这些事件如何在工程层落地、如何被 evaluation / Trial Closeout 消费？
1. Goal
V1 试运营无需「证明完整商业模式成立」，但必须能在 Trial Closeout 时回答：
- 使用强度：用户是否反复使用？
- 保存与复用：用户是否把输出当成长期资产？
- 持续跟踪：是否在多次会话间维护同一对象？
- 耐心阈值：是否愿意为高质量等待 / 补充上下文？
- 传播意愿：是否愿意推荐？
- 付费意愿：在哪些功能上愿意付费？
- 价值表达：能否说清相对普通 chat / 搜索 / 新闻聚合的差异？
2. Signal Inventory
| Signal ID | 信号 | 来源 | 采集方式 |
|---|---|---|---|
| CS-1 | 用户反复使用 | MVP §14.7 / PRD §11 | 行为事件 + 留存漏斗 |
| CS-2 | 用户保存输出 | MVP §14.7 | 行为事件（save_snapshot, save_thread） |
| CS-3 | 用户持续跟踪 | MVP §14.7 | 行为事件（thread_refresh, thread_revisit） |
| CS-4 | 用户用于真实金融认知任务 | MVP §14.7 | 访谈信号（HXS-4 复用 + 行为：含真实资产/主题输入比例） |
| CS-5 | 用户愿意补充上下文换取更好结果 | MVP §14.7 | 行为事件（clarification_resolved, context_added_after_prompt） |
| CS-6 | 用户愿意等待高质量输出 | MVP §14.7 | 行为事件（waited_for_advisor, did_not_abandon_during_loading） |
| CS-7 | 用户愿意推荐 | MVP §14.7 | 访谈信号（HXS-8a） + 行为事件（share_action） |
| CS-8 | 用户愿意为高级功能付费 | MVP §14.7 / PRD §11 | 访谈信号（HXS-8b）+ 行为事件（pricing_intent_click） |
| CS-9 | 用户能说清差异化价值 | MVP §14.7 | 访谈信号（HXS-4 / 自由表述）+ 关键词聚类 |
3. Event Schema
所有商业信号事件统一进入 events 表，符合下列 schema：
event_schema:
event_id: uuid
event_name: string # 见 §4 事件目录
event_category: usage | save | retention | patience | share | pricing_intent | value_articulation
user_anon_id: string # 不含 PII，邀请码派生
session_id: string
ts: datetime
source: web | mobile | trial_owner_input
related_object_refs:
snapshot_id: string | null
thread_id: string | null
checkpoint_id: string | null
payload: object # 事件特定字段
consent_state:
consent_for_trial_data: bool
training_use_allowed: bool
signal_mapping: # 反向映射回 §2 表
- CS-1
- CS-3
consent_state 必须在事件落库前从 ProfileConsent 读取；如 consent_for_trial_data == false，事件不进入分析数据库（最多进入临时审计日志，48h 内清理）。
4. Event Catalog
4.1 Usage Events（CS-1 / CS-4）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
session_started | 用户进入 Home | device, language | CS-1 |
task_submitted | 用户提交自然语言问题 | task_type_inferred, has_real_asset_or_topic (bool) | CS-1, CS-4 |
snapshot_generated | 系统生成一次 Snapshot | snapshot_id, ui_state, advisor_count | CS-1 |
thread_refreshed | Thread 刷新完成 | thread_id, refresh_trigger, change_count | CS-1, CS-3 |
checkpoint_generated | Pre-Execution Checkpoint 生成 | checkpoint_id, source_question_class | CS-1 |
4.2 Save Events（CS-2）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
snapshot_saved | 用户点击「保存快照」 | snapshot_id, save_destination (library / thread) | CS-2 |
thread_created | 用户从 Snapshot 创建 Thread | thread_id, snapshot_id, user_focus_reason_provided (bool), title_edited (bool) | CS-2 |
thread_save_declined | 用户在 Save Thread Sheet 选择放弃 | snapshot_id, decline_reason (enum: just_reading / not_relevant / unsure / other) | CS-2 反向 |
4.3 Retention Events（CS-3）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
thread_revisited | 用户回到已有 Thread 视图 | thread_id, days_since_last_visit | CS-3 |
watch_question_resolved | 用户在刷新中标记 watch question 已解决 | thread_id, question_id | CS-3 |
thread_paused | 用户暂停 Thread | thread_id, pause_reason | CS-3 反向（但可能是健康决策） |
thread_closed | 用户关闭 Thread | thread_id, close_reason | CS-3 反向 |
4.4 Patience / Context Events（CS-5 / CS-6）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
clarification_resolved | 用户回答澄清问题后系统继续生成 | task_id, clarification_question_id, response_length_chars | CS-5 |
context_added_after_prompt | 用户在 Snapshot 阅读后补充上下文重生成 | snapshot_id, added_field_kind | CS-5 |
waited_for_advisor | 用户在 advisor planner 加载 ≥ N 秒后未离开 | task_id, wait_ms, advisor_count | CS-6 |
low_confidence_continue_chosen | 用户在低置信状态下选择继续输出 | task_id | CS-5, CS-6 |
4.5 Share Events（CS-7）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
share_action | 用户点击 share / copy link | snapshot_id or thread_id, share_target (link / image / text) | CS-7 |
referral_invite_used | 邀请码被新用户使用 | referrer_anon_id, new_user_anon_id | CS-7 |
4.6 Pricing Intent Events（CS-8）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
pricing_intent_click | 用户点击「了解付费 / 升级 / 解锁」入口（试运营期仅做 dummy 入口收集意愿） | feature_kind: deep_research / continuous_thread / report / external_channel / privacy_first / byom | CS-8 |
pricing_intent_submitted | 用户在意愿调查中提交感兴趣的功能与价格段 | features_selected, price_band | CS-8 |
⚠️ Pricing 入口在 V1 试运营期间不真实收费，仅做意愿调查；UI 必须明确标注「这是意愿调查，不会扣款」。
4.7 Value Articulation Events（CS-9）
| event_name | 触发点 | payload | signal |
|---|---|---|---|
value_articulation_submitted | 用户在 trial 退出问卷或访谈中描述「FinClaw 强在哪里 / 弱在哪里」 | text_summary (脱敏), keywords_extracted, sentiment | CS-9 |
文本字段必须经过敏感信息过滤（无人名、账户、地址、链上地址）才入库。
5. Funnel Definitions
| Funnel ID | Steps | 用途 |
|---|---|---|
| FN-1 Activation | session_started → task_submitted → snapshot_generated | 衡量进入 → 首次产出转化 |
| FN-2 Save | snapshot_generated → snapshot_saved or thread_created | 衡量是否把输出当成资产 |
| FN-3 Retention | thread_created → thread_revisited (7d) → thread_refreshed | 衡量持续跟踪 |
| FN-4 Patience | task_submitted → clarification_resolved or waited_for_advisor → snapshot_generated | 衡量耐心阈值 |
| FN-5 Pricing Intent | snapshot_generated → pricing_intent_click → pricing_intent_submitted | 衡量付费意愿 |
| FN-6 Share | snapshot_generated or thread_refreshed → share_action → referral_invite_used | 衡量传播 |
每个 funnel 输出 conversion rate 与 drop-off step。
6. Retention Cohorts
试运营期 ≤ 4 周。建议 cohort 切片：
| Cohort | 入选标准 | 留存指标 |
|---|---|---|
| Day-0 user | 首次 session_started | D1 / D3 / D7 / D14 留存 |
| Saver | 至少 1 次 thread_created | D7 / D14 thread_revisited 比例 |
| Refresher | 至少 1 次 thread_refreshed | D14 重复 refresh 用户数 |
| Action-adjacent user | 至少 1 次 checkpoint_generated | 后续是否回访（区分行动需求 vs 认知需求） |
7. Reporting Shape
每周一份 commercial signal 周报，结构：
report_id: cs-week-<YYYY-WW>
date_range: <YYYY-MM-DD..YYYY-MM-DD>
n_active_users: int
events_total: int
funnels:
FN-1: { conversion: float, drop_off: { ... } }
FN-2: { ... }
FN-3: { ... }
FN-4: { ... }
FN-5: { ... }
FN-6: { ... }
retention:
D1: float
D3: float
D7: float
D14: float
signals_summary:
CS-1: <强度判断>
CS-2: <强度判断>
CS-3: <强度判断>
CS-4: <强度判断>
CS-5: <强度判断>
CS-6: <强度判断>
CS-7: <强度判断>
CS-8: <强度判断>
CS-9: <关键词聚类 top-N>
notable_events:
- <异常事件描述>
进入 v1-trial-operations-plan.md §10 Trial Closeout 时合并为 closeout packet 中的 commercial signal 章节。
8. Privacy and Consent Constraints
| 约束 | 描述 |
|---|---|
| Consent gate | 任何事件落库前必须确认 ProfileConsent.consent_for_trial_data == true |
| Training gate | 进入训练资产候选必须 training_use_allowed == true 且 de_identified == true |
| Sensitive payload filter | value_articulation_submitted 文本字段在落库前去除人名、地址、账户、链上地址、私钥模式 |
| No keys ever | pricing_intent_* 事件不得收集真实支付凭证（试运营期不真实收费） |
| Deletion right | 用户撤回同意 48h 内删除其 user_anon_id 下所有事件与衍生分析记录 |
9. Engineering Handoff
实现承接：
- 事件总线建议复用现有
server/agent/event_sink.py，新增 commercial signal 事件类别； - 漏斗 / 留存查询可在试运营期间用 SQLite + 简单 Python 报表，无需引入完整数据仓库；
- pricing intent UI 入口在 web 端新增（受 feature flag 控制，仅 trial cohort 可见）；
- value_articulation_submitted 文本字段必须经过 sensitive filter（复用现有 SensitiveInputHandling 分类器）；
- 全部事件 schema 落地到
server/agent/models.py或独立server/api/commercial_events.py； - 周报由独立脚本生成，不进入产品主数据库的写路径。
10. Out of Scope
V1 商业信号 instrumentation 不做：
- 真实计费 / 订阅扣款；
- 跨产品归因（与 Data Horizon / Trading Matrix 联动归因）；
- A/B 实验框架；
- LTV / CAC 模型；
- 完整 BI / 数据仓库；
- 任何强行把 cognition 信号包装成「交易信号」的指标。
这些都是 V1 之后阶段的事。
11. Open Items
- 工程层 instrumentation 实现尚未启动（v1-execution-plan-and-milestones.md M-C4）；
- pricing intent 的具体功能描述需要 PM 在 trial 启动前确认（建议借鉴 mvp-product-definition.md 末尾的「免费试用 / 标准订阅 / 深度研究 / 外部渠道 / BYOM」假设）；
- 与 Legal / Compliance 团队的隐私 / GDPR 合规复核未完成。