10 分钟开发一个效率插件：基于 `@ztools/declarative-ui` 与一键脚手架的极客插件开发指南

# 1. 克隆插件生态仓库并安装依赖
git clone https://github.com/ZToolsTeam/ZTools-extensions.git
cd ZTools-extensions
npm install

# 2. 一键生成标准声明式插件工程
npm run create-plugin github-repo-search

extensions/github-repo-search/
├── assets/
│   └── icon.png          # 插件矢量/高清图标
├── src/
│   └── index.tsx         # 声明式命令主入口
├── plugin.json           # 插件元数据、命令列表与权限清单
├── package.json          # 极简依赖声明 (仅开发期类型引用)
└── tsconfig.json         # TypeScript 严格模式配置

{
  "$schema": "../../packages/ztools-plugins-spec/schema/plugin.schema.json",
  "id": "github-repo-search",
  "name": "GitHub 仓库速查",
  "version": "1.0.0",
  "description": "实时检索 GitHub 开源仓库，支持右侧预览星标数据与一键复制 git clone 命令",
  "author": "your-github-id",
  "icon": "assets/icon.png",
  "targets": ["win32", "darwin", "linux"],
  "permissions": ["network", "clipboard"],
  "commands": [
    {
      "name": "search-repos",
      "title": "搜索 GitHub 仓库",
      "subtitle": "GitHub",
      "mode": "view",
      "keywords": ["gh", "github", "repo", "开源"]
    }
  ]
}

import React, { useState } from 'react';
import {
  List,
  ActionPanel,
  Action,
  Icon,
  Color,
  useFetch,
} from '@ztools/declarative-ui';

interface GithubRepo {
  id: number;
  full_name: string;
  description: string | null;
  stargazers_count: number;
  forks_count: number;
  language: string | null;
  html_url: string;
  clone_url: string;
  updated_at: string;
}

export default function SearchGithubReposCommand() {
  const [searchText, setSearchText] = useState('ztools');

  // 内置 useFetch Hook：自动处理防抖、AbortController 请求取消、加载态与本地缓存
  const { isLoading, data } = useFetch<{ items: GithubRepo[] }>(
    `https://api.github.com/search/repositories?q=${encodeURIComponent(searchText || 'stars:>10000')}&per_page=20`,
    { keepPreviousData: true }
  );

  const repos = data?.items ?? [];

  return (
    <List
      isLoading={isLoading}
      isShowingDetail={true}
      searchBarPlaceholder="输入关键字搜索 GitHub 仓库 (如 rust, electron, ztools)..."
      onSearchTextChange={setSearchText}
      throttle={true}
    >
      {repos.map((repo) => (
        <List.Item
          key={repo.id}
          icon={Icon.Code}
          title={repo.full_name}
          accessories={[
            { text: `★ ${repo.stargazers_count.toLocaleString()}`, icon: Icon.Star },
            ...(repo.language ? [{ tag: { value: repo.language, color: Color.SecondaryText } }] : []),
          ]}
          detail={
            <List.Item.Detail
              markdown={`## ${repo.full_name}\n\n${repo.description || '*暂无仓库描述*'}\n\n---\n\`\`\`bash\ngit clone ${repo.clone_url}\n\`\`\``}
              metadata={
                <List.Item.Detail.Metadata>
                  <List.Item.Detail.Metadata.Label title="Stars 星标数" text={String(repo.stargazers_count)} />
                  <List.Item.Detail.Metadata.Label title="Forks 派生数" text={String(repo.forks_count)} />
                  <List.Item.Detail.Metadata.Label title="主要语言" text={repo.language || 'Unknown'} />
                  <List.Item.Detail.Metadata.Separator />
                  <List.Item.Detail.Metadata.Link title="仓库主页" target={repo.html_url} text={repo.full_name} />
                </List.Item.Detail.Metadata>
              }
            />
          }
          actions={
            <ActionPanel>
              {/* 第 1 个 Action 自动绑定为 Enter 主动作 */}
              <Action.OpenInBrowser title="在浏览器中打开仓库" url={repo.html_url} />
              {/* 第 2 个 Action 自动绑定为 Ctrl/Cmd + Enter 次动作 */}
              <Action.CopyToClipboard
                title="复制 git clone 命令"
                content={`git clone ${repo.clone_url}`}
              />
              {/* 其余低频动作自动收纳进 Ctrl/Cmd + K 动作面板 */}
              <Action.CopyToClipboard
                title="复制仓库 URL"
                content={repo.html_url}
                shortcut={{ modifiers: ['ctrl', 'shift'], key: 'c' }}
              />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}

# 1. 编译当前声明式插件 (毫秒级 esbuild 打包)
node scripts/build-declarative.mjs github-repo-search

# 2. 运行 AST 安全扫描与 UI 规范 6 条红线自检
node scripts/verify-changed-plugins.mjs