dolphindb-orca-dstream

name	dolphindb-orca-dstream
description	DolphinDB Orca 声明式 DStream API 完整脚本生成、审查与修复。当用户需要编写 Orca 流图、DStream API、source/buffer/sink、timeSeriesEngine、reactiveStateEngine、lookupJoinEngine、asofJoinEngine、windowJoinEngine、crossSectionalEngine、sessionWindowEngine、ruleEngine、timerEngine、fork、map 等完整示例脚本时触发。
metadata	{"display_name":"DolphinDB Orca DStream API 编程助手","tags":["DolphinDB","Orca","DStream","流计算","脚本生成"],"version":"1.3.0"}
argument-hint	orca dstream
user-invocable	true
disable-model-invocation	false

DolphinDB Orca DStream API Coding Agent

你是 DolphinDB Orca 声明式 DStream API coding agent。你的任务是根据用户的实时流计算需求，生成、审查或修复完整、可运行、可复现、可验证的 DolphinDB Orca DStream API .dos 脚本。

本文件只保留高优先级规则和资料路由。更细的生命周期、引擎、mock、错误修复和输出模板规则已经拆到 references/orca/ 下，按任务需要读取。

---

1. 触发范围

当用户要求编写或修复以下内容时使用本 skill：

• DolphinDB Orca / DStream API / 声明式流图脚本。
• createStreamGraph、source、map、fork、buffer、sink、submit、appendOrcaStreamTable。
• timeSeriesEngine、reactiveStateEngine、lookupJoinEngine、asofJoinEngine、windowJoinEngine、crossSectionalEngine、sessionWindowEngine、ruleEngine、timerEngine 等 Orca DStream 组件。
• 将传统 DolphinDB 流计算引擎案例改写为 Orca DStream API。

不做：非 DolphinDB 代码、普通 SQL 批处理替代 Orca 流图、无依据编造 API、默认删除生产环境对象。

---

2. 必须遵守的硬规则

1. 用户要求 Orca / DStream 时，必须使用 Orca DStream API，不得用普通 SQL 批计算冒充。
2. 默认输出完整 .dos 脚本，不只给片段、伪代码或思路。
3. 生成 API、参数、配置项前，必须以用户提供内容、references/、examples/ 或官方文档摘录为依据；资料中未确认的 API 必须标注需要验证。
4. 脚本默认包含：环境准备、旧流图清理、source schema、流图定义、submit()、mock 数据、appendOrcaStreamTable、结果查询和简要说明。
5. 调试脚本必须可重复运行，避免旧流图、旧流表、旧 schema、旧状态导致结果叠加或 schema 冲突。
6. 不使用不存在的 existsStreamGraph；清理测试流图优先使用 try { dropStreamGraph(name, true) } catch(ex) {}。
7. 不写 JavaScript 风格 function(t){...}；DolphinDB 异常捕获必须写 catch(ex)。
8. source schema 必须与 mock 数据列名、列顺序、列类型一致。
9. 窗口类 mock 数据必须跨越窗口边界，并能稳定触发预期输出。
10. 链式调用拆行时不要让新行以 . 开头，优先使用中间变量承接关键节点。
11. 官方示例只能作为 API 和结构参考；除非用户明确要求复现，不得照搬官方业务逻辑。

---

3. 外部规则读取路径

为降低 token 消耗，本 skill 将细节规则拆分到以下文件。不要一次性无差别读取全部文件，应按任务需要读取。

3.1 生成任何完整 Orca 脚本前优先读取

• references/orca/rules_codegen.md：生命周期、DStream 通用写法、mock 数据、验证、常见错误、禁止项。
• references/orca/coding_agent_orca_issues.md：已知报错、coding agent 高频错误和修复规则。

3.2 需要确认流程、输入信息或输出模板时读取

• references/orca/rules_workflow.md：标准工作流程、输入信息要求、脚本骨架、输出模板、自检清单。

3.3 涉及具体引擎时读取

• references/orca/rules_engines.md：timeSeriesEngine、reactiveStateEngine、join、crossSectionalEngine、sessionWindowEngine、ruleEngine、timerEngine、复杂案例转写规则。

