用途与实际影响
这项功能怎样使用
为什么需要它
发布命令失败却仍打印成功，或只确认某个路径存在，都可能留下假的备份安心感。另一个“把远端 README 正文移进密文”的动作又会改变远端当前内容，需要与普通密文上传分开解释和确认。
举个实际例子
普通备份：“把这份明确的 vault.enc 备份到我指定的私人路径，再读回来确认大小和哈希。”独立的正文保护：“我明确要把当前远端 README 的内容转成密文，先预演，密码我在本机确认。”后一句不是前一句默认附带的动作。
最后我会得到什么
普通上传与README保护都分别报告实际写入和远端回读。README保护还核对当前说明及密文字节，响应丢失时只回读原操作；仍不能确定就保留效果未知。字节一致不证明密码可恢复，也不表示旧历史已清除或既有保险库已合并。
正常时
普通备份必须从私人目标读回同一份密文；单独保护远端说明时，也要核对当前说明与新密文。两者都不代表已经凭密码恢复原文。
发现问题时
目标或远端内容在操作中改变、写入结果不明或读回不符时，分别说清是否已经写入，不给笼统成功提示。
入口不可用或证据不足时
私人目标、权限或本人本地确认不成立时停止写入；预演和只读检查仍不算发布。
从哪里开始
在已接通本机 vault-workflow 的 AI 对话中明确要求“把这份密文备份到已核准的私人 Key”，或单独要求保护 README；两件事分别确认。
需要准备什么
- 要备份的密文或要保护的 README
- 已核准的私人目标和路径
- 本次只做哪一种动作
从开始到拿到结果
- 1
确认目标与动作
现场核对仓库私有状态、默认分支、路径及本次究竟上传密文还是处理 README。
- 2
写入并远端读回
按明确选择执行，然后从默认分支核对对应密文字节和分支；效果不明时停在未知。
- 3
分开报告恢复条件
字节一致只证明密文备份；真正取回内容还要密码、密钥文件和实际恢复演练。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
上传与回读接口已验证；未操作私人远端关键规则与设计选择
公开的是 vault-tool 工具仓库；Key 是独立私人密文目标，没有公开正文入口。
WhatIf（只读预演） 只预演，不上传；VerifyRemote（远端核验） 的树检查只证明路径存在。
README 保护改变当前版本而不重写历史，也不自动合并已有 vault（加密保险库）。
本模块用到的名词
- PRIVATE（私有仓库）
- 本次远端访问范围，必须由真实目标元数据确认；它不是来自文件名或 README 的自称。
- WhatIf（只预演）
- 检查并说明计划动作，不上传、不替换远端正文，也不能作为已有备份证据。
- read-back（从目标重新读取）
- 写入后重新取实际保存的内容并核对，区别于只相信发送请求前的本地字节。
- safe_readme_present（README 路径存在字段）
- 现有名字容易误解；它只检查树路径，不证明正文安全或已经被替换。
专业定义
先确认私人目标，再上传和逐字节回读；密文还在，不代表解锁条件一定齐全。
解决什么
防止路径存在、脚本退出码、上传提示和真正可恢复混为同一个成功状态。
当前怎样实现
- Publish-KeyVaultToGitHub.ps1 通过现有 gh（GitHub 命令行工具）使用 Contents API；先解析实际仓库私有状态与默认分支，检查明确输入、非空字节和许可扩展名。扩展名许可不是加密真实性证明。
- 更新已有路径需带当前文件 SHA；只有真实不存在才按创建处理，权限或网络错误不能静默当成没有文件。PUT 的退出码和返回结构必须被核对，失败不能继续输出 Uploaded。
- 实际成功还需从默认分支读取目标 blob（Git 文件内容对象）身份，再读取 base64 编码字节，与本次上传同一缓冲区的长度和 SHA-256 比较；提交存在与当前分支路径一致分别核对。
- 远端响应和临时请求文件包含的是密文；对调用方只返回目标、提交和指纹等元数据，不打印密文大正文，不克隆 Key，也不建立计划任务。
- VerifyRemote（远端核验）的树路径检查仍只证明路径存在，safe_readme_present不是正文安全证明。ProtectRemoteReadme另按完整字节核验受管占位说明，不接受仅含marker；existing_stub_verified不表示检验过已有密文或密码。
- ProtectRemoteReadme 是独立精确动作：WhatIf（只读预演） 不读正文、不取密码、不写远端；真实执行由本地辅助进程读取固定 source_head_sha 的 README，要求两次本地密码一致，打包单个 README 并自检。
- 正文保护写入前重新核对PRIVATE（私有）、固定source_head_sha的完整树和目标。截断树不能证明文件不存在；已有vault（加密保险库）/vault.enc而README仍为普通正文时拒绝覆盖密文。非强制提交后回读分支头、README与密文并比较SHA-256；响应丢失只核对原结果，不盲重放，无法确定时effect（外部现实动作）为null。正常换行Base64及固定blob读取均受支持。
- 恢复还需要对应密码、密钥文件、容器版本与依赖。本地 .bak、远端密文、程序测试和真正打开原文是不同恢复证据。
执行流程
- 1
明确普通密文备份，或另行明确远端README保护；不自动合并两种意图。
- 2
现场解析目标、私有状态、默认分支和精确路径，必要时先预演。
- 3
普通备份上传明确密文，再从默认分支读取blob字节和指纹。
- 4
README保护在本地确认后处理固定来源，自检候选，非强制写入后回读README、密文和分支；已经保护、实际写入和效果未知分别报告。
- 5
分别交回写入、字节核对与仍未进行的密码恢复，不把三层合称都已验收。
边界
- 本轮网站建设不授权向私人 Key 写入虚构样例，所有发布接口测试均与真实远端隔离。
- 密文读回可证明字节一致，不能确认遗失的密码或密钥文件，也不能替代真实恢复演练。
- 不创建定时备份服务、公开分享链接、第二个远端或全历史改写流程。
- 不能用一个 README 保护结果推断整个仓库及全部历史都没有原文。
失败与恢复
- 目标不是现场确认的私有仓库
- 拒绝密文发布；不会为了完成脚本而改变仓库可见性。
- 读取旧路径或 PUT 失败
- 保留明确错误，停止后续成功标记；非 404 错误不被当成新文件。
- 远端回读失败或字节不同
- 说明可能已写入但尚未完成验证，不把失败自动重试成多次未知提交。
- 正文保护被取消或远端版本变化
- 取消就不写，版本冲突不强推；固定来源与尚未执行的动作分别保留。
真实入口
E:\Projects\Tools\vault-tool\scripts\Publish-KeyVaultToGitHub.ps1私人密文上传与目标字节核对
E:\Projects\Tools\vault-tool\docs\key-repository-workflow.md人工准备、密文与恢复条件
E:\.agents\skills\vault-workflow\scripts\Invoke-VaultWorkflow.ps1VerifyRemote（远端核验）、PublishVault、预演与结果适配
E:\.agents\skills\vault-workflow\scripts\protect_remote_readme.py固定远端版本、两次本地确认与单提交正文保护
E:\.agents\skills\vault-workflow\references\json-contract.md发布、读取与真实效果字段
GitHub REST API：文件内容与 blobGitHub 官方文件对象读取合同；base64 字节与接口容量边界
如何验证
- 来源发布脚本已通过九类隔离mock gh（模拟GitHub命令）验证：PUT失败、非404错误、404创建、正常回读、回读失败、字节不符、预演、非私人目标和扩展名拒绝。
- 源库自身已normal-push并从真实main读回，但这不是向私人Key上传的结果。
- 真实私人密文发布、密码恢复和换机恢复未在本轮执行。
与其他模块的关系
本模块保存密文与解释远端材料保护；具体加密、密码和本机取回仍由前面的模块负责。实际使用例子是PRIVATE（私有）Key：用户明确采用VAULT03与独立密码，并让最高权限体系和Vault（加密保险库）分别保管一部分恢复材料。分别解锁、互不替代，单边不能代表完整材料；两处保管的材料分别满足各自取回条件；本轮未读取真实密文、密码或恢复码，也未试解密，实际恢复仍需独立验证。它与AI工作区中的配置和记忆备份分别使用。