xworkmate-bridge/docs/internal-reference.md

# Internal Reference

本文档记录 `xworkmate-bridge` 的内部实现参考，覆盖 package、关键 `struct` / `interface`、导出函数，以及核心运行时中的关键未导出主链路函数。

术语约定：

- “类” 在本仓库映射为 Go 的 `struct` 与 `interface`
- “接口” 同时指外部协议接口与 Go `interface`
- “参数 / 返回” 同时包含 Go 签名与运行时语义

## internal/acp

### 核心真源映射 (Core Service Mapping)

为确保高性能与就绪性可靠性，本包默认配置直连以下核心真源。开发与维护时应确保这些端口在宿主机 `127.0.0.1` 保持可用：

| 规范服务名 | 监听端口 | 协议模式 | 关键职责 |
| :--- | :--- | :--- | :--- |
| **`acp-codex.service`** | `9001` | HTTP | Codex 核心 ACP 控制面 |
| **`acp-opencode.service`** | `38992` | HTTP | Opencode 核心 ACP 控制面 |
| **`acp-gemini.service`** | `8791` | HTTP | Gemini 协议适配器 (protocol-adapter) |
| **`acp-hermes.service`** | `3920` | HTTP | Hermes 协议适配器 (stdio ACP adapter) |
| **`openclaw-gateway.service`** | `18789` | WS | OpenClaw 独立部署网关运行时，映射到 `127.0.0.1:18789` |

### 包职责

APP-facing bridge 主控面。该模块已全面切换至 **JSON-RPC 2.0** 作为默认协议。负责 HTTP / WebSocket 路由、JSON-RPC method dispatch、session / thread 队列、routing resolve、single-agent / multi-agent / gateway 执行分流，以及 provider / gateway runtime 桥接。

### 主要输入 / 输出

- 输入：HTTP 请求、WebSocket RPC frame、stdio RPC 请求、bridge 环境变量
- 输出：JSON-RPC result / error envelope、`session.update` notification、gateway 转发结果、provider 转发结果

### 关键类型

- `type Server struct`
  - 作用：bridge 运行时聚合根，持有 session map、thread queue、gateway manager、provider catalog、auth service。
  - 主要副作用：维护内存态 session / queue，并向下调用 gatewayruntime、router、mounts、dispatch、shared。

### 关键函数 / 方法

- `func Serve(args []string) error`
  - 参数：`args` 为 `serve` 子命令参数。
  - 返回：监听失败或 server 非正常退出时返回 error。
  - 副作用：创建 `http.Server`，监听 `ACP_LISTEN_ADDR`。
  - 场景：`main.go` 中的 `serve` 模式入口。

- `func NewServer() *Server`
  - 参数：无。
  - 返回：初始化后的 `*Server`。
  - 副作用：装载内建 provider catalog、gateway manager、static token auth service。
  - 场景：`Serve` 和测试中的 server 构造。

- `func (s *Server) Handler() http.Handler`
  - 参数：receiver `s *Server`。
  - 返回：统一的 HTTP handler。
  - 副作用：按路径路由到 `/`、`/api/ping`、`/bridge/bootstrap/health`、`/acp/rpc`、`/acp`。
  - 场景：bridge HTTP 服务挂载。

- `func (s *Server) HandleRPC(w http.ResponseWriter, r *http.Request)`
  - 参数：标准 HTTP writer/request。
  - 返回：无显式返回；通过 HTTP body 输出 JSON-RPC envelope。
  - 副作用：处理 CORS、auth、body decode、SSE streaming、RPC dispatch。
  - 场景：`POST /acp/rpc`。

- `func (s *Server) HandleWebSocket(w http.ResponseWriter, r *http.Request)`
  - 参数：标准 HTTP writer/request。
  - 返回：无显式返回；通过 WebSocket 发回 JSON-RPC result / notification。
  - 副作用：做 origin/auth 校验，升级连接，持续读取 RPC frame。
  - 场景：`GET /acp`。

- `func (s *Server) HandleBridgeBootstrapHealth(w http.ResponseWriter, r *http.Request)`
  - 参数：标准 HTTP writer/request。
  - 返回：无显式返回；输出 bridge health JSON。
  - 副作用：读取 `BRIDGE_SERVER_URL`。
  - 场景：bootstrap 自检或部署健康检查。

