senpi-trading-runtime

Senpi 交易运行时——运行时契约

此技能属于基础设施：它记录了 Senpi 运行时（@senpi-ai/runtime）的规范行为，以及策略如何与其交互。生命周期技能——author（构建）、ops（安装/监控）、discover（推荐）——均以此为准。

运行时模型

策略从一个指向仓库内 Python 模块的 runtime.yaml 运行。运行时会启动并监控该模块，并每隔 interval_seconds 调用一次冻结的 scan(inputs, ctx)。职责划分是固定的：

• 你的代码只生成信号，不做其他事情。 scan(inputs, ctx) 读取市场和账户数据，并返回候选信号组成的 list[dict]。它不会开仓、平仓、调整仓位、安排计划或执行任何操作。
• 零模型成本，且这是唯一的循环。 运行时每隔 interval_seconds 运行一次，不会调用模型。切勿在旁边再安排 Agent 轮次的 cron——无论是生成器、复查还是监视器；每次触发都是一次完整的模型调用。系统没有模拟交易模式：使用 senpi validate 测试策略（一次真实运行，不需要钱包），然后以 10 美元的最低金额实盘运行。
• 运行时负责所有后续工作： 调度（interval_seconds）、启动 + 监控 + 重启扫描器、验证（signal_data_schema）+ 对你返回的信号去重、仓位调整与订单执行（FEE_OPTIMIZED_LIMIT）、槽位核算、risk.guard_rails、两阶段 DSL 移动止损退出，以及重启时的崩溃安全持仓对账。
• 运行时不负责的事项：部分退出。 运行时执行的所有退出（DSL、CLOSE_POSITION）都会平掉整个仓位，而 edit_position——唯一能减仓的操作——会被扫描器拦截。因此，像“ROE 达到 +10% 时平掉 25%，其余继续持有”这样的规则，根本无法在运行时包中实现；扫描器若尝试执行，每次运行都会引发 PermissionError，但日志却会显示规则似乎正在生效。详情：references/runtime-concepts.md → DSL 退出引擎。

代码如何与运行时交互

交互接口简洁且单向：你读取数据并返回信号，运行时负责执行。

• runtime.yaml 声明扫描器、操作门控、退出引擎和风险护栏，并通过 inputs: 传入可由作者调整的参数。→ references/runtime-yaml.md
• scan(inputs, ctx) 是唯一入口。inputs 是运行时的 inputs: 映射；ctx 提供：
  • ctx.senpi_mcp.call_tool(name, args)——Senpi MCP 客户端，只读（市场、账户、排行榜、发现、strategy_get* 等）。这是获取数据的唯一方式。
  • ctx.state——由运行时持久化的事务性历史记录（last() / append() / len），用于去重、轮换和首次发现记录；只有在一次运行成功完成后才会推进。
  • ctx.wallet——策略的钱包地址。
  • → references/scan-contract.md
• 返回值是一个 list[dict]，每项对应一个候选信号（asset、direction、marginPct、leverage、data{}）。运行时会根据 runtime.yaml 的 signal_data_schema 验证每个 data{}，然后调整仓位、执行交易并管理退出。

将策略逻辑放在同级的纯函数 scoring.py 中（不执行 I/O，也不使用 MCP），以便进行单元测试；scan.py 负责读取数据和处理状态，scoring.py 负责计算。

运行时命令（基础用法）

该插件会在网关上注册一个 senpi 命令组。部署策略并检查状态：

openclaw plugins install @senpi-ai/runtime
openclaw senpi validate <dir-with-runtime.yaml>        # THE GATE, pre-money: one real tick, no wallet; a PASS records the proof deploy requires
openclaw senpi deploy -p <package-dir> --budget <usd>  # ONE verb, detached: funds preflight → wallet create+fund → install → one observed tick
openclaw senpi deploy status                           # poll until terminal; the verified report (read-only)
openclaw senpi runtime list                            # id, source, status ("running — NO ENTRY SCANNERS" = scanners never wired)

通过 senpi-strategy-ops 的 deploy.py create <id> --budget <usd> 部署软件包，该命令会解析软件包、运行结构预检，并驱动同一操作。该操作负责所有门控——实盘标的范围检查（[E_UNIVERSE_NOT_LIVE]，资金投入前）、资金预检、skillName/skillVersion 归属信息以及已验证的运行周期。runtime create 属于内部命令：它会安装运行时，并跳过上述所有检查，因此不能用于部署。 senpi validate 是每次部署都必须通过的关卡——它会加载扫描器，并在没有钱包、没有资金的情况下运行一次真实的 tick；在实时深度下完整通过且不受范围限制，才会生成 .senpi-proof.json，而 senpi deploy 没有该文件就拒绝为程序包注资。运行 deploy 前，每个实例都要运行一次，并将其指向存放该实例 runtime.yaml 的目录。

