星火行情 kaiwu/sparkles

Sparkles

面向两类编码智能体宿主的只读金融证据工具：终端里的 Pi，以及浏览器里的 DeepSeek Harness (DSH)。
两个发行版复用同一套 Gleam 函数式内核，但宿主注册、会话归属、展示、打包和发布成熟度各自独立。

Pi 和 DSH 两个发行版是各自独立的 ProductUseful T1–T6 版本，通过各自的宿主原生入口覆盖同样的 135 个账本组件。任何组件都无法下单、路由、撤单、改单，也无法以其他方式改动模拟或实盘订单。

| 宿主 | npm 包 | 宿主原生输出 | 发布状态 |
| Pi | @pi-sparkles/pi-sparkles | 终端组件，包括响应式彩色 Unicode OHLCV 图表 | 已发布 · ProductUseful T1–T6 |
| DSH | @dsh-sparkles/dsh-sparkles | 浏览器插槽、会话投影，以及响应式内联 SVG OHLCV 图表 | 已发布 · ProductUseful T1–T6 |

安装与启动

Pi：

pi install npm:@pi-sparkles/pi-sparkles@latest
export AGENT_CONTACT="ops@example.com"
pi --finance-track cn

DeepSeek Harness：

dsh plugin --profile <name> add @dsh-sparkles/dsh-sparkles@latest
export AGENT_CONTACT="ops@example.com"
dsh --profile <name>

无论用哪个宿主，首次向服务商拉取数据之前，都要先运行 /finance-setup 和 /finance-track。适配器缺失是允许的，绝不会触发回退。

| 仓库 | github.com/kaiwu/sparkles |
| 发布指南 | Pi 与 DSH 的 npm 发布线 |
| 层级 | Pi 与 DSH 各自独立通道中的 T1–T6 ProductUseful · Pi 阻塞项 0 个 · tiers.json |
| 清单 | 135 个账本插件 · 142 个 Gleam 插件包 · 77 个金融库 |
| 赛道 | 已关闭 cn / hk / us |
| Pi 版本 | @pi-sparkles/pi-sparkles@0.1.13 · 已在 Pi 1.0.2 上测试 |
| 测试环境 | Pi 1.0.2 · DSH 0.2.0-rc.2 · Gleam 1.18.0 · Bun 1.3.14 |

有七个包不计入汇总（hello、lifecycle、safety_gate、cn_setup、hk_setup、cn_fundamentals、hk_fundamentals），它们是开发用的附加项，不是额外产品。

包级别的 Experimental 标签只是清单信息。ProductUseful 只适用于整个角色层级。层级不是 6×3 的赛道矩阵。见 PRODUCT_TIERS.md。

DSH 发行版挂载了 131 个全局安全外壳，另外还有按智能体区分的对应外壳，用于赛道状态、波段工作台、持仓和自选列表。它的金融赛道状态通过 DSH 浏览器的 shell.overlay 渲染；它的 OHLCV 图表是带键的内联工具结果卡片，而不是 Pi 终端组件。见 dsh/README.md。

用 Pi Durable 记住个人自选

当你使用自选列表时，Sparkles 会给 LLM 一个可以提出的选项：「要不要我跨聊天记住这些选股？」在对话中确认即可，不需要命令行 opt-in。你确认之前，存储和检查都保持关闭。默认私有存储是 ~/.pi-sparkles-watchlist；已确认的存储会随 Pi 重新打开。

保存选股与调度是两回事。你可以要求单次复盘，也可以选择间隔和有限次数的循环复盘。CN 检查复用显式的 Eastmoney A-share 数据源及其运行时 AGENT_CONTACT 要求。HK/US 选股会保存，但它们的定时检查标记为 track_partial。检查在 Pi 打开时运行。通过对话查看结果；失败和中断的调用状态未知，不会自动重新拉取，也没有外部告警。控制和限制见 watchlist。

试试：「我的选股是 CN 600519 和 CN 600000。」如果 Pi 提出记住它们，回复「Yes, remember these picks across chats.」在另一个聊天里，要求显示已保存的自选列表，或用 Eastmoney A-share 行情复盘一次。Pi Durable 1.0.2 按需懒加载；DSH 保留其按智能体的会话自选列表。