- `func RunStdio(input io.Reader, output io.Writer)`
  - 参数：stdio 输入输出流。
  - 返回：无。
  - 副作用：运行 stdio ACP bridge。
  - 场景：`acp-stdio` 模式。

### 核心未导出主链路

- `func (s *Server) handleRequest(request shared.RPCRequest, notify func(map[string]any)) (map[string]any, *shared.RPCError)`
  - 参数：解码后的 RPC 请求、通知回调。
  - 返回：成功 result map 或 RPCError。
  - 副作用：分派所有 bridge JSON-RPC 方法。
  - 场景：HTTP 与 WebSocket 统一 RPC dispatch 核心。

- `func (s *Server) executeSessionTask(task task) (map[string]any, *shared.RPCError)`
  - 参数：排队后的内部任务对象。
  - 返回：执行结果或 RPCError。
  - 副作用：强制 routing、创建 / 更新 session、按 resolved mode 分流。
  - 场景：thread queue 实际执行入口。

- `func resolveRoutingMetadataWithProviders(params map[string]any, availableProviders []string) (router.Result, bool)`
  - 参数：JSON-RPC params、当前 bridge 可用 provider 列表。
  - 返回：`router.Result` 与 “是否提供 routing” 标记。
  - 副作用：读取 routing、skill install approval、memory 偏好。
  - 场景：`xworkmate.routing.resolve` 与 session 执行前置。

- `func (s *Server) runSingleAgent(ctx context.Context, method string, session *session, params map[string]any, turnID string, notify func(map[string]any)) taskResult`
  - 参数：上下文、RPC method、session、执行参数、turnId、通知回调。
  - 返回：内部 `taskResult`。
  - 副作用：选择 provider、归一化 working directory、对外做 ACP forwarding。
  - 场景：single-agent 主路径。

- `func (s *Server) runMultiAgent(ctx context.Context, session *session, params map[string]any, turnID string, notify func(map[string]any)) taskResult`
  - 参数：上下文、session、执行参数、turnId、通知回调。
  - 返回：multi-agent 汇总结果。
  - 副作用：调用 OpenAI-compatible chat completion，产出多智能体总结。
  - 场景：复杂任务升级到 multi-agent 时。

- `func (s *Server) runGateway(ctx context.Context, method string, session *session, params map[string]any, turnID string, notify func(map[string]any)) taskResult`
  - 参数：上下文、RPC method、session、执行参数、turnId、通知回调。
  - 返回：gateway 执行结果。
  - 副作用：调用 `gatewayruntime.Manager.RequestByMode`。
  - 场景：gateway-chat / gateway 模式。

- `func (s *Server) runSingleAgentViaExternalProvider(ctx context.Context, provider syncedProvider, method string, params map[string]any, notify func(map[string]any)) (map[string]any, error)`
  - 参数：上下文、bridge 内建 provider、RPC method、转发参数、通知回调。
  - 返回：upstream ACP result 或 error。
  - 副作用：HTTP / WebSocket forwarding、auth header 选择、结果补全。
  - 场景：对 `codex` / `opencode` / `gemini` 做桥接转发。

- `func handleGatewayConnect(server *Server, params map[string]any, notify func(map[string]any)) map[string]any`
  - 参数：server、JSON-RPC params、通知回调。
  - 返回：gateway connect 结果。
  - 副作用：把 JSON 参数映射为 `gatewayruntime.ConnectRequest`，应用 production routing。
  - 场景：`xworkmate.gateway.connect`。

## internal/gatewayruntime

### 包职责

维护 gateway runtime 生命周期，包括建连、认证挑战、请求 / 响应配对、push 事件规范化、重连与快照通知。

### 关键类型

- `type Endpoint struct { Host string; Port int; TLS bool }`
  - 作用：声明 gateway endpoint。

- `type PackageInfo struct { AppName string; PackageName string; Version string; BuildNumber string }`
  - 作用：附带客户端包信息。

- `type DeviceInfo struct { Platform string; PlatformVersion string; DeviceFamily string; ModelIdentifier string }`
  - 作用：附带设备平台信息。

- `func (d DeviceInfo) PlatformLabel() string`
  - 参数：receiver `DeviceInfo`。
  - 返回：`Platform` 与 `PlatformVersion` 拼出的展示文本。
  - 场景：快照或日志展示。

- `type DeviceIdentity struct { DeviceID string; PublicKeyBase64URL string; PrivateKeyBase64URL string }`
  - 作用：携带设备标识与签名密钥材料。

