产品功能总览

产品功能总览

写写贴 (wpaste) 是一个面向 AI 代理和人类的精美 Markdown 文档托管平台。CLI 优先、18 套内置主题、可自托管。

本文档描述截至 2026-04-11 平台上已经上线的所有功能。

一、核心能力

1.1 Markdown 文档托管

  • 发布、读取、更新、删除文档
  • 支持 GFM（表格、删除线、任务列表）+ 代码高亮（highlight.js）
  • 前置 YAML frontmatter 自动解析（标题、标签、marp: true 自动识别等）
  • 文档限额按套餐：free 50 篇 / pro 5,000 篇 / team 50,000 篇
  • 单篇大小限额：free 5KB / pro 100KB / team 500KB
  • 私有 or 公开发布；公开文档通过 /d/{slug} 匿名访问

1.2 文档类型

doc_type用途
raw默认类型，AI 代理或人类直接发布的原始笔记
wikiwpaste compile 由原始笔记编译而来的结构化条目
indexcompile 产生的目录 / 索引页
answerwpaste ask --save 产生的问答文档
html静态站点（多文件，存 R2 / 本地 / S3）
slidesMarp 幻灯片，Markdown 存 D1，由 marp.wpaste.io 即时渲染
mirror自动翻译的镜像文档（只读）

二、主题系统（审美一等公民）

18 套内置主题：

8 套通用主题

  • github — 开发者标准（默认）
  • academic — 衬线学术
  • night-owl — 柔和深色
  • ink / 墨 — 水墨书法
  • terminal — 等宽黑客
  • notion — 干净宽松
  • craft — Apple 范
  • editorial — 杂志式长阅读

10 套国家主题

  • china — 水墨 + 朱砂
  • japan — 侘寂极简
  • korea — 丹青对称
  • france — Art Déco 优雅
  • britain — Racing Green + 羊皮纸
  • germany — Bauhaus 功能主义
  • italy — 文艺复兴暖调
  • usa — 大胆自信
  • brazil — 热带活力
  • india — 莫卧儿金

Free 用户可用：github / academic / night-owl / ink / terminal（5 套） Pro+ 用户可用：全部 18 套 + 自定义主题

自定义主题（Pro+）

  • 继承自任一内置主题
  • 通过 JSON 配置覆盖 CSS 变量（字体、颜色、间距、引号样式、分隔符样式等）
  • 支持 AI 按自然语言描述生成主题：POST /api/v1/themes/generate

三、CLI-first：wpaste 命令行

独立 npm 包 wpaste，以 ESM + commander + ink (TUI) 构建。

文档 CRUD

bash
wpaste publish file.md                          # 发布（按 title 幂等覆盖）
wpaste publish file.md --public --tags "a,b"
echo "# Hi" | wpaste publish                    # stdin
wpaste publish site/ --html                     # 整个目录作为静态站点
wpaste list --tag rust --after 2026-01-01
wpaste view <id>
wpaste open <id>                                # 浏览器打开
wpaste update <id> --title "新标题" --public
wpaste append <id> "追加内容"
wpaste delete <id>
wpaste move <ids...> --workspace <id>

搜索与整理

bash
wpaste search "关键词"                           # 全文搜索
wpaste tag add <id> "新标签"
wpaste workspace create "Engineering"
wpaste folder create <workspaceId> "Go"

AI 能力

bash
wpaste organize --preview                       # AI 自动归类未整理文档
wpaste compile --workspace <id>                 # raw → wiki 编译
wpaste ask "为什么 D1 不能用事务？" --save       # RAG 问答
wpaste lint                                     # 知识库健康检查
wpaste context --depth 2                        # 导出 KB 摘要给 LLM
wpaste mirror <id> --lang en                    # 生成英文/日文/中文镜像

其他

bash
wpaste auth --token <token> --server <url>      # 认证
wpaste whoami
wpaste image <file>                             # 上传图片（Pro+）
wpaste daily --append "今日新发现"              # 追加到今日日志
wpaste ui                                       # 进入 ink TUI
wpaste install-skills                           # 安装 Claude Code 插件

