# AI Skill Manager Windows 设计规格 ## 背景 本项目是一个基于 Wails 的 Windows 桌面应用，用于从 Gitea 组织仓库中发现、下载、更新和安装 AI skill。首版面向 Codex 和 Claude 两个目标应用，后续可以扩展到其他应用。 项目约束： - 不使用 git worktree。 - 一个 Gitea 仓库对应一个 skill。 - 只有仓库根目录存在 `SKILL.md` 时，才认为该仓库是有效 skill。 - 本地只保留一份 skill 仓库，安装到目标应用时使用 Windows 目录 Junction，不复制完整目录。 ## 首版范围 首版包含三类页面： 1. 配置页 2. 远程市场页 3. 本地管理页 首版支持： - 配置 Gitea `baseURL`、认证方式、账号密码或 Token、组织名。 - 默认使用账号密码认证，同时支持 Token 认证。 - 从指定 Gitea 组织读取仓库列表。 - 只展示根目录存在 `SKILL.md` 的仓库。 - 将 skill 仓库 clone 到本地应用数据目录。 - 对已下载仓库执行手动更新和自动更新。 - 将本地 skill 通过 Junction 安装到 Codex 和 Claude。 - 从 Codex 和 Claude 卸载本软件创建的 Junction。 - 删除本地 skill 仓库。 - 使用 VS Code 打开 skill 目录。 - 使用资源管理器打开 skill 目录。 首版不包含： - 多 Gitea 实例或多组织同时管理。 - GitHub、GitLab 或其他代码托管源。 - skill 版本选择、回滚和发布管理。 - 自动解决本地未提交改动。 - 批量安装、批量卸载和批量删除。 ## 路径约定 应用数据目录： ```text %APPDATA%\sgg-ai-skill-manager ``` 配置文件： ```text %APPDATA%\sgg-ai-skill-manager\config.json ``` 状态文件： ```text %APPDATA%\sgg-ai-skill-manager\state.json ``` 本地仓库目录： ```text %APPDATA%\sgg-ai-skill-manager\repos\{org}\{repo} ``` Codex skill 目录： ```text C:\Users\{user}\.codex\skills ``` Claude skill 目录： ```text C:\Users\{user}\.claude\skills ``` ## 认证设计 配置页提供两种认证方式： - 账号密码认证，作为默认方式。 - Token 认证，作为可选方式。 敏感信息不明文写入 `config.json`。配置文件只保存认证方式和凭据引用标识，真实密码或 Token 优先保存到 Windows Credential Manager。 如果 Windows Credential Manager 写入失败，保存配置失败并提示用户，不降级为明文保存。 Gitea API 调用规则： - 账号密码模式使用 Basic Auth。 - Token 模式使用 `Authorization: token `。 Git clone 和 pull 的认证规则： - 首版优先调用系统 `git`。 - 账号密码或 Token 仅在执行 git 命令时从 Credential Manager 读取到内存中使用，不写入 `config.json`、`state.json` 或仓库 remote URL。 - clone 后仓库 remote URL 保存为不含密码和 Token 的普通 HTTPS URL。 - 如果认证失败，错误显示在对应仓库状态上，不阻塞整个应用。 ## Gitea 仓库发现 远程市场页通过 Gitea API 读取组织仓库： ```http GET /api/v1/orgs/{org}/repos ``` 列表需要分页加载。每个仓库再检查根目录是否存在 `SKILL.md`。只有检查通过的仓库出现在远程市场页。 远程市场页展示字段： - 仓库名 - 描述 - 默认分支 - 最近更新时间 - 本地状态：未下载、已下载、可更新、检查失败 搜索行为： - 首版在已加载的远程仓库结果中按名称和描述进行本地过滤。 - 后续可以扩展为服务端搜索。 ## 页面设计 ### 配置页 配置项： - Gitea baseURL - 认证方式：账号密码或 Token - 用户名 - 密码 - Token - 组织名 - 自动更新开关，默认开启 - 启动时检查更新开关，默认开启 - 定时检查间隔，默认 60 分钟 操作： - 保存配置 - 测试连接 测试连接需要验证： - baseURL 可访问 - 凭据有效 - 当前账号能访问指定组织 ### 远程市场页 远程市场页用于发现和下载 skill。 主要控件： - 搜索框 - 刷新按钮 - 仓库列表 仓库操作： - 下载：本地不存在时执行 `git clone` - 更新：本地存在时执行更新检查和 `git pull` - 打开本地：本地存在时打开目录 下载目标： ```text %APPDATA%\sgg-ai-skill-manager\repos\{org}\{repo} ``` ### 本地管理页 本地管理页用于管理已下载 skill 和目标应用安装状态。 建议使用表格布局，字段包括： - 名称 - 本地路径 - 当前 commit - 更新状态 - Codex 安装状态 - Claude 安装状态 - 操作 操作包括： - 手动更新 - 安装到 Codex - 卸载 Codex - 安装到 Claude - 卸载 Claude - VS Code 打开 - 文件夹打开 - 删除本地 VS Code 打开使用： ```powershell code . -n ``` 命令执行目录为对应 skill 本地仓库目录。 文件夹打开使用 Windows 资源管理器打开对应目录。 ## Junction 安装语义 安装到 Codex 或 Claude 时，不复制 skill 文件，而是在目标 skills 目录创建同名 Junction。 示例： ```text C:\Users\{user}\.codex\skills\{repo} -> %APPDATA%\sgg-ai-skill-manager\repos\{org}\{repo} C:\Users\{user}\.claude\skills\{repo} -> %APPDATA%\sgg-ai-skill-manager\repos\{org}\{repo} ``` 安装规则： - 如果目标 skills 目录不存在，安装时创建该目录。 - 如果目标路径不存在，创建 Junction。 - 如果目标路径是本软件记录的 Junction，且指向当前 skill 本地路径，可以重建或保持不变。 - 如果目标路径是普通目录、文件、或指向其他位置的 Junction，标记为冲突，不自动删除。 - 安装成功后写入 `state.json`。 卸载规则： - 只卸载本软件记录的目标。 - 删除前再次确认目标是 Junction，且指向当前 skill 本地路径。 - 确认通过后，只删除 Junction 本身，不删除本地 skill 仓库。 - 如果目标不是预期 Junction，卸载失败并提示冲突。 删除本地 skill 规则： - 如果 skill 已安装到 Codex 或 Claude，先卸载对应 Junction。 - 如果任一 Junction 无法安全卸载，则阻止删除本地仓库。 - Junction 清理完成后，再删除本地仓库目录。 ## 后端模块 ### config 职责： - 读取和保存 `config.json`。 - 管理自动更新设置。 - 管理 Credential Manager 中的密码或 Token 引用。 ### gitea 职责： - 测试连接。 - 读取组织仓库。 - 检查仓库根目录 `SKILL.md`。 - 获取仓库默认分支和远程最新 commit。 ### gitops 职责： - 检查系统 `git` 是否可用。 - 执行 clone。 - 执行 fetch 和 pull。 - 获取当前 commit。 - 获取远程 commit。 - 检测工作区是否存在未提交改动。 ### skillstore 职责： - 管理本地仓库目录。 - 读取和保存 `state.json`。 - 记录本地 skill 元数据。 - 根据本地路径扫描已下载 skill。 ### targets 职责： - 管理 Codex 和 Claude 两个目标应用。 - 检测目标 skills 目录是否存在。 - 创建 Junction。 - 识别 Junction 目标。 - 卸载 Junction。 - 识别安装冲突。 ### updater 职责： - 启动后执行更新检查。 - 按配置间隔执行定时检查。 - 对无本地改动的已下载 skill 自动 pull。 - 记录更新失败原因。 ## 状态文件设计 `config.json` 示例： ```json { "gitea": { "baseURL": "https://gitea.example.com", "org": "ai-skills", "authType": "password", "username": "user", "credentialKey": "sgg-ai-skill-manager:gitea" }, "update": { "autoUpdate": true, "checkOnStartup": true, "intervalMinutes": 60 } } ``` `state.json` 示例： ```json { "skills": [ { "org": "ai-skills", "repo": "lark-base", "localPath": "C:\\Users\\wdh\\AppData\\Roaming\\sgg-ai-skill-manager\\repos\\ai-skills\\lark-base", "remoteURL": "https://gitea.example.com/ai-skills/lark-base.git", "defaultBranch": "main", "currentCommit": "abc123", "lastCheckedAt": "2026-05-13T14:00:00+08:00", "lastError": "", "installedTargets": { "codex": { "path": "C:\\Users\\wdh\\.codex\\skills\\lark-base", "linkType": "junction", "targetPath": "C:\\Users\\wdh\\AppData\\Roaming\\sgg-ai-skill-manager\\repos\\ai-skills\\lark-base" }, "claude": { "path": "C:\\Users\\wdh\\.claude\\skills\\lark-base", "linkType": "junction", "targetPath": "C:\\Users\\wdh\\AppData\\Roaming\\sgg-ai-skill-manager\\repos\\ai-skills\\lark-base" } } } ] } ``` ## 自动更新策略 默认开启自动更新。 启动时： 1. 读取 `state.json`。 2. 对已下载 skill 执行更新检查。 3. 如果远程 commit 比本地新，且本地没有未提交改动，执行 `git pull`。 4. 如果 skill 已安装到 Codex 或 Claude，因为目标应用读取的是 Junction，pull 完成本身即完成同步。 5. 如果更新失败，记录错误并在本地管理页显示。 定时检查： - 按配置的分钟间隔执行。 - 同一时刻只允许一个更新任务运行。 - 用户手动更新时，如果后台正在更新同一个 skill，需要返回“正在更新”状态。 本地改动处理： - 如果发现本地仓库有未提交改动，不执行自动更新。 - 状态显示为“本地有改动”。 - 首版允许用户打开目录或 VS Code 手动处理。 - 首版不自动 stash、reset 或覆盖本地改动。 ## 错误处理 错误状态应落到具体对象上，避免一个仓库失败影响其他仓库。 常见错误： - Gitea baseURL 不可访问。 - 凭据无效。 - 当前账号无组织访问权限。 - 仓库没有 `SKILL.md`。 - 系统未安装 `git` 或 `git` 不在 PATH。 - clone 或 pull 认证失败。 - 本地仓库存在未提交改动。 - 目标 skills 目录不存在。 - 目标路径存在同名普通目录。 - 目标路径存在未知 Junction。 - Junction 删除前校验失败。 用户可见错误需要包含： - 失败对象，例如仓库名或目标应用名。 - 简短原因。 - 可执行建议，例如“检查配置”“打开本地目录处理改动”“手动处理同名目录”。 ## 安全规则 - 不自动删除用户已有普通目录。 - 不自动删除未知 Junction。 - 不自动覆盖本地仓库未提交改动。 - 不明文保存 Gitea 密码或 Token。 - 删除本地 skill 前必须先安全清理本软件创建的 Junction。 - 所有路径操作使用绝对路径。 - 删除操作限定在应用管理目录或记录中的目标 Junction 路径内。 ## 验收标准 配置： - 能保存 Gitea baseURL、认证方式、账号密码或 Token、组织名。 - 能测试连接并识别组织访问权限。 - 敏感信息不出现在 `config.json` 明文中。 远程市场： - 能读取组织仓库列表。 - 只展示根目录存在 `SKILL.md` 的仓库。 - 能按名称和描述搜索。 - 能下载未下载 skill。 - 能更新已下载 skill。 本地管理： - 能展示已下载 skill 的路径、commit 和安装状态。 - 能安装到 Codex。 - 能安装到 Claude。 - 安装结果是 Junction，不是目录复制。 - 能卸载 Codex 和 Claude 的 Junction。 - 卸载不会删除本地仓库。 - 能删除本地 skill，并先清理本软件创建的 Junction。 - 遇到同名普通目录或未知 Junction 时不会自动覆盖。 - 能用 VS Code 打开 skill 目录。 - 能用资源管理器打开 skill 目录。 自动更新： - 启动时能检查已下载 skill 是否有更新。 - 无本地改动时能自动 pull。 - 已安装 skill 更新后，Codex 和 Claude 通过 Junction 能读取最新内容。 - 有本地未提交改动时不会自动覆盖。 ## 后续扩展方向 首版采用轻量 MVP，但保留模块边界，后续可以扩展： - 更多目标应用。 - 多个 Gitea 组织。 - 多个代码托管源。 - 批量操作。 - 更新日志和版本回滚。 - skill 元数据解析和分类。