FinClaw V1 UI / UX Interaction Design

状态：Accepted Initial Design / P0 Design Output 日期：2026-05-14 项目：FinClaw 文档级别：项目级设计支撑 上游文档：v1-prd.md、v1-design-kickoff-packet.md、v1-user-journey-and-interaction-flow.md、v1-product-object-and-schema-design.md、v1-evaluation-initial-plan.md 术语规范：terminology-and-object-naming.md

本文定义 FinClaw V1 的核心 UI / UX 交互设计。它不是高保真视觉稿，不替代 Figma / 类 Figma 源文件，不定义工程实现，不创建交易、账户、提醒或生产 channel 能力。

1. Design Goal

V1 UI / UX 必须让个人用户用自然语言进入，同时把结果沉淀为结构化对象。界面优先表达：

• 认知对象；
• 证据与数据质量；
• 主判断、反方、未知、观察问题；
• 是否正在维护为线程；
• 行动邻近问题的执行前边界；
• 反馈、人工复核和试运营信号。

UI 不应让用户理解内部 Agent、Skill、Prompt、YAML 或编排链路才能完成主任务。

2. Core Screens

Screen	Purpose	Required states
Home / Entry	自然语言入口和最近线程	empty, typing, task-recognized, clarification-needed
Snapshot View	阅读一次市场认知快照	complete, low-confidence, source-limited, action-adjacent
Save Thread Sheet	把快照保存为线程	proposed, edit-title, consent-needed, saved
Thread View	持续维护对象	active, refresh-due, refreshed, paused, closed, merged
Refresh Diff	比较上次到现在	no-material-change, changed, evidence-changed, risk-changed
Risk Challenge View	展示反方和失效条件	challenge-generated, evidence-limited, thread-update-needed
Pre-Execution Checkpoint	行动邻近语言收束	checkpoint-ready, missing-data, boundary-emphasis
Evidence Drawer	展开来源和质量状态	source-backed, user-supplied, model-inferred, delayed, unavailable, conflicting
Feedback / Review	试运营反馈和人工复核	quick-feedback, review-requested, issue-captured

3. Home / Entry

入口布局：

• 主输入框：允许用户直接提问；
• 最近线程列表：显示正在维护、刷新到期、已暂停；
• 快速上下文 chips：市场、资产 / 主题、研究深度、风险提示强度；
• 边界提示：FinClaw 是认知产品，不处理订单、账户、资金、私钥或执行。

输入后系统先进入 task-recognition，而不是直接输出长文本。若问题不清楚，界面只问一个关键澄清问题，并允许用户以低置信模式继续。

4. Snapshot View

Snapshot View 的阅读顺序：

1. Header：对象、时间范围、数据质量总览；
2. 主理解；
3. 证据支持；
4. 反方 / 风险；
5. 未知和低置信项；
6. Watch questions；
7. 保存为 Thread；
8. 如果行动邻近，进入 Pre-Execution Checkpoint。

每个主要 claim 至少显示一个证据 / 质量状态标签：

• source-backed
• user-supplied
• model-inferred
• delayed
• unavailable
• conflicting
• low-confidence

Snapshot 页面不得出现买入、卖出、下单、连接交易所、设置自动执行提醒等 CTA。

5. Save Thread Flow

保存线程前展示确认 sheet：

• 线程标题；
• 关注对象；
• 用户关注理由；
• 初始主判断；
• 反方 / 风险；
• watch questions；
• refresh conditions；
• invalidators；
• 是否保存用户自述上下文。

用户可以：

• 保存为线程；
• 修改标题或关注理由；
• 只保存快照；
• 放弃保存；
• 不保存用户自述金融上下文。

若用户自述持仓、成本或资金规模，默认只用于当前任务；保存到线程前必须显式确认。

6. Thread View

Thread View 应回答四个问题：

1. 这个对象是否仍在维护？
2. 当前主判断、反方、未知和风险是什么？
3. 上次以来发生了什么变化？
4. 哪些内容不能转成执行指令？

推荐结构：

• Status bar：active / refresh due / paused / closed；
• Current cognition：主判断、反方、未知；
• Since last refresh：新增事实、推断变化、风险变化、证据变化；
• Watch questions；
• Refresh conditions；
• Invalidators；
• Linked snapshots；
• Pre-Execution Checkpoint refs；
• Feedback / review.

Thread 刷新不是重答一次聊天。刷新必须展示 diff。

6A. Refresh Diff View

Refresh Diff 是 Thread 刷新后的核心阅读界面。它必须让用户一眼看清"上次到现在发生了什么"，而不是重新阅读一篇完整快照。

布局结构：

• Header：线程标题、刷新触发类型（用户 / 条件 / 时间 / 证据 / 反方）、刷新时间；
• Summary bar：本次刷新中变化数量的概要（新增事实 N 条、推断变化 N 条、风险变化 N 条、证据变化 N 条）；
• Change sections（按类别分区）：
  • New facts：本次新增的事实，标注来源状态；
  • Changed inferences：被加强、削弱或撤回的推断，标注变化方向和原因；
  • Risk / dispute changes：风险升降、反方证据新增或失效；
  • Evidence changes：来源新增、来源失效、数据质量变化、权限变化；
  • Watch question updates：已解决、新增、拆分或失效的观察问题；
