文档受众分层重构计划

状态：待实施 创建日期：2026-05-12 核心目标：把 docs/technical/{zh,en}/manual.md 拆成"纯客户视角"的使用手册，把 planet.sh、日志、LAN、故障排查这类运维内容迁到独立 ops-runbook.md，并把分层规则写进 documentation-coverage-rules.md 和 .claude/commands/docs.md，让以后写文档时自动按受众归档。

背景

当前 manual.md 把客户实际使用和开发/运维操作混在一份文档里：开头 200 多行讲的是 planet.sh start/stop/restart/log/health/createuser/--allow-lan、AI Provider 镜像构建、netsh portproxy 和故障排查顺序，后面才进入 Earth、控制台、AI、Docs 这些客户真正会用到的功能。

客户读到一半会被 shell 命令吓住，开发者想找运维细节又要在大段 UI 操作里翻。documentation-coverage-rules.md 现在也没有受众分层规则，未来文档继续混着写。

本计划假定客户已经能拿到账号登录使用 — 注册/验证流程本身见用户公开注册与邮箱验证计划。

新的文档地形

文档	受众	Gatekeeper 组	范围
`manual.md` (zh+en)	纯客户/最终用户	`public`	注册、登录、账户、设置 UI、collector 配置、AI 配置、Console 页面、Earth、Docs 浏览
`quickstart.md` (zh+en)	纯客户	`public`	"我刚拿到 Planet 怎么开始用" — 打开 URL → 注册 → 验证 → 登录 → 第一次配置
`ops-runbook.md` (zh+en, 新增)	运维/部署人员	`docs_admin`	`planet.sh` 完整命令、健康检查、日志位置、LAN/portproxy、故障排查顺序、createuser CLI、Bun 构建约定
`ops-planet-sh-startup.md` (已存在)	运维	`docs_admin`	启动性能、AI Provider 镜像、`PLANET_LOAD_ZSHRC_ENV` 深度调优 — 保持不动
现有 `-context.md` / `backend-.md`	二次开发者	`docs_developer`	保持现状

backend-system-service-control.md 偏后端服务控制原理，不和 ops-runbook.md 重复 — runbook 讲"运维要敲什么命令"，service-control 讲"后端怎么实现服务管控"。

manual.md 重写后的章节顺序（客户旅程）

