企业官网建设流程全解析

• 后端
• 前端
• CMS

Talebook 的spec/目录承载着整个项目的领域规格：它用 23 篇无时态文档回答"产品是什么、按什么规则运转"，并通过一套自动化校验门禁保证规格始终与代码同步。本文以 spec/索引.md 为骨架，完整梳理这份规格体系的定位、篇章组织、固定结构、概念辨析，并结合仓库内的校验器与测试用例，说明它如何成为开发者、Agent 与 LLM 检索项目行为规则的可靠入口。读完本文，你将掌握如何快速定位任一功能模块的产品定义与实现落点。

一、规格文档的定位：唯一、最新、无时态

spec/是 Talebook 的领域规格文档集合，描述产品"是什么、按什么规则运转"。索引页开篇即给出三条硬性约束：

• 唯一一份。领域定义不在别处重复——任何行为规则的权威描述只存在于spec/对应篇目，杜绝多份文档互相矛盾。
• 总是最新。改变产品行为的改动必须在同一次提交里更新对应篇目，规格与代码同步演进。
• 无时态。只写当下的产品应然，不写变更历史、不写未实现、不写已废弃；那些属于design/目录。

这三条约束决定了spec/的属性：它不是开发笔记，而是一份可以当作契约来读、来校验的产品定义。其中"不写未实现"尤其重要——这意味着规格中出现的每个功能都应有真实代码支撑，反过来也为仓库的自动化校验提供了前提。

二、与仓库其他文字资产的分工

索引用一张表划清了四类文档的职责边界，这是理解整个仓库文档体系的关键：

简单说：想知道"这个功能存在吗、规则是什么"看spec/；想知道"这个改动当时为什么这么做、验证过什么"看design/（注意其中有大量.active.html、.superseded.html后缀的设计文档）；想知道"普通用户怎么操作"看document/（如 Development.zh_CN.md、README.zh_CN.md）；而research/保存的是对外部系统（如 audiobookshelf、apple-podcast-rss）的研究快照。四类文档各司其职，spec/是其中最稳定、最权威的一层。

三、每篇规格的固定七节结构

索引规定每篇规格文档采用固定七节，顺序遵循"先建立直觉，再交付词汇，最后进入细节"：

1. 定义—— 是什么，以及不是什么（每篇必须包含"不是什么"边界，防止概念蔓延）。
2. 使用场景—— 谁、在什么情况下、要达成什么。
3. 功能—— 概述清单。
4. 术语与界面用词—— 术语表（含示例）与操作按钮用词表。
5. 行为逻辑—— 详细产品设计，全篇最重。
6. 关联实体—— 与其他篇的关系。
7. 实现对照—— 数据存储、API 接口、关键定义、代码落点、界面文案五张子表，唯一允许出现实现细节的地方。

一个值得注意的设计原则写在索引末尾：正文使用产品语言，表名、字段名、路由与常量只出现在第 7 节。这意味着前六节是给产品经理、测试、Agent 读的"应然"，第 7 节才是给开发者读的"实然"映射——两套词汇严格分层，避免产品规则被实现细节污染。

以 spec/书籍.md 为例，第 1 节定义了书籍是"书库里可以被单独管理、阅读和交付的一个条目"，并明确"不是描述信息（那是元数据）、不是读者与书的关系（那是阅读状态）"；第 5 节展开所有权、可见范围、格式操作、内容形态等行为逻辑；第 7.1 节给出items表与Item模型、Item.scope、Item.media_type等存储细节，7.2 节列出/api/book/<id>全套接口。从产品定义到代码落点，一篇文档走完。

四、索引组织的四大篇章

索引把 22 篇正文按业务领域分为四组，每组都给出了"一句话"概括，方便快速判断去哪一篇查：

核心实体

