@keepclaw/skill-sdk

Keep Agent Skill 与 CLI 的共享运行时。提供五块能力：

1. 凭证存取（~/.keepai/.env，权限 0600，env 与 file 两级兜底）
2. MCP 客户端（包装官方 @modelcontextprotocol/sdk，自动翻译错误码）
3. MCP exec 桥（mcp-cli + keep-mcp bin，给不支持原生 MCP 的 runtime 用）
4. 安装 / 调用埋点（统一上报 endpoint）
5. 统一错误类型（KeepError + ErrorCodes）

安装

npm install @keepclaw/skill-sdk

使用

凭证

const {
  hasValidToken, loadCredentials,
  persistCredentials, clearCredentials,
  persistMcpUrl, clearMcpUrl,
  resolveEnvPath, decodeJwtExp,
} = require("@keepclaw/skill-sdk/auth");

if (!hasValidToken()) {
  // ... run login flow
  persistCredentials({ token: "<jwt>" });  // 自动解码 exp，0600 写入 ~/.keepai/.env
}

const { token, exp, mcpUrl } = loadCredentials();  // 读取顺序：env > file

安装时同步 MCP URL（供 postinstall 使用）：

const { syncMcpUrl } = require("@keepclaw/skill-sdk/auth");
const { DEFAULT_MCP_URL } = require("@keepclaw/skill-sdk/mcp");

// postinstall 场景：读 KEEP_MCP_URL 或 fallback 到默认值
const url = process.env.KEEP_MCP_URL || DEFAULT_MCP_URL;
const { changed, tokenCleared } = syncMcpUrl({ url });
// changed=false → URL 未变，幂等
// changed=true, tokenCleared=false → 首次写入，token 保留
// changed=true, tokenCleared=true  → URL 切换，旧 token 已清除，需重新登录

MCP 客户端

const { McpClient } = require("@keepclaw/skill-sdk/mcp");
const { KeepError, ErrorCodes } = require("@keepclaw/skill-sdk/errors");

const client = new McpClient({
  url: "https://mcp.gotokeep.com/skills-mcp-gateway-page/v1",
  token: process.env.keep_auth_token,
});

try {
  const tools = await client.listTools();
  const result = await client.callTool("record_tool", { text: "午餐吃了..." });
  console.log(result);
} catch (err) {
  if (err instanceof KeepError && err.code === ErrorCodes.AUTH_REQUIRED) {
    // 引导重新登录
  }
} finally {
  await client.close();
}

callTool 的返回值：

• 工具 isError=false：返回已解析的 structured content / text payload（JSON 对象）
• 工具 isError=true：抛 KeepError(code, message, { retryAfter, data })
• 协议层异常（网络、反序列化）：抛 KeepError(PROTOCOL_ERROR | TRANSPORT_ERROR, ...)

MCP exec 桥（给 OpenClaw / Hermes 这类不支持原生 MCP 的 runtime）

# 随包附带的 bin
npx keep-mcp --list
npx keep-mcp record_tool '{"text":"午餐"}'

# 或在自己的 skill 脚本里 shim 一下（保持 exec 命令模板稳定）
#   scripts/mcp-call.js:
#     require("@keepclaw/skill-sdk/mcp-cli").runCli();

约定：

• stdout 单行 JSON envelope：{ok:true, data} / {ok:false, error:{code, message}}
• 退出码：0 成功 / 1 业务错误 / 2 用法错误 / 3 网络协议错误 / 4 鉴权错误
• 自动从 env / ~/.keepai/.env 读凭证并注入 Authorization header
• KEEP_MCP_URL / KEEP_MCP_TIMEOUT_MS 可覆盖默认值（默认 60s，适配 record_tool 的偶发长耗时）

也可以程序化调用：

const { runBridge } = require("@keepclaw/skill-sdk/mcp-cli");
const { envelope, exitCode } = await runBridge(["--list"]);

错误码

const { KeepError, ErrorCodes } = require("@keepclaw/skill-sdk/errors");
// AUTH_REQUIRED / TOKEN_EXPIRED / QRCODE_EXPIRED / RATE_LIMITED /
// MEDIA_TOO_LARGE / MEDIA_TYPE_NOT_ALLOWED / UPSTREAM_ERROR /
// INVALID_PARAM / TRANSPORT_ERROR / PROTOCOL_ERROR

埋点

const { reportInstall, reportInvoke } = require("@keepclaw/skill-sdk/telemetry");

// postinstall
await reportInstall({ skillName: "keep-record", version: "1.1.0", source: "web" });

// 业务调用（默认上报；KEEP_TELEMETRY=0 等可关闭）
await reportInvoke({ tool: "record_tool", ok: true, durationMs: 120 });

环境变量

| 变量 | 说明 | |------|------| | keep_auth_token | JWT | | keep_auth_token_expired | Unix 过期时间 | | keep_username | 登录用户名（登录成功后写入，便于排查） | | KEEP_MCP_URL | MCP server 地址。安装时传入则由 postinstall 持久化到 ~/.keepai/.env（同名 key）；运行时传入则临时覆盖文件值，优先级更高。 | | KEEP_TELEMETRY | 调用埋点，默认开启；0 / false / off / no 关闭 | | KEEP_TELEMETRY_URL | 自定义埋点上报地址 | | KEEP_INVOKE_SOURCE | 仅 mcp-cli（exec 桥）调用 reportInvoke 时作为 JSON 的 source；未设时视为 mcp-skill-exec；@keepclaw/keep-record 的 scripts/mcp-call.js 默认 keep-record；与独立 keep CLI 的 keep-cli 区分 |

许可

MIT