OpenClaw：GitHub 配置同步、按日版本与参数影响分析
能力总览（与用户任务一一对应）
| # | 能力 | 实现要点 |
|---|---|---|
| 1 | 配置在 GitHub | 用 Raw URL、Contents API 或已克隆仓库读取；私有库需 token。 |
| 2 | 从链接得「项目名」并找配置 | 解析 owner/repo；项目文件夹名默认 = repo；在仓库内搜索 配置文件/、config/ 等及 *字段说明*.md。 |
| 3 | 在工作区建项目目录 | {workspace}/{repo}/，其下为按日期的版本子目录（见下节）。 |
| 4 | 读配置与字段说明 | 成对加载；YAML 展平为点分键与表格「字段」列对齐。 |
| 5 | 下载到工作区 | 每次非最新或首次同步时，写入新版本目录内，保持与仓库相同的相对路径。 |
| 6 | 用户提问 → 解释参数与变更影响 | 必须先完成新鲜度检查；再基于当前最新版本目录作答（见「参数解释答题模板」）。 |
| — | 版本管理 | 每次成功同步用更新当日日期作为文件夹名；历史目录保留不覆盖。 |
| — | 每次提问先判断是否最新 | 比较远程 remote_ref 的 tip commit_sha 与 .openclaw-config-state.json；一致则只读 latest_version_dir；不一致则先同步再分析。 |
何时使用
- 用户提供 GitHub 仓库链接（或
owner/repo），需要定位、同步、解释配置。 - 用户问「这个参数什么意思」「改了这个会怎样」「dev 和 prod 差在哪」等——默认必须先校验本地是否仍对应远程最新提交。
核心约定
- 配置文件与说明常成对出现，例如
g3fo-user-dev.yml与g3fo-user-dev-字段说明.md。 - 字段说明里 点分路径（如
app.cache.caffeine.max-size）对应 YAML 嵌套结构；分析前将 YAML 展平再与表格对齐。
一、目录布局与元数据
1. 路径约定
- 工作区根：OpenClaw/Cursor 当前 workspace 根，或用户指定的绝对路径。
- 项目根：
{workspace}/{repo}/（repo为仓库 slug，除非用户另指定文件夹名）。 - 版本目录：
{workspace}/{repo}/{版本文件夹名}/...，其下子路径与 GitHub 仓库内相对路径一致，例如： .../2026-04-08/配置文件/g3fo-dx-dev.yml.../2026-04-08/配置文件/g3fo-dx-dev-字段说明.md
2. 版本文件夹命名
- 每次拉取远程并成功写入时新建目录（不覆盖旧目录）。
- 默认名：同步当日日期
YYYY-MM-DD（在回复中说明所用时区，如 UTC+8）。 - 同一天多次同步：若该目录已存在，使用
YYYY-MM-DD_2、YYYY-MM-DD_3或YYYY-MM-DDTHHmm（任选一种，与state一致）。
3. 元数据文件（必须）
路径：{workspace}/{repo}/.openclaw-config-state.json
用于记录「当前应读哪一版」以及「上次同步时远程 ref 指到哪一提交」。所有「当前配置」类读取只认 latest_version_dir 指向的目录。
建议字段：
| 字段 | 含义 |
|---|---|
owner, repo |
GitHub 坐标 |
remote_ref |
跟踪的分支名或 tag（如 main、v1.2.0） |
commit_sha |
同步时该 ref 在远程的 tip 完整 SHA |
latest_version_dir |
当前应使用的版本目录名（如 2026-04-08） |
synced_at |
ISO 时间戳（可选） |
tracked_paths |
已同步的配置与说明文件在仓库中的相对路径（可选） |
示例：
{
"owner": "acme",
"repo": "g3fo-config",
"remote_ref": "main",
"commit_sha": "a1b2c3d4e5f6789abcdef0123456789abcdef01",
"latest_version_dir": "2026-04-08",
"synced_at": "2026-04-08T10:30:00+08:00",
"tracked_paths": [
"配置文件/g3fo-dx-dev.yml",
"配置文件/g3fo-dx-dev-字段说明.md"
]
}
二、每次用户提问时的强制顺序：先判断是否最新
在回答任何依赖「仓库里当前配置内容」的问题之前（解释参数、影响、环境对比等），先执行本节。未完成判断前，不要仅凭旧本地文件下结论。
步骤 A：确定跟踪目标
- 从用户链接或对话中确定
owner、repo、remote_ref（无则默认main或仓库默认分支，见 API）。 - 若不存在
.openclaw-config-state.json：视为非最新，进入「全量同步」后再分析。
步骤 B：查询远程 tip SHA
- 使用 GitHub API 获取
remote_ref当前指向的 commit SHA（分支 tip 或 tag 解析对象）。 - 与
state.commit_sha比较（remote_ref须一致；若用户改跟踪分支/tag，一律重新同步并更新remote_ref）。 - 默认策略：以 ref 的 tip commit 为准；任一新推送都会触发重新拉取，避免遗漏同分支上其它提交带来的配置变更。
- 可选：仅当
tracked_paths下文件变更才更新（需按路径查 last commit，更省带宽但实现更复杂）。
步骤 C：判定与动作
| 条件 | 动作 |
|---|---|
SHA 一致 且 latest_version_dir 存在 |
仅 Read 该目录下文件，再进行分析或解释。 |
| SHA 不一致 或 无 state | 新建版本目录 → 发现并下载配置与 *字段说明*.md → 更新 state → 简短告知用户（版本目录名、短 SHA）→ 再分析。 |
步骤 D：远程不可用时的降级
若 API 失败（网络、权限、限流）：
- 不得静默假装最新；应说明失败原因。
- 可在用户同意下，使用
state.latest_version_dir对应目录中的上次成功快照，并明确标注「未校验远程，可能已过期」。 - 若用户指定只分析某历史日期目录，可跳过 B，但须声明依据的是哪一版本地快照。
三、全量同步子流程（首次或过期时）
在「步骤 C」要求同步时执行：
- 按「版本文件夹命名」规则新建目录（不覆盖已有日期目录）。
- 发现文件：在仓库内搜索
配置文件/、config/等及.yml/.yaml/.properties与成对的*字段说明*.md（见 reference.md）。 - 下载：Raw 或 Contents API 拉取正文，写入新版本目录内，相对路径与仓库一致。
- 写入/更新
.openclaw-config-state.json：commit_sha、latest_version_dir、remote_ref、tracked_paths、synced_at。 - 私有仓库：确保环境具备
GITHUB_TOKEN或等价方式（见 reference）。
四、在通过新鲜度检查之后：分析工作流
1. 定位仓库与配置路径（若同步时尚未完成）
解析 URL；若只给根链接，按典型目录与扩展名搜索；记录 remote_ref 与默认分支。
2. 获取内容
优先 Raw URL；目录列举用 API；本地已有克隆则可直接 Read。
3. 解析配置与字段说明
- 每个配置文件匹配同目录或同前缀的字段说明。
- YAML 展平；properties 键直接对齐。
- 从 Markdown 表格提取字段路径、类型、说明。
4. 回答「改了什么、会怎样」
有两次状态（两文件、两 commit、或片段）：
- 做点分键 diff；逐键查字段说明；无说明的键单独列出。
- 使用下方「变更摘要」模板。
仅描述意图（如「把 Redis 库从 2 改成 5」）：
- 映射到键；引用说明；区分文档确定项与推断项。
变更摘要（输出模板）
## 变更摘要
- 共 N 个键变化（M 个有文档依据）
| 配置键 | 原值 | 新值 | 文档摘要 | 可能影响 | 风险 |
|--------|------|------|----------|----------|------|
| ... | ... | ... | ... | ... | 低/中/高 |
## 文档未覆盖的键
- ...
## 建议验证
- 重启/热更新是否生效
- 依赖服务（DB/Redis/注册中心）是否一致
参数解释答题模板（单个或若干键）
## 参数说明（基于当前最新版本目录：{latest_version_dir}，commit 短 SHA：{short_sha}）
| 配置键 | 当前值 | 含义（文档） | 若修改的典型影响 | 风险 |
|--------|--------|--------------|------------------|------|
| ... | ... | ... | ... | 低/中/高 |
- 若某键无文档：标注「文档未覆盖」，推断须标明为推断。
风险分级参考
- 高：鉴权、密钥、生产 URL、关闭安全策略、数据隔离。
- 中：端口/注册发现、限流重试、缓存、连接池。
- 低：日志级别、非关键超时、仅本地开发开关。
注意事项
- 禁止在对话或日志中输出完整密钥、密码、Token；可用掩码。
- 私有仓库需 read 权限；无权限时引导用户配置 token 或提供可访问路径。
- 不同环境文件之间值不同未必是错误，先确认对比的是否为同一环境/同一文件。
附加资源
- URL、API、点分键、一致性判断细节见 reference.md。
