sindri-extension-guide

Sindri 扩展开发指南

新增内容：扩展能力系统

近期新增（2026 年 1 月）：Sindri 现在支持可选的能力系统，适用于高级扩展：

• 项目初始化 - 设置新项目的命令（project-init）
• 多方式身份验证 - 支持 API 密钥和 CLI 身份验证（auth）
• 生命周期钩子 - 安装和项目初始化前后的钩子（hooks）
• MCP 集成 - 注册为 Model Context Protocol 服务端（mcp）

大多数扩展不需要能力——只有扩展了项目管理功能的扩展才需要（如 Claude Flow、Agentic QE、Spec-Kit）。常规扩展（nodejs、python、docker）的工作方式与以往完全相同。

斜杠命令（推荐）

如需可靠地创建扩展并更新所有文档，请使用以下命令：

命令	用途
/extension/new <name> [source]	创建新扩展并完成完整的文档工作流
/extension/update-docs <name>	更新现有扩展的文档

示例：

/extension/new mdflow https://github.com/johnlindquist/mdflow
/extension/update-docs nodejs

这些命令会确保完成完整的工作流，包括所有必要的文档更新。

---

概述

本指南将引导你为 Sindri 创建声明式 YAML 扩展。扩展是 YAML 文件，而非 bash 脚本——所有配置均由声明式 YAML 定义驱动。

文档位置

**重要：**创建任何扩展后，都必须更新相关文档。

关键文档文件

类型	路径	用途
架构	v2/docker/lib/schemas/extension.schema.json	扩展验证架构
注册表	v2/docker/lib/registry.yaml	扩展主注册表
配置文件	v2/docker/lib/profiles.yaml	扩展配置文件定义
类别	v2/docker/lib/categories.yaml	类别定义
扩展文档	docs/extensions/{NAME}.md	单个扩展的文档
目录	v2/docs/EXTENSIONS.md	所有扩展概览
编写指南	v2/docs/EXTENSION_AUTHORING.md	详细的编写参考
幻灯片	docs/slides/extensions.html	可视化演示

快速入门检查清单

1. 创建目录：v2/docker/lib/extensions/{name}/
2. 创建包含必需部分的 extension.yaml
3. 添加到 v2/docker/lib/registry.yaml
4. 验证：./v2/cli/extension-manager validate {name}
5. 测试：./v2/cli/extension-manager install {name}
6. 更新文档（参见下方的扩展完成后检查清单）

扩展目录结构

v2/docker/lib/extensions/{extension-name}/
├── extension.yaml       # Required: Main definition
├── scripts/             # Optional: Custom scripts
│   ├── install.sh       # Custom installation
│   ├── uninstall.sh     # Custom removal
│   └── validate.sh      # Custom validation
├── templates/           # Optional: Config templates
│   └── config.template
└── mise.toml            # Optional: mise configuration

最小扩展模板

metadata:
  name: my-extension
  version: 1.0.0
  description: Brief description (10-200 chars)
  category: dev-tools
  dependencies: []

install:
  method: mise
  mise:
    configFile: mise.toml

validate:
  commands:
    - name: mytool
      versionFlag: --version
      expectedPattern: "v\\d+\\.\\d+\\.\\d+"

扩展 YAML 部分

扩展包含必需部分（metadata、install、validate）和可选部分（requirements、configure、remove、upgrade、bom、capabilities）。

重要：能力是可选的——大多数扩展（nodejs、python、docker 等）都不需要能力。只有需要项目初始化、身份验证、生命周期钩子或 MCP 集成的扩展才需要 capabilities 部分。

1. 元数据（必填）

metadata:
  name: extension-name # lowercase with hyphens
  version: 1.0.0 # semantic versioning
  description: What it does # 10-200 characters
  category: dev-tools # see categories below
  author: Your Name # optional
  homepage: https://... # optional
  dependencies: # other extensions needed
    - nodejs
    - python

有效类别：

• base - 核心系统组件
• language - 编程语言运行时（Node.js、Python 等）
• dev-tools - 开发工具（代码检查工具、格式化工具）
• infrastructure - 云端／容器工具（Docker、K8s、Terraform）
• ai - AI／ML 工具和框架
• agile - 项目管理工具（Jira、Linear）
• database - 数据库服务
• monitoring - 可观测性工具
• mobile - 移动端 SDK
• desktop - GUI 环境
• utilities - 通用工具

