如何给 Vibe-Trading 提供台股数据？VIBE_TW_STOCK_DB 快照配置
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
Vibe-Trading 内置了一个只读工具get_taiwan_stock_data，用于查询 TWSE（台证）与 TPEx（兴证）的台股快照数据，但它不随仓库附带任何市场数据：只有当环境变量VIBE_TW_STOCK_DB指向一个 schema 合法的 SQLite 快照文件时，这个工具才会被注册进 Agent 的工具列表（见 README.md 的环境变量表与 CHANGELOG.md 中 "registered only whenVIBE_TW_STOCK_DBpoints at a schema-valid snapshot" 的说明）。本文覆盖三件事：把快照文件放对位置、正确配置环境变量（Docker Compose 与非 Docker 两条路径）、验证工具生效并能查询。
工具生效机制：路径如何解析、如何校验
实现见 taiwan_stock_data_tool.py。快照路径的解析规则是：
- 设置了
VIBE_TW_STOCK_DB时，使用该变量的值（环境变量定义见 env_schema.py）； - 未设置时，回退到默认路径
/data/tw-stock/latest.db。这个路径是容器内挂载约定，非容器环境下通常不存在，工具就不会注册。
注册前，工具会通过check_available()做一次性校验：配置路径必须是一个文件、是可读的 SQLite 数据库、并且包含下文列出的全部表与列。任何一项不满足，工具会被静默跳过——工具注册表在 tools/__init__.py 中记录Tool ... unavailable, skipping。注意这个校验发生在 Agent 构建工具注册表时；如果快照文件是在之后才放好的，需要重启 Agent（或容器）让它重新检查。
工具对快照始终以只读、不可变方式打开（file:...?mode=ro&immutable=1），文档中明确写了 "This tool never places orders"，它不会修改快照文件，也不会下单。
快照文件的 schema 要求
REQUIRED_SCHEMA常量定义了工具会读取的四张表及必需列。标识符按 SQLite 惯例做大小写不敏感比较，额外的表或列不影响校验，缺了任何一个必需项就会失败：
| 表名 | 必需列 |
|---|---|
stock_master | stock_id,stock_name,market,industry,enable |
daily_price | date,stock_id,open,max,min,close,Trading_Volume,Trading_money,Trading_turnover,spread |
stock_feature | date,stock_id,ma5,ma20,ma60,ema12,ema26,macd,macd_signal,macd_hist,rsi14 |
analysis_universe | stock_id,stock_name,market,industry,active,reason,price_rows,last_price_date,last_feature_date,trading_day_lag,latest_close |
仓库本身不附带数据文件，快照应由台股数据管线（Taiwan stock pipeline）发布——仓库文档没有给出数据下载地址，需要你自备一份符合上述 schema 的快照文件。想要一份可参照的建表 SQL，可以直接看测试文件 test_taiwan_stock_data_tool.py 顶部的SCHEMA_SQL，它构造的就是一个 schema 合法的测试库。
拿到快照文件后，可以用 sqlite3 快速预检（把路径替换成你的快照文件绝对路径）：
sqlite3 /绝对路径/snapshot.db ".tables"输出中应出现stock_master、daily_price、stock_feature、analysis_universe四张表（多出其他表没有问题）。
Docker Compose 部署：把文件放进约定目录
用 docker-compose.yml 运行时不需要自己写VIBE_TW_STOCK_DB，compose 文件已经配好了：
environment: - VIBE_TW_STOCK_DB=/data/tw-stock/latest.db volumes: - ${VIBE_TW_STOCK_DATA_DIR:-${HOME}/.vibe-trading/tw-stock}:/data/tw-stock:ro即容器内固定读/data/tw-stock/latest.db，它对应宿主机上~/.vibe-trading/tw-stock/目录下的latest.db，以只读方式挂载。compose 注释里强调了这个目录保持在仓库工作树之外（"no market data may ever land in the working tree"），不要改到仓库目录里。
所以最短主路径是：
mkdir -p ~/.vibe-trading/tw-stock # 将你的快照文件放到该目录下并命名为 latest.db如果快照文件放在别的宿主机目录，在仓库根目录的.env文件中设置VIBE_TW_STOCK_DATA_DIR为另一个绝对路径即可（compose 注释明确说明 Compose 不展开~，所以.env里必须写绝对路径）。注意VIBE_TW_STOCK_DB被 compose 的environment段固定为容器内路径，改.env里的VIBE_TW_STOCK_DB对 Docker 部署无效，宿主机侧的开关只有VIBE_TW_STOCK_DATA_DIR。
非 Docker 部署：显式设置 VIBE_TW_STOCK_DB
直接从源码运行 Agent 时，在启动 Vibe-Trading 之前导出该变量：
export VIBE_TW_STOCK_DB=/绝对路径/snapshot.db/绝对路径/snapshot.db替换为你快照文件的实际绝对路径。这是可选变量（README 环境变量表中该项为 No），不设置时回退到容器默认路径，普通主机上一般会导致工具不注册。
验证配置生效
按以下顺序判断：
- 工具是否注册：启动后查看 Agent 是否暴露了
get_taiwan_stock_data工具；若快照未就绪，注册表只记录Tool ... unavailable, skipping，会话里查不到这个工具。这是文档中描述的第一种失败形态——不是查询报错，而是工具直接缺席。 - 查询
status动作：工具可用后，向 Agent 发起action=status的查询。成功时返回的 JSON 信封形如{"status": "success", "tool": "get_taiwan_stock_data", "action": "status", "snapshot": "快照文件名", "data": {...}}，其中data包含各表行数（stock_master_rows、daily_price_rows等）、latest_market_date、integrity（即PRAGMA integrity_check的结果）、journal_mode以及reason_distribution。这些字段来自你快照文件的真实内容，不是固定预期值。 - 跑仓库自带测试：
pytest agent/tests/test_taiwan_stock_data_tool.py该测试在临时目录中构造 schema 合法的快照，覆盖VIBE_TW_STOCK_DB设置后check_available()返回 True、文件缺失或 schema 不符时返回 False 等行为，可以确认工具链本身工作正常。
查询方式与输出限制
工具支持五个action：status（快照摘要）、lookup（个股身份与是否可分析）、latest（最新价与技术指标）、history（历史日线）、universe（分析池列表）。关键参数：
stock_ids：台股四位数字 ID，例如["2330", "2317"]；lookup/latest/history必填，最多 50 个；start_date/end_date：YYYY-MM-DD格式，start_date不能晚于end_date；market：仅universe可用，取值twse或tpex；industry为部分匹配过滤；active_only：universe查询默认true，只返回 active 标的；limit：默认 60、上限 200，对universe是最大行数，对history是每只股票的最大 K 线数。
两个需要理解的输出行为：
- 截断：响应受 9,500 字符的工具结果预算限制。超出时按"每只股票最新 K 线优先、轮流保留"的顺序丢弃最旧的行，并在返回中给出
truncated: true和提示：收窄日期范围、调低limit或减少stock_ids数量。 stale_features标记：最新价行与最新指标行按各自日期独立选取，可能不在同一天；不一致时该行会带stale_features: true，不要把指标日期当作价格日期。- 查询中未命中的 ID 会出现在
not_found（lookup/latest）或not_found_or_no_rows（history）里。
错误信息与限制
如果查询时报错，工具会给出三种带具体原因的失败信息，直接对应排查方向（见 taiwan_stock_data_tool.py）：
- 文件不存在：
Taiwan stock snapshot not found: <路径>. Point VIBE_TW_STOCK_DB at a published snapshot file.—— 检查VIBE_TW_STOCK_DB（或 Docker 下的VIBE_TW_STOCK_DATA_DIR）指向的文件是否真的存在； - 不是可读的 SQLite 数据库：
Taiwan stock snapshot <路径> is not a readable SQLite database: ...； - schema 不符：
Taiwan stock snapshot <路径> does not match the required schema: ...，消息中会逐一列出缺失的表或列，对照上文的 schema 表补齐即可。
限制方面：该工具是纯只读快照查询，不联网拉取数据，也不支持下单；快照内容的新鲜度取决于发布方，status里的latest_market_date可以反映快照覆盖到哪天。数据文件放置完成后，若工具仍未出现，先重启 Agent 让注册表重新执行check_available()。
【免费下载链接】Vibe-Trading"Vibe-Trading: Your Personal Trading Agent"项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
