01 / 双空间与模板边界
站点只是纯壳模板:同一份无硬编码代码按域名解析个人空间或工作室空间,共享受控读源,隔离分空间管理写权限。
02 / 零硬编码模型与跨空间挂载
空间品牌档案、创作者/成员署名、产品属性与正文 AST 全部数据化;通过受控挂载与跨站 Canonical 联动代表作而不产生重复索引。
03 / 差异化体验壳编排
个人空间偏探索(Classic + Desktop),工作室空间偏专业陈列与转化(Classic + Showcase 预留);共享同一套语义 AST 渲染器。
04 / 模板演进与多空间发布
模板代码升级与各空间品牌/内容发布彻底解耦;新建空间或改品牌定位无需改代码、无需重发前端包。
By Keros & Studio 双空间架构扩展方案(v0.4 草案)
状态:架构扩展草案(基于 PRD-v0.2、7 条语音需求、正式决策 r7 Q01–Q42 与 v0.3 37 表设计演进;未开通云服务、未注册域名、未改动原始交接包)。
场景定位:面向个人 IP 空间 + 核心创作者主导的工作室/独立产品矩阵展示空间(同库分空间 space 为默认拓扑,同时保持契约级可拆库能力)。
第一铁律(Template-Only Shell):站点代码只是纯粹的承载模板与交互引擎。任何 IP 身份、品牌描述、Slogan、团队介绍、成员信息、旗下产品/项目/工具条目及正文内容,均不在前端组件或后端路由中硬编码,全部作为后续可编辑、可版本化、可多语言发布的领域内容注入。
1. 为什么强调“站点只是模板”:代码与内容的彻底剥离
在传统个人站或工作室官网中,首页 Hero 文案、关于页介绍、导航栏栏目、团队成员列表和代表产品往往直接写在 .astro / .tsx 组件或静态配置文件里。一旦要从“个人站”扩展到“工作室/产品矩阵站”,就会被迫复制仓库、硬改文案,沦为两套无法同步升级的代码。
v0.4 将系统严格切分为三层:
| 层级 | 职责定义 | 允许存在于代码中的内容 | 必须作为数据后续录入的内容 |
| 引擎与模板层(Code) | 路由解析、空间上下文解析、AST 语义渲染器、受控交互组件注册表、体验壳(Classic / Desktop / Showcase 等)布局与窗口编排 | 布局骨架、通用 UI 控件状态文本(如加载/错误回退)、Schema 校验器、API 协议 | 禁止出现:任何具体人名、工作室名、Slogan、产品名、外链 URL、固定分类营销语 |
| 空间配置与档案层(Space & Profile Data) | 定义“当前空间是谁、启用哪些体验壳、主导航展示哪些槽位、有哪些创作者/成员” | space_profile_revision、space_domain、actor_profile 的数据结构与渲染槽位契约 | 个人或工作室名称、定位简介、Logo/头像媒体引用、导航开关(如团队空间关闭 note 日常流)、社交/联系入口 |
| 作品与叙事内容层(Content & Media Data) | 承载具体的产品、项目、工具、文章、短记录及其跨空间关联 | content、revision(JSON/AST)、work_profile、asset_version 等领域规则 | 产品介绍、架构指标、受控交互参数、工具跳转地址、中英文正文、演示图片与 1080p SDR 视频 |
直接收益:
1. 站点刚启动尚无内容时,渲染的是诚实的模板空态(Empty State)或显式标记 sampleData: true 的本地 Fixture,绝不用虚构案例或 AI 营销黑话充数。
2. 新建一个工作室空间或新产品专题时,零代码改动、零重新构建前端包,仅通过管理 API 写入新的 space、绑定域名、录入空间档案和内容即可上线。
2. 延续与不破除的正式决策基线(Q01–Q42 对齐)
v0.4 完全继承交接包中已锁定的核心决策,不回退任何一项非第一推荐选择:
技术与存储底座:Astro + React(Q07)、Cloudflare D1 关系库(Q08)、版本化 JSON/AST 唯一正文真源(Q09)、差异修订 + 周期检查点(Q14)、R2 + Images 预设变换 + Stream 1080p SDR 展示版及导出备份(Q03/Q27/Q28/Q29/Q30)。
编辑与多语言策略:普通块可视化 + 复杂受控块专业/API 编辑(Q10)、受控交互必须具备静态/文本有效替代表达才可发布(Q01/Q13)、中文先发 + 英译校验通过自动公开 + 旧译文保留提示 + 人工保护片段保留(Q15–Q18)。
路由、体验与验收:同内容同语言唯一 URL + 本地体验偏好(Q19)、明确导航记历史(Q20)、首发路径固定(Q22)、可撤销限时预览链接(Q26)、首期中文增强搜索适配层(Q38)、兼容扩展→验证迁移→收缩(Q39)、小时级恢复目标论证(Q40)、所有该空间承诺开启的体验同批验收通过(Q42)。
正式/预览数据共享:预览环境通过可信只读服务边界消费同一受控内容源,不持有生产 D1/R2 写凭据(最新 7 条语音覆盖项)。
3. 核心领域演进:从单站 v0.3(37 表)到双空间模板 v0.4(45 表)
为了支撑“个人 IP + 工作室产品矩阵”双空间且不硬编码任何身份信息,v0.4 新增 8 张表,并对 9 张既有表 做最小向后兼容扩展。
3.1 新增的 8 张核心表
| 新增表 | 主键 / 唯一约束 | 解决的核心问题 |
space | space_id (slug UNIQUE) | 定义逻辑空间实例(kind IN ('personal','studio'))、生命周期、默认语言、允许开启的体验壳列表 enabled_experiences_json 与默认体验壳。 |
space_domain | hostname (space_id, is_primary 唯一主域) | 将访问 Hostname(如未来的个人主域、工作室主域、301 跳转别名域、预览域)动态映射到 space_id,代码不写死域名判断。 |
space_profile_revision | profile_revision_id (space_id, locale, sequence UNIQUE) | 模板去硬编码核心表:按空间 + 语言版本化存储站点标题、副标题、Hero/关于区 AST(支持受控交互块与媒体引用)、导航栏配置 JSON、页脚与联系入口配置 JSON。 |
space_profile_publication | (space_id, locale) | 控制每个空间各语言当前对外生效的品牌/外壳配置快照指针与 generation,使改版站点介绍与发布文章一样可回滚、可审计。 |
actor_profile | actor_profile_id (handle UNIQUE) | 公开创作者/成员身份实体(区别于内部鉴权表 api_principal),可选关联 principal_id,记录头像资产版本与状态。 |
actor_profile_locale | (actor_profile_id, locale) | 创作者/成员的多语言展示名、头衔/职能、个人简介与外部链接 JSON(同样作为内容后续录入)。 |
content_credit | (revision_id, actor_profile_id, role_code) | 作品/文章修订级的署名与分工图谱(如创作者、架构、设计、工程及排序 ordinal),个人作品为单人署名,工作室产品支持多人或主体联合署名。 |
space_content_mount | (space_id, content_id) | 跨空间双向展示契约:允许一件归属于工作室的核心产品(owner_space_id = studio)以受控引用方式挂载到个人空间作品集展示(反之亦然),不复制 content 与 revision,并明确记录挂载模式(canonical_redirect 跳回主空间,或 syndicated_card 仅展示卡片外链,或受控镜像且强制指向主空间 Canonical)。 |
3.2 对 v0.3 既有表的兼容变更清单
1. content:新增 owner_space_id TEXT NOT NULL REFERENCES space(space_id) 与 visibility_scope TEXT NOT NULL DEFAULT 'space_only' CHECK (visibility_scope IN ('space_only','cross_mountable'))。每件作品/产品/文章有且仅有一个主归属空间(Canonical Owner Space)。
2. work_profile:保持 Q11“核心字段 + 类型化扩展”,明确 catalog_kind CHECK (catalog_kind IN ('product','tool','project','experiment')) 可选分类标识,其余产品矩阵所需元数据(如版本号、运行状态徽章、在线访问入口、仓库链接、核心指标列表)统一走受 Schema 校验的 typed_extension_json,不在表列上写死某款特定产品的字段。
3. tag:新增可选 space_id REFERENCES space(space_id)(NULL 表示跨空间通用技术标签,非空表示某空间专属业务标签),唯一键调整为 ( COALESCE(space_id, ''), stable_key ) 唯一索引。
4. asset:新增 space_id TEXT NOT NULL REFERENCES space(space_id),媒体资产按归属空间治理配额与后台列表;跨空间挂载已公开内容时,通过 asset_reference 与 space_content_mount 授权读取不可变 asset_version,无需重复上传同一张图或视频。
5. public_snapshot / publication / publish_attempt:冗余携带 space_id 外键,保证单空间公开读取、缓存刷新与发布回执核验都在 (space_id, content_id, locale) 边界内完成,杜绝跨空间串读。
6. content_route:主键从 (locale, path) 升级为 (space_id, locale, path)。个人空间与工作室空间可各自拥有独立的 /zh/works/... 路径命名空间而互不冲突。
7. api_key:新增 allowed_spaces_json TEXT NOT NULL(JSON 数组,如 ["*"] 或 ["studio-main"]),实现按集成 + 按空间双重最小权限隔离(Q24 强化)。
8. preview_grant:新增 space_id TEXT NOT NULL REFERENCES space(space_id),使 Q26 可撤销限时预览链接严格绑定在目标空间的预览域名下校验,不会在另一空间泄露未公开草稿。
9. space_member_role(并入权限组,作为第 8 张扩展治理或使用 api_key/会话声明):为简洁且精确,v0.4 在 api_principal 之上通过 api_key.scopes_json 与管理端会话声明支持空间级角色语义:space:owner(空间配置/路由/Key/撤回)、space:publisher(触发发布)、space:editor(草稿修订/上传/建预览链接)。*注:SQL 草案中已将 8 张新增表精确对齐上述结构,共计 45 张表。*
4. 多空间路由、域名拓扑与 SEO / Canonical 规则
4.1 动态 Host → Space 解析(无硬编码域名)
所有前端与访客 API 请求到达 Worker 时,第一步由 SpaceResolver 根据请求 Host 查询缓存化的 space_domain 表:
域名角色(domain_role) | 示例拓扑(仅作结构示意,实际域名后续配置) | 行为契约 |
primary(空间主规范域) | 个人空间主域 / 工作室空间主域 | 直接渲染对应 space_id 的体验壳与公开内容;生成该空间内容的默认 canonical 与 sitemap.xml。 |
redirect_alias(品牌根域/别名跳转) | 根域或 www 别名域 | 返回 301/308 永久跳转至目标空间的 primary 域名并保留语言/路径策略,不在别名域重复输出可索引正文。 |
env_preview(代码环境预览域) | 个人预览域 / 工作室预览域 | 绑定对应 space_id,通过可信只读边界读取同一受控公开内容;全站强制响应 X-Robots-Tag: noindex, nofollow。 |
draft_preview(限时修订预览入口) | 各空间预览域 /preview/{grant_token} | 校验 preview_grant(匹配 space_id、未过期、未撤销、媒体继承白名单),脱敏 Referrer 与日志,禁止搜索引擎抓取。 |
4.2 同一空间内的路径与体验规则(继承 Q19–Q22)
标准路径结构:/{locale}/{collection}/{slug}(例如 /zh-CN/works/{slug}、/en/articles/{slug})。collection 的可用集合由该空间的模板配置决定(例如工作室空间可隐藏 /notes 生活记录入口,若直接访问则返回诚实的 404)。
首发路径固定(Q22):内容首次在所属 owner_space_id 公开时写入 content_route(space_id, locale, path);后续修改产品名称或文章标题不改变首发路径,确需变更时将原记录置为 route_state = 'redirect' 并指向新路径。
URL 不携带 UI 皮肤参数(Q19):无论是个人空间的 Classic / Desktop,还是工作室空间的 Editorial Showcase / Interactive Showroom,同一内容 URL 完全一致;访客切换体验偏好存储在本地(按 space_id 独立存储偏好,互不干扰)。
4.3 个人空间 × 工作室空间的交叉展示与 Canonical 铁律(防重复索引)
当一件作品(例如某款独立 AI 产品或工具)主归属于工作室空间(owner_space_id = studio),但同时希望出现在个人空间的作品列表中以体现创作者代表作时,通过 space_content_mount 提供三种受控模式,彻底避免“复制粘贴两份文章导致 SEO 自相残杀”:
1. directory_card(目录卡片直跳模式 · 推荐默认)
个人空间的列表/桌面窗口展示该产品的摘要卡片、作者在该产品中的角色(来自 content_credit)及缩略图;点击详情直接跳转至工作室空间的规范详情页 URL。个人空间不生成重复正文页。
2. canonical_mirror(受控镜像阅读 + 跨站 Canonical 模式)
个人空间允许在本地体验壳(如拟真桌面窗口内)直接打开阅读同一份 public_snapshot 正文与交互块,但其 HTML <link rel="canonical" href="https://{studio_primary_domain}/..." /> 强制指向 owner_space_id 的主域名 URL,并在页面显著标注“本产品归属于 {动态读取的工作室名称}”及来源链接。
站点地图策略:仅 owner_space_id 的 sitemap.xml 收录该详情页 URL,镜像挂载端不将其写入自身 sitemap.xml。
3. featured_link(纯外部独立产品入口模式)
当旗下某个产品未来拥有完全独立的业务域名与应用站时,工作室空间和个人空间均通过 work_profile.tool_entry_url 提供独立入口与作者/工作室背书页,主站详情页承载“背景、架构取舍、演进记录与交互演示”,与产品运行站形成互补而非重复。
5. 公开读 API 与隔离管理 API 契约变化(v1 演进)
保持《架构叙述 v0.3》中“同源访客 API + 隔离管理域名/API + 内部可信读/命令边界”的安全架构,不引入公共万能写接口。
5.1 访客公开只读 API(同源 /api/v1/*,由 Host 自动锁定 space_id)
前端模板不靠写死配置渲染外壳,首屏 SSR 或水合时统一消费公开契约:
| 端点 | 用途说明 | 双空间与模板化关键变化 |
GET /api/v1/space/bootstrap?locale=zh-CN | 新增:获取当前空间模板启动载荷 | 返回当前 space_id、space_kind、生效中的 space_profile(动态站名、定位语、Logo 资产、导航菜单、可用体验壳列表、联系通道配置),无硬编码文案。 |
GET /api/v1/content?locale=zh-CN&kind=work&role=tool | 获取当前空间公开内容列表 | 自动合并本空间主归属已发布内容 + space_content_mount 有效挂载项;每项附带 credits[](署名摘要)与 canonicalUrl、mountMode。 |
GET /api/v1/content/{contentIdOrPath}?locale=zh-CN | 获取单篇公开 ContentDTO + 版本化 AST | 仅返回本空间已发布或合法镜像挂载的 public_snapshot;附带 ownerSpace 标识、完整 credits[]、语言可用性矩阵及 canonicalUrl。 |
GET /api/v1/actors?locale=zh-CN | 新增:获取当前空间关联的公开创作者/成员档案 | 供工作室空间的“团队/创作者”模块或个人空间的“关于作者”模块动态渲染,数据来自已关联公开内容的 actor_profile 或空间档案指定列表。 |
GET /api/v1/search?q=...&locale=zh-CN | 空间内增强搜索(Q38 适配层) | 默认严格按当前 space_id 过滤检索投影(可选参数 includeMounted=1 包含挂载作品),绝不跨空间泄露未挂载内容或任何草稿。 |
GET /api/v1/media/{assetVersionId}?preset=reading | 公开媒体预设交付解析 | 校验该 asset_version_id 是否被当前空间有效公开快照(含 space_profile 与挂载快照)引用。 |
POST /api/v1/telemetry/events | 导航阅读实例与受控交互事件(Q31–Q34) | 自动注入服务端解析的 space_id;不同空间的标签页短会话相互独立,原始路径保留 ≤7 天真实到期清理。 |
5.2 隔离管理与 Agent 命令 API(管理端 /api/admin/v1/*)
所有写接口均强制校验:身份凭据有效 + allowed_spaces 包含目标 spaceId + 角色 Scope 满足 + Idempotency-Key 幂等 + expectedRevision / expectedGeneration 乐观并发检查(Q24/Q25)。
| 端点 | 所需最小 Scope | 职责说明 |
POST /api/admin/v1/spaces | platform:owner | 创建新空间(如新增工作室空间或专题产品空间),初始化允许的体验壳与默认语言。 |
PUT /api/admin/v1/spaces/{spaceId}/domains | space:owner | 绑定或调整该空间的主域名、跳转别名域与预览域映射。 |
POST /api/admin/v1/spaces/{spaceId}/profile/revisions | space:owner | 提交空间品牌档案修订(站名、Slogan、关于页 AST、导航结构、联系入口),完全替代改代码改文案。 |
POST /api/admin/v1/spaces/{spaceId}/profile/publications | space:owner | 发布空间品牌档案修订并生成生效回执。 |
POST /api/admin/v1/actors / PATCH /api/admin/v1/actors/{actorId} | space:editor | 创建/更新创作者或团队成员公开档案(多语言名称、职能、简介、头像资产引用)。 |
POST /api/admin/v1/spaces/{spaceId}/content/{id}/revisions | space:editor | 提交归属该空间的内容差异修订/检查点,包含 AST、类型化产品扩展 work_profile 与署名列表 credits[]。 |
POST /api/admin/v1/spaces/{spaceId}/publications | space:publisher | 校验 AST、受控交互静态替代(Q13)、关键媒体就绪状态(Q29),更新公开指针并核验页面/列表/搜索传播(Q37)。*Agent 默认不授予此 Scope。* |
POST /api/admin/v1/spaces/{spaceId}/mounts | space:publisher | 将另一空间允许跨空间展示(cross_mountable)的内容挂载到本空间,或解除挂载。 |
POST /api/admin/v1/spaces/{spaceId}/previews | space:editor | 签发绑定该 spaceId 与明确 revisionId 的可撤销限时预览链接(Q26),供队友或外部合作方审阅未公开产品页。 |
POST /api/admin/v1/spaces/{spaceId}/media/uploads | space:editor | 在该空间配额与命名空间下创建受限上传会话(R2 / Stream)。 |
6. 模板化前端体验壳(Experience Registry)设计
为了兼顾个人 IP 的探索感与工作室产品矩阵的专业感,同时遵守“不重复维护内容、不同时 SSR 多套隐藏 DOM”的原则,体验注册表升级为“空间声明可用体验集合,共享同一 ContentRenderer”:
共享内核(所有空间共用)
SpaceBootstrapContext:注入动态读取的空间品牌、导航与联系契约。
SemanticAstRenderer:渲染标题、段落、列表、不可变媒体引用、代码/架构块,以及带静态 Fallback 的受控交互块(Q01/Q13)。
WorkCard / CreditBadge:根据数据动态渲染产品/工具/项目双角色入口与创作者署名。
可插拔体验壳适配器(按 space.enabled_experiences_json 按需启用)
1. classic(经典编辑部/阅读流壳):适用于个人空间与工作室空间,强调高可读性、清晰的产品/文章索引与快速直达。
2. desktop(拟真电脑桌面实验壳):默认在个人空间开启,把作品、工具入口与文章作为窗口化应用体验,窗口几何状态仅存本地会话。
3. showcase(工作室展厅/产品矩阵壳 · 预留给 Studio 空间):聚焦产品矩阵陈列、技术能力受控交互沙盒、署名分工与合作联系转化;手机端自动使用触屏等价编排,不模拟拖窗(Q04/Q42)。
7. 整体分阶段落地计划(不阻塞首期交付)
遵循“底座契约一步预埋,前台与内容分步生长”的节奏,避免因为规划团队空间而拖慢首个可用模板落地:
阶段一:v0.4 契约与纯模板内核定型(本地离线可完成)
1. 冻结 content-schema-v0.4.sql(45 表)、SpaceBootstrapDTO / ContentDTO v1.1(含 space、credits、canonicalUrl)与修订重放校验逻辑。
2. 将现有本地 demo 改造为纯零硬编码模板验证:所有页面标题、空间介绍、示例产品与示例文章全部仅从可替换的 fixture-spaces.json 读取,验证切换 personal-sample 与 studio-sample 两个示例空间时,同一套代码即可渲染两种截然不同的站点身份。
阶段二:单实例可信后端与内容管线闭环(待获批开通开发/预览环境后)
1. 在独立验收环境中跑通 D1 迁移(兼容扩展检查点)、R2/Images/Stream 受控上传与就绪门禁、版本化管理命令 API(含 expectedRevision 与幂等去重)。
2. 落地中译英异步任务管线(Q15–Q18 片段保护与自动检查)与 CF-only 中文增强搜索适配层(Q38 独立检索投影库,不污染主库导出能力)及联合恢复演练(Q40)。
阶段三:首个真实空间上线与内容录入(待域名与生产授权后)
1. 通过管理 API 或轻量后台/Agent 工具创建首个正式 space,动态录入首个空间的品牌描述、创作者档案与首批真实项目/工具/文章内容。
2. 完成 classic + desktop + 移动端同批性能和 SEO/AEO 矩阵验收(Q42)。
阶段四:工作室/产品矩阵空间扩展(零后端重构)
1. 新增 studio 空间记录与域名映射,录入工作室品牌档案、团队成员档案及旗下产品矩阵内容,配置与个人空间的 space_content_mount 双向代表作联动。
2. 按需研发并挂载工作室专属的 showcase 体验壳与产品级受控交互演示模块,实现“一套底座支撑个人 IP 与工作室矩阵长期共演进”。