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

Sindri V3 Extension Development Guide

V3 extensions are YAML-driven, declarative configurations for the modern Rust-based Sindri CLI platform.

V3 Paths and Resources

V3 Categories

# Valid V3 categories (different from V2!)
- ai-agents      # AI agent frameworks
- ai-dev         # AI development tools
- claude         # Claude-specific tools
- cloud          # Cloud provider tools
- desktop        # Desktop environments
- devops         # DevOps/CI/CD tools
- documentation  # Documentation tools
- languages      # Programming runtimes
- mcp            # Model Context Protocol servers
- productivity   # Productivity tools
- research       # Research tools
- testing        # Testing frameworks

Quick Start Checklist

1. Create directory: v3/extensions/{name}/
2. Create extension.yaml with required sections
3. Validate: sindri extension validate {name}
4. Test: sindri extension install {name}
5. Add docs section to extension.yaml (optional, for human-written content)
6. Update catalog: v3/docs/EXTENSIONS.md
7. Add to registry: v3/registry.yaml (alphabetically by category)
8. Add to compatibility matrix: v3/compatibility-matrix.yaml (see Compatibility Matrix Management)

Extension Directory Structure

v3/extensions/{name}/
├── extension.yaml       # Required: Main definition
├── mise.toml            # Optional: mise configuration
├── scripts/             # Optional: Custom scripts
│   ├── install.sh
│   └── uninstall.sh
├── templates/           # Optional: Config templates
│   └── SKILL.md         # Project context file
└── resources/           # Optional: Additional resources

Minimal Extension Template

metadata:
  name: my-extension
  version: 1.0.0
  description: Brief description (10-200 chars)
  category: ai-dev  # Use V3 categories!
  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:
      - gpgKey: https://download.docker.com/linux/ubuntu/gpg
        sources: "deb [arch=amd64] https://download.docker.com/linux/ubuntu jammy stable"
    packages:
      - docker-ce
    updateFirst: true

binary (Direct download - Enhanced in V3)

install:
  method: binary
  binary:
    downloads:
      - name: tool
        source:
          type: github-release  # or: direct-url
          url: https://github.com/org/repo
          asset: "tool-linux-amd64.tar.gz"
          version: latest
        destination: ~/.local/bin/tool
        extract: true

npm-global (V3-only method)

install:
  method: npm-global
  npm:
    package: "@scope/package@latest"

script (Custom installation)

install:
  method: script
  script:
    path: scripts/install.sh
    args: ["--option", "value"]
    timeout: 600  # V3 default is 600s

hybrid (Multiple methods)

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

Requirements (V3 Enhanced)

requirements:
  domains:
    - api.github.com
    - registry.npmjs.org
  diskSpace: 500          # MB required
  memory: 256             # MB runtime memory
  installTime: 120        # Estimated seconds
  installTimeout: 600     # Max timeout
  validationTimeout: 30   # Validation timeout
  secrets:
    - GITHUB_TOKEN
  gpu:                    # V3-only: GPU requirements
    required: false
    recommended: true
    type: nvidia          # nvidia, amd, any
    minCount: 1
    minMemory: 4096       # MB
    cudaVersion: "12.0"

Capabilities (Optional - Advanced Extensions)

project-init (with priority)

capabilities:
  project-init:
    enabled: true
    priority: 50          # V3-only: Lower = earlier execution
    commands:
      - command: "mytool init --force"
        description: "Initialize mytool"
        requiresAuth: anthropic
        conditional: false
    state-markers:
      - path: ".mytool"
        type: directory
    validation:
      command: "mytool --version"
      expectedPattern: "^\\d+\\.\\d+"

auth (Multi-method)

capabilities:
  auth:
    provider: anthropic   # anthropic, openai, github, custom
    required: false
    methods: [api-key, cli-auth]
    envVars: [ANTHROPIC_API_KEY]
    validator:
      command: "claude --version"
      expectedExitCode: 0
    features:
      - name: agent-spawn
        requiresApiKey: false
        description: "Works with CLI auth"
      - name: api-integration
        requiresApiKey: true
        description: "Requires API key"

