# Space：插件与工作流

Space 是侧边导航栏中的独立页面，与管理已安装插件的“插件中心”分开。提供“插件”“工作流”“我的发布”三个标签，管理员额外看到“审核中心”。支持名称、描述、作者搜索与分页；作者／审核页可以切换插件和工作流、筛选状态。列表与详情之间可以拖动调整大小，窄窗口改为上下排列，控件跟随深浅主题。

Space.Server 使用 XFEExtension.NetCore.ServerInteractive，独立部署 Windows 或 Linux 控制台。AutoConfig 保存账号、会话、两类资源的目录及上传元数据，插件包与工作流包独立存文件，元数据修改通过串行锁保存。首版按单实例部署。

## 上传与使用

1. 在独立的“Space”页面登录。账号与 Space 共用应用固定的本地地址 `http://localhost:3300/space/v1/`，客户端没有地址修改入口。未登录用户也能浏览、下载已上架内容。
2. 上传插件：点击“上传插件”，选择 `.xfeplugin`。包内清单决定插件 ID、版本、能力与依赖；本地插件可先在“插件中心”导出。
3. 上传工作流：点击“上传工作流”，选择已保存的本地工作流，或通过“从文件选择”读取 `.xfeworkflow` / `.json`。填写发布名称、介绍与语义版本（例如 `1.0.0`），点击“提交审核”。本地定义保持不变，工作流 ID 标识同一作者的版本系列。
4. “我的发布”显示自己的插件和工作流及审核说明。管理员在“审核中心”选择资源类型，审核上架、拒绝或下架。公开目录只展示已上架内容，详情中的“查看所有版本”可下载旧版。相同 ID / 版本即使被拒绝或下架也不能覆盖，修改内容后提高版本号。
5. 下载插件会自动解析依赖、校验哈希和清单后安装。下载工作流会校验包与目录信息，默认自动安装并启用 `pluginVersions` 锁定的插件版本，包括它们的传递依赖；找不到锁定版本时说明缺失依赖，停止导入。可以取消自动安装，先导入用于查看，缺失插件仍会阻止运行。
6. 下载的工作流生成新的本地 ID，并默认关闭，避免覆盖已有流程或自动启动触发器。点击“打开工作流编辑器”编辑；准备好后在“工作流”列表中开启。

### 下载前预览

详情中的“预览图形与代码”打开只读窗口：图形化流程可以平移、缩放、选择节点查看参数／端口／代码，并通过下拉框切换结构化子图；“对应 C# 代码”显示由当前图生成的源码，纯 C# 工作流显示发布的实际代码；“插件依赖”显示名称、ID、锁定版本和声明依赖，缺失版本也保留说明。

预览只获取定义和已上架的插件清单，不安装 DLL、不导入工作流、不运行代码或触发器。已上架版本公开预览；未公开版本只有作者本人和管理员可以预览，支持审核前检查。服务端读取包前核对 SHA-256 和目录，客户端检查发布身份与声明，预览图和编辑器均禁止修改。

