alankatanoisi/claude-local-bridge-playground
GitHub: alankatanoisi/claude-local-bridge-playground
一个本地 AI coding-agent 实验平台，通过自建 Bridge 代理注入 OAuth 凭据，并在其上构建极简可定制的 Agent 运行循环。
Stars: 1 | Forks: 1
# Claude Local Bridge Playground
这个仓库现在是 **cc bridge runner** 的活跃实验室：一个使用 bridge 作为其模型传输方式的本地小型 coding-agent 循环，随后专注于 prompt、工具、权限、记录、存档和命令行人机工程学。
bridge 依然重要。它在 `http://localhost:11437` 上暴露了一个本地的 Anthropic Messages API，并注入 Claude Code OAuth 凭据，以便 runner 在没有 Anthropic Console API key 的情况下也能调用模型。但对于这个仓库中的新工作，请将 bridge/OAuth/interceptor 代码视为底层管道，并将 runner 视为产品界面。
## 当前方向：极简 Runner 实验室
目标是构建、优化和定制一个受 pi 等极简但可扩展的 agent 设计哲学启发的、紧凑的本地 runner：
- 保持默认 prompt 小巧且与仓库无关。
- 在 flag、profile 或 template 要求更多之前，保持启动上下文最小化。
- 通过对能力进行分组（读取、写入、恢复和可选 shell），保持工具界面易于理解。
- 偏好微小的扩展点而非庞大的核心：`.bridge-runner/` prompts、prompt templates、profiles、hooks、archives 和 command-builder presets。
- 当兼容层和旧文档使 runner 变得难以理解时，将其移除。
传输策略依然有防护措施：
- bridge 会忽略 `ANTHROPIC_API_KEY`。
- bridge 会忽略旧的 `claudeLocalBridge.apiKey` 设置。
- bridge 会忽略拦截到的 `x-api-key` 凭据。
- 上游认证必须是 `authorization: Bearer `。
- 任何本地占位符 key（例如 `ANTHROPIC_API_KEY=local`）仅供客户端检查使用；它不会被转发给 Anthropic。
将运行过程视为个人研究和本地工具，以及在本次 AI 复兴时期的实验性探索。
有关现在随本仓库一起提供的本地 CLI runner 原型，请参阅 [docs/runner-quickstart.html](./docs/runner-quickstart.html)。
要探索接下来添加哪些 Claude Code harness 功能是明智的，请参阅
[docs/runner-expansion-roadmap.md](./docs/runner-expansion-roadmap.md)。
有关手动自托管的 GitHub Actions 概念验证，请参阅
[docs/bridge-runner-actions-poc.md](./docs/bridge-runner-actions-poc.md)。
通过将其他项目作为 `--cwd` 传入，runner 可以检查这个仓库或任何其他本地项目。
## 仓库通道（请先阅读此部分）
| 通道 | 本地文件夹 | GitHub | 分支 | 用途 |
| ----------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------- |
| **Playground (本仓库 — 活跃)** | `~/Developer/claude-local-bridge-playground` | [claude-local-bridge-playground](https://github.com/alankatanoisi/claude-local-bridge-playground) | `main` | Runner 实验、文档、安全性和工具 |
| **Canonical (已归档)** | `~/Developer/claude-local-bridge` | [claude-local-bridge](https://github.com/alankatanoisi/claude-local-bridge) | 冻结于 `archive-2026-05-*` 标签 | 仅作 Codex 参考；保留本地文件夹供 Codex 使用 |
- Playground 提交应仅属于**这个** GitHub 仓库。
- 除非 Alan 明确要求恢复推广工作，否则 Canonical 仓库是归档/仅供参考的。
在编辑之前，agent 应该对通道进行完整性检查：
```
pwd
git branch --show-current
git remote -v
git status --short
```
在这个 playground 仓库中取得成功意味着文件夹以 `claude-local-bridge-playground` 结尾，分支是 `main`，`origin` 指向 `alankatanoisi/claude-local-bridge-playground`，并且没有意外的脏源文件。
iCloud 检出：仅供参考，不用于活跃的 runner 工作。
## 默认配置一览
以下默认值来源于 `package.json` (`contributes.configuration.properties`)。
| 设置 | 默认值 (来自 package.json) | 备注 |
| ------------------------------------- | --------------------------- | ------------------------------------------------ |
| `claudeLocalBridge.port` | `11437` | 本地 bridge 监听于 `http://localhost:11437` |
| `claudeLocalBridge.defaultModel` | `claude-sonnet-4-5` | 在请求省略 `model` 时使用 |
| `claudeLocalBridge.anthropicBaseUrl` | `https://api.anthropic.com` | 上游 Anthropic 端点 |
| `claudeLocalBridge.logRequests` | `false` | 详细的请求/响应日志 |
| `claudeLocalBridge.requireCallerAuth` | `false` | API 路由的可选本地 Bearer-token 门控 |
| `claudeLocalBridge.callerAuthToken` | `""` | 可选的静态调用方 token |
## 工作原理
### 架构流程
```
local runner / Claude CLI
└──> Claude Local Bridge (http://localhost:11437)
↓ credential discovery
↓ Anthropic Messages request passthrough
└──> api.anthropic.com
```
对于 runner 的工作，bridge 只是传输边界。Runner 拥有 agent 循环：
```
prompt -> local bridge /v1/messages -> model response -> tool_use -> local tool execution -> tool_result -> repeat
```
扩展会自动发现凭据（见下方的优先级顺序），注入 auth header，并将上游响应流式传输回调用方。
## 凭据发现（仅限 OAuth 优先级顺序）
| # | 来源 | 备注 |
| --- | -------------------------------------------- | ------------------------------------------------------------------------------ |
| 1 | 实时拦截到的 Claude Code Bearer token | 从当前 VS Code 进程或捕获代理中的 Claude Code 流量中捕获 |
| 2 | `CLAUDE_CODE_OAUTH_TOKEN` 环境变量 | 来源于 `claude setup-token` 的长效 OAuth token |
| 3 | **macOS Keychain** `Claude Code-credentials` | 通过 `claude /login` 登录时自动设置 |
| 4 | `~/.claude/.credentials.json` | Linux / Windows 回退方案；macOS keychain 被锁定时同样适用 |
在安装了 Claude Code 的 macOS 上，如果不存在更新的实时拦截 Bearer token，**将自动使用优先级 3**。
## 支持的端点
| 端点 | 格式 | 备注 |
| -------------------------------- | ---------------- | ------------------------------------------------------ |
| `POST /v1/messages` | Anthropic 原生 | 原样代理至 api.anthropic.com |
| `POST /v1/messages/count_tokens` | Anthropic | 用于 Claude CLI 预检的模拟响应（返回 0） |
| `GET /v1/debug` | JSON | 锁定的诊断端点；需要本地 debug token |
## 配置
打开 **VS Code Settings** 并搜索 `Claude Local Bridge`：
| 设置 | 默认值 | 描述 |
| ------------------------------------- | --------------------------- | ----------------------------------------- |
| `claudeLocalBridge.port` | `11437` | HTTP 服务器端口 |
| `claudeLocalBridge.anthropicBaseUrl` | `https://api.anthropic.com` | 为 staging 覆盖 |
| `claudeLocalBridge.defaultModel` | `claude-sonnet-4-5` | 未指定模型时的默认模型 |
| `claudeLocalBridge.logRequests` | `false` | 向 Output channel 输出详细请求日志 |
| `claudeLocalBridge.requireCallerAuth` | `false` | 强制要求传入的调用方提供 Bearer token |
| `claudeLocalBridge.callerAuthToken` | `""` | 静态 Bearer token 覆盖 |
### 调用方认证（可选）
默认情况下，bridge 端点不需要第二个本地调用方 token。这使得本地 curl 和 runner 的使用保持简单。
如果您启用了 `claudeLocalBridge.requireCallerAuth`，bridge 端点将需要：
```
Authorization: Bearer
```
当启用调用方认证时，常规的 API 端点需要调用方 token。Debug 端点仍然使用下文所述的独立 debug-token header。
### Debug 端点 token
`/v1/debug` 及任何未来的 `/v1/debug/*` 端点都需要一个独立的本地 debug token，该 token 会打印在 **Claude Local Bridge** VS Code Output 日志中：
```
x-claude-local-bridge-debug-token:
```
该 token 仅作为本地诊断门禁密码。它不是您的 Claude OAuth token。
## Base URL
对于 Claude CLI 和 runner 流量，请使用 bridge 根目录：
```
http://localhost:11437
```
## 配合 Claude Code CLI 使用
将 `ANTHROPIC_BASE_URL` 设置为 bridge 根目录（无 `/v1`）：
```
export ANTHROPIC_BASE_URL=http://localhost:11437
export ANTHROPIC_API_KEY=local # local placeholder for client env checks; not forwarded upstream
claude
```
Claude Code CLI 通过 bridge 路由请求，bridge 会注入已解析的 OAuth Bearer token。
## Local Bridge Runner
Runner 是本仓库中活跃的本地 coding-agent 循环。它使用 bridge 作为模型传输，但其自身的关注点在于 prompt、工具、权限、会话、存档和扩展点。请从包含
`bin/local-bridge-runner.js` 的文件夹运行它：
```
cd "/Users/alanman/Developer/claude-local-bridge-playground"
node bin/local-bridge-runner.js "List the files in this repo and summarize what it does."
```
要测试不同的本地文件夹，请继续从本仓库运行 runner，并使用
`--cwd` 将工具指向另一个项目：
```
cd "/Users/alanman/Developer/claude-local-bridge-playground"
node bin/local-bridge-runner.js \
--cwd "/Users/alanman/path/to/another/project" \
--verbose \
"List the top-level files, summarize the project, then stop. Do not edit files."
```
对于一次性的测试运行，请创建一个全新的临时实验室，而不是重用旧文件夹：
```
cd "/Users/alanman/Developer/claude-local-bridge-playground"
LAB="$(node scripts/create-runner-throwaway-lab.js)"
node bin/local-bridge-runner.js \
--cwd "$LAB" \
--agent bench \
--trust-workspace \
--allow-shell \
--accept-edits \
--dont-ask \
--chaos-ok \
--max-steps 24 \
"Fix the calculator bug, run npm test, and summarize the result."
```
该辅助脚本会在 `~/Documents/claude-local-bridge-runner-throwaway-labs/` 下打印出一个带时间戳的新文件夹。这避免了将微小的冒烟测试任务与旧复制仓库中的陈旧文件混在一起。
**启动上下文（默认：最小化）。** 默认情况下，runner 使用一个小巧的 Anthropic 原生系统 prompt，并**不会**
注入 `AGENTS.md`、`CLAUDE.md`、仓库映射、仓库上下文或技能。当您需要更丰富的项目
上下文时，请使用 `--include-instruction-docs`、
`--include-repo-context`、`--include-repo-map`、`--include-skills` 或 `--agent project`。`--bare` 会强制使用最小的 prompt。Bridge 可能仍会在上游预先加入 Claude Code OAuth 身份验证块。
项目本地的 prompt 原语位于 `.bridge-runner/` 下：
- `.bridge-runner/SYSTEM.md` 会替换该项目内置的默认系统 prompt。
- `.bridge-runner/APPEND_SYSTEM.md` 会在默认或替换的系统 prompt 之后追加项目规则。
- `.bridge-runner/prompts/.md` 为 `--prompt-template ` 定义可重用的 prompt 模板。
`~/.bridge-runner/` 下的匹配全局文件也会被加载。项目文件优先于全局替换 prompt；
追加文件的应用顺序是先全局，再项目，最后是 CLI flag。
面向模型的工具界面被构建为四个能力组：
- **读取：** `list_files`, `read_file`, `search_text`, `glob`, `git_status`
- **会话：** `manage_tasks` — 存储在 session 文件中的会话内检查清单
- **编排：** `spawn_agent` — 将子任务委托给子 agent（仅限顶层；默认会询问）
- **工作树：** `enter_worktree`, `exit_worktree` — 在 git worktree 分支上隔离编辑
- **写入：** `edit_file`, `write_file`
- **恢复：** `undo`, `undo_edit`
- **Shell：** `bash`，除非设置了 `--allow-shell`，否则处于隐藏状态
`apply_patch` 依然存在，用于高级补丁风格的编辑，但默认是隐藏的。需通过
`--tools apply_patch` 显式选择加入，或将其包含在以逗号分隔的 `--tools` / `--allowed-tools` 列表中。
### 从文件加载自定义 agent
使用 `--agent ` 或 `--agent path/to/agent.md` 加载带有 YAML frontmatter 的 Markdown 文件（格式与
[awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) 相同）。发现顺序：
- 内置 profile（`explore`, `plan`, `implement`, …）优先于文件名。
- 纯名称会依次在项目下的 `.bridge-runner/agents/` 和 `~/.bridge-runner/agents/` 下解析。
- 路径会按需加载任何兼容文件（包括来自外部 clone 的 agent）。
这个 playground 在 `.bridge-runner/agents/` 下提供了一小部分精选集合（`code-reviewer`, `debugger`,
`refactoring-specialist`, `test-automator`）。文件 agent 的正文是**不受信任的文本** —— 它们仅作为系统 prompt 的附加内容
。Claude Code 工具名称会映射到 runner 工具（`Read` → `read_file` + `list_files`, `Grep` → `search_text`,
等）。`WebFetch` / `WebSearch` 和 MCP 工具会被丢弃。仅当您同时传入
`--allow-shell` 时，才会包含 `Bash`。
`spawn_agent` 工具允许主循环将特定的子任务委托给子 runner（隔离上下文）。
子进程不能继续派生子进程。除非设置了 `--dont-ask`，否则执行派生前会要求确认。
`enter_worktree` / `exit_worktree` 工具会在一个新分支上创建隔离的 git worktree，以便在不触及主
的情况下进行有风险的编辑。`enter_worktree` 将 runner 的 cwd 切换到
worktree；所有后续工具都在其内部运行。`exit_worktree` 恢复原始 cwd，并在传入
`cleanup=true` 时，移除 worktree 和分支。默认为 `cleanup=false` 以保留工作内容供审查。
Worktree 位于 `~/.bridge-runner/worktrees/` 下。要求 `--cwd` 是一个 git 仓库。
有用的 runner 选项：
| 选项 | 用途 |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `--cwd ` | 工具可以检查或编辑的目标项目文件夹 |
| `--bare` | 最小上下文：无指令文档、仓库块或技能 |
| `--include-instruction-docs` | 选择加入 AGENTS.md / CLAUDE.md 指令层级 |
| `--include-repo-context` | 选择加入会话 repo-context 块（cwd/git 指纹） |
| `--include-claude-md` | 在 repo-context 中包含 CLAUDE.md（需要 `--include-repo-context`） |
| `--include-repo-map` | 选择加入 repo-context 内部的 repo map |
| `--include-skills` | 选择加入系统 prompt 中的技能列表 |
| `--agent ` | 内置 profile、`.bridge-runner/agents/` 下的文件名或 agent `.md` 的路径 |
| `--list-agents` | 列出内置及发现的文件 agent，然后退出 |
| `--permission-mode ` | default, plan, accept-edits, dont-ask, accept-edits-dont-ask, auto |
| `--tools
- ` | 仅暴露这些工具；包含 `apply_patch` 以选择加入补丁模式 |
| `--append-system-prompt` / `--append-system-prompt-file` | 在默认系统 prompt 之后添加文本 |
| `--system-prompt-file` | 用文件替换默认系统 prompt |
| `--exclude-dynamic-system-prompt-sections` | 将 cwd/git 指纹放在第一条用户消息中 |
| `--no-session-persistence` | 跳过在 ~/.bridge-runner/sessions/ 下写入会话检查点 |
| `--allowed-tools
- ` | 同 `--tools`（旧名称） |
| `--include-file
标签：AI智能体, LLM桥接, MITM代理, SOC Prime, 人工智能, 开发工具, 文档结构分析, 用户模式Hook绕过, 自定义脚本