velaria-python-local

name	velaria-python-local
description	How to use a locally installed Velaria Python package for local analysis and stream SQL workflows.

Velaria Local Python Skill

这个 Skill 用于说明如何把 velaria 的 Python 包作为本地分析工具使用，不涉及仓库实现代码或编译/构建逻辑。
核心思路：把数据先加载为临时视图，再用 session.sql(...) 写 SQL 处理。

在 Velaria Agent 中处理数据任务时，优先调用已注册的 Velaria local functions/MCP tools：

• HTTP(S) 数据集 URL：先用 velaria_dataset_download 本地化，或直接把 URL 传给 velaria_dataset_import / velaria_read / velaria_sql / velaria_dataset_process。
• 本地文件：用 velaria_dataset_import 注册、velaria_read / velaria_schema 检查、velaria_sql 查询、velaria_dataset_process 保存 run/artifact。
• 编码、中文列名、invalid token byte 或 SQL 标识符问题：先用 velaria_dataset_normalize 转成 UTF-8 CSV 和 SQL-safe 字段名，再按返回的 schema / column_mapping 写 SQL。
• SQL 函数、能力边界和常见模板：按需用 velaria_sql_capabilities、velaria_sql_function_search、velaria_sql_query_patterns 或资源 velaria://sql/catalog 检索，不要凭记忆猜函数。
• 公开财经数据：不要假设存在专用 finance agent tool；在 Velaria Agent 中通过 velaria_cli_run 调用 finance ... 子命令，例如 finance fetch-quotes --provider tencent --market cn --symbols 000001。
• 不要在 Velaria 工具失败前先写 curl、wget 或自定义 Python 下载脚本；只有 Velaria 工具无法覆盖时再回退到通用方式。

本 Skill 默认只使用 uv 执行。仓库内可直接使用的入口只有两类：

• 源码入口：uv run --project python python python/velaria_cli.py ...
• 打包产物：./dist/velaria-cli ...

如果你已经把 wheel 安装到了独立环境，也可以使用安装后的 velaria-cli / velaria_cli，但下面的示例统一使用仓库内可见入口。

1. 环境准备

推荐先创建一个本地环境并安装 velaria：

uv venv .venv
source .venv/bin/activate

# 二选一：
uv pip install velaria
# 或
uv pip install /path/to/velaria-<version>-<python_tag>-<abi_tag>-<platform_tag>.whl

uv run --project python python python/velaria_cli.py --help
uv run python -c "import velaria; print(velaria.__version__)"

若外部 whl 已包含原生扩展，则可直接使用 Session；若是纯 Python 子集或兼容层缺失，会在首次创建 Session 时报错。
本 Skill 不包含仓库构建步骤，只描述“已安装包后如何使用”。 若你只想做一次性验证，也可以用 uv run --with velaria ... 临时拉起环境，但不作为本 Skill 的默认路径。

2. Skill 脚本

目录：skills/velaria_python_local/scripts/

• smoke.py：最小本地 smoke。
• query_csv_to_sql.py：CSV 直接转 SQL。
• query_excel_to_sql.py：Excel 直接转 SQL。
• query_bitable_to_sql.py：Bitable 记录转 SQL（需要环境变量 FEISHU_BITABLE_*）。
• read_xlsx.py：最小 Excel 读取示例（兼容旧示例用途）。

3. 核心数据链路（数据 → SQL）

from velaria import Session

session = Session()
df = session.read_csv("data/sales.csv")
session.create_temp_view("sales", df)
result = session.sql("SELECT region, SUM(amount) AS amount_sum FROM sales GROUP BY region").to_arrow()
print(result.to_pylist())

如果你更适合用 CLI 而不是临时 Python 片段，在已安装 velaria 的环境里也可以直接使用 workspace/run store。

所有 CLI 顶层命令和子命令都支持 --help，例如 uv run --project python python python/velaria_cli.py run diff --help。 uv run --project python python python/velaria_cli.py 会进入 Velaria Agent TUI。

uv run --project python python python/velaria_cli.py

uv run --project python python python/velaria_cli.py run start -- file-sql \
  --run-name "regional_row_count" \
  --description "regional row count for the current CSV snapshot" \
  --tag regional \
  --tag daily-check \
  --csv path/to/file.csv \
  --query "SELECT region, COUNT(*) AS cnt FROM input_table GROUP BY region"

uv run --project python python python/velaria_cli.py run list --tag regional --query "row count" --limit 20
uv run --project python python python/velaria_cli.py run result --run-id <run_id>
uv run --project python python python/velaria_cli.py run diff --run-id <run_id> --other-run-id <other_run_id>
uv run --project python python python/velaria_cli.py run show --run-id <run_id>
uv run --project python python python/velaria_cli.py artifacts list --run-id <run_id>

