template-skill/README.md

# 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 自动下载）
```