hotplex-doc-sync

HotPlex Doc Sync — 文档防腐同步

核心原则

文档是代码的门面。过时的文档比没有文档更危险——它会误导开发者，让他们沿着错误的路径走。本 skill 的职责是确保文档永远反映代码的真实状态。

工作流程

Step 1: 建立文档清单

首先建立项目文档清单，按优先级分类：

第一优先级（项目核心文档，每次发布必须检查）：

hotplex.go                    # Version 常量
Makefile                      # VERSION 变量
CLAUDE.md                     # Project Status 版本号
AGENT.md                      # Project Status 版本号
CHANGELOG.md                  # 变更记录
README.md                     # 根 README
ARCHITECTURE.md               # 架构文档

第二优先级（模块级 README，每个 internal/*/README.md）：

internal/engine/README.md
internal/config/README.md
internal/security/README.md
internal/server/README.md
internal/persistence/README.md
internal/secrets/README.md
internal/telemetry/README.md
internal/strutil/README.md
internal/sys/README.md
internal/panicx/README.md
provider/README.md
plugins/storage/README.md
brain/README.md
chatapps/README.md

第三优先级（指南和参考文档）：

docs/configuration.md / docs/configuration_zh.md
docs/providers/*.md
docs/observability-guide.md
docs/quick-start.md
docs-site/reference/protocol.md

Step 2: 版本一致性检查

验证所有版本引用是否一致。执行：

grep 'Version = ' hotplex.go          # 获取当前版本
grep 'VERSION\s*?=' Makefile          # Makefile 版本
grep 'v[0-9]\+\.[0-9]\+' CLAUDE.md    # CLAUDE.md 版本
grep 'v[0-9]\+\.[0-9]\+' AGENT.md     # AGENT.md 版本
grep '^## \[v' CHANGELOG.md | head -1  # CHANGELOG 最新版本

常见不一致场景：

• hotplex.go 是真相来源，其他文件应与之对齐
• CHANGELOG 顶部版本号必须与 hotplex.go 完全匹配
• 如果发现不一致 → 立即修复

Step 3: 模块 README 一致性检查

对每个 */README.md，验证：

1. 包名和导入路径是否正确
2. 导出的类型/函数/常量是否在代码中存在
3. 结构描述是否与实际目录结构匹配

检查方法：

# 获取模块的导出
grep -r '^type \|^func \|^var \|^const ' --include="*.go" <module>/

# 获取 README 声称的内容
grep -E '\*\*|##|`' <module>/README.md

典型问题：

• README 提到某个 package 但实际 import path 不同
• README 列出的子目录已被删除或重命名
• README 的示例代码使用了旧 API

Step 4: API 和配置文档检查

配置文档（docs/configuration*.md）：

# 获取实际配置结构
grep -r 'type.*Config\|YAMLTag\|json:' --include="*.go" internal/config/

# 获取文档中的配置项
grep -E '^###|^##|^\s*-\s|\|' docs/configuration*.md