3.1 公开财经数据 CLI

用途：

• 通过公开 provider 获取 A股 / 美股历史数据、quote 或新闻 RSS
• 把 quote 写入 Velaria external_event source
• 给 monitor / FocusEvent / 候选排名 / Agent 研究链路提供带来源 metadata 的输入

可用子命令：

• finance doctor：检查 finance 依赖和公开 quote provider 是否可达
• finance sources：列出公开 provider、支持市场、freshness 和推荐用法
• finance analyze：面向用户的一条命令分析入口；获取 quote、入库、运行 monitor，并输出可读研究报告或 JSON
• finance pipeline：完整链路入口；获取历史 OHLCV、订阅实时 quote tick、运行 monitor，并输出分析和 service 集成 metadata
• finance rank-candidates：候选池排名入口；持续获取 quote、历史 OHLCV、新闻 RSS 和透明情绪证据，输出 Top N 研究候选
• finance intelligence index：把同一 watch-session 已沉淀的 evidence 预构建成可复用 hybrid index，供后续 search 直接命中
• finance intelligence search：对同一 watch-session 已沉淀的 quote/history/news/features/candidates/fundamentals/native stream signal 做 hybrid search，返回可复盘 evidence hit
• finance fetch-history：获取历史 OHLCV 行情；优先使用 provider=yahoo，也可使用 provider=akshare
• finance fetch-quotes：获取 quote 行；可用 provider=akshare、provider=tencent 或 provider=yahoo
• finance fetch-news：获取公开新闻、财经新闻或监管 filing evidence；可用 provider=google-news、provider=yahoo-finance-news、provider=sec-filings
• finance fetch-fundamentals：获取公开基本面 evidence；美股可用 provider=sec-companyfacts
• finance ingest-quotes：获取 quote 并写入 external_event source，供 monitor 使用
• finance watch：持续监听一个标的，逐 tick 写入 observation、运行 monitor，并输出事件上下文
• finance watch-session：完整盯盘会话入口；把候选排名、native stream 信号、quote/history/news、大盘上下文、基本面 provider 快照落到同一个 session_id，并支持复盘查询和总结

源码入口示例：

uv run --project python --extra finance python python/velaria_cli.py finance doctor

uv run --project python --extra finance python python/velaria_cli.py finance sources

uv run --project python --extra finance python python/velaria_cli.py finance analyze \
  --market cn \
  --symbol 000001

uv run --project python --extra finance python python/velaria_cli.py finance analyze \
  --market cn \
  --symbol 000001 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance pipeline \
  --market cn \
  --symbol 000001 \
  --start-date 20250101 \
  --end-date 20250131 \
  --iterations 1 \
  --interval-sec 0

uv run --project python --extra finance python python/velaria_cli.py finance pipeline \
  --market cn \
  --symbol 000001 \
  --start-date 20250101 \
  --end-date 20250131 \
  --iterations 1 \
  --interval-sec 0 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance pipeline \
  --market us \
  --symbol AAPL \
  --start-date 20260501 \
  --end-date 20260518 \
  --iterations 1 \
  --interval-sec 0 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance rank-candidates \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --iterations 1 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance rank-candidates \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --iterations 0 \
  --interval-sec 30 \
  --jsonl

uv run --project python --extra finance python python/velaria_cli.py finance rank-candidates \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --native-stream \
  --ingest-raw \
  --entry-score-threshold 8 \
  --entry-return-threshold 5 \
  --exit-score-threshold 0 \
  --exit-quote-pct-threshold -3 \
  --signal-policy-preset balanced \
  --iterations 0 \
  --interval-sec 300 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance rank-candidates \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --start-date 20260501 \
  --end-date 20260518 \
  --native-stream \
  --ingest-raw \
  --signal-policy '{"entry":{"all":[{"field":"momentum_state","op":"!=","value":"bearish"},{"field":"score","op":">=","value":0}]},"exit":{"any":[{"field":"news_sentiment_label","op":"=","value":"negative"},{"field":"quote_pct_change","op":"<=","value":-2}]}}' \
  --iterations 1 \
  --interval-sec 0 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session start \
  --session-id us_watch_20260519 \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --market-symbols SPY,QQQ,DIA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --entry-score-threshold 8 \
  --entry-return-threshold 5 \
  --exit-score-threshold 0 \
  --exit-quote-pct-threshold -3 \
  --signal-policy-preset balanced \
  --iterations 0 \
  --interval-sec 300 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session summarize \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence start \
  --intelligence-id us_intel_20260519 \
  --session-id us_watch_20260519 \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --market-symbols SPY,QQQ,DIA \
  --fundamentals-provider sec-companyfacts \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --iterations 0 \
  --interval-sec 300 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence report \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence index \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence search \
  --session-id us_watch_20260519 \
  --query "NVDA momentum risk news fundamentals" \
  --top-k 5 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence jobs \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence status \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence stop \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence resume \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence evaluate \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance intelligence eval-report \
  --session-id us_watch_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session start \
  --session-id us_watch_async_20260519 \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --market-symbols SPY,QQQ,DIA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --iterations 0 \
  --interval-sec 300 \
  --async-run \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session status \
  --session-id us_watch_async_20260519 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session logs \
  --session-id us_watch_async_20260519 \
  --limit 20 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session review \
  --session-id us_watch_async_20260519 \
  --log-limit 20 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance watch-session supervise \
  --session-id us_watch_async_20260519 \
  --interval-sec 60 \
  --log-limit 20 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance rank-candidates \
  --market us \
  --symbols AAPL,MSFT,NVDA \
  --start-date 20260501 \
  --end-date 20260518 \
  --top 3 \
  --news-limit 5 \
  --stream-monitor \
  --ingest-raw \
  --entry-score-threshold 8 \
  --entry-return-threshold 5 \
  --exit-score-threshold 0 \
  --exit-quote-pct-threshold -3 \
  --until-time 2026-05-18T16:00:00-04:00 \
  --interval-sec 300 \
  --format json

