ShortRef 安装与设置

创建 Workers KV Namespace

1. 进入 Cloudflare 控制台。
2. 创建一个 Workers KV Namespace，例如 shortref。
3. 记录 Namespace ID，稍后 Worker binding 和本地 Skill 都需要使用。

填写 wrangler.jsonc

在仓库的 worker/wrangler.jsonc 中，把刚刚创建的 Namespace ID 写入 SHORTREF_KV：

"kv_namespaces": [
  {
    "binding": "SHORTREF_KV",
    "id": "YOUR_NAMESPACE_ID"
  }
]

连接 GitHub 仓库

1. Workers & Pages → Create application → Import a repository。
2. 选择 ShortRef 仓库。
3. Worker name 使用 shortref。
4. Production branch 使用 main。
5. Root directory 填 worker。
6. Build command 留空。
7. Deploy command 使用 npx wrangler deploy。

验证并绑定 Custom Domain

1. 部署完成后先打开 Cloudflare 分配的 *.workers.dev 地址。
2. 根路径应显示 ShortRef 服务页。
3. 不存在的引用应显示统一 404 页面。
4. 如需正式域名，在 Worker 的 Domains 中添加自己控制的 Custom Domain。

下载 ZIP

当前稳定版：

压缩包只包含通用 Skill 逻辑，不包含个人配置、Cloudflare Token 或私有引用数据。

在 WorkBuddy 中上传

1. 打开 WorkBuddy。
2. 进入“专家·技能·连接器”。
3. 进入“技能”。
4. 选择“添加技能” → “上传技能”。
5. 选择刚刚下载的 ZIP。
6. 安装后确认 shortref 出现在“我安装的”技能中并处于启用状态。

创建个人配置

可从 Skill 中的 templates/config.example.json 复制一份到自己的私有目录。例如：

{
  "version": 1,
  "base_url": "https://reference.example.com",
  "data_dir": "D:/ShortRefData",
  "cloudflare": {
    "account_id": "YOUR_ACCOUNT_ID",
    "namespace_id": "YOUR_NAMESPACE_ID",
    "api_token_env": "CLOUDFLARE_SHORTREF_TOKEN"
  },
  "hash": {
    "algorithm": "sha256-base62-v1",
    "initial_length": 8,
    "max_length": 12
  },
  "storage": {
    "backup_limit": 30
  }
}

把 reference.example.com 换成你的实际 Worker Custom Domain 或 workers.dev 地址。

创建专用 Cloudflare Token

1. 在 Cloudflare 创建专用 Account API Token。
2. 仅授予相关账户 Workers KV Storage Write 权限。
3. 不要使用 Global API Key。
4. Token 创建后立即保存；Cloudflare 不会再次显示完整 secret。

设置用户环境变量

推荐使用 Windows“编辑帐户的环境变量”界面，新建两个用户变量：

SHORTREF_CONFIG=D:\ShortRef\config.json
CLOUDFLARE_SHORTREF_TOKEN=你的 Cloudflare Token

也可以在 PowerShell 当前会话中临时测试：

$env:SHORTREF_CONFIG = "D:\ShortRef\config.json"
$env:CLOUDFLARE_SHORTREF_TOKEN = "your-token"

重新启动 WorkBuddy

环境变量是在 WorkBuddy 启动时继承的。设置完成后，请完全退出 WorkBuddy，再重新打开。

如果之后修改 Token 或 SHORTREF_CONFIG，同样需要重启 WorkBuddy。

创建或复用稳定引用

最直接的调用：

/ShortRef https://example.com/

WorkBuddy 会调用 ShortRef Skill：规范化 URL → 生成或复用确定性 ID → 保存本地记录 → 写入 KV → 返回稳定引用。

直接用自然语言管理

也可以直接告诉 WorkBuddy：

• “停用 MBkxkQep”
• “重新启用 MBkxkQep”
• “把 MBkxkQep 的目标地址改成……”
• “查看 MBkxkQep”
• “验证 ShortRef 本地记录与 KV 是否一致”