openscript

用途

OpenScript 用于为 OpenAlgo 编写研究指标（study）或交易策略（strategy）。写好的 .oscript 文件安装到 strategies/openscript/ 后，交易者可以在编辑器中打开它，在 /trading 页面回测，并部署到某个标的上运行。

需要注意，仓库中有三样东西都被称作“指标”，但彼此并无关系：

OpenScript（本技能）是一种编译为程序的语言，文件扩展名为 .oscript，既能绘图也能下单。
chart-indicator 是 openalgo-charts 上的纯 JavaScript 描述符，只能绘图，由浏览器在运行时加载。
openalgo.ta 是 Python 库，供 Python 策略宿主、扫描器和回测使用。

如果请求中提到了 .oscript 文件、OpenScript 编辑器，或要部署到 /trading 的策略，那么指的就是本技能。

主要能力与规则

一条核心规则：不要手工写入 strategies/openscript/ 目录。该目录中每个脚本有两个文件，<name>.oscript 与 <name>.oscript.program.json，运行器只读取程序文件，从不打开源码。这会导致两种静默失败：

有源码但没有程序，等于一个无法运行的策略。它能被保存、能在编辑器中打开、能出现在列表里，但启动会在一分钟后被拒绝，且记录在无人阅读的日志中。
程序由不同的文本构建则更糟——运行的脚本与交易者阅读的脚本不是同一个。

因此两个文件必须来自同一次编译，同时写入或都不写入：

# 1. 草稿写到临时文件（绝不写入 openscript 目录）
#    例如 <scratchpad>/my_strategy.oscript

# 2. 按浏览器的方式编译
node .claude/skills/openscript/validate.mjs <scratch>/my_strategy.oscript

# 3. 仅在 PASSED 时安装两个文件
node .claude/skills/openscript/validate.mjs <scratch>/my_strategy.oscript --install

#    以不同名称安装：
node .claude/skills/openscript/validate.mjs <scratch>/draft.oscript --install --as mean-reversion.oscript

--install 仅在零错误时写入两个文件，否则以退出码 1 结束。写入前会检查编译程序记录的哈希与即将写入它旁边的源码是否匹配，这与平台自身的保存路径所做检查相同。若配对不匹配则拒绝写入，不会有任何文件被写入，因此失败不会只应用一半。

“通过”的含义

编译器接受了文本：名称可解析、类型一致、调用存在、限制满足。但这里不会运行任何一根 K 线。它不代表策略是好策略、数值正确，或能赚钱。reference/strategies.md 结尾列出了从编译到盈利之间的四个步骤，这些步骤不是可选的。

编写前应阅读的资料

reference/library.md：全部 350 个名称，含各自回答的问题与预热（warmup）。由已安装的编译器生成。
reference/pitfalls.md：会出什么问题，以及你实际会看到的诊断代码。页面上的每个代码都经过编译器验证。
reference/strategies.md：策略可取的各种形态，以及哪个示例回答哪类需求。
examples/*.oscript：六个可编译的完整示例文件，推理写在注释中。

请查阅名称而不是凭记忆回想。350 个名称超出任何人的记忆，危险的失败不是取了一个不存在的名称，而是取了一个计算别的东西的邻近名称——它能编译，但报告的策略并非本意。

最耗时的三点

350 个名称中有 95 个在本版本中属于“已规划但未实现”。库会描述名称，无论某版本是否实现它，因此名称能解析并不保证能编译。取用这类名称会得到 OS2020。它们已在 reference/library.md 中标注。order.qtyForRisk 是最容易误取的，因为它读起来正好像是你想要的调用；整个族系都处于规划中，包括全部 leg.* 和全部 book.*。
buy 和 sell 是按数量移动持仓，而不是把持仓设为某一方向。sell(qty = lots) 在已做多一手时会让持仓变为持平，而不是做空。没有任何东西会拒绝它。这是 reference/pitfalls.md 的第一条，也是 examples/stop-and-reverse.oscript 存在的原因。
缺失值不是零。每个有状态调用都有预热期，对缺失值做算术得到的是缺失而非零，这正是信号不会在其均值存在之前触发的原因。用 orElse 或 otherwise 在预热期替换为某个数字的脚本，在最初一段 K 线上会悄悄出错，却看起来能正常工作。

保持技能可信

有两个脚本，都必须通过，且都由 CI 任务运行：

node .claude/skills/openscript/generate-reference.mjs   # 重写 reference/library.md
node .claude/skills/openscript/coverage.mjs             # 必须输出 COVERAGE COMPLETE
node .claude/skills/openscript/check-pitfalls.mjs       # 必须输出 PITFALLS VERIFIED

coverage.mjs 双向校验参考与编译器（编译器有而页面缺的名称会失败，页面教了而编译器没有的名称也会失败），检查每个规划中的名称都被标注，并检查作者需要的每种形态都在可编译的示例中得到演示，类型读取自编译后的程序而非文本。

check-pitfalls.mjs 会编译 reference/pitfalls.md 中每一条目的两半：错误写法必须仍然产生所述代码，提供的修复必须仍然干净通过。它还检查页面与脚本命名同一组代码，使二者不会单独漂移。该页面初稿中有两条断言是错的，正是这个脚本发现的。

升级 openalgo-script 时需在同一次变更中更新本技能，方式类似图表升级。先运行生成器，再运行两项检查，然后手工更新说明文字：生成器负责名称表，没有任何东西会生成教学内容。