uv run --project python --extra finance python python/velaria_cli.py finance fetch-quotes \
  --provider tencent \
  --market cn \
  --symbols 000001,600519

uv run --project python --extra finance python python/velaria_cli.py finance fetch-news \
  --provider google-news \
  --market us \
  --symbol AAPL \
  --limit 5

uv run --project python --extra finance python python/velaria_cli.py finance fetch-news \
  --provider yahoo-finance-news \
  --market us \
  --symbol AAPL \
  --limit 5

export VELARIA_SEC_USER_AGENT="VelariaFinance/1.0 [e-mail]"

uv run --project python --extra finance python python/velaria_cli.py finance fetch-news \
  --provider sec-filings \
  --market us \
  --symbol AAPL \
  --limit 5

uv run --project python --extra finance python python/velaria_cli.py finance fetch-fundamentals \
  --provider sec-companyfacts \
  --market us \
  --symbols AAPL,MSFT,NVDA

uv run --project python --extra finance python python/velaria_cli.py finance ingest-quotes \
  --provider tencent \
  --market cn \
  --symbols 000001 \
  --source-id finance_cn_quotes

uv run --project python --extra finance python python/velaria_cli.py finance watch \
  --market cn \
  --symbol 000001 \
  --interval-sec 30 \
  --iterations 0 \
  --jsonl

uv run --project python --extra finance python python/velaria_cli.py finance fetch-history \
  --provider yahoo \
  --market cn \
  --symbol 000001 \
  --start-date 20250101 \
  --end-date 20250131 \
  --output /tmp/velaria-cn-history.parquet

在 velaria_cli.py -i 交互式 Agent 模式中，使用已注册 agent tool velaria_cli_run，并且只传 Velaria 子命令，不要包含 uv、python 或 python/velaria_cli.py：

finance doctor
finance sources
finance analyze --market cn --symbol 000001 --format json
finance pipeline --market cn --symbol 000001 --start-date 20250101 --end-date 20250131 --iterations 1 --format json
finance rank-candidates --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --top 3 --format json
finance intelligence start --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --iterations 0 --format json
finance intelligence review --session-id us_watch_async_20260519 --format json
finance intelligence replay --session-id us_watch_async_20260519 --format json
finance intelligence index --session-id us_watch_async_20260519 --format json
finance intelligence search --session-id us_watch_async_20260519 --query "NVDA momentum risk news fundamentals" --format json
finance intelligence report --session-id us_watch_async_20260519 --format json
finance intelligence jobs --session-id us_watch_async_20260519 --format json
finance intelligence status --session-id us_watch_async_20260519 --format json
finance intelligence stop --session-id us_watch_async_20260519 --format json
finance intelligence resume --session-id us_watch_async_20260519 --format json
finance intelligence evaluate --session-id us_watch_async_20260519 --format json
finance intelligence eval-report --session-id us_watch_async_20260519 --format json
finance watch-session start --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --iterations 0 --format json
finance watch-session start --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --iterations 0 --async-run --format json
finance watch-session status --session-id us_watch_async_20260519 --format json
finance watch-session logs --session-id us_watch_async_20260519 --limit 20 --format json
finance watch-session review --session-id us_watch_async_20260519 --format json
finance watch-session supervise --session-id us_watch_async_20260519 --interval-sec 60 --format json
finance watch-session stop --session-id us_watch_async_20260519 --format json
finance watch-session summarize --session-id us_watch_20260519 --format json
finance fetch-quotes --provider tencent --market cn --symbols 000001
finance fetch-news --provider google-news --market us --symbol AAPL --limit 5
finance fetch-fundamentals --provider sec-companyfacts --market us --symbols AAPL,MSFT,NVDA
finance ingest-quotes --provider tencent --market cn --symbols 000001 --source-id finance_cn_quotes
finance watch --market cn --symbol 000001 --interval-sec 30 --iterations 0 --jsonl