- `type AuthConfig struct { Token string; DeviceToken string; Password string }`
  - 作用：承载 gateway connect 认证材料。

- `type ConnectRequest struct`
  - 参数字段：`RuntimeID`、`Mode`、`ClientID`、`Locale`、`UserAgent`、`Endpoint`、`ReportedRemoteAddress`、`ConnectAuthMode`、`ConnectAuthFields`、`ConnectAuthSources`、`HasSharedAuth`、`HasDeviceToken`、`PackageInfo`、`DeviceInfo`、`Identity`、`Auth`。
  - 作用：gateway 建连请求的完整输入对象。

- `type ConnectResult struct { OK bool; Snapshot map[string]any; Auth map[string]any; ReturnedDeviceToken string; Error map[string]any }`
  - 作用：建连返回体。

- `type RequestResult struct { OK bool; Payload any; Error map[string]any }`
  - 作用：gateway request 返回体。

- `type GatewayError struct { Message string; Code string; Details map[string]any }`
  - 作用：规范化 gateway 错误。

- `func (e *GatewayError) Error() string`
  - 返回：错误消息字符串。

- `func (e *GatewayError) DetailCode() string`
  - 返回：`Details["code"]` 的规范化 detail code。

- `func (e *GatewayError) Map() map[string]any`
  - 返回：适合写入 JSON / RPC 的错误对象。

- `type Manager struct`
  - 导出字段：`ReconnectDelay`、`ConnectTimeout`、`ChallengeTimeout`
  - 作用：gateway runtime manager，内部持有 runtime session map。

### 关键函数 / 方法

- `func NewManager() *Manager`
  - 返回：带默认重连与超时参数的 manager。

- `func (m *Manager) Connect(request ConnectRequest, notify func(map[string]any)) ConnectResult`
  - 参数：connect request、通知回调。
  - 返回：connect 结果。
  - 副作用：查找或创建 runtime session，配置 session 并发起建连。
  - 场景：`xworkmate.gateway.connect`。

- `func (m *Manager) Request(runtimeID string, method string, params map[string]any, timeout time.Duration, notify func(map[string]any)) RequestResult`
  - 参数：runtimeId、method、params、超时、通知回调。
  - 返回：request 结果。
  - 副作用：把 gateway RPC 发到已连接 runtime。
  - 场景：`xworkmate.gateway.request`。

- `func (m *Manager) RequestByMode(mode string, method string, params map[string]any, timeout time.Duration, notify func(map[string]any)) RequestResult`
  - 参数：gateway mode、method、params、超时、通知回调。
  - 返回：request 结果。
  - 副作用：按 mode 选择当前已连接 session。
  - 场景：bridge gateway 执行路径。

- `func (m *Manager) Disconnect(runtimeID string, notify func(map[string]any))`
  - 参数：runtimeId、通知回调。
  - 返回：无。
  - 副作用：断开指定 runtime session。
  - 场景：`xworkmate.gateway.disconnect`。

### 核心未导出主链路

- `func newSession(manager *Manager, runtimeID string) *session`
- `func (s *session) configure(request ConnectRequest, notify func(map[string]any))`
- `func (s *session) connect() ConnectResult`
- `func (s *session) connectAttempt() (ConnectResult, *GatewayError)`
- `func (s *session) request(method string, params map[string]any, timeout time.Duration) RequestResult`
- `func (s *session) requestRemote(method string, params map[string]any, timeout time.Duration, requireConnected bool) RequestResult`
- `func (s *session) disconnect()`
- `func (s *session) readLoop(conn *websocket.Conn, challengeCh chan string)`
- `func (s *session) scheduleReconnect()`
- `func (s *session) emitNotification(method string, params map[string]any)`

这些函数共同组成 gateway runtime 的状态机：配置、建连、读循环、请求发出、错误处理、重连调度以及 `xworkmate.gateway.snapshot` / `xworkmate.gateway.push` / `xworkmate.gateway.log` 通知发射。

## internal/router

### 包职责

根据 prompt、显式 routing、memory 偏好、provider 可用性与 skill 解析结果，决定任务应该走 `single-agent`、`multi-agent` 还是 `gateway`。

### 常量

- `RoutingModeAuto = "auto"`
- `RoutingModeExplicit = "explicit"`
- `ExecutionTargetSingleAgent = "single-agent"`
- `ExecutionTargetMultiAgent = "multi-agent"`
- `ExecutionTargetGateway = "gateway"`
- `ExecutionTargetGatewayChat = "gateway-chat"`
- `GatewayProviderOpenClaw = "openclaw"`

