git-sync — 全平台发布工具

将 skill/agent 代码规范化推送到码云（Gitee）、GitHub，并支持 ClawHub、SkillHub、PyPI 发布与 Release 创建。

约束

• 让位式 LLM 交互（v2.43.0） — git-sync 包含两处 LLM 决策点（文件筛除、敏感脱敏），采用让位式握手：遇到决策点时写 resume 状态文件 + exit 3 退出，把控制权交还调用方（AI 助手）。调用方写入决策文件后重跑同一命令，git-sync 检测 resume 从当前环节续跑，不从头开始。不再进程内轮询等待（旧版 v2.42.0 的 120s 轮询会占用控制权导致卡死，已废弃）
• 断点续跑 — resume_{name}.json 记录让位环节（file_filter / sensitive_scan），重跑时跳过已完成步骤。决策消费成功后 resume 自动清除
• ⚠️ 决策文件必须用 _paths.py 路径函数写入 + 全流程一条命令（v2.45.6 实战教训，铁律） — LLM 决策文件（file_filter_{name}.decisions.json / sensitive_scan_{name}.decisions.json）必须在 git-sync 脚本环境下通过 from _paths import temp_filter_decisions_path / temp_scan_decisions_path 写入并验证 exists()；让位 → 写决策 → 重跑必须放在同一条 Bash 命令里一次跑完（拆成多条命令时 temp 文件跨命令被重建/清理，必现"文件存在却读不到"→ 反复让位 exit 3 死循环，2026-08-09 git-sync 自推送重试 N 次证实）。严禁用 Write 工具或跨进程硬编码路径写入。完整写法见 references/guide.md 步骤 3.7 / 4.5 警示框
• 自动检测类型 — 自动识别 skill（_meta.json）或 agent（rglob 扫描含 __version__ 的 __init__.py，任意包目录名均可，不硬编码），分别走不同发布流程
• all 模式 — git-sync all 遍历配置的全部仓库项目（默认 skill 仓库 + agent 仓库，仓库名/路径由 config.json 的 repos 注册表决定）
• 网络依赖 — 推送 Gitee/GitHub/ClawHub/SkillHub/PyPI 需要可用网络连接，超时阈值 60 秒
• 冲突不自动合并 — git merge 冲突需人工介入
• 多仓库模型（v2.37.0） — 按项目类型解析目标仓库：get_repo_name(type) 从 config.json 的 repos 注册表匹配（type 字段：skills/agents），未配置时用默认名（skill→maby_skills、agent→maby_agent）。仓库本地路径、双平台 remote、README 文案全在注册表条目中声明，用户按需配置，技能本身通用
• 参数约束 — 项目名不含路径分隔符，version 格式严格 x.y.z
• 仓库规模 — 支持 1-50 个项目，每个 ≤ 500MB
• 数据持久性 — manifest.json 记录同步状态，不备份远程仓库数据

触发条件

正向触发：

• 「同步/上传/推送/发布某个 skill 或 agent」
• 「全量同步/全部发布」
• 「发布到 ClawHub/SkillHub/PyPI」
• 「创建 Release」
• 「打包/更新 README.md」
• 「检查版本号」

否定条件：

• 用户只是说「帮我看看这个文件」——没有同步/打包意图
• 用户要求「用 git 提交代码」——这是通用 git 操作，不是本技能

核心能力

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

• 全平台发布 —— Gitee + GitHub + ClawHub + SkillHub + PyPI，一次同步全自动
• 类型自动识别 —— skill（_meta.json）/ agent（__init__.py），版本号各自读取
• 路径统一管理（_paths.py） —— 所有路径变量（技能目录、数据目录、仓库路径、临时目录等）在 scripts/_paths.py 统一定义，其他脚本一律 from _paths import ... 引用，不各自写死；仓库路径由 config.json 的 repos 注册表配置，get_work_repo(type) 动态解析
• 路径由 manifest 统一管理 —— 每个条目记录 source_path（源路径）+ repo_path（仓库内路径），skill 和 agent 统一走同一套逻辑
• all 批量模式 —— 遍历全部 skills 和 agents 逐个同步
• LLM 文件过滤（让位式） —— 同步前扫描源文件 → 全量打印文件列表 + 规则 → 写 resume 状态 + exit 3 让位 → 调用方（AI 助手）写 file_filter_{name}.decisions.json 决策 → 重跑续跑 → 只复制允许的文件
• LLM 脱敏（强制，让位式） —— 同步后强制脱敏敏感信息（邮箱/token/路径/本地路径），无跳过选项。扫描发现敏感信息后 exit 3 让位，调用方写 sensitive_scan_{name}.decisions.json 后重跑，从脱敏环节续跑（不重复文件过滤与同步）
• 版本号三方对比 —— _meta.json / SKILL.md frontmatter / changelog
• SKILL.md 规范审查 —— 内联审计（版本一致性 + R-23 脚本引用检查）
• ZIP 打包 + HTML 索引 —— 生成安装包 + 可视化索引页
• PyPI 隔离构建 —— 拷贝源码到临时目录 → 生成 setup.py → build → twine 上传，版本号自动归一化 PEP 440，dev_status 按定稿规则判别：主版本号 <1 → Beta；≥1 时纯 x.y.z 为 Production/Stable、跟随 b（x.y.zbn）为 Beta（rc/alpha/dev 已废弃）
• Release 创建 —— git tag + GitHub/Gitee API Release（技能用 {name}-v{ver}，智能体用 v{ver}），源码包由平台自动生成

平台发布差异