输出约束：

• finance analyze 默认输出人类可读中文报告；Agent 自动化应传 --format json
• finance pipeline 默认输出人类可读中文报告；Agent 自动化应传 --format json
• finance rank-candidates 输出 research_candidates，不是买卖建议；Agent 自动化应传 --format json、持续模式 --jsonl，native stream 模式 --native-stream --ingest-raw，或 agentic stream monitor 模式 --stream-monitor --until-time <RFC3339>
• finance rank-candidates --signal-policy-preset balanced|momentum|defensive 先用可解释 policy 计算 entry_signal / exit_signal，再交给 native stream SQL 的 WHERE entry_signal >= 1 OR exit_signal >= 1 过滤；如果需要自定义，传 --signal-policy JSON，格式为 entry.all / entry.any / exit.all / exit.any 条件列表
• finance intelligence start 是产品化主入口，复用 watch-session 的 public provider、raw ingestion 和 Velaria native realtime stream 链路，并额外写入 finance_intelligence_sessions 和 finance_intelligence_ai_notes
• finance intelligence review 读取同一个 watch-session 的进程、日志、feed 计数和信号摘要，沉淀 agent-readable AI note；finance intelligence replay 只从已持久化的实时 feed 读取，不重新请求 provider；finance intelligence index 将 evidence docs、BM25 keyword index 和 metadata fingerprint 写入 $VELARIA_HOME/finance/evidence_indexes/ 并登记 finance_intelligence_evidence_indexes；finance intelligence search 默认 --index-mode auto，命中同指纹索引时返回 retrieval.index_status=hit，缺失或过期时重建，并写入 finance_intelligence_searches；finance intelligence 产品路径不使用 hash embedding，未显式接入真实生产 embedding provider 前 retrieval.semantic.status=disabled；finance intelligence report 生成并持久化最终 scorecard、supervisor checks 和 replayable research summary；finance intelligence jobs/status/stop/resume 暴露 finance_intelligence_jobs 与 finance_watch_session_runs 的 durable job surface，供 Agent 查询、停止和恢复长时间运行的 intelligence session；finance intelligence evaluate/eval-report 只读取已沉淀 rows 和 job/search/index 事件，写入 finance_intelligence_evaluations，输出 signal/provider/retrieval/runtime 质量指标
• finance intelligence supervise --iterations 0 在 CLI 内持续运行 review loop，适合 agent 通过 velaria_cli_run 长时间观察、调试和复盘；输出仍是研究证据，不是投资建议
• finance watch-session start 输出完整盯盘会话 JSON，包含 watch_session、raw_sources、native_stream、ticks、research_candidates、stream_signals；它会默认启用 native stream 和 raw ingestion
• finance watch-session start --async-run 会在后台 CLI 进程中运行同一条 core native stream 链路，前台返回 pid、log_path 和后续命令；Agent 自动化应随后调用 status/logs/signals/summarize/stop
• finance watch-session list/show/events/signals/summarize/status/logs/review/supervise/stop 用于观察、调试、停止和复盘同一 session_id 下沉淀的实时数据；Agent 自动化应传 --format json
• finance watch-session review 会读取 async runtime、进程状态、日志尾部、feed 计数、latest signals 和 provider-unavailable 证据，并把 review 事件写入 finance_watch_session_reviews
• finance watch-session supervise 在 CLI 内持续运行同一 review 循环；--iterations 0 表示持续运行，--interval-sec 控制检查周期，适合通过 velaria_cli_run 保持观察和改进闭环
• finance doctor / finance sources 默认输出人类可读文本；Agent 自动化可传 --format json
• finance stream-history 查询 native stream sink 的持久化历史；Agent 自动化应传 --format json，并可传 --source-id finance_<market>_rank_candidates_native_stream_signals
• fetch-*、ingest-quotes、watch 默认 stdout 是 JSON，失败也是 JSON
• fetch-news 输出 sentiment，情绪方法为透明关键词词典，不是不可解释模型判断
• finance watch 默认在有限 --iterations 后输出一个 JSON；--iterations 0 是持续监听，配合 --jsonl 可逐 tick 输出
• finance pipeline 输出包含 history、subscription、quote、focus_events、analysis、analysis_prompt 和 service_integration
• finance rank-candidates 输出包含 score_parts、quote、history、news_sentiment、news、feature_snapshot、risk_flags、evidence、service_integration；开启 --native-stream 时还包含 native_stream、native_stream_signals，并把 native stream sink 输出写入 finance_<market>_rank_candidates_native_stream_signals；开启 --ingest-raw 时会把 quote/history/news/features/candidate 写入 Velaria external_event sources；开启 --stream-monitor 时还包含 stream_monitors、stream_monitor_runs、focus_events
• finance intelligence search 输出包含 retrieval.mode、retrieval.fusion=rrf、retrieval.semantic.status、retrieval.index_status、retrieval.index_path、hits[].score_breakdown、hits[].source_ref 和 hits[].row；Agent 应优先根据这些 evidence 再生成复盘问题或下一步命令
• provider 失败应读取 error_type、message、hint、details
• 行数据包含 provider、source_url、fetched_at、freshness、delay_sec、license_note
• watch tick 包含 quote、observations、signals、focus_events、artifacts、analysis 和 analysis_prompt
• finance sources --format json 来自实际 provider registry，是 Agent 选择 provider / command 的优先依据
• freshness / delay_sec 是研究证据，不要把所有 quote 都当成交易所级实时数据
• 金融输出只作为研究辅助，不构成投资建议；禁止把 research_candidates 改写成买入、卖出、持有指令