### 关键类型

- `type Request struct`
  - 关键字段：`Prompt`、`WorkingDirectory`、`RoutingMode`、`PreferredGatewayProviderID`、`ExplicitExecutionTarget`、`ExplicitProviderID`、`ExplicitModel`、`ExplicitSkills`、`AllowSkillInstall`、`InstallApproval`、`AvailableSkills`、`AvailableProviders`、`AIGatewayBaseURL`、`AIGatewayAPIKey`。
  - 作用：routing 计算输入。

- `type Result struct`
  - 关键字段：`ResolvedExecutionTarget`、`ResolvedProviderID`、`ResolvedGatewayProviderID`、`ResolvedModel`、`ResolvedSkills`、`SkillResolutionSource`、`SkillCandidates`、`NeedsSkillInstall`、`SkillInstallRequestID`、`MemorySources`、`Unavailable`、`UnavailableCode`、`UnavailableMessage`。
  - 作用：routing 计算输出。

- `type Resolver struct`
  - 字段：`SkillFinder`、`SkillInstaller`、`MemoryService`、`Classifier`
  - 作用：routing 聚合器。

- `type ClassificationRequest struct { Prompt string; AIGatewayBaseURL string; AIGatewayAPIKey string }`
  - 作用：传给分类器的输入。

- `type Classifier interface { Classify(req ClassificationRequest) string }`
  - 作用：抽象分类器接口。

- `type LLMClassifier struct{}`
  - 作用：默认分类器实现。

### 关键函数 / 方法

- `func NewResolver() Resolver`
  - 返回：绑定默认 skills finder / installer、memory service、classifier 的 resolver。

- `func (r Resolver) Resolve(req Request) Result`
  - 参数：routing request。
  - 返回：routing result。
  - 副作用：读取 memory、解析技能、决定 execution target / provider / gateway provider。
  - 场景：bridge session 执行前置与 `xworkmate.routing.resolve`。

- `func (LLMClassifier) Classify(req ClassificationRequest) string`
  - 参数：classification request。
  - 返回：execution target 候选字符串。
  - 场景：启发式规则未命中时的分类补充。

### 核心未导出主链路

- `func (r Resolver) resolveExecution(req Request, prefs memory.Preferences) (string, string)`
- `func (r Resolver) classify(req Request) string`
- `func mapExplicitTarget(value string, preferredGatewayProviderID string) (string, string)`
- `func resolveGatewayProvider(preferredGatewayProviderID string) string`
- `func resolveProvider(req Request, prefs memory.Preferences, availableProviders []string, executionTarget string) (string, bool, string, string)`

这些函数共同实现了 execution target 与 provider 的两阶段决策。

## internal/dispatch

### 包职责

在 provider 列表、capability 要求和 node runtime state 之间做轻量级 dispatch 解析，并产出 bridge / provider / node metadata。

### 关键类型

- `type Provider struct { ID string; Name string; DefaultArgs []string; Capabilities []string }`
- `type NodeState struct { SelectedAgentID string; GatewayConnected bool; ExecutionTarget string; RuntimeMode string; BridgeEnabled bool; BridgeState string; ResolvedCodexCLIPath string; ConfiguredCodexCLIPath string }`
- `type NodeInfo struct { ID string; Name string; Version string }`
- `type Request struct { Providers []Provider; PreferredProviderID string; RequiredCapabilities []string; NodeState *NodeState; NodeInfo *NodeInfo }`
- `type Result struct { Provider *Provider; AgentID string; Metadata map[string]any }`

### 关键函数

- `func Resolve(request Request) Result`
  - 参数：provider、capability、node state / info。
  - 返回：dispatch result。
  - 副作用：无外部 I/O；纯粹做 provider 选择和 metadata 组装。
  - 场景：`xworkmate.dispatch.resolve`。

- `func ResultMap(result Result) map[string]any`
  - 参数：dispatch result。
  - 返回：适合写回 RPC 的 map。
  - 场景：bridge handler 层输出序列化。

### 核心未导出主链路

- `func selectProvider(providers []Provider, preferredProviderID string, requiredCapabilities []string) *Provider`
  - 作用：优先选显式 provider，否则按 capability 过滤并按 ID 稳定排序。

## internal/geminiadapter

### 包职责

