Vibe-Trading 定时研究 Playbook 深度解析A 股盘后资金流复盘模板 a-share-money-flow 的设计与调度实现【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本文以 Vibe-Trading 内置的定时研究 Playbook a-share-money-flow.md 为核心完整拆解这份收盘后 A 股资金流向复盘指令模板的元数据、方法论与输出契约并结合 playbooks.py、executor.py、verdict.py 等源码说明它如何被加载、渲染、排程为可重复触发的研究任务以及如何通过 CLI、REST 与斜杠命令三种入口使用。读完本篇你既能理解这份 Playbook 的每个章节为什么这样写也能掌握 Vibe-Trading 定时研究模板体系的整体机制。一、模板定位一个盘后资金流复盘研究任务a-share-money-flow.md 的目标只有一句话在刚收盘的 A 股交易日结束后复盘钱到底去了哪里。它不是行情摘要也不是选股清单而是一份对交易所公开信息做事实性交叉核验的复盘报告覆盖五类证据面交易所每日公开交易信息披露上榜个股及买卖席位金额当日北向 Stock Connect 资金流按成交单规模拆分的个股与行业资金流当日两融融资与融券余额的总量与异动个股当日板块与行业表现排行、涨跌停个股及成交/触板信息。该文件与另外四个内置模板earnings-season-tracker、institutional-holdings-diff、portfolio-checkup、premarket-brief共同构成 Vibe-Trading 的 Playbook 目录。测试 test_research_playbooks.py 中的EXPECTED_SLUGS常量精确锁定了这五个内置模板的 slug 集合。二、Frontmatter目录记录的逐字段解读Playbook 文件由 YAML frontmatter 与 Markdown 正文两部分组成。frontmatter 是目录记录catalogue record供列表、检索与任务创建使用正文是运行时逐字交给 Agent 的指令文本。a-share-money-flow 的 frontmatter 如下--- name: A-Share Money Flow Review description: Post-close A-share flow review — exchange public trading disclosures, northbound flows, sector money flow and the limit-up board. markets: [cn] suggested_schedule: 0 19 * * 1-5 suggested_timezone: Asia/Shanghai data_capabilities: - Exchange daily public trading disclosures naming the top buying and selling seats for each listed stock - Northbound Stock Connect flow figures for the session - Per-stock and per-sector money flow broken down by order size - Margin financing and securities lending balances by stock and in aggregate - Sector and industry performance rankings for the session - Daily price, volume and turnover history for individual A-share tickers variables: watchlist: (no watch list configured) ---各字段的含义与源码约束playbooks.py字段值/说明源码约束name人类可读标题 A-Share Money Flow Review必填_REQUIRED_METAdescription目录列表中的一行摘要必填_REQUIRED_METAmarkets[cn]标记该模板面向 A 股市场省略时默认(global,)必须是字符串列表且无空项_string_list校验suggested_schedule0 19 * * 1-5每周一至周五 19:00 触发加载时经validate_schedule校验接受毫秒间隔整数或 5 字段 cronmodels.py 中CRON_BOUNDS ((0,59),(0,23),(1,31),(1,12),(0,6))suggested_timezoneAsia/Shanghaicron 按上海墙上时钟求值加载时只做形状校验validate_timezone_shape在to_job()时经ZoneInfo真正解析data_capabilities六项自然语言数据能力声明必须是列表且每项非空刻意不写工具名——测试test_declares_data_capabilities_not_tool_names断言其中不出现任何 snake_case 标识符variableswatchlist默认值(no watch list configured)正文中出现的每个{{占位符}}必须在variables中声明否则加载失败其中suggested_schedule: 0 19 * * 1-5值得单独说明5 字段 cron 依次为分、时、日、月、周1-5表示周一到周五cron 约定Sunday 0models.py的注释明确不接受7作为周日别名因此该模板建议每个 A 股交易日的 19:00Asia/Shanghai即收盘后 1.5 小时多数交易所公开信息已发布自动运行一次复盘。三、正文方法论七项数据、五条方法、六条缺失规则正文是ScheduledResearchJob.prompt的逐字来源playbooks.py模块 docstring 明确the body is the instruction text that becomesScheduledResearchJob.promptverbatim。它由六个章节构成全部保留如下核心内容。3.1 运行日期锚定正文开篇即要求从运行环境解析当前日期并用取回的数据本身确认会话日期遇到节假日或半天市最新可用会话可能不是今天必须在第一行写明报告覆盖的是哪一天。这一点由测试test_body_resolves_the_run_date_at_run_time强制保障所有内置模板正文必须包含 run environment且禁止出现任何20xx-xx-xx硬编码日期——因为 prompt 在创建时持久化一次、之后每次触发都原样重放the prompt is persisted once at creation and re-sent unchanged on every fire写死日期会在第 N 天变成错误事实。3.2 Inputswatchlist 变量模板声明了唯一变量{{watchlist}}。正文说明watchlist 只在最后追加一个交叉参照章节其余部分是全市场视角配置与否都能运行。这对应 frontmatter 中的默认值(no watch list configured)——用户不传变量时渲染结果就是默认占位文案报告照常产出。3.3 Data to gather七项数据清单模板按顺序列出运行期必须采集的七类数据当日交易所公开交易信息哪些个股上榜、上榜原因、每只个股买卖前五席位及金额当日北向 Stock Connect 资金流粒度以数据源实际发布为准按成交单规模拆分的资金流行业层面 当日最活跃个股当日两融余额总量 任何大幅异动个股当日板块与行业表现排行收盘封住当日涨跌停的个股涨跌停双向、成交额与触板时间数据源提供多少算多少对 watchlist 中每个代码当日涨跌幅、成交额以及是否出现在上述任何名单中。3.4 Method五条方法纪律这是模板的方法论核心逐条对应 A 股数据的特殊性涨跌停幅度分板确定A 股不同板块的每日价格涨跌幅限制不同特殊处理如风险警示个股又不同。模板要求从取回的数据中确定适用幅度而不是给全市场假设同一个数字且必须写明每只涨停股所在板块。席位信息只描述披露字面席位级公开信息显示的是交易通道对手方渠道不是投资者身份。只写该席位买入该金额不得点名或刻画席位背后是谁。北向粒度如实声明若数据源只发布收盘汇总值就用汇总值并明说禁止用收盘数字反推盘中路径。交叉核验当日叙事某板块表现领先但资金流不领先、或某涨停股没有匹配资金流——这类矛盾值得单独一行作为contradiction指出而不是抹平。单位与币种如实标注按数据源使用的币种与单位报告并标注单位。3.5 When data is missing缺失数据协议模板将数据源空返回、报错或未配置定义为要报告的事实而不是要填补的空隙并给出六条硬规则在Data gaps章节逐项点名缺失项若失败给出了原因也要写上只使用本次运行实际取回的证据继续撰写永不用记忆、一般先验、第三方摘要或本 Playbook 之前某次运行的数值替代——本次运行没有取回的资金流数字不出现在本报告里永不把过期数字当现价呈现。多类披露在收盘后不同时间发布若最新可得记录属于前一个会话必须把它和日期一起印出来、标注为前一会话而非今日若整节都没有证据保留章节标题下面写no data retrieved每个数字都携带会话日期、单位与来源。这组规则不是散文而是有测试锁定的契约test_body_carries_the_missing_data_rule断言所有内置模板正文必须包含## When data is missing、Data gaps、from memory、third-party summary等关键表述。3.6 Output九段式输出契约报告必须是 Markdown且章节顺序固定## Session— 报告覆盖的日期与当日指数收盘## Northbound— 取回的资金流数字注明粒度## Sector flow— 排行表板块、当日涨跌幅、净流、单位## Public trading disclosures— 逐股上榜原因、买五席位、卖五席位、净额## Limit board— 涨停与跌停个股、所在板块、成交额以及它们若存在板块聚集则指出聚集方向## Margin balances— 总量变化与值得注意的单股变化## Watch list cross-reference— 未提供 watchlist 时整节省略## Data gaps—恒在无缺失时写none## Verdict— 机器可读尾部且是唯一允许最后出现的章节每个被跟踪代码一行- SYMBOL: STATE - one short reasonSTATE 为本模板声明的ACTIVE或QUIET二选一若本轮没有任何标的异动就输出只有标题、没有条目的一节——这是一个真实答案而不是缺失。该章节只报告状态、不给建议受 Boundaries 约束。3.7 Boundaries行为边界单会话的事实性复盘不给买卖/持有意见、不给价格目标、不做次日预测不提交、不修改、不取消任何订单不触碰任何实盘交易连接器不把资金流归因到具名机构、基金或个人只报告披露的通道与金额集中买入是观察不是信号——说到披露了什么就停。测试test_body_states_output_and_boundaries将 No buy, sell, or hold calls、no price targets、Do not place, modify, or cancel any order 设为所有内置模板正文的强制存在项并对换行做了归一化防止断行绕过检测。四、数据能力声明到工具实现的映射data_capabilities刻意使用自然语言而非工具名原因写在 playbooks.py 模块 docstring 中No template names a tool. A playbook states the datacapabilityit needs in plain language and lets the agent route to whatever tool provides it, so the templates survive changes to the tool surface.模板不点名工具让 Agent 自行路由从而在工具面变化时模板依然存活。测试test_body_names_no_tool甚至断言正文去掉占位符后不得出现任何 snake_case 词因为这个仓库里所有工具名都是 snake_case。对照 agent/src/tools/ 下的实际工具六项能力在源码中都有对应实现以下对应关系从源码结构看是能力与工具的语义匹配模板本身并不绑定它们data_capability对应工具文件交易所每日公开交易信息上榜个股与买卖席位dragon_tiger_tool.py龙虎榜/公开交易信息北向 Stock Connect 资金流northbound_tool.py按单规模拆分的个股/行业资金流fund_flow_tool.py两融余额个股与总量margin_trading_tool.py板块/行业表现排行sector_tool.py个股日级价量成交额历史各市场数据加载器akshare、eastmoney、tushare、baostock 等 loader 家族这一设计意味着即便上述某个工具日后改名、拆分或替换数据源只要新工具仍提供交易所公开交易信息这类能力这份 Playbook 无需任何修改即可继续工作。五、加载机制从 .md 文件到 ResearchPlaybook目录发现、文件解析、slug 命名均由 playbooks.py 负责关键机制如下。5.1 目录链与覆盖规则playbook_dirs()按优先级返回候选目录环境变量VIBE_TRADING_PLAYBOOK_DIR指向的目录若设置优先于随仓库内置的playbooks/数据目录。list_playbooks()遍历时先出现的 slug 遮蔽后面的同名 sluga slug found in an earlier directory shadows the same slug later即用户文件同名即覆盖内置文件。测试test_user_file_shadows_bundled_slug验证了这一点并断言覆盖是替换而非追加slug 集合保持五个。5.2 文件名即 slug命名即校验文件名主干就是模板的稳定 IDslug。_SLUG_RE ^[a-z0-9][a-z0-9-]*$要求小写字母、数字、连字符。校验发生在加载时而不仅是查询时——测试注释解释了动机一个list_playbooks能枚举、但get_playbook会拒绝的文件如My_Playbook.md必须大声失败而不是变成目录里一个永远选不中的条目。a-share-money-flow.md正是符合该规则的文件名其 slug 即a-share-money-flow。5.3 frontmatter 解析的严格性用utf-8-sig读取load_playbook_file中注释Windows 编辑器留下的 BOM 否则会被读成缺少 frontmatterfrontmatter 正则_FRONTMATTER_RE刻意比通用解析器更严格因为 Playbook 元数据携带含逗号的块序列自然语言短语yaml.safe_load解析后必须是 mapping缺name/description/suggested_schedule/data_capabilities任一必填键即抛PlaybookError正文为空、正文使用了未声明的占位符都直接拒绝加载损坏的 Playbook 是错误而非可跳过的文件list_playbooks的 docstring 写明 A broken playbook is surfaced, not skipped测试test_broken_user_file_surfaces_instead_of_being_skipped锁定了该行为。5.4 变量渲染一次持久化永远重放render()将正文中的{{name}}替换为variables声明的默认值或调用方覆盖值规则包括传入未声明的变量名 →PlaybookError而不是静默忽略空值回落到声明的默认值单个变量文本上限_MAX_VARIABLE_CHARS 4000字符注释说明理由One substituted variable is user text pasted into a prompt that is persisted and replayed forever; cap it so a paste accident cannot bloat every run.一次粘贴事故不能撑爆每一次运行。a-share-money-flow 的watchlist变量正是走这条路径用户创建任务时传watchlist600519, 000858渲染后写入## Inputs章节并永久存于 job 的 prompt 中。六、从 Playbook 到定时任务to_job 与首次触发规则ResearchPlaybook.to_job()playbooks.py把模板转换为PENDING状态的 ScheduledResearchJob要点job_id默认playbook-{slug}-{8位hex}如playbook-a-share-money-flow-3f2a9c1bschedule 与 timezone默认取suggested_schedule/suggested_timezone显式传timezoneNone表示强制 UTC与保持建议时区的_KEEP哨兵严格区分首次触发规则带时区的 cron 任务next_run_at由executor.next_due(schedule, now, tz)计算为创建之后的第一个计划时刻无时区或间隔任务则立即可触发。a-share-money-flow 是带Asia/Shanghai的 cron因此周五 19:00 之后创建要等到下周一 19:00。测试test_renders_and_schedules断言job.next_run_at NOW_MSREST 侧测试test_suggested_timezone_defers_first_fire_to_an_authored_occurrence进一步断言一个工作日的 19:00 节奏绝不会在创建时刻触发config 溯源自动写入config[playbook] a-share-money-flowREST 路由还会补上source_typeplaybook与playbook_slugscheduled_routes.py 中create_scheduled_run_from_playbook处理逻辑。cron 求值的实现细节executor.py 的next_due()先做格式判定纯数字字符串走间隔毫秒分支after_ms int(spec)否则按 cron 求值。_next_cron_due以目标时区的本地日历逐日推进候选日按天搜索而非按分钟_CRON_SEARCH_LIMIT_DAYS 6*3661注释解释四年窗口覆盖含闰日 2 月 29 的真实周期额外余量吸收 DST 春季跳变间隙日匹配遵循标准 5 字段 cron 语义dom与dow同时受限时取 OR_day_matches。0 19 * * 1-5在该实现下展开为每月任意日、19 时 0 分、周一到周五按 Asia/Shanghai 墙上时钟转 UTC epoch 毫秒。DST 策略同样明确_local_wall_time_to_epoch_ms春季跳变中不存在的墙上时间直接跳过该次触发秋季回拨的歧义时间取fold0首次出现。任务到期判定is_due()另有两层防护终态CANCELLED/FAILED/EXPIRED/RUNNING任务永不重放若该次触发的投递 outbox 行仍处于PENDING/SENDING则跳过——dispatch 在运行被接受时返回而不是在投递完成时返回短于该间隔的调度否则会覆盖同一 outbox 行、孤立一条仍欠付的简报。七、Verdict 尾部机器可读契约如何落地模板第 9 节## Verdict不是给人看的附录而是被 verdict.py 的解析器严格消费的契约标题必须恰好是## Verdict_HEADING_RE多行匹配取到下一个##标题为止的正文逐行匹配- SYMBOL: STATE - reason_ITEM_RESTATE 保持不透明 token词汇表由各 Playbook 自行声明——本模板为ACTIVE/QUIET解析只有三种状态ok、no_verdict_section无标题如临时 prompt、contract_violation有标题但某行不合契约——anything malformed must degrade tocontract_violationrather than guessMarket Watch 列表直接渲染该记录绝不重读自由文本outcome_of()派生服务器侧摘要空列表为no_calls全部条目同状态时取该状态否则mixed解析出的VerdictRecord在运行到达终态时被 executor.py 的_record_verdict_on写到 job 的last_verdict字段并内嵌一层previousa verdict chain any deeper is noise for the list view使列表视图一次查询即可渲染前后两次的差异。对 a-share-money-flow 而言一轮 19:00 的复盘结束后last_verdict里形如- 600519: ACTIVE - limit up with disclosed seat buying这样的条目就沉淀在任务记录上无需打开报告全文即可判断本轮是否出现资金异动。八、使用方式CLI、REST 与斜杠命令tests/test_playbooks_surface.py 锁定了三个入口且要求三者产出逐字节一致的 prompttest_all_three_surfaces_produce_the_same_promptREST、CLI、slash 三条路径的 prompt 完全相等且等于get_playbook(slug).render(variables)。8.1 CLI# 列出目录含 a-share-money-flow 等五个内置模板 vibe-trading playbook list vibe-trading playbook list --json # 查看模板完整正文 vibe-trading playbook show a-share-money-flow vibe-trading playbook show a-share-money-flow --json --var watchlist600519,000858 # 按模板创建定时任务默认 schedule 0 19 * * 1-5时区 Asia/Shanghai vibe-trading playbook create a-share-money-flow --id ashare-flow \ --var watchlist600519,000858 # 覆盖调度 / 强制 UTC / 只预览不落盘 vibe-trading playbook create a-share-money-flow --id flow-30m --schedule 1800000 vibe-trading playbook create a-share-money-flow --id flow-utc --utc vibe-trading playbook create a-share-money-flow --dry-run参数行为均有测试背书--utc与--timezone互斥退出码 2 且提示 mutually exclusive非法 schedule 报 out of range未声明变量名被拒绝且不落盘未知 slug 会列出可用 slug。8.2 REST路由定义在 agent/src/api/scheduled_routes.pyGET /scheduled-runs/playbooks— 目录列表不含正文body恒为null保证列表小体积GET /scheduled-runs/playbooks/{slug}— 单模板详情to_dict(include_bodyTrue)返回逐字正文POST /scheduled-runs/playbooks/{slug}— 按模板建任务请求体可含id、variables、schedule、timezone成功返回 201且config.playbook记录来源 slug。TestRestAuth是一个结构性守卫断言/scheduled-runs下每一条路由都声明了require_auth配置API_AUTH_KEY后无凭据请求返回 401/403Authorization: Bearer key通过。测试还覆盖了校验细节未知 slug 返回 404、不安全 slug如bad.slug返回 400、timezone: null强制 UTC 且立即可触发。8.3 斜杠命令交互式会话中/playbook命令research_playbook.py支持list / show / run / schedule四个动作run把渲染后的正文作为 pending prompt 排入当前会话字节级等同调度器将重放的文本schedule直接持久化一个定时 job变量支持不带引号的多词值run a-share-money-flow watchlist600519 000858会被解析为单个多词值。九、用户自定义目录覆盖与继承规则由于发现链支持VIBE_TRADING_PLAYBOOK_DIR用户可以把自研 Playbook 放在任意目录并整体加入目录同名文件则覆盖内置版本。要复刻 a-share-money-flow 的结构写一份自己的模板需要满足加载器的全部硬约束文件名是合法 slug小写字母/数字/连字符、frontmatter 含四个必填键、schedule 通过validate_schedule、variables为 name→默认值映射、正文非空且占位符全部声明。加载期对 BOM、YAML 语法、空能力项、坏 slug 的拒绝行为都有对应测试TestLoader组。十、测试体系模板契约如何被固化围绕这份 Playbook 及其基础设施仓库用两个测试模块形成了双层约束test_research_playbooks.py —— 模板与加载器层五个内置 slug 的完整性、schedule/时区有效性、markets覆盖cn与global、能力声明与正文均无工具名、缺失数据规则四要素恒在、Output/Boundaries 章节与三条纪律恒在、正文无硬编码日期、build_job(slug, now_ms固定时钟)产出PENDING任务且next_run_at NOW_MScron时区首次触发外加加载器全部失败模式与目录覆盖规则。test_playbooks_surface.py —— 三个入口层REST 目录/详情/创建含认证守卫与 400/404/422 边界、CLI 三个子命令list/show/create 及--json、--utc、--dry-run、互斥参数、斜杠命令注册与四个动作最后是跨入口一致性断言与REST 目录即加载器输出断言test_catalogue_size_matches_the_loader。其中NOW_MS 17855856000002026-08-04T12:00:00Z这类固定时钟注入使首次触发的断言不依赖墙钟——这与 executor.py 模块 docstring 宣称的Schedule math is intentionally pure and clock-injected设计一致。十一、小结a-share-money-flow 是 Vibe-Trading 定时研究 Playbook 体系中一个完整的样板frontmatter 以suggested_schedule: 0 19 * * 1-5Asia/Shanghai声明了每个 A 股交易日收盘后 19 点自动复盘的节奏正文用七项数据清单、五条方法纪律、六条缺失数据协议和九段式输出契约把事实性复盘做成了可机器校验的行为规范而data_capabilities的自然语言声明配合 dragon_tiger_tool.py、northbound_tool.py、fund_flow_tool.py、margin_trading_tool.py、sector_tool.py 等工具实现使模板与具体工具解耦。加载器、调度器、Verdict 解析器与三入口测试共同保证了从vibe-trading playbook create a-share-money-flow这一条命令到每个工作日 19:00 的自动触发、简报投递与ACTIVE/QUIET状态沉淀整条链路都是可验证、可重复、可被用户同名覆盖的。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考