Prototypes

实验性 mini-project 集散地：快速验证的想法就地保存在仓库根目录 prototypes/<name>/，随仓库一起提交，不影响主站的构建、格式化与 lint 流程。列表事实来源为仓库内 prototypes/README.md，本页保持同步；点击链接在新标签页打开 GitHub 目录。

Overview

Prototype	Category	Status	Created
ali-oss-client	Object Storage	🟢 Working	2026-08-01
prototype-example	Others	🟡 Experimental	2026-08-01
go-cli-urfave	Utilities	🟢 Working	2026-08-03
supabase-storage-client	Object Storage	🟢 Working	2026-08-04
r2-client	Object Storage	🟢 Working	2026-08-05
protomaps-map-view	Maps	🟢 Working	2026-08-07
etl-dbt	ETL	🟢 Working	2026-08-26
pg-boss-demo	Job Queue	🟢 Working	2026-08-30

状态：🟡 Experimental（实验性，随时变化）· 🟢 Working（已验证可用）· ⏸️ Shelved（搁置）· ✅ Done（完成）· 🗑️ Abandoned（废弃）

Object Storage

相关文档：对象存储基本用法 · 挂载 Bucket（FUSE Mount） · 供应商对比 · 签名 URL（Signed URL）

ali-oss-client

TypeScript 原型，用官方 ali-oss SDK（pnpm 管理）演示阿里云 OSS 基本用法。

环境变量配置（密钥不入代码）
列 bucket / 对象
上传、下载
生成签名 URL（GET 下载 / PUT 上传）
删除对象（demo 对象自动清理）
README 含基本的阿里云 OSS 配置步骤（RAM 用户 + AccessKey、建 bucket、region/endpoint、.env.dev.local）
Source

supabase-storage-client

TypeScript 原型，用官方 @supabase/supabase-js SDK（pnpm 管理）在本地测试 Supabase Storage 基本用法。

自带 supabase/ 项目配置（supabase init，storage 默认开启），实现零配置本地运行
anon key 未配置时自动从 supabase status -o env 读取
列 bucket、建私有 bucket
列对象、上传（upsert）、下载
签名 URL（GET 下载 / PUT 上传）、公开 URL
删除对象（demo 对象自动清理；bucket 仅当本次运行创建时才删除，已有 bucket 保留）
Source

r2-client

TypeScript 原型，用 S3 兼容 AWS SDK v3（@aws-sdk/client-s3 + @aws-sdk/s3-request-presigner，pnpm 管理）演示 Cloudflare R2 基本用法。

环境变量配置（密钥不入代码）
列 bucket、建 bucket（私有，缺失时自动创建）、列对象
上传、下载
预签名 URL（GET 下载 / PUT 上传）
删除对象（demo 对象自动清理；bucket 仅当本次运行创建时才删除）
README 含测试环境准备（Cloudflare 账号 + 付费方式、R2 API Token、.env.dev.local）
本地 MinIO（S3 兼容，Docker）测试：minio:start / minio:stop / minio:clean-volumes / minio:clean-images，无需 Cloudflare 账号即可跑通；Console 管理界面 http://127.0.0.1:9001
Source

Job Queue

pg-boss-demo

NestJS 12 + pg-boss 12 的 Job Queue 原型（pnpm 管理）：pg-boss 封装为 NestJS Service（DI / Config / Logger，配置从 @nestjs/config 读入），REST API 布置任务、查询状态与结果，演示队列执行、并行控制、重试、状态/结果查询等日常用法。

三个演示队列（handler 注册表驱动，1 类型 = 1 队列）：echo（立即完成并存结果）/ flaky（随机失败演示重试，retryLimit/retryBackoff）/ slow （sleep 演示并发，localConcurrency 控制每队列并行数）
REST API：POST /jobs、GET /jobs?queue=&state=、GET /jobs/:id、 POST /jobs/:id/cancel|retry、GET /queues、GET /health； Swagger UI /api/docs
handler 为 @Injectable() 类，经 DI 容器解析（ModuleRef.get），构造函数可注入其它 service（演示 NotificationService）
单测（NestJS Test.createTestingModule + useValue mock，无 DB）+ e2e （真实 Postgres，随机端口，跑完只删除自己创建的任务，实测 0 残留）
Postgres 18 用 docker compose 启动（pnpm db:start，schema 由 pg-boss 自动迁移）； @pg-boss/dashboard 调试面板（pnpm dashboard，http://localhost:3001）
状态 Working：端到端已验证（布置三类任务、状态流转、重试、结果查询）
Source