2. 要求（可选）

requirements:
  domains: # Network access needed
    - api.github.com
    - registry.npmjs.org
  diskSpace: 500 # MB required
  secrets: # Credentials needed
    - GITHUB_TOKEN

3. 安装（必填）

选择一种安装方式：

mise（语言工具推荐使用）：

install:
  method: mise
  mise:
    configFile: mise.toml # Reference to mise config
    reshim: true # Rebuild shims after install

apt（系统软件包）：

install:
  method: apt
  apt:
    repositories:
      - name: docker
        key: https://download.docker.com/linux/ubuntu/gpg
        url: https://download.docker.com/linux/ubuntu
        suite: jammy
        component: stable
    packages:
      - docker-ce
      - docker-ce-cli

binary（直接下载）：

install:
  method: binary
  binary:
    url: https://github.com/org/repo/releases/download/v1.0.0/tool-linux-amd64.tar.gz
    extract: tar.gz # tar.gz, zip, or none
    destination: ~/.local/bin/tool

npm（Node.js 软件包）：

install:
  method: npm
  npm:
    packages:
      - typescript
      - eslint
    global: true

script（自定义安装）：

install:
  method: script
  script:
    path: scripts/install.sh
    timeout: 300 # seconds (default: 300)

hybrid（多种方式）：

install:
  method: hybrid
  hybrid:
    steps:
      - method: apt
        apt:
          packages: [build-essential]
      - method: script
        script:
          path: scripts/install.sh

4. 配置（可选）

configure:
  templates:
    - source: templates/config.template
      destination: ~/.config/tool/config.yaml
      mode: overwrite # overwrite|append|merge|skip-if-exists
  environment:
    - key: TOOL_HOME
      value: $HOME/.tool
      scope: bashrc # bashrc|profile|session

5. 验证（必填）

validate:
  commands:
    - name: tool-name
      versionFlag: --version
      expectedPattern: "\\d+\\.\\d+\\.\\d+"
  mise:
    tools:
      - node
      - python
    minToolCount: 2
  script:
    path: scripts/validate.sh
    timeout: 60

6. 移除（可选）

remove:
  confirmation: true
  mise:
    removeConfig: true
    tools: [node, python]
  apt:
    packages: [package-name]
    purge: false
  script:
    path: scripts/uninstall.sh
  paths:
    - ~/.config/tool
    - ~/.local/share/tool

7. 升级（可选）

upgrade:
  strategy: automatic # automatic|manual|none
  mise:
    upgradeAll: true
  apt:
    packages: [package-name]
    updateFirst: true
  script:
    path: scripts/upgrade.sh

8. 物料清单（可选，但推荐）

bom:
  tools:
    - name: node
      version: dynamic # or specific version
      source: mise
      type: runtime
      license: MIT
      homepage: https://nodejs.org

9. 功能（可选——仅限高级扩展）

在扩展需要以下功能时使用 capabilities：

• 项目初始化 - 用于设置新项目的命令（例如，claude-flow init、spec-kit init）
• 身份验证 - 运行前验证 API 密钥或 CLI 身份验证
• 生命周期钩子 - 安装前／后或项目初始化命令
• MCP 集成 - 注册为 Model Context Protocol 服务，供 Claude Code 使用

大多数扩展不需要 capabilities。 仅在扩展需要增强项目管理功能时使用。