Docs

| Doc | Use it for |
| PRODUCT_TIERS.md, tiers.json | six role products, blockers, promotion |
| PRODUCT_READINESS.md | input paths, compact/drill-down contract, non-executing broker boundary |
| CHANGELOG.md, NPM_RELEASE.md | published npm identity and release gate (Pi and DSH lines) |
| dsh/README.md | DeepSeek Harness all-in-one plugin builder + adapter |
| FUNCTIONAL_DESIGN.md | functional core / effect shell |
| TRACK_GUIDE.md | adding another closed market track |
| SECURITY.md | trusted-local-code model |
| FUTU.md | external OpenD runbook; OpenD is never a deliverable |
| plugins/README.md | 135-proposal index |
| pi_gleam/README.md | binding authoring |
| ROADMAP.md | historical family design, not the release ledger |

Develop

Requirements: Gleam and Bun, plus the host used by the lane being tested:
either a hydrated Pi checkout or installed pi, and installed dsh for DSH
runtime verification.

bun run tier:audit
bun run aggregate:build
pi --no-extensions -e ./dist/aggregate/t6 --list-models
bun run test:aggregate:pi

test:aggregate:pi 一次性加载累积的 T1–T6 入口点。按插件和更早层级的 Pi-load 目标不属于验证范围。当该 checkout 有依赖时，它使用 PI_SOURCE_DIR，在此工作区默认是 /home/kaiwu/Documents/github/pi-mono，否则回退到已安装的 Pi。

聚焦诊断成本很低；晋级始终以整个层级为单位：

bun run build -- hello
bun run test:unit -- safety_gate
bun run tier:checkpoint -- T1
bun run test:acceptance -- swing

Opt-in 实时通道不包含在 bun run test 中：

bun run test:live:tutor
AGENT_CONTACT="you@your-real-domain.com" bun run test:live:sec

打包：bun run tier:package -- T1、bun run aggregate:build（T6 表示 T1–T6；只传 T5 可复现之前的边界）、bun run npm:pack、 bun run npm:release:verify。详见 NPM_RELEASE.md 和 PRODUCT_TIERS.md。

Hex 分发的仍然是 Gleam 源码，不是可加载的 Pi 插件，也不是面向用户的产品。pi_gleam 是未发布的 0.1.0 绑定。

运行环境

在启动 Pi 或 DSH 的环境里设置变量。本仓库不加载 .env 文件。改动后重启所选宿主。

| 变量 | 类型 | 使用者 |
| AGENT_CONTACT | 非密钥的操作者身份 | 所有 CN/HK/US 适配器和状态栏 |
| TUSHARE_TOKEN | 凭据 | CN 标的发现和 Tushare 支持的事件工具 |
| ALPACA_API_KEY_ID、ALPACA_API_SECRET_KEY | 凭据 / 密钥 | US 报价、OHLCV、标的池、公司行动、新闻 |
| OPENFIGI_API_KEY | 可选密钥 | finance_symbols（否则匿名访问） |
| TWELVE_DATA_API_KEY | 凭据 | company_profile |
| FRED_API_KEY | 凭据 | macro_fred |

AGENT_CONTACT 用于标识调用方，不授予任何服务商或市场权限。已知的精确 CN 代码可以不用 Tushare，直接使用 Eastmoney 历史数据。Eastmoney、CNINFO、HKEX 和 SEC 只复用 AGENT_CONTACT。T6 审查调用方提供的权限包和回执，不读取券商凭据。

export AGENT_CONTACT="ops@example.com"
export TUSHARE_TOKEN="<secret-manager:tushare>" # optional
export OPENFIGI_API_KEY="<secret-manager:openfigi>" # optional
export ALPACA_API_KEY_ID="<secret-manager:alpaca-key-id>"
export ALPACA_API_SECRET_KEY="<secret-manager:alpaca-secret>"
export TWELVE_DATA_API_KEY="<secret-manager:twelve-data>"
export FRED_API_KEY="<secret-manager:fred>"
Pi
pi --finance-track cn