Provider 使用建议：

• 普通用户第一步先运行 finance doctor，再运行 finance analyze --market cn --symbol 000001
• 需要完整链路时运行 finance pipeline --market cn --symbol 000001 --start-date 20250101 --end-date 20250131
• 美股完整链路可运行 finance pipeline --market us --symbol AAPL --start-date 20260501 --end-date 20260518 --iterations 1 --format json
• 美股候选池排名可运行 finance rank-candidates --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --top 3 --format json
• 需要产品化盯盘、复盘和 agent brief 时优先运行 finance intelligence start，然后用 finance intelligence review/replay/supervise 和 finance watch-session summarize/events/signals 查询同一会话
• 历史行情优先尝试 provider=yahoo；AkShare / Eastmoney 可作为补充 provider
• 轻量 quote 优先尝试 provider=tencent
• 美股 quote 也可尝试 provider=yahoo，它来自公开 chart metadata，按 provider contract 标记延迟或未知 freshness
• 新闻和舆论证据优先尝试 provider=google-news；更聚焦的财经新闻可尝试 provider=yahoo-finance-news；监管 filing 事件可尝试 provider=sec-filings。所有这些 row 都带 source_category/source_type/source_score/source_score_reason
• 美股基本面优先尝试 provider=sec-companyfacts；生产访问 SEC 前先设置 VELARIA_SEC_USER_AGENT 为包含应用名和联系人的 User-Agent；如果 SEC、CIK 或字段不可用，必须保留结构化 unavailable row，不要 mock
• Tencent 美股 quote 当前按 provider contract 标记为 freshness=delayed，不要描述为交易所级实时
• AkShare / Eastmoney 上游不可达时，不要 mock 或编造历史数据；把结构化 provider 错误返回给用户，并可用 Tencent quote 做实时监控链路验证

Service 集成：

• 不要假设存在 finance-specific service route
• finance pipeline 使用 CLI 写入 Velaria AgenticStore
• finance rank-candidates --native-stream --ingest-raw 会创建 Velaria native realtime stream source/sink，把 candidate event 推入 native stream SQL，同时把 quote/history/news/candidate 和 native stream sink signal 全部落入 Velaria external_event sources
• finance intelligence start 是上层产品入口：它复用 watch-session 底层算子和 runtime，不复制 provider 或 stream 逻辑；输出 runtime_plane、data_plane、ai_plane，并把 session、AI note、features、native stream signal 和后续 replay/report 事件分别写入 Velaria external_event sources
• finance intelligence replay 证明实时数据会自然沉淀为历史数据：它只读取 watch-session 已落库 rows，不再次访问 Yahoo/Tencent/Google News provider
• finance intelligence index/search 证明沉淀数据可以继续进入 hybrid retrieval 资产层：索引文件落在 Velaria home，索引事件写入 finance_intelligence_evidence_indexes，搜索事件写入 finance_intelligence_searches
• finance intelligence report 读取同一批已沉淀 rows，输出 supervisor_checks.replayability/data_quality/signal_consistency/provider_quality，并写入 finance_intelligence_reports
• finance watch-session start 复用同一条 ranking/native stream/raw ingestion 链路，并额外写入 finance_watch_sessions、大盘上下文 source 和基本面 source；provider 不可用时写入结构化 unavailable 事件，不 mock 数据
• finance watch-session start --async-run 额外写入 finance_watch_session_runs，记录 pid、log_path、core_runtime=velaria_native_realtime_stream、ai_cli_runtime=velaria_cli_run，使 Agent 可以边观察边调试
• finance watch-session review/supervise 额外写入 finance_watch_session_reviews，把持续运行诊断、下一步命令和 agent_prompt 沉淀为可复盘事件
• finance rank-candidates --stream-monitor 会创建 entry / exit execution_mode=stream monitors，并在每个 ranking tick 后由 Velaria monitor 链路产生 FocusEvent
• 如果本地 velaria_service 使用相同 VELARIA_HOME，可通过通用 service routes 查看 CLI 创建的 source、monitor 和 focus-events