capabilities:
  # Project initialization (optional)
  project-init:
    enabled: true
    commands:
      - command: "mytool init --force"
        description: "Initialize mytool project"
        requiresAuth: anthropic # or: openai, github, none
        conditional: false # true = only run if condition met

    state-markers:
      - path: ".mytool"
        type: directory
        description: "Mytool configuration directory"
      - path: ".mytool/config.json"
        type: file
        description: "Mytool config file"

    validation:
      command: "mytool --version"
      expectedPattern: "^\\d+\\.\\d+\\.\\d+"
      expectedExitCode: 0

  # Authentication (optional)
  auth:
    provider: anthropic # or: openai, github, custom
    required: false # true = block installation without auth
    methods:
      - api-key # API key in environment variable
      - cli-auth # CLI authentication (e.g., Max/Pro plan)
    envVars:
      - ANTHROPIC_API_KEY
    validator:
      command: "claude --version"
      expectedExitCode: 0
    features:
      - name: agent-spawn
        requiresApiKey: false
        description: "CLI-based features"
      - name: api-integration
        requiresApiKey: true
        description: "Direct API features"

  # Lifecycle hooks (optional)
  hooks:
    pre-install:
      command: "echo 'Preparing installation...'"
      description: "Pre-installation checks"
    post-install:
      command: "mytool --version"
      description: "Verify installation"
    pre-project-init:
      command: "mytool doctor --check"
      description: "Pre-init health check"
    post-project-init:
      command: "echo 'Project initialized'"
      description: "Post-init notification"

  # MCP server registration (optional)
  mcp:
    enabled: true
    server:
      command: "npx"
      args:
        - "-y"
        - "@mytool/mcp-server"
        - "start"
      env:
        MYTOOL_MCP_MODE: "1"
    tools:
      - name: "mytool-action"
        description: "Perform mytool action"
      - name: "mytool-query"
        description: "Query mytool data"

  # Feature configuration (optional, V3+ extensions)
  features:
    core:
      daemon_autostart: true
      unified_config: true
    advanced:
      plugin_system: true
      security_scanning: false

功能指南：

1. 保持简单 - 仅添加实际需要的功能
2. 状态标记 - 定义 project-init 创建的文件／目录，以确保幂等性
3. 条件命令 - 对可选设置步骤使用 conditional: true
4. 多种身份验证方式 - 尽可能同时支持 API 密钥和 CLI 身份验证
5. 功能级身份验证 - 某些功能可能无需 API 密钥也能使用（使用 features 数组）

添加到注册表

创建扩展后，将其添加到 v2/docker/lib/registry.yaml：

extensions:
  my-extension:
    category: dev-tools
    description: Short description
    dependencies: [nodejs]
    protected: false

验证命令

# Validate single extension
./v2/cli/extension-manager validate my-extension

# Validate all extensions
./v2/cli/extension-manager validate-all

# Check extension info
./v2/cli/extension-manager info my-extension

# Test installation
./v2/cli/extension-manager install my-extension

# Check status
./v2/cli/extension-manager status my-extension

常见模式

语言运行时（基于 mise）

适用场景：Node.js、Python、Go、Rust、Ruby

• 使用 method: mise 和 mise.toml 配置文件
• 在配置部分设置适当的环境变量
• 使用版本命令进行验证
• 无需 capabilities - 只需安装工具

开发工具（基于 npm）

适用场景：TypeScript、ESLint、Prettier

• 依赖 nodejs 扩展
• 使用 method: npm 安装全局软件包
• 添加配置模板

CLI 工具（二进制文件下载）

适用场景：GitHub releases、独立二进制文件

• 使用 method: binary 和 GitHub release URL
• 处理解压（tar.gz、zip）
• 验证二进制文件存在且可运行

复杂设置（hybrid）

适用场景：桌面环境、多步安装

• 使用 method: hybrid 并按顺序执行步骤
• 结合 apt 和 script，以提高灵活性
• 在移除部分包含清理操作
• 无需 capabilities，除非需要项目初始化

AI/项目管理工具（具备相应能力）

适用于：Claude Flow、Agentic QE、Spec-Kit

• 使用合适的安装方式（mise、脚本、npm）
• 为项目初始化添加能力部分
• 定义用于幂等性的状态标记（.claude/、.agentic-qe/、.github/spec.json）
• 添加身份验证配置（anthropic、openai、github 或无）
• 添加生命周期钩子，用于执行安装后/初始化后的操作
• 如果扩展提供 Claude Code 工具，则注册 MCP 服务
• 扩展示例：claude-flow-v3、spec-kit、agentic-qe

当前使用能力的扩展：

扩展	project-init	auth	hooks	mcp	说明
claude-flow-v2	✓	anthropic	✓	✓	稳定版，158+ 个别名
claude-flow-v3	✓	anthropic	✓	✓	Alpha 版，性能提升 10 倍，15 个工具
agentic-qe	✓	anthropic	✓	✓	AI 驱动的测试
spec-kit	✓	none	✓	-	GitHub 规范文档
agentic-flow	✓	anthropic	✓	✓	多 Agent 工作流