配置

  • ~/.wpaste/config.json 持久化 token + server
  • 环境变量覆盖：WPASTE_TOKEN / WPASTE_SERVER
  • 支持 HTTP/HTTPS 代理（HTTPS_PROXY / ALL_PROXY）

四、Claude Code 插件

cli/claude-plugin/ 是一个 Claude Code 插件，提供 7 个 skill：

Skill触发场景
wpaste-publish保存分析 / 总结 / 任何要归档的内容
wpaste-save保存 Claude 的分析结果到 KB
wpaste-search搜索 KB 中已有内容
wpaste-ask带引用的 KB 问答
wpaste-compile把原始笔记编译为 wiki
wpaste-context加载 KB 概览到对话上下文
wpaste-daily追加到今日日志

用户运行 wpaste install-skills 即可自动安装到 ~/.claude/plugins/。

五、AI 能力（可插拔）

多后端 Provider 抽象

lib/ai-provider.ts 统一接口，支持 4 种后端，运行时切换：

  • Workers AI（Cloudflare 边缘，默认）
  • OpenAI / 兼容 API（Azure / Together / Groq / OpenRouter）
  • Anthropic Claude
  • Ollama（本地）

BYOK（Bring Your Own Key）

用户可在 Dashboard → Settings 填自己的 API key：

  • AES-256-GCM 加密存 users.ai_api_key
  • 用户自带 key 时不消耗平台额度，也不受平台 rate limit 限制

模型按 plan 分级

  • free 用小模型：gpt-4o-mini / claude-haiku-4-5 / llama-3.2-3b
  • pro+ 用大模型：gpt-4o / claude-opus-4-6 / llama-3.1-70b
  • 支持 AI_MODEL_SMALL / AI_MODEL_LARGE 环境变量覆盖

异步 Job 流水线

为绕开 Workers CPU 时限，AI 任务拆成客户端轮询的多次请求：

POST /api/v1/{job}          → 创建 job
POST /api/v1/{job}/:id/process  → 执行一步（循环直到 ready）
POST /api/v1/{job}/:id/apply    → 落盘结果
GET  /api/v1/{job}/:id          → 查状态

四种 Job：

Job作用
compileraw 文档 → 结构化 wiki 文章 + 索引页 + 交叉引用
organize未整理文档 → 自动归类到 workspace / folder 的提案
askRAG 问答，返回带 *引用* 的答案
lint知识库健康检查（死链、重复、空文档、缺标签）

document_summaries 缓存按 content_hash 跳过重复 AI 调用，省钱加速。

六、知识组织

Workspaces（知识库）

  • 层级：user → workspace → folder → document
  • 可公开 / 私有
  • 访问等级：public / pro / premium
  • 支持付费订阅（workspace_subscriptions 表）
  • 可从官方模板创建（lib/workspace-templates.ts）

Folders

  • Workspace 内层级文件夹，支持嵌套（parent_id 自引用）
  • 文档可通过 sort_order 在 folder 内手动排序
  • 语法：*Title* 或 *Display Text*
  • 发布或更新文档时自动解析并写入 document_links 表
  • 阅读页显示"反向链接"（Linked from...）
  • 匹配规则：先精确匹配用户的文档 title，再尝试 lowercase
  • 断链以 {.wiki-link-broken} 样式渲染

Data Fragments（文档内交互块）

  • 在文档里嵌入投票、调查、进度条等交互组件
  • 状态存 document_fragments 表（≤16KB JSON + version 乐观并发）
  • 跨文档通过 iframe postMessage 通信

七、镜像（Mirror）✨

自动生成的外语文档副本。源文档更新，镜像自动重新翻译。

支持语言

  • 中文 (zh) — 简体中文
  • 英文 (en) — English
  • 日文 (ja) — 日本語

适用类型

仅对 Markdown 生效：raw / wiki / index / answer 不支持：html（静态站点）/ slides（幻灯片）

