Docsbook 概念：工作区、项目余额、索引
Docsbook 界面和文档中使用的每个术语都在此统一定义。每个条目先给出一句话定义，然后说明你会在哪里遇到该术语以及它会影响什么。术语按组归类，各组内部按字母顺序排列。
网站及其内容#
工作区#
工作区是一个文档网站及其设置，由一个 Markdown 文件仓库提供支持。该仓库可以是您在 GitHub 上拥有的仓库，也可以是您从网站扫描或书面简介开始后由 Docsbook 为您托管的仓库。
工作区拥有自己的地址、外观、语言设置、分析数据和余额。Docsbook 的管理面板和账单页面将同一个对象称为项目；这两个词指的是同一事物。
草稿#
草稿是已生成但尚未发布的文档网站。Docsbook 会在您拥有账户之前，根据您的源内容创建一个草稿。
来自网站扫描或书面简报的草稿会一直保存在您的浏览器中，直到您发布它。草稿会在与已发布工作区相同的管理面板中打开，因此您可以在登录前设置品牌、布局和 SEO。
页面#
页面是工作区仓库中的一个 Markdown 文件，通过其专属 URL 提供访问。文件和文件夹名称决定 URL 以及其在导航树中的位置。
.md 和 .markdown 扩展名都会被读取。其他格式的文件——.txt、.rst——不会被转换为页面。
导航树#
导航树是 Docsbook 根据存储库的文件夹结构构建的侧边栏。文件夹会成为一个组；文件会成为其下的条目。
文件夹根目录中的 README.md 会成为该文件夹的着陆页。您无需编写导航文件：在存储库中移动文件时，它也会在侧边栏中随之移动。
大纲#
大纲是 Docsbook 根据该页面的标题生成的页面目录，显示在内容右侧。点击标题即可将页面滚动到相应位置。
大纲由 H2 及更低级别的标题生成，因此跳过某个标题级别会在大纲中留下空缺。
内容小部件#
内容小部件是 Markdown 页面中的一个区域，Docsbook 会将其呈现为丰富的内容块——卡片网格、折叠面板、编号步骤或行动号召——并用两条 HTML 注释进行标记。
这些注释在其他所有 Markdown 阅读器中都是不可见的，因此同一个文件在 GitHub 上仍能正常阅读。未知的小部件名称会降级为普通 Markdown；任何内容都不会被隐藏。请参阅内容小部件。
内容如何进入并保持最新#
索引#
索引是 Docsbook 对您的 Markdown 执行的处理过程，用于构建网站所需的一切内容：搜索索引、导航树、每页的大纲、链接图，以及 AI 聊天检索所使用的嵌入向量。
工作区创建时会运行索引，Docsbook 检测到内容发生更改时也会再次运行。未建立索引的页面无法通过搜索找到，也不会被聊天引用。
GitHub 同步#
GitHub 同步是 Docsbook 网站与其代码仓库保持同步的方式：当有人访问网站时，Docsbook 会检查 GitHub 是否有新的提交，并重新索引发生更改的内容。无需配置 webhook，也无需等待构建步骤完成。
会同步：新的 .md 文件、文本编辑、删除、重命名、新文件夹。不会同步：提交历史、分支信息、代码注释以及其他格式的文件。
事实来源#
事实来源是指你已连接到工作区的代码库或网站，这样编写文档的代理就会从中读取事实，而不是凭记忆生成内容。每个已连接的来源都带有所有者关于连接该来源原因的说明。
来源是只读输入。它们与用于构建网站的代码库分开。请参阅已连接的来源。
Web 编辑器#
Web 编辑器是 Docsbook 中用于编辑工作区 Markdown 文件的浏览器内编辑器。保存操作会将更改提交到构建该网站的仓库。
在 Web 编辑器、GitHub 以及通过 MCP 操作的代理中所做的编辑都会进入同一个仓库，因此只有一份历史记录，而不是两份。
费用与计量#
项目余额#
项目余额是与某个工作区关联的资金，用于支付该工作区执行的 AI 工作。每个新项目创建时都会获得 $1.00 的余额，此外，项目创建满 3 分钟后，所有者还可以领取 $5.00，之后可在计费页面充值。
余额按项目计算，而不是按账户计算：一个项目余额用完不会导致另一个项目停止。请参阅定价。
充值#
充值是向某个项目的余额中支付一笔由您指定金额的款项。单次充值最低为$20.00，最高为$5,000.00。
充值不会过期，余额也不会按计划自动补充。您可以在账单页面设置每月定期付款；每月都会为同一余额充值。
按量计费的工作#
按量计费的工作是指会消耗项目余额的工作。共有四种，每种都对应项目“限额”卡片中按来源支出的一行：
- 读者（AI 聊天） — 向已发布文档的读者提供的 AI 答案。
- 管理员 & AI Agent — 代理运行，包括按量计费的 MCP 工具调用。
- AI 翻译 — 将页面翻译成其他语言。
- 语义索引 — 构建 AI 聊天检索所依据的嵌入。
其他内容均不按量计费：托管、自定义域名及其 TLS 证书、读者、编辑者、GitHub 同步、全文搜索、品牌设置、分析和 MCP 读取调用均不收取使用费用。可以在“限额”卡片中为这四种来源中的任意一种设置周期上限，将上限设为 $0 则会关闭该来源。
加价#
加价是 Docsbook 针对回答请求的模型，在 AI 提供商实际价格基础上收取的百分比——目前为 900%。模型、每 100 万个 token 的费率以及加价都会显示在控制面板中。
使用您自己的提供商 API 密钥即可免除这项费用：您直接向提供商付费，Docsbook 不会就该用量向您收取任何费用。
谁可以阅读该网站#
公共站点#
公共站点是默认设置：任何拥有链接的人都可以阅读，包括没有 GitHub 账户的用户和搜索引擎爬虫。仓库本身的可见性不会改变这一点——Docsbook 会读取仓库，然后提供它构建的页面。
公开状态使站点能够被 Google 编入索引，也便于 AI 助手引用。
私有站点#
私有站点会向除所有者之外的所有人显示解锁屏幕，而不是显示您的内容；解锁由共享密码或您自己的 SSO 身份提供商控制。在读者解锁之前，站点结构、页面和搜索索引都会保持隐藏。
无论可见性如何，所有者始终拥有完整访问权限。请参阅私有文档：密码和 SSO。
自定义域名#
自定义域名是您自己的主机名 — docs.yourcompany.com —，用于提供工作区，而不是使用 docsbook.io/{owner}/{repo}。您只需添加一条 CNAME 记录，Docsbook 就会配置 TLS 证书。
绑定自定义域名后，docsbook.io 地址仍可继续使用。请参阅自定义域名设置。
机器读取的表面#
llms.txt#
llms.txt 是 Docsbook 网站的纯文本索引，发布在网站根目录，供寻找此类索引的 AI 代理使用。它列出了各个页面及其涵盖的内容。
Docsbook 根据已编入索引的内容生成该文件，因此它不会与网站内容分别过时。请参阅 llms.txt。
MCP 服务器#
MCP 服务器是 Docsbook 位于 https://docsbook.io/api/mcp/server 的模型上下文协议端点，提供 140 个工具，使 AI 代理能够询问 docsbook_expert 代理该做什么并获取返回的指示，读取您的文档、搜索文档、更改设置，以及将页面提交回去。身份验证通过 OAuth 2.0 搭配 PKCE 使用 Bearer 方式。
发现调用不会计量；其他调用会消耗项目余额。请参阅 MCP 服务器和 MCP 工具参考。
浮动小部件#
浮动小部件是您发布的文档右下角的控制菜单，仅在您登录后对您可见。读者永远看不到它。
它可以切换聊天、代码仓库和模式，打开设置，以及退出登录。