把 Gemini CLI / Gemini ACP stdio 协议包装成独立 HTTP / WebSocket ACP adapter，同时提供一条兼容本地 prompt runner 的 fallback 路径。

### 关键类型

- `type Server struct`
  - 作用：Gemini adapter 聚合根，持有 RPC client、auth service、provider 元数据、session map。

### 关键函数 / 方法

- `func Serve(args []string) error`
  - 参数：`gemini-acp-adapter` 子命令参数。
  - 返回：监听失败或 adapter 异常退出时返回 error。
  - 副作用：读取 `GEMINI_ADAPTER_*` 环境变量，启动 HTTP 服务。

- `func NewServer(client rpcClient) *Server`
  - 参数：Gemini ACP RPC client。
  - 返回：adapter server。
  - 副作用：绑定 auth token、provider label、allowed origins、session runner。

- `func (s *Server) HandleRPC(w http.ResponseWriter, r *http.Request)`
  - 作用：处理 `/acp/rpc`。

- `func (s *Server) HandleWebSocket(w http.ResponseWriter, r *http.Request)`
  - 作用：处理 `/acp` WebSocket。

### 核心未导出主链路

- `func (s *Server) handleRequest(request shared.RPCRequest) map[string]any`
- `func (s *Server) handleCapabilities() map[string]any`
- `func (s *Server) handleSessionRequest(method string, params map[string]any) map[string]any`
- `func (s *Server) handleCompatSessionRequest(method string, params map[string]any) map[string]any`

这些函数负责区分真实 upstream ACP 能力与本地兼容路径，并维护 adapter local session history。

## internal/toolbridge

### 包职责

默认模式下的本地 MCP-style 工具桥。负责从 stdin 读取 JSON-RPC / Content-Length frame，暴露 `chat`、`claude_review`、`vault_kv` 三个工具。

### 关键函数

- `func Run(input io.Reader, output io.Writer)`
  - 参数：输入流、输出流。
  - 返回：无。
  - 副作用：持续读取消息、解析 RPC、写回结果。
  - 场景：`main.go` 默认模式。

### 核心未导出主链路

- `func readMessage(reader *bufio.Reader) ([]byte, error)`
- `func writeMessage(output io.Writer, message map[string]any)`
- `func writeError(output io.Writer, id any, code int, message string)`
- `func handleRequest(request shared.RPCRequest) map[string]any`

## internal/service

### 包职责

认证服务层。一个分支做用户名 / 密码认证，另一个分支做 bearer token 认证。

### 关键类型与函数

- `var ErrInvalidCredentials = errors.New("invalid credentials")`

- `type AuthRepository interface { Verify(ctx context.Context, username, password string) (bool, error) }`
  - 作用：用户名 / 密码认证仓储抽象。

- `type AuthService struct`

- `func NewAuthService(repo AuthRepository) *AuthService`
  - 参数：认证仓储。
  - 返回：认证服务。

- `func (s *AuthService) Authenticate(ctx context.Context, username, password string) error`
  - 参数：上下文、用户名、密码。
  - 返回：认证成功返回 `nil`，失败返回 `ErrInvalidCredentials` 或仓储错误。

- `type StaticTokenAuthService struct`

- `func NewStaticTokenAuthService(expectedToken string) *StaticTokenAuthService`
  - 参数：期望 bearer token。
  - 返回：静态 token 服务。

- `func (s *StaticTokenAuthService) ValidateToken(token string) bool`
  - 参数：token 或 auth header。
  - 返回：是否通过校验。

- `func (s *StaticTokenAuthService) ValidateAuthorizationHeader(header string) bool`
  - 参数：HTTP `Authorization` header。
  - 返回：是否通过校验。
  - 规则：支持裸 token 和 `Bearer <token>`；若 expectedToken 为空，则接受任意非空 bearer。

## internal/handler

### 包职责

HTTP handler 适配层，把 `service` 层认证能力暴露为简单 HTTP endpoint。

### 关键类型与函数

- `type Authenticator interface { Authenticate(username, password string) error }`

- `type AuthHandler struct`

- `func NewAuthHandler(svc Authenticator) *AuthHandler`

- `func (h *AuthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)`
  - 参数：HTTP writer/request。
  - 返回：无显式返回。
  - 副作用：读取 JSON body，调用用户名 / 密码认证，返回 `200` 或 `401`。

