跳到主要内容

包格式

.soduwork-plugin 包的参考说明，适用于 schemaVersion: 1。

包结构​

.soduwork-plugin 文件是一个 zip 压缩包。

my-team-flow.soduwork-plugin
├─ plugin.json          必需
├─ workflow.json        可选；也可以把 "workflow" 写在 plugin.json 里
├─ skills/              可选
└─ README.md            可选
限制值
包大小10 MB
包内文件数300
清单根目录的 plugin.json

包的身份是按文件名和内容计算的 SHA-256，压缩时间、顺序和算法都不影响它。导入时不会运行脚本，也不会建立网络连接。

plugin.json 字段​

字段类型必需说明
schemaVersion数字是1
key字符串是只能用小写字母、数字和短横线。这是稳定身份，不能改变
version字符串是SemVer。同一版本号内容不同会被拒绝，不会覆盖
name字符串是显示名称
description字符串是插件的用途
instructions字符串见说明工作方法。没有工作流的插件，至少要有 instructions、Skill 或 MCP 连接之一
author字符串否
template字符串否method、connector、workflow 或 app。省略时自动推断：有工作流为 workflow；有 MCP 或平台连接为 connector；否则为 method
locales对象否name、description 和输入项文字的翻译，键为 zh-CN、en-US 等
entrypoints对象否conversation、task、automation，值为 true 或 false
inputs数组否见输入项
setup对象否见使用偏好
capabilities对象否见能力声明
workflow对象否{ "nodes": [...] }，见工作流节点
resources数组否见随包文件
evaluations数组否最多 20 个发布评测，见发布
ui对象即用必需窗口和导航入口，见即用
appWindow对象否即用的默认窗口尺寸
process对象否组织工作流的流程标识
icon字符串否PNG，不超过 256 像素、96 KB

身份​

插件所在位置显示为
内置soduwork/<key>
组织org:<org-id>/<key>
个人，仅在一台电脑上local:<uuid>

同一平台或同一组织内 key 不能重复。不同组织可以使用相同的 key。

输入项​

输入项是从任务或自动化启动插件时填写的公开参数。

{
  "key": "run_mode",
  "type": "select",
  "label": "运行模式",
  "options": [
    { "value": "confirm", "label": "每步人工确认（默认）" },
    { "value": "auto", "label": "自动执行" }
  ],
  "default": "confirm",
  "required": true
}
字段说明
key稳定名称
typetext、textarea、boolean、number 或 select
label、description、placeholder显示给用户
requiredtrue 或 false
optionsselect 的选项：字符串，或 { "value", "label" } 对象
defaultselect 的默认值，必须与某个选项的 value 完全一致

输入项不能收集账号、密码、令牌或密钥。

使用偏好​

安装后每位用户填写一次的非敏感偏好。

"setup": {
  "title": "使用偏好",
  "description": "安装后配置一次",
  "preferences": [
    { "key": "language", "label": "语言", "type": "select", "options": ["中文", "英文"], "default": "中文" }
  ]
}

类型：text、textarea、boolean、number、select、multiselect、url。没有偏好时写 { "preferences": [] }。账号、密码、令牌和 OAuth 通过组织连接接入，不放进 setup。

随包文件​

随插件分发的模板、示例、脚本和素材。

"resources": [
  { "path": "templates/report.md", "kind": "template" },
  { "path": "examples/input.json", "kind": "example" },
  { "path": "scripts/render.py", "kind": "script" }
]
规则值
kindtemplate、example、asset、script、reference、ui
目录templates/、examples/、assets/、scripts/、references/、ui/
文件最多 64 个，合计 8 MB
导入文件（草稿 JSON、ZIP 或插件包）不超过 24 MB

越出目录的路径、符号链接、密钥文件和明显的凭据会被拒绝。安装时会连同 SHA-256 一起保存文件，但不会运行脚本。本机对话使用插件时，文件会放到工作目录的 .soduwork/plugins/<key>/<摘要>/ 下。模板请先复制再编辑。

默认窗口尺寸​

即用按默认尺寸打开，居中显示在主窗口所在的屏幕上，屏幕较小时自动缩小。只有需要特定的默认尺寸时才设置 appWindow。

"appWindow": {
  "width": 1280, "height": 800,
  "minWidth": 480, "minHeight": 360,
  "rules": [ { "maxScreenWidth": 1366, "width": "100vw", "height": "100vh" } ]
}

值可以是数字（px），也可以是带 px、vw、vh 单位的字符串。rules 最多 12 条，按屏幕可用宽度从上往下匹配，采用第一条匹配的规则。maxWidth、maxHeight 只限制默认尺寸，用户仍可以最大化。改过的尺寸在下次打开即用时生效。

流程标识​

组织工作流可以在用户选择流程的地方，标明它做什么、交付到哪里。

"process": {
  "enterprise": true,
  "label": "研发流程",
  "route": "AI 修改 → 代码评审 → 合并 → 发布",
  "environments": [ { "label": "测试环境", "scope": "company" } ]
}
字段说明
enterprise在客户端和管理端显示徽标
label默认为"企业流程"
route一句话，不超过 200 个字符
environments最多 8 项；scope 为 company、department 或 project

没有声明 process 时，含 merge、deploy 或 deploy_chain 节点的工作流会被视为企业流程。

自动生成的报告​

SoduWork 会为每个版本生成一份供审查用的报告，不需要你自己维护。

  • 组件：工作说明、Skill、MCP 连接、工作流，以及暂不支持的第三方组件。
  • 依赖：外部 Skill、MCP、密钥名称和环境。只记录名称，不记录值。
  • 权限：网络、脚本、密钥和兼容性阻断项，附低、中、高风险说明。
  • 调用入口：对话、任务、自动化。去掉已有入口属于破坏性变更；新增入口需要重新审查。

绑定不能授予超出版本声明的能力。

编辑此页