星火编码代理 zendev-lab/ulota

Spark

本地优先的编码智能体运行时，支持持久执行、可验证工作流和多工作区协同。

Spark 让智能体的工作不再局限于单个终端进程。本地守护进程负责持久会话、调用、后台执行、重试和恢复。Hub 协调已注册的工作区和委派，但不接管它们的仓库或执行状态。本地 Web 工作台、Hub Web UI、频道和 ACP 都是这些归属方的接口，而不是相互竞争的运行时。

当编码任务需要继续推进、请求决策、产出可追溯的产物、在前端重启后存活，或在终端与浏览器监管之间切换时，请使用 Spark。

快速开始

Spark 需要 Node.js >=24 和 npm。推荐直接使用经过验证的 curl 引导脚本作为原生入口；它会安装精确受管的 npm 载荷，并保留原子升级和回滚：

curl -fsSL https://github.com/zendev-lab/spark/releases/latest/download/install.sh | sh
spark doctor
spark

当包管理器应当持有命令时，仍支持全局 npm 安装：

npm install --global @zendev-lab/spark

不启动浏览器工作台，直接运行前台任务：

spark run "Summarize this repository and identify its validation command."

当主机只需要该进程时，可独立安装可执行应用：

npm install --global @zendev-lab/spark-hub
spark-hub

完整的 @zendev-lab/spark 包会安装匹配的守护进程、Hub 和 Web 配套组件，因此其调度器也可以使用：

spark hub

Spark 会按需启动或连接本地守护进程。需要直接检查执行状态时，请使用 spark-daemon status --json。

有关服务商配置、包管理器持有的安装、后台运行、会话和远程操作，请参阅[入门指南][getting-started]。

Spark 提供什么

- 持久执行 —— 会话、调用、后台工作、重试和恢复归属于守护进程，而不是前端进程。
- 受控自主 —— 一次性 /plan、/execute 和 /fleet 指令覆盖常规工作；Goal、Loop、Repro 和 Workflow 增加受监督的长时间运行行为。
- 人工决策 —— 问题和审批始终附着在请求它们的会话和工作上。
- 可追溯结果 —— 任务将工作连接到 issue、git_change 和 document 产物，验证与面向用户的结果保持分离。
- 多种接口 —— 在同一执行模型上使用本地 Web 工作台、Hub Web UI、消息频道、无头 JSON 命令或无状态 ACP 适配器。
- 本地优先边界 —— 每个守护进程保留本地执行和副作用；Hub 协调携带路由状态、审计数据和有界回执。

架构

Spark 将调度、呈现、协调和执行分离：

spark CLI / spark web ─────────► 本地 spark-daemon ───► 工作区 + 服务商 channels / spark-acp ────────────────────────┘

browser / Hub Web ─────────────► spark-hub ◄────────── 已注册的 spark-daemon │ └── 内嵌 Web UI + 全局控制面

| 组件 | 职责 | 不负责 |
| spark | 向配套可执行文件稳定分发命令 | 产品状态 |
| spark-web | 本地交互展示与会话挂接 | 持久业务状态 |
| spark-daemon | 会话、调用、通道、执行、重试与恢复 | 跨工作区协调 |
| spark-hub | 认证、daemon 网关、工作区注册表、委派、审计与内嵌管理 UI | 目标执行、仓库或内部证据 |
| spark-acp | 无状态协议转换 | 会话或调用 |

详细的归属关系与命令语法见 .agents/notes/contracts/command-planes.md。包依赖方向与状态写入方由 architecture/packages.json 和包架构规范定义。

典型工作流

1. 在 spark web 中或用 spark run 描述预期结果。
2. 用 /plan 把意图转成持久、可检查的任务。
3. 普通执行用 /execute，隔离的并行前沿用 /fleet；工作需要自主推进时，再选用 Goal、Loop、Repro 或 Workflow。
4. 在所属会话或 Hub Inbox 中回答问题、处理审批。
5. 交付前检查产物、变更、任务与验证结果。
6. 在本地继续，或通过 Hub 把有边界的工作委派给另一个工作区。

[用户文档][docs]讲解这些工作流，无需了解内部包或存储。

接口

| 接口 | 最适合 |
| spark / spark web | 交互式本地编码会话 |
| spark run / spark bg | 前台脚本与后台工作 |
| spark-daemon | 执行检查与运维控制 |
| spark-hub | 全局浏览器管理、协调与委派 |
| spark-acp | 基于规范 daemon 会话的 ACP 兼容客户端 |

原生根命令行接受 spark daemon、spark hub、spark web、spark acp 和 spark mcp 作为便捷形式，并执行对应的 spark-* 配套程序。完整元包会安装所有配套程序；真正的解析器、诊断、更新器与路由仍留在 @zendev-lab/spark-cli。运行 spark --help 查看当前命令表。完整命令参考维护在[用户文档][cli-reference]中。

文档

- [用户文档][docs] —— 安装、工作流、接口与故障排查。
- EVOLUTION.md — 项目意图、目标、非目标，以及待解决的问题。
- .agents/notes — 按需查阅的内部约定、决策，以及维护者操作手册。
- .agents/AGENTS.md — 智能体知识的存放位置，以及渐进式披露规则。
- CONTRIBUTING.md — 源码环境搭建、仓库工作流、校验、文档归属，以及 pull request。
- AGENTS.md — 编码智能体在整个仓库范围内必须遵守的约束。

分发与状态

Spark 从同一个私有 monorepo 发布版本同步的产品分发包，以及各平台专用的原生命令行载荷：

- @zendev-lab/spark 是完整安装元包。它锁定版本匹配的命令行、daemon、Hub 和 web app 包，并通过一个轻量转发启动器让 spark 始终可用，但自身不含解析器或应用实现。
- @zendev-lab/spark-cli 负责原生 spark 解析器、诊断、更新器、伴随路由、ACP/MCP 适配器，以及各平台专用的可选载荷。
- @zendev-lab/spark-daemon、@zendev-lab/spark-hub 和 @zendev-lab/spark-web 是可独立安装的可执行应用。

这种拆分是部署与信任边界，不是源码归属的拆分。私有应用组装根，以及内部的适配器/能力工作区，仍是未公开的源码边界。各产品 tarball 共用同一个发布版本和协议兼容约定。npm 会针对当前平台，只解析出一个受支持的 macOS/Linux 原生命令行载荷；而各应用包可以独立安装和部署。

GitHub Releases 还会发布经过校验的原生 bootstrap 归档、native-release-manifest.json、SHA256SUMS、来源证明，以及锁定精确版本的 install.sh。bootstrap 不含 Node 运行时：它先校验 Node 24 和 npm，再把产品载荷的事务交给原生更新器处理。

Spark 正在积极开发中。受管理的根目录安装提供明确的更新与回滚行为；源码检出永远不会自我修改。直接安装的应用由各自的包管理器或容器部署来更新。

Spark 采用 MIT 协议。源自源码的组件声明记录在 THIRD_PARTY_NOTICES.md。

[cli-reference]: https://spark-docs.2742392377.workers.dev/reference/cli/
[docs]: https://spark-docs.2742392377.workers.dev/
[getting-started]: https://spark-docs.2742392377.workers.dev/getting-started/