变更记录

本页记录当前 VitePress 文档覆盖的 v0.2 用户可见状态。它不是营销列表，而是评估、部署和试点前需要知道的变化。

v0.3.0

• 通过单个 docker-compose.yml 部署和更新，配置与密钥直接写在 YAML 中，无需 .env 或安装脚本。
• 从 GHCR 直接拉取通过验证的 Backend/Admin 镜像，支持 Linux amd64 和 arm64。
• 数据库初始化前检查必填配置；后端启动时自动处理数据库迁移、首个管理员和存储桶。
• 补充旧 Compose 压缩包迁移说明，升级时沿用原密钥和数据卷。

本版不新增数据库迁移，MCP API 契约保持 v0.2.0。升级步骤见升级与回滚。

v0.2.1

• 部署指南新增完整 Docker Compose 示例，可一次复制四个服务的配置，并说明 .env、安装目录和镜像加载步骤。示例直接引用部署包源文件。
• 修复 Admin 小屏幕下 MCP 配置框被截断的问题，长配置可在框内横向滚动。
• 五个仓库、预构建镜像、Compose 下载包及 MCP/Skill 安装引用统一到 v0.2.1。

本次补丁不新增数据库迁移，后端接口和 22 项 MCP 工具契约与 v0.2.0 兼容。升级步骤见升级与回滚。

v0.2.0

• MCP 新增 get_schema_version 和 get_doc_version，读取指定已发布版本全文。
• 最新内容查询必须明确分支；未知参数会报错。升级后请重新加载 MCP 工具清单，并为 get_latest_schema / get_latest_doc 补上 branch_id。
• OpenAPI 草稿读取增加原始正文，与 revision 来自同一快照；原有元数据字段保留。
• Backend/Admin 提供 Linux amd64 和 arm64 预构建 Docker 镜像，安装器校验下载与源码来源；无需先获取五个源码仓库。
• 工作台和首次使用指南提供 Codex / Cursor 配置；官网改善中文搜索、语言切换、正文地标与卡片链接名称。
• 官网统一为 GitHub Pages，仅正式 Site 标签通过检查后自动上线。

本版不新增数据库迁移。人工审核发布、不可变版本和令牌权限保持原有边界。升级前备份数据库与对象存储，并同步升级五仓发行包。

当前文档变化

• 文档阅读路线从“运维手册”调整为“认识 Vdoc、理解运行流程、部署、首次使用、Agent 接入、升级排障”。
• 中文默认入口是 /。
• 英文文档使用 /en/...，并保持同名主题路由。
• 新增 运行流程，解释 Admin review、Draft、Version、MCP、Skill 和 Agent 的关系。
• 部署指南 已按 scripts/vdoc-local-bootstrap.sh、root Compose、可选 demo seed、live-compose E2E、release dry-run、直接部署和外部 PostgreSQL/S3 compatible storage 重写。
• 首次使用 已覆盖初始管理员、Project、Document、Draft、Version、MCP Token、MCP adapter 和 Skill 的第一条链路。
• 新增 Admin AI，记录系统和项目 provider、两种 OpenAI-compatible API 模式、prompt 覆盖、自动摘要、页面对话、审计和人工发布边界。
• 升级与回滚 已覆盖 PostgreSQL/object storage 备份、docker compose --env-file .env up -d --build、live E2E、scripts/vdoc-release-dry-run.sh、健康验证和回滚。

当前产品面

• Backend 提供 public health/auth/docs/MCP routes 和 private Admin routes。
• Backend 在启用 database 时自动运行 migrations，在启用 storage 时会尝试创建缺失 bucket。
• Admin Docker 支持 runtime VDOC_ADMIN_API_BASE_URL，用于生成浏览器可用的 backend API base URL。
• @vdoc/mcp 是可安装 stdio MCP adapter，负责把 Agent MCP 请求转发到 backend。
• Vdoc-skill 是可安装 Agent 工作流包，要求 Agent 使用 Vdoc MCP 查询事实后再给结论。
• 后台 Admin AI 可以辅助解释 Draft、Version 和 Diff，但不替代外部 MCP/Skill Agent、机器 Diff 或人类发布门禁。
• Live E2E 使用 ./scripts/vdoc-e2e.sh live-compose --env-file ../.env，只重置一次性 VDOC_TEST_POSTGRES_DB，默认 vdoc_e2e。

仍需记住的边界

• MCP 不能直接发布 Version。
• Agent 可以提交 Draft，发布必须由 Admin 或 SuperAdmin 审核。
• 不要把 Compose service name 用在浏览器配置里；浏览器使用 127.0.0.1 或域名，容器内部才使用 postgres、rustfs、backend 等服务名。
• 不要把真实 secret 写入文档、日志、截图或 Git history。

如何验证文档

1. 打开 /，确认默认中文页面加载。
2. 打开 /en/product-overview，确认英文页面加载。
3. 点击 运行流程、Admin AI、部署指南、MCP 工具 和 升级与回滚，确认主题路径连贯。