这四篇是产品的地基。以 spec/用户.md 为例，它定义了"身份 / 能力权限 / 资源所有权"三层互不推导的权限模型、八个能力开关（登录、浏览、阅读、下载、上传、编辑、删除、推送，能力字符集delprsuv）、三态权限存储（小写允许、大写禁止、缺失按默认允许）、游客开关、邀请模式、演示模式等一整套规则，并在 7.4 节把判定逻辑定位到Reader.has_permission()、webserver/handlers/base.py的@auth等具体函数。

阅读与个人数据

这一组覆盖"读者与书的关系"全链路。注意 spec/有声书.md 强调有声书是独立的衍生媒体而非书籍的一部分，与书籍的定义边界形成呼应——规格文档之间通过"关联实体"和"不是什么"互相锚定，构成闭环。

内容来源与对外通道

spec/系统设置.md 中值得一提的设计是分层覆盖的配置模型："仓库默认值 → 管理员在界面保存的值 → 本地开发覆盖"，后者覆盖前者，管理员改设置无需改代码、无需重启；webserver/loader.py的get_settings()单例CONF正是这一模型的实现入口。

插件

插件篇章是规格体系中体量最大的分组。以 spec/插件/插件平台.md 为例，它把整个平台压成一句核心结论："插件是产品与生命周期单元，能力是业务发现边界，Provider 是实现角色，连接是配置与凭据的所有权边界，运行是审计边界"——五个概念对应五组不同的数据表（plugin_definitions、plugin_installations、plugin_connections、plugin_secrets、plugin_runs），混用任意两个都会写出错误的代码。同时它明确了"内置插件没有安装动作""管理员不能管理其他读者的连接""凭据加密存储且公开接口永不返回密文""预览先于执行"等关键规则。

五、容易混淆的几组概念：索引的辨析价值

索引专门用一节表格厘清最容易踩坑的八组概念对，这是阅读 spec 时最值得先看的部分：

这些辨析不是修辞游戏，而是直接映射到代码中的独立状态位：例如"启用 / 已配置 / 健康"对应plugin_installations的启用状态、plugin_connections的配置存在性、连接的健康度三个互相独立的字段；"阅读进度 / 收听进度"在实现上也是两套互不覆盖的数据。理解这些边界，是正确调用 API 与排查问题的前提。

六、自动化门禁：校验器如何保证规格不腐烂

spec/的"唯一、最新"不是靠自觉，而是靠一条可执行的校验门禁。仓库在 scripts/check_spec.py 中实现了一个约 260 行的规格校验器，并在 Makefile 中提供check-spec目标（python3 scripts/check_spec.py）。其校验维度覆盖了索引中声明的全部约定：

