只写安装命令不够。新手第一次部署还要关注依赖、配置、服务启动、健康检查、群内验证和隐私检查。
机器人项目的安装文档，最怕写成一串命令。
装 Node，装依赖，复制配置，启动服务，扫码登录，然后在群里试一下。每一步单独看都不复杂，但第一次部署的人经常卡在“不知道现在到底跑通了哪一层”。
chatbot-qq 的 Windows 安装指南说明了一点：新手文档要先保证第一次部署能按步骤跑完，而且下次还能照着复现。
这里的首跑流程，从准备依赖开始，到生成本地配置、启动桥接组件、通过健康检查、在允许的群里收到消息，最后确认没有把本地运行现场带进仓库。中间任何一步失败，都能知道该回头看哪一层。
安装文档先交代链路
QQ 群聊机器人不是单进程工具。
它至少要经过这几层：
QQ 登录侧 -> NapCat -> OneBot v11 -> 本地代理 -> cc-connect 项目如果安装文档一上来只写“运行脚本”，读者很难判断脚本背后到底启动了什么。出了问题以后，也只会得到一句模糊的“机器人没反应”。
所以文档开头要先交代链路。NapCat 负责平台连接，OneBot 提供协议面，本地代理负责把消息送进项目，cc-connect 再接住具体任务。知道这条路以后，后面的检查才有位置感。
收不到消息，不一定是模型没回；可能是 QQ 侧没有登录，可能是 OneBot 没开，可能是代理没连上，也可能是允许列表没配置。链路写清楚，排错才不会一开始就跑偏。
交互式脚本要减少猜配置
新手安装里最容易出错的是配置。
群号、私聊白名单、NapCat 目录、本地配置文件、插件开关，这些东西如果全靠手写，很容易出现一个空格、一个路径、一个文件名导致整条链路断掉。更麻烦的是，很多配置里带着真实标识，不适合复制到公开文档或仓库示例里。
所以更适合采用交互式安装脚本。
脚本可以问几个必要问题，然后生成本机配置和本地工作目录。文档只保留占位说明，不直接展示真实群号、真实用户 ID、真实登录状态和本机路径。这样既降低了第一次部署的门槛，也顺手把公开材料和本地现场隔开。
好的安装脚本要把风险收进固定位置：
- 公开仓库放模板、示例和脚本。
- 本地目录放真实配置、日志和运行状态。
- 生成文件默认不提交。
- 发布前再跑一次隐私检查。
这几条比“请别提交敏感信息”更可靠。提醒会被忘记，结构更不容易漏。
首跑必须有健康检查
服务启动了，不代表已经可用。
终端里出现一堆日志，也不代表消息能从 QQ 群走到项目。安装指南里必须有一个明确的健康检查点，告诉使用者：至少代理进程已经起来，基础连接没有立刻断。
首跑检查可以写成三段：
process uphealth endpoint okreal message round-trip ok第一段确认进程在跑。第二段确认本地健康接口能返回正常状态。第三段是在允许的群或私聊里发一条真实消息，确认机器人能收到并回复。
这三段最好都保留。进程在，不一定协议通；健康接口正常，也可能白名单没配；群里没回复时，还要继续分清是桥接、路由还是模型侧的问题。
本地路径别写成公共答案
Windows 新手文档很容易把本机路径写死。
这样对当前机器很方便，对公开仓库却不友好。别人照着走，路径未必存在；搜索引擎收录以后，还会把个人运行习惯变成公共说明。更糟的是，路径常常暴露项目组织方式、用户名、同步目录和运行脚本位置。
更合理的做法是把文档拆成两层：
公开指南：说明组件、步骤、占位变量和检查方式本机备注：记录真实路径、端口、启动器和临时修复公开指南要让别人能复现思路，本机备注只服务当前机器。两者别混在同一个 README 里。
如果确实需要在文档里展示路径，也应该用 <project-root>、<napcat-root>、<group-id> 这样的占位符。真实值应该只出现在本地生成配置或私有笔记里。
插件配置也要进首跑流程
群机器人装好以后，很快会遇到第二个问题：功能从哪里开。
图片、提醒、文件处理、维护命令、长回复渲染，如果全靠改主配置，安装文档会越来越像杂物间。chatbot-qq 这类项目更适合把新能力放进插件，再让安装文档告诉使用者怎么查看默认配置、怎么写本地覆盖、怎么跑插件检查。
这一步很容易被放到后面，但它会影响维护。主链路跑通以后，最好顺手确认插件的权限和配置没有塞回主流程。
所以安装指南里应该保留插件检查命令，哪怕第一天只启用很少的插件。
发布前再看一眼仓库内容
聊天机器人部署完，最后一步别只庆祝它回话了，还要确认仓库内容没有被本地配置污染。
本地配置、群空间、日志、上传文件、聊天导出、登录缓存、私有插件开关，都不该因为一次安装被带进 Git。尤其是交互式脚本会生成不少文件，文档必须明确哪些是本机成果，哪些可以进入公开仓库。
这个检查适合写进安装指南的末尾：
run testsrun privacy scaninspect generated filescommit only templates and public code这样第一次部署就顺手建立发布习惯。以后功能越多，越不会把“能跑”误认为“能公开”。
安装指南也是产品的一部分
chatbot-qq 这种项目，写出能回消息的机器人只是开始。更麻烦的是换一台机器、换一个群、隔一段时间维护时，别人还能看懂它怎么跑。
安装指南就是这个理解入口。
它要告诉读者怎么开始、哪些地方别乱改；让新手少猜配置，让维护者能看到健康状态；跑通第一条真实消息后，还要把私有配置挡在仓库外。
对我来说，好的机器人安装文档不该只是命令列表。它应该帮第一次部署的人跑完一遍、知道哪里坏了，并且确认私有配置没有被一起提交。
继续读