智能体操作指南

# ZBWD Skills Hub 智能体操作指南

本指南面向 Codex、Hermes 和其他能够操作本机文件与终端的智能体。Hub 是唯一服务端入口；不要寻找 `codex-skills-hub` 项目目录，不要 clone Skill Git 仓库，也不要索要 SSH 密钥或 Hub Token。

## 1. 发现 Hub 能力

```bash
HUB="http://192.168.10.50:3010"
curl -fsSL "$HUB/.well-known/zbwd-skills-hub.json"
curl -fsSL "$HUB/api/health"
```

只有 `writeReady=true` 时才能上传或更新。上传身份来自 Hub 登录会话，不能通过命令行传入或伪造维护人 ID、姓名。

## 2. 下载并校验独立客户端

```bash
HUB="http://192.168.10.50:3010"
CLIENT="${TMPDIR:-/tmp}/zbwd-skill.mjs"
curl -fsSL "$HUB/client/zbwd-skill.mjs" -o "$CLIENT"
curl -fsSL "$HUB/client/zbwd-skill.mjs.sha256" -o "$CLIENT.sha256"
cd "$(dirname "$CLIENT")"
if command -v sha256sum >/dev/null 2>&1; then sha256sum -c "$CLIENT.sha256"; else shasum -a 256 -c "$CLIENT.sha256"; fi
```

客户端只依赖 Node.js 18 或更高版本，不依赖 Hub 项目、第三方 npm 包、Git 或 SSH。

## 3. 注册或登录账号

网页和独立客户端使用同一账号体系。注册时用户输入姓名和密码，Hub 自动生成 `user-...` ID；建议保存该 ID 用于精确识别账号，但登录时可直接使用姓名或系统 ID。网页登录只用于网页操作；每台电脑上的独立客户端首次上传时，还需用同一账号登录一次，之后会话会复用，不再反复询问姓名、ID 或密码。密码只用于登录，不会被保存到 Skill、Git 或审计记录。

```bash
export ZBWD_SKILLS_HUB_PASSWORD='用户自己输入的密码'
node "$CLIENT" register --hub-url "$HUB" --name "你的姓名"
# 输出的 user-... ID 建议保存，用于精确识别账号。

node "$CLIENT" login --hub-url "$HUB" --account "你的姓名"
# 也可使用：--user-id "user-系统生成的 ID"（兼容旧命令）
node "$CLIENT" profile
```

客户端会把可过期登录会话以 `0600` 权限保存到 `~/.config/zbwd-skills-hub/session.json`。创建 Skill 时原作者自动使用当前登录用户；更新已有 Skill 默认保留原作者，当前登录用户只记为本次操作人。作者转移必须明确确认后追加 `--transfer-author`。

如果同名贡献者曾使用旧版自声明 ID，必须由管理员通过显式身份别名和迁移脚本归并到系统账号；普通上传智能体不得按姓名猜测、修改作者 ID 或重新注册同名账号。

## 4. 上传或更新 Skill

```bash
node "$CLIENT" upload \
  --hub-url "$HUB" \
  --skill-dir "/absolute/path/to/skill" \
  --bucket general \
  --agent codex
```

新 Skill 默认所有用户可用。只有系统用户上传时可以、并且必须明确选择使用权限：

```bash
# 所有用户可发现、同步和安装
node "$CLIENT" upload --hub-url "$HUB" --skill-dir "/absolute/path/to/skill" --bucket general --agent codex --access all

# 仅管理员和系统用户可发现、同步和安装
node "$CLIENT" upload --hub-url "$HUB" --skill-dir "/absolute/path/to/skill" --bucket general --agent codex --access admin
```

普通用户和管理员不能用 `--access` 修改权限。旧客户端或直接调用 API 更新已有 Skill 时，未显式传入权限会保留原权限；当前独立客户端和管理页面生成给系统用户的上传提示词都会要求先选择“所有用户”或“仅管理员”。

