同步配置注意事项

两类本地仓库

普通公共克隆保存公共仓库的提交历史，协作方式见 关于合作开发。私人生产笔记库还保存个人配置和私人内容，已配置白名单直连同步时，公共历史与本地历史分别维护，不依赖中间仓库。

本页说明两类仓库的区别与配置风险。私人生产笔记库的正式操作流程在本地 .agents/skills/sync/SKILL.md，同步范围以其 scripts/sync-paths.psd1 为唯一权威。该工具目录属于维护者的本地文件，不随公共克隆或 Release 分发；普通读者无需安装这套维护流程。

本地操作与公共发布

编辑、保存、暂存和本地提交本身不向 GitHub 发布。编辑器中的“提交并同步”可能另行调用 pull/push，需要与单纯提交区分。

私人生产笔记库通过直连入口预览、接收和发布。预览会下载公共 Git 对象、计算候选快照，不改变笔记、真实索引或远程；实际回流会留下共享内容的未暂存增改删，供审阅并本地提交。工作区因此有待处理改动，是接收内容的结果，不代表公共配置混入。

普通 Git 命令不会被直连脚本接管。对私人生产笔记库执行普通 pull、切换公共分支或按远程整体 reset，不会获得白名单隔离。

内容与目录边界

白名单之外的本地内容不传播；公共快照中的非共享内容保留原样，不检出到私人笔记目录。白名单是路径边界，不负责识别正文中的私人信息；新建学科目录是否参与同步，应核对正式清单。

笔记引用的本地附件不会因此自动发布。公共附件与公共专有内容需要独立审查维护，否则发布的笔记可能出现缺图或失效链接。

同步不创建第二份常驻工作目录，但公共历史和文件对象会保存在现有 .git 中，占用磁盘空间。本地忽略的工具、规则和任务文件也不会被普通本地提交自动备份，需要纳入已有的文件备份方式。

忽略规则与历史切换

.gitignore 管理未跟踪文件的忽略匹配，不会让已经被 Git 跟踪的配置自动脱离版本管理。私人笔记库可以在本地提交配置，同时由同步清单隔离公共发布；不能只凭“目录被忽略”判断它是否受 Git 管理。

切换分支不会无条件删除所有未跟踪文件，但仍有以下具体风险：

• 当前提交跟踪某个配置，目标提交删除该配置时，切换可能将它从工作区删除。
• 当前文件被忽略、目标分支却跟踪同一路径时，checkout 默认可能覆盖它；不能笼统声称 Git 总会保护所有未跟踪配置。Git checkout 文档说明了 --no-overwrite-ignore 的保护条件。
• skip-worktree 主要用于稀疏工作区语义，不是“任何 Git 操作都不会改配置”的保护锁，见 Git update-index 文档。

查看旧内容优先使用 git show <提交>:<路径>，不会切换当前工作区。确需完整历史工作区时，先备份个人配置并选择隔离位置；不把切换历史作为生产笔记库的日常同步方式。

冲突与撤销

直连同步依据共同基准识别两端改动。同一路径双方改成不同结果时停止，即使修改的是不同段落，也不自动选择一方。共享内容未提交或已有暂存项时，先完成本地审阅，再运行同步。

实际回流后，同步基准已经前移。若随后丢弃回流内容，不能直接当作从未接收过更新继续发布，否则恢复的旧内容可能被当作新的本地修改发布回去。撤销、中断或上游重写时，应同时核对文件与基准，恢复步骤仍以本地 sync 技能为准。

2026-03-22 的一次性公共历史迁移记录见 历史重写后的同步说明，不作为私人生产笔记库的日常操作流程。