DSH (select the track with /cn-track after launch)
dsh --profile <name>

生成的 CONFIGURATION.md 只列出名称。每个插件的契约见各自的插件 README。

目录结构

sparkles/
├── pi_gleam/ Gleam binding for Pi's extension API
├── finance/ 77 reusable non-Pi libraries (no Pi imports)
├── plugins/ 142 Gleam plugin packages; 135 are the T1–T6 ledger
├── dsh/ DeepSeek Harness adapter + bundle (parallel npm line)
├── scripts/ Bun task drivers
├── test/ binding, architecture, artifact, acceptance, workflow
├── tiers.json exclusive proposal ownership and promotion state
└── dist/ generated, gitignored Pi and DSH artifacts

根目录不是 Gleam 包。每个 finance/ 和 plugins/ 包都有自己的 gleam.toml、README、源码和测试。根任务通过 gleam.toml 发现包。135 个账本提案全部已实现，没有只剩 README 的遗留项。
架构规则见 FUNCTIONAL_DESIGN.md。插件索引见 plugins/README.md。绑定接口见 pi_gleam/README.md。

任务

| 命令 | 用途 |
| bun run tier:audit | 完整统计六层归属与阻塞项数量 |
| bun run tier:show -- T1 | 查看某一层的结果、配置档、阻塞项、提案 |
| bun run tier:checkpoint -- T1 | 对改动集合做格式化、构建、聚焦测试 |
| bun run tier:verify -- T1 | 为完整的一层跑一次高成本晋级矩阵 |
| bun run tier:package -- T1 | 为一个 ProductUseful Pi 包做内容锁定 |
| bun run tier:install -- T1 | 校验并执行 pi install（默认用户范围） |
| bun run aggregate:build -- [T5\|T6] | 生成单个 Pi 入口；T6 即 T1–T6 |
| bun run npm:pack -- [T5\|T6] | 打包一体化 npm tarball，不发布 |
| bun run dsh:bundle -- [T5\|T6] | 打包一体化 DeepSeek Harness 插件（dist/dsh/dsh-sparkles） |
| bun run dsh:verify | 校验 schema，并针对已安装的 DSH 运行时执行生成的 bundle |
| bun run dsh:npm:pack -- [T5\|T6] | 打包 @dsh-sparkles/dsh-sparkles npm tarball，不发布 |
| bun run dsh:npm:preview:verify | 跑 DSH 适配器测试 + 私有 npm 安装与真实运行时冒烟 |
| bun run check | 对每个包做格式化，并把警告当错误处理 |
| bun run build [-- name] | 诊断用插件 bundle |
| bun run test:unit [-- name] | Gleam 测试 |
| bun run test:architecture | 函数式核心 / 副作用外壳的导入规则 |
| bun run test:ffi | JavaScript 绑定契约 |
| bun run test:artifacts | 生成的扩展模块 |
| bun run test:acceptance [-- swing] | 确定性的 CN/HK/US 行程 |
| bun run test:aggregate:pi | 在 Pi 中一次性加载 T1–T6 |
| bun run test:live:tutor | 需手动开启的 LLM 行程 |
| bun run test:live:sec | 需手动开启的实时 SEC 兼容性测试 |
| bun run test:workflow | 层级清单与晋级规则 |
| bun run test | 完整诊断矩阵 |
| bun run clean | 删除生成产物 |

PI_SPARKLES_TEST_JOBS=1..16 限定单元测试的 worker 数量（默认 4）。发布永远不属于 build 或 test 的一部分。

仍未完成

Pi 与 DSH 的金融产品走两条独立的发布通道。剩下的工作是 Hex 源码发布，以及继续扩大 pi_gleam 的类型化覆盖范围——不是缺角色层级。

- Hex 名称、消费者构建器，以及 hex:check / hex:publish 都还没做。
- pi_gleam 的类型化封装仍然只在插件需要时才增加；其余部分由 pi/raw 兜底。
- 后续日历、官方 CN/HK 申报关联的会计深度、生产环境权益、再分发，都明确保持未知。

未知的事实就让它保持未知。服务商、SDK、网关、凭据、登录状态、实时认证，一律由调用方自己负责。