STABLE REFERENCE WORKFLOW

ShortRef

稳定引用工作流

把普通 URL 转换为可长期维护的稳定引用。WorkBuddy 是用户入口，ShortRef Skill 提供交互与生命周期管理能力，ShortRef Worker 作为公开只读后端完成引用解析。

已投入使用

ARCHITECTURE

入口、控制层与后端各司其职

ShortRef 将自然语言交互、本地管理与公开解析明确分层。用户不需要直接操作 KV 或 Worker；公开 Worker 也不承担写入和管理职责。

主要交互入口

接收用户关于创建、修改、停用、启用、查看、验证或同步引用的自然语言请求，并调用 ShortRef Skill。

调用：ShortRef Skill →

交互能力与本地控制层

整理参数、规范化 URL、生成确定性 ID、维护完整本地记录，并通过 Cloudflare REST API 向 Workers KV 写入最小映射。

写入：Local Records + KV →

只读解析后端

读取 Workers KV 中已经创建的引用。有效且 active 的记录使用 HTTP 302 跳转；不存在、停用或异常记录统一返回 404。

输出：302 Redirect / 404

创建与管理链路经 WorkBuddy → Skill → Cloudflare API 完成；实际访问稳定引用时，浏览器直接进入 ShortRef Worker，不需要再次经过 WorkBuddy。

REFERENCE LIFECYCLE

ShortRef 的重点不是把 URL 变短，而是把引用身份与当前目标地址解耦。相同规范化 URL 重复创建会复用同一 ID；后续目标地址变化也不要求重新生成引用。

URL 经保守规范化后使用 SHA-256 + Base62 生成确定性 ID。默认取前 8 位，发生冲突时逐步扩展至 12 位。

目标 URL 可以更新，但引用 ID 不变。已有文档、笔记或文章中的稳定引用无需跟随目标迁移而修改。

停用后保留引用身份与完整历史，公开访问返回 404；重新启用后恢复同一个 ID 的解析能力。

本地记录作为管理依据，可以验证本地状态与 KV 最小映射是否一致，并在明确确认后同步修复。

DATA & SECURITY BOUNDARY

ShortRef 把管理数据与公开解析数据分开保存，减少 Cloudflare 侧的数据暴露和写入面。

{ "version": 1, "url": "...", "status": "active" }

Worker 在代码层面只读，不提供公开写接口、管理后台或公开 API Token。

Cloudflare Token 不进入 Skill、Git、Markdown 或配置文件，而从本地环境变量读取。写入权限只交给本地 ShortRef 管理链路。

有效引用使用 302（Found）而不是 301。稳定的是引用 ID，而不是它此刻指向的目标地址。