客户端和服务端都会校验 `SKILL.md`、中文 `hub.json`、文件数量与大小，并拒绝 `.env*`、`.git`、`node_modules`、构建产物、`.codex`、auth/session、缓存、依赖目录和符号链接。

- 新建 Skill：preview 校验通过后客户端自动 commit。
- 更新已有 Skill：客户端只展示 diff 和确认命令，必须先把 diff 呈现给用户并取得明确确认，再执行带 `--preview-id ... --confirm` 的命令。
- 不得把首次上传命令擅自追加 `--confirm`，也不得重新生成一个未经用户查看的 preview。

成功结果必须包含 `validationStatus=valid`、`operationId`、Git revision、原作者、维护人和 `auditRecorded=true`。

## 5. 同步 Skill

精准同步单个 Skill：

```bash
node "$CLIENT" sync --hub-url "$HUB" --bucket agentx --only agentx-deployment --agent codex --dry-run
node "$CLIENT" sync --hub-url "$HUB" --bucket agentx --only agentx-deployment --agent codex
```

同步整个 bucket：

```bash
node "$CLIENT" sync --hub-url "$HUB" --bucket general --agent codex --dry-run
node "$CLIENT" sync --hub-url "$HUB" --bucket general --agent codex
```

同步客户端会复用当前设备上匹配 Hub 的登录会话。匿名用户和普通用户只能看到并同步 `access=all` 的 Skill；管理员和系统用户登录后才可以看到、下载和安装 `access=admin` 的 Skill。服务端会同时保护列表、详情、JSON package 和 tar archive，不能通过手工拼接下载地址绕过。

`--agent codex` 可使用 Codex 目标目录自动探测，顺序是 `CODEX_SKILLS_DIR`、`$CODEX_HOME/skills`、现有 `~/.codex/skills`，新设备默认创建 `~/.agents/skills`。

Hermes 或通用智能体不得使用上述 Codex 自动探测。执行智能体必须先根据自身官方文档、配置或运行时上下文确认它实际加载 Skill 的根目录，再用绝对路径显式传入 `--target`：

```bash
AGENT_SKILLS_DIR="/absolute/path/to/current-agent/skills"
node "$CLIENT" sync --hub-url "$HUB" --bucket general --only example-skill --agent generic-agent --target "$AGENT_SKILLS_DIR" --dry-run
node "$CLIENT" sync --hub-url "$HUB" --bucket general --only example-skill --agent generic-agent --target "$AGENT_SKILLS_DIR"
```

如果 Hermes 或通用智能体省略 `--target`，或目标位于 Codex Skill 目录，客户端必须拒绝执行。无法确认自身 Skill 根目录时应暂停并询问用户，不能猜测或把 Skill 安装到 Codex 后声称已为当前智能体安装。同步完成后，核对输出中的 `agent`、`target` 和每个 `destination`，再提醒用户在实际目标智能体中 reload skills 或重启。

## 6. 没有 Node.js 时的 curl + tar 回退

状态检查不需要 Node.js：

```bash
curl -fsSL "$HUB/api/health"
```

精准同步一个已经发布的 Skill：

```bash
BUCKET="agentx"
SKILL="agentx-deployment"
TARGET="${CODEX_SKILLS_DIR:-$HOME/.agents/skills}/$SKILL"
mkdir -p "$TARGET"
curl -fsSL "$HUB/api/v2/skills/$SKILL/archive?bucket=$BUCKET" | tar -xzf - -C "$TARGET"
```

curl + tar 回退只适用于所有用户可用的 Skill。仅管理员 Skill 必须由已登录的独立客户端携带会话同步。上传必须使用独立客户端或直接实现 v2 multipart preview/commit 协议，不能绕过 preview、中文说明、安全校验和替换确认。

## 7. 权限边界

普通智能体只能在已登录用户身份下维护已有 bucket 中、且自己有权访问的 Skill。系统用户可在上传时选择 Skill 使用权限；管理员和系统用户可使用仅管理员 Skill。Bucket 创建、Bucket 删除、服务部署、Git 仓库修复、Skill 权限设置和作者转移不包含在普通上传指令中。