extension-guide-v2（扩展指南 v2）

Sindri V2 Extension Development Guide

V2 extensions are YAML-driven, declarative configurations for the Bash/Docker-based Sindri platform.

V2 Paths and Resources

V2 Categories

# Valid V2 categories
- base          # Core system components
- agile         # Project management (Jira, Linear)
- language      # Programming runtimes
- dev-tools     # Development tools
- infrastructure # Cloud/container tools
- ai            # AI/ML tools
- database      # Database servers
- monitoring    # Observability tools
- mobile        # Mobile SDKs
- desktop       # GUI environments
- utilities     # General tools

Quick Start Checklist

1. Create directory: v2/docker/lib/extensions/{name}/
2. Create extension.yaml with required sections
3. Add to v2/docker/lib/registry.yaml
4. Validate: ./v2/cli/extension-manager validate {name}
5. Test: ./v2/cli/extension-manager install {name}
6. Create docs: docs/extensions/{NAME}.md
7. Update catalog: v2/docs/EXTENSIONS.md

Extension Directory Structure

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

Minimal Extension Template

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+"

Install Methods

mise (Recommended for language tools)

install:
  method: mise
  mise:
    configFile: mise.toml
    reshimAfterInstall: true

apt (System packages)

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 (Direct download)

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

npm (Node.js packages)

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

script (Custom installation)

install:
  method: script
  script:
    path: scripts/install.sh
    timeout: 300

hybrid (Multiple methods)

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

Capabilities (Optional - Advanced Extensions)

Most extensions don't need capabilities. Only use for extensions requiring:

• Project initialization (e.g., claude-flow init)
• Authentication validation
• Lifecycle hooks
• MCP server registration

capabilities:
  # Project initialization
  project-init:
    enabled: true
    commands:
      - command: "mytool init --force"
        description: "Initialize mytool"
        requiresAuth: anthropic  # or: openai, github, none
        conditional: false
    state-markers:
      - path: ".mytool"
        type: directory
        description: "Config directory"
    validation:
      command: "mytool --version"
      expectedPattern: "^\\d+\\.\\d+"

  # Authentication
  auth:
    provider: anthropic
    required: false
    methods: [api-key, cli-auth]
    envVars: [ANTHROPIC_API_KEY]
    validator:
      command: "claude --version"
      expectedExitCode: 0
    features:
      - name: agent-spawn
        requiresApiKey: false
        description: "CLI-based features"

  # Lifecycle hooks
  hooks:
    pre-install:
      command: "echo 'Preparing...'"
      description: "Pre-install checks"
    post-install:
      command: "mytool --version"
      description: "Verify installation"

  # MCP server
  mcp:
    enabled: true
    server:
      command: "npx"
      args: ["-y", "@mytool/mcp", "start"]
      env:
        MYTOOL_MCP_MODE: "1"
    tools:
      - name: "mytool-action"
        description: "Perform action"

Registry Entry

Add to v2/docker/lib/registry.yaml:

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

Validation Commands

# 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

Common Patterns

Language Runtime (No Capabilities)

# v2/docker/lib/extensions/nodejs/extension.yaml
metadata:
  name: nodejs
  version: 1.0.0
  description: Node.js LTS via mise
  category: language

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

validate:
  commands:
    - name: node
      expectedPattern: "v\\d+\\.\\d+\\.\\d+"
    - name: npm

bom:
  tools:
    - name: node
      version: dynamic
      source: mise
      type: runtime
      license: MIT

AI Tool with Capabilities

# Extensions like claude-flow-v2, agentic-qe, spec-kit
metadata:
  name: ai-tool
  version: 1.0.0
  description: AI-powered tool
  category: ai
  dependencies: [nodejs]

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

capabilities:
  project-init:
    enabled: true
    commands:
      - command: "ai-tool init"
        description: "Initialize project"
        requiresAuth: anthropic
    state-markers:
      - path: ".ai-tool"
        type: directory

  auth:
    provider: anthropic
    methods: [api-key, cli-auth]

  mcp:
    enabled: true
    server:
      command: "npx"
      args: ["-y", "@ai-tool/mcp"]
    tools:
      - name: "ai-tool-action"
        description: "Perform AI action"

V2-Specific Features

VisionFlow Extensions

VisionFlow extensions use the vf- prefix and are only available in V2:

v2/docker/lib/extensions/vf-{name}/
├── extension.yaml
└── ...

Document in: docs/extensions/vision-flow/VF-{NAME}.md

Shell Aliases

V2 supports 158+ shell aliases defined in extensions. These are configured in the configure.environment section with scope: bashrc.

Script Requirements

All scripts must:

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

echo "Installing..."
# Commands here
echo "Done"

Post-Extension Documentation

After creating an extension, update:

1. Registry: v2/docker/lib/registry.yaml
2. Extension Doc: docs/extensions/{NAME}.md
3. Catalog: v2/docs/EXTENSIONS.md
4. Profiles (if applicable): v2/docker/lib/profiles.yaml

Troubleshooting