脚本指南

所有脚本必须：

1. 以 #!/usr/bin/env bash 开头
2. 包含 set -euo pipefail
3. 成功时退出代码为 0，失败时退出代码为非零
4. 使用 $HOME、$WORKSPACE 环境变量
5. 使用 echo 语句记录进度

示例：

#!/usr/bin/env bash
set -euo pipefail

echo "Installing my-tool..."
# Installation commands here
echo "my-tool installed successfully"

故障排除

问题	解决方案
架构验证失败	检查 YAML 语法，并确认必填字段
未找到依赖项	将缺失的扩展添加到 registry.yaml
安装超时	增加脚本部分中的超时时间
验证失败	检查 expectedPattern 正则表达式的转义
权限被拒绝	脚本必须具有可执行权限

---

扩展文档后续检查清单

重要： 创建或修改扩展后，必须完成以下文档更新：

必需的更新（始终执行）

• 注册表条目 - 添加到 v2/docker/lib/registry.yaml

  extensions:
    my-extension:
      category: dev-tools
      description: Short description
      dependencies: []
  

• 扩展文档 - 创建 docs/extensions/{NAME}.md

  • 文件名使用大写字母（例如，NODEJS.md、AI-TOOLKIT.md）
  • 包含：概述、安装、配置、使用示例
  • 对于 VisionFlow：docs/extensions/vision-flow/VF-{NAME}.md

• 扩展目录 - 更新 v2/docs/EXTENSIONS.md

  • 添加到合适的类别表格中
  • 包含指向扩展文档的链接

条件更新（适用时执行）

• 配置文件 - 如果将扩展添加到配置文件：

  • 更新 v2/docker/lib/profiles.yaml
  • 更新 v2/docs/EXTENSIONS.md 中相关配置文件的说明

• 类别 - 如果添加新类别：

  • 更新 v2/docker/lib/categories.yaml
  • 更新 v2/docker/lib/schemas/extension.schema.json（category 枚举）
  • 更新 v2/docs/EXTENSIONS.md 中的类别文档

• 架构 - 如果添加新的扩展字段：

  • 更新 v2/docker/lib/schemas/extension.schema.json
  • 更新 docs/SCHEMA.md
  • 更新此技能中的 REFERENCE.md

• 幻灯片 - 如果扩展值得重点介绍或已列为特色：

  • 更新 docs/slides/extensions.html

VisionFlow 专属更新

• 更新 docs/extensions/vision-flow/README.md
• 更新 docs/extensions/vision-flow/CAPABILITY-CATALOG.md
• 如适用，更新 VisionFlow 配置文件

更新后的验证

# Validate YAML files
pnpm validate:yaml

# Lint markdown
pnpm lint:md

# Validate extension
./v2/cli/extension-manager validate {name}

---

扩展文档模板

创建 docs/extensions/{NAME}.md 时，请使用此模板：

# {Extension Name}

{Brief description of what the extension provides.}

## Overview

{More detailed explanation of the extension's purpose and capabilities.}

## Installation

\`\`\`bash
extension-manager install {name}
\`\`\`

## What Gets Installed

- {Tool 1} - {purpose}
- {Tool 2} - {purpose}

## Configuration

{Any configuration options or environment variables.}

## Usage

{Usage examples.}

## Dependencies

{List any extension dependencies.}

## Requirements

- **Disk Space:** {X} MB
- **Network:** {domains accessed}
- **Secrets:** {optional secrets}

## Related Extensions

- {Related extension 1}
- {Related extension 2}

---

参考文件

• Schema：v2/docker/lib/schemas/extension.schema.json
• 注册表：v2/docker/lib/registry.yaml
• 类别：v2/docker/lib/categories.yaml
• 配置文件：v2/docker/lib/profiles.yaml
• 示例：v2/docker/lib/extensions/*/extension.yaml

字段详细参考请参阅 REFERENCE.md。 完整示例请参阅 EXAMPLES.md。

**提示：**使用 Glob 和 Grep 工具动态查找当前文档文件：

# Find all extension docs
ls docs/extensions/*.md

# Find VisionFlow docs
ls docs/extensions/vision-flow/*.md