Server 项目管理

项目详情页围绕已发布的 Workflow、Conversation 和 Kanban 项目工作。你可以查看运行或预览状态、管理访问权限、发布版本、配置环境变量、开放 Embed 和 Webhook，并排查执行日志。

常用任务

检查项目是否可运行

查看 latest 版本、运行入口、运行统计、Webhook 和 Embed 状态。

查看概览 →配置成员和运行权限

添加项目成员、生成邀请、调整角色，并按需加入运行禁止名单。

管理成员 →配置远程运行参数

为 server run、external API、Embed 和 Webhook 设置项目级环境变量。

管理环境变量 →开放外部入口

生成公开 Embed 链接，或让外部系统通过 Webhook 触发 workflow。

配置 Embed 和 Webhook →

项目概览

概览页展示项目标识、当前语言名称、整体 latest、最新 Server 可运行版本、最近发布、运行入口和运行统计。统计信息由服务端聚合，包含状态分布、版本吞吐、趋势、耗时、来源、运行用户和 token 用量。

概览页适合快速判断：

• 是否存在在线且具备完整兼容 runtime 的 Server 可运行版本。
• Webhook 或 Embed 是否启用。
• 是否存在运行中或等待中的任务。
• 近期成功率、失败率和耗时是否异常。

完整筛选和分页查询请进入“执行日志”。

设置

设置页集中管理运行接入、访问策略和项目基线：

区域	说明
数据存储声明	只读展示 local、server、both 或缺声明，以及 Server 可访问或被阻断的原因。
运行接入	控制是否接收新任务、并发上限、队列状态和停止全部。
访问策略	切换公开/私有，并进入成员授权。
配置入口	跳转到成员、环境变量、Webhook、版本、KV、知识库和执行日志；至少发布过一个版本后再提供 Embed。
项目基线	只读展示 workflow id、latest、下一版本和更新时间。

接收新任务和并发配置会立即保存。保存失败时，页面会回滚到上一次服务端值并显示错误。

Server Web 只支持服务器数据。项目声明为 server 或 both 时才开放概览、运行、成员、版本、计划、KV、知识库、环境变量、Embed、Webhook 和其它数据页；local 或缺少 dataStorage.mode 时统一阻断这些入口，设置页只读展示声明与原因。声明必须从 Desktop 的项目信息页或项目源码补充，Server Web 不提供绕过声明的修改控件。

成员、邀请和运行控制

项目成员支持四类角色：

角色	权限概览
owner	项目所有者，拥有完整项目管理和源码下载权限。
manager	可管理成员、配置、发布、运行和下载源码。
runner	可运行项目。
viewer	只读查看项目，并可下载保留的源码快照。

成员页会把成员、邀请、运行用户和运行禁止名单整合到同一张表中。身份展示统一使用头像、显示名、邮箱和用户 ID。管理员可以生成邀请链接，邀请被接受后用户会加入项目成员表。

运行禁止名单用于阻止指定用户运行项目。owner 和 manager 不能被加入禁止名单。解除禁止后，该用户会恢复其角色允许的运行能力。

项目身份

服务器项目以 UUID 作为稳定身份。Desktop 新建和克隆本地项目时会立即生成 UUID、写入 package.json.id，并用它承载本地路由、SQLite 会话、运行记录和项目数据。手工导入的旧空 ID 项目仍会获得稳定注册 UUID 以便迁移；创建云端应用时，Desktop 会把现有 package UUID 或该注册 UUID 作为必填 workflowId 发送给 Server，并在旧项目中将同一个值写进 package.json.id。

POST /api/workflows 必须提供本地 package.json.id 中的 UUID 作为 workflowId，以及 projectType: "workflow" | "conversation" | "kanban" 和包含 dataStorage.mode 的完整 projectInfo。Server 在一个创建请求中原子保存 UUID、名称、类型、完整声明、可选 projectCard 与可见性，不再先创建默认记录再二次同步；该接口不接收源码或完整 package.json。项目已存在且由同一账号管理时，同 UUID、名称和类型的重试会恢复绑定并刷新完整声明，不会创建第二个项目。首次上传源码仍会校验创建类型：Workflow/Conversation 静态分析 executor 的 projectType，Kanban 读取 package.json.workflowCode.projectType 并要求配置后的 HTML 入口。发布、成员授权、Kanban 配置、远程运行、KV、日志和 actor 记录都以该 UUID 对齐。

