Local Proxy

local-proxy

路径约定（先看这里）

下文命令里的 <skill目录> 指本技能所在目录，也就是本文件所在的那个目录：

• AI 调用时：直接用技能元信息里给出的 base directory，不要猜、不要沿用别人机器上的路径。
• 人工使用时：替换成你自己的实际路径 —— 用户级 ~/.workbuddy/skills/local-proxy，项目级 <项目>/.workbuddy/skills/local-proxy。
• <node24> 指本机 Node ≥ 24 的 node.exe 绝对路径（只有「Node 脚本里要用 fetch」时才需要；其它场景用当前 node 即可）。

运行期数据（订阅地址、settings.json、生成的配置、日志）固定在 ~/.workbuddy/local-proxy/， 与技能目录装在哪无关 —— 所以技能目录随便挪，不用重新配置。

解决什么问题

AI 需要访问外网（最典型的是 git push 到 GitHub），但用户系统上并没有开 VPN。 本 skill 在同一次工具调用内完成：启动本地代理内核 → 把代理注入这条命令的环境变量 → 执行 → 关闭内核。 不碰系统代理开关、不建虚拟网卡、不改路由表和 DNS。

用之前，只需要准备一样东西：订阅地址

这是唯一的必填项。没有它 skill 跑不起来；除此之外所有东西都已自带。

1. 打开你机场（VPN 服务商）的官网 → 用户中心 → 找「一键订阅」或「Clash 订阅」→ 复制链接
2. 把链接单独一行粘贴进 ~/.workbuddy/local-proxy/subscription.txt（不要加引号、不要有空格）
3. 跑一次让配置生效：

node "<skill目录>/scripts/proxy.mjs" refresh

看到 config written 加一行套餐信息（已用流量 / 到期日）就成功了。

订阅地址等同于你的账号密码：不要发给别人，不要贴进聊天，不要提交进 git 仓库。

如果跳过这步直接跑 run，skill 会停下来并打印上面这三步 —— 它不会瞎猜，也不会拿别的代理顶替。

铁律（不得违反）

1. 绝不用 TUN 模式，绝不写系统代理（注册表 ProxyEnable），绝不改 DNS 或路由表。 只用 mixed-port 端口模式 + 环境变量注入。TUN 才会动系统网络，端口模式不会。
2. 代理只监听 127.0.0.1。订阅原文里写的是 allow-lan: true + bind-address: '*'（等于把代理暴露给整个局域网）， 生成配置时会强制覆盖为 false / 127.0.0.1，不要绕过这一步去手工改配置文件。
3. 订阅地址等同于账号密码，不得打印到对话、写入日志或提交进 git 仓库。 它保存在 ~/.workbuddy/local-proxy/subscription.txt。

环境要求

必需（缺任何一个都跑不起来）

可选（只影响对应的那类操作，缺了不影响别的）

不需要：管理员权限、不用装 VPN 客户端、不用改任何系统设置、不用另外下载内核或 GeoIP 库（都已随 skill 自带）。

一条命令确认全部依赖：

node "<skill目录>/scripts/proxy.mjs" doctor

输出分 host / skill 两段：[!!] 是必须修的，[--] 是可选项缺失（正常）。

主用法

node "<skill目录>/scripts/proxy.mjs" <命令> [参数]

需要联网的命令一律套在 run 里：

# 单条命令
node "<skill目录>/scripts/proxy.mjs" run "git push origin main"

# 多条命令串起来（推荐，一次调用只启动一次内核）
node "<skill目录>/scripts/proxy.mjs" run "git add -A && git commit -m \"update\" && git push"

# ssh:// 远程的仓库要加 --ssh
node "<skill目录>/scripts/proxy.mjs" run --ssh "git push origin main"

命令表

关键限制（务必先读，否则会误判）

1. 必须用 run，不能指望 up 之后的进程还活着

