# GitHub 本地管理器

给 Windows 用户使用的本地 GitHub 工具与项目管理器。提供浏览器管理面板，也可以接入 Codex，通过聊天查看清单和检查更新。

**这是为小白做的工具。** 希望把散落在电脑里的 GitHub 项目、下载的源码、npm 工具和插件放在一个容易看懂的页面里，减少“装在哪里、怎么更新”的困惑。欢迎大家反馈问题、改进界面、补充文档和参与开发。

[下载安装包](https://github.com/chenlu882/github-local-manager/releases/latest) · [新手操作文档](docs/USAGE.md) · [反馈问题](https://github.com/chenlu882/github-local-manager/issues) · [贡献指南](CONTRIBUTING.md)

## 第一次使用

1. 下载 `github-local-manager-0.3.0-windows.zip`，解压到你准备长期保留的位置，例如 `E:\应用\GitHub本地管理器`。不要直接在压缩包里运行，也不要在接入 Codex 后随意移动目录。
2. 电脑需安装 **Node.js 20 或更高版本**。如果没有，请从 [Node.js 官网](https://nodejs.org/) 安装 LTS 版本，再重新打开启动入口。包内不附带 Node.js，不会自动安装它。
3. 双击 **启动管理器.cmd**。会在默认浏览器打开仅供本机访问的页面。
4. 首次页面会显示设置引导。选择 Git 项目目录、下载目录和 npm 工具安装目录，每行一个完整目录；留空表示不扫描该分类目录。确认后点击“保存并开始扫描”。也会只读识别当前用户的 Codex 插件缓存与配置引用的 npm 工具，以及所配置 DSH profile 的插件记录。
5. 以后双击同一启动入口即可使用。需要调整范围时点击页面“设置”。

若没有安装 Git，仍可查看其他清单，但 Git 更新不可用。可安装官方 [Git for Windows](https://git-scm.com/downloads/win)，或在高级设置填写已有 `git.exe` 路径。npm 工具检查和更新需要完整 npm 环境。不会自动安装 Git、Node.js 或其他工具。

## 接入 Codex（可选）

先完成首次设置，再双击 **接入Codex.cmd**。它只追加 `github_local_manager` MCP 项，保留原有设置，并在个人数据目录备份原配置。随后重新连接 MCP 或重启 Codex。

可以直接说：

- “列出本地 GitHub 工具和项目。”
- “检查这个 npm 工具有没有更新。”
- “给这个项目准备更新计划，先别执行。”
- “打开本地 GitHub 管理面板。”

如果已经存在同名的不同管理器，接入程序会停止，不擅自覆盖。请先在 Codex MCP 设置中确认旧项。目录移动后，原接入路径不会自动更新。

也附带 `plugin.json`、`mcp.json` 和 `skills/`，可供支持 Agent Plugins 本地安装的桌面宿主使用；具体安装入口以宿主版本为准。`mcp.json` 通过 `${PLUGIN_ROOT}` 启动打包好的服务器。普通用户无需自己改写配置或执行 npm install。**不要同时用本地插件和 CMD 重复接入。**

## 支持的功能

| 分类 | 查看 | 检查与确认后更新 |
|---|---|---|
| npm 外部工具 | 是 | 是，安装确认的具体版本 |
| GitHub Git 仓库 | 是 | 是，仅快进到确认提交 |
| DSH 插件 | 是 | 只读，请在 DSH 管理 |
| Codex 插件缓存 | 是 | 只读，缓存不等于运行状态 |
| GitHub 源码包 | 名称和目录特征识别 | 只读 |

更新前会展示名称、路径、当前版本、目标和影响。用户确认后才执行。计划十分钟内有效且只能使用一次；有未提交文件、分叉、游离 HEAD 或没有上游时，不会强行更新 Git 项目。npm 安装可能执行目标包的安装脚本。

本工具不删除、不卸载、不提供任意命令执行。扫描不是全盘搜索，可能漏掉范围外目录、嵌套仓库或特殊部署方式。

## 本地数据与权限

数据保存位置：如果有 E 盘，默认 `E:\项目\GitHub本地管理器数据`；否则为当前用户主目录下 `.github-local-manager`。首次设置页会显示实际路径。高级用户可用 `GITHUB_MANAGER_HOME` 指定其他数据目录。程序不会在宿主管理的插件缓存内写入个人设置。

MCP 使用本地 STDIO。管理页面另用随机的 127.0.0.1 端口与随机访问凭据，只接受本机可信来源；不公开部署网站。不需要 GitHub Token 或 OpenAI API Key，但 Git/npm 更新会使用已有本机凭据与注册表配置并联网。

不要分享地址中 `#` 后的访问片段，也不要公开个人数据目录、日志、Codex 配置或运行时文件。关闭页面不会结束后台服务；同一安装再次启动会复用服务，电脑重启后需重新打开。

这份 ZIP 不是 OpenAI 公共目录已上架插件，也没有签名的安装 EXE。它是可从 GitHub Release 分发的、需要 Node.js 的解压即用包。当前验证环境为 Windows、Node.js 24.20.0；构建目标为 Node 20，其他版本由 CI 配置覆盖，尚未声称远端 CI 已运行。

## 欢迎改进与二次开发

本项目采用 [MIT 许可证](LICENSE)。所有人都可以在此基础上修改、二次开发、再发布或用于商业项目；分发时请保留原版权声明和 MIT 许可声明。你可以独立维护自己的版本，无需逐次向作者申请。提交到本仓库的修改请通过 Fork → Pull Request，由仓库所有者审核同意后合并。

### 希望有人把它做成 Codex 插件

这是作者面向新手做的一次尝试。**希望有兴趣的开发者能一起改进，把它完善成更好安装、更好用的 Codex 插件，争取上架 Codex 插件目录（商城），让更多小白方便使用。** 欢迎 Fork 后独立开发，也欢迎提交 PR 一起完善。

目前提供本地管理面板、MCP 接入方式及本地插件相关文件，尚未上架 Codex 官方插件目录。是否能上架、如何审核和提交，以平台届时的官方要求为准。

## 开发

源码 ZIP 或仓库中的开发命令：

```text
npm ci
npm run build
npm test
```

构建生成 `dist/` 和 `THIRD_PARTY_NOTICES.txt`；发布包包含依赖的打包代码，不包含 node_modules。`scripts/pack.ps1` 生成干净的运行包与源码包，不收录个人配置、日志、备份和测试数据。

许可证：[MIT](LICENSE)。打包第三方许可见 `THIRD_PARTY_NOTICES.txt`。