package.json 根 name 是默认名称；workflowCode.projectInfo 保存本地化名称、手工声明、展示平台和强制数据存储位置。已绑定 Desktop 通过 PUT /api/workflows/{workflowId}/project-info 同步完整 { name, projectInfo }。Server 按界面语言显示本地化名称并回退默认名称，搜索覆盖默认、简体中文和英文。普通声明与 macOS/Windows/Web 平台仅用于展示；dataStorage.mode 严格决定 Server 能否执行项目以及访问 KV、知识库和 PersistentValue，不会回退到本地或另一种存储。

文件存储模式和数据库模式都会把未迁移源码作为明确错误返回。Workflow/Conversation 缺少 executor 类型、Kanban 缺少 package 类型或配置后的 HTML 入口、未知类型、遗留 conversation.enabled 或 workflowCode.projectCard.kind 不会让项目从列表中静默消失，也不会回退成 Workflow；修正源码后再重新上传或读取。

具备项目管理权限的客户端可以通过 POST /api/workflows/{workflowName}/project-card-image 上传裁剪后的 WebP 图片。请求只接受 image/webp，单文件最大 1 MB；Server 按内容哈希保存图片，并返回可公开读取、长期缓存的不可变 URL。随后使用 PUT /api/workflows/{workflowName}/project-card 保存只包含图标、图片 URL、图标颜色和背景颜色的视觉元数据；该接口不能修改项目类型。历史内容哈希图片会继续保留，避免旧项目元数据或已发布版本中的 URL 失效。

GET /project-card-images/{workflowId}/{hash}.webp 不需要登录，用于项目列表、公开 Embed 和其它展示入口读取图片。上传和卡片更新接口仍要求登录及对应项目管理权限。旧 projectCard.iconUrl 中已有的外部 http(s) 地址保持兼容读取，但 Desktop 不再提供手动填写入口。

用户与 Sub2API 绑定

配置 Sub2API 管理连接后，全局用户管理表会显示每个 Workflow 用户的 Sub2API 绑定状态。默认列表只检查当前分页中的用户，并使用 10 秒进程内缓存合并相同用户的重复查询；选择“未绑定 Sub2API”时，Server 会先检查符合账号与搜索条件的用户，再按未绑定状态筛选和分页。Sub2API 暂时不可用时显示检查失败，不影响 Workflow 用户列表继续加载。

用户表的操作入口会打开统一的用户管理弹窗，可在用户资料、角色权限、Sub2API 和账号状态区域之间切换。Sub2API 邮箱和用户名以固定文本展示；已绑定用户可以绕过列表缓存实时校验绑定是否仍然有效。具备 users.manage 权限的管理员可以对未绑定用户执行绑定，也可以在二次确认后解除已有绑定。Server 使用 Workflow 用户 ID 作为 Sub2API 用户名，并生成 <userId>@workflow-code.local 邮箱和随机密码，在 Sub2API 中创建普通用户。创建操作使用确定性邮箱进行幂等检查，重复请求不会创建第二个用户。解除绑定会删除对应的 Sub2API 普通用户，并由 Sub2API 按其用户删除语义处理该用户的 API Key 等关联资源；Workflow 用户不受影响，重复解除会保持未绑定状态。绑定和解绑成功后会立即失效相关用户状态缓存。随机密码不会返回浏览器；Sub2API 启用 Backend 模式时，新建的普通用户仍不能直接登录。

Sub2API API 密钥分组

系统管理员可以在管理中心左侧展开 Sub2API，进入“订阅配置”管理可向 Workflow Server 用户提供的 Sub2API API 密钥分组。这里展示的是 Sub2API 管理接口中的 API 密钥分组，不是 Workflow 用户组。

模型能力不在订阅配置中由管理员声明。Sub2API 仍是分组与可用模型的真相源；Server 只使用版本化模型能力目录为实时模型列表补充显示名称、视觉、联网、推理和工具调用信息。目录无法识别的模型仍可用于普通调用，但不会开放未声明的能力。

页面提供三类操作：

• “刷新配置”重新获取当前分组和 Server 已保存的开放选择。
• “从 Sub2API 同步”绕过短期缓存重新拉取分组，并记录管理员同步审计事件。
• “保存配置”持久化当前启用的分组 ID；可以关闭全部订阅。