hooks (Lifecycle)

capabilities:
  hooks:
    pre-install:
      command: "echo 'Pre-install'"
      description: "Preparation"
    post-install:
      command: "mytool doctor"
      description: "Health check"
    pre-project-init:
      command: "mytool check"
    post-project-init:
      command: "echo 'Ready'"

mcp (MCP Server Registration)

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

project-context (V3-only: CLAUDE.md merging)

capabilities:
  project-context:
    enabled: true
    mergeFile:
      source: templates/SKILL.md
      target: CLAUDE.md
      strategy: append-if-missing  # append, prepend, merge, replace, append-if-missing

features (Advanced feature flags)

capabilities:
  features:
    core:
      daemon_autostart: true
      flash_attention: true
      unified_config: true
    swarm:
      default_topology: hierarchical-mesh
      consensus_algorithm: raft
    llm:
      default_provider: anthropic
      load_balancing: false
    advanced:
      sona_learning: false
      security_scanning: true
      claims_system: false
      plugin_system: true
    mcp:
      transport: stdio  # stdio, http, websocket

collision-handling (V3-only: Smart conflict resolution)

capabilities:
  collision-handling:
    enabled: true

    # Conflict rules for specific files
    conflict-rules:
      - path: "CLAUDE.md"
        type: file
        on-conflict:
          action: append  # overwrite, append, prepend, merge-json, merge-yaml, backup, skip, prompt
          separator: "\n\n---\n\n"

      - path: ".claude"
        type: directory
        on-conflict:
          action: merge
          backup: true

      - path: ".claude/config.json"
        type: file
        on-conflict:
          action: merge-json

    # Version detection markers
    version-markers:
      - path: ".claude/config.json"
        type: file
        version: "v3"
        detection:
          method: content-match
          patterns: ["\"version\":\\s*\"3\\."]

      - path: ".claude"
        type: directory
        version: "v2"
        detection:
          method: directory-exists
          exclude-if: [".claude/config.json"]

    # Upgrade scenarios
    scenarios:
      - name: v2-to-v3-upgrade
        detected-version: "v2"
        installing-version: "v3"
        action: prompt
        message: "Detected v2 configuration. Upgrade to v3?"
        options:
          - label: "Upgrade (backup existing)"
            action: backup
            backup-suffix: ".v2-backup-{timestamp}"
          - label: "Skip v3 config"
            action: skip

Validation Commands

# Validate extension
sindri extension validate my-extension

# Install extension
sindri extension install my-extension

# List extensions
sindri extension list

# Check extension status
sindri extension status my-extension

# Preview generated documentation
sindri extension docs my-extension

Docs Section (Optional - Human-Written Content)

The docs section provides human-written content that is combined with auto-derived content (BOM, requirements, env vars, validation) when generating documentation via sindri extension docs <name>. Documentation is generated on-demand and does not require manually creating markdown files.

docs:
  title: string           # Display name (fallback: title-case of metadata.name)
  overview: string         # Extended description (fallback: metadata.description)
  last-updated: string     # ISO date (YYYY-MM-DD)
  features:                # Key features bullet list
    - "Feature one"
    - "Feature two"
  usage:                   # Usage examples grouped by section
    - section: "Getting Started"
      examples:
        - description: "Check version"
          code: "mytool --version"
          language: "bash"
        - code: |
            mytool init
            mytool run
  related:                 # Related extensions
    - name: other-extension
      description: "Provides complementary tooling"
  notes: string            # Freeform notes (markdown supported)

BOM Tool Types

The bom.tools[].type field uses kebab-case values. The Rust enum uses #[serde(rename_all = "kebab-case")], so multi-word variants are hyphenated.

IMPORTANT: Use cli-tool, NOT cli. Use package-manager, NOT package-manager shorthand.

Type Selection Guide

