SkySpark 集成

两个集成界面

服务器与 SkySpark 通过两种方式进行通信：

1. 文件系统 — 读取 SkySpark 主目录下的 config/ 来枚举项目并提取用户定义的函数，无需实例运行。
2. HTTP + Haystack — 对运行中的实例执行查询、评估表达式和提交函数。

文件系统发现在服务器启动时运行。HTTP 调用在客户端调用 queryHaystack、executeAxonCode 或 commitAxonFunction 时按需进行。

自动发现

在配置中设置 skyspark.autoDiscover: true 时，服务器在启动时遍历 SkySpark 主目录：

/path/to/skyspark/
├── config/            ← enumerated
│   ├── project-a/
│   ├── project-b/
│   └── sensorRead/
└── ...

对于找到的每个项目文件夹，服务器：

1. 读取项目的元数据文件以确认它是有效的 Haystack 项目。
2. 获取用户定义函数列表（func 记录）。
3. 将这些函数索引到本地 Axon 索引中，标记为 project:<name>。

结果：searchAxonExamples 可以从真实的 SkySpark 项目中显示函数，同时包括静态库示例。

函数同步

发现仅枚举。同步获取实际的函数源代码。

启用 autoSyncFunctions: true 时，同步在启动时自动运行。否则客户端可以通过 discoverProjectFunctions 触发它：

{
  "tool": "discoverProjectFunctions",
  "arguments": { "project": "sensorRead" }
}

并发性

syncConcurrency（默认 10）控制有多少函数并行获取。对于局域网上的快速实例，提高该值；对于慢速或速率限制的实例，降低该值。

版本控制

启用 functionVersioning: true 和 maxVersions: 4（默认值）时，每次 commitAxonFunction 调用：

1. 从 SkySpark 读取当前版本。
2. 写入新版本。
3. 将前一个版本存档到 .data/versions/<project>/<function>-v<N>.axon。
4. 清理早于 maxVersions 的修订。

恢复旧版本目前需要手动将文件复制回 SkySpark — 还没有 restoreFunctionVersion 工具。

主项目概念

执行和提交工具需要选择单个项目。主项目就是该选择：

"primaryProject": {
  "instance": "localhost8080",
  "project":  "sensorRead"
}

客户端可以在运行时切换它：

{ "tool": "setPrimaryProject", "arguments": { "instance": "localhost8080", "project": "plantRoom" } }

后续的 executeAxonCode 和 commitAxonFunction 调用将针对 plantRoom，直到下次切换。

运行查询

queryHaystack 接受原始 Haystack 查询字符串并将结果网格作为 JSON 返回：

{
  "tool": "queryHaystack",
  "arguments": {
    "query": "read(site)"
  }
}

结果：

{
  "meta": { "ver": "3.0" },
  "cols": [ { "name": "id" }, { "name": "dis" }, { "name": "site" } ],
  "rows": [
    { "id": "@p:sensorRead:r:1a2b", "dis": "Main Campus", "site": true }
  ]
}

查询使用主项目的身份验证上下文执行。

备用凭证

如果自动发现失败（路径错误、SkySpark 未安装在同一主机上等），服务器会回退到明确的连接块：

"fallback": {
  "host":     "skyspark.example.com",
  "port":     443,
  "project":  "demo",
  "username": "readonly",
  "password": "<use-env-var>",
  "protocol": "https"
}

对于密码，优先使用环境变量替换（SKYSPARK_PASSWORD），而不是将其提交到配置文件。

排查连接问题

• SKYSPARK_UNREACHABLE — 实例未在配置的主机/端口接受连接。检查 curl http://<host>:<port>/about。
• SKYSPARK_AUTH_FAILED — 凭证错误，或用户缺少目标项目的权限。
• PROJECT_NOT_FOUND — 主项目在实例上不存在。运行 listSkySparkProjects 以查看可用的项目。