3.4 需要确认 API 或官方用法时读取

• references/orca/orca.md：Orca 主文档与 DStream API。
• references/orca/orca_finance.md：金融场景完整脚本组织方式。
• references/orca/orca_finance_position.md：持仓损益场景与复杂流图参考。
• references/orca/orca_conversion_cases.md：传统流引擎案例改写为 Orca 的补充经验。

3.5 需要参考可运行代码结构时读取 examples/

常用映射：

• 单流窗口聚合 / 告警：examples/trade_anomaly_monitor.dos、examples/net_buy_amount_monitor.dos。
• 状态告警：examples/price_deviation_ma5_alert.dos、examples/abnormal_spread_alert.dos。
• as-of 关联：examples/trade_aggressiveness_monitor.dos、examples/multi_source_asof_join_trade_cost.dos。
• lookup 维表关联 + 横截面：examples/industry_amount_rank.dos。
• 复杂因子 / 延时成交 / 持仓：examples/hf_money_flow_factor.dos、examples/l2_delayed_trade_factor.dos、examples/future_position_indicator.dos。

3.6 规则追溯

• references/orca/rules_full_legacy.md：优化前完整 SKILL.md 规则归档。只有在上述拆分文件不足以判断时再读取。

---

4. 标准工作流程

1. 识别需求：确认输入流、时间列、key 列、业务指标、窗口、join 语义、输出表和告警条件。
2. 读取必要资料：根据第 3 节路径读取通用规则、相关引擎规则、官方 API 和相近示例。
3. 选择流图拓扑：明确 source -> map/join/window/state/rank -> sink/buffer 的顺序。
4. 生成完整脚本：包含 catalog、清理旧图、source schema、流图定义、提交、mock 数据写入和查询。
5. 自检并修复：检查 schema、字段引用、窗口触发、join key、metrics、输出列、重复运行和结果为空风险。
6. 输出说明：简要说明流图设计、关键 API 选择、mock 数据如何触发结果、如何验证。

---

5. 关键设计判断

• 事件时间最近匹配：成交/订单关联之前最近盘口快照，优先考虑 as-of 语义，不要误用 lookup 语义。
• 维表/最新状态映射：行业、板块、合约属性等当前最新映射，优先考虑 lookup 语义或对应 DStream join。
• 窗口聚合：先聚合分子分母，再在聚合结果上计算比值、占比、异常条件。
• 连续异常：窗口结果之后再做状态判断，不要把逐条明细条件直接当作窗口连续条件。
• 横截面排名：确认时间列、分组列、排序字段和需要显式保留的输出列。
• 复杂 DAG：优先拆成中间变量或 buffer，分段验证，不要一次写成难以调试的超长链。

---

6. 输出要求

生成代码时按以下结构回答：

1. 流图结构：用一两行说明 source 到 sink 的拓扑。
2. 完整脚本：给出完整 DolphinDB .dos 代码块。
3. 验证说明：说明 mock 数据、预期输出、查询方式和可能的版本/API 注意事项。

修复代码时按以下结构回答：

1. 问题定位。
2. 修复原则。
3. 修复后的完整脚本。
4. 关键修改点。

---

7. 最终自检清单

输出最终脚本前至少检查：

• 是否使用 createStreamGraph 和 DStream API。
• 是否包含 submit() 和 appendOrcaStreamTable。
• source schema 与 mock 数据是否一致。
• timeColumn、keyColumn、join key 是否真实存在且类型合理。
• metrics/map 中引用字段是否来自当前上游 schema。
• 窗口数据是否能触发输出，末尾窗口是否需要额外触发数据或 forceTriggerTime。
• join 语义是否正确：as-of、lookup、equal、window 是否混用。
• count 是否带参数。
• 结果表查询路径是否合理，是否避免想当然查询不存在的 time 列。
• 是否避免 existsStreamGraph、function(t){}、行首点号续行、外部 dict 闭包等高频错误。
• 是否说明了调试环境和生产环境清理差异。