ETL

etl-dbt

Python 原型：dbt-core + DuckDB 的最小调用链演示（无服务器、无容器）， CSV 源数据 → seed → 单个 staging 视图转换。

源数据：seeds/test_data.csv 10 条固定订单记录（无随机），dbt seed 直接载入
唯一转换模型 stg_test_data（视图）：过滤 cancelled、新增计算列 line_total
测试两层：schema.yml 通用测试（unique / not_null）+ 两个 singular 测试（断言无 cancelled 泄漏、断言 line_total = qty * unit_price 重算一致）
完整调用链演示：seed → run → test → build → compile，编译产物可审查真实 SQL
工程化：uv run poe fmt（sqlfmt 格式化 dbt Jinja SQL + mdformat）、poe fmt-check
uv 管理：Python 3.13，dbt-core 1.12.3 / dbt-duckdb 1.11.0 / DuckDB 1.5.5
Source

Utilities

go-cli-urfave

Go CLI 原型，用 urfave/cli v3 框架（官方文档 https://cli.urfave.org/）写的命令行程序，已从 v2 迁移至 v3。

根命令 greet：全局 --name / -n 参数（默认 World）与根 Action
子命令：hello / bye（bye 带别名 b；hello 不加 h 别名以避免与内建 help 冲突）
嵌套命令：team add <name> --role <role> / team remove <name>，演示二级命令树、局部参数与位置参数（缺参、多余参数、未知命令或空 --name 时报错并退出码 2）
Justfile：just build / run / fmt / vet / test / clean
VS Code 调试：自带 .vscode/launch.json（Go/Delve），README 含调试说明
原为研究 Lux 时在 research/experiments/ 下的实验代码，已迁移至此
go.sum 纳入版本控制，保证依赖可复现构建
Source

Others

prototype-example

最小 Rust hello-world 示例，用于验证原型机制的完整流程（不是实际功能原型）。

证明非 Python 工具链项目可以干净地放在 prototypes/ 下
不影响 MkDocs 构建、ruff / mdformat 格式化与 lint
Source

Maps

相关文档：Protomaps 自建底图研究

protomaps-map-view

React + Vite + TypeScript 原型：在本地 Protomaps 底图上的通用地图组件 （MapLibre GL JS + pmtiles 协议 + @protomaps/basemaps 完整样式，pnpm 管理）。

本地瓦片：gitignored .cache/pmtiles/（VITE_PMTILES_DIR/FILE 配置），vite 内联插件在 dev/preview 同源挂载（HTTP Range 字节读取，无 CORS、无额外服务）
通用 MapView：中心/缩放、中心 HUD、导航控件、marker（emoji 或圆点 + 标签 + 弹窗）、轨迹线图层、事件 props（onClick/onMove/onZoom/onIdle）、运行时底图切换（多 pmtiles，换 URL 重建地图、换坐标移动相机）
架构拆分：src/lib/map/（MapController + basemap + layers + hooks，框架无关）
glyphs 本地化：.cache/glyphs/ + scripts/warm-glyphs.ts 预热（支持 protomaps / maplibre 双源，后者含 CJK 真字形）
可嵌入 widget：createMapWidget() 纯 HTML 直接可用（pnpm build:widget， pmtiles/glyphs 作为参数），examples/embed.html 示例；分发不走 npm （直接 copy 产物，或 js/css + 瓦片 + 字体一起发 S3）
已知限制：官方字体无 CJK（pnpm warm:glyphs --source=maplibre 可解）； maplibre 固定 v5（v6 与 pmtiles 协议不兼容，见 README Known issue）
Source

Backlinks (4)

