内容
# HSpace — 发送给一个人，而不是所有人。
> English | [简体中文](README.zh-CN.md)
**登录:** https://hspace.zhanjian.space · **API / OpenAPI:** https://html-share.kzhan.workers.dev/openapi.json
**适用于使用AI构建的开发者：** 将刚刚编写的HTML演示文稿或Markdown文档Cursor / Claude Code生成的演示文稿，转化为**链接 + 密码**，发送给团队成员和客户：查看谁打开了它，任何时候都可以撤销，迭代更新内容而不改变链接。匿名发布，安全分享。
## 不只是另一个HTML托管服务
常规托管服务（tiiny.host / Netlify Drop / Pages）都竞争于**公开链接**——上传，获取URL，发送到全世界。HSpace则相反：
- **默认私有，非公开。** 每次发布都会生成一个随机密码；链接和密码一起出现在剪贴板上。没有密码，无法访问。永不被索引，安全防止转发——链接是您控制的资产，如果发送错误，可以撤销。
- **完成的内容，而非网站或协作编辑。** 您分享*一个查看的内容*——演示文稿、报告、提案、数据可视化。无需多文件，无需构建，无需配置——只需“发送”。
- **为AI编码工作流而构建。** 内容源自编辑器和AI聊天；分享也应在这些场景中进行——从编辑器一键分享，今天还可以从聊天中发布（MCP）。
一句话总结：**其他人“发布到全世界”，HSpace则实现定向分享。**
## 已发布功能（MVP上线）
- ✅ VS Code / Cursor 扩展：一键发布 `.html` / `.md`，自动生成4位密码，链接+密码复制
- ✅ 文档集合：右键文件夹 / 多选 → 批量md/html变为一个链接 + 密码 + 索引页，支持跨文档导航
- ✅ MCP服务器：直接在Claude / Cursor对话中发布（单个 + 集合）
- ✅ Claude Code插件：`/plugin marketplace add agentx1boss/hspace` → `/plugin install hspace@hspace` → `/share`（捆绑MCP服务器）
- ✅ 查看回执：查看面板中每个链接的查看次数（`GET /pages/:slug/stats`）
- ✅ 逐人链接：一个链接，每个用户一个单独的密码，个人统计数据，单独撤销（`/pages/:slug/grants`）
- ✅ 内容版本控制：链接保持不变，内容迭代更新；历史记录 + 回滚
- ✅ 密码门：边缘验证 + 签名cookie（24小时），防暴力破解
- ✅ OpenAPI + 第一方边缘分析；CI/CD（推送 → 部署，标签 → 双市场发布）
```
hspace/
├── backend/ Cloudflare Worker（发布API + 子域名服务 + 密码门）
├── vscode-extension/ VS Code / Cursor 扩展
├── mcp-server/ MCP服务器（从AI聊天中发布）
├── clients/ Claude Code插件（/share命令 + 捆绑MCP配置）
├── docs/ 定位、商业模式、设计与运维文档
├── assets/ 品牌资产（应用图标 / 收藏图标 / 锁定图标 / OG卡片）
└── .github/workflows/ CI（部署后端 / 发布扩展）
```
架构：内容隔离在通配符子域名（`<slug>.zhanjian.space`，与API域名分开）；元数据存储在D1；HTML/MD存储在R2；速率限制计数器存储在KV；密码通过边缘门 + 签名cookie实现——完全无服务器。
## 自主托管
前提：Cloudflare账户 + Cloudflare域名（用于内容通配符子域名）。
```bash
cd backend
npm install
npx wrangler r2 bucket create html-share-pages
npx wrangler d1 create html-share # 将database_id放入wrangler.toml
npx wrangler kv namespace create RATELIMIT # 将id放入wrangler.toml
npx wrangler d1 execute html-share --remote --file=./schema.sql
npx wrangler secret put COOKIE_SIGNING_SECRET
# 编辑wrangler.toml：通配符路由、USERCONTENT_DOMAIN、资源id、限制
npm run deploy
```
DNS：在内容域名上添加通配符记录（`*` → 任意IP，橙色云代理）；Worker路由接管。API可以直接使用workers.dev地址。设置仓库秘密`CLOUDFLARE_API_TOKEN`，将`backend/**`推送到main分支会自动部署。
## 扩展（开发中）
```bash
cd vscode-extension
npm install && npm run compile # 然后在VS Code中按F5启动扩展开发主机
```
自主托管时，将`hspace.apiBaseUrl`设置指向您的API。发布：增加`package.json`版本 → 推送`v<version>`标签 → CI发布到VS Code市场 + Open VSX。
## API
机器可读的**OpenAPI 3规范**位于[`/openapi.json`](https://html-share.kzhan.workers.dev/openapi.json)（`servers.url`根据请求来源自动填充，因此自主托管实例也适用）。将其放入GPT Actions、代理框架或函数调用中。
| 方法 | 路径 | 备注 | 认证 |
|---|---|---|---|
| POST | `/publish` | 发布（`html`或`markdown`，或`files`用于集合） | 可选Bearer |
| PATCH | `/pages/:slug` | 更新内容（版本）/ 密码 / 过期时间 | Bearer或`X-Edit-Token` |
| DELETE | `/pages/:slug` | 删除（链接失效） | Bearer或`X-Edit-Token` |
| GET | `/pages/:slug/stats` · `/versions` · `/grants` | 回执、版本、逐人链接 | Bearer或`X-Edit-Token` |
匿名与登录（`wrangler.toml`中的阈值）。匿名用户权限故意限制较轻，以便重度/严肃用户有理由登录（免费）：匿名用户 ≤ 512 KB，≤ 3天（一次性，无续期），≤ 3个文档/集合，20/小时 & 50/天，必须保持密码，**且不支持逐人链接或版本历史**。登录用户 ≤ 2 MB，每个期限最多30天（可续期），50个文档集合，支持逐人链接、版本历史/回滚，无每日限制。**每个链接都会过期——没有永久链接**（续期前请勿过期；废弃后会自动清理）。匿名用户唯一不变的是：大约30秒内发布单个草稿，无需注册。
## 法律与运维
隐私政策 `/privacy`，服务条款 `/terms`，报告 `/report`。报告发送到D1 `reports`；下架 = 设置 `pages.status` 为 `blocked`（页面立即404）。参见 [docs/operations.md](docs/operations.md)。
## 安全注意事项
`isSuspicious` / `isPhishy` 是基于规则的扫描（混淆执行、密码输入、外部表单）；在扩大规模之前，请连接专业的扫描器。密码使用PBKDF2（Workers原生）派生；内容通过HTTPS发送，并在R2上存储（静息时未加密）。请联系：mengmajiang@gmail.com。
## License
MIT
