系列文档 · 第 418 min

第 4 集 - 审阅、发布、预览，并理解边界

正文

这一集把私人文章在内容源中标记为公开，然后说明预览、生产部署、访问反馈和 MCP 集成分别需要什么。发布是源状态转换；预览和部署是独立的基础设施动作。

发布 item 改变内容源状态；预览仍是单独的 Docker-backed 操作。

本集结果

核心流程结束时：

文章已经经过审阅；
item 被标记为 published 和 public；
发布后索引已经重新构建；
你知道本地预览、生产部署、stats 或 MCP 是否属于当前工作区范围。

一、审阅文章

发布前，把文章当作公开 claim 检查：

前两句是否说明结果和重要性；
证据是否可见、已链接或被明确命名；
不确定性边界是否没有被藏起来；
标题和摘要是否使用同行能识别的词；
是否还残留私人笔记、凭据或未完成 claim。

如果 Agent 准备了改动，接受前先检查提案：

silan proposal list
silan proposal show <id>
silan proposal accept <id>

接受提案只会改变内容源，不会发布 item，也不会部署网站。

二、发布 item

silan blog publish new-research-result
silan content lint
silan index sync
silan blog show new-research-result

确认 item 状态是 published 和 public。这是第一次成功路径的终点：内容源已经记录了你的明确发布决定。

三、有 Docker 时再预览

silan site preview 会在 http://localhost:8080 启动本地栈。它需要 Docker，但不需要生产凭据。

先检查本地运行环境：

docker --version
docker compose version
docker info >/dev/null

如果没有手动设置 token，CLI 会为 preview 写入一个只用于本地的 _deploy/staging/deploy/.env，其中包含 STATS_SYNC_TOKEN。如果你自己覆盖 STATS_SYNC_TOKEN 或 SILAN_STATS_SYNC_TOKEN，请使用至少 32 个 ASCII 字符；更短的值现在会在 Docker Compose 启动前失败。

silan site preview
silan site preview --confirm

第一条命令是 dry run，会打印计划执行的动作：sync、build、package、ship、promote 和启动本地栈。只有当计划符合预期时，才使用 --confirm。

预览时检查：

标题和摘要；
图片和媒体 URL；
语言切换；
指向证据和相关工作的链接；
桌面端和移动端布局。

本流程已经用 Docker E2E 实测：

通过 CLI 创建、校验、索引、发布并完成 API 检查后，在 Docker preview 栈中渲染出的公开文章。

实际验证路径是：

silan init
silan blog new docker-e2e-result
silan blog add-lang docker-e2e-result zh
silan content lint
silan index sync
silan blog publish docker-e2e-result
silan site preview --confirm
curl http://localhost:8080/api/v1/blog/posts?lang=en

这次 Docker stack 达到了 healthy backend 状态；文章详情可以通过 /blog/docker-e2e-result/ 打开；公开 blog API 能返回这篇文章；无头浏览器打开页面后，文章详情、评论、geo 和 view-recording API 调用都成功返回。

E2E 过程中发现的问题：

Docker CLI 和 Compose 可用，不代表 Docker daemon 已经运行。预览前先启动 Docker Desktop，并确认 docker info 成功。
STATS_SYNC_TOKEN 必须能被后端读取，并且至少 32 bytes。现在没有手动覆盖时，CLI 会把本地 preview .env 自动写到 staged compose 文件旁边。
新建种子工作区可能有非致命 lint 提示；只有汇总显示 0 fatal 时才继续。
/blog/<slug> 会重定向到 /blog/<slug>/；做精确 HTTP 检查时使用尾部斜杠。
Docker web 镜像之前使用 Node 20 构建，而本地 Puppeteer 依赖声明需要 Node >=22.12.0；镜像现在改为 Node 22。
本地 preview 镜像中的后端会记录缺少 GeoIP country database 的 warning；这次测试中 geo API 仍返回了有效响应。

四、配置目标以后再部署

生产部署需要经过审阅的 silan-viking.toml [deploy] 配置、凭据、可连接主机，以及目标机器上的 Docker。新建工作区不会替你决定这些信息。

先运行 dry run：

silan site deploy --dry-run
silan site deploy --confirm

只有当 dry run 明确列出目标主机、远程目录、compose 文件和操作后，才运行确认命令。

五、克制解释反馈

部署后，仪表盘和 silan stats 命令可以报告真实读者活动、评论、线上版本状态，以及被分类为搜索或 AI crawler 的请求。解释这些信号时要克制：

crawler 请求表示 URL 被请求过，不表示被理解；
page view 表示页面被打开，不表示结果被读完；
没有请求可能是发现失败，也可能只是 crawler 还没到达。

问一个更小的问题：这些证据建议的最小有用更新是什么？答案可能是更清楚的开头、一条缺失链接、另一种语言版本，也可能是什么都不改。

进阶：连接支持 MCP 的 Agent

silan skill emit
silan mcp status
silan mcp serve --stdio

这是面向开发者的集成，不属于第一次发布成功路径。在支持 MCP 的客户端中注册 silan mcp serve --stdio，并把当前工作区设为命令运行目录。先从只读请求开始，例如“列出这个工作区中的文章”。客户端准备修改后，用 silan proposal list 和 silan proposal show <id> 检查。