flowchart LR
  n0["AI"]
  n1["Database"]
  n2["Dev Tools"]
  n3["Emoji"]
  n4["Frontend"]
  n5["Game Dev"]
  n6["Collection"]
  n7["Languages"]
  n8["Maps"]
  n9["Media"]
  n10["Monitor"]
  n11["Study Materials"]
  n12["Plans"]
  n13["Storage"]
  n14["Knowledge"]
  n15["Cloud"]
  n16["对象存储基本用法（Bucket / Object / 常用操作）"]
  n17["对象存储数据迁移（R2 → MinIO / 跨厂商搬迁）"]
  n18["Object Storage"]
  n19["挂载 Bucket 为本地文件系统（FUSE Mount）"]
  n20["对象存储签名 URL（Signed URL）原理与实战"]
  n21["对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"]
  n22["Infrastructure"]
  n23["Prototypes"]
  n24["Research"]
  n25["Better Auth 源码阅读指南"]
  n26["DuckDB 环境与基本使用"]
  n27["DuckDB 实战研究"]
  n28["DuckDB 模拟数据"]
  n29["PostgreSQL 数据用 DuckDB 加速查询"]
  n30["Hollow Knight 英语主题"]
  n31["英语学习 Dashboard"]
  n32["English Scraps Archive"]
  n33["English Scraps 使用指南"]
  n34["Jellyfin 源码阅读指南"]
  n35["Lux 资料整理"]
  n36["Nest Commander 学习资料"]
  n37["NestJS 源码阅读指南"]
  n38["Protomaps 自建底图研究"]
  n39["自制 PMTiles 地图（最简单例子）"]
  n40["MapLibre 集成 Protomaps"]
  n41["PMTiles 格式与工具链"]
  n42["上海地区底图项目"]
  n43["Redash 源码阅读指南"]
  n44["Rust 学习计划"]
  n45["shadcn/ui 进阶使用"]
  n46["shadcn/ui 组件添加与基本使用"]
  n47["shadcn/ui 实用研究（从环境到基本使用）"]
  n48["shadcn/ui 环境与初始化"]
  n49["TRIP 项目核心原理与代码阅读指南"]
  n1 --> n27
  n1 --> n29
  n4 --> n47
  n6 --> n0
  n6 --> n1
  n6 --> n2
  n6 --> n3
  n6 --> n4
  n6 --> n5
  n6 --> n7
  n6 --> n8
  n6 --> n9
  n6 --> n10
  n6 --> n11
  n6 --> n12
  n6 --> n13
  n6 --> n24
  n14 --> n22
  n15 --> n18
  n16 --> n17
  n16 --> n20
  n16 --> n21
  n16 --> n23
  n17 --> n16
  n17 --> n19
  n17 --> n20
  n17 --> n21
  n18 --> n16
  n18 --> n17
  n18 --> n19
  n18 --> n20
  n18 --> n21
  n19 --> n16
  n19 --> n20
  n19 --> n21
  n20 --> n23
  n21 --> n16
  n21 --> n17
  n21 --> n20
  n21 --> n23
  n22 --> n15
  n23 --> n16
  n23 --> n19
  n23 --> n20
  n23 --> n21
  n23 --> n38
  n24 --> n25
  n24 --> n27
  n24 --> n31
  n24 --> n34
  n24 --> n35
  n24 --> n36
  n24 --> n37
  n24 --> n38
  n24 --> n43
  n24 --> n44
  n24 --> n47
  n24 --> n49
  n26 --> n28
  n27 --> n1
  n27 --> n24
  n27 --> n26
  n27 --> n28
  n27 --> n29
  n28 --> n26
  n28 --> n29
  n29 --> n27
  n29 --> n28
  n30 --> n33
  n31 --> n30
  n31 --> n32
  n31 --> n33
  n33 --> n31
  n33 --> n32
  n38 --> n8
  n38 --> n39
  n38 --> n40
  n38 --> n41
  n38 --> n42
  n39 --> n41
  n40 --> n23
  n40 --> n42
  n41 --> n39
  n41 --> n42
  n42 --> n40
  n42 --> n41
  n45 --> n46
  n46 --> n45
  n46 --> n48
  n47 --> n4
  n47 --> n24
  n47 --> n45
  n47 --> n46
  n47 --> n48
  n48 --> n46
  click n0 "../collection/ai/" "AI"
  click n1 "../collection/database/" "Database"
  click n2 "../collection/dev-tools/" "Dev Tools"
  click n3 "../collection/emoji/" "Emoji"
  click n4 "../collection/frontend/" "Frontend"
  click n5 "../collection/game-dev/" "Game Dev"
  click n6 "../collection/" "Collection"
  click n7 "../collection/languages/" "Languages"
  click n8 "../collection/maps/" "Maps"
  click n9 "../collection/media/" "Media"
  click n10 "../collection/monitor/" "Monitor"
  click n11 "../collection/reading/" "Study Materials"
  click n12 "../collection/scraps/plans/" "Plans"
  click n13 "../collection/storage/" "Storage"
  click n14 "../knowledge/" "Knowledge"
  click n15 "../knowledge/infrastructure/cloud/" "Cloud"
  click n16 "../knowledge/infrastructure/cloud/object-storage/basic-usage/" "对象存储基本用法（Bucket / Object / 常用操作）"
  click n17 "../knowledge/infrastructure/cloud/object-storage/data-migration/" "对象存储数据迁移（R2 → MinIO / 跨厂商搬迁）"
  click n18 "../knowledge/infrastructure/cloud/object-storage/" "Object Storage"
  click n19 "../knowledge/infrastructure/cloud/object-storage/mount-bucket/" "挂载 Bucket 为本地文件系统（FUSE Mount）"
  click n20 "../knowledge/infrastructure/cloud/object-storage/signed-url/" "对象存储签名 URL（Signed URL）原理与实战"
  click n21 "../knowledge/infrastructure/cloud/object-storage/vendors-comparison/" "对象存储供应商对比（S3 / R2 / OSS / Supabase / MinIO）"
  click n22 "../knowledge/infrastructure/" "Infrastructure"
  click n23 "./" "Prototypes"
  click n24 "../research/" "Research"
  click n25 "../research/topics/better-auth/" "Better Auth 源码阅读指南"
  click n26 "../research/topics/duckdb/basic-usage/" "DuckDB 环境与基本使用"
  click n27 "../research/topics/duckdb/" "DuckDB 实战研究"
  click n28 "../research/topics/duckdb/mock-data/" "DuckDB 模拟数据"
  click n29 "../research/topics/duckdb/postgresql-acceleration/" "PostgreSQL 数据用 DuckDB 加速查询"
  click n30 "../research/topics/english/hollow-knight/" "Hollow Knight 英语主题"
  click n31 "../research/topics/english/" "英语学习 Dashboard"
  click n32 "../research/topics/english/scraps/archive/" "English Scraps Archive"
  click n33 "../research/topics/english/scraps/" "English Scraps 使用指南"
  click n34 "../research/topics/jellyfin/" "Jellyfin 源码阅读指南"
  click n35 "../research/topics/lux/" "Lux 资料整理"
  click n36 "../research/topics/nest-commander/" "Nest Commander 学习资料"
  click n37 "../research/topics/nestjs/" "NestJS 源码阅读指南"
  click n38 "../research/topics/protomaps/" "Protomaps 自建底图研究"
  click n39 "../research/topics/protomaps/make-own-map/" "自制 PMTiles 地图（最简单例子）"
  click n40 "../research/topics/protomaps/maplibre/" "MapLibre 集成 Protomaps"
  click n41 "../research/topics/protomaps/pmtiles/" "PMTiles 格式与工具链"
  click n42 "../research/topics/protomaps/shanghai-map/" "上海地区底图项目"
  click n43 "../research/topics/redash/" "Redash 源码阅读指南"
  click n44 "../research/topics/rust/" "Rust 学习计划"
  click n45 "../research/topics/shadcn-ui/advanced/" "shadcn/ui 进阶使用"
  click n46 "../research/topics/shadcn-ui/components/" "shadcn/ui 组件添加与基本使用"
  click n47 "../research/topics/shadcn-ui/" "shadcn/ui 实用研究（从环境到基本使用）"
  click n48 "../research/topics/shadcn-ui/setup/" "shadcn/ui 环境与初始化"
  click n49 "../research/topics/trip/" "TRIP 项目核心原理与代码阅读指南"

Links (5)