3.2 当前 SQL v1 边界

批量 SQL 当前适合直接走 session.sql(...) 的形态：

• CREATE TABLE、CREATE SOURCE TABLE、CREATE SINK TABLE
• INSERT INTO ... VALUES
• INSERT INTO ... SELECT
• SELECT 的列投影 / 别名、WHERE（含列对列谓词）、GROUP BY、ORDER BY、LIMIT、当前最小 JOIN
• 当前内建函数：LOWER、UPPER、TRIM、LTRIM、RTRIM、LENGTH、LEN、CHAR_LENGTH、CHARACTER_LENGTH、REVERSE、CONCAT、CONCAT_WS、LEFT、RIGHT、SUBSTR / SUBSTRING、POSITION、REPLACE、CAST、ABS、CEIL、FLOOR、ROUND、YEAR、MONTH、DAY、ISO_YEAR、ISO_WEEK、WEEK、YEARWEEK、NOW、TODAY、CURRENT_TIMESTAMP、currentTimestamp、UNIX_TIMESTAMP
• 投影中的已支持标量函数可以嵌套，例如 SUBSTR(CAST(open AS STRING), 1, 6)

约束：

• CREATE SOURCE TABLE 是只读表，不允许 INSERT
• CREATE SINK TABLE 允许写入，但不能作为查询输入
• ORDER BY 当前只支持对 SELECT 输出中可见的列排序
• 超出当前范围的 SQL 形态会直接返回明确错误，例如 not supported in SQL v1

stream SQL 当前边界：

• session.stream_sql(...) 只适合 SELECT
• session.explain_stream_sql(...) 适合 SELECT 或 INSERT INTO <sink> SELECT ...
• session.start_stream_sql(...) 只适合 INSERT INTO <sink> SELECT ...
• stream source 必须是 source table，stream target 必须是 sink table
• 适合的能力是 filter / projection / window / stateful aggregate，以及 bounded source 上的 ORDER BY
• unbounded stream 上的 ORDER BY 会被显式拒绝；当前 runtime 不对无界输入承诺全局有序结果

4. 新增功能与参数说明

4.1 velaria_cli.py run start

用途：

• 启动一次被 workspace 跟踪的执行
• 自动生成 run_id
• 自动创建 run 目录
• 自动记录 run.json、inputs.json、stdout.log、stderr.log、progress.jsonl、artifacts/

基础语法：

uv run --project python python python/velaria_cli.py run start -- <action> ...

公共参数：

• --run-name：给本次执行起一个更易读的名字，便于人工检索
• --description：给本次 run 追加一段备注/描述，便于后续 run show、索引检索和人工回看
• --tag：给 run 打标签，支持重复传入或逗号分隔，便于后续 run list --tag ... 过滤
• --timeout-ms：超时毫秒数；超时后 run 会标记为 timed_out

当前支持的 action：

• file-sql
• vector-search
• stream-sql-once

4.2 file-sql（tracked run 模式）

用途：

• 读取本地文件输入
• 按 --input-type 或自动探测注册成临时视图
• 执行 session.sql(...)
• 把结果落到 artifact 文件，并生成 preview

关键参数：

• --csv / --input-path：输入文件路径
• --table：临时视图名，默认 input_table
• --input-type：输入类型，可选 auto、csv、line、json
• --delimiter：CSV 或 line split 的分隔符
• --line-mode：line 模式，可选 split、regex
• --regex-pattern：line regex 模式下的正则
• --mappings：line 的列映射，例如 uid:1,action:2
• --columns：json 或顺序 line 的列名列表，例如 id,name,score
• --json-format：json 输入格式，可选 json_lines、json_array
• --query：要执行的 SQL
• --output-path：结果文件路径；不传时默认写到 run_dir/artifacts/result.parquet

附加行为：

• 会生成 explain.json
• logical 来自 DataFrame.explain()
• physical / strategy 是 Python 生态层补齐的本地 batch 执行说明

4.3 vector-search（tracked run 模式）

用途：

• 从 CSV 读入向量列
• 调用 Session.vector_search(...)
• 落结果 artifact，并把 native vector explain 单独保存

关键参数：

• --csv：输入 CSV 路径
• --vector-column：向量列名
• --query-vector：查询向量，例如 1.0,0.0,0.0
• --metric：距离指标，可选 cosine、cosin、dot、l2
• --top-k：返回前 K 个结果
• --output-path：结果文件路径；不传时默认写到 run_dir/artifacts/result.parquet

