feat: 新增 Hook 遥测回调 + 更新 README
scripts/run.ts 在每次 skill 执行后自动 POST hookUrl（由 auth server 下发）， 实现服务端可观测性，客户端零配置。README 补充遥测机制、新建 skill 流程说明。 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
8be28aab5a
commit
01fcb90505
128
README.md
128
README.md
|
|
@ -1,20 +1,19 @@
|
|||
# template-skill
|
||||
|
||||
新 skill 的基础模版。
|
||||
新 skill 的基础模版，内置认证、遥测回调、CI/CD 注册流程。
|
||||
|
||||
---
|
||||
|
||||
## 认证机制：auth-cli.ts
|
||||
|
||||
每个 skill 内置一份 `src/auth-cli.ts`，它是一个薄 wrapper，通过 subprocess 调用 `auth-rt` 二进制。
|
||||
|
||||
**不使用 npm 依赖**，auth-runtime 更新时只需重新编译二进制，不需要改动任何 skill。
|
||||
|
||||
### 工作原理
|
||||
每个 skill 内置一份 `src/auth-cli.ts`，通过 subprocess 调用 `auth-rt` 二进制完成认证，**零 npm 依赖**。
|
||||
|
||||
```
|
||||
skill/src/index.ts
|
||||
→ import { createSkillClient } from './auth-cli.ts'
|
||||
→ auth-cli.ts 通过 spawnSync 调用 auth-rt 二进制
|
||||
→ auth-rt 处理 token/session/request
|
||||
skill/scripts/run.ts
|
||||
→ createSkillClient().session()
|
||||
→ auth-cli.ts spawnSync auth-rt
|
||||
→ auth-rt 读取 ~/.openclaw/.env (CLIENT_KEY)
|
||||
→ 返回 { accessToken, hookUrl, hookToken, ... }
|
||||
```
|
||||
|
||||
### 使用方式
|
||||
|
|
@ -22,44 +21,105 @@ skill/src/index.ts
|
|||
```typescript
|
||||
import { createSkillClient } from './auth-cli.ts';
|
||||
|
||||
const client = createSkillClient({
|
||||
apiBase: process.env.API_BASE, // 可选
|
||||
dryRun: false, // 可选，dry-run 模式返回模拟数据
|
||||
});
|
||||
const client = createSkillClient({ dryRun: false });
|
||||
const session = await client.session();
|
||||
// session = { accessToken, hookUrl, hookToken, ... }
|
||||
|
||||
// API 调用
|
||||
const res = await client.post('/ecom/your/endpoint', { param: 'value' });
|
||||
// res = { status: 200, body: '...' }
|
||||
|
||||
// 获取 session
|
||||
const session = await client.session();
|
||||
// session = { accessToken: '...', expiresIn: 900 }
|
||||
```
|
||||
|
||||
### 前置条件
|
||||
|
||||
每台运行 skill 的机器上必须安装 `auth-rt` 二进制：
|
||||
每台运行 skill 的机器需安装 `auth-rt`（`install.sh` 自动处理）：
|
||||
|
||||
```bash
|
||||
git clone http://192.168.0.108:3030/agent-skills/auth-runtime.git ~/clawd/skills/auth-runtime
|
||||
cd ~/clawd/skills/auth-runtime && ./install.sh
|
||||
# 安装到 ~/.openclaw/bin/auth-rt
|
||||
# 手动安装
|
||||
bash install.sh
|
||||
|
||||
# 或确保 ~/.openclaw/.env 中配置
|
||||
CLIENT_KEY=sk_xxxx
|
||||
```
|
||||
|
||||
确保 `~/.openclaw/bin` 在 PATH 中，或通过 `AUTH_RT_BIN` 环境变量指定路径。
|
||||
---
|
||||
|
||||
### auth-runtime 更新流程
|
||||
## 遥测与可观测性：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 注册到平台。
|
||||
|
||||
auth-runtime 代码变更后：
|
||||
```bash
|
||||
cd ~/clawd/skills/auth-runtime && git pull && ./install.sh
|
||||
# 发布新版本
|
||||
git tag v1.0.0 && git push origin v1.0.0
|
||||
```
|
||||
重新编译即可，**无需改动任何 skill 代码**。
|
||||
|
||||
### 新建 skill 检查清单
|
||||
注册所需的 `CLIENT_KEY` 通过 Forgejo 仓库 Secret 配置，skill 代码中不包含任何密钥。
|
||||
|
||||
1. 从此模版创建仓库
|
||||
2. 确认 `src/auth-cli.ts` 已包含（直接从模版继承）
|
||||
3. `src/index.ts` 中 `import { createSkillClient } from './auth-cli.ts'`
|
||||
4. `package.json` 中 **不要** 添加 `@clawd/auth-runtime` 依赖
|
||||
5. `install.sh` 中包含 auth-rt 二进制检查
|
||||
---
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
.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 自动下载）
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
#!/usr/bin/env bun
|
||||
import type { Command } from '../src/index.ts';
|
||||
import { run } from '../src/index.ts';
|
||||
import { createSkillClient } from '../src/auth-cli.ts';
|
||||
|
||||
const SKILL_NAME = 'my-skill'; // TODO: replace with actual skill name
|
||||
|
||||
function printUsage(): void {
|
||||
console.error(`Usage:
|
||||
|
|
@ -9,10 +12,20 @@ function printUsage(): void {
|
|||
Commands:
|
||||
run <arg>
|
||||
|
||||
Config: ~/.openclaw/.env (API_BASE)
|
||||
Config: ~/.openclaw/.env (CLIENT_KEY)
|
||||
`);
|
||||
}
|
||||
|
||||
async function reportHook(
|
||||
hookUrl: string,
|
||||
hookToken: string | undefined,
|
||||
payload: object,
|
||||
): Promise<void> {
|
||||
const headers: Record<string, string> = { 'Content-Type': 'application/json' };
|
||||
if (hookToken) headers['Authorization'] = `Bearer ${hookToken}`;
|
||||
await fetch(hookUrl, { method: 'POST', headers, body: JSON.stringify(payload) });
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const positionals: string[] = [];
|
||||
let dryRun = false;
|
||||
|
|
@ -31,8 +44,51 @@ async function main(): Promise<void> {
|
|||
|
||||
if (positionals.length < 1) { printUsage(); process.exit(1); }
|
||||
|
||||
const result = await run(positionals[0] as Command, positionals.slice(1), dryRun);
|
||||
const command = positionals[0] as Command;
|
||||
|
||||
// Exchange CLIENT_KEY for session — gives us hookUrl for telemetry
|
||||
let hookUrl: string | undefined;
|
||||
let hookToken: string | undefined;
|
||||
try {
|
||||
const client = createSkillClient({ dryRun });
|
||||
const session = await client.session();
|
||||
hookUrl = session.hookUrl;
|
||||
hookToken = session.hookToken;
|
||||
} catch {
|
||||
// Auth failure is non-fatal for telemetry; skill still runs
|
||||
}
|
||||
|
||||
const startMs = Date.now();
|
||||
let result: Awaited<ReturnType<typeof run>>;
|
||||
|
||||
try {
|
||||
result = await run(command, positionals.slice(1), dryRun);
|
||||
} catch (err) {
|
||||
const error = err instanceof Error ? err.message : String(err);
|
||||
const failed = { status: 'failed' as const, command, dryRun, error };
|
||||
console.log(JSON.stringify(failed, null, 2));
|
||||
|
||||
if (hookUrl && !dryRun) {
|
||||
reportHook(hookUrl, hookToken, {
|
||||
skill: SKILL_NAME, command, status: 'failed',
|
||||
durationMs: Date.now() - startMs, error,
|
||||
}).catch(() => {});
|
||||
}
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
|
||||
// Fire-and-forget telemetry — never delays output
|
||||
if (hookUrl && !dryRun) {
|
||||
reportHook(hookUrl, hookToken, {
|
||||
skill: SKILL_NAME,
|
||||
command,
|
||||
status: result.status,
|
||||
durationMs: Date.now() - startMs,
|
||||
error: (result as any).error,
|
||||
}).catch(() => {});
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
|
|
|
|||
Loading…
Reference in New Issue