• Most extensions should use cli-tool (the most common type)
• Language extensions (nodejs, python, ruby): use runtime for the language, package-manager for its package manager
• MCP servers: use server
• AI agents/tools: use cli-tool (they are CLI tools, not applications)

Common Mistakes

Common V3 Patterns

Language Runtime

metadata:
  name: nodejs
  version: 1.0.0
  description: Node.js LTS runtime
  category: languages  # V3 uses 'languages' not 'language'

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

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

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

CLI Tool (e.g., AI coding assistant)

metadata:
  name: kilo
  version: 1.0.0
  description: AI coding assistant CLI
  category: ai-dev
  dependencies: [mise-config, nodejs]

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

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

bom:
  # NOTE: Versions researched 2026-02-16
  tools:
    - name: kilo
      version: "1.0.21"
      source: mise
      type: cli-tool       # NOT 'cli' - must be 'cli-tool'
      license: Apache-2.0
      homepage: https://kilo.ai
      purl: pkg:npm/%40kilocode/cli@1.0.21

MCP Server Extension

metadata:
  name: my-mcp
  version: 1.0.0
  description: MCP server for service integration
  category: mcp

install:
  method: npm-global
  npm:
    package: "@myorg/mcp-server@latest"

validate:
  commands:
    - name: my-mcp
      expectedPattern: "\\d+\\.\\d+"

capabilities:
  mcp:
    enabled: true
    server:
      command: "my-mcp"
      args: ["serve"]
    tools:
      - name: "service-query"
        description: "Query service data"

AI Agent Tool with Full Capabilities

metadata:
  name: claude-flow-v3
  version: 3.0.0
  description: Multi-agent orchestration with 10x performance
  category: ai-agents
  dependencies: [nodejs]

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

configure:
  environment:
    - key: CF_SWARM_TOPOLOGY
      value: "hierarchical-mesh"
      scope: bashrc

capabilities:
  project-init:
    enabled: true
    priority: 50
    commands:
      - command: "claude-flow init --full"
        description: "Initialize Claude Flow v3"
        requiresAuth: anthropic

  auth:
    provider: anthropic
    methods: [api-key, cli-auth]
    features:
      - name: agent-spawn
        requiresApiKey: false
        description: "CLI features"

  hooks:
    post-install:
      command: "claude-flow doctor --check"
    post-project-init:
      command: "claude-flow status"

  mcp:
    enabled: true
    server:
      command: "npx"
      args: ["-y", "@claude-flow/cli@alpha", "mcp", "start"]
    tools:
      - name: "agent-spawn"
        description: "Spawn agents"
      - name: "swarm-coordinate"
        description: "Coordinate swarms"

  collision-handling:
    enabled: true
    conflict-rules:
      - path: ".claude"
        type: directory
        on-conflict:
          action: merge
          backup: true

  project-context:
    enabled: true
    mergeFile:
      source: templates/SKILL.md
      target: CLAUDE.md
      strategy: append-if-missing

V3-Specific Notes

1. Extension Discovery: V3 auto-discovers extensions from v3/extensions/ directory, but v3/registry.yaml must be maintained for registry listing
2. Rust Validation: V3 uses native Rust schema validation (faster, stricter)
3. Enhanced Binary Downloads: Supports GitHub release asset patterns
4. GPU Requirements: First-class GPU specification for AI workloads
5. Collision Handling: Smart conflict resolution for cloned projects
6. Project Context: Automatic CLAUDE.md file management
7. Generated Docs: Extension documentation is generated on-demand via sindri extension docs <name> combining human-written docs section content with auto-derived data from the extension YAML

Post-Extension Checklist

After creating an extension:

1. Preview docs: Run sindri extension docs <name> to preview generated documentation
2. Catalog: v3/docs/EXTENSIONS.md (add to category table + extension list)
3. Registry: v3/registry.yaml (add alphabetically under correct category)
4. Test locally: sindri extension install {name} && sindri extension status {name}

Registry Entry Format

Add to v3/registry.yaml under the appropriate category section (alphabetically):