附加行为：

• explain 不会包装成 logical/physical/strategy
• native explain 会单独写到 run_dir/artifacts/vector_explain.txt

4.4 stream-sql-once

用途：

• 用目录流 CSV 作为 source
• 建立 CSV sink
• 执行一次 INSERT INTO ... SELECT ... 的流式 SQL
• 把流式 progress 逐行写到 progress.jsonl

适合场景：

• agent 需要拿到一次性的流式执行快照
• 需要保留 native snapshotJson() 结果做状态观察
• 需要把 sink 文件当成 artifact 管理

关键参数：

• --source-csv-dir：输入 source 目录
• --source-table：source 临时视图名，默认 input_stream
• --source-delimiter：source CSV 分隔符，默认 ,
• --sink-table：sink 表名，默认 output_sink
• --sink-schema：sink schema，必填，用于 CREATE SINK TABLE
• --sink-path：sink 文件路径；默认 run_dir/artifacts/stream_result.csv
• --sink-delimiter：sink CSV 分隔符，默认 ,
• --query：流式 SQL，必须以 INSERT INTO 开头
• --trigger-interval-ms：trigger 间隔
• --checkpoint-delivery-mode：checkpoint 投递模式，例如 at-least-once、best-effort
• --execution-mode：执行模式，例如 single-process、local-workers
• --local-workers：本地 worker 数
• --max-inflight-partitions：最大并发 partition 数
• --max-batches：最多处理批次数；默认 1，保证“once”语义

附加行为：

• explain.json 会保留 native logical/physical/strategy
• progress.jsonl 每一行都直接写 native snapshotJson()，不改字段名

4.5 run list

用途：

• 浏览最近的 tracked runs
• 按 status、action、tag 过滤
• 快速定位某一类分析任务的历史结果

基础语法：

uv run --project python python python/velaria_cli.py run list \
  [--status succeeded] [--action file-sql] [--tag slow-query] [--query triage] [--limit 20]

关键参数：

• --status：只看指定状态，例如 running、succeeded、failed
• --action：只看指定 action，例如 file-sql
• --tag：只看带指定标签的 run
• --query：按 run_name、description、tags、action 做关键词过滤
• --limit：最多返回多少条

返回结果会额外带上适合人工浏览的摘要字段，例如 artifact_count 和 duration_ms。

4.6 run show

用途：

• 查看单个 run 的完整元数据
• 同时列出该 run 关联的 artifacts

关键参数：

• --run-id：目标 run id
• --limit：返回 artifact 条数上限

4.7 run result

用途：

• 直接返回某个 run 的主结果 artifact
• 不需要手动先找 artifact_id
• 同时返回 artifact metadata 和 preview

关键参数：

• --run-id：目标 run id
• --limit：最多预览多少行，默认 50

4.8 run diff

用途：

• 比较两次 run 的核心 metadata
• 比较两边主结果 artifact 的 schema、row_count 和 preview
• 适合快速确认结果是否发生变化

关键参数：

• --run-id：左侧 run id
• --other-run-id：右侧 run id
• --limit：两边 preview 最多各返回多少行

4.9 run status

用途：

• 查看 run 当前状态
• 对 stream run 返回最后一条 progress snapshot
• 对 batch / vector run 返回状态和 artifact 摘要

关键参数：

• --run-id：目标 run id
• --limit：返回 artifact 条数上限

4.10 artifacts list

用途：

• 从 artifact 索引列出结果文件、explain 文件、preview 缓存对应的记录

关键参数：

• --run-id：只看某个 run 的 artifacts
• --limit：最多返回多少条

4.11 artifacts preview

用途：

• 读取某个 artifact 的前 N 行 preview
• 若索引中已有 preview，直接复用
• 若没有，则现算并回写索引

关键参数：

• --artifact-id：目标 artifact id
• --limit：最多预览多少行，默认 50

支持的预览格式：

• csv
• parquet
• arrow

约束：

• preview 会限制大小，避免 SQLite / JSONL 索引膨胀

4.12 run cleanup

用途：

• 清理旧 run 的索引记录
• 可选删除 run 目录文件

关键参数：

• --keep-last N：保留最新 N 个 run
• --ttl-days D：删除超过 D 天的 run
• --delete-files：显式删除 run 目录；不带该参数时默认只清索引，不删文件

5. 脚本示例

5.1 CSV 到 SQL

uv run --project python python \\
  skills/velaria_python_local/scripts/query_csv_to_sql.py \\
  "path/to/file.csv" \\
  --query "SELECT region, COUNT(*) AS cnt FROM csv_data GROUP BY region"

5.2 Excel 到 SQL

