execute-dlang

name	execute-dlang
description	专注于 DolphinDB 脚本执行的技能。当用户提到“执行 DolphinDB 脚本”、“运行 .dos 文件”或“在 Python 中执行 DDB 代码”时，触发此技能。提供一个基于 Python 的执行环境，支持持久化会话（Persistent Session），让用户能够分步骤执行代码并保留变量定义。
license	MIT
metadata	{"author":"ddb-user","version":"3.0.0"}

DolphinDB 执行器 (Script Analysis & Persistence)

本技能包提供了一套基于 Python 的 DolphinDB 执行环境，你可以直接执行dolphindb脚本文件（.dos）或代码片段，或者持久化会话，让你在多次执行中保留变量和函数定义。

🚀 极简执行指南 (AI Agent 必读)

作为 AI Agent，当你需要执行 DolphinDB 代码时，首选使用命令行传参的直连模式，这样最稳定且不需要依赖任何配置文件。

1. 准备工作

确保系统已安装 uv (如果没有，请先执行 pip install uv)。 本技能包的脚本自带依赖声明，uv run 会自动处理包下载。

2. 快速执行代码 (推荐)

使用 execute.py 并通过参数传入连接信息。

-c/--code 现在会先把代码片段写入临时 .dos 文件，再按文件模式执行。这样可以减少 DolphinDB 侧因为内联片段过长、含特殊字符而出现的执行问题。

执行代码片段:

# 先设置环境变量，或把下面占位符替换成你的实际连接信息
uv run ./skills/execute-dlang/scripts/ddb_runner/execute.py -c "1+1" --host <DDB_HOST> --port <DDB_PORT> --user <DDB_USER> --password <DDB_PASSWORD>

从 stdin 执行代码片段（PowerShell 更稳妥）:

@"
pattern = "%check%"
select name from objs(true) where shared = true and lower(name) like pattern
"@ | uv run ./skills/execute-dlang/scripts/ddb_runner/execute.py --stdin --host <DDB_HOST> --port <DDB_PORT> --user <DDB_USER> --password <DDB_PASSWORD>

执行 .dos 文件:

uv run ./skills/execute-dlang/scripts/ddb_runner/execute.py path/to/your_script.dos --host <DDB_HOST> --port <DDB_PORT> --user <DDB_USER> --password <DDB_PASSWORD>

---

🔄 高级用法：持久化会话 (Server 模式)

如果你需要分步执行代码，并且保留上下文变量（例如第一步定义了函数，第二步要调用），你需要使用 Server 模式。

步骤 1: 启动后台 Server

在终端中启动 Server（它会保持运行）：

uv run ./skills/execute-dlang/scripts/ddb_runner/server.py --host <DDB_HOST> --port <DDB_PORT> --user <DDB_USER> --password <DDB_PASSWORD>

(看到 [Info] Server listening on 127.0.0.1:65432 表示成功)

步骤 2: 使用 --use-server 发送代码

# 定义变量
uv run ./skills/execute-dlang/scripts/ddb_runner/execute.py -c "x = 1..100; y = x * 2;" --use-server

# 调用变量
uv run .github/skills/execute-dlang/scripts/ddb_runner/execute.py -c "avg(y)" --use-server

---

⚠️ 常见问题与 AI 经验总结 (Pitfalls)

在使用 AI 辅助编程或通过脚本自动化执行时，我们总结了以下高频错误模式，请务必注意：

1. 脚本执行结果为空 (Empty Return)

• 现象: 运行 execute.py 后显示 Success 但没有内容输出，或者返回 None。
• 原因:
  1. DolphinDB 脚本的最后一行是赋值语句（如 x = 1），或 void 函数调用，默认不返回结果。
  2. print() 函数在 server 端执行，输出可能流向了 server 的 log (dolphindb.log)，而不是通过 API 返回给 Python client。
• 解决方案:
  • 显式返回: 在脚本最后一行单独写上通过想要查看的变量名（例如最后一行写 resultTable）。
  • 尽量少用 print: 除非你在调试服务端日志，否则尽量让脚本返回对象，由 Python 端打印。

2. 找不到脚本路径

• 现象: 提示 File not found。
• 解决方案: 脚本现在会自动尝试相对于当前工作目录解析路径。如果仍然找不到，请使用绝对路径或相对于工作区根目录的完整路径。

2.1 PowerShell 引号陷阱（新增）

• 现象: -c 执行复杂代码时，字符串中的引号被 PowerShell 吞掉，DolphinDB 报 Cannot recognize token。
• 解决方案:
• 优先使用 .dos 文件执行：execute.py your_script.dos。
• 若必须动态拼代码，优先使用 --stdin，它会把原始输入写入临时 .dos 后执行。
• -c 现在内部也会落临时 .dos，但它仍然无法修复 Python 进程启动前 已被 PowerShell 改写的参数。
• 对包含 URL、DFS 路径、数组字面量、%...% 模式串的代码，不要直接依赖 -c 的 shell 引号。

3. 长连接断开与变量丢失

• 现象: 之前定义的 function 或 table 找不到了。
• 原因: server.py 可能因为网络波动或报错重启了。
• 解决方案: 如果发现变量丢失，请检查 server.py终端是否有错误堆栈。重新运行初始化脚本。

3. Socket 通信限制 (Buffer Size)

• 现象: 执行非常长（几千行）的脚本时，报错或被截断。
• 原因: 目前 server.py 的接收缓冲区逻辑较为简单 (4096 bytes chunk)，对于极其巨大的脚本可能存在粘包或截断风险。
• 解决方案:
  • 尽量不要一次性发送 MB 级别的 SQL 脚本。
  • 将大任务拆分为多个 .dos 文件，使用 include 或分次执行。

4. 数据类型陷阱与格式化

• 现象: 也就是 Python 接收到的数据格式看起来很奇怪（如 Dictionary 变成了 String）。
• 优化: 现在的脚本已经内置了 pandas 依赖，当 DolphinDB 返回 Table 时，会自动使用 pandas.DataFrame.to_string(index=False) 进行格式化输出，使其在终端中更易读。对于 List 和 Dict，也会使用 pprint 进行美化。
• 建议: 本工具定位为执行与验证。如需进行大规模数据拉取与分析（如 Pandas 处理），请直接使用 Python SDK (import dolphindb) 编写专门的数据处理脚本，而不是依赖本工具的 shell 输出。

📂 文件清单

• scripts/ddb_runner/server.py: 持久化会话服务器（核心）。
• scripts/ddb_runner/execute.py: 客户端命令行入口。
• scripts/ddb_runner/.env: 配置文件（需自行创建/修改）。