agent-protocol-cli 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# agent-protocol-cli
+
+**Discover and install AI Skills — no store needed.**
+
+The official CLI for the [Agent Manifest Protocol](https://github.com/Polaris899/agent-protocol) — an open, decentralized registry of AI capabilities that work across any runtime.
+
+```bash
+npx agent-protocol-cli search 财报分析
+npx agent-protocol-cli install Polaris899/fsa-analyzer
+```
+
+## Features
+
+- 🔍 **Semantic search** — TF-IDF vector matching with CJK support. Search in any language.
+- 📦 **One-command install** — `agent install user/repo` clones, validates, and registers a Skill.
+- ✅ **Schema validation** — Every manifest is validated against the AMP Schema v1.0.
+- 🔄 **Update management** — `agent update` checks all installed Skills for new versions.
+- 🏷️ **Rich metadata** — Capabilities, intents, permissions, audit status, all in the search results.
+
+## Quick Start
+
+```bash
+# Search for Skills
+npx agent-protocol-cli search 天气
+
+# Install a Skill
+npx agent-protocol-cli install Polaris899/fsa-analyzer
+
+# List installed Skills
+npx agent-protocol-cli list
+
+# Get detailed info
+npx agent-protocol-cli info fsa-analyzer
+
+# Validate a manifest
+npx agent-protocol-cli validate ./agent.json
+```
+
+## Registry
+
+Browse the full registry at **[agent-protocol.dev](https://polaris899.github.io/agent-protocol/)**
+
+## Protocol Spec
+
+The Agent Manifest Protocol defines a standard JSON schema for describing AI Skills:
+
+- **Interoperable** — Works with any agent runtime (OpenClaw, OpenAI GPTs, custom)
+- **Decentralized** — Skills live on GitHub, no central store required
+- **Safe by design** — Sandbox levels, permission declarations, verified audits
+
+Read the spec: [`spec/manifest.md`](https://github.com/Polaris899/agent-protocol/blob/main/spec/manifest.md)
+
+## License
+
+MIT

package/bin/agent.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Manifest Protocol CLI
+ * 
+ * Usage:
+ *   agent search <query>       — Search for Skills
+ *   agent install <repo>       — Install a Skill from GitHub
+ *   agent list                  — List installed Skills
+ *   agent update                — Update all installed Skills
+ *   agent info <name|id>       — Show Skill info
+ *   agent validate <path>      — Validate a manifest file
+ */
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { searchCommand } from './commands/search.js';
+import { installCommand } from './commands/install.js';
+import { listCommand } from './commands/list.js';
+import { updateCommand } from './commands/update.js';
+import { infoCommand } from './commands/info.js';
+import { validateCommand } from './commands/validate.js';
+
+const program = new Command();
+
+program
+  .name('agent')
+  .description('Agent Manifest Protocol CLI — discover and manage AI Skills')
+  .version('1.0.0');
+
+program
+  .command('search')
+  .description('Search for Skills matching your intent')
+  .argument('<query>', 'Search query (natural language or keywords)')
+  .option('-l, --limit <n>', 'Max results', '10')
+  .option('--json', 'Output as JSON')
+  .action(searchCommand);
+
+program
+  .command('install')
+  .description('Install a Skill from GitHub (user/repo)')
+  .argument('<repo>', 'GitHub repository (e.g., openclaw/weather-skill)')
+  .option('--dir <path>', 'Install directory', '~/.agents')
+  .option('-v, --version <ver>', 'Specific version (tag) to install')
+  .option('-b, --branch <branch>', 'Specific branch to install')
+  .option('--no-validate', 'Skip schema validation')
+  .option('--no-symlink', 'Skip registering symlink in OpenClaw')
+  .action(installCommand);
+
+program
+  .command('list')
+  .description('List installed Skills')
+  .option('--json', 'Output as JSON')
+  .action(listCommand);
+
+program
+  .command('update')
+  .description('Update installed Skills')
+  .argument('[name]', 'Skill name to update (omit to update all)')
+  .option('-a, --all', 'Update all installed Skills')
+  .option('--check', 'Check for updates without applying')
+  .option('--rollback', 'Rollback to a previous version')
+  .option('--to <ref>', 'Rollback target commit/ref')
+  .option('-f, --force', 'Force update even if already latest')
+  .action(updateCommand);
+
+program
+  .command('info')
+  .description('Show detailed info about a Skill')
+  .argument('<name>', 'Skill name or ID')
+  .option('--json', 'Output as JSON')
+  .action(infoCommand);
+
+program
+  .command('validate')
+  .description('Validate a manifest file against the schema')
+  .argument('<path>', 'Path to agent.json or agent.yaml')
+  .action(validateCommand);
+
+program.parse(process.argv);

package/bin/commands/info.js

@@ -0,0 +1,112 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import chalk from 'chalk';
+
+const AGENTS_DIR = join(homedir(), '.agents');
+const CONFIG_PATH = join(AGENTS_DIR, '.agent-config.json');
+
+export async function infoCommand(name, options) {
+  const asJson = options.json || false;
+
+  // Try local installed first
+  if (existsSync(CONFIG_PATH)) {
+    const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+    const installed = config.installed || {};
+
+    if (installed[name]) {
+      const skill = installed[name];
+      const manifestPath = join(skill.dir, 'agent.json');
+
+      if (existsSync(manifestPath)) {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        renderManifest(manifest, asJson);
+        return;
+      }
+    }
+  }
+
+  // Try searching the registry
+  const registryUrls = [
+    process.env.AGENT_REGISTRY || '',
+    'http://localhost:3456',
+    'https://api.agent-protocol.dev',
+  ].filter(Boolean);
+
+  for (const baseUrl of registryUrls) {
+    try {
+      // Try by exact id first
+      const idRes = await fetch(`${baseUrl}/manifest?id=${encodeURIComponent(name)}`);
+      if (idRes.ok) {
+        const manifest = await idRes.json();
+        renderManifest(manifest, asJson);
+        return;
+      }
+
+      // Fallback: search by name
+      const searchRes = await fetch(`${baseUrl}/search?q=${encodeURIComponent(name)}&limit=1`);
+      if (searchRes.ok) {
+        const data = await searchRes.json();
+        if (data.results && data.results.length > 0) {
+          renderManifest(data.results[0], asJson);
+          return;
+        }
+      }
+    } catch {}
+  }
+
+  console.log(chalk.yellow(`  未找到名为 "${name}" 的 Skill。`));
+  console.log(chalk.gray('  使用 agent search <query> 搜索，或确认名称是否准确'));
+}
+
+function renderManifest(manifest, asJson) {
+  if (asJson) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`📄 ${chalk.bold(manifest.name)}`));
+  console.log(`  ${chalk.gray(manifest.description || '')}`);
+  console.log();
+  console.log(`  ID:      ${chalk.cyan(manifest.id)}`);
+  console.log(`  版本:    ${chalk.green(manifest.version)}`);
+  if (manifest.author?.name) console.log(`  作者:    ${manifest.author.name}`);
+  if (manifest.license) console.log(`  许可:    ${manifest.license}`);
+  if (manifest.tags?.length) console.log(`  标签:    ${chalk.gray(manifest.tags.join(', '))}`);
+  console.log();
+
+  // Capabilities
+  const caps = manifest.capabilities || [];
+  console.log(chalk.blue(`🎯 能力 (${caps.length})：`));
+  for (const cap of caps) {
+    console.log(`  ${chalk.bold(cap.name)} (${cap.id})`);
+    console.log(`    ${chalk.gray(cap.description)}`);
+    if (cap.intents?.length) {
+      const samples = cap.intents.slice(0, 3);
+      console.log(`    ${chalk.gray('意图示例: ' + samples.join(' | '))}`);
+    }
+    console.log(`    ${cap.latency ? chalk.gray(`延迟: ${cap.latency}  |  `) : ''}${chalk.gray(`安全: ${cap.security_level || 'low'}  |  费用: ¥${cap.cost_per_call || 0}/次`)}`);
+    console.log();
+  }
+
+  // Runtime
+  if (manifest.runtime) {
+    console.log(chalk.blue('⚙ 运行时'));
+    console.log(`  引擎:     ${manifest.runtime.engine}`);
+    console.log(`  类型:     ${manifest.runtime.type || 'skill'}`);
+    if (manifest.runtime.config_url) console.log(`  配置:     ${chalk.gray(manifest.runtime.config_url)}`);
+    console.log();
+  }
+
+  // Trust
+  if (manifest.trust) {
+    console.log(chalk.blue('🔒 安全与信任'));
+    const perms = manifest.trust.permissions || [];
+    console.log(`  权限:     ${perms.length > 0 ? chalk.yellow(perms.join(', ')) : chalk.gray('无')}`);
+    console.log(`  沙箱:    ${manifest.trust.sandbox_level || 'basic'}`);
+    if (manifest.trust.verified_by?.length) {
+      console.log(`  ${chalk.green('✓ 已通过审计: ' + manifest.trust.verified_by.join(', '))}`);
+    }
+    console.log();
+  }
+}

package/bin/commands/install.js

@@ -0,0 +1,336 @@
+import { execSync, spawnSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, symlinkSync, rmSync, copyFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, basename, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { createInterface } from 'readline';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = join(homedir(), '.agents');
+const CONFIG_PATH = join(AGENTS_DIR, '.agent-config.json');
+const SCHEMA_PATH = join(__dirname, '..', 'data', 'manifest.schema.json');
+
+export async function installCommand(repo, options) {
+  const installDir = options.dir || AGENTS_DIR;
+  const version = options.version || options.tag || null;
+  const branch = options.branch || null;
+  const noValidate = options['no-validate'] || false;
+  const noSymlink = options['no-symlink'] || false;
+
+  // Parse user/repo[/path]
+  const parts = repo.split('/');
+  if (parts.length < 2) {
+    console.error(chalk.red('❌ 无效格式。使用: agent install user/repo'));
+    console.error(chalk.gray('   可选: agent install user/repo#v1.0.0'));
+    console.error(chalk.gray('         agent install user/repo@main'));
+    process.exit(1);
+  }
+
+  const [user, repoName, ...subPath] = parts;
+  const fullName = `${user}/${repoName}`;
+  const targetDir = join(installDir, repoName);
+
+  console.log(chalk.blue(`📦 安装 ${chalk.bold(fullName)}`));
+
+  // ── Step 1: Pre-flight checks ──
+  if (existsSync(targetDir)) {
+    const answer = await ask(chalk.yellow(`  目录已存在: ${targetDir}\n  覆盖？[y/N] `));
+    if (answer.toLowerCase() !== 'y') {
+      console.log(chalk.yellow('  已取消'));
+      return;
+    }
+    rmSync(targetDir, { recursive: true, force: true });
+  }
+
+  if (!existsSync(installDir)) {
+    mkdirSync(installDir, { recursive: true });
+  }
+
+  // ── Step 2: Git clone ──
+  const gitUrl = `https://github.com/${fullName}.git`;
+  console.log(chalk.gray(`  git clone ${gitUrl}`));
+
+  try {
+    const cloneArgs = ['clone', '--depth', '1'];
+    if (branch) cloneArgs.push('--branch', branch);
+    if (version) cloneArgs.push('--branch', `v${version.replace(/^v/, '')}`);
+    cloneArgs.push(gitUrl, targetDir);
+
+    const result = spawnSync('git', cloneArgs, {
+      stdio: 'pipe',
+      timeout: 60000,
+      encoding: 'utf-8',
+    });
+
+    if (result.status !== 0) {
+      // Try shallow clone with specific ref as fallback
+      const fallback = spawnSync('git', [
+        'clone', '--depth', '1', '--single-branch',
+        ...(version || branch ? ['--branch', (version || branch).replace(/^v/, '')] : []),
+        gitUrl, targetDir
+      ], { stdio: 'pipe', timeout: 60000, encoding: 'utf-8' });
+
+      if (fallback.status !== 0) {
+        throw new Error(fallback.stderr?.split('\n')[0] || 'Clone failed');
+      }
+    }
+  } catch (err) {
+    console.error(chalk.red(`❌ 克隆失败: ${err.message}`));
+    cleanupFailedInstall(targetDir);
+    process.exit(1);
+  }
+
+  // ── Step 3: Parse manifest ──
+  const manifestPath = findManifest(targetDir);
+  let manifest = null;
+  let installError = null;
+
+  if (!manifestPath) {
+    installError = `未找到 agent.json/agent.yaml 文件`;
+    console.log(chalk.yellow(`  ⚠ ${installError}`));
+  } else {
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+      console.log(chalk.green(`  ✓ 找到 Manifest: ${basename(manifestPath)}`));
+
+      // ── Step 4: Validate against schema ──
+      if (!noValidate) {
+        const valid = await validateManifest(manifestPath, manifest);
+        if (!valid) {
+          console.log(chalk.yellow('  ⚠ Manifest 校验有警告（继续安装）'));
+        } else {
+          console.log(chalk.green('  ✓ Schema 校验通过'));
+        }
+      }
+
+      // ── Step 5: Check dependencies ──
+      if (manifest.dependencies?.skills?.length) {
+        console.log(chalk.blue('  🔗 检查依赖...'));
+        const depsOk = await resolveDependencies(manifest.dependencies.skills, installDir);
+        if (!depsOk) {
+          console.log(chalk.yellow('  ⚠ 部分依赖未满足（继续安装）'));
+        }
+      }
+
+      // ── Step 6: Run lifecycle hooks ──
+      if (manifest.lifecycle?.on_install) {
+        console.log(chalk.blue('  🎣 执行安装钩子...'));
+        await runLifecycleHook(targetDir, manifest.lifecycle.on_install, 'on_install');
+      }
+
+      // ── Step 7: Store version info ──
+      manifest._installed_version = manifest.version;
+      manifest._installed_commit = getCommitHash(targetDir);
+
+    } catch (err) {
+      installError = err.message;
+      console.log(chalk.yellow(`  ⚠ Manifest 解析失败: ${err.message}`));
+    }
+  }
+
+  // ── Step 8: Register via symlink (for OpenClaw) ──
+  if (!noSymlink && manifest) {
+    try {
+      const skillsDir = getSkillsDir();
+      if (skillsDir) {
+        const linkPath = join(skillsDir, repoName);
+        if (!existsSync(linkPath)) {
+          symlinkSync(targetDir, linkPath, 'dir');
+          console.log(chalk.green(`  ✓ 已注册到 OpenClaw: ${linkPath}`));
+        } else {
+          console.log(chalk.gray(`  - OpenClaw 目录中已存在 ${repoName}（跳过）`));
+        }
+      }
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠ 注册 symlink 失败: ${err.message}`));
+    }
+  }
+
+  // ── Step 9: Register in local config ──
+  registerSkill(repoName, fullName, targetDir, manifest, version || branch || 'main', installError);
+
+  // ── Summary ──
+  console.log('');
+  if (installError && !manifest) {
+    console.log(chalk.yellow(`⚠ ${fullName} 已下载到: ${targetDir}`));
+    console.log(chalk.gray('  但未找到有效的 agent.json，请手动配置'));
+  } else {
+    console.log(chalk.green(`✅ ${chalk.bold(repoName)} v${manifest?.version || '?'} 安装成功！`));
+    console.log(chalk.gray(`   路径: ${targetDir}`));
+    console.log(chalk.gray(`   命令: agent info ${repoName}`));
+    console.log(chalk.gray(`        agent update`));
+    if (manifest?.lifecycle?.health_check) {
+      console.log(chalk.gray(`   健康检查已注册（每 ${manifest.lifecycle.health_check.interval_seconds}s）`));
+    }
+  }
+}
+
+// ─── Helpers ───
+
+function findManifest(dir) {
+  // Look in root, then .agent/
+  const patterns = [
+    join(dir, 'agent.json'),
+    join(dir, 'agent.yaml'),
+    join(dir, 'agent.yml'),
+    join(dir, '.agent', 'manifest.json'),
+    join(dir, '.agent', 'manifest.yaml'),
+  ];
+  for (const p of patterns) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+async function validateManifest(manifestPath, manifest) {
+  // Try Ajv validation
+  try {
+    const { default: Ajv } = await import('ajv');
+    const addFormats = (await import('ajv-formats')).default;
+    const ajv = new Ajv({ strict: false });
+    addFormats(ajv);
+
+    if (existsSync(SCHEMA_PATH)) {
+      const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf-8'));
+      const validate = ajv.compile(schema);
+      const valid = validate(manifest);
+      if (!valid) {
+        console.log(chalk.yellow('  校验问题:'));
+        validate.errors.slice(0, 3).forEach(e => {
+          console.log(chalk.gray(`    ${e.instancePath} ${e.message}`));
+        });
+        return false;
+      }
+      return true;
+    }
+  } catch {}
+  return true; // Skip if schema not available
+}
+
+async function resolveDependencies(deps, installDir) {
+  let allOk = true;
+  const config = loadConfig();
+
+  for (const dep of deps) {
+    const existing = Object.entries(config.installed || {})
+      .find(([_, s]) => s.id === dep.id);
+
+    if (existing) {
+      console.log(chalk.gray(`    ✓ ${dep.id}（已安装 v${existing[1].version})`));
+      continue;
+    }
+
+    if (dep.optional) {
+      console.log(chalk.gray(`    - ${dep.id}（可选，跳过）`));
+      continue;
+    }
+
+    console.log(chalk.yellow(`    ⚠ ${dep.id}（未安装）`));
+    allOk = false;
+  }
+
+  return allOk;
+}
+
+async function runLifecycleHook(targetDir, hook, hookName) {
+  if (!hook) return;
+
+  const { default: chalk } = await import('chalk');
+
+  if (hook.requires_approval) {
+    const answer = await ask(chalk.yellow(`  安装需要执行: ${hook.description || hookName}\n  确认执行？[y/N] `));
+    if (answer.toLowerCase() !== 'y') {
+      console.log(chalk.gray(`  跳过 ${hookName} 钩子`));
+      return;
+    }
+  }
+
+  try {
+    if (hook.command) {
+      const result = spawnSync(hook.command, {
+        cwd: targetDir,
+        shell: true,
+        timeout: hook.timeout_ms || 30000,
+        stdio: 'pipe',
+        encoding: 'utf-8',
+      });
+      if (result.status !== 0) {
+        console.log(chalk.yellow(`  ⚠ ${hookName} 钩子返回非零: ${result.stderr?.slice(0, 200)}`));
+      }
+    } else if (hook.url) {
+      // Webhook / HTTP hook — note only
+      console.log(chalk.gray(`  ${hookName}: webhook 配置为 ${hook.url}`));
+    }
+  } catch (err) {
+    console.log(chalk.yellow(`  ⚠ ${hookName} 执行失败: ${err.message}`));
+  }
+}
+
+function getCommitHash(dir) {
+  try {
+    const result = spawnSync('git', ['rev-parse', '--short', 'HEAD'], {
+      cwd: dir, stdio: 'pipe', encoding: 'utf-8', timeout: 5000,
+    });
+    return result.stdout?.trim() || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function getSkillsDir() {
+  // Look for OpenClaw skills directory in standard locations
+  const candidates = [
+    join(homedir(), '.openclaw', 'workspace', 'skills'),
+    join(homedir(), '.agents'),
+    join(homedir(), 'skills'),
+  ];
+  for (const dir of candidates) {
+    if (existsSync(dir)) return dir;
+  }
+  return null;
+}
+
+function registerSkill(name, fullName, dir, manifest, ref, error) {
+  const config = loadConfig();
+  if (!config.installed) config.installed = {};
+
+  config.installed[name] = {
+    id: manifest?.id || `${fullName.replace('/', '.')}`,
+    name: manifest?.name || name,
+    repo: fullName,
+    dir,
+    ref,
+    version: manifest?.version || '0.1.0',
+    capabilities: (manifest?.capabilities || []).map(c => c.id),
+    tag_count: (manifest?.tags || []).length,
+    installed_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    install_error: error || null,
+  };
+
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function cleanupFailedInstall(dir) {
+  try {
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  } catch {}
+}
+
+function ask(query) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(query, answer => {
+    rl.close();
+    resolve(answer);
+  }));
+}

package/bin/commands/list.js

@@ -0,0 +1,62 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import chalk from 'chalk';
+
+const AGENTS_DIR = join(homedir(), '.agents');
+const CONFIG_PATH = join(AGENTS_DIR, '.agent-config.json');
+
+export async function listCommand(options) {
+  const asJson = options.json || false;
+
+  if (!existsSync(CONFIG_PATH)) {
+    console.log(chalk.yellow('  尚未安装任何 Skill。'));
+    console.log(chalk.gray('  使用 agent search <query> 查找 Skill，然后用 agent install <repo> 安装'));
+    return;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    console.log(chalk.red('❌ 配置文件损坏'));
+    process.exit(1);
+  }
+
+  const installed = config.installed || {};
+  const names = Object.keys(installed);
+
+  if (names.length === 0) {
+    console.log(chalk.yellow('  尚未安装任何 Skill。'));
+    return;
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(installed, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(`📋 已安装的 Skill (${names.length})：`));
+  console.log();
+
+  for (const [i, name] of names.entries()) {
+    const skill = installed[name];
+    const manifestPath = join(skill.dir, 'agent.json');
+    let displayName = name;
+    let desc = '';
+
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+        displayName = manifest.name || name;
+        const caps = manifest.capabilities || [];
+        desc = `${caps.length} 个能力`;
+      } catch {}
+    }
+
+    const date = new Date(skill.installed_at).toLocaleDateString('zh-CN');
+    console.log(`  ${chalk.cyan(String(i + 1).padStart(2, ' '))}. ${chalk.bold(displayName)}`);
+    console.log(`     ${chalk.gray(`仓库: ${skill.repo}  |  安装: ${date}  |  ${desc}`)}`);
+    console.log();
+  }
+}