分组名称、描述、平台、计费类型、启用/停用状态、用量限制和排序以 Sub2API 为准。Server 默认使用 60 秒进程内缓存降低重复读取延迟，相同并发请求只访问一次上游；Workflow Server 数据库只保存管理员开放的分组 ID 和套餐价格，不复制分组描述、计费类型、状态、路由、模型能力或账号数量。计费类型中的 standard 显示为“余额计费”，subscription 显示为“订阅计费”。每行最右侧的配置按钮打开弹窗；管理员可设置是否向用户开放，订阅计费分组还必须设置人民币套餐金额，价格周期固定为 30 天。保存时 Server 会绕过缓存再次读取 Sub2API 并校验分组 ID。该页面和管理 API 均要求 system.admin 权限。

分组表格单独展示 Sub2API 描述、计费类型和订阅金额。订阅计费分组显示人民币套餐金额与固定的 30 天周期，余额计费分组显示“不适用”。页面支持按名称、描述、ID、平台、计费类型、上游状态和开放状态筛选。上游状态中的 active 显示为“启用”，inactive 显示为“停用”。启用、关闭和套餐金额都在末列配置弹窗中完成，不使用行首多选框。超过 20 个分组时使用管理台统一分页。窄屏下筛选控件会按可用宽度分行排列，分组表格保留完整列并可在表格区域内横向滚动，不会带动整个管理页面横向偏移。

Sub2API 用户订阅与退款

系统管理员可以进入管理中心 Sub2API > 用户订阅，分页查看 Sub2API 中的全部用户订阅。订阅状态、套餐、起止时间以及每日、每周、每月用量以 Sub2API 为准；Server 默认使用 10 秒进程内缓存并合并相同并发请求，但不会把这些订阅数据持久化到 Workflow Server 数据库。能够匹配 Workflow 账号的记录会显示账号名称、邮箱和头像，无法匹配的历史记录仍以 Sub2API 用户 ID 展示。页面支持按订阅状态、套餐和平台筛选，并保留已取消订阅的历史记录。

退款功能对应现有模拟付款流程。只有存在 Workflow 已完成订阅订单的生效中订阅才能退款，可退上限为该 Sub2API 订阅关联的已付款总额；由管理员直接在 Sub2API 分配、没有 Workflow 付款记录的订阅不能退款。管理员输入人民币退款金额并确认后，Server 会绕过列表缓存实时读取订阅，创建可重试退款记录并撤销真实 Sub2API 订阅；只有撤销成功后退款才标记为完成，同时立即失效订阅列表缓存。退款失败时页面保留失败状态和重试入口；成功后订阅显示为已取消。退款操作需要 system.admin 权限并写入审计日志。

个人 AI 配置与订单

个人设置的“AI 配置”按“账户余额”“订阅套餐”和“余额计费分组”分区展示。相同计费类型的分组使用等高卡片和一致的标题、权益、状态、操作结构；已开通订阅和余额计费分组都在卡片标题区展示密钥配置状态。每个订阅或余额计费分组都提供“支持模型”入口：分组启用自定义模型列表时以该列表为准，未启用时分页读取分组内 active 账号的当前模型列表并合并去重，因此 Sub2API 账号中新增或删除的模型会在缓存刷新后反映到 Desktop。Server 使用 60 秒进程内缓存合并重复读取，不把模型列表同步到 Workflow Server 数据库。未订阅套餐只显示一个“未开通”状态区，不重复铺开未配置密钥、空时间、空额度；订阅完成后才显示付款时间、到期时间以及每日、每周、每月额度。每个周期通过进度条展示当前用量、总额度和剩余额度，未设置上游限制的周期显示“不限”。这些额度以 Sub2API 为准，Server 默认使用 10 秒进程内缓存并合并相同并发请求，不同步到 Workflow Server 数据库。用户点击订阅或续费后先进入模拟付款弹窗，确认后 Server 会绕过缓存检查现有订阅，在真实 Sub2API 中分配或续期 30 天订阅，再为该用户创建绑定到对应分组的 API 密钥；写入成功后立即失效订阅和密钥缓存。

“使用偏好”按当前账号保存管理员开放分组的完整优先级。用户通过上移、下移调整后显式保存；未订阅、已停用或暂时失效的分组仍保留原位置，服务器生成 LLM 凭据目录时跳过不可用项并选择后续有效配置。Desktop 和 Web 共享同一份服务端偏好，任一端保存后另一端刷新即可同步。未保存偏好时沿用分组 ID 升序，新开放且未列入已有偏好的分组追加到末尾；此回退不重放已经开始的模型请求。

