62 lines
4.2 KiB
Markdown
62 lines
4.2 KiB
Markdown
# 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 路径。
|
||
|
||
## 审查重点
|
||
|
||
1. Git 配置包含不同优先级和多个 helper 时，真实生效配置不能被误判。
|
||
2. 源账号或站点不匹配、多条凭据存在歧义时，迁移须停止。
|
||
3. 目标凭据已存在且不相同时，不能覆盖；源凭据始终保留。
|
||
4. 失败或拒绝的认证请求不得泄露或删除凭据。
|
||
5. 无图形会话或系统库锁定时，不能把短期缓存冒充持久化。
|
||
|
||
## Task 1: 验证并实现安全迁移
|
||
|
||
**文件：** `skills/updating-gitea-repositories/scripts/credential_migrate.py`；`tests/test_credential_migrate.py`。
|
||
|
||
- [x] 在隔离配置中用虚构 helper 和虚构凭据，验证 source `get`、target `store` 和跨仓库凭据匹配。
|
||
- [x] 验证目标已存在、缺少密码、账号或站点不匹配时停止；输出不含虚构密钥；源 helper 不收到 `erase` 或 `store`。迁移总是选用新的隔离命名空间，不覆盖已有目标。
|
||
- [x] 实现只接收明确源文件和 HTTPS 站点的迁移工具；通过受限子进程和内存通道传递密钥，失败时只输出非敏感原因。
|
||
- [x] 用真实 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`。
|
||
|
||
- [x] 改为先检查和复用已有凭据，再按站点修复配置；补充不会误删凭据的诊断、迁移和 401 分流。
|
||
- [x] Windows、macOS、WSL、Linux 指明安全持久化与实际运行位置；无图形 Linux 采用可用的持久库，说明初始化与解锁。
|
||
- [x] 纳入条件式 OAuth 流程和 2.6.1 的刷新风险；明确需验证站点、客户端版本、权限和客户端注册，禁止写出客户端密钥。
|
||
- [x] 更新插件版本与展示说明，并检查各入口、参考链接和脚本调用一致。
|
||
|
||
## Task 3: 验证示例和交付
|
||
|
||
**文件：** 上述 skill 和测试；ManySkills 只允许已授权的认证配置处理。
|
||
|
||
- [x] 运行安全迁移测试、skill 结构验证；对认证决策做独立情景检查。
|
||
- [x] 不暴露凭据、不触发旧凭据删除地检查 ManySkills；通过浏览器完成一次授权并验证跨仓库复用。
|
||
- [ ] 确认目标项目的暂存范围、测试和远端状态，正常提交并推送，获取远端 SHA 核对结果。
|
||
- [ ] 核对市场来源锁定的上游提交及安装缓存，分别报告项目推送和市场同步状态；未经授权不修改其他市场来源。
|
||
|
||
## 补充：OIDC 用户与长 OAuth 令牌
|
||
|
||
- [x] 验证真实 Gitea 站点的浏览器 OAuth、OIDC 账号及 Git 读取权限。
|
||
- [x] 处理 Windows 自带 helper 无法同时保存长访问和刷新令牌的问题，安全复用系统凭据库并保留原记录。
|
||
- [x] 使用隔离虚构服务验证过期后的 Git 自动刷新、轮换结果持久化及自动 erase 不删除凭据。
|
||
- [x] 验证真实站点刷新后，ManySkills 与 skill 项目可读取新凭据；不推送 ManySkills。
|