实际预览：[图形与子图](screenshots/space-preview-graph.png)、[对应 C#](screenshots/space-preview-code.png)、[插件与版本](screenshots/space-preview-plugins.png)。预览面板约束选项卡的实际内容尺寸，确保代码编辑器撑满可用高度。[可见尺寸验证](screenshots/space-preview-code-layout.json)。

工作流包包含图形、C# 代码、端口、参数、变量、内嵌模板与插件版本声明。凭据引用保留，凭据库、浏览器会话、联系人缓存、历史运行和外部文件不打包；发布前应检查代码及普通参数中的个人内容。服务器只检查并保存包，不执行工作流、不启动触发器或加载插件 DLL。

## 启动与管理员

```powershell
dotnet run --project XFEWorkflow/XFEWorkflow.Space.Server -- --data=.artifacts/space --init-admin --account=admin
dotnet run --project XFEWorkflow/XFEWorkflow.Space.Server -- --data=.artifacts/space --url=http://localhost:3300/
```

初始化命令从终端或标准输入读取至少 12 位的密码。公开注册只能创建作者；管理员仅由初始化命令创建。初始化已有管理员的数据目录会拒绝重复创建。发布后的可执行程序接受相同参数，Linux 需给可执行文件设置执行权限。

客户端固定地址包含完整前缀：`http://localhost:3300/space/v1/`。启动以上服务后即可从客户端登录、上传插件与工作流，作者可下架自己的已上架版本。

TLS：

```powershell
$env:XFE_TLS_PFX_PASSWORD = '证书密码'
dotnet run --project XFEWorkflow/XFEWorkflow.Space.Server -- --data=.artifacts/space --url=https://localhost:3443/ --tls-pfx=C:/certs/space.pfx
```

PFX 密码从环境变量读取，不写入命令行或配置。也可在反向代理处终止 TLS，内部服务监听本地地址。Ctrl+C 或 Linux SIGTERM 会停止服务并保存配置。日志在数据目录 logs 中；备份应包含整个数据目录。

## 协议

路由位于 `/space/v1`，使用 ServerInteractive 的 JSON 请求和响应。客户端通过 ClientRequester 传递 deviceInfo/session，公开接口无需登录。请求示例：

```powershell
Invoke-RestMethod -Method Post -Uri http://localhost:3300/space/v1/plugins/search -ContentType application/json -Body '{"query":"AI"}'
```

| 路由 | 参数 | 访问 |
|---|---|---|
| health | 无 | 公开 |
| register | account、password、nickname | 公开 |
| login / relogin | 框架账号密码 / 会话 | 公开 |
| plugins/search | query、offset、limit | 公开 |
| plugins/detail | pluginId | 公开，仅上架版本 |
| workflows/search | query、offset、limit | 公开，按工作流 ID 返回最新上架版本 |
| workflows/detail | workflowId | 公开，全部上架版本，按语义版本降序 |
| workflows/preview | id（发布版本 ID） | 公开，仅已上架版本，返回定义和可用插件清单 |
| workflows/preview/private | id（发布版本 ID） | 作者本人或管理员，支持未公开版本 |
| packages/chunk | kind、id、index | 公开，仅对应资源的上架版本 |
| plugins/mine | 无 | 登录作者 |
| workflows/mine | 无 | 登录作者，仅自己的工作流版本 |
| account/profile | 无 | 登录用户，返回自己的昵称和头像 |
| account/update | nickname、avatarUrl（HTTP/HTTPS，可为空） | 登录用户，只更新自己的资料 |
| uploads/begin | kind、length、sha256；工作流额外提供 version | 登录作者 |
| uploads/chunk | id、index、data（Base64） | 上传所属作者 |
| uploads/complete | id | 上传所属作者 |
| uploads/cancel | id | 上传所属作者，清理分片和临时包 |
| plugins/withdraw | id | 发布所属作者 |
| workflows/withdraw | id | 发布所属作者 |
| reviews/list | kind | 管理员，返回对应资源的所有状态版本 |
| reviews/decide | kind、id、decision、reason | 管理员 |

`kind` 为 `plugin` / `workflow`，不填写时默认为 `plugin`，保留旧插件接口兼容。上传会话的类型和工作流版本在创建时确定，完成上传不能更改。`decision` 为 publish / reject / withdraw。发布状态为 Pending / Published / Rejected / Withdrawn；只能审核待审核版本、下架已上架版本。版本内容不可覆盖，即使已拒绝或已下架也需要新版本号重新提交。

上传分片为 1 MiB，最后一片可更短；插件默认包上限 100 MiB，工作流压缩包及展开定义均不超过 32 MiB。工作流包只允许根目录一个 `workflow.json`，拒绝其他文件、路径穿越、损坏 JSON、无效端点及依赖锁定；最多 10000 个节点、32 层子图。完成时检查片数、长度、SHA-256、ZIP 内容及清单／定义，禁止跨作者声明同一资源 ID。下载同样按片返回，客户端检查哈希与目录声明后安装或导入。每位作者最多保留 5 个未完成上传，两类资源共用此限制；过期上传在 24 小时后清理，客户端上传失败会尝试取消会话并清理临时文件。

作者归属及管理员权限在服务端检查，越权返回 403，格式错误或无效包返回 400。密码使用框架 PBKDF2 保存，会话由框架校验设备及来源；客户端会话使用 Windows DPAPI 保存。

工作流目录元数据保留原始 ID、名称、介绍、版本、Graph / CSharp 类型、输入输出和插件锁定。插件目录与工作流目录分别保存，互不混入搜索或审核结果；两类包分别保存为 `packages/<发布ID>.xfeplugin` 和 `.xfeworkflow`。现有 AutoConfig 数据目录首次升级时自动初始化空的工作流目录，原有账号和插件不迁移。

## 界面与验收

实机截图：[插件目录](screenshots/space-plugins-dark.png)、[上传工作流](screenshots/space-workflow-upload.png)、[工作流与已安装依赖（深色）](screenshots/space-workflows-dark.png)、[浅色](screenshots/space-workflows-light.png)、[窄窗口](screenshots/space-workflows-narrow.png)。

2026-10-13 Windows x64：全量 XFE XUnit 337 项通过，收尾调整后 Space 相关 14 项再次通过；原生界面 6 项通过，使用独立工作区和真实 ServerInteractive 控制台进程。覆盖插件和 Graph / CSharp 工作流上传、审核、权限、版本、损坏包、持久化、插件依赖、默认关闭导入，以及 26 个发布工作流的实际翻页、搜索、安装后状态刷新、深浅主题、面板拖动、账号入口与本地企业微信插件回归。[验收范围与报告](acceptance.md#独立-space-与工作流分享2026-10-13)。