القائمة
How to use a locally installed Velaria Python package for local analysis and stream SQL workflows.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | velaria-python-local |
| description | How to use a locally installed Velaria Python package for local analysis and stream SQL workflows. |
这个 Skill 用于说明如何把 velaria 的 Python 包作为本地分析工具使用，不涉及仓库实现代码或编译/构建逻辑。
核心思路：把数据先加载为临时视图，再用 session.sql(...) 写 SQL 处理。
在 Velaria Agent 中处理数据任务时，优先调用已注册的 Velaria local functions/MCP tools：
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。velaria_sql_capabilities、velaria_sql_function_search、velaria_sql_query_patterns 或资源 velaria://sql/catalog 检索，不要凭记忆猜函数。velaria_cli_run 调用 finance ... 子命令，例如 finance fetch-quotes --provider tencent --market cn --symbols 000001。curl、wget 或自定义 Python 下载脚本；只有 Velaria 工具无法覆盖时再回退到通用方式。本 Skill 默认只使用 uv 执行。仓库内可直接使用的入口只有两类：
uv run --project python python python/velaria_cli.py ..../dist/velaria-cli ...如果你已经把 wheel 安装到了独立环境，也可以使用安装后的 velaria-cli / velaria_cli，但下面的示例统一使用仓库内可见入口。
推荐先创建一个本地环境并安装 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 的默认路径。
目录：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 读取示例（兼容旧示例用途）。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>
用途：
external_event source可用子命令：
finance doctor：检查 finance 依赖和公开 quote provider 是否可达finance sources：列出公开 provider、支持市场、freshness 和推荐用法finance analyze：面向用户的一条命令分析入口；获取 quote、入库、运行 monitor，并输出可读研究报告或 JSONfinance pipeline：完整链路入口；获取历史 OHLCV、订阅实时 quote tick、运行 monitor，并输出分析和 service 集成 metadatafinance 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 hitfinance fetch-history：获取历史 OHLCV 行情；优先使用 provider=yahoo，也可使用 provider=aksharefinance fetch-quotes：获取 quote 行；可用 provider=akshare、provider=tencent 或 provider=yahoofinance fetch-news：获取公开新闻、财经新闻或监管 filing evidence；可用 provider=google-news、provider=yahoo-finance-news、provider=sec-filingsfinance fetch-fundamentals：获取公开基本面 evidence；美股可用 provider=sec-companyfactsfinance 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 ops@example.com"
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 jsonfinance pipeline 默认输出人类可读中文报告；Agent 自动化应传 --format jsonfinance 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_notesfinance 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 ingestionfinance watch-session start --async-run 会在后台 CLI 进程中运行同一条 core native stream 链路，前台返回 pid、log_path 和后续命令；Agent 自动化应随后调用 status/logs/signals/summarize/stopfinance watch-session list/show/events/signals/summarize/status/logs/review/supervise/stop 用于观察、调试、停止和复盘同一 session_id 下沉淀的实时数据；Agent 自动化应传 --format jsonfinance watch-session review 会读取 async runtime、进程状态、日志尾部、feed 计数、latest signals 和 provider-unavailable 证据，并把 review 事件写入 finance_watch_session_reviewsfinance watch-session supervise 在 CLI 内持续运行同一 review 循环；--iterations 0 表示持续运行，--interval-sec 控制检查周期，适合通过 velaria_cli_run 保持观察和改进闭环finance doctor / finance sources 默认输出人类可读文本；Agent 自动化可传 --format jsonfinance stream-history 查询 native stream sink 的持久化历史；Agent 自动化应传 --format json，并可传 --source-id finance_<market>_rank_candidates_native_stream_signalsfetch-*、ingest-quotes、watch 默认 stdout 是 JSON，失败也是 JSONfetch-news 输出 sentiment，情绪方法为透明关键词词典，不是不可解释模型判断finance watch 默认在有限 --iterations 后输出一个 JSON；--iterations 0 是持续监听，配合 --jsonl 可逐 tick 输出finance pipeline 输出包含 history、subscription、quote、focus_events、analysis、analysis_prompt 和 service_integrationfinance 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_eventsfinance 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 再生成复盘问题或下一步命令error_type、message、hint、detailsprovider、source_url、fetched_at、freshness、delay_sec、license_notequote、observations、signals、focus_events、artifacts、analysis 和 analysis_promptfinance sources --format json 来自实际 provider registry，是 Agent 选择 provider / command 的优先依据freshness / delay_sec 是研究证据，不要把所有 quote 都当成交易所级实时数据research_candidates 改写成买入、卖出、持有指令Provider 使用建议：
finance doctor，再运行 finance analyze --market cn --symbol 000001finance pipeline --market cn --symbol 000001 --start-date 20250101 --end-date 20250131finance pipeline --market us --symbol AAPL --start-date 20260501 --end-date 20260518 --iterations 1 --format jsonfinance rank-candidates --market us --symbols AAPL,MSFT,NVDA --start-date 20260501 --end-date 20260518 --top 3 --format jsonfinance intelligence start，然后用 finance intelligence review/replay/supervise 和 finance watch-session summarize/events/signals 查询同一会话provider=yahoo；AkShare / Eastmoney 可作为补充 providerprovider=tencentprovider=yahoo，它来自公开 chart metadata，按 provider contract 标记延迟或未知 freshnessprovider=google-news；更聚焦的财经新闻可尝试 provider=yahoo-finance-news；监管 filing 事件可尝试 provider=sec-filings。所有这些 row 都带 source_category/source_type/source_score/source_score_reasonprovider=sec-companyfacts；生产访问 SEC 前先设置 VELARIA_SEC_USER_AGENT 为包含应用名和联系人的 User-Agent；如果 SEC、CIK 或字段不可用，必须保留结构化 unavailable row，不要 mockfreshness=delayed，不要描述为交易所级实时Service 集成：
finance pipeline 使用 CLI 写入 Velaria AgenticStorefinance 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 sourcesfinance 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 sourcesfinance intelligence replay 证明实时数据会自然沉淀为历史数据：它只读取 watch-session 已落库 rows，不再次访问 Yahoo/Tencent/Google News providerfinance intelligence index/search 证明沉淀数据可以继续进入 hybrid retrieval 资产层：索引文件落在 Velaria home，索引事件写入 finance_intelligence_evidence_indexes，搜索事件写入 finance_intelligence_searchesfinance intelligence report 读取同一批已沉淀 rows，输出 supervisor_checks.replayability/data_quality/signal_consistency/provider_quality，并写入 finance_intelligence_reportsfinance 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 链路产生 FocusEventvelaria_service 使用相同 VELARIA_HOME，可通过通用 service routes 查看 CLI 创建的 source、monitor 和 focus-events批量 SQL 当前适合直接走 session.sql(...) 的形态：
CREATE TABLE、CREATE SOURCE TABLE、CREATE SINK TABLEINSERT INTO ... VALUESINSERT INTO ... SELECTSELECT 的列投影 / 别名、WHERE（含列对列谓词）、GROUP BY、ORDER BY、LIMIT、当前最小 JOINLOWER、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_TIMESTAMPSUBSTR(CAST(open AS STRING), 1, 6)约束：
CREATE SOURCE TABLE 是只读表，不允许 INSERTCREATE SINK TABLE 允许写入，但不能作为查询输入ORDER BY 当前只支持对 SELECT 输出中可见的列排序not supported in SQL v1stream SQL 当前边界：
session.stream_sql(...) 只适合 SELECTsession.explain_stream_sql(...) 适合 SELECT 或 INSERT INTO <sink> SELECT ...session.start_stream_sql(...) 只适合 INSERT INTO <sink> SELECT ...ORDER BYORDER BY 会被显式拒绝；当前 runtime 不对无界输入承诺全局有序结果velaria_cli.py run start用途：
run_idrun.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-sqlvector-searchstream-sql-oncefile-sql（tracked run 模式）用途：
--input-type 或自动探测注册成临时视图session.sql(...)关键参数：
--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.jsonlogical 来自 DataFrame.explain()physical / strategy 是 Python 生态层补齐的本地 batch 执行说明vector-search（tracked run 模式）用途：
Session.vector_search(...)关键参数：
--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附加行为：
logical/physical/strategyrun_dir/artifacts/vector_explain.txtstream-sql-once用途：
INSERT INTO ... SELECT ... 的流式 SQLprogress.jsonl适合场景：
snapshotJson() 结果做状态观察关键参数：
--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/strategyprogress.jsonl 每一行都直接写 native snapshotJson()，不改字段名run list用途：
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。
run show用途：
关键参数：
--run-id：目标 run id--limit：返回 artifact 条数上限run result用途：
artifact_id关键参数：
--run-id：目标 run id--limit：最多预览多少行，默认 50run diff用途：
关键参数：
--run-id：左侧 run id--other-run-id：右侧 run id--limit：两边 preview 最多各返回多少行run status用途：
关键参数：
--run-id：目标 run id--limit：返回 artifact 条数上限artifacts list用途：
关键参数：
--run-id：只看某个 run 的 artifacts--limit：最多返回多少条artifacts preview用途：
关键参数：
--artifact-id：目标 artifact id--limit：最多预览多少行，默认 50支持的预览格式：
csvparquetarrow约束：
run cleanup用途：
关键参数：
--keep-last N：保留最新 N 个 run--ttl-days D：删除超过 D 天的 run--delete-files：显式删除 run 目录；不带该参数时默认只清索引，不删文件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"
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"
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"
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"
配置 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。
# 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"
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"
在 Settings 页面配置 Agent Provider（支持 OpenAI 兼容接口或 Claude）。 在 Analyze 页面使用 Agent SQL Assistant 输入框生成 SQL。 支持 Session 管理（开启/关闭会话）以保持上下文。
uv run --project python python skills/velaria_python_local/scripts/smoke.py
输出 ok 代表最小场景（CSV batch + streaming sink）通过。
velariasession.create_temp_view(...) 成功session.sql(...)/脚本 --query 将你的业务分析逻辑落到 SQLuv run --project python python python/velaria_cli.py run ...
与
uv run --project python python python/velaria_cli.py artifacts ...