添加qiming-rcoder模块

2026-06-01 13:54:52 +08:00
parent 8092c4b1f8
commit 4b1a580132
539 changed files with 151650 additions and 0 deletions
--- a/qiming-rcoder/.qoder/repowiki/zh/content/附录/变更日志.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/附录/变更日志.md
@@ -0,0 +1,339 @@
+# 变更日志
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [Cargo.toml](file://Cargo.toml)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
+- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
+- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
+- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件旨在系统化梳理 RCoder 项目在版本迭代中的变更，围绕功能更新、缺陷修复与架构演进，结合代码库中的实际实现，解释变更日志在版本控制、升级路径与向后兼容性中的作用，并提供升级评估与问题排查的最佳实践。由于仓库未包含 CHANGELOG.md 文件，本文将基于现有 README 与源码，对 v0.1.0 版本的现状与关键特性进行总结，并给出面向未来的变更日志模板与生成建议，以便团队在后续版本中持续完善。
+
+## 项目结构
+RCoder 采用多 crate 的工作区组织，核心模块包括：
+- 主应用与路由：rcodes/rcoder
+- Pingora 反向代理封装：crates/pingora-proxy
+- Docker 容器管理：crates/docker_manager
+- 共享类型与协议：crates/shared_types
+- 代理适配器与示例：acp_adapter、claude-code-agent、codex-acp-agent 等
+
+```mermaid
+graph TB
+subgraph "工作区"
+A["crates/rcoder<br/>主应用/路由/配置/代理启动"]
+B["crates/pingora-proxy<br/>Pingora 反向代理库"]
+C["crates/docker_manager<br/>Docker 管理器/镜像选择/全局实例"]
+D["crates/shared_types<br/>共享模型/多镜像配置"]
+E["crates/acp_adapter<br/>ACP 协议适配"]
+F["crates/claude-code-agent<br/>Claude 代理示例"]
+G["crates/codex-acp-agent<br/>Codex 代理示例"]
+end
+A --> B
+A --> C
+A --> D
+A --> E
+A --> F
+A --> G
+```
+
+图表来源
+- [Cargo.toml](file://Cargo.toml#L1-L20)
+- [README.md](file://README.md#L269-L378)
+
+章节来源
+- [Cargo.toml](file://Cargo.toml#L1-L20)
+- [README.md](file://README.md#L269-L378)
+
+## 核心组件
+- 主应用与配置系统：命令行参数、环境变量、配置文件三段式优先级，支持代理与 Docker 配置的加载与覆盖。
+- Pingora 反向代理：Axum + Pingora 的双服务架构，主服务提供 API/SSE，Pingora 独立监听代理端口，路径前缀路由到目标后端。
+- Docker 管理器：全局单例、镜像选择策略、容器生命周期管理、清理任务与网络/挂载配置。
+- 共享类型：多镜像配置结构、服务类型枚举、镜像选择器与缓存策略。
+
+章节来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L210)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
+- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L40-L120)
+
+## 架构总览
+RCoder 采用“主服务 + Pingora 代理”的双服务架构：
+- 主服务（Axum）：提供健康检查、聊天、SSE 实时进度、代理状态/配置/统计等接口。
+- Pingora 代理：独立监听代理端口，按路径前缀 /proxy/{port}/{path} 转发到指定后端，支持动态后端发现与健康检查。
+
+```mermaid
+graph TB
+Client["客户端"] --> Axum["主服务(Axum)<br/>端口: config.port"]
+Client --> Pingora["Pingora 代理<br/>端口: proxy_config.listen_port"]
+Axum --> API["业务 API/SSE"]
+Axum --> ProxyDocs["/proxy/* 文档接口"]
+Pingora --> Backend["后端服务<br/>127.0.0.1:{port}"]
+```
+
+图表来源
+- [README.md](file://README.md#L133-L206)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+
+章节来源
+- [README.md](file://README.md#L133-L206)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+
+## 详细组件分析
+
+### 变更日志模板与生成建议
+为保证变更日志的可追溯性与可维护性，建议采用如下模板（示例，非仓库既有内容）：
+- 版本号：vX.Y.Z
+- 发布日期：YYYY-MM-DD
+- 关键变更
+  - 新增：新增 API 端点、代理支持类型扩展、配置系统优化、可观测性增强等
+  - 修复：缺陷修复、兼容性问题修正、性能回归修复等
+  - 变更：架构调整、依赖升级、行为变更、弃用项等
+- 升级指引：影响范围、破坏性变更、迁移步骤、兼容性说明
+- 问题排查：常见问题、诊断方法、相关日志位置
+
+说明：本仓库未包含 CHANGELOG.md 文件，本文基于现有 README 与源码总结 v0.1.0 的现状与关键特性，作为后续版本变更日志的参考。
+
+章节来源
+- [README.md](file://README.md#L627-L652)
+
+### v0.1.0 版本要点（基于现有 README 与源码）
+- 新增功能
+  - 基于 ACP 协议的 AI 代理统一管理（Codex、Claude Code）
+  - HTTP API 接口与统一 SSE 进度流
+  - 多层配置系统（命令行 > 环境变量 > 配置文件 > 默认）
+  - OpenTelemetry 集成与分布式追踪
+  - Swagger UI API 文档
+  - 项目文件解析器（Nuwax Parser）
+- 技术特性
+  - 基于 Rust 2024 Edition
+  - 异步架构（Tokio）
+  - 模块化设计（Workspace Crates）
+  - 实时通信（SSE）
+  - 结构化日志（Tracing）
+
+章节来源
+- [README.md](file://README.md#L627-L652)
+
+### Pingora 反向代理能力与变更要点
+- 能力概述
+  - 独立监听代理端口，路径前缀路由到目标后端
+  - 支持动态后端发现与健康检查
+  - 提供状态、配置、统计等查询接口（Axum 文档接口）
+- 关键实现
+  - 主应用在启动时根据配置创建 Pingora 服务器管理器，并在后台启动
+  - 路由中提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
+  - 代理库提供便捷函数与错误类型，支持快速启动与错误处理
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Axum as "主服务(Axum)"
+participant Router as "路由"
+participant Pingora as "Pingora 代理"
+participant Backend as "后端服务"
+Client->>Axum : "GET /proxy/status"
+Axum->>Router : "匹配 /proxy/*"
+Router-->>Client : "返回状态/配置/统计(文档接口)"
+Client->>Pingora : "GET /proxy/{port}/{path}"
+Pingora->>Backend : "转发到 127.0.0.1 : {port}"
+Backend-->>Pingora : "响应"
+Pingora-->>Client : "返回代理响应"
+```
+
+图表来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
+- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
+
+### Docker 容器管理与镜像选择能力
+- 能力概述
+  - 全局 DockerManager 单例，支持自动检测平台、镜像选择与缓存
+  - 多镜像配置结构，支持服务类型（rcoder/agent-runner）与架构（arm64/amd64）选择
+  - 项目级镜像覆盖与环境变量注入
+- 关键实现
+  - DockerManagerConfig 默认配置与全局初始化
+  - ImageSelector 选择策略（ServiceOnly），支持缓存与校验
+  - 容器生命周期管理、清理任务与网络/挂载配置
+
+```mermaid
+classDiagram
+class DockerManager {
+new(config)
+create_container(config)
+get_multi_image_config()
+}
+class DockerManagerConfig {
+docker_host
+default_image
+default_platform
+default_network_mode
+default_work_dir
+auto_cleanup
+container_ttl_seconds
+multi_image_config
+}
+class ImageSelector {
+select_image(service_type, project_overrides)
+get_service_config(service_type)
+}
+class MultiImageConfig {
+services
+global_defaults
+selection_strategy
+cache_config
+}
+DockerManager --> DockerManagerConfig : "使用"
+DockerManager --> ImageSelector : "创建并使用"
+ImageSelector --> MultiImageConfig : "读取配置"
+```
+
+图表来源
+- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
+- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)
+
+章节来源
+- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
+- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)
+
+### 配置系统与升级影响评估
+- 配置优先级
+  - 命令行参数 > 环境变量 > 配置文件 > 默认配置
+- 代理配置
+  - 主应用根据命令行与配置文件决定是否启用 Pingora 代理及其监听端口、默认后端端口等
+- 升级影响评估
+  - 若新增代理端口参数或健康检查配置项，需确保命令行与环境变量覆盖逻辑一致
+  - Docker 配置新增字段时，应提供默认值与校验逻辑，避免破坏性变更
+
+```mermaid
+flowchart TD
+Start(["启动"]) --> ParseCLI["解析命令行参数"]
+ParseCLI --> LoadFile["加载配置文件(若存在)"]
+LoadFile --> ApplyEnv["应用环境变量覆盖"]
+ApplyEnv --> MergeProxy["合并代理配置(端口/默认后端)"]
+MergeProxy --> Validate["验证配置(含 Docker 多镜像)"]
+Validate --> InitDocker["初始化 DockerManager(全局单例)"]
+InitDocker --> StartProxy{"是否启用代理?"}
+StartProxy --> |是| RunProxy["启动 Pingora 代理服务"]
+StartProxy --> |否| RunMain["启动主服务(Axum)"]
+RunProxy --> Done(["完成"])
+RunMain --> Done
+```
+
+图表来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+
+章节来源
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+
+## 依赖关系分析
+- 工作区与依赖
+  - 工作区包含多个 crate，主应用默认成员包含 rcoder、agent_runner、shared_types、docker_manager、acp_adapter、claude-code-agent、pingora-proxy
+  - 依赖包括 axum、tokio、clap、utoipa、pingora、bollard 等
+- 组件耦合
+  - rcoder 依赖 pingora-proxy 与 docker_manager，通过配置与全局实例进行解耦
+  - 共享类型在 rcoder 与 docker_manager 之间传递，避免重复定义
+
+```mermaid
+graph LR
+rcoder["rcoder"] --> pingora_proxy["pingora-proxy"]
+rcoder --> docker_manager["docker_manager"]
+rcoder --> shared_types["shared_types"]
+docker_manager --> shared_types
+```
+
+图表来源
+- [Cargo.toml](file://Cargo.toml#L1-L20)
+
+章节来源
+- [Cargo.toml](file://Cargo.toml#L1-L20)
+
+## 性能考量
+- 双服务架构
+  - 主服务与 Pingora 代理并行运行，互不阻塞，提高吞吐与隔离性
+- 代理性能
+  - 基于 Rust 异步 I/O 的高性能代理，支持动态后端发现与健康检查
+- 观测性
+  - OpenTelemetry 与 Tracing 集成，便于定位性能瓶颈与异常
+
+章节来源
+- [README.md](file://README.md#L133-L206)
+- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
+
+## 故障排查指南
+- 代理请求未转发
+  - 确认请求是否发送到 Pingora 监听端口，而非主服务端口
+  - 检查路径前缀是否符合 /proxy/{port}/{path}
+- 后端不可达
+  - 确认目标后端端口已启动且可访问
+- Docker 相关
+  - 检查 Docker socket 路径、权限与挂载
+  - 查看全局 DockerManager 初始化日志与清理任务输出
+
+章节来源
+- [README.md](file://README.md#L193-L206)
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L351)
+
+## 结论
+- v0.1.0 版本已具备核心能力：统一 AI 代理接入、HTTP API 与 SSE、Pingora 反向代理、Docker 容器管理与多镜像配置、可观测性与文档化。
+- 变更日志应聚焦于功能新增、缺陷修复与架构变更，并提供升级指引与兼容性说明。
+- 建议在后续版本中补充 CHANGELOG.md，并建立自动化生成与校验流程，确保变更可追溯、可审计。
+
+## 附录
+
+### 变更日志生成最佳实践
+- 自动化生成
+  - 使用 Git 标签与提交信息生成候选条目
+  - 通过 CI 校验变更类型（feat/fix/refactor/chore）与语义化版本
+- 人工审核
+  - 评审破坏性变更与迁移成本
+  - 补充升级指引与兼容性说明
+- 模板字段
+  - 版本号、发布日期、变更类型、影响范围、修复问题、相关 PR/Issue
+
+### 代码级变更示例（基于现有实现）
+- 代理端口与默认后端端口
+  - 主应用根据配置创建 Pingora 服务器管理器并启动
+  - 路由提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
+- Docker 镜像选择
+  - ImageSelector 采用 ServiceOnly 策略，优先使用服务特定镜像，支持缓存与校验
+  - DockerManagerConfig 默认配置与全局初始化，支持项目级镜像覆盖
+
+章节来源
+- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
+- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L250-L415)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/附录/常见问题解答.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/附录/常见问题解答.md
@@ -0,0 +1,353 @@
+# 常见问题解答
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [CLAUDE.md](file://CLAUDE.md)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+- [config.yml](file://config.yml)
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
+- [service.rs](file://crates/pingora-proxy/src/service.rs)
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
+- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本FAQ面向初学者与专家用户，围绕安装配置、AI代理集成、反向代理路由、SSE进度流中断等高频问题，结合代码库中的实际实现，提供现象、根因、解决方案与预防措施，并给出可复现的排查步骤与日志分析技巧。文档同时整合跨组件问题（如配置优先级冲突导致的行为异常），帮助快速定位与修复。
+
+## 项目结构
+- 主应用（Axum）负责业务API、会话管理与SSE进度流
+- Pingora代理独立监听端口，按路径前缀“/proxy/{port}/{path}”转发到指定后端
+- 两者并行运行，互不阻塞；Axum中的“/proxy/...”路由仅作文档与重定向到Pingora
+
+```mermaid
+graph TB
+A["客户端"] --> B["Axum 主服务"]
+A --> C["Pingora 反向代理"]
+B --> D["API 路由"]
+B --> E["Agent 工作者(LocalSet)"]
+C --> F["后端: 127.0.0.1:{port}"]
+```
+
+图表来源
+- [README.md](file://README.md#L16-L30)
+
+章节来源
+- [README.md](file://README.md#L16-L30)
+
+## 核心组件
+- 配置系统：命令行 > 环境变量 > 配置文件 > 默认值，优先级明确
+- 反向代理：Pingora提供端口路由、路径重写、指标统计与健康检查
+- 观测性：Tracing + OpenTelemetry，统一注入trace_id，便于跨服务串联
+- 容器化：DockerManager动态创建容器，内部网络通信，自动路径解析与挂载
+- SSE：统一的实时进度流接口，便于前端消费
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [config.yml](file://config.yml#L1-L30)
+
+## 架构总览
+- 主服务与代理并行：Axum提供REST API与SSE；Pingora独立监听代理端口
+- 代理请求必须发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
+- 代理模式下不支持查询参数提取端口（遵循“代理端口提取规则”）
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Axum as "Axum 主服务"
+participant Proxy as "Pingora 代理"
+participant Backend as "后端服务(127.0.0.1 : {port})"
+Client->>Axum : "GET /proxy/status" (文档/状态)
+Axum-->>Client : "307 重定向到 Pingora 端口"
+Client->>Proxy : "GET /proxy/{port}/{path}" (直接请求代理端口)
+Proxy->>Proxy : "提取端口/重写路径"
+Proxy->>Backend : "转发请求"
+Backend-->>Proxy : "响应"
+Proxy-->>Client : "返回响应"
+```
+
+图表来源
+- [README.md](file://README.md#L133-L206)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L253-L354)
+
+章节来源
+- [README.md](file://README.md#L133-L206)
+
+## 详细组件分析
+
+### 反向代理路由失败
+- 现象
+  - 请求误发到Axum主服务端口的“/proxy/...”路由，收到307重定向
+  - 收到JSON演示响应而非真实转发
+  - 端口提取失败（路径非“/proxy/{port}/{path}”或端口非法）
+- 根因
+  - 代理模式仅支持路径前缀提取端口，不解析查询参数
+  - 未指定目标后端端口或端口不可达
+- 解决方案
+  - 直接请求Pingora监听端口，路径格式为“/proxy/{port}/{path}”
+  - 确认目标后端服务已在本机启动且端口有效
+- 预防措施
+  - 在客户端或网关层统一走Pingora端口
+  - 使用代理状态/配置/统计接口辅助排障
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> CheckPort["检查路径是否为 /proxy/{port}/{path}"]
+CheckPort --> ValidPort{"端口是否为有效数字?"}
+ValidPort --> |否| FixPath["修正路径格式为 /proxy/{port}/{path}"]
+ValidPort --> |是| BackendUp{"目标后端(127.0.0.1:{port}) 是否启动?"}
+BackendUp --> |否| StartBackend["启动后端服务"]
+BackendUp --> |是| Forward["转发到后端"]
+FixPath --> End(["结束"])
+StartBackend --> End
+Forward --> End
+```
+
+图表来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+
+章节来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+
+### SSE进度流中断
+- 现象
+  - 客户端SSE连接断开，无法持续接收进度事件
+- 根因
+  - 代理层或上游服务超时、连接中断、NAT/防火墙丢弃空闲连接
+  - 客户端未正确处理长连接或网络波动
+- 解决方案
+  - 保持客户端长连接，合理设置心跳与重连策略
+  - 在代理层开启健康检查与负载均衡，避免后端不稳定导致中断
+- 预防措施
+  - 使用代理统计接口观察活跃连接数与失败率
+  - 在主服务侧确保SSE通道稳定，避免阻塞
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+### Docker权限问题
+- 现象
+  - 容器创建失败、镜像拉取失败、无法获取容器日志
+- 根因
+  - Docker socket权限不足或未挂载
+  - 容器内无法访问宿主机路径映射
+- 解决方案
+  - 确保Docker socket挂载到容器并具备读写权限
+  - 在compose中设置正确的环境变量（如DOCKER_SOCKET_PATH）
+  - 使用容器自检测器进行socket连通性与容器ID解析验证
+- 预防措施
+  - 启动时先验证Docker连接，再执行容器操作
+  - 在CI/本地开发环境统一挂载策略
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者"
+participant Compose as "Docker Compose"
+participant RC as "RCoder 容器"
+participant Inspect as "ContainerSelfInspector"
+Dev->>Compose : "启动服务"
+Compose->>RC : "挂载 /var/run/docker.sock"
+RC->>Inspect : "初始化并验证Docker连接"
+Inspect-->>RC : "连接成功/失败"
+RC-->>Dev : "日志输出(成功/失败)"
+```
+
+图表来源
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+
+章节来源
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+
+### AI代理集成（Claude Code代理无法启动）
+- 现象
+  - Claude Code代理启动失败或无法连接
+- 根因
+  - Claude Code CLI未安装或环境变量未配置
+  - 容器内网络隔离导致外部服务不可达
+  - 容器内路径解析失败，挂载映射不正确
+- 解决方案
+  - 安装并配置Claude Code CLI，设置API密钥与模型
+  - 使用内部网络通信，避免宿主机端口映射带来的复杂性
+  - 通过容器自检测器校验挂载点与宿主机路径映射
+- 预防措施
+  - 在配置文件中明确镜像与资源限制
+  - 启动后检查容器健康状态与日志
+
+章节来源
+- [CLAUDE.md](file://CLAUDE.md#L116-L133)
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L132-L242)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
+
+### 配置优先级冲突导致的行为异常
+- 现象
+  - 端口、代理监听端口、默认后端端口与期望不一致
+  - 环境变量覆盖配置文件但被命令行参数再次覆盖
+- 根因
+  - 配置来源优先级顺序：命令行 > 环境变量 > 配置文件 > 默认值
+- 解决方案
+  - 明确各层配置来源，必要时显式指定命令行参数
+  - 在启动脚本中统一设置环境变量，避免遗漏
+- 预防措施
+  - 在CI/本地开发环境固化配置来源，减少歧义
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+- [config.yml](file://config.yml#L1-L30)
+
+## 依赖关系分析
+- 配置来源与优先级
+  - 命令行参数最高优先级，环境变量次之，配置文件再次之，最后为默认值
+- 代理与后端
+  - Pingora代理负责端口提取与路径重写，后端映射动态维护
+- 观测性
+  - Tracing中间件统一注入trace_id，便于跨服务日志关联
+
+```mermaid
+graph LR
+CLI["命令行参数"] --> Prio["配置优先级"]
+ENV["环境变量"] --> Prio
+CFG["配置文件"] --> Prio
+DEF["默认值"] --> Prio
+Prio --> AX["Axum 主服务"]
+Prio --> PRX["Pingora 代理"]
+```
+
+图表来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+
+## 性能考量
+- 代理层指标
+  - 总请求数、成功率、平均响应时间、按端口统计、活跃连接数
+- 负载均衡
+  - 支持轮询与健康检查，定期探测后端可达性
+- 容器化
+  - 内部网络通信，避免端口映射带来的额外开销
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+## 故障排查指南
+
+### 通过tracing_middleware日志定位请求失败原因
+- 步骤
+  - 启用详细日志：设置RUST_LOG为debug或指定模块
+  - 观察请求进入与退出日志，定位trace_id
+  - 在Axum中间件层记录请求开始/结束与状态码
+- 建议
+  - 在客户端携带trace_id或x-request-id，便于跨服务串联
+  - 使用代理统计接口查看失败率与平均响应时间
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Axum as "Axum 中间件"
+participant Handler as "业务处理器"
+Client->>Axum : "请求(携带trace_id)"
+Axum->>Axum : "记录请求开始"
+Axum->>Handler : "处理请求"
+Handler-->>Axum : "返回响应"
+Axum->>Axum : "记录响应状态"
+Axum-->>Client : "响应"
+```
+
+图表来源
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
+
+章节来源
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
+
+### 通过container_self_inspector诊断容器状态
+- 步骤
+  - 初始化ContainerSelfInspector，验证Docker socket连接
+  - 获取当前容器ID与挂载信息，核对容器内路径到宿主机路径映射
+  - 若未找到挂载信息，列出所有挂载点辅助定位
+- 建议
+  - 在容器启动脚本中先验证Docker连接与挂载权限
+  - 使用compose挂载/var/run/docker.sock并设置环境变量
+
+章节来源
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+
+### 代理端口提取失败排查
+- 步骤
+  - 确认请求路径为“/proxy/{port}/{path}”，端口为有效数字
+  - 如未指定端口，确认默认后端端口配置
+  - 使用代理状态/配置/统计接口查看后端映射与健康状态
+- 建议
+  - 在客户端统一走Pingora端口，避免误发到Axum主服务端口
+
+章节来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L63-L118)
+
+### SSE进度流中断排查
+- 步骤
+  - 检查代理统计接口，关注活跃连接数与失败率
+  - 确认上游服务健康状态与响应时间
+  - 在客户端侧增加重连与心跳机制
+- 建议
+  - 使用代理健康检查循环，定期探测后端可达性
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+### 容器内路径解析失败
+- 步骤
+  - 使用容器自检测器检测容器ID与挂载点
+  - 核对容器内路径到宿主机路径映射是否正确
+  - 在配置文件中明确挂载路径并进行变量替换
+- 建议
+  - 在启动脚本中统一挂载策略，避免相对路径与容器内绝对路径混淆
+
+章节来源
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L244-L295)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L138-L166)
+
+## 结论
+- 代理请求必须直接发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
+- 配置优先级清晰，命令行最高，环境变量次之，配置文件再次之
+- 观测性与容器化能力完善，建议结合Tracing与代理统计进行问题定位
+- Docker权限与路径解析是容器化部署的关键，务必在启动阶段验证
+
+## 附录
+- 常用命令与接口
+  - 健康检查：/health
+  - 代理状态：/proxy/status
+  - 代理配置：/proxy/config
+  - 代理统计：/proxy/stats
+  - 实时进度流：/agent/progress/{session_id}
+
+章节来源
+- [README.md](file://README.md#L209-L268)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/附录/相关链接.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/附录/相关链接.md
@@ -0,0 +1,311 @@
+# 相关链接
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [CLAUDE.md](file://CLAUDE.md)
+- [install.md](file://install.md)
+- [Makefile](file://Makefile)
+- [http_test.rest](file://http_test.rest)
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh)
+- [config.yml](file://config.yml)
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考量](#性能考量)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本章节聚焦于项目中的“相关链接”，即 README.md 中列出的项目主页、贡献指南、许可证文件、设计文档（specs/目录下）以及其他关键文档（如 CLAUDE.md、install.md）。我们将解释这些文档的作用、访问方式，并给出实际使用场景示例，帮助开发者在开发、部署与故障排除中高效集成这些资源。同时，针对常见问题（如链接失效、文档版本不匹配）提供解决方案，并建议性能优化措施（如本地文档镜像、自动化文档索引）。
+
+## 项目结构
+围绕“相关链接”的组织方式，项目提供了如下关键入口与配套资源：
+- 顶层文档：README.md、CLAUDE.md、install.md
+- 设计文档：specs/agent-abstraction-layer-design.md、specs/grpc-migration-design.md、specs/multi-docker-image-design.md
+- 部署与脚本：Makefile、docker/docker-compose.yml、docker/start-rcoder.sh
+- 配置与测试：config.yml、http_test.rest
+- 子模块文档：crates/docker_manager/README.md
+
+```mermaid
+graph TB
+A["README.md<br/>项目主页/贡献指南/许可证/相关链接"] --> B["CLAUDE.md<br/>开发指引与环境配置"]
+A --> C["install.md<br/>安装基础环境"]
+A --> D["specs/*<br/>设计文档集合"]
+D --> D1["agent-abstraction-layer-design.md"]
+D --> D2["grpc-migration-design.md"]
+D --> D3["multi-docker-image-design.md"]
+A --> E["Makefile<br/>构建与开发容器命令"]
+A --> F["docker/docker-compose.yml<br/>容器编排"]
+F --> G["docker/start-rcoder.sh<br/>容器启动脚本"]
+A --> H["config.yml<br/>配置文件示例"]
+A --> I["http_test.rest<br/>API 测试脚本"]
+A --> J["crates/docker_manager/README.md<br/>Docker 管理模块文档"]
+```
+
+图表来源
+- [README.md](file://README.md#L585-L620)
+- [CLAUDE.md](file://CLAUDE.md#L1-L60)
+- [install.md](file://install.md#L1-L9)
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
+- [Makefile](file://Makefile#L1-L40)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [config.yml](file://config.yml#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L20)
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L40)
+
+章节来源
+- [README.md](file://README.md#L585-L620)
+- [Makefile](file://Makefile#L1-L40)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [config.yml](file://config.yml#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L20)
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L40)
+
+## 核心组件
+- 项目主页与贡献指南：位于 README.md 的“相关链接”区域，提供仓库地址、问题跟踪、贡献指南与变更日志入口。
+- 许可证文件：位于 README.md 的“许可证”区域，说明采用 MIT 或 Apache-2.0 双许可证。
+- 设计文档（specs/）：包含 Agent 抽象层、gRPC 迁移、多镜像设计等，指导架构演进与实现。
+- 开发与安装文档：CLAUDE.md 提供开发命令、环境变量、API 接口与调试方法；install.md 提供安装基础依赖的指引。
+- 构建与部署：Makefile 提供本地编译、安装、Docker 镜像构建与开发容器的快捷命令；docker/docker-compose.yml 与 docker/start-rcoder.sh 提供容器化运行与健康检查。
+- 配置与测试：config.yml 展示默认配置项与代理配置；http_test.rest 提供 API 测试脚本，便于手动验证接口行为。
+
+章节来源
+- [README.md](file://README.md#L585-L620)
+- [CLAUDE.md](file://CLAUDE.md#L27-L120)
+- [install.md](file://install.md#L1-L9)
+- [Makefile](file://Makefile#L1-L40)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [config.yml](file://config.yml#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L20)
+
+## 架构总览
+“相关链接”在整体架构中的作用是为开发者提供从入门到深入实现的路径图。通过 README 的“相关链接”导航到贡献指南与设计文档，再结合 CLAUDE.md 的开发命令与 Makefile 的构建流程，最终落地到 docker-compose 与启动脚本完成部署与运行。
+
+```mermaid
+graph TB
+Dev["开发者"] --> R["README.md<br/>相关链接"]
+R --> Contrib["CONTRIBUTING.md<br/>贡献指南"]
+R --> License["LICENSE<br/>许可证"]
+R --> Specs["specs/*<br/>设计文档"]
+Specs --> AAL["Agent 抽象层设计"]
+Specs --> GRPC["gRPC 迁移设计"]
+Specs --> MDI["多镜像设计"]
+Dev --> CL["CLAUDE.md<br/>开发命令/环境变量/API"]
+Dev --> MK["Makefile<br/>构建/安装/开发容器"]
+Dev --> DC["docker-compose.yml<br/>容器编排"]
+DC --> SH["start-rcoder.sh<br/>启动脚本"]
+Dev --> CFG["config.yml<br/>配置示例"]
+Dev --> HT["http_test.rest<br/>API 测试"]
+```
+
+图表来源
+- [README.md](file://README.md#L585-L620)
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
+- [CLAUDE.md](file://CLAUDE.md#L27-L120)
+- [Makefile](file://Makefile#L1-L40)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [config.yml](file://config.yml#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L20)
+
+## 详细组件分析
+
+### README.md 的“相关链接”与“许可证”
+- 项目主页与问题追踪：提供仓库地址与 Issues 页面，便于提交问题与跟踪进展。
+- 贡献指南与变更日志：CONTRIBUTING.md 与 CHANGELOG.md 提供贡献流程与版本演进记录。
+- 许可证：LICENSE 文件说明采用 MIT 或 Apache-2.0 双许可证，明确使用范围与分发条件。
+- 使用场景示例：
+  - 开发者在遇到问题时，先查阅 FAQ（README 的“问题排查”区域），再搜索 Issues，最后在 Issues 中补充详细信息。
+  - 贡献者在提交 PR 前，先阅读 CONTRIBUTING.md 的流程与规范。
+
+章节来源
+- [README.md](file://README.md#L585-L620)
+
+### 设计文档（specs/）的作用与访问方式
+- agent-abstraction-layer-design.md：定义 Agent 抽象层、Agent Trait、Launcher、Supervisor 与配置管理，指导多 Agent 支持与扩展。
+- grpc-migration-design.md：规划从 HTTP+SSE 迁移到 gRPC 的接口契约与模块改造计划，统一通信协议与类型安全。
+- multi-docker-image-design.md：设计双镜像配置系统，支持 rcoder 与 agent-runner 两类服务类型，兼顾向后兼容与未来扩展。
+- 使用场景示例：
+  - 架构师在评估新 Agent 集成时，参考 agent-abstraction-layer-design.md 的抽象接口与生命周期管理。
+  - 团队在讨论通信协议升级时，参考 grpc-migration-design.md 的 Proto 定义与实施步骤。
+  - 在引入新服务类型时，参考 multi-docker-image-design.md 的镜像选择策略与容器创建接口。
+
+章节来源
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L120)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L60)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L120)
+
+### CLAUDE.md 的开发命令与环境配置
+- 开发命令：提供本地构建、安装、Docker 镜像构建与开发容器的常用命令，便于快速迭代。
+- 环境变量：列举服务端口、Docker socket、代理密钥等关键环境变量，确保开发与调试一致性。
+- API 接口：列出核心端点与响应格式，便于前后端联调与测试。
+- 使用场景示例：
+  - 新成员入职时，先按 install.md 安装基础依赖，再参考 CLAUDE.md 的开发命令搭建本地环境。
+  - 调试阶段，通过 CLAUDE.md 的日志配置与容器调试命令快速定位问题。
+
+章节来源
+- [CLAUDE.md](file://CLAUDE.md#L27-L120)
+- [CLAUDE.md](file://CLAUDE.md#L116-L170)
+- [CLAUDE.md](file://CLAUDE.md#L139-L190)
+
+### install.md 的安装基础环境
+- 提供安装 Claude Code ACP 与 Claude Code CLI 的命令，确保 AI 代理相关能力可用。
+- 使用场景示例：
+  - 在首次运行前，先执行 install.md 中的安装步骤，避免后续代理调用失败。
+
+章节来源
+- [install.md](file://install.md#L1-L9)
+
+### Makefile 的构建与开发容器命令
+- 本地编译、安装、卸载二进制与安装 agent 的命令，便于快速构建与分发。
+- Docker 镜像构建与开发容器的一键流程，支持快速重启与日志查看。
+- 使用场景示例：
+  - 本地开发：make dev-build 后 make dev-up 启动开发容器；修改代码后 make dev-restart 快速重启。
+  - CI/CD：make docker-build 构建镜像，配合 docker/docker-compose.yml 进行部署。
+
+章节来源
+- [Makefile](file://Makefile#L1-L40)
+- [Makefile](file://Makefile#L75-L120)
+- [Makefile](file://Makefile#L122-L166)
+
+### docker/docker-compose.yml 与 docker/start-rcoder.sh
+- docker-compose.yml：定义服务名称、端口映射、环境变量、卷挂载与健康检查，确保容器化运行稳定。
+- start-rcoder.sh：在容器内初始化必要目录、导出环境变量并启动 rcoder 主程序。
+- 使用场景示例：
+  - 通过 docker-compose.yml 的 healthcheck 验证服务可用性。
+  - 使用 make dev-logs 查看容器日志，定位启动与运行问题。
+
+章节来源
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+
+### config.yml 的配置示例与代理配置
+- 展示默认代理配置（listen_port、default_backend_port、backend_host、port_param）与健康检查参数。
+- 使用场景示例：
+  - 在本地或生产环境中，根据实际网络与端口策略调整 proxy_config，确保代理请求正确转发。
+
+章节来源
+- [config.yml](file://config.yml#L1-L40)
+- [config.yml](file://config.yml#L31-L80)
+
+### http_test.rest 的 API 测试脚本
+- 提供 chat、SSE 进度流、取消任务、停止 Agent 等接口的测试用例，支持 REST Client 插件的动态变量。
+- 使用场景示例：
+  - 在开发阶段，使用 http_test.rest 快速验证聊天、取消与停止等核心流程。
+  - 在回归测试中，复用该脚本进行端到端验证。
+
+章节来源
+- [http_test.rest](file://http_test.rest#L1-L40)
+- [http_test.rest](file://http_test.rest#L41-L109)
+
+### crates/docker_manager/README.md 的 Docker 管理模块
+- 介绍 Docker Manager 的功能特性、核心组件与使用场景，指导如何为项目创建独立运行环境。
+- 使用场景示例：
+  - 在需要为每个项目创建隔离容器时，参考该文档的配置与最佳实践。
+
+章节来源
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L60)
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L135-L170)
+
+## 依赖分析
+“相关链接”在项目中的依赖关系体现为：README 的“相关链接”作为导航入口，串联起贡献指南、设计文档与许可证；CLAUDE.md 与 Makefile 为开发与部署提供具体命令；docker-compose.yml 与启动脚本负责容器化运行；config.yml 与 http_test.rest 则分别提供配置与测试支撑。
+
+```mermaid
+graph TB
+R["README.md<br/>相关链接"] --> Contrib["CONTRIBUTING.md"]
+R --> License["LICENSE"]
+R --> Specs["specs/*"]
+Specs --> AAL["Agent 抽象层设计"]
+Specs --> GRPC["gRPC 迁移设计"]
+Specs --> MDI["多镜像设计"]
+CL["CLAUDE.md"] --> MK["Makefile"]
+MK --> DC["docker-compose.yml"]
+DC --> SH["start-rcoder.sh"]
+CFG["config.yml"] --> DC
+HT["http_test.rest"] --> R
+```
+
+图表来源
+- [README.md](file://README.md#L585-L620)
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
+- [CLAUDE.md](file://CLAUDE.md#L27-L120)
+- [Makefile](file://Makefile#L1-L40)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [config.yml](file://config.yml#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L20)
+
+## 性能考量
+- 文档访问性能优化建议：
+  - 本地文档镜像：在开发机或 CI 机器上维护一份本地文档镜像，减少对外部链接的依赖，提高加载速度与稳定性。
+  - 自动化文档索引：通过脚本定期抓取并生成索引页，便于快速定位设计文档与 API 文档。
+  - 缓存策略：对频繁访问的文档（如 README、设计文档）启用浏览器缓存或静态站点缓存，降低带宽消耗。
+- 部署与运行性能优化建议：
+  - 使用 Makefile 的开发容器命令进行快速迭代，减少编译与打包时间。
+  - 在 docker-compose.yml 中合理设置资源限制与健康检查，确保容器稳定运行。
+
+[本节为通用建议，不直接分析具体文件]
+
+## 故障排除指南
+- 常见问题与解决方案：
+  - 链接失效：当 README 中的仓库地址或外部文档链接不可用时，优先检查仓库是否迁移或私有化；在内部知识库中同步更新链接。
+  - 文档版本不匹配：设计文档（specs/）与当前实现可能存在差异。建议在 PR 中同步更新相关文档，并在 README 的“更新日志”中标注变更。
+  - 代理配置错误：检查 config.yml 中的 proxy_config，确保 listen_port、default_backend_port 与 backend_host 配置正确。
+  - 容器启动失败：通过 docker-compose.yml 的 healthcheck 与 make dev-logs 查看日志，确认端口冲突、卷挂载权限或镜像拉取问题。
+  - API 测试失败：使用 http_test.rest 的动态变量功能，逐步验证 chat、SSE、取消与停止等流程，定位具体环节的问题。
+
+章节来源
+- [README.md](file://README.md#L612-L652)
+- [config.yml](file://config.yml#L14-L30)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
+- [http_test.rest](file://http_test.rest#L1-L40)
+
+## 结论
+“相关链接”是开发者从入门到深入实现的重要桥梁。通过 README 的导航、CLAUDE.md 的开发命令、Makefile 的构建流程、docker-compose.yml 的容器化运行以及 config.yml 与 http_test.rest 的配置与测试，开发者可以高效地完成开发、部署与故障排除。建议在团队内部维护本地文档镜像与自动化索引，以提升文档访问效率与一致性。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+- 实际使用场景示例（路径引用）：
+  - 快速定位部署脚本：docker/docker-compose.yml、docker/start-rcoder.sh
+  - 构建工具：Makefile
+  - API 测试：http_test.rest
+  - 设计文档：specs/agent-abstraction-layer-design.md、specs/grpc-migration-design.md、specs/multi-docker-image-design.md
+  - 开发与安装：CLAUDE.md、install.md
+  - 配置参考：config.yml
+  - Docker 管理：crates/docker_manager/README.md
+
+章节来源
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
+- [Makefile](file://Makefile#L1-L40)
+- [http_test.rest](file://http_test.rest#L1-L40)
+- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L120)
+- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L60)
+- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L120)
+- [CLAUDE.md](file://CLAUDE.md#L27-L120)
+- [install.md](file://install.md#L1-L9)
+- [config.yml](file://config.yml#L1-L40)
+- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L60)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/附录/许可证.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/附录/许可证.md
@@ -0,0 +1,216 @@
+# 许可证
+
+<cite>
+**本文档引用的文件**  
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
+- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
+- [tmp/rust-sdk/LICENSE](file://tmp/rust-sdk/LICENSE)
+- [tmp/tonic/LICENSE](file://tmp/tonic/LICENSE)
+</cite>
+
+## 目录
+1. [项目许可证概述](#项目许可证概述)
+2. [许可证类型详解](#许可证类型详解)
+3. [用户权利与义务](#用户权利与义务)
+4. [贡献者指南](#贡献者指南)
+5. [第三方依赖兼容性分析](#第三方依赖兼容性分析)
+6. [商业使用与静态链接](#商业使用与静态链接)
+7. [衍生作品发布](#衍生作品发布)
+8. [常见问题解答](#常见问题解答)
+
+## 项目许可证概述
+
+本项目采用MIT或Apache-2.0双许可证模式，为用户提供灵活的使用选择。项目根目录下的`Cargo.toml`文件明确声明了许可证类型为"MIT OR Apache-2.0"，这一信息也在`README.md`文件中得到确认。这种双许可证策略允许用户根据自身需求选择最适合的许可证条款进行使用、修改和分发。
+
+项目采用Rust语言开发，基于工作区（workspace）结构组织多个功能模块，包括AI代理适配器、Docker管理器、Pingora代理等组件。每个组件的许可证均继承自工作区配置，确保了整个项目许可证的一致性。尽管项目根目录下未找到独立的LICENSE文件，但通过`Cargo.toml`中的声明和`README.md`的说明，许可证信息已得到充分披露。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+
+## 许可证类型详解
+
+本项目采用MIT与Apache-2.0双重许可证，用户可选择其中任一许可证的条款来使用本软件。
+
+MIT许可证是一种宽松的开源许可证，主要要求包括：
+- 保留原始版权声明和许可声明
+- 在软件和文档中包含许可证副本
+- 不提供任何担保，作者不对使用本软件造成的损害负责
+
+Apache-2.0许可证也是一种宽松的开源许可证，但相比MIT许可证提供了更全面的保护，其主要特点包括：
+- 明确的专利授权：贡献者自动授予用户必要的专利许可
+- 详细的归属要求：修改文件必须有显著说明
+- 专利报复条款：如果用户对项目发起专利诉讼，则其专利许可自动终止
+- 兼容性良好：与GPLv3等主要开源许可证兼容
+
+用户可以根据具体使用场景选择最适合的许可证。对于简单的集成和使用，MIT许可证的简洁性更具吸引力；而对于企业级应用和专利敏感的环境，Apache-2.0许可证提供的专利保护更为有利。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+
+## 用户权利与义务
+
+### 再分发权利
+用户有权以源代码或编译后的二进制形式再分发本项目，无论是否进行了修改。再分发时必须遵守所选许可证的具体要求：
+
+对于MIT许可证：
+- 必须在所有副本或实质性部分中包含原始版权声明和许可声明
+- 不需要公开修改后的源代码
+- 可以用于商业目的，无需支付许可费用
+
+对于Apache-2.0许可证：
+- 必须在所有副本或实质性部分中包含原始版权声明、专利声明、商标声明和归属声明
+- 修改的文件必须有显著说明，指出哪些部分被修改
+- 必须随分发物提供NOTICE文件的副本（如果存在）
+
+### 修改权利
+用户有权修改本项目的源代码以满足特定需求。修改后的作品被视为衍生作品，再分发时需要遵守相应的许可证要求。建议在修改文件的头部添加注释，说明修改内容和日期，这虽然不是强制要求，但有助于代码维护和合规性。
+
+### 专利授权
+选择Apache-2.0许可证的用户将获得明确的专利授权。每个贡献者都授予用户一项永久的、全球性的、非独占的、免版税的专利许可，用于实施与项目相关的专利权利要求。这一条款为企业用户提供了重要的法律保护，降低了专利侵权风险。
+
+### 归属要求
+无论选择哪种许可证，都必须保留原始的版权声明和许可声明。建议在项目的文档或"关于"页面中提及本项目及其许可证信息，这不仅是法律要求，也是对开源社区的尊重。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+
+## 贡献者指南
+
+### 贡献流程
+本项目欢迎外部贡献。贡献者应遵循以下流程：
+1. Fork项目仓库
+2. 创建特性分支
+3. 提交更改
+4. 推送分支
+5. 创建Pull Request
+
+贡献者在提交代码时，默认同意其贡献遵循项目的双许可证模式。这意味着贡献者的代码也将以MIT或Apache-2.0许可证发布，用户可以选择其中任一许可证使用。
+
+### 代码归属
+贡献者保留其贡献代码的版权，但通过提交贡献，授予项目维护者和其他用户使用、修改和分发其代码的权利。这种模式是开源社区的常规做法，确保了项目的持续发展和广泛使用。
+
+### 贡献者协议
+虽然本项目目前没有要求签署正式的贡献者许可协议（CLA），但建议贡献者在首次贡献时明确声明其同意项目的许可证条款。对于重大贡献，项目维护者可能会要求贡献者确认其贡献的许可条款。
+
+**Section sources**
+- [README.md](file://README.md#L603)
+
+## 第三方依赖兼容性分析
+
+### Axum框架兼容性
+本项目使用Axum作为HTTP框架，Axum本身采用MIT许可证，与本项目的双许可证完全兼容。MIT许可证的宽松性确保了与本项目的无缝集成，用户在使用本项目时无需担心Axum的许可证限制。
+
+Axum作为Rust生态中流行的Web框架，其MIT许可证允许：
+- 无限制的商业使用
+- 私有修改和分发
+- 与其他许可证的代码静态链接
+- 无需公开衍生作品的源代码
+
+### Pingora代理兼容性
+本项目集成了Pingora作为反向代理，Pingora采用Apache-2.0许可证。由于本项目也提供Apache-2.0许可证选项，两者完全兼容。用户选择Apache-2.0许可证时，可以合法地使用和分发包含Pingora的完整系统。
+
+Pingora的Apache-2.0许可证提供了：
+- 明确的专利授权，保护用户免受专利诉讼
+- 详细的归属要求，确保适当的信用归属
+- 与本项目相同的许可证选项，简化了合规性管理
+
+```mermaid
+graph TD
+A[RCoder项目] --> B[MIT许可证]
+A --> C[Apache-2.0许可证]
+B --> D[Axum框架<br>MIT许可证]
+C --> E[Pingora代理<br>Apache-2.0许可证]
+D --> F[完全兼容]
+E --> G[完全兼容]
+```
+
+**Diagram sources**
+- [Cargo.toml](file://Cargo.toml#L60)
+- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L22)
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L60)
+- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
+- [README.md](file://README.md#L36)
+
+## 商业使用与静态链接
+
+### 商业使用
+本项目的双许可证模式完全支持商业使用。无论是MIT还是Apache-2.0许可证，都允许将本项目集成到商业产品和服务中，无需支付许可费用或提供源代码。这对于希望利用AI代理功能的企业用户来说是一个重要优势。
+
+商业用户可以根据自身需求选择合适的许可证：
+- 选择MIT许可证：适用于希望最小化法律义务的简单集成
+- 选择Apache-2.0许可证：适用于需要专利保护的企业级应用
+
+### 静态链接合规性
+本项目采用Rust语言开发，通常会生成静态链接的二进制文件。两种许可证对静态链接都有明确的规定：
+
+MIT许可证：完全允许静态链接，无特殊要求，只需保留版权声明和许可声明。
+
+Apache-2.0许可证：允许静态链接，但要求：
+- 在文档或"关于"页面中包含NOTICE文件的内容（如果存在）
+- 对修改的文件进行适当标记
+- 保留所有原始版权声明
+
+对于本项目，由于采用工作区结构，所有组件都遵循相同的许可证策略，静态链接后的二进制文件被视为一个整体，只需遵守所选许可证的总体要求即可。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+
+## 衍生作品发布
+
+当用户基于本项目创建衍生作品时，需要遵守以下准则：
+
+### 源代码分发
+如果以源代码形式分发衍生作品，必须：
+- 包含原始的LICENSE文件或其内容
+- 在修改的文件中添加适当的修改说明
+- 保留所有原始版权声明
+
+### 二进制分发
+如果以编译后的二进制形式分发衍生作品，必须：
+- 在文档或"关于"页面中包含原始版权声明和许可声明
+- 如果选择了Apache-2.0许可证，还需包含NOTICE文件的内容
+- 提供获取源代码的方式说明（虽然不是强制要求，但推荐）
+
+### 许可证选择
+衍生作品的发布者可以选择：
+- 继续使用MIT或Apache-2.0双许可证模式
+- 仅选择其中一种许可证
+- 在Apache-2.0许可证下，还可以选择更宽松的许可证，但不能增加限制
+
+建议在衍生作品中明确说明其与原始项目的关系，这有助于建立透明的开源生态。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
+
+## 常见问题解答
+
+### 商业使用是否受限？
+不受限。本项目的双许可证模式完全允许商业使用，无需支付许可费用或提供源代码。
+
+### 静态链接是否合规？
+合规。两种许可证都允许静态链接，只需遵守相应的归属要求。
+
+### 是否需要公开修改后的源代码？
+不需要。无论是MIT还是Apache-2.0许可证，都不要求公开修改后的源代码。
+
+### 如何正确归属？
+在软件和文档中包含原始的版权声明和许可声明。如果选择了Apache-2.0许可证，还需包含NOTICE文件的内容。
+
+### 可以将许可证更改为其他类型吗？
+不可以。衍生作品必须遵守原始项目的许可证条款，但可以选择MIT或Apache-2.0中的一种。
+
+### 专利风险如何？
+选择Apache-2.0许可证的用户将获得明确的专利授权，大大降低了专利侵权风险。
+
+**Section sources**
+- [Cargo.toml](file://Cargo.toml#L31)
+- [README.md](file://README.md#L597)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/附录/附录.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/附录/附录.md
@@ -0,0 +1,153 @@
+# 附录
+
+<cite>
+**本文档中引用的文件**  
+- [README.md](file://README.md)
+- [config.yml](file://config.yml)
+- [CLAUDE.md](file://CLAUDE.md)
+- [install.md](file://install.md)
+- [Cargo.toml](file://Cargo.toml)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
+- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
+- [crates/shared_types/src/service_type.rs](file://crates/shared_types/src/service_type.rs)
+</cite>
+
+## 目录
+1. [相关链接](#相关链接)
+2. [许可证](#许可证)
+3. [变更日志](#变更日志)
+4. [FAQ](#faq)
+
+## 相关链接
+
+本项目依赖并关联多个外部资源和文档，以下是关键链接的详细说明：
+
+- **项目仓库**: [GitHub](https://github.com/your-org/rcoder) - 项目源代码的主仓库，包含所有开发分支和发布版本。
+- **问题追踪**: [Issues](https://github.com/your-org/rcoder/issues) - 用于报告 bug、提出功能请求和讨论技术问题的平台。
+- **贡献指南**: [CONTRIBUTING.md](CONTRIBUTING.md) - 详细说明如何为项目贡献代码，包括开发流程、代码风格和提交规范。
+- **ACP 协议**: [Agent Client Protocol](https://github.com/zed-industries/zed/tree/main/crates/agent_client_protocol) - RCoder 所依赖的 AI 代理通信协议的官方文档。
+- **Claude Code**: [Anthropic Claude Code](https://docs.anthropic.com/claude/docs) - 集成的 Claude AI 代理的官方文档和 API 参考。
+- **OpenAI Codex**: [OpenAI Codex Documentation](https://github.com/openai/codex) - 集成的 OpenAI Codex 代理的相关文档。
+
+这些链接为开发者提供了深入理解项目架构、协议细节和外部依赖的入口。
+
+**Section sources**
+- [README.md](file://README.md#L585-L593)
+
+## 许可证
+
+本项目采用 MIT 或 Apache-2.0 双许可证模式，为使用者提供了灵活的选择。您可以在以下两种许可证中选择一种来遵守：
+
+- **MIT 许可证**: 允许在任何项目中自由使用、复制、修改、合并、发布、分发、再许可和销售软件的副本，只需在软件和衍生作品中包含原始版权声明和许可声明。
+- **Apache-2.0 许可证**: 提供了更全面的条款，包括明确的专利授权、商标使用限制和贡献者责任豁免。它还要求在分发源代码或二进制文件时包含 NOTICE 文件。
+
+这种双许可证策略旨在平衡开源社区的开放性与企业用户的法律确定性。详细的许可证文本可以在项目根目录下的 `LICENSE` 文件中找到。
+
+**Section sources**
+- [README.md](file://README.md#L595-L597)
+- [Cargo.toml](file://Cargo.toml#L31)
+
+## 变更日志
+
+### v0.1.0 (当前版本)
+
+#### 新增功能
+- ✅ 初始版本发布
+- ✅ 基于 ACP 协议的 AI 代理统一管理
+- ✅ HTTP API 接口支持
+- ✅ Claude Code 和 OpenAI Codex 代理集成
+- ✅ YAML 配置文件支持
+- ✅ 命令行参数支持
+- ✅ 多层配置系统（命令行 > 环境变量 > 配置文件 > 默认）
+- ✅ OpenTelemetry 集成和分布式追踪
+- ✅ Swagger UI API 文档
+- ✅ 项目文件解析器 (Nuwax Parser)
+
+#### 技术特性
+- ✅ 基于 Rust 2024 Edition
+- ✅ 异步架构 (Tokio)
+- ✅ 模块化设计 (Workspace Crates)
+- ✅ 实时通信 (SSE)
+- ✅ 结构化日志 (Tracing)
+
+**Section sources**
+- [README.md](file://README.md#L627-L649)
+
+## FAQ
+
+### 如何配置 AI 代理？
+
+AI 代理的配置主要通过环境变量完成。对于 Claude Code 代理，需要设置 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_MODEL` 环境变量。例如：
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
+```
+对于 OpenAI Codex 代理，需要参考其官方文档进行相应的设置。
+
+**Section sources**
+- [README.md](file://README.md#L107-L129)
+
+### 如何解决端口被占用的问题？
+
+如果遇到端口被占用的情况，可以通过命令行参数 `--port` 指定一个不同的端口。例如：
+```bash
+cargo run --bin rcoder -- --port 8087
+```
+此外，也可以通过环境变量 `RCODER_PORT` 或在 `config.yml` 配置文件中修改 `port` 字段来更改端口。
+
+**Section sources**
+- [README.md](file://README.md#L622-L623)
+- [config.yml](file://config.yml#L11)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L18)
+
+### 配置系统的优先级是怎样的？
+
+RCoder 的配置系统遵循一个明确的优先级顺序，从高到低依次为：
+1. **命令行参数**：最高优先级，直接在启动命令中指定。
+2. **环境变量**：中等优先级，可以在系统或 shell 中设置。
+3. **配置文件**：较低优先级，存储在 `config.yml` 文件中。
+4. **默认配置**：最低优先级，由代码中的默认值提供。
+
+例如，如果同时在命令行指定了 `--port 8080`，在环境变量中设置了 `RCODER_PORT=9000`，并且在 `config.yml` 中配置了 `port: 3000`，最终生效的端口将是 8080。
+
+**Section sources**
+- [README.md](file://README.md#L388-L393)
+- [CLAUDE.md](file://CLAUDE.md#L109-L113)
+- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L274-L294)
+
+### 如何启用和配置 Pingora 反向代理？
+
+要启用 Pingora 反向代理，需要在启动命令中添加 `--enable-proxy` 参数，并通过 `--proxy-port` 指定监听端口。例如：
+```bash
+cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
+```
+您也可以在 `config.yml` 文件中配置 `proxy_config` 部分，包括 `listen_port`、`default_backend_port` 等选项。代理请求应直接发送到 Pingora 的监听端口，路径格式为 `/proxy/{port}/{path}`。
+
+**Section sources**
+- [README.md](file://README.md#L70-L77)
+- [config.yml](file://config.yml#L14-L22)
+- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L9)
+
+### Docker 容器是如何管理的？
+
+RCoder 使用 DockerManager 和 ContainerManager 组件来动态创建和管理每个项目的独立 Docker 容器。容器的镜像选择策略支持多镜像配置，可以根据系统架构（ARM64/AMD64）自动选择合适的镜像。相关的配置在 `config.yml` 的 `docker_config` 部分定义，包括镜像仓库、资源限制和网络模式等。
+
+**Section sources**
+- [CLAUDE.md](file://CLAUDE.md#L102-L107)
+- [config.yml](file://config.yml#L31-L161)
+- [crates/shared_types/src/service_type.rs](file://crates/shared_types/src/service_type.rs#L9)
+- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L12)
+
+### 如何进行故障排查？
+
+当遇到问题时，建议按照以下步骤进行排查：
+1. 查看 `RUST_LOG=debug` 启用的详细日志输出。
+2. 检查 `README.md` 和 `CLAUDE.md` 中的相关说明。
+3. 搜索已有的 Issues 看是否已有解决方案。
+4. 使用 `cargo clippy` 和 `cargo fmt` 检查代码质量和格式。
+5. 如果问题依然存在，可以创建一个新的 Issue 并提供详细的错误信息和复现步骤。
+
+**Section sources**
+- [README.md](file://README.md#L611-L626)
+- [CLAUDE.md](file://CLAUDE.md#L193-L203)