开发第一个 Clip

Clip 是用 TypeScript 编写的。用 @pinixai/core SDK 定义命令，pinix daemon 负责运行。

前置条件

已安装并启动 pinix daemon
Bun（安装 Pinix 时已自动安装）

创建 Clip

初始化项目

mkdir my-clip && cd my-clip
bun init -y
bun add @pinixai/core

创建 clip.json

{
  "name": "@yourscope/my-clip",
  "version": "0.1.0",
  "description": "我的第一个 Clip",
  "main": "src/index.ts"
}

编写 Clip

创建 src/index.ts：

import { Clip } from "@pinixai/core";

const clip = new Clip({
  name: "@yourscope/my-clip",
  description: "我的第一个 Clip",
});

clip.command("hello", {
  description: "Say hello",
  input: {
    name: { type: "string", description: "Name to greet", required: true },
  },
  handler: async ({ input }) => {
    return { message: `Hello, ${input.name}!` };
  },
});

clip.run();

本地安装并测试

pinix hub add local/my-clip --path .
pinix invoke my-clip hello --name "World"
# → { "message": "Hello, World!" }

迭代开发

修改 src/index.ts 后，daemon 会自动重启 Clip 进程。直接再次调用即可测试。

项目结构

my-clip/
├── clip.json          # 包描述
├── src/
│   └── index.ts       # 入口文件
├── package.json       # 依赖
└── web/               # 可选：Web UI
    └── index.html

添加更多命令

clip.command("list", {
  description: "List all items",
  handler: async () => {
    const items = await db.getAll();
    return { items, total: items.length };
  },
});

clip.command("add", {
  description: "Add a new item",
  input: {
    title: { type: "string", required: true },
    priority: { type: "string", enum: ["low", "medium", "high"] },
  },
  handler: async ({ input }) => {
    const item = await db.create(input);
    return item;
  },
});

调用其他 Clip

你的 Clip 可以通过 Hub 调用其他已安装的 Clip：

import { invoke } from "@pinixai/core";

clip.command("research", {
  description: "Research a topic",
  input: {
    topic: { type: "string", required: true },
  },
  handler: async ({ input }) => {
    const results = await invoke("google", "search", {
      query: input.topic,
    });
    return { results };
  },
});

查看 Clip 信息

# 查看 Clip 的完整信息（命令、参数、版本等）
pinix hub info my-clip

# 查看所有命令
pinix invoke my-clip --help

# 查看单个命令的参数
pinix invoke my-clip hello --help

下一步

发布与共享 Clip
Clip 设计原则——如何设计让 Agent 更好用的 Clip
命令设计——命令命名、输入输出的最佳实践