Zhe

整理短链接、想法和待办，把零散信息放进可查找的个人工作台。

站点 · English

这是什么

Zhe 是个人链接与信息管理应用。它可以收藏网页、生成短链接、记录 Markdown 想法、整理层级待办，并通过统一搜索找回内容。Web 管理台使用 Google 登录，短链接可直接分享给其他人。

仓库包含 Next.js 应用、处理跳转与数据库代理的 Cloudflare Worker，以及面向 zhe.to 的命令行客户端。数据按登录用户查询；自行部署需要配置身份认证和存储服务。

功能

• 创建和编辑短链接，设置自定义 slug、过期时间、备注、文件夹与标签；在 Inbox 逐项整理未分类链接。
• 查看点击记录与来源、地区等统计；边缘 Worker 优先读取 KV，未命中时查询源站并回填缓存。
• 撰写和搜索 Markdown 想法，使用标签归类；通过 API 或 CLI 新建和更新想法。
• 用层级列表管理待办，设置日期、标签、图标、完成状态，并移动或排序条目。
• 使用 Cmd/Ctrl + K 搜索链接、想法和待办，直接进入对应内容。
• 上传文件到 R2，生成公开文件地址或临时分享；管理存储、导入导出数据，并接入 Backy 备份。
• 在 AI 设置中配置供应商、模型和密钥，为链接生成文件夹与标签建议，由用户确认后应用。
• 通过 Webhook URL 直接收藏网页；创建带权限范围的 API Key，供 REST API 与 CLI 使用。
• 照常保存 X 链接，由 CLI 内置的本机 Connector 自动补全正文、作者、图片和视频；归档媒体纳入现有 R2 存储管理和连锁删除。
• 由同一个 Connector 为缺少预览图的普通网页补全 4:3 高清 WebP 截图，存入 R2 并通过 CDN 显示；与 X、GitHub 补全轮换串行执行。
• 按特殊来源筛选书签，在独立 GitHub 收藏中查看 Connector 采集的 stars、默认分支 commit 数、分类标签和 README 全文。

使用

访问 zhe.to，使用获准的 Google 账号登录。创建链接时填写目标网址，可选择文件夹、标签、slug 和有效期；想法与待办在侧栏单独管理。

需要命令行操作时，先在管理台的 API Keys 页面生成具有所需权限的密钥：

npm install -g @nocoo/zhe
zhe login
zhe create https://example.com/article --slug reading
zhe list
zhe idea list

CLI 将密钥保存在 ~/.config/zhe/config.json，当前 API 地址固定为 https://zhe.to/api/v1。登录验证需要链接读取权限；创建或修改内容还需要相应写入权限。更多命令见 CLI README 和 zhe --help。

开启 X 自动补全时，为同一个 CLI 密钥选择 links:read 和 connector:write，本机安装 OpenCLI 浏览器扩展、登录 X，并安装 FFmpeg，然后运行 zhe connector start（macOS）或 zhe connector watch。OpenCLI 随 CLI 安装，无需另一个 Connector 账号或 LLM；API Key 默认永久有效，创建时可选 30、7、3、1 天，Connector 与普通 API 使用同一有效期。详见 X 书签与 Connector。

开发

需要 Bun、Node.js ≥ 22.16；运行本地端到端测试还需要 PATH 中的 Wrangler、FFmpeg 和 ffprobe。根应用、Worker 和 CLI 各自维护依赖：

git clone https://github.com/nocoo/zhe.git
cd zhe
bun install --frozen-lockfile
bun install --cwd worker --frozen-lockfile
bun install --cwd cli --frozen-lockfile
cp .env.example .env.local

先准备自己的 Google OAuth 应用及已初始化的 D1 数据库，按 Worker 配置模板配置 D1、KV 和源站。Next.js 当前通过 Worker 代理访问 D1；仅填写 Cloudflare REST API 凭据不足以运行数据库查询。

配置	用途
AUTH_SECRET、AUTH_GOOGLE_ID、AUTH_GOOGLE_SECRET	Auth.js 与 Google 登录；本地回调为 http://localhost:7006/api/auth/callback/google
D1_PROXY_URL、D1_PROXY_SECRET	Next.js 访问 Worker 的 D1 代理
AUTH_ALLOWED_EMAILS	逗号分隔的登录邮箱名单；为空时允许任何完成 Google 登录的账号
R2_*	文件上传所需的端点、bucket、凭据、公开域名与用户路径盐值
CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN、CLOUDFLARE_KV_NAMESPACE_ID	源站写入 KV；未配置时跳过这些缓存写入
WORKER_SECRET	源站与 Worker 之间的统计、清理和缓存同步认证
TRUSTED_ORIGINS、PUBLIC_ORIGIN	反向代理环境下的可信主机与公开地址

Worker 使用 DB、LINKS_KV 绑定及 ORIGIN_URL、WORKER_SECRET、D1_PROXY_SECRET。它每半小时触发临时文件清理与有变更时的 KV 补偿同步。首次部署需核对数据库 schema和迁移文件；历史迁移包含手工建表后的差异，本地测试初始化脚本会补齐这些差异，不应直接用作生产安装器。

bun run dev
bun run lint
bun run typecheck
bun run build
bun run start

bun run dev opens the local Demo/E2E/Prod launcher on port 7006 through https://zhe.dev.hexly.ai. Demo is the default; --mode e2e starts switchable manual E2E. bun run demo:reset resets stopped, owned Demo fixtures. bun run start serves the configured production bundle on 7006. See environment commands.

测试

测试层	从仓库根目录执行
单元与组件测试	bun run test:unit
应用集成测试	bun run test:integration
API 端到端测试	bun run test:api
浏览器端到端测试	bun run test:e2e:pw
Worker 单元测试	bun run --cwd worker test
CLI 单元测试	bun run --cwd cli test

Install browser engines with bunx playwright install chromium webkit. API and browser runners use app ports 17006 and 27006, allocate native Wrangler D1/KV/R2 ports, and own .test-storage/runs/<uuid>. Builds and evidence are per-run. No remote test credentials are required; launchers generate fixture credentials and issue normal Auth.js sessions. This does not certify real Google OAuth. See local environments for lifecycle and evidence.

技术栈

部分	实现
Web 与界面	Next.js、React、TypeScript、Tailwind CSS、Basalt
登录与数据	Auth.js / Google OAuth、Cloudflare D1、Drizzle schema
跳转与文件	Cloudflare Workers、KV、R2、S3 API
可选 AI	Vercel AI SDK、@nocoo/next-ai
CLI 与测试	Bun、@nocoo/base-cli、Vitest、Testing Library、Playwright、Biome

文档

• 想法功能
• 待办功能
• 统一搜索
• AI 链接整理建议
• X 书签与 Connector
• Mainland Douyin and Instagram Media Connectors (proposed)
• 特殊来源与 GitHub 收藏
• 网页预览图补全
• Eagle 图片旁路
• Backy 集成
• CLI 使用

许可证

仓库当前未提供根目录许可证文件；CLI 的包元数据声明为 MIT。