126 lines
3.6 KiB
Markdown
126 lines
3.6 KiB
Markdown
# template-skill
|
||
|
||
新 skill 的基础模版，内置认证、遥测回调、CI/CD 注册流程。
|
||
|
||
---
|
||
|
||
## 认证机制：auth-cli.ts
|
||
|
||
每个 skill 内置一份 `src/auth-cli.ts`，通过 subprocess 调用 `auth-rt` 二进制完成认证，**零 npm 依赖**。
|
||
|
||
```
|
||
skill/scripts/run.ts
|
||
→ createSkillClient().session()
|
||
→ auth-cli.ts spawnSync auth-rt
|
||
→ auth-rt 读取 ~/.openclaw/.env (CLIENT_KEY)
|
||
→ 返回 { accessToken, hookUrl, hookToken, ... }
|
||
```
|
||
|
||
### 使用方式
|
||
|
||
```typescript
|
||
import { createSkillClient } from './auth-cli.ts';
|
||
|
||
const client = createSkillClient({ dryRun: false });
|
||
const session = await client.session();
|
||
// session = { accessToken, hookUrl, hookToken, ... }
|
||
|
||
const res = await client.post('/ecom/your/endpoint', { param: 'value' });
|
||
// res = { status: 200, body: '...' }
|
||
```
|
||
|
||
### 前置条件
|
||
|
||
每台运行 skill 的机器需安装 `auth-rt`（`install.sh` 自动处理）：
|
||
|
||
```bash
|
||
# 手动安装
|
||
bash install.sh
|
||
|
||
# 或确保 ~/.openclaw/.env 中配置
|
||
CLIENT_KEY=sk_xxxx
|
||
```
|
||
|
||
---
|
||
|
||
## 遥测与可观测性：Hook 回调
|
||
|
||
`scripts/run.ts` 在每次 skill 执行后，**自动**向 auth server 下发的 `hookUrl` 发送结构化执行报告。
|
||
|
||
### 工作原理
|
||
|
||
```
|
||
Client 执行 skill
|
||
│
|
||
├─ 1. auth-rt session → auth gateway 返回 { hookUrl, hookToken }
|
||
├─ 2. 执行命令
|
||
└─ 3. POST hookUrl (fire-and-forget，不阻塞输出)
|
||
{
|
||
skill: "my-skill",
|
||
command: "run",
|
||
status: "success" | "failed",
|
||
durationMs: 1234,
|
||
error: "..." (仅失败时)
|
||
}
|
||
↓
|
||
服务端 → Loki → Grafana
|
||
```
|
||
|
||
### 特性
|
||
|
||
- **服务端控制**：`hookUrl` 由 auth server 在 session 时下发，客户端无需任何配置
|
||
- **非阻塞**：fire-and-forget，hook 失败不影响 skill 正常执行和输出
|
||
- **dry-run 跳过**：`--dry-run` 模式下不发送 hook
|
||
- **统一入口**：所有遥测逻辑在 `scripts/run.ts` 中，`src/index.ts` 保持纯业务逻辑
|
||
|
||
### 服务端可查询内容
|
||
|
||
| 维度 | Loki label / 字段 |
|
||
|------|-----------------|
|
||
| 哪个客户端调用了哪个 skill | `CLIENT_KEY` → session → hook |
|
||
| 成功率 / 失败率 | `status` |
|
||
| 响应耗时 | `durationMs` |
|
||
| 错误类型分布 | `error` |
|
||
| 命令维度拆分 | `command` |
|
||
|
||
---
|
||
|
||
## 新建 Skill 检查清单
|
||
|
||
1. 从此模版创建仓库（Forgejo → Use this template）
|
||
2. `package.json` 中修改 `name` 字段
|
||
3. `scripts/run.ts` 中修改 `SKILL_NAME` 常量
|
||
4. `SKILL.md` 中更新 `name` / `description` frontmatter
|
||
5. `src/index.ts` 中实现业务逻辑
|
||
6. **不要** 在 `package.json` 中添加 `@clawd/auth-runtime` 依赖
|
||
7. 推送 `v*` tag 触发 CI/CD 自动注册 skill
|
||
|
||
---
|
||
|
||
## CI/CD：自动注册
|
||
|
||
`.forgejo/workflows/register-skill-release.yml` 在推送 `v*` tag 时触发，调用 `shared-actions/register-skill` 将 skill 注册到平台。
|
||
|
||
```bash
|
||
# 发布新版本
|
||
git tag v1.0.0 && git push origin v1.0.0
|
||
```
|
||
|
||
注册所需的 `CLIENT_KEY` 通过 Forgejo 仓库 Secret 配置，skill 代码中不包含任何密钥。
|
||
|
||
---
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
.forgejo/workflows/ # CI/CD：tag 触发自动注册
|
||
scripts/run.ts # CLI 入口：参数解析 + session + 遥测 hook
|
||
src/
|
||
auth-cli.ts # auth-rt 薄 wrapper（勿修改）
|
||
index.ts # 业务逻辑入口
|
||
types.ts # 类型定义
|
||
SKILL.md # skill 元数据（frontmatter）+ Claude 使用说明
|
||
.env.example # 环境变量模版
|
||
install.sh # 依赖安装（含 auth-rt 自动下载）
|
||
```
|