Sub2API 余额属于用户账户，由全部余额计费分组共享，因此页面只在顶部账户余额区域显示一次余额和充值入口。账户余额以 Sub2API 为准并使用默认 10 秒进程内缓存，不同步到 Workflow Server 数据库。账户充值订单不关联具体分组；用户输入人民币充值金额并确认模拟付款后，Server 按 1:1 数值增加 Sub2API 账户余额，并立即失效余额缓存。每个余额计费分组卡片分别展示按 Asia/Shanghai 时区统计的今日用量、包含今日在内的过去 30 个自然日用量和累计总用量；这些数据使用 Sub2API 的实际扣减金额口径并使用默认 10 秒进程内缓存。余额计费分组首次“启用”时创建对应分组密钥，不会再次充值；“停用”只把现有 Sub2API Key 状态改为 inactive，不删除密钥；“重新启用”直接把同一个 Key 恢复为 active，不创建重复密钥。Key 状态写入成功后会立即失效相关缓存。外部创建操作使用稳定幂等键，重复请求不会重复创建同名分组密钥。

个人设置的“AI 用量”按最近 7 天、最近 30 天或全部时间分页读取当前账号的 Sub2API 请求记录。页面汇总请求次数、总 Token、实际花费和平均耗时，并逐条展示模型与配置、请求入口、输入/输出/缓存 Token、标称与实际花费、总耗时、首 Token 延迟和计费方式。每页固定展示 20 条，筛选或翻页时从 Sub2API 重新读取对应分页；Server 使用默认 10 秒进程内缓存合并相同并发查询，并在默认 5 分钟 stale 窗口内为临时网络、超时、限流或 5xx 故障返回最后一次成功结果。用量明细不写入 Workflow Server 数据库，浏览器响应不会包含真实 Sub2API Key、用户资料、IP、User-Agent、上游请求 ID 或内部账号标识。

个人设置的“订单”展示订阅和账户余额充值的订单号、产品、金额、状态、付款时间、完成时间与创建时间。订单先保存为待付款，确认后进入处理中；Sub2API 同步完成后标记已完成，同步失败则标记失败并允许后台重试。订阅订单保存分组关联，账户余额充值订单不保存分组关联。Sub2API 密钥明文仅在服务端创建调用的内存中短暂出现，随后立即丢弃；Workflow Server 数据库只记录必要的外部用户、订阅和密钥 ID，用户 API 和页面不返回这些关联 ID、密钥前缀或密钥明文。

运行队列

每个 workflow 都有自己的运行接入配置：

• acceptsNewRuns：是否接收新任务。
• concurrency：当前 server 实例允许的并发数。

超过并发上限的运行会进入 waiting 状态，等可用槽位后继续执行。设置页会展示执行中和等待中的任务，并提供停止单条或停止全部入口。

多 server 实例部署时，concurrency 是每个实例的上限；停止全部只作用于接收该请求的实例。

定时任务

Workflow 项目的“定时任务”页按计划展示启用状态、IANA 时区、触发规则、精确版本、entrypoint、下次运行、最近结果和跳过原因。可以创建、编辑、启停或删除计划，也可以立即触发一次并查看 fire 历史。Conversation 和 Kanban 不显示该页。

Server 计划只接受精确已发布版本，不接受 latest 或 draft。保存时会校验版本在线、入口存在且参数符合该入口的静态定义，并返回未来 5 次触发预览。项目 package 声明的 workflowCode.schedulePresets 会作为未启用建议显示，必须由用户确认后才创建。

管理计划需要 schedule.manage 权限并具备项目访问权；立即运行还需要 runs.create 和项目运行权限。计划创建者身份不会被普通编辑替换，每次 fire 都会重新检查创建者仍为 active、权限仍有效、目标版本和入口仍可执行，运行额度也归创建者。

同一计划上一次 run 未结束时，本次 fire 记录为 skipped_overlap，不会进入等待队列或重试；waiting_for_input 同样视为未结束。Server 停机期间的触发不补跑，恢复后只记录一条 skipped_missed 并推进到未来首个时间。多实例通过数据库领取和 lease 恢复 fire；同一计划与计划时间的唯一记录避免重复创建 run。完整规则参见 Workflow 定时运行。

版本详情

