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 闭包等高频错误。
- 是否说明了调试环境和生产环境清理差异。