跳到主要内容

SteamHarness 指南

SteamHarness 是开发、运行和分发 Agent 项目的平台。它由 Core SDK、CLI、Studio 工作站、Server 与 Server Web 管理端组成；项目可以在本地开发，也可以上传到 Server，并发布到 Store。

三种项目类型​

类型形态适合入口
Workflow类型化的 TypeScript 工作流自动化、多步骤任务、工具编排入口函数 + 节点 / 执行器
Conversation对话型 Agent 项目对话助手、Agent 会话会话执行器
Kanban静态 HTML / CSS / JavaScript看板、可视化、人机协作index.html

Workflow​

Workflow 用节点和执行器描述一条可运行的任务链：输入、LLM 调用、工具、条件分支、循环和输出都由 Runtime API 声明。适合把一组需要类型约束和可复用步骤的操作串起来。

  • 典型场景：数据处理、内容生成、工具调用、多步骤自动化。
  • 从 Workflow 模型 和 Core API 开始。

Conversation​

Conversation 是面向对话的 Agent 项目，围绕会话轮次、工具调用和会话数据组织执行。它复用同一套 Core Runtime，但入口以消息和会话为单位。

  • 典型场景：对话助手、客服/运营助手、需要持续上下文的 Agent。
  • 从 KV 与会话 和 Core API 开始。

Kanban​

Kanban 是由 HTML、CSS、JavaScript、图片和字体组成的静态项目，以 index.html 为入口，不执行 Runtime API，也不需要执行器。页面可以通过受限 Bridge 读取项目 KV 和知识库。

  • 典型场景：看板、地图、仪表盘、需要嵌入对话或项目详情页的可视化界面。
  • 从 Kanban HTML 项目 开始。

项目在哪里运行​

SteamHarness 把“执行”和“管理”分开：

位置执行项目代码作用
Studio / 本地 CLI是本地运行、调试、查看执行轨迹
Server否保存源码、版本、成员、KV、知识库和项目文件
Server Web 管理端否在浏览器中管理项目、成员和数据
Store否浏览、下载和发布版本归档

Server 不安装项目依赖、不构建、也不加载上传的项目代码。Kanban 的预览是绑定项目、用户和版本的静态 iframe，不继承账号凭据，也不等于在 Server 上执行项目。

主要功能​

能力说明入口
Studio 工作站基于 VS Code OSS，打开和运行本地项目、查看执行轨迹、管理版本与账号使用 Studio
本地 CLI检查项目结构、运行项目、打开 Web 工作区本地 CLI
Server 与 Server Web管理项目源码、版本、成员、知识库、KV 和账号Server Web 管理端
Workspace CLI登录 Server、上传下载源码、发布和切换版本Workspace CLI
Store浏览、下载和发布项目版本Store 概览
系统 AI（增强版）共享模型、个人默认模型、供应方偏好、用量与订单系统 AI 指南
内置项目开发者小助手、Codex、Conversation、OpenCode、Pi 等开箱即用的项目发布日志

项目数据与配置​

项目数据的位置由 package.json 的 steamHarness.projectInfo.dataStorage 声明，运行时按声明拒绝越界访问：

模式允许位置说明
local仅本地CLI 可离线运行
server仅服务器需要登录并绑定同一个项目 UUID
both本地与服务器每次访问显式选择位置
  • KV / PersistentValue：通过 context.storage.local 或 context.storage.server 访问；两端数据独立。
  • 知识库与项目文件：由 Server 保存，Server Web 管理。
  • 项目配置：configuration.json 声明字段（字符串、数字、布尔、JSON、文件），实际值在 Studio、CLI Web 或 Server Web 的面板管理；敏感字段使用 secret: true。
  • 关联项目：projectInfo.relatedProjects 声明 alias、目标项目 UUID 和读写授权；双方都声明后才生效。

更改 dataStorage 只改变以后允许的位置，不会迁移已有数据。详见项目数据存储、项目配置、KV 与会话和文件输入。

账号、权限与协作​

Server 使用账号和固定的项目角色管理权限：

角色能做什么
guest查看项目、已发布版本、KV、知识库、文件和预览；下载已发布源码并本地运行
developer编辑草稿、上传和发布版本，修改服务器 KV、知识库和项目文件
maintainer管理项目信息、公开状态、官方配置，以及访客和开发者
owner分配全部角色、管理所有者、删除项目和转移归属

项目可以放在组里，组支持多级子组，有效角色取项目直接角色和各级组角色的最高值。公开项目向所有登录用户提供访客权限；私有项目可以通过已发布版本的分享链接申请访问。详见项目管理。

AI 能力​

开源版的项目自己管理模型：在项目中声明 LLM Provider 和 API Key，节点运行时读取配置；Server 不保存或代理第三方模型凭据。详见 LLM Provider。

增强版在此基础上提供系统 AI：平台统一维护模型目录、凭据和计费，用户可以选择默认模型、供应方偏好、订阅/余额，并查看用量与订单；Studio 小助手登录项目后直接使用系统 AI。详见增强版比开源版多了什么：系统 AI 配置。

开发流程​

  1. 创建项目：在 Studio 中点击「新建项目」，选择 Workflow、Conversation 或 Kanban 类型和模板；也可以手动创建目录。
  2. 声明项目：在根 package.json 写入 steamHarness.projectType（workflow、conversation 或 kanban），以及可选的 projectInfo（名称、展示平台、数据存储、关联项目）。
  3. 编写入口：Workflow / Conversation 使用 Core Runtime API 声明入口和执行器；Kanban 直接编写 index.html 及其静态资源。
  4. 本地运行：在 Studio 中打开项目并点击运行，或在终端执行 steamharness structure .、steamharness run .、steamharness web .。
  5. 上传到 Server：使用 Workspace CLI 登录、打包源码并发布版本，然后在 Server Web 管理端管理项目、成员和数据。
  6. 发布到 Store（可选）：从 Server 上已有的版本创建 Store 条目，提交审核并上架。

项目结构​

一个最小的 Workflow / Conversation 项目通常包含：

my-project/
├── package.json   # name、steamHarness.projectType、projectInfo、Core/CLI 版本
├── index.ts       # 入口与执行器
└── ...

Kanban 项目只需要：

my-board/
├── package.json
└── index.html

package.json 是项目信息的唯一权威来源。steamHarness.projectType 决定项目类型；steamHarness.projectInfo 保存本地化名称、展示平台、数据存储位置和关联项目。Workflow / Conversation 需要在 devDependencies 中精确记录 Core 与 CLI 版本，Kanban 只把 Core 版本作为静态包元数据校验。

内置项目​

Studio 自带一组可以直接打开或创建的项目：

项目作用
开发者小助手（Project Assistant）在 Studio 中协助理解项目、生成代码和执行开发任务
Studio 控制（Studio Control）为 Agent 提供受控的 Studio 操作能力
Studio 分析（Studio Analysis）汇总本地项目与运行状态
Codex / Conversation / OpenCode / Pi开箱即用的 Agent / 对话项目

内置项目同样遵循项目类型、版本和权限规则。各项目的版本记录见发布日志。

版本、测试与部署​

  • 版本：Core、CLI、Server、Server Web 和内置项目各自发版；项目在 devDependencies 中固定 Core 与 CLI 版本。兼容性与历史见发布日志和版本兼容性。
  • 迁移：从 Core 0.1 升级到 0.2 见迁移指南。
  • 测试：steamharness structure . 检查项目结构；项目自己的测试和仓库门禁见自动化测试。
  • 部署：Server、Server Web 和 Store 的部署见部署与发布。

选择你的下一步​