FinClaw V1 Product Object and Schema Design

状态：Accepted Initial Design / P0 Design Output 日期：2026-05-14 项目：FinClaw 文档级别：项目级设计支撑 上游文档：v1-design-kickoff-packet.md、v1-prd.md、product-object-and-advisor-design.md、terminology-and-object-naming.md 评测承接：case-schema.md、cases/README.md 任务包：v1-product-object-and-schema-design-task-packet.md

本文产出 FinClaw V1 的产品对象和 schema 设计。它不是新的产品定义入口，不冻结数据库实现，不定义 API 细节，不改工程代码。

本文只把 Market Cognition Snapshot、Market Cognition Thread、Pre-Execution Checkpoint、Evidence / Data Quality、Advisor Output、User Context / Profile Consent、Sensitive Input Handling 映射为可评审的字段、状态、关系和验收约束。

1. Object Boundary

V1 正式对象仍以三份 canonical 和 V1 PRD 为准。本文只做下推。

Object	Role	First-class in V1	Execution boundary
MarketCognitionSnapshot	一次结构化金融认知输出	Yes	不含订单、信号或执行参数
MarketCognitionThread	可持续维护的认知对象	Yes	不是 watchlist、提醒队列或投资组合
PreExecutionCheckpoint	行动邻近问题的认知边界对象	Yes	不构成交易建议或执行指令
EvidenceItem	事实、推断、争议或未知项的来源记录	Trial field	只说明来源状态，不证明可执行性
DataQualityNote	来源、模型、权限、延迟、冲突等质量说明	Trial field	不能被当作交易信号置信度
AdvisorOutput	金融认知顾问中间输出	Support object	用户可查看，但不是主消费对象
UserContext	本次任务上下文	Support object	不含账户权限或凭证
ProfileConsent	保存用户上下文和偏好的确认状态	Support object	未确认不得长期保存
SensitiveInputHandling	高危输入拒收和过滤记录	Required control	凭证 / 私钥类必须拒收
TrainingAssetCandidate	未来学习资产候选治理状态	Candidate only	不表示已进入训练集

Legacy Action Suggestion、行动建议、交易信号、订单候选、target price、rating、自动提醒、开多 / 开空、加仓 / 减仓不得作为 V1 正式对象恢复。

2. Naming Rules

字段和枚举使用英文 canonical name 或 snake_case 派生名：

• market_cognition_snapshot
• market_cognition_thread
• pre_execution_checkpoint
• evidence_item
• data_quality_note
• advisor_output
• user_context
• profile_consent
• sensitive_input_handling
• training_asset_candidate

用户可见中文标题可以使用“市场认知快照”“市场认知线程”“执行前认知检查点”，但评审、schema、run result 和工程 handoff 必须保留 canonical mapping。

3. MarketCognitionSnapshot

MarketCognitionSnapshot 承接一次认知任务。它必须可保存、可复查、可引用、可进入线程。

3.1 Required Fields

Field	Type	Required	Notes
snapshot_id	string	yes	Stable identifier
title	string	yes	User-readable title
cognition_object	object	yes	Asset, project, theme, event, narrative or question
task_type	enum	yes	snapshot / risk_challenge / thread_refresh / pre_execution
time_context	object	yes	Generated time, coverage window, stale boundary
market_context	object	yes	Market, regime hint, recent key moves when available
main_thesis	string	yes	Core cognition
supporting_reasons	array	yes	Claims linked to evidence state where possible
counter_thesis	array	yes	Risks, disputes, alternate paths
uncertainties	array	yes	Unknowns and missing information
watch_questions	array	yes	Follow-up observation questions
invalidators	array	yes	Conditions that weaken or invalidate the thesis
evidence_items	array	yes	Trial field; maps claims to source state
data_quality_notes	array	yes	Trial field; records limitations
advisor_outputs	array	optional	Intermediate advisor outputs
pre_execution_checkpoint_refs	array	optional	Only when action-adjacent language appears
thread_proposal	object	optional	Recommendation to save as Thread
execution_boundary	string	yes	Must state non-execution boundary
created_at	datetime	yes	Creation timestamp

3.2 UI States

State	Meaning
complete	Enough evidence for a bounded snapshot
needs_clarification	Missing key object, time range or user intent
low_confidence	Output allowed but confidence is explicitly bounded
source_limited	Sources delayed, stale, conflicting or unavailable
action_adjacent	Must include or link to Pre-Execution Checkpoint
thread_candidate	Snapshot has ongoing observation value

4. MarketCognitionThread

MarketCognitionThread is the V1 continuity object. It is not a chat log, order object, watchlist, alert queue or portfolio object.

4.1 Required Fields