版本页展示版本号、上传用户、发布日志、发布时间、生命周期状态、latest 标记和“Server 可运行 / 仅本地 / 静态 Web”状态。版本 API 同时返回随版本固化的 sourceMode 与 executionTargets。

源码上传会先创建持久化准备任务。Desktop 或 CLI 按项目根目录 .workflowignore 选择文件并提交归档，.gitignore 不参与；上传请求只等待服务器保存归档，然后返回 jobId。启用 executionTargets.server 时，Workflow/Conversation 执行解包、安装依赖和 bundle/minify；Server 关闭时只解包、校验、复制并哈希源码，不安装依赖、不 bundle，也不创建 runtime artifact。Kanban 固定不进入 Server executor，只校验 artifactDir、HTML entry 与可选 kanban.json，并原样保留静态产物。任务和 draft 都保存同一发行策略；publish 省略策略时沿用 draft，显式不一致返回 409。

发行目标随每个不可变版本固化：

目标	行为
server: true	生成 Server runtime，可供 Run、Debug、Embed、Webhook、External API 和计划任务使用。
desktop: ["macos"] / ["windows"]	允许对应 Desktop 下载；必须使用 source 模式。
Server + Desktop	同时保存 Server runtime 与可下载源码。
Kanban 全部为空	继续由 Server 静态托管 Web 产物，但不进入 Server executor，也没有 Desktop 发行目标。

Workflow/Conversation 至少启用一个目标；Kanban 强制 server: false。首次 Workflow/Conversation 发布默认仅 Server，后续上传继承上一精确版本的策略。旧 source 版本兼容为 Server 加 macOS/Windows，旧 bundled 版本保持仅 Server。

发布时的源码模式会随版本固化：

模式	版本内容
bundled	Workflow/Conversation 保存可运行的 bundle/minify 产物；Kanban 保存完整静态站点资源。
source	Workflow/Conversation 在运行产物之外保留原始源码快照；Kanban 同样保留完整静态站点资源，供受权限控制的下载使用。

Workflow/Conversation 的两种模式都会保留上传清单中已有的 README，但 README 不是上传必需文件；Kanban 只要求 package.json 与配置后的 HTML 入口，也不强制 README。宿主不再暗中排除 .env*、node_modules、dist、Git 元数据、缓存或临时文件；项目必须在 .workflowignore 中显式声明。该规则文件自身始终保留，必需入口被规则排除时上传失败并指出生效规则。

GET /api/workflows/{workflowName}/source-files 只读取已发布的 source 模式版本，不允许下载 draft，并要求 platform=macos|windows 与目标版本的 Desktop 发行目标匹配。调用方必须先具备项目读取权限，并同时具备 projects.download_source 全局权限，或以项目 owner、manager、viewer 成员身份访问；runner 角色不具备源码下载权限。项目组下载只用根版本的发行目标控制整组下载，included 依赖仍按精确 dependency lock 与源码权限处理。

关联项目与源码交付

项目详情的“关联项目”工作区面向 Workflow、Conversation 和 Kanban 统一管理 workflowCode.projectInfo.relatedProjects。关系由 alias、目标项目 UUID 和“允许对方访问当前项目”的 KV 授权组成；双方当前声明互相指向才是“已确认”，单边声明显示“待确认”。能同时管理两个项目时，Server 在一个事务中写入或删除双方关系；不能管理目标项目时只保存当前项目声明，且不会产生 KV 权限。

新建双方关系默认在两个项目中显式写入 read: all、write: none。读取、写入规则分别支持 none、all 和带非空前缀列表的 prefixes。A 通过自己的 alias 找到 B，但实际访问要读取 B 对 A 的当前授权；getValue 检查 read，setValue 检查 write，compare-and-set 同时检查 read 和 write。每次访问都重新读取双方当前声明，因此修改、删除关系或撤销授权立即生效。关联 KV 只允许直接关系，不会继续递归解析 B 的关联项目。

Kanban 项目组的源码交付从根项目精确版本中已确认的通用关系生成。发布者可以把关联项目选为 included，也可以保留为 external。Server 为根项目的每个精确版本保存 dependency lock：included 项固定关联项目的精确已发布版本和 source hash，external 项只保留 alias 与项目 UUID。待确认关系可以保存在 draft 和版本中，但不进入 dependency lock 的 included 集合。

项目组发布按以下顺序执行：

