kimigaiiwuyi SayuStock 插件开发与维护指南（核心入口）
本 SKILL 面向 SayuStock 插件本身的开发者 / 维护者，描述插件结构、行情层、 出图链路、AI 集成与模拟盘，以及后续开发必须注意的约束与坑点。 目标：让不熟悉本仓库的人也能安全地改插件，不踩历史上踩过的坑。
内容按章节拆分为「主入口 +
references/子文档」。需要某专题细节时，顺着下表的相对 路径按需Read对应文件，不要一次性把所有内容塞进上下文。源码永远是唯一 事实源，本 SKILL 是导航与设计意图说明；改动核心后请同步更新对应章节。
谁该读这个 SKILL（与其他文档的分工）
| 你的任务 | 该读的文档 |
|---|---|
| 改 SayuStock 业务代码（行情 / 出图 / 命令 / 模拟盘 / AI 工具） | 本 SKILL |
| 修 CI / 写测试 / 提 PR 对齐 Actions | 本 SKILL 八 + 十 |
| 改 GsCore 框架核心（handler / ai_core / 启动 / 配置基类） | Core .agents/skills/gscore-development |
| 写一个全新的 GsCore 插件（通用模板） | Core .agents/skills/gscore-plugin-development |
| 查 AI Core 给插件暴露的 API | Core .agents/skills/gscore-ai-core-api |
| 用户向模拟盘操作说明 | 插件内 docs/papertrade.md、SayuStock/stock_papertrade/PAPERTRADE_GUIDE.md |
| 行情 Port 一页速查 | 插件内 doc/market_data_port.md |
文档目录索引
| 章节 | 主题 | 链接 |
|---|---|---|
| 一 | 架构与模块全景（目录树、包职责、请求→出图总链路） | references/01-architecture-and-modules.md |
| 二 | 插件布局与命令层（Plugins / SV、各子包命令、to_ai 桥接） | references/02-plugin-layout-and-commands.md |
| 三 | 行情数据层 MarketDataPort（领域模型、适配器、路由、禁止 f*） | references/03-market-data-port.md |
| 四 | 渲染管线（data 服务 → render_data → chart/plotly → render_text / ai_return） | references/04-render-pipeline.md |
| 五 | AI 工具与能力代理（@ai_tools、stock_agent、Kronos 预测） | references/05-ai-tools-and-agents.md |
| 六 | 模拟盘 papertrade（账户/持仓/心跳/撮合/SQLModel） | references/06-papertrade.md |
| 七 | 配置 / 数据库 / 缓存 / 资源路径 | references/07-config-database-cache.md |
| 八 | 测试与质量门（pytest / ruff / pyright、fixtures） | references/08-testing-and-quality.md |
| 九 | 已知坑与开发注意事项（红线、不变量、历史事故） | references/09-developer-pitfalls.md |
| 十 | CI/CD 与本地开发流程（GitHub Actions、双布局、conftest、踩坑） | references/10-cicd-and-dev-workflow.md |
推荐阅读顺序（按需跳转）
- 第一次接触插件：先看 一、架构全景，再看 三、MarketDataPort。
- 加/改用户命令：看 二、命令层。
- 改出图 / 分时 / K 线 / 云图：看 四、渲染管线，并回看 三。
- 接 AI / 加工具 / 改能力代理：看 五。
- 改模拟盘：看 六。
- 动手前必读：九、已知坑。
- 跑测试 / 修 CI / 提 PR 前：八、测试 + 十、CI/CD。
关键概念速记
- GsCore 插件，不是独立 Bot：靠 Core 的
Plugins/SV注册触发器；前缀默认a/股票（见SayuStock/__init__.py）。 - 行情只走
get_market()：业务侧读Quote/IntradaySeries/KlineSeries/BoardSnapshot，禁止解析东财f*或依赖compat编码。 - 供应商字段只在 adapter 内解析：
utils/market/adapters/eastmoney/parse_*.py等是唯一合法解析点。 - 有图必有文字：
ai_return(...)必须在图片缓存判断之前调用；部分模型看不到图，文字是唯一输入。 - 指标单源：图表与 AI 读数共用
utils/indicators.py（通达信/东财口径，勿改用 mplchart 西方 MACD/RSI）。 - 渲染计算单源：
utils/render_data.py；stock_stockinfo与stock_cloudmap只 re-export，不要再分叉拷贝。 - 模拟盘落库 SQLModel：禁止用
record_*/state_set拼第二套账本。 - 插件加载只 import 各包
__init__.py：兄弟模块的@sv/@ai_tools必须在__init__.py里显式 import 才会生效。 - 测试双布局：扁平（无 Core，CI 指标门）与嵌套（
…/plugins/SayuStock，全量 CI）都要能过；依赖test/conftest.py包壳，勿让单测执行SayuStock/__init__.py的 Plugins 链。 - CI 四门全挡合并：lint（ruff）→ indicators（轻量）→ full pytest → basedpyright；细节见 十。
仓库路径约定
gsuid_core/plugins/SayuStock/ # 插件根（本仓库）
├── SayuStock/ # 可导入包
├── test/ # pytest（含 conftest 路径/包壳）
├── .github/workflows/ci.yml # GitHub Actions
├── pyproject.toml # pytest / pyright 配置
├── pyrightconfig.json # basedpyright（勿写死本机 venv）
├── doc/ / docs/ # 散落专题文档
└── .agents/skills/sayustock-development/ # 本 SKILL
运行时数据目录（Core 的 data_store）：
{get_res_path()}/SayuStock/
├── config.json # STOCK_CONFIG
└── data/ # 行情/图缓存 JSON、PNG、HTML
关联文档
- 代码红线：GsCore 根
AGENTS.md（插件内见AGENTS.md） - 行情速查：
doc/market_data_port.md - 模拟盘用户文档：
docs/papertrade.md - 接口/路由旧索引：
doc/interfaces_and_routes.md（可能滞后，以源码为准）