- `func NewServiceAdapter(svc *service.AuthService) Authenticator`
  - 作用：把带 `context.Context` 的 `AuthService` 包装成 handler 所需接口。

- `type TokenAuthHandler struct`

- `func NewTokenAuthHandler(service *service.StaticTokenAuthService) *TokenAuthHandler`

- `func (h *TokenAuthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)`
  - 参数：HTTP writer/request。
  - 副作用：读取 `Authorization`，校验静态 token，成功返回 `{"ok": true}`。

## internal/memory

### 包职责

从全局 home memory、项目 home memory、项目本地 `.xworkmate/memory.md` 合并 memory，并在 auto routing 成功后把偏好写回项目级 memory。

### 关键类型与函数

- `type Source struct { Path string; Scope string }`
- `type Preferences struct { PreferredRoute string; PreferredModel string; PreferredSkills []string; Provider string }`
- `type LoadResult struct { MergedText string; Sources []Source; Preferences Preferences; ProjectFiles []string }`
- `type SuccessEntry struct { ResolvedExecutionTarget string; ResolvedProviderID string; ResolvedModel string; ResolvedSkills []string; Summary string }`
- `type Service struct { HomeDir string }`

- `func NewService(homeDir string) Service`
  - 参数：home 目录。
  - 返回：memory service。

- `func (s Service) Load(workingDirectory string) LoadResult`
  - 参数：工作目录。
  - 返回：合并后的文本、来源、偏好、项目文件路径。
  - 副作用：读文件；会过滤 token / password / secret 等敏感文本。

- `func (s Service) RecordSuccess(workingDirectory string, entry SuccessEntry) error`
  - 参数：工作目录、成功条目。
  - 返回：写入错误。
  - 副作用：向 `.xworkmate/memory.md` 或 home project memory 追加 auto route block。

## internal/mounts

### 包职责

计算 Codex / Claude / Gemini / OpenCode / OpenClaw / ARIS 的 mount 与 MCP 就绪状态，并在可行时把 managed MCP block 写入配置文件。

### 关键类型与函数

- `type ManagedMCPServer struct { ID string; Name string; Transport string; Command string; URL string; Args []string; Enabled bool }`
- `type Config struct { AutoSync bool; UsesAris bool; ManagedMCPServers []ManagedMCPServer }`
- `type ArisInput struct { Available bool; BundleVersion string; LLMChatServerPath string; SkillCount int; BridgeAvailable bool; Error string }`
- `type Request struct { Config Config; AIGatewayURL string; ConfiguredCodexCLIPath string; CodexHome string; OpencodeHome string; OpenClawHome string; Aris ArisInput }`
- `type MountTargetState struct { TargetID string; Label string; Available bool; SupportsSkills bool; SupportsMCP bool; SupportsAIGatewayInjection bool; DiscoveryState string; SyncState string; DiscoveredSkillCount int; DiscoveredMCPCount int; ManagedMCPCount int; Detail string }`
- `type Result struct { MountTargets []MountTargetState; ArisBundleVersion string; ArisCompatStatus string }`

- `func Reconcile(request Request) Result`
  - 参数：mount reconcile request。
  - 返回：所有目标的 reconcile 结果。
  - 副作用：在 `AutoSync` 打开时可能更新 Codex / OpenCode / OpenClaw 配置文件中的 managed block。

- `func ResultMap(result Result) map[string]any`
  - 作用：把 reconcile 结果序列化为 RPC 返回格式。

## internal/skills

### 包职责

解析显式技能、本地技能候选、fallback finder 和安装批准流，输出本轮应启用的技能集合及安装请求标记。

### 关键类型与函数

- `type Candidate struct { ID string; Label string; Description string; Installed bool }`
- `type Finder interface { Find(prompt string) []Candidate }`
- `type Installer interface { Install(candidates []Candidate) ([]Candidate, error) }`
- `type ResolveRequest struct { Prompt string; ExplicitSkills []string; AvailableSkills []Candidate; AllowSkillInstall bool; InstallApproval InstallApproval }`
- `type InstallApproval struct { RequestID string; ApprovedSkillKeys []string }`
- `type ResolveResult struct { ResolvedSkills []string; Candidates []Candidate; Source string; NeedsInstall bool; InstallRequestID string }`
- `type StaticFinder struct{}`
- `type ChainFinder struct { Primary Finder; Fallback Finder }`
- `type CommandFinder struct { Binary string }`
- `type CommandInstaller struct { Binary string }`