extensions:
  # Category Section (e.g., # MCP Servers)
  your-extension:
    category: "mcp"
    description: "Brief description matching extension.yaml"

Compatibility Matrix Management

When creating or modifying extensions, you MUST also update the compatibility matrix at v3/compatibility-matrix.yaml.

When to Update

• New extension created - add entry to all applicable CLI version sections
• Extension version bumped - update semver range if the new version falls outside existing range
• Extension removed - remove entry from all CLI version sections

How to Add a New Extension

1. Read v3/compatibility-matrix.yaml
2. Read the new extension's extension.yaml to get metadata.version and metadata.category
3. Add an entry under compatible_extensions in each CLI version section, placed alphabetically within the correct category comment group
4. Use semver range format: ">=X.Y.Z,<NEXT_MAJOR.0.0"

Entry Format

compatible_extensions:
  # Category Comment (e.g., # MCP Servers)
  my-extension: ">=1.0.0,<2.0.0"

Determining the Category Comment Group

Map extension metadata.category to the matrix comment groups:

Example: Adding notebooklm-mcp-cli (category: mcp, version: 1.0.0)

For a newly created extension, use the same range for all current CLI series — the extension is new, so there is no version difference between CLI series yet.

In the 3.0.x section, under # MCP Servers:

      notebooklm-mcp-cli: ">=1.0.0,<2.0.0"

In the 3.1.x section, under # MCP Servers:

      notebooklm-mcp-cli: ">=1.0.0,<2.0.0"

In the 4.0.x section, under # MCP Servers:

      notebooklm-mcp-cli: ">=2.0.0,<3.0.0"

Version Range Rules

Key principle: Only bump the minimum version for a CLI series when the extension itself ships a real software change for that series (actual BOM version updates, new features, changed install scripts). Do not auto-bump minimums just because a new CLI series exists.

Validation

After updating, verify:

• Entries are alphabetically sorted within their category group
• All three CLI version sections have an entry for the new extension
• Semver ranges are valid (use >= and < operators)
• No duplicate entries exist

Extension Version Upgrade

When a user asks to upgrade an extension's software versions, follow this introspection-and-research workflow.

Trigger Phrases

• "upgrade extension X", "update versions for X", "check for newer versions in X"
• "refresh versions", "bump versions", "update cloud-tools versions"

Step 1: Introspect the Extension

Read the extension directory to identify all version sources:

Build a version inventory - a list of every software component and its current pinned version.

Example inventory for cloud-tools:

aws-cli:     2.33.21  (versions.env: AWS_VERSION, bom)
azure-cli:   2.83.0   (versions.env: AZURE_CLI_VERSION, bom)
gcloud:      556.0.0  (versions.env: GCLOUD_VERSION, bom)
flyctl:      0.4.11   (versions.env: FLYCTL_VERSION, bom)
aliyun-cli:  3.2.9    (versions.env: ALIYUN_VERSION, bom)
doctl:       1.150.0  (versions.env: DOCTL_VERSION, bom)
ibmcloud:    2.41.1   (versions.env: IBM_VERSION, bom)

Step 2: Research Latest Versions

For each component in the inventory, use WebSearch to find the latest stable release version:

Search strategies by tool type:

Key rules:

• Only consider stable releases (no alpha, beta, RC, nightly, dev)
• For GitHub releases, use gh api repos/{owner}/{repo}/releases/latest via Bash when possible (faster and more reliable than web search)
• Skip tools with version: dynamic or version: lts (these resolve at install time)
• Include the current year in search queries for freshness

Step 3: Compare Versions

For each component, determine if the latest version is newer:

Semver comparison (most tools): Compare major.minor.patch numerically

• 2.33.21 vs 2.35.0 -> newer (minor bump)
• 0.4.11 vs 0.4.15 -> newer (patch bump)
• 3.2.9 vs 3.2.9 -> same (skip)

Date-based versions (e.g., Google Cloud SDK 556.0.0): Compare as integers

