进阶
常见问题
使用 Anydocs 时最常见的几个疑问，以及对应的排查方向。
这页不是完整教程，而是排障入口。先判断你遇到的是发布状态问题、reader 预览行为，还是初始化 / 导入方式的问题。
最常见的误判是：在 Studio 里看得到，就以为 reader、preview、搜索索引和 AI 产物里也一定看得到。公开边界实际由 `published` 状态决定。
为什么刚写的页面在 reader 或 preview 里看不到？
短答案：最常见原因是页面还不是 `published`。`draft` 和 `in_review` 会留在 Studio 里继续编辑，但不会进入 reader、搜索索引、`llms.txt` 或 `mcp/` 产物。
先检查：
- 页面状态是不是已经切到 `published`
- 页面是否已经出现在对应语言的导航里
- 如果是通过 AI 或 MCP 写入，是否已经完成状态切换，而不只是更新正文
为什么 preview 启动了，却没有自动打开浏览器？
短答案：`preview` 会启动本地 reader 服务并打印访问地址，但不会主动替你打开浏览器。
你应该看到：
- 终端输出里的 Preview URL
- 默认入口会指向默认语言下的第一个已发布页面
- 如果当前还没有已发布页面，入口会落在 `/{lang}`
为什么 Studio 能看到页面，preview 却看不到？
短答案：这不是数据不同步，而是两个界面的职责不同。Studio 是作者界面，会显示全部工作流状态；preview 是读者界面，只暴露 `published` 内容。
区分方法：
- Studio 用来看全部源内容，包括 `draft` 和 `in_review`
- preview 用来看读者最终能访问到的公开内容
为什么导入后的页面默认是草稿？
短答案：`convert-import` 会先把导入内容转换成 canonical `draft` 页面，避免历史文档未经检查就直接公开。
导入后建议立即做这几步：
- 检查 slug 是否符合目标语言和 URL 规划
- 检查正文和 metadata 是否需要清洗或补全
- 确认导航位置后，再决定哪些页面要发布
`search-index` 和 `llms.txt` / `mcp/` 有什么区别？
短答案：它们都是公开产物，但面向的消费方不同。
- `search-index.<lang>.json` 主要用于站内搜索
- `llms.txt`、`llms-full.txt` 和 `mcp/` 更适合外部 AI 或机器读取
- 如果某篇文档没有进入这些产物，先回到页面状态检查它是否已经发布
为什么项目里有时是 `skill.md`，有时是 `AGENTS.md` 或 `CLAUDE.md`？
短答案：这取决于 `init` 时是否指定了 `--agent`。
- 默认不指定 `--agent` 时生成 `skill.md`
- `--agent codex` 生成 `AGENTS.md`
- `--agent claude-code` 生成 `CLAUDE.md` 和 `.claude/commands/`
如果你看到更早的示例与此不一致，以当前 CLI 实际生成结果为准。
`init` 为什么会失败？
短答案：如果目标目录里已经存在 `anydocs.config.json`，CLI 会拒绝覆盖已有项目。
最稳妥的处理方式：
- 换一个空目录重新初始化
- 如果你本来就在已有项目里工作，直接打开它，而不是再次执行 `init`