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  add @dsh-sparkles/dsh-sparkles@latest
export AGENT_CONTACT="ops@example.com"
dsh --profile

在任一宿主中，请在首次提供方拉取之前运行 /finance-setup 和 /finance-track。允许缺少适配器，且绝不会触发回退。

| | |
| --- | --- |
| 仓库 | github.com/kaiwu/sparkles |
| 发布指南 | Pi 和 DSH npm 产品线 |
| 层级 | 独立的 Pi 和 DSH 通道中的 T1–T6 ProductUseful · 0 个未解决的 Pi 阻塞项 · tiers.json |
| 清单 | 135 个账本插件 · 142 个 Gleam 插件包 · 77 个金融库 |
| 轨道 | 已关闭的 cn / hk / us |
| 测试环境 | Pi 0.84.1 · DSH 0.1.1-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。

文档

| 文档 | 用途 |
| --- | --- |
| PRODUCT_TIERS.md、tiers.json | 六个角色产品、阻塞项、晋升 |
| PRODUCT_READINESS.md | 输入路径、紧凑/下钻契约、非执行券商边界 |
| CHANGELOG.md, NPM_RELEASE.md | 已发布的 npm 标识与发布门禁（Pi 和 DSH 线） |
| dsh/README.md | DeepSeek Harness 一体化插件构建器 + 适配器 |
| FUNCTIONAL_DESIGN.md | 功能核心 / 效果外壳 |
| TRACK_GUIDE.md | 添加另一个封闭市场赛道 |
| SECURITY.md | 可信本地代码模型 |
| FUTU.md | 外部 OpenD 运行手册；OpenD 从不是交付物 |
| plugins/README.md | 135 项提案索引 |
| pi_gleam/README.md | 绑定编写 |
| ROADMAP.md | 历史家族设计，而非发布台账 |

开发

要求：Gleam 和 Bun，以及所测试赛道使用的主机：
要么是已水合的 Pi 检出，要么是已安装的 pi，以及用于 DSH
运行时验证的已安装 dsh。

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 加载目标不属于验证范围。当该检出具有其依赖项时，
它使用 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

可选的实时赛道被排除在 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 代码可以使用 Eastmoney 历史数据，无需 Tushare。Eastmoney、CNINFO、HKEX 和 SEC 仅复用 AGENT_CONTACT。T6 审查调用方提供的能力包和回执；它不读取券商凭证。

export AGENT_CONTACT="ops@example.com"
export TUSHARE_TOKEN=""            # optional
export OPENFIGI_API_KEY=""        # optional
export ALPACA_API_KEY_ID=""
export ALPACA_API_SECRET_KEY=""
export TWELVE_DATA_API_KEY=""
export FRED_API_KEY=""
Pi
pi --finance-track cn

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

生成的 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 | 针对已安装的 DSH 运行时进行 schema + 生成包执行 |
| 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] | 诊断插件打包 |
| 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 限制单元测试工作进程数（默认 4）。发布
永远不属于 build 或 test 的一部分。

仍未完成

Pi 和 DSH 金融产品通过独立的发布通道交付。
剩余工作是 Hex 源码发布以及进一步扩展带类型的 pi_gleam
覆盖范围——而非缺失的角色层级。

- Hex 名称、消费者构建器以及 hex:check / hex:publish 尚未构建。
- pi_gleam 带类型的包装器仅在插件需要时才会增加；pi/raw
覆盖其余部分。
- 后续日历、官方 CN/HK 申报关联的会计深度、生产环境授权以及
再分发仍明确未知。

未知事实保持未知。提供商、SDK、网关、凭据、登录
状态以及实时认证仍由调用方负责。