1. 校验发布者对根项目和全部 included 项目的管理权限，并预留各项目版本。
2. 校验 project-group v1 归档、每个项目类型、源码哈希和构建结果。
3. 以 source 模式发布 included 项目。
4. 写入完整 dependency lock，最后发布并激活 Kanban 根版本。

preparing 上传中断后可以重新提交完整项目组包，publishing 中断后可以幂等续跑；已经发布且 hash 一致的依赖不会重复创建版本。任一步失败时根版本不会上线。项目组归档、Server 上传和下载都禁止包含 KV、PersistentValue、定时计划、运行历史、环境变量、SQLite、CLI 登录凭据或其它宿主用户配置。

源码权限与关系中的 KV 权限分开管理：

• included 依赖下载要求关联项目读取与源码下载权限。缺少权限时，下载其余项目并返回短期申请链接；登录用户提交原因后，由关联项目 owner 或 manager 批准、拒绝或撤销项目级 download_source 能力。
• 用户具备消费项目 A 的读取或运行权限，且 A-B 关系双方确认后，即可通过 A 的 alias 按 B 对 A 的授权访问 B KV，无需成为 B 的成员。直接打开、管理 B 或绕过 A 访问仍按 B 自己的项目权限校验。
• prefixes 只限制匹配的 KV key，不增加源码下载、运行或管理能力；待确认关系和 none 规则不授予访问。撤销后现有 revision 流和后续请求立即失效。
• Server Web 预览中的关联写入还要求访问者能够管理消费项目；公开 Kanban 仍要求登录和有效 Embed token，项目关系不会放开匿名访问。

“关联项目”页会显示双方 alias、确认状态、双方各自的 read/write 规则，以及 Kanban 精确版本的 included/external 交付方式、源码权限和 Server 数据状态。新增或编辑关系时从当前账号可管理的项目中选择目标；项目 UUID 只作为持久标识，不要求用户手工输入。Server KV 为空时显示“项目已部署，Server 数据尚未初始化”；开发者需要运行相应 Workflow entrypoint、配置定时任务、调用 Server Run API 或自己的业务接口完成初始化，平台不会从 Desktop 本地 KV 自动复制数据。

版本生命周期：

状态	说明
preparing	版本正在准备中。
online	版本已发布且可获取；不保证能够在 Server 执行。
offline	已下线但记录保留。
latest	最新在线发行版，可能是仅本地版本。

Server 运行场景中的 latest 独立解析为最新 Server 可运行在线版本；macOS/Windows 下载中的 latest 分别解析为最新兼容在线版本。显式请求仅本地版本执行时返回可本地化的 409。普通/流式运行、调试、参数解析、Embed、Webhook、External API 和计划任务都经过同一 runtime 门禁，要求 server: true、在线、runtime artifact 完整且 Core 兼容。整体 latest 仍指向最新在线发行版，因此发布仅本地新版本不会中断已有云端入口。旧在线版本可以重新上线或手动下线；整体 latest 版本不能直接下线。

KV 数据库

KV 工作区只读展示声明为 server 或 both 的当前项目服务器 project 和 conversation scope 数据，不混入其它项目或 Desktop 本地 KV。local 或缺声明时，API 与页面都会在读取数据前阻断。KV 与 PersistentValue 使用强制隔离的存储域；该页面只查询 KV 域。列表按页展示 key、scope、conversation、value 类型、大小、摘要、更新时间和最后写入来源。

支持按 key、conversation id、run id、scope、value type 和日志关联状态筛选。点击某一行可以读取完整值；列表默认只返回摘要，避免大型 JSON 阻塞浏览器。

Kanban 页面通过 JS Bridge 写入的值位于当前项目 project scope，因此会出现在同一 KV 工作区。Server Web 预览 Bridge 的当前项目写操作只允许拥有项目管理权限的用户调用；请求不能指定其它项目、scope、数据库路径或 workflow 名称。关联项目请求只能提交当前 Kanban 声明中的 alias 和 key；Server 按页面固定的 resolvedTarget 解析关系，再读取双方当前声明并检查目标项目对当前 Kanban 的 read/write 规则，调用方不能指定目标 UUID。

关联项目 KV 的成功写事务会在同一事务中递增目标项目 revision，提交后通过受鉴权 SSE 通知已经打开的相关 Kanban；回滚不会发送变化。Server Web 预览和 Embed 在连接或重连时先取得完整 revision 快照，之后只接收 alias 与不透明 revision。权限撤销或关系失效时，Server 返回统一的关联项目不可用状态并关闭流，不暴露目标项目、KV key 或数据库信息。