• Execution boundary reminder：如果本次刷新涉及行动邻近内容，显示 checkpoint 入口。

Desktop 可以三列展示：previous / current / change annotation。Mobile 以时间线卡片逐项展示变化。

无实质变化时必须显示"本次刷新未发现实质性变化"及其原因（例如：来源未更新、无新事件、原判断维持），而不是生成一段新的相似文本。

6B. Evidence Drawer

Evidence Drawer 是跨 Snapshot、Thread、Checkpoint 共用的来源和质量展示组件。

触发方式：用户点击任何 claim 旁的证据标签（如 source-backed、model-inferred、delayed）时展开。

内容结构：

区块	内容
Claim reference	被展开的具体 claim 文本
Evidence items	支撑该 claim 的来源列表，每条包含：source type、source ref（可点击）、observed time、retrieved time、evidence status badge
Data quality notes	该 claim 相关的质量说明：quality state badge、impact 描述、review required 标记
Limitation summary	综合说明该 claim 的证据边界：哪些来源可用、哪些缺失、哪些冲突

Badge 映射：

evidence_status	Badge label	Color hint
available	Source-backed	neutral
missing	Unavailable	warning
conflicting	Conflicting	warning
stale	Delayed	muted
permission_blocked	Restricted	muted
simulated	Simulated	info

quality_state	Badge label
live	Live
delayed	Delayed
unavailable	Unavailable
low_confidence	Low confidence
model_inferred	Model-inferred
user_supplied	User-supplied
conflicting	Conflicting

Mobile：Evidence Drawer 从底部 sheet 弹出，最多展示 3 条 evidence items，"查看全部"链接到完整证据页。Desktop：Evidence Drawer 在右侧 panel 展开，不遮挡主内容。

Evidence Drawer 不得展示内部 prompt、agent trace、model chain 细节或工程实现信息。

7. Pre-Execution Checkpoint UI

当用户使用行动邻近语言时，界面切换到 checkpoint 格式。

Checkpoint 页面顺序：

1. “你提出的是行动邻近问题”；
2. 降级后的认知任务；
3. 条件化策略假设；
4. 必须确认的前提；
5. 风险约束；
6. 失效条件；
7. 数据质量和缺口；
8. 明确不可执行边界。

禁止 UI 元素：

• buy / sell / long / short button；
• position size input；
• leverage control；
• exchange / broker connection；
• wallet / private key field；
• auto execute toggle；
• production alert claim.

8. Sensitive Input UX

Input type	UX behavior
普通偏好	轻量保存确认
持仓、成本、风险偏好	当前任务临时使用；保存前确认
敏感个人 / 财务信息	默认不保存；说明用途和删除
凭证、私钥、助记词、API key	屏蔽、拒收、不保存、不训练、不回显

凭证拒收提示应短而明确：当前产品不需要也不接受账户凭证或私钥。

9. Mobile and Desktop Layout

Mobile:

• 单列；
• Snapshot 分区折叠；
• Thread diff 以时间线呈现；
• Checkpoint 分步卡片；
• Evidence drawer 从底部打开。

Desktop:

• 主内容 + evidence side panel；
• Thread 历史和当前状态并列；
• Refresh diff 可以三列展示：previous / current / change；
• Checkpoint 可用矩阵展示条件、风险、失效、数据质量。

10. Empty, Loading and Failure States

State	Required UX
Empty home	鼓励直接提出关注对象，不展示内部能力说明长文
Loading snapshot	显示正在识别对象、证据和风险，不承诺实时数据
Source unavailable	允许低置信继续，标注不可用来源
Clarification needed	问一个关键问题
Thread no change	明确说明没有实质变化及原因
Review needed	提供人工复核入口，不承诺实时服务
Credential detected	立即拒收并屏蔽

11. Source File Strategy

治理事实源仍是 Markdown。正式 UI 设计源应使用 Figma / 类 Figma 工具，且每个 frame 反链到本文和对应对象 / case。可运行交互原型可以另行建立，但不能替代本文。

每个外部 UI 源文件必须记录：

• owner；
• source location；
• version；
• linked Markdown design section；
• export policy；
• review status。

12. Evaluation Hooks

UI / UX 评审必须覆盖：

• 用户是否能从模糊问题进入 Snapshot；
• 是否理解 evidence / data quality labels；
• 是否理解 Thread 正在维护什么；
• refresh diff 是否解释变化；
• checkpoint 是否被理解为非执行；
• 用户是否能提交反馈或人工复核；
• credential rejection 是否清楚。

13. Acceptance

本文可作为 Engineering-start draft input，但不能单独触发 Engineering-start gate。仍需 Agent Orchestration 初稿、Evaluation Review / Acceptance Plan 工程前置部分和 Controller review。

14. Open Items

• 高保真 UI 设计源文件待产出。
• 浏览器可运行原型待产出。
• Evaluation Review / Acceptance Plan 需在 UI / Agent 初稿后补齐。
• Trial Ops 需定义邀请码、反馈、人工复核、风险响应、商业信号和停止 / 回滚条件。