Field	Type	Required	Notes
thread_id	string	yes	Stable identifier
title	string	yes	User-readable name
object	object	yes	Asset, theme, event chain, narrative or open question
status	enum	yes	See lifecycle states
user_focus_reason	string	yes	Why the user cares
research_style	object	optional	Depth, language, risk emphasis, report preference
linked_snapshots	array	yes	Snapshot references, never overwritten
current_thesis	string	yes	Current main cognition
counter_thesis	array	yes	Current counter-thesis or disputes
watch_questions	array	yes	Maintained follow-up questions
refresh_conditions	array	yes	Event, time, evidence, counter-thesis triggers
invalidators	array	yes	Conditions that weaken or invalidate thesis
evidence_state	object	yes	Current evidence and quality state
cognition_changes	array	yes	Refresh-by-refresh change log
pre_execution_checkpoints	array	optional	Checkpoint references
profile_consent_refs	array	optional	Consent records for saved user context
last_refreshed_at	datetime	optional	Last refresh
closed_reason	string	optional	Required when closed

4.2 Lifecycle States

State	Entry	Exit
proposed	Snapshot has ongoing value	User saves, ignores or discards
active	User confirms continuous tracking	Refresh, pause, close, merge, split
refresh_due	Trigger condition appears	Refresh completes or user skips
refreshed	New cognition change is generated	Change is written back to active thread
paused	User or system pauses maintenance	Resume, close or merge
closed	User ends tracking or object loses value	Read-only review or copy to new thread
merged	User confirms overlap with another thread	Original remains read-only reference

4.3 Refresh Change Record

Each refresh creates:

Field	Meaning
refresh_id	Stable refresh identifier
trigger_type	user / condition / time / evidence / counter_thesis
previous_snapshot_ref	Previous baseline
new_snapshot_ref	New output
new_facts	Newly available facts
changed_inferences	Strengthened, weakened or withdrawn interpretations
risk_changes	Risk, dispute or invalidator changes
evidence_changes	Source, freshness, conflict or permission changes
watch_question_updates	Resolved, added, split or retired questions
execution_boundary_update	Any boundary reminder if action-adjacent language appears

5. PreExecutionCheckpoint

PreExecutionCheckpoint is the only V1 object allowed to handle action-adjacent language. It is a cognition boundary object, not an execution input.

5.1 Required Fields

Field	Type	Required	Notes
checkpoint_id	string	yes	Stable identifier
source_question	string	yes	Original user action-adjacent wording
normalized_cognition_task	string	yes	Downgraded cognition task
related_snapshot_ref	string	optional	Snapshot reference
related_thread_ref	string	optional	Thread reference
strategy_hypothesis	object	optional	Conditional hypothesis, not instruction
supporting_conditions	array	yes	Conditions that would need to hold
risk_constraints	array	yes	Risk, exposure, uncertainty constraints
invalidators	array	yes	Conditions that invalidate hypothesis
user_confirmation_needed	array	yes	Information user must verify independently
data_quality_notes	array	yes	Evidence limitations
forbidden_execution_fields	array	yes	Must include absent order / account / key fields
non_execution_statement	string	yes	Explicit boundary
created_at	datetime	yes	Creation timestamp

5.2 Forbidden Fields

The schema must not include:

• order_side
• order_type
• quantity
• leverage
• exchange_account
• broker_account
• wallet_address
• private_key
• api_key
• stop_loss_order
• take_profit_order
• auto_execute
• alert_trigger_to_execute

If later integration with AI Trading Matrix is needed, handoff must go through a separate authorized execution system contract outside FinClaw.

6. EvidenceItem and DataQualityNote

EvidenceItem and DataQualityNote are required trial fields in V1 outputs, but remain support fields until evaluation proves they should become first-class product objects.

6.1 EvidenceItem

Field	Required	Notes
evidence_id	yes	Stable identifier
claim_ref	yes	Claim, fact, inference or uncertainty being supported
source_type	yes	user_supplied / public_source / model_inferred / tool_result / reference_report
source_ref	optional	URL, doc path, tool trace or user note reference
observed_at	optional	Source time
retrieved_at	optional	Retrieval time
evidence_status	yes	available / missing / conflicting / stale / permission_blocked / simulated
limitation	yes	Human-readable limitation

6.2 DataQualityNote

Field	Required	Notes
quality_id	yes	Stable identifier
applies_to	yes	Snapshot, thread, checkpoint, claim or evidence item
quality_state	yes	live / delayed / unavailable / stale / conflicting / low_confidence / model_inferred / user_supplied
impact	yes	How the quality state affects interpretation
user_visible_label	yes	Short UI label
review_required	yes	Whether human or later system review is required

7. AdvisorOutput

Advisor outputs are intermediate and may be shown for transparency. They must write into Snapshot, Thread, Checkpoint or risk structures.

Field	Required	Notes
advisor_output_id	yes	Stable identifier
advisor_role	yes	Canonical advisor role
question_scope	yes	What this advisor handled
not_covered	yes	Explicit exclusions
key_points	yes	Main observations
evidence_used	yes	Evidence refs or limitations
assumptions	yes	Assumptions behind inference
uncertainties	yes	Unknowns and conflicts
risks_or_counterpoints	yes	Risks or counter-thesis
thread_write_target	yes	Target field in Snapshot / Thread / Checkpoint
execution_boundary	yes	Required for action-adjacent content

Advisor success is measured by whether it improves the user's cognition object, not by the number of advisors shown.

8. UserContext and ProfileConsent

V1 can use user context progressively, but must not turn onboarding into an account or compliance flow.