• 556.0.0 vs 563.0.0 -> newer

Symbolic versions (e.g., lts, latest): Skip - these auto-resolve

Step 4: Apply Updates

For each component with a newer version available, update ALL locations where the version appears:

4a. Update versions.env

# Before
AWS_VERSION="2.33.21"
# After
AWS_VERSION="2.35.0"

Also update the # Updated: date comment at the top of the file.

4b. Update mise.toml

# Before
[tools]
python = "3.13"
# After
[tools]
python = "3.14"

4c. Update extension.yaml BOM entries

bom:
  tools:
    - name: aws
      version: "2.35.0"      # Updated from 2.33.21
      purl: pkg:generic/awscli@2.35.0    # Update version in purl too
      cpe: cpe:2.3:a:amazon:aws_cli:2.35.0:*:*:*:*:*:*:*  # Update CPE if present

4d. Update install scripts (if versions are hardcoded)

Search for the old version string in scripts/install.sh and replace with the new version.

4e. Update npm package version (if pinned)

install:
  method: npm-global
  npm:
    package: "@scope/package@2.0.0"  # Updated from 1.5.0

4f. Update bom comment date

bom:
  # NOTE: Versions researched YYYY-MM-DD

4g. Update docs.last-updated

docs:
  last-updated: "YYYY-MM-DD"

Step 5: Bump Extension Version and Update References

After updating software versions, bump the extension's own metadata.version:

• Patch bump (e.g., 2.1.0 -> 2.1.1): Only patch-level software updates
• Minor bump (e.g., 2.1.0 -> 2.2.0): Minor or mixed software version updates
• Major bump (e.g., 2.1.0 -> 3.0.0): Major software version update (e.g., Python 3.x -> 4.x)

Then update all external references to the extension version:

1. v3/docs/EXTENSIONS.md - Update the version number shown in the extensions catalog
2. v3/compatibility-matrix.yaml - Ensure the new version falls within the semver range; if not, update the range (see Compatibility Matrix Management)
3. v3/registry.yaml - Update description if the extension's capabilities changed

When NOT to Bump

• Do NOT bump metadata.version if only the CLI version changed but the extension's software, install scripts, configuration, and capabilities remain identical. metadata.version tracks extension content changes (software versions, install methods, config, BOM), not CLI release cadence.
• Do NOT inflate compatibility matrix ranges to require higher minimums for extensions with no changes. If extension v1.0.0 works fine with CLI 3.1.x, the range should still say >=1.0.0. The matrix should reflect reality.
• Do NOT auto-bump 3.1.x minimums for newly created extensions. A new extension gets the same range across all current CLI series since there is no version difference yet.

Step 6: Report Changes

Present a summary table to the user:

Extension: cloud-tools (2.1.0 -> 2.2.0)

| Component    | Old Version | New Version | Change Type |
|-------------|-------------|-------------|-------------|
| aws-cli     | 2.33.21     | 2.35.0      | minor       |
| azure-cli   | 2.83.0      | 2.84.0      | minor       |
| gcloud      | 556.0.0     | 563.0.0     | minor       |
| flyctl      | 0.4.11      | 0.4.11      | (current)   |
| aliyun-cli  | 3.2.9       | 3.2.9       | (current)   |
| doctl       | 1.150.0     | 1.152.0     | minor       |
| ibmcloud    | 2.41.1      | 2.41.1      | (current)   |

Files modified:
- v3/extensions/cloud-tools/versions.env
- v3/extensions/cloud-tools/extension.yaml (bom + metadata.version)
- v3/docs/EXTENSIONS.md (version reference updated)
- v3/compatibility-matrix.yaml (if version range needed adjustment)

Skipping Upgrades

Some version types should NOT be upgraded automatically:

• version: dynamic - resolved at install time
• version: lts - symbolic, always resolves to latest LTS
• version: latest - always resolves to latest
• Tools where the extension description explicitly states a specific major version constraint (e.g., "Python 3.x runtime" should not jump to Python 4.x)

Troubleshooting