欢迎与入口 — Planet 是什么、几个入口（Earth 公开 / Console 需登录 / Docs / API）
注册账户 — 打开 /login → 点"注册" → 填用户名/邮箱/密码 → 收邮件 → 输入 6 位验证码 → 登录
登录与找回密码 — 登录页、忘记密码流程
账户设置 — 修改密码、修改邮箱（需重新验证）、查看权限组、登出
Console 总览 — 左侧菜单结构、各路由用途
配置数据采集器 — /settings?tab=collector_credentials：选择 collector、连接测试、保存凭证；BarentsWatch / AISStream 两个典型例子
配置 AI 凭证 — /ai?tab=providers：默认 provider、模型、Base URL、API Key、本地代理；工具 tab（WebSearch、OCR）
系统设置 — /settings 其他子 tab（系统设置、电视直播源、SMTP 邮件）
用户管理（管理员） — /users：创建、删除、改角色、Gatekeeper 权限组
数据探索 — /datasources、/data、/bgp、/alerts/*
AI 测试台 — /ai?tab=playground
Earth 公开页面 — 现 manual.md 的 Earth 章节原样保留（图层、图例、搜索、位置候选、设置、视角、动捕、巡航、移动端）
Docs 文档站 — 当前 Docs 章节保留（权限组说明）

不再出现：planet.sh、./planet.sh log、netsh portproxy、source ~/.zshrc && bun run build、"故障排查顺序"、"开发命令约定"。

quickstart.md 重写

当前 quickstart 假设读者会自己 git clone 然后 ./planet.sh start，这是给开发者看的。改为：

打开管理员给你的 URL
注册账号 + 邮箱验证
登录后第一次做什么（建议先到 /settings?tab=collector_credentials 配一个 collector，再到 /ai 配模型）
看 Earth

部署/开发的 quickstart 内容并入 ops-runbook.md 的"首次部署"小节，不再单独出 ops-quickstart.md，避免新增维护点。

ops-runbook.md 内容大纲

抽自现 manual.md，重新组织：

首次启动 — ./planet.sh start、默认账号（admin/admin123、linkong/12345678，引用 b15d097b 引入的 DEFAULT_LOGIN_USERS）
启停与按模块重启 — start/stop/restart 及 -b -f -a -d
健康检查 — ./planet.sh health
日志 — ./planet.sh log 及 -f -b -a，日志文件路径
创建用户（CLI 兜底）— ./planet.sh createuser；说明这是公开注册不可用（SMTP 未配置）时的兜底
局域网/WSL 访问 — --allow-lan、netsh portproxy、防火墙
AI Provider 环境变量与构建 — aiprovider/.env、~/.zshrc、PLANET_LOAD_ZSHRC_ENV
故障排查顺序 — 现 manual 末尾那段，原样搬来
开发命令约定 — Bun、bun run build、为什么不用 npm

documentation-coverage-rules.md 增量

在现有"覆盖清单"末尾新增一段：

受众分层（强制）

客户/最终用户能在浏览器里完成的操作 → 只写到 manual.md / quickstart.md

需要 SSH/shell/Docker/planet.sh/日志文件路径/端口转发 → 只写到 ops-runbook.md（或现有 ops-*.md），禁止出现在 manual/quickstart

同一动作两种入口（如"创建用户"既能 UI 也能 CLI）→ UI 路径写 manual.md，CLI 路径写 ops-runbook.md，互相用一句话相互引用

新增客户可见 UI 流 → 同时更新 manual.md zh+en 与 docs-content.ts

新增 ops 命令或脚本 → 只更新 ops-runbook.md zh+en

.claude/commands/docs.md 增量

在 "Step 2 — Decide Scope" 后插一段：

Document Audience Routing (Planet)

在 Planet 仓库内，写文档前先判断动作的执行者：

浏览器 UI 用户 → docs/technical/{zh,en}/manual.md / quickstart.md

shell/容器/运维 → docs/technical/{zh,en}/ops-runbook.md 或现有 ops-*.md

二次开发者 → 现有 *-context.md / backend-*.md

永远不要把 shell 命令、日志路径、Docker 操作写进 manual/quickstart；永远不要把 UI 截图/按钮路径写进 ops-*。

关键文件清单

docs/technical/zh/manual.md & en/manual.md — 重写
docs/technical/zh/quickstart.md & en/quickstart.md — 重写
docs/technical/zh/ops-runbook.md & en/ops-runbook.md (新)
docs/documentation-coverage-rules.md — 加受众分层段
.claude/commands/docs.md — 加 Document Audience Routing 段
frontend/src/pages/Docs/docs-content.ts — 注册 ops-runbook 到 DOCS_METADATA（docs_admin 组）

依赖

manual.md 的"注册账户"和"登录与找回密码"两章需要前后端注册/验证流程已经落地，否则文档会描述不存在的功能。注册功能本身见用户公开注册与邮箱验证计划。建议先实现注册再重写 manual，避免文档与代码错位。

验证

rg -n 'planet\.sh' docs/technical/zh/manual.md docs/technical/en/manual.md docs/technical/zh/quickstart.md docs/technical/en/quickstart.md 应该为空
rg -n '注册账户|register|邮箱验证' docs/technical/zh/manual.md docs/technical/en/manual.md 应该有命中
rg -n 'planet\.sh' docs/technical/zh/ops-runbook.md docs/technical/en/ops-runbook.md 应该有命中
frontend/src/pages/Docs/docs-content.ts 中 ops-runbook 出现且分组为 docs_admin
zh/en manual 章节标题对齐（按 documentation-coverage-rules.md 现有要求）
Docs 站点访问：未登录看 manual/quickstart 正常；非 docs_admin 用户看不到 ops-runbook；admin 能看到

7.8 KiB Raw Blame History Unescape Escape