发布记录不是营销文案#

chatbot-qq 这种项目天然离私域现场很近。

它要接 QQ，要通过 NapCat 收消息，要用 OneBot 作为协议面，还要把不同群、不同私聊、不同工作区路由到 cc-connect。工程上需要记录的是这套骨架：路由怎么拆、插件怎么管、测试怎么写、公开包怎么过滤。

但运行现场本身不适合公开，也没必要公开。

真实 QQ 号、群号、私有路由、Windows 本地路径、日志、聊天导出、NapCat token、provider key，这些东西即使不是每一项都算传统意义上的“密钥”，也不该进入公开仓库。它们会把一个可复用的工程项目，变成一份暴露个人现场的快照。

所以发布记录要写清楚两类变化：

• 能力变化：插件平台、测试、文档、示例配置。
• 公开包变化：脱敏、占位符、忽略规则、公开包检查。

如果 CHANGELOG 只写功能，会很像普通更新列表；把公开包处理也写进去，几年后回看才知道当时怎么发布的。

CHANGELOG 里要看得见删改#

Changed 和 Security 这两段值得重点关注。

很多项目的 changelog 会把它们写得很薄，好像只有 Added 才需要展示。但对自用机器人来说，公开发布前最重要的工作往往正好发生在删改里。

比如：

1
Redacted real IDs and local Windows paths.
2
Hardened public release examples with placeholder IDs.
3
Generated local config remains ignored.

这些句子不炫，但它们说明公开规则真的被处理过。

相比一句“修复若干问题”，这些记录更容易定位当时检查过什么：ID、路径、示例配置、默认路由、生成文件、发布包。

如果以后发现公开仓库里误混入了不该出现的内容，也能回到 changelog 追问：当时声称处理了哪一类？是扫描没覆盖，还是后续改动绕过了检查门？

插件平台也需要发布回执#

插件平台听起来像功能，其实也在管能力怎么拆。

群聊机器人能力越多，越不能把所有逻辑继续塞进 OneBot 代理。提醒、画图、文件处理、状态查询、维护命令，如果都共享一堆全局开关和隐式权限，后面很难判断某个功能到底能读什么、能写什么、坏了会不会拖垮主链路。

所以发布记录里不应只留一句“新增插件系统”，还要补上这些检查点：

• 插件配置示例是否可公开。
• 插件本地测试是否覆盖关键行为。
• 插件权限是否通过 manifest 声明。
• 插件失败是否只影响自己。
• 插件默认配置是否会泄露运行现场。

这几项写进 changelog，等于给后续功能加了一条路标：新能力先放进插件，再进公开发布检查，别直接挤进主入口。

示例配置必须用占位符#

机器人项目公开时，示例配置很容易出问题。

因为配置文件通常最像真实运行现场。开发时为了方便，可能会把某个测试群、某个私聊用户、某个本机路径写进去。功能跑通以后，这些值就容易跟着文档、测试、默认配置一起被提交。

公开仓库里的示例配置应该反过来设计：先假设它会被复制、会被搜索、会被别人照着改。

所以它只能放占位符和结构：

1
group_id = "123456789"
2
workspace = "groups/sandbox-123456789"
3
token = "<set locally>"

占位符不是敷衍。它让读者看懂结构，又不会把作者自己的运行环境一并带出去。

同样，生成出来的本地配置、运行状态、日志、聊天导出，应该默认被 ignore。公开仓库保留的是模板，不是机器当时的记忆。

发布包要能回答“为什么安全”#

一次公开发布，除了确认项目能跑，还得说明这个包为什么适合放到公开仓库。

发布前至少应留下几类检查结果：

• 文档里没有真实账号和本地绝对路径。
• 示例配置只使用占位符。
• 运行时文件和私有记忆不在仓库里。
• 插件测试能独立跑，不依赖真实 QQ 登录态。
• release notes 和 changelog 能解释这次版本的公开包变化。

这些结果不一定都要展示给读者，但维护者自己要有。

否则公开发布会变成一件很靠记忆的事：大概删过了，记得没问题，应该不会泄漏。这样的发布方式不适合机器人项目。机器人项目的麻烦通常是代码、配置、日志、账号和群空间混在一起，泄漏点未必只是一行代码。

能公开的是骨架，不是现场#

个人自动化项目公开时，最需要写清楚的是：如何把能力和现场分开。

chatbot-qq 公开出来最有用的部分，是 NapCat/OneBot/cc-connect 的接法，是路由代理的分层，是插件 manifest 的约束，是隐私审计和发布记录的习惯。

真实群聊、真实账号、真实路径、真实日志，都只是这个骨架在某台机器上的一次运行。

CHANGELOG 写细一点，就会从更新列表变成发布回执。它会记录：功能发布了，公开仓库里也只该留下可复用的工程结构，私有运行环境要留在仓库外。

这类记录看起来不热闹，但以后出问题时，它比一段漂亮介绍有用得多。