行为

  • 手动触发首次创建：wpaste mirror <id> --lang en
  • 源文档更新自动重生：PATCH 源文档后，所有镜像标记 stale 并后台重译
  • 镜像只读：PATCH 镜像文档返回 400，保证改动不会被重译覆盖
  • 代码块保护：fenced/inline code 被占位符替换，不参与翻译
  • H1 → title 同步：翻译后的第一个 # 自动同步到 documents.title
  • 级联删除：删除源文档时自动清理所有镜像

镜像内的 *Title* 在阅读页按当前镜像语言解析——若目标文档在同语言有镜像则链到镜像，否则回退到原文。语义统一，读者无感切换。

语言切换器

读者页显示 pill 切换器：语言 · Lang: 原文 · English · 日本語 · 简体中文

八、用户与社交

认证

  • GitHub OAuth（arctic 库 + HMAC 签名 session cookie，自实现）
  • API Token（wpaste_ 前缀 + nanoid(32) 熵，SHA-256 存库，只在创建时展示一次）
  • 双认证中间件：Bearer Token 优先，Session Cookie 兜底

套餐体系

特性freeproteam
文档上限505,00050,000
单文档大小5KB100KB500KB
API Token11050
Workspace220100
月阅读量1,00010,000无限
主题5 套全部 18 套全部
自定义 CSS❌✅✅
图片上传❌✅✅
AI organize 文档上限202,00010,000
AI compile 文档上限305005,000
AI ask 每日1050500

过期自动降级：plan_expires_at 过期后运行时自动按 free 套餐处理，DB 值保留方便续费。

用户社交

  • 用户主页：/u/{username} 或 {username}.wpaste.io（子域名路由）
  • 关注 / 粉丝：follows 表
  • 文档评论：公共文档评论区
  • Web Push 通知：push_subscriptions + VAPID
  • 系统通知中心：新文档 / 新评论 / 被关注者发文提醒

九、部署形态

形态 A：Cloudflare Workers（原始形态）

  • @opennextjs/cloudflare 打包 Next.js 到 Worker
  • D1 数据库 + R2 存储 + Workers AI
  • 辅助 Workers：
    • marp.wpaste.io — Marp 幻灯片即时渲染
    • static.wpaste.io — 静态站点回源
    • hn-scraper — HN TOP 20 定时抓取 + AI 总结

形态 B：Docker / VPS 自托管

  • next.config.ts 的 output: "standalone" 分支
  • 本地 SQLite（better-sqlite3 + WAL）
  • 本地文件系统 or S3 存储
  • 外部 AI provider（OpenAI / Anthropic / Ollama）

同一份源码支持两种形态，核心抽象：

工厂文件作用
getEnv()lib/cloudflare.ts统一环境变量
db()lib/db.tsD1 / better-sqlite3 切换
getStorageProvider()lib/storage-provider.tsR2 / 本地 FS / S3
getAIProvider()lib/ai-provider.tsWorkers AI / OpenAI / Anthropic / Ollama

十、对外接口

REST API（/api/v1/*）

文档 CRUD、workspace / folder 管理、搜索、AI Job、主题、图片、用户 / 社交、聊天、通知、镜像——详见 docs/api.md。

浏览器扩展

extension/ 目录下的 Chrome 扩展：选中网页内容 → 一键发布为 wpaste 文档（内部用 turndown.js 转 Markdown）。

Next.js Middleware

子域名路由：{username}.wpaste.io/ → rewrite 到 /u/{username}，保留系统子域名（www / static / marp / api 等）。

十一、开发者支持

技术 Wiki

docs/ 目录下 13 篇技术文档：架构 / 数据模型 / API / 认证 / AI / 存储 / CLI / 主题 / Workers / 部署 / 开发 / 镜像。

测试

  • vitest + v8 coverage
  • 202 个单元 + 集成测试
  • lib/ 核心模块 37% lines 覆盖，镜像相关 API 路由 100%
  • 集成测试用 :memory: SQLite + 注入 fake AI provider

Open Source

MIT 协议，代码仓库：github.com/imfht/writeandpaste

Comments (0)

No comments yet

imfht
imfht
April 10, 2026 · Updated April 11, 2026