From ac873a2bac7acd899101fbb5769678d024468d49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BF=AE=E9=9B=A8?= <47820304+PeterGuy326@users.noreply.github.com> Date: Sun, 20 Sep 2026 01:04:09 +0800 Subject: [PATCH 1/2] docs: add distribution strategy page with three doors --- CHANGELOG.md | 7 ++++ README.md | 3 +- docs/DISTRIBUTION.md | 85 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 docs/DISTRIBUTION.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c02077..3463d8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,13 @@ All notable changes to `doc` are documented here. ## [Unreleased] +### Added + +- Add `docs/DISTRIBUTION.md`: the three distribution doors (local single-player, gated + ByteFolk-hosted SaaS, guided self-hosting), their identity, cost, and compliance + boundaries, the authentication consistency principle across deployments, and the + guidance surfaces in `doc init`, README, and `doc doctor`. + ### Fixed - Persist like identity per viewer using a server-side `PubDocLike` table and cookie-based diff --git a/README.md b/README.md index 1494b2c..7ac81ae 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ 保留稳定的 API 与可追溯修改边界。 项目的北极星、边界与验收场景见 [GOAL.md](GOAL.md)，当前实现契约见 -[SPEC.md](SPEC.md)。 +[SPEC.md](SPEC.md)。分发形态与三扇门（本地单人 / ByteFolk 托管 SaaS / 引导式自部署） +见 [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)。 > [!WARNING] > `doc` 仍处于 experimental 阶段。接口、数据模型和部署方式可能变化，请勿把它 diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md new file mode 100644 index 0000000..50a8063 --- /dev/null +++ b/docs/DISTRIBUTION.md @@ -0,0 +1,85 @@ +# doc distribution + +`doc` 与 `mem` 的核心价值只在"别人也够得着"时成立：人与人共享文档、跨 Agent 共享记忆， +前提都是存在一个多人可达的部署。而默认状态下用户不会部署。因此产品显式提供三扇门， +并由 CLI 与文档引导用户选择其一，而不是把"部署"当作文档角落里的前提条件。 + +## The three doors + +| 门 | 给谁 | 身份与认证边界 | 成本与合规谁背 | 当前缺口 | +| ------------------------ | ---------------------------- | ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------ | +| 本地单人（现状默认） | 个人写作 + 与 AI 协作 | 回环自验（本地开发邮箱），不构成真实身份 | 无人背 | 文案诚实化：明确标注单人模式，不让用户误以为本地即共享 | +| ByteFolk 托管 SaaS | "登录就用"的用户 | ByteFolk 统一身份：GitHub 任意用户 + 邮箱 magic link；org 成员资格只 gating 我们自己人 | 我们：基础设施、运维、用户内容与个人信息保管、境内域名则备案 | 多租户隔离工程、隐私政策、最低付费基础设施；**门未开，见开启条件** | +| 引导式自部署（现阶段主推） | 有服务器或有合规要求的团队 | 部署者自定边界：他的 GitHub org、他的 SMTP、未来的 OIDC | 部署者：自己的服务器、域名、发信通道与数据合规 | 部署向导、一键模板、`doctor` 门位报告 | + +## Door 1: local single-player + +现状默认路径（`doc init` + `doc dev`）服务个人写作与 AI 协作。它必须被诚实标注为 +单人模式：本地邮件闭环（开发邮箱）只用于验证权限流程，不产生真实身份，也不产生 +人与人共享。任何界面与文档不得暗示本地运行即具备协作能力。 + +## Door 2: ByteFolk-hosted SaaS (gated) + +SaaS 默认不开。开启条件是需求信号：若干个团队明确表达"让我登录就用、我愿意付钱"。 +原因不是工程，而是责任：开了 SaaS 我们就从工具方变成数据保管方，用户文档落在我们 +盘上，个人信息保护、隐私政策、数据驻留随之而来。 + +开启前必须就绪： + +- 多租户隔离。当前实现是单租户部署形态，租户边界是工程前提而非配置项； +- 隐私政策与数据驻留说明； +- 最低付费基础设施。免费托管档（闲置休眠、限期数据库）只能承载试验，不能承载 + 真实用户数据； +- 统一身份落地：GitHub 任意用户 + 邮箱 magic link，org 成员资格仅用于我们自己的 + 管理面。 + +## Door 3: guided self-hosting (current main path) + +自部署就是产品定位本身：部署者控制数据库、对象存储、模型凭据和认证边界（见 +[GOAL.md](../GOAL.md)）。我们要做的是把这条路做顺： + +- 部署向导：生产拓扑（web + collaboration + PostgreSQL + HTTPS 反代）加 DNS、 + 发信、OAuth 逐项检查，把"还缺哪几样"变成机器可读的报告； +- 一键模板：容器平台 blueprint、永久免费虚拟机 runbook 等各一份，覆盖零成本试验 + 到正式落点； +- `doc doctor` 报告当前实例处于哪扇门、距离下一扇门还缺什么。 + +参考组合（runbook 维护细节）：零成本试验用免费托管加免费数据库，接受休眠与限期； +正式落点用整机虚拟机加自动 HTTPS 与免费域名解析，数据落在部署者自己盘上；升级 +路径为付费轻量服务器或 SaaS。 + +## mem follows the same doors + +`mem` 与 `doc` 同构：单机是个人记忆库，部署了才是团队资产层。自部署与 SaaS 均以 +同一拓扑打包两者；`doc` 与 `mem` 之间保持显式 API 连接，不共享隐藏数据库状态 +（见 [GOAL.md](../GOAL.md)）。分发、身份与合规边界按本页同一套门执行。 + +## Authentication consistency principle + +一致性不是一个中心账号，而是同一套认证协议走遍所有部署： + +- 用户可能连 ByteFolk SaaS，也可能连自己团队的自部署实例。客户端（roleweave）的 + 登录因此是**按部署的会话管理**，类比 git 客户端按主机记凭证：SaaS 只是一个预置 + 部署地址； +- 一致的是身份映射与协议（GitHub OAuth、邮箱 magic link、未来的 OIDC），不是账号 + 库。三扇门共用一套认证代码，客户端不为每扇门重做登录； +- 开放条目：roleweave 客户端的按部署登录需求尚未开单，登记后与本页互引。 + +## Guidance surfaces + +- `doc init` 的第一个问题即路由：就你自己 / 你团队有自己的基础设施 / 想让我们托管； +- README 与落地页三扇门并列呈现，自部署不埋进文档深处； +- `doc doctor` 输出门位与缺口清单，作为升级与排障的统一入口。 + +## Security boundaries for ByteFolk operators + +- 部署与注册只用个人账户与个人身份，不触碰任何雇主内部基础设施； +- 服务器与任何内部网络之间零隧道； +- 实例只存放 ByteFolk 或用户自己的内容，不存放第三方雇主的代码、文档与数据； +- 免费档供给风险（配额缩水、限期资源）作为已知风险管理，兜底手段是下一条。 + +## Upgrade and migration + +三扇门之间的移动是一次完整迁移，属于产品承诺（见 [GOAL.md](../GOAL.md) 北极星第 +5 条：完整迁移到另一套部署），不是运维人情。试验档到正式档、自部署到 SaaS 的路径 +均由导出与导入能力支撑。 From c28a25fe85bcfd495ab2cca43fa4dc4db08a63e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BF=AE=E9=9B=A8?= <47820304+PeterGuy326@users.noreply.github.com> Date: Sun, 20 Sep 2026 01:07:14 +0800 Subject: [PATCH 2/2] style: apply prettier to distribution docs --- docs/DISTRIBUTION.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/DISTRIBUTION.md b/docs/DISTRIBUTION.md index 50a8063..b106f28 100644 --- a/docs/DISTRIBUTION.md +++ b/docs/DISTRIBUTION.md @@ -6,11 +6,11 @@ ## The three doors -| 门 | 给谁 | 身份与认证边界 | 成本与合规谁背 | 当前缺口 | -| ------------------------ | ---------------------------- | ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------ | -| 本地单人（现状默认） | 个人写作 + 与 AI 协作 | 回环自验（本地开发邮箱），不构成真实身份 | 无人背 | 文案诚实化：明确标注单人模式，不让用户误以为本地即共享 | -| ByteFolk 托管 SaaS | "登录就用"的用户 | ByteFolk 统一身份：GitHub 任意用户 + 邮箱 magic link；org 成员资格只 gating 我们自己人 | 我们：基础设施、运维、用户内容与个人信息保管、境内域名则备案 | 多租户隔离工程、隐私政策、最低付费基础设施；**门未开，见开启条件** | -| 引导式自部署（现阶段主推） | 有服务器或有合规要求的团队 | 部署者自定边界：他的 GitHub org、他的 SMTP、未来的 OIDC | 部署者：自己的服务器、域名、发信通道与数据合规 | 部署向导、一键模板、`doctor` 门位报告 | +| 门 | 给谁 | 身份与认证边界 | 成本与合规谁背 | 当前缺口 | +| -------------------------- | -------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ | +| 本地单人（现状默认） | 个人写作 + 与 AI 协作 | 回环自验（本地开发邮箱），不构成真实身份 | 无人背 | 文案诚实化：明确标注单人模式，不让用户误以为本地即共享 | +| ByteFolk 托管 SaaS | "登录就用"的用户 | ByteFolk 统一身份：GitHub 任意用户 + 邮箱 magic link；org 成员资格只 gating 我们自己人 | 我们：基础设施、运维、用户内容与个人信息保管、境内域名则备案 | 多租户隔离工程、隐私政策、最低付费基础设施；**门未开，见开启条件** | +| 引导式自部署（现阶段主推） | 有服务器或有合规要求的团队 | 部署者自定边界：他的 GitHub org、他的 SMTP、未来的 OIDC | 部署者：自己的服务器、域名、发信通道与数据合规 | 部署向导、一键模板、`doctor` 门位报告 | ## Door 1: local single-player