要修改已上线的策略 → 用 openclaw senpi update，不要先删除再重新部署。 删除运行时会丢弃其 DSL 持仓文件，因此每个未平仓位都会失去策略原本承诺的追踪止损，而替换后的策略会从头开始，按它找到的任意价格重新接管持仓。update 会就地替换组件，并保留 DSL 状态、扫描器存储和操作历史——不会创建钱包，不会注资，也不会平仓。

openclaw senpi update ./pkg                       # PLAN — what changes, what it leaves alone
openclaw senpi update ./pkg --apply               # commit (needs the same proof deploy needs)
openclaw senpi update ./pkg --apply --code-only   # assert only scan.py changed; refuses if not

默认情况下，它只会制定计划；只有 --apply 才会提交更改。phase2.tiers 就是用户所说的 ratchet； 如果没有未平仓位，编辑并加上 --apply 就完成了更改。dsl_preset 的更改只对未来生效——只影响新开仓；每个未平仓位都会保留开仓时使用的预设快照（其他 exit: 字段，例如 order_type，会实时读取，也会影响未平仓位）。以下更改会被直接拒绝，不会产生任何变更：修改 strategy.wallet（这相当于新部署，旧钱包中的持仓将无人管理）、重命名或移动外部扫描器（状态同时按名称和持仓索引，插入或删除扫描器会移动其下方的所有外部扫描器；追加到末尾不会移动任何扫描器，因此允许），或在名称不变的情况下更改 action_type。--apply 还要求证明文件通过验证，且涵盖要应用的配方，因此请将其指向程序包目录：仅以纯文本形式提供的配方没有可供验证的对象，会被拒绝。退出码 2 表示运行时从未被触碰；退出码 1 表示已尝试应用，但运行时可能已不再是原来的状态——重试前请先阅读提示信息。

已保存不等于已应用。 不带 --apply 时，update 不会更改任何内容，只有输出的第一行会说明这一点——Dry run for <runtime_id> — nothing has been applied.——因此绝不要将 openclaw senpi 的输出通过管道传给 tail 或 head。扫描器启动时只会导入一次 scan.py，因此运行中的策略会继续使用旧代码，直到 --apply 重启其扫描器（崩溃或网关重启也会加载修改，但不会发出通知）。senpi validate 检查的是磁盘上的副本，而不是正在运行的副本；对已在运行的策略重新执行 deploy 不会应用任何更改。只有当应用操作以退出码 0 结束，且第一行显示 Updated <runtime_id>.，并且没有警告外部扫描器未运行的 WARNING，同时运行中的策略也显示出更改时，编辑才算真正生效：

openclaw senpi events -r <runtime_id> --name runtime.updated   # an entry for this apply (code-only edits too)
openclaw senpi update ./pkg --id <runtime_id>                  # read-only: a recipe edit that landed plans "The recipe is unchanged."

在这两处都看到更改之前，请告知用户该编辑已保存，但尚未应用。tick 会保留什么、丢弃什么：references/scan-contract.md。

除了 validate、deploy/deploy status、update 和 runtime list/delete，CLI 还提供运行时的实时状态——senpi dsl positions|inspect|closes（退出引擎）、senpi action list|inspect|history|decisions（决策层）、senpi risk（我是否可以交易，为什么不可以）、senpi audit（包含 AI 推理过程的后端交易记录）、senpi scanner（每个扫描器的健康状况、运行状态，以及针对运行但没有任何产出的扫描器显示的 (no signals yet) 标记）、 senpi events/senpi explain <asset>（本地领域事件日志——交易叙述，以及某个资产串联起来的生命周期）、senpi status/senpi state（健康状态——默认安全关闭：未经 tick 验证的外部扫描器状态为 unknown，而非 healthy；非健康扫描器会单独列出，并显示重启次数和原因），以及 senpi guide …（Shell 内参考指南）。完整的命令列表及所有选项 → references/runtime-cli.md。 要确认未平仓仓位确实受到止损保护（没有 DSL 的仓位不会出现在 dsl positions 的结果中，因此很容易被忽略）→ 查看判定流程：references/dsl-protection-check.md。

参考文档

阅读此文档	用途
references/runtime-concepts.md	端到端了解运行时的行为：运行时流水线、position_tracker 以及两阶段 DSL 退出引擎
references/runtime-yaml.md	runtime.yaml 架构——每个部分、external_scanner 字段和风险防护措施
references/scan-contract.md	深入了解作者约定：scan(inputs, ctx)、ctx 接口、信号结构和 scoring.py
references/runtime-cli.md	完整的 openclaw senpi … 命令集——validate（部署前检查：标志、深度、退出代码及其记录的证明）、deploy、runtime、dsl、action、status/state、skills、guide
references/dsl-protection-check.md	验证未平仓仓位是否受到 DSL 保护——PROTECTED / UNPROTECTED / STOP-NOT-ON-VENUE 判定，以及未平仓与跟踪仓位的核对

软件包命名（至关重要）

运行时软件包是 @senpi-ai/runtime（带 -ai）——用户在其主机上安装的软件包。 务必保留 -ai。