扩展能力与清单格式

Suzu Lives 可以导入带有能力清单的本地扩展包，将其中的 Skill 或 MCP 接入软件。使用已有扩展时，先按下面的步骤导入；需要编写扩展时，再阅读后面的 V1 清单格式。

导入并启用扩展#

1. 将扩展包放在本机固定位置，保留清单和它引用的 Skill、脚本等文件。
2. 让 Suzu 助手“打开扩展”，进入“管理 → 扩展”。
3. 点击“导入扩展”，选择扩展包中的 suzu-capability.json 文件。
4. 核对名称、版本、本地来源和“静态检查”提示，再点击“启用”。
5. 下一次聊天会使用新的扩展配置。需要更新已启用的扩展时，再次导入同一 ID 的清单，并点击“更新配置”。

导入用于检查扩展资料，点击“启用”后扩展才会供角色使用。扩展在软件内统一启用，供各联系人使用。按扩展作者的说明准备所需程序和依赖；使用期间，已启用的 MCP 服务可能按配置启动本机程序或连接远程服务。

看到本地文件缺失等诊断时，先恢复扩展包的完整文件，再尝试启用或更新。需要停用、移除或修改扩展类型时，阅读更新与移除说明。

文件与导入范围#

建议将清单命名为 suzu-capability.json。导入时检查的是你选择的本地清单及其引用的文件，软件会显示检查结果。下载依赖和准备运行环境，按扩展作者的说明完成。

保留原扩展包所在的目录和文件，方便以后启用、更新或恢复缺失内容。出现文件缺失提示时，先恢复完整扩展包；日常启停和移除使用软件内的对应按钮。

V1 清单格式#

{
  "schemaVersion": 1,
  "id": "example.local-weather",
  "name": "本地天气",
  "version": "1.0.0",
  "description": "可选，最多 2000 个字符。",
  "adapters": {
    "skill": {
      "directory": "skill"
    },
    "mcp": {
      "transport": "stdio",
      "command": "node",
      "args": ["./server.mjs"],
      "env": {
        "WEATHER_CACHE": "${WEATHER_CACHE_DIR:-./cache}"
      }
    },
    "cli": {
      "command": "local-weather",
      "args": ["--json"]
    }
  }
}

必填字段如下：

description 可选。清单中的字段须符合当前格式，额外的未知字段会被拒绝。

skill 适配器#

skill 必须且只能使用下面一种写法：

"skill": { "directory": "skill" }

"skill": { "file": "SKILL.md" }

推荐 directory。它指向能力包内的一个真实目录，目录根必须有 SKILL.md，并且可包含 scripts/、references/、assets/、模板和其他普通文件。例如：

skill/
├─ SKILL.md
├─ scripts/
│  └─ format-result.mjs
├─ references/
│  └─ contract.md
└─ assets/
   └─ icon.bin

file 是兼容既有单文件 Skill 的写法；安装时它会成为受管目录中的 SKILL.md。两种路径都必须是能力包内使用 / 的相对路径，不能使用绝对路径、反斜杠或 ..。

导入/启用会递归读取目录型 Skill，但只接受真实目录和普通文件：符号链接、特殊文件、路径逃逸、超过 16 层目录、超过 256 个文件、单文件超过 1 MB 或总计超过 8 MB 都会被拒绝。普通文件按原始字节复制，所以资源文件不被转码；根目录 SKILL.md 必须是非空 UTF-8 文本。导入和启用过程不会执行包内脚本、运行 CLI 或 MCP、下载依赖或联网探测；后续聊天中的工具执行与 MCP 启动按实际运行时配置处理。

SKILL.md 使用 frontmatter 填写名称与说明，正文描述这个 Skill 的用途与操作步骤。

mcp 适配器#

V1 支持本地 stdio 与 HTTPS（或本机回环 HTTP）两种描述：

{
  "transport": "stdio",
  "command": "node",
  "args": ["./server.mjs"],
  "env": { "CACHE_DIR": "${CACHE_DIR}" }
}

{
  "transport": "http",
  "url": "https://example.test/mcp",
  "headers": { "X-Client": "suzu-lives" }
}

stdio 的 command 和 args 中以 ./ 开头的文件路径，相对于扩展包目录填写。清单中的命令、依赖和连接地址由扩展作者准备，导入检查不代替实际运行验证。API Key、token 或密码应通过支持的环境变量展开（例如 ${API_KEY}）或扩展自己的配置入口提供，分享清单时检查是否带有完整凭据。

cli 适配器（已预留，不执行）#

"cli": {
  "command": "local-weather",
  "args": ["--json"]
}

cli 字段可省略。当前版本仅保留这份描述，启用扩展时不会单独注册或执行它；清单仍须包含 skill 或 mcp。

更新、停用和移除#

• 更新：再次导入相同 id 的清单，再按页面提示点击“更新配置”或重新启用。
• 更换适配器类型：先停用扩展，再导入更新后的清单。
• 停用：取消扩展在软件中的启用状态，清单仍保留，方便以后重新启用。
• 移除：先取消启用，再移除软件中保存的这项扩展资料。

更新或清理时，如果提示文件内容已被修改，先按错误提示核对扩展文件，再重试。

可参考最小示例清单。示例的 skill/ 目录展示脚本、参考资料和资源的组织方式；导入和启用时不会执行这些文件。server.mjs 是展示本地路径格式的占位文件，实际使用需要提供实现了 MCP 协议的服务程序及其依赖。