4.2 KiB
4.2 KiB
Gitea 凭据持久化实施计划
面向 Agent 型工作者： 按任务验证后再进行真实环境操作；用户已确认设计和实施范围。
目标： 让同一执行用户的 Gitea 凭据安全持久化、跨仓库复用，并减少失效时的重复授权。
架构： 保留现有 skill，以 GCM 和平台安全凭据库为基础；将可验证的凭据迁移、诊断和 Windows OAuth 存储隔离到小工具。按实际有效配置诊断认证问题，OAuth 仅在兼容性经过验证时启用。
技术栈： Git、GCM、Python 标准库、各平台凭据库和 Markdown。
规格说明： docs/superpowers/specs/2026-11-05-gitea-credential-persistence-design.md
全局约束
- 用户和站点级复用；保留其他站点配置与旧凭据。
- 密钥不得出现在聊天、日志、命令参数、URL、环境变量或项目文件。
- 实际认证测试不能意外删除或覆盖旧凭据。
- 示例仓库不执行发布或推送；skill 项目验证通过后推送。
- 站点不支持 OAuth 或无法证明兼容时，保留可用的 PAT 路径。
审查重点
- Git 配置包含不同优先级和多个 helper 时，真实生效配置不能被误判。
- 源账号或站点不匹配、多条凭据存在歧义时，迁移须停止。
- 目标凭据已存在且不相同时，不能覆盖；源凭据始终保留。
- 失败或拒绝的认证请求不得泄露或删除凭据。
- 无图形会话或系统库锁定时，不能把短期缓存冒充持久化。
Task 1: 验证并实现安全迁移
文件： skills/updating-gitea-repositories/scripts/credential_migrate.py；tests/test_credential_migrate.py。
- 在隔离配置中用虚构 helper 和虚构凭据，验证 source
get、targetstore和跨仓库凭据匹配。 - 验证目标已存在、缺少密码、账号或站点不匹配时停止；输出不含虚构密钥；源 helper 不收到
erase或store。迁移总是选用新的隔离命名空间，不覆盖已有目标。 - 实现只接收明确源文件和 HTTPS 站点的迁移工具；通过受限子进程和内存通道传递密钥，失败时只输出非敏感原因。
- 用真实 Git 和隔离的虚构凭据运行测试，确认目标写入、原记录保留和失败保护。
Task 2: 修订 skill 和平台指南
文件： skills/updating-gitea-repositories/SKILL.md；references/repository-workflow.md、windows.md、macos.md、linux.md；必要时新增 references/credentials.md；.codex-plugin/plugin.json。
- 改为先检查和复用已有凭据，再按站点修复配置；补充不会误删凭据的诊断、迁移和 401 分流。
- Windows、macOS、WSL、Linux 指明安全持久化与实际运行位置；无图形 Linux 采用可用的持久库，说明初始化与解锁。
- 纳入条件式 OAuth 流程和 2.6.1 的刷新风险；明确需验证站点、客户端版本、权限和客户端注册，禁止写出客户端密钥。
- 更新插件版本与展示说明，并检查各入口、参考链接和脚本调用一致。
Task 3: 验证示例和交付
文件： 上述 skill 和测试；ManySkills 只允许已授权的认证配置处理。
- 运行安全迁移测试、skill 结构验证；对认证决策做独立情景检查。
- 不暴露凭据、不触发旧凭据删除地检查 ManySkills；通过浏览器完成一次授权并验证跨仓库复用。
- 确认目标项目的暂存范围、测试和远端状态，正常提交并推送，获取远端 SHA 核对结果。
- 核对市场来源锁定的上游提交及安装缓存，分别报告项目推送和市场同步状态；未经授权不修改其他市场来源。
补充：OIDC 用户与长 OAuth 令牌
- 验证真实 Gitea 站点的浏览器 OAuth、OIDC 账号及 Git 读取权限。
- 处理 Windows 自带 helper 无法同时保存长访问和刷新令牌的问题，安全复用系统凭据库并保留原记录。
- 使用隔离虚构服务验证过期后的 Git 自动刷新、轮换结果持久化及自动 erase 不删除凭据。
- 验证真实站点刷新后，ManySkills 与 skill 项目可读取新凭据；不推送 ManySkills。