渐进式文件索引

不支持：

• 通用 git 提交：本技能专注于 skill/agent 仓库同步，通用 git 操作由用户手动完成
• merge 冲突解决：遇到 git merge 冲突时不会自动合并，需要用户手动处理

快速开始

⚠️ 执行入口：环境无 rsync 时（如部分 Windows Git 环境），git-sync.sh 会自动切换到 Python 完整流程。直接调用 python git-sync.py 与 bash git-sync.sh 效果相同，推荐直接使用 Python 入口。

场景：推送技能到双平台 用户需求：skill-name=novel-weaver, 当前版本=1.35.4, 目标版本=1.36.0 系统执行：

python "$SKILLS_DIR/git-sync/scripts/git-sync.py" novel-weaver

系统输出：[1/8] 触发判断 → 继续 [2/8] 安全校验 → 通过 [3/8] 清单检查 → 升级至 1.36.0 [4/8] 文件同步 → 已复制 47 个文件 [5/8] 敏感信息脱敏 → 2 处已替换 [6/8] 更新 README → 新增 1 条 [7/8] 提交推送 → Gitee ✅ / GitHub ✅ [8/8] 打包索引 → .zip 已生成 最终输出: 码云 ✅ / GitHub ✅ → 版本 1.36.0 已同步

场景：仅打包不推送 用户需求：skill-name=git-sync, 当前版本=2.40.0, --pack-only 标志 系统执行：

python "$SKILLS_DIR/git-sync/scripts/git-sync.py" git-sync --pack-only

系统输出：[1/8] 触发判断 → 继续（--pack-only 跳过推送） [4/8] 文件同步 → 已复制 22 个文件 [8/8] 打包索引 → .dist/git-sync-v2.40.0.zip 已生成（45.2 KB，22 文件） 最终输出: .dist/git-sync-v2.40.0.zip 已生成

场景：仅推送不打包 用户需求：skill-name=workday-calendar, 当前版本=2.2.0, 目标版本=2.2.1, --push-only 标志 系统执行：

python "$SKILLS_DIR/git-sync/scripts/git-sync.py" workday-calendar --push-only

系统输出：[1/8] 触发判断 → 继续 [2/8] 安全校验 → 通过 [3/8] 清单检查 → 升级至 2.2.1 [4/8] 文件同步 → 已复制 31 个文件 [5/8] 敏感信息脱敏 → 0 处 [6/8] 更新 README → 无变化 [7/8] 提交推送 → 码云 ✅ / GitHub ✅ [8/8] 打包索引 → 跳过（--push-only） 最终输出: 码云 ✅ / GitHub ✅ → 版本 2.2.1 已同步

工作流程

1. 触发判断 → 输入 用户请求文本 → 输出 触发决策（继续/拒绝） — 解析用户请求，判断是否为同步/推送/打包意图
2. 安全校验 → 输入 目标路径 + skill 名称 → 输出 校验通过/拒绝 — 检查目标路径合法性、skill 名称白名单
3. 清单检查 + 路径解析 → 输入 manifest.json → 输出 同步状态 — 读取 manifest 条目获取 source_path/repo_path，无则按 type 走默认路径
4. 版本号对比 → 输入 仓库版本 v.s. 本地源文件 → 输出 升级/跳过/冲突 — 读取 _meta.json（skill）或 __init__.py（agent），版本号自动归一化 PEP 440
5. LLM 文件过滤 → 输入 源目录 → 输出 允许文件列表 — 扫描源目录 → 全量打印文件列表 + 决策路径 → 写 resume（phase=file_filter）+ exit 3 让位 → 调用方写 file_filter_{name}.decisions.json 后重跑，从本环节续跑 → 只复制允许的文件到 workrepo
6. 敏感信息脱敏（强制） → 输入 工作仓库文件 → 输出 脱敏后的副本 — 扫描邮箱/token/IP，发现敏感信息则 exit 3 让位，调用方写 sensitive_scan_{name}.decisions.json 后重跑。断点续跑：resume.phase=sensitive_scan 时跳过文件过滤与同步，直接从脱敏环节继续
7. 更新 README → 输入 workrepo → 输出 更新后的 README.md — 按仓库类型全量扫描（skill 仓库扫技能目录、agent 仓库扫智能体目录），重新生成 README.md（技能表格 + 智能体表格）
8. 提交推送 → 输入 提交信息 → 输出 推送状态 — git add/commit/push 到码云 + GitHub
9. ZIP 打包 → 输入 技能目录 → 输出 .zip 文件 + index.html — 将 skill 目录打包为 .zip（仅 skill，agent 跳过）
10. 市场发布（可选）→ ClawHub / SkillHub（skill）/ PyPI（agent + --pypi）
11. 创建 Release（--release 标志）→ 打 tag + 推双平台 + 创建 GitHub Release + Gitee 发行版，源码包由平台自动生成

数据目录说明

本技能的数据文件存放在技能安装目录的标准化子目录下（实际路径以 $SKILLS_DIR 为准）：

$SKILLS_DIR/.standardization/git-sync/
├── data/
│   ├── config.json     # 平台配置（repos 注册表、用户名、仓库名、gitee_token 等）
│   └── manifest.json   # 技能同步状态清单（按 repos 组织条目）
└── backup/             # 改造/更新前的自动备份

安装目录 $SKILLS_DIR/git-sync/ 只保留 SKILL.md 和 scripts/。

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为轻量入口（≤230行），详细内容拆分到 references/*.md 按需加载。完整文件清单见「核心能力 → 渐进式文件索引」表格。