知识库

知识库工作区管理声明为 server 或 both 的当前服务器项目内 markdown 文档。local 或缺声明时，API 与页面都会在访问 PersistentValue 前阻断。左侧展示文档列表和搜索结果，右侧展示预览或编辑器；正文固定保存为 markdown，并通过 PersistentValue 存在服务器数据库中。

常见操作：

• 新建、编辑和删除文档。
• 全文搜索并查看上下文行。
• 按分页加载大型文档列表。
• 查看标题、摘要、创建时间和更新时间。

该页面不会读取或修改 Desktop 本地知识库。Desktop 中选择“服务器”数据源时查看的是同一套服务器项目数据；选择“本地”数据源时则是当前设备的独立存储，二者不会自动同步。

Kanban 页面通过 JS Bridge 使用的知识库与此工作区相同。新建、编辑、删除、搜索和按行读取都沿用同一 PostgreSQL 项目数据与输入限制。

环境变量

环境变量页保存 server 运行时使用的项目配置。server run、external API、Embed 和 Webhook 都会读取这里的值。密钥类变量不会在公开页面中明文展示；保存和删除操作需要明确确认。

Desktop 本地 Env 与 Server 环境变量是两套配置：本地运行读取 Desktop 本地值，发布后远程运行读取 Server 值。

Embed 工作流入口

Embed 只面向至少存在一个已发布版本的项目。仅注册、尚未首次发布的项目不会在项目表格、详情侧栏或设置页显示 Embed；直接访问其 Embed 管理地址会回到项目概览。完成首次发布后，这些入口会自动出现。

Embed 与 Desktop 使用同一套 composer 参数协议。普通 Workflow 按目标版本声明顺序显示 Swagger 式扁平入口列表；紧凑标题栏左侧显示标题、ID 和默认标记，可选说明在最右侧单行显示，标题栏不提供 Run。默认入口初始展开，其它入口必须先展开，再从内容区运行；在其它入口填写参数、选择日期或完成参数联动不会重新展开已手动折叠的入口。点击 Run 只创建该入口的 run，不先执行默认入口。一次只聚焦一条 live run，期间其它入口禁用，结果归属实际入口。Conversation 保持单一会话界面，不显示或接受入口选择。

panel: "quick" 参数显示在 Advanced 右侧；conversation 的快捷选择会在浏览器中按 workflow、访问身份和会话分别保存。Workflow 的草稿按 workflow、精确目标和入口隔离。当所选入口（Conversation 则为 executor）定义 resolveParams 时，浏览器会在初始化以及 main、Advanced、Quick 的任意 Form 参数变化后把当前 args 和入口 ID 发送到受 token 和登录态保护的参数求值接口；动态隐藏会同步更新 Advanced 计数和 Quick 入口。主输入内容仅在参数声明 resolveOnInput: true 时参与触发。求值只返回参数状态补丁，不创建 run；求值中或失败时 Run/Send 不可用。visible: false 不会隐式清空参数，互斥字段需要同时返回 value: null，避免隐藏值继续提交。

Server Web 和公开 Embed 直接消费 shared 的日期参数控件，不维护宿主副本。control: "date" | "time" | "datetime" | "date-range" 使用 YYYY-MM-DD、HH:mm:ss、本地 YYYY-MM-DDTHH:mm:ss 和闭区间 YYYY-MM-DD/YYYY-MM-DD 字符串；它们可用于主表单、Advanced 和用户输入节点，但不用于 Quick。弹出日历通过 portal 展示，避免被 composer 或 Advanced 裁切，并支持 Escape、外部点击和关闭后的焦点归还。点击标题会打开年份、月份双列滚轮，“完成”后切换日历，“取消”保持原月份。宽屏日期范围的两个日历重新打开时分别显示已选的起止月份；起止同月时右侧显示下一个月。任一侧导航不会移动另一侧，窄屏使用单日历。Workflow 入口展开时不显示必填或格式错误，首次点击 Run 后才显示并阻止无效提交，值修正后恢复运行。

Embed 用于生成可嵌入或直接打开的项目页面。开启后 server 返回公开 URL，并使用独立 token 控制入口有效性。

主要配置：

字段	说明
enabled	是否启用公开入口。
title / description	入口元信息。
target	latest 或指定在线版本。
token	公开入口 token；重置后旧链接失效。