沙箱在每次工具调用结束时回收整个进程树，所以上一条调用里 up 起来的内核，下一条调用就没了 （status 会显示 DOWN + pid ... (stale)）。 因此启动与执行必须落在同一次调用内 —— 这正是 run 做的事。

2. 各类客户端是否认 HTTP_PROXY 环境变量（实测）

Node 写脚本要用 fetch 时，改走 v24：

node "<skill目录>/scripts/proxy.mjs" run "\"<node24>\" your-script.mjs"

（<node24> = 本机 Node ≥ 24 的 node.exe 绝对路径，见开头「路径约定」。）

3. SSH 远程要加 --ssh

git@github.com:... 这类远程不走 HTTP 代理。加 --ssh 后 skill 会生成一份临时 ssh 配置并通过 GIT_SSH_COMMAND 注入， 只影响这条命令的子进程。

两个本机实测结论：

• 这个机场不通 github.com:22 —— CONNECT 返回 200 但永远等不到 SSH banner， 所以 github.com / gist.github.com 被自动改写到 ssh.github.com:443（GitHub 官方的备用端点），实测可拿到 banner。
• 使用 --ssh 会把主机密钥写入 ~/.ssh/known_hosts（等价于首次连接时确认），属于预期行为。

用 HTTPS 远程的话不需要 --ssh；凭据的事见 §4。

4. 首次推送可能需要凭据（不要假设已经存过）

git 本身可能就不在 PATH 上（便携版 git 很常见）。doctor 里那行 [--] git 只在你不用 git 时才无所谓 —— 要用就先确认调得到，调不到就写全路径。

凭据同理，不要假设已经存过：~/.gitconfig 不存在、凭据管理器里没有 git:https://github.com，都是常态。这时第一次 git push 必然需要交互式登录， 在非交互环境里表现为命令卡住不动。

遇到这种情况不要反复重试：先停掉卡住的命令，让用户在自己的终端里手动 git push 一次完成登录。 只要那次选择把凭据存进了凭据管理器，之后 AI 就能静默使用。

要探测先禁用交互再加超时，否则会被凭据 helper 挂住： 设 GIT_TERMINAL_PROMPT=0，用 Git Credential Manager 的话再加 GCM_INTERACTIVE=never。

5. 要调 GitHub API 时怎么拿凭据

先探测，不要假设有。 唯一的途径是 git credential fill，而本机没存过凭据时 它会挂起等输入 —— 所以必须像下面这样禁用交互，并自己加超时：

const c = spawn('git', ['credential', 'fill'], {
  stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' },
});
c.stdin.end('protocol=https\nhost=github.com\n\n');   // 从 stdout 解析出 password，仅用于 Authorization 头

有输出才用 token，且绝不能把 token 打印出来或落盘； 没有输出（或超时）就是没有凭据 —— 此时不要重试，直接告诉用户需要先手动登录一次， 或由用户提供 PAT 后再继续。凭据一旦存好，同一段代码就能静默复用。

电脑上已经开了 VPN / 代理软件时会怎样

结论：绝大多数情况完全正常，两者并列共存，互不干扰。

两点值得单独说：

1. 内核启动时会被主动剥掉代理环境变量（coreEnv()）。原因：如果环境里 HTTP_PROXY 指向 127.0.0.1:7891，一个"听话"的内核会连上自己形成死循环。内核本身就是代理，不需要再走代理。
2. 本 skill 从不修改系统代理，也从不关闭别人的代理。 它和系统里已有的 VPN 是并列关系，不是替代关系。所以"电脑上开着 VPN"和"用这个 skill"可以同时成立。

顺带一提：既然已经有全局代理在跑了，你也可以直接用它 —— 但那是全局生效的、需要你手动开。本 skill 的价值在于按需、只给单条命令，用完即走。

配置

端口 7891 是特意避开 Clash for Windows 的 7890 的，两者可以同时存在、互不干扰。

排错

先跑 doctor，再看 references/troubleshooting.md。