• 结构校验（check_structure）：一级标题必须与文件名一致；七节必须齐全、编号必须连续为 1..7；"实现对照"至少需要一张子表，子表必须是 7.1–7.5 的子集且保持顺序；定义一节必须包含"不是什么"边界；术语表必须为 4 列（标准用词、英文、含义、示例）且示例不能为空。
• 互链校验（check_links与check_inbound_links）：规格内部链接不能断链，且链接文案必须与目标文件名一致（如写[书籍](https://link.gitcode.com/i/da188b5d7d78c5a2e94a5873840d9837)可以，写[书籍条目](https://link.gitcode.com/i/da188b5d7d78c5a2e94a5873840d9837)会被判错）；仓库其他 Markdown 指向spec/的链接也必须在门禁扫描范围内——注释里特别提到，此前CONTEXT.md删除后 document/PluginGuide.md 留下死链，正是靠这项扫描发现的。
• 实现对照可核对性（check_implementation）：第 7 节中出现的仓库相对路径必须真实存在；7.2 API 接口表格中的每个完整路径必须命中服务端真实注册的路由。校验器通过正则扫描 webserver/handlers/ 与 webserver/webdav/ 下的路由定义（collect_routes），并把文档中的占位写法（如/api/book/<id>）具体化后逐一匹配，同时聪明地排除了 webserver/handlers/files.py 末尾的兜底路由/(.*)——否则它会匹配一切、让校验形同虚设。
• 插件覆盖校验（check_plugin_coverage）：每个在 webserver/plugins/register.py 中实际 import 装配（以from ... import PROVIDER为准）的内置插件，其插件 ID 必须出现在 spec/插件/ 的某篇文档中，否则报"已注册但在 spec/插件/ 下没有归属"。
• 索引完整性校验（check_index）：spec/下每一篇 Markdown 都必须被 索引.md 收录，防止新增篇目"失联"。

从源码看，check_spec.py对路由的校验相当严谨：它支持同一行并列多个完整路由（每行取首段一致的路由逐一校验）、对/api/(author\|publisher\|tag)这类分组写法和查询串做了归一化还原，避免误报。ROUTE_RE与PATH_RE两条正则分别约束了路由写法与仓库路径写法的格式。

七、测试如何守护这套门禁

门禁本身的正确性由一组专门的测试守护。仓库在 tests/test_check_spec.py 中为校验器搭建了最小化仓库夹具（构造spec/，借用真实仓库的handlers与webdav目录做路径与路由校验），覆盖了超过 20 个用例，其中值得关注的边界场景包括：

• test_section_order_is_enforced：章节顺序错乱必须报"章节应为"错误；
• test_unknown_route_fails与test_route_shape_must_match：写了未注册路由、甚至路由段数写错（如/opds/category/<name>实际接两段参数）都会被捕获；
• test_external_url_in_code_span_is_not_treated_as_path：代码跨度里的外部地址（如github.com/talebook/moke/releases）不会被误判为仓库路径；
• test_broken_inbound_link_from_outside_spec_fails：document/中指向spec/的死链会被"跨目录入链"扫描捕获，而test_links_outside_spec_are_not_checked则确认document/内部互引不在本门禁职责内；
• test_implementation_subsections_may_be_omitted：7.1/7.3/7.5 等子表"不适用时整张删除"是允许的，但 7.2 之后至少要留一张子表（test_implementation_requires_at_least_one_subsection）；
• test_repository_spec_passes：直接对真实仓库跑check_spec()，断言当前 23 篇规格全部通过校验。

这些用例不仅验证了校验器逻辑，也侧面固化了规格体系自身的演进规则——例如"子表可按需缺省"来自 spec/插件/插件平台.md 5.2 节的设计约定，测试注释直接引用了它。测试还特意把 20 多个子进程用例改为进程内调用（run_check），避免后台线程测试被硬编码墙钟超时挤掉，细节上也体现了工程严谨性。

八、如何高效使用这份索引

对不同的读者，spec/索引的用法不同：

• 开发者：改某个功能前，先读对应篇目的第 5 节"行为逻辑"确认产品规则，再读第 7 节"实现对照"直达代码落点（如书籍功能定位到 webserver/handlers/book.py、媒体分析定位到 webserver/services/media_analysis.py）；改动行为时必须同步更新规格，否则make check-spec会在 CI 中失败。
• 测试工程师：把第 5 节的每条行为逻辑当作测试用例的验收标准，第 7.2 节的 API 表格是接口测试的路径清单（每个路径都经过校验器确认真实存在）。
• Agent / LLM：spec/是回答"这个产品怎么运转"的单一事实源——先读索引定位篇目，再读对应篇目获取无时态的产品定义与实现映射，比在散落的代码里反向推断准确得多。
• 运维 / 部署者：重点读系统设置与用户两篇，掌握分层配置、安装向导、访问控制与演示模式的行为规则。

最后提醒一点边界：spec/只回答"是什么"，部署细节（端口、卷挂载、反向代理）在 document/ 与 docker/ 中，设计论证在 design/ 中。把四层文档配合使用，才能既看到产品规则，又看到落地方式与演进轨迹。

• 后端
• 前端
• CMS