普通 workflow 会在实际入口下显示表单/Raw 输入、Output、运行状态和取消入口。conversation workflow 会显示会话列表、消息记录和 composer。文件、图片、工具权限、用户输入节点和 token 用量会按所选入口或 Conversation executor 配置展示。等待人工批准的工具调用会显示工具名称和本次实际 JSON 调用参数；只有请求本身未携带参数时才显示“未提供调用参数”。conversation 的工具权限覆盖值只属于对应会话；在首次发送前修改权限时，浏览器会先创建当前草稿会话并保存覆盖值，新建或未配置会话仍使用 workflow 注册的默认值。普通 workflow 的工具权限按 workflow、精确目标、入口、Embed token 和当前访问身份隔离，并在审批恢复后继续使用同一份策略。

Kanban Embed 不显示 composer、运行历史、Output、Diagram 或 Logs。它从固定版本的 artifactDir 加载配置的 HTML 入口及其离线静态资源，并使用与 Desktop 相同的命名配置界面；没有参数时只显示全幅画布。source 和 bundled 模式发布的 Kanban 版本都使用同一静态项目结构生成 Embed 站点信息和预览。访问者必须已经登录并携带有效 Embed token；首次打开时 Server 会为当前用户创建默认配置，后续命名配置按登录用户隔离，不会跨用户共享。页面 Bridge 使用当前项目级 KV 和知识库，所有满足上述条件的访问者共享这两类数据，并且都可以修改或删除其中内容。关联项目 KV 只按双方已确认的直接关系和目标项目授予当前 Kanban 的 none/all/prefixes 读写规则开放；访问者无需成为目标项目成员。配置变化实时通知 iframe，不创建 run history；具备读权限的关联项目 revision 变化会通知 iframe，让页面自行防抖重读当前数据，撤销关系或读权限会立即关闭订阅。Kanban 不支持 Run、Webhook、external run 或 debug node。

公开 Embed 的历史记录按有效 actor 隔离：登录用户使用账号 ID，未登录访问使用浏览器生成的匿名用户标识。管理员从执行日志进入深链时，可以查看被授权范围内的目标会话。

Webhook

Webhook 用于让外部系统触发 workflow。配置页包含签名入口、body 映射、过滤规则和投递日志。

配置项包括：

• 是否启用。
• 目标版本。
• Workflow 入口；Conversation 不显示该选项。
• X-Workflow-Webhook-Secret 签名头。
• body 到 workflow input 的映射。
• 请求体过滤规则。

触发路径是：

POST /webhooks/{workflowName}/trigger

过滤规则使用 body path 语法，$ 表示完整 JSON body。条件支持 equals、not_equals、contains、starts_with、ends_with、matches、in、exists 和 missing。

{
  "enabled": true,
  "target": "latest",
  "entrypointId": "validate",
  "mapping": [{ "bodyPath": "$", "inputName": "payload" }],
  "filters": [
    {
      "conditions": [
        { "bodyPath": "object_kind", "operator": "equals", "value": "push" }
      ]
    }
  ]
}

目标版本变化时，配置页会重新加载入口目录，并分别显示 loading、无入口和已保存入口失效状态；body mapping 只按当前入口的参数校验。旧 Webhook 配置的空入口会按目标版本默认入口读取，下一次保存时固化为显式 ID。

Webhook 保存时按目标版本校验入口。配置为 latest 后，如果未来 latest 版本不再包含已保存入口，触发请求返回 409 且不会创建 run，也不会静默回退默认入口。未配置过滤规则时，所有通过签名和入口校验的请求都会触发运行；配置后，只有命中过滤条件的请求才会创建 run。

审计日志

审计日志覆盖账号、权限、API key、device flow、项目上传、发布、版本上下线、运行、取消、用户输入恢复、环境变量、Embed 和 Webhook 等敏感操作。

审计读取需要 audit.read 权限。审计详情会脱敏 token、secret、password、Authorization、cookie、session 和环境变量值等凭据字段，只保留必要上下文用于排查。

移动端与深色模式

项目详情、KV、Embed、Webhook、日志、Sub2API 订阅配置和弹窗都支持移动端布局。宽表格在自身区域内横向滚动，筛选控件会随可用宽度重排。深色模式沿用同一套中性色和语义色，确保状态、警告、错误和操作入口可辨认。