# Gitea 凭据持久化设计

## 目标

让 AI 使用 `updating-gitea-repositories` 时，优先复用执行 Git 的机器上已有的安全凭据。对于同一系统用户、Gitea 站点和账号，同一个有效凭据应能用于该账号有权访问的多个仓库。首次配置、令牌失效或安全库被锁定时，仍可能需要用户参与。

本次同时处理 ManySkills 示例环境中的认证问题；ManySkills 的发布与推送继续遵照原会话的安排。完成验证后，将 skill 更新推送到本项目仓库，并核实市场获取更新的方式。

## 方案

用户选择扩展现有 skill，复用 Git Credential Manager（GCM）和操作系统提供的安全凭据库。仅在凭据迁移、安全诊断或平台兼容需要确定性处理时，增加范围明确、可验证的小型辅助脚本。

备选方案是开发独立凭据管理器。该方案能够统一控制凭据生命周期，但会引入额外的敏感代码、跨平台兼容和维护成本，本次不采用。Windows 的 OAuth 存储适配器只调用系统凭据库，不实现独立密码库或 OAuth 客户端。

## 凭据复用和配置

- 执行 Git 前，检查实际生效的站点、账号、helper、凭据库及路径匹配配置；考虑系统、用户、仓库和站点级设置的覆盖关系。
- 优先使用已有的有效凭据。只有确认缺少可用凭据或需要新的授权时，才引导用户进行相应操作；不无条件要求创建新 PAT。
- 允许 AI 自动修复该 Gitea 站点所需的当前用户级配置，并保留其他站点的设置和已有凭据。账号或凭据匹配存在歧义时，先澄清，避免覆盖或使用错误账号。
- 同一站点的多个仓库默认复用凭据，但仍尊重仓库访问权限、站点策略和用户明确配置的账号隔离要求。
- 已有旧凭据与目标账号匹配明确时，可以通过不展示凭据内容的方式复制到可用的安全凭据库；不得将密钥输出到聊天、日志、命令参数、URL、环境变量或项目文件。迁移前后保留原记录。如果原记录为明文，应告知明文副本仍然存在。
- 诊断和迁移不得未经授权删除或覆盖原凭据。考虑 Git 在认证失败时可能向 helper 发送删除请求，验证方案须防止意外清除现有凭据；无法保证时停止并说明原因。

## 不同环境

- Windows 优先使用 GCM 和 Windows Credential Manager；macOS 优先使用 GCM 和 Keychain。
- WSL 或远程环境依据 Git 实际运行的主机及可用凭据库选择方案，不根据控制端操作系统推断。
- Linux 优先使用现有可用的安全凭据库；无图形会话需要持久化时，可安装必要组件并引导初始化 GPG/pass 或其他适用的安全存储。首次设置和后续解锁可能需要用户参与。
- 不把 15 分钟内存缓存当作长期持久化方案，也不静默退回明文存储。

## 认证方式和故障处理

- 保留 GCM + PAT。站点和客户端确实支持时，可使用浏览器 OAuth 登录及令牌刷新；具体流程、权限范围、客户端注册和跨版本兼容性必须先验证。不得为了配置 OAuth 将客户端密钥或令牌明文写入 Git 配置。
- 仅在确认当前 GCM 版本阻碍所需功能时，按需更新到与系统兼容的稳定版本；普通仓库更新继续复用现有安装。
- 对认证失败，先区分凭据匹配、客户端配置、网络、服务端认证和仓库权限等可观察问题。HTTP 401 本身不足以证明令牌已过期；无法确定时明确说明，不盲目创建或撤销令牌。
- 令牌过期、被撤销或用户失去权限时，持久化不能代替重新授权。需要用户输入时，通过本地可信交互完成，不要求用户在聊天中发送密钥。

## 示例环境的已知事实

ManySkills 示例此前的凭据被 Gitea 拒绝，返回 HTTP 401。当前站点级配置使用 GCM、Windows 凭据管理器和 `useHttpPath=false`；该值覆盖仓库级通用的 `true`。现有证据不能确定 401 的具体原因。

本机 GCM 为 2.6.1。GCM 2.7.0 修复了通用 OAuth 的刷新令牌更新问题；这不是当前 PAT 认证失败的已证实原因。OAuth 路径是否受影响及是否需要升级须单独验证。

用户确认常用 OIDC 登录；该站点支持公开 OAuth 客户端和 PKCE。浏览器授权后，用户身份及两个仓库的认证读取得到验证。Git 自带 Windows 凭据助手将访问与刷新令牌合并为 UTF-16 后超过系统凭据条目大小限制；增加隔离的 Windows 凭据库适配器，以单个压缩条目保存令牌和到期时间，不使用明文文件。

以隔离虚构服务验证 Git 在令牌过期时自动刷新和保存轮换结果，并对真实 Gitea 执行一次刷新和安全库回读；真实到期时的自动刷新仍取决于 Git 和服务器的后续行为。原有凭据被保留，ManySkills 未推送。

## 验收

1. 对已有有效凭据的场景，AI 能识别并复用，避免重复要求用户创建或输入 PAT。
2. 使用隔离的 Git 配置及虚构凭据验证站点级覆盖、跨仓库匹配、不同账号、迁移保留原记录，以及输出和日志不泄露密钥。失败的认证探测不得删除原凭据。
3. 覆盖无图形 Linux 的持久化决策、凭据库锁定，以及缺少组件时的初始化流程；不能将短期缓存冒充持久化。
4. 区分 401、仓库权限不足和网络故障；无法确定原因时不宣称具体根因。验证实际支持的 OAuth 流程；不支持时保留 PAT 路径。
5. 验证 skill 的元数据、引用和关键行为。完成已授权的 ManySkills 认证处理后，使用不推送该仓库的方式确认可用；如必须由用户重新授权，明确给出安全操作步骤。
6. 推送本 skill 项目前确认变更范围并验证目标远端提交。分别报告项目仓库推送结果和市场同步结果，不假定两者等同。

## 参考

- [GCM 凭据库](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md)
- [GCM 通用 OAuth](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/generic-oauth.md)
- [GCM 2.7.0 发布说明](https://github.com/git-ecosystem/git-credential-manager/releases/tag/v2.7.0)
- [Git 凭据配置](https://git-scm.com/docs/gitcredentials)