- `func Resolve(req ResolveRequest, finder Finder, installer Installer) ResolveResult`
  - 参数：技能解析请求、候选查找器、安装器。
  - 返回：resolved skills、候选、来源、安装请求。
  - 副作用：在批准条件满足时可能触发外部 installer 二进制。

- `func (StaticFinder) Find(prompt string) []Candidate`
- `func (f ChainFinder) Find(prompt string) []Candidate`
- `func (f CommandFinder) Find(prompt string) []Candidate`
- `func (i CommandInstaller) Install(candidates []Candidate) ([]Candidate, error)`
- `func NewDefaultFinder() Finder`
- `func NewDefaultInstaller() Installer`

## internal/shared

### 包职责

公共工具层：RPC envelope、参数读取、provider command 执行、OpenAI-compatible HTTP 调用、Vault KV bridge、prompt 组装等。

### 关键类型

- `type RPCRequest struct { JSONRPC string; ID any; Method string; Params map[string]any }`
- `type RPCError struct { Code int; Message string }`
- `type ToolCallParams struct { Name string; Arguments map[string]any }`
- `type VaultKVResult struct { Operation string; Mount string; Path string; Data map[string]any; Keys []string; Metadata map[string]any }`

### 关键函数

- `func DecodeRPCRequest(payload []byte) (RPCRequest, error)`
  - 参数：原始 JSON payload。
  - 返回：解码后的 RPCRequest；若 method 缺失则返回 error。

- `func WriteSSE(w http.ResponseWriter, payload map[string]any)`
  - 参数：writer、payload。
  - 副作用：按 SSE `data: ...` 形式写出。

- `func ResultEnvelope(id any, result map[string]any) map[string]any` (已升级为混合模式，支持 JSON-RPC 2.0 规范同时兼顾 legacy APP 字段)
- `func ErrorEnvelope(id any, code int, message string) map[string]any` (已升级为混合模式，确保 401 等错误能以 JSON 格式被 legacy APP 解析)
- `func NotificationEnvelope(method string, params map[string]any) map[string]any`
- `func ErrorResponse(id any, code int, message string) map[string]any`
- `func ToolTextResult(id any, content string) map[string]any`
- `func ToolErrorResult(id any, err error) map[string]any`

- `func EnvOrDefault(key, fallback string) string`
- `func StringArg(arguments map[string]any, key, fallback string) string`
- `func ListArg(arguments map[string]any, key string) []any`
- `func IntArg(raw string, fallback int) int`
- `func BoolArg(raw string, fallback bool) bool`
- `func NormalizeBaseURL(raw string) string`

- `func ResolveProviderCommand(provider, model, prompt, cwd string) (string, []string)`
  - 参数：provider、model、prompt、工作目录。
  - 返回：二进制路径和参数列表。
  - 场景：Codex / OpenCode / Claude / Gemini 命令构造。

- `func RunProviderCommand(ctx context.Context, provider, model, prompt, workingDirectory string) (string, error)`
  - 参数：上下文、provider、model、prompt、工作目录。
  - 返回：CLI 输出文本或 error。
  - 副作用：启动外部命令。

- `func NormalizeProviderWorkingDirectory(provider, requested string) (string, string)`
  - 参数：provider、请求目录。
  - 返回：规范化目录与有效目录。
  - 场景：Codex / OpenCode 目录可访问性保护。

- `func AugmentPromptWithAttachments(prompt string, params map[string]any) string`
- `func ComposeHistoryPrompt(history []string) string`
- `func CallOpenAICompatibleCtx(ctx context.Context, baseURL, apiKey, model string, messages []map[string]string) (string, error)`
- `func CallOpenAICompatible(baseURL, apiKey, model string, messages []map[string]string) (string, error)`
- `func HandleChatTool(arguments map[string]any) (string, error)`
- `func HandleClaudeReviewTool(arguments map[string]any) (string, error)`
- `func RunClaudeReview(prompt, model, system, tools string, timeout time.Duration) (string, error)`
- `func ParseClaudeJSON(raw string) (map[string]any, error)`
- `func HandleVaultKVTool(arguments map[string]any) (string, error)`

### 调用关系

- `internal/acp` 同时依赖 shared 的 RPC、provider command、OpenAI-compatible、Vault / tool helpers。
- `internal/toolbridge` 直接把 shared 作为工具实现层。
- `internal/geminiadapter` 通过 shared 运行 provider command 和读取环境变量。