uv run --project python python \\
  skills/velaria_python_local/scripts/query_excel_to_sql.py \\
  "python/tests/fixtures/employee_import_mock.xlsx" \\
  --sheet "员工" \\
  --query "SELECT name, dept, COUNT(*) AS cnt FROM excel_data GROUP BY name, dept"

5.3 Bitable 到 SQL

FEISHU_BITABLE_APP_ID=... \\
FEISHU_BITABLE_APP_SECRET=... \\
FEISHU_BITABLE_BASE_URL="https://my.feishu.cn/base/...?...&view=..." \\
uv run --project python python \\
  skills/velaria_python_local/scripts/query_bitable_to_sql.py \\
  --query "SELECT owner, COUNT(*) AS cnt FROM bitable_data GROUP BY owner"

5.4 读取本地 Excel 示例

uv run --project python python \\
  skills/velaria_python_local/scripts/read_xlsx.py \\
  "python/tests/fixtures/employee_import_mock.xlsx" --sheet "员工" \\
  --query "SELECT name, COUNT(*) AS cnt FROM sheet_data GROUP BY name"

6. Agent 辅助分析

配置 Agent runtime。两个 runtime（Codex / Claude）共用相同的配置文件和配置键前缀 agent*。

Codex runtime 默认使用本地 codex app-server：

{
  "agentRuntime": "codex",
  "agentAuthMode": "local",
  "agentProvider": "openai",
  "agentReasoningEffort": "none",
  "agentRuntimeWorkspace": "~/.velaria/ai-runtime",
  "agentCodexNetworkAccess": true
}

{
  "agentRuntime": "claude",
  "agentAuthMode": "local",
  "agentProvider": "anthropic",
  "agentModel": "claude-sonnet-4-20250514",
  "agentReasoningEffort": "none",
  "agentRuntimeWorkspace": "~/.velaria/ai-runtime",
  "agentNetworkAccess": true
}

Codex 默认复用本地 Codex config 中的模型，并在没有本地模型时回退到 gpt-5.4-mini； 只有需要让 Velaria 覆盖本地 Codex 模型时才设置 agentCodexModel。 Claude 默认 claude-sonnet-4-20250514。 agentReasoningEffort 默认是 none，两个 runtime 均支持。 agentRuntimeWorkspace 是 runtime 工作目录，用于保存 agent thread、session 与工具日志。 agentAuthMode: "local" 复用本地 Codex 或 Claude 登录；需要显式凭证时改为 agentAuthMode: "api_key"，并设置 agentApiKey / agentBaseUrl。 Codex 的 agentCodexNetworkAccess 和 Claude 的 agentNetworkAccess 分别控制各自 runtime 的网络访问，默认开启。 只有需要覆盖本地可执行文件时才设置 agentRuntimePath / agentCodexRuntimePath / agentClaudeRuntimePath。 代理直接使用标准环境变量，如 http_proxy、https_proxy、all_proxy。 Velaria usage skill 与 SQL catalog 都是按需资源：需要 SQL 函数、能力边界或常见模板时，优先调用 velaria_sql_capabilities、velaria_sql_function_search、velaria_sql_query_patterns，或读取 velaria://sql/catalog。

CLI 模式

# Velaria Agent TUI
uv run --project python python python/velaria_cli.py

# TUI 内切换当前 runtime 的模型：Ctrl+M 打开选择器，或输入 /model <model-name>

# 脚本化 Agent turn
uv run --project python python python/velaria_cli.py agent --print "按地区统计平均分数"

# 历史兼容的非交互 SQL 生成
uv run --project python python python/velaria_cli.py ai generate-sql \
  --prompt "按地区统计平均分数" \
  --schema "name,score,region,department"

Agent 模式

uv run --project python python python/velaria_cli.py
uv run --project python python python/velaria_cli.py agent --runtime claude
uv run --project python python python/velaria_cli.py agent --stream-json "summarize recent runs"

App 模式

在 Settings 页面配置 Agent Provider（支持 OpenAI 兼容接口或 Claude）。 在 Analyze 页面使用 Agent SQL Assistant 输入框生成 SQL。 支持 Session 管理（开启/关闭会话）以保持上下文。

7. Skill 自检

uv run --project python python skills/velaria_python_local/scripts/smoke.py

输出 ok 代表最小场景（CSV batch + streaming sink）通过。

8. 最小执行清单

1. 先创建或激活一个本地环境，并安装 velaria
2. 选一个脚本加载数据，确保 session.create_temp_view(...) 成功
3. 用 session.sql(...)/脚本 --query 将你的业务分析逻辑落到 SQL
4. 若需可追踪执行、状态查看和 artifact 预览，优先使用 uv run --project python python python/velaria_cli.py run ... 与 uv run --project python python python/velaria_cli.py artifacts ...