8.1 UserContext

Field	Required	Handling
context_id	yes	Per task or per thread
language_preference	optional	User editable
research_depth	optional	User editable
risk_prompt_preference	optional	User editable
user_focus_reason	optional	Save only with consent
user_stated_position_context	optional	Temporary by default
time_horizon	optional	Task-scoped unless saved
constraints	optional	User-stated, not execution instruction
sensitive_classification	yes	See SensitiveInputHandling

8.2 ProfileConsent

Field	Required	Notes
consent_id	yes	Stable identifier
context_ref	yes	Linked context
save_to_profile	yes	Explicit true / false
save_to_thread	yes	Explicit true / false
training_use_allowed	yes	Explicit true / false; default false
de_identified	yes	Required before training candidate
retention_scope	yes	Current task, thread, profile or none
delete_or_revoke_available	yes	Must be user-visible
confirmed_at	optional	Timestamp

9. SensitiveInputHandling

Sensitive handling is a required control object.

Input class	Examples	Handling
ordinary_preference	language, depth, report style	May save with lightweight confirmation
financial_context	holding, cost basis, risk preference, thesis	Use temporarily; save only with explicit confirmation
sensitive_personal_financial	net worth, income, account size	Default no-save; explain purpose and retention if used
credential_or_permission	API key, private key, seed phrase, account login	Reject, mask, do not save, do not train, do not echo

Required handling record:

Field	Required
input_ref	yes
classification	yes
allowed_use	yes
save_allowed	yes
training_allowed	yes
masking_required	yes
rejection_message_ref	optional
review_required	yes

10. Model, Provider and Source Boundary

Every formal output should preserve model and source boundary metadata sufficient for evaluation.

Field	Required	Notes
model_mode	yes	platform_certified / user_provided / fallback / unknown
provider_ref	optional	Provider or model family where allowed
tool_trace_ref	optional	Tool result or trace reference
source_boundary	yes	What sources were used or missing
quality_review_required	yes	Required if model is fallback or user-provided

User-provided or fallback model output cannot be counted as equivalent formal cognition without quality review.

11. TrainingAssetCandidate

Training asset fields are candidate governance metadata only. They do not mean V1 has a complete self-training loop.

Field	Required	Notes
candidate_id	yes	Stable identifier
source_output_ref	yes	Snapshot, Thread refresh, Checkpoint or review
user_authorized	yes	Explicit authorization
de_identified	yes	Required before any training use
sensitive_filtered	yes	Required
personal_domain_separated	yes	Must separate personal memory from aggregate learning
failure_case_type	optional	If used as failure sample
human_review_status	yes	pending / reviewed / rejected
withdrawal_status	yes	Whether user can revoke

12. Evaluation Mapping

Evaluation case	Required schema coverage
crypto-asset-snapshot-colloquial.yaml	Snapshot fields, evidence items, data quality, clarification
crypto-event-narrative-understanding.yaml	Snapshot, market context, source boundaries, advisor output
crypto-thesis-risk-controversy.yaml	Risk / counter-thesis, invalidators, advisor output
snapshot-to-watch-questions.yaml	Thread proposal, watch questions, refresh conditions
strategy-hypothesis-pre-execution-checkpoint.yaml	PreExecutionCheckpoint, forbidden execution fields
evidence-degradation-source-uncertainty.yaml	EvidenceItem, DataQualityNote, low-confidence states

Evaluation run results should check whether outputs include the required fields and whether action-adjacent language is downgraded into Pre-Execution Checkpoint instead of execution fields.

13. API and Persistence Boundaries

Future API / persistence design must not cross these lines:

• Do not store credentials, private keys, exchange keys or account permissions.
• Do not model order objects, positions as execution state, leverage or trade instructions inside FinClaw.
• Do not allow PreExecutionCheckpoint to be used as an execution trigger.
• Do not overwrite historical snapshots when a thread refreshes.
• Do not save financial context to profile or thread without explicit confirmation.
• Do not add training use without authorization, de-identification, sensitive filtering and revocation path.
• Do not make reference reports or evaluation cases product truth.

14. Acceptance

本文满足 P0 Product Object and Schema task packet 的接收条件：

• 每个核心对象都回链到 V1 PRD；
• 线程对象是一等对象，不是普通聊天历史字段；
• 行动邻近字段只进入 Strategy Hypothesis / Pre-Execution Checkpoint；
• 凭证、私钥、账户权限类输入有拒收 / 屏蔽 / 不保存 / 不训练字段；
• 用户画像和金融上下文保存前有确认状态；
• 数据质量、证据限制、模型来源和用户授权可被 evaluation 检查；
• schema 不要求 V1 已经具备完整自有模型训练闭环。

15. Open Items

• 本文不是 API contract；API contract 应在 UI / Agent / persistence 边界稳定后产出。
• 本文不是数据库 migration；持久化设计需要工程仓库另行承接。
• 本文不是 Evaluation Initial Plan；评测计划应在本文和 User Journey 初稿存在后启动。
• 本文不是 trial closeout evidence；试运营证据仍需 Trial Operations Plan 和 run evidence。