Host Bridge

AnyIDE

自托管工具服务器通过MCP和OpenAPI协议向LLM客户端公开主机功能

版本：0.1.0\ 状态：✅ 生产就绪

______________________________________________________________________

概述

AnyIDE是一个单一的Docker容器，它通过两个行业标准协议同时向LLM应用程序公开主机管理功能：

• MCP（模型上下文协议） 通过流式HTTP
• OpenAPI（REST/JSON） 对于Open WebUI等工具

内置的管理仪表板提供人工监督、HITL（human in the Loop）审批工作流、审计日志和秘密管理。

______________________________________________________________________

特性

✅ 实现

• 双协议支持： MCP+OpenAPI同时运行
• 模块化工具加载： 启动时通过启用/禁用工具类别 ANYIDE_MODULES 或 config.yaml
• 文件系统工具：

- 使用工作区沙盒读写文件 - 使用递归遍历列出目录内容 - 使用正则表达式支持按名称或内容搜索文件

• 壳牌执行： 执行带有安全控制和分配列表的命令
• Git工具： 完整的Git仓库管理

- 状态、日志、差异、显示、分支、远程 - 提交、推送、拉取、结账、藏匿操作 - HITL批准写入操作 - Git凭据支持 {{secret:KEY}} 经过身份验证的推送/拉取模板 - 使用临时脚本实现安全的GIT_ASKPASS

• Docker工具： 集装箱管理和监控

- 列出具有筛选功能的容器（正在运行、已停止、按名称/状态） - 检查容器详细信息（配置、网络、装载、状态） - 使用尾部和时间戳过滤检索容器日志 - 控制容器生命周期（启动、停止、重新启动、暂停、取消暂停） - HITL批准破坏性操作 - Docker套接字与安全控制的集成

• 语言工具（树保姆+LSP）： IDE级结构代码工具

- lang_skeleton 和 lang_read_file 用于结构感知代码导航 - lang_diff 和 lang_apply_patch 用于具有备份+验证功能的锚定编辑工作流 - lang_create_file, lang_validate, lang_index, lang_search_symbols, lang_reference_graph - lang_validate 支持语法/lint/类型检查(pyright + typescript-language-server 配置时） - lang_reference_graph 通过LSP为JavaScript/TypeScript添加语义跨文件边 - lang_read_file 包括可选的LSP悬停/转到定义丰富功能 - LSP进程生命周期包括延迟启动、初始化握手、超时恢复和崩溃时重新启动 - 增量SQLite支持的符号索引和基线过梁布线（Python的ruff）

• 技能模块： 孤立的 /skills 存储和技能.sh集成

- 支持离线的本地工具： skills_list, skills_read, skills_read_file - 在线工具： skills_search (npx skills find ... --json)HITL门控 skills_install - skills_install 使用项目范围安装 /skills （通常 /skills/.agents/skills/) - skills_list/read/read_file 从两者中发现技能 /skills/ 和 /skills/.agents/skills/ - 强大的CLI解析/错误规范化（JSON+ANSI/搜索输出的明文回退）

• 子代理模块： 由统一LLM客户端支持的配置驱动的专业子代理

- subagent_list 发现已配置的子代理类型 - subagent_run 使用端点/模型选择执行单转弯提示模板 - 响应元数据包括模型、端点、令牌使用、延迟和配置的JSON模式 - 每种类型的超控控制闸门 override_model 和 override_temperature - 策略集成支持允许/阻止/HITL控制 subagent_list 和 subagent_run

• 工作区管理： 安全的路径解析和边界执行
• HITL系统： 敏感操作的实时审批工作流
• 管理员仪表板： 高级用户界面，实时更新

- 管理员会话到期时自动重定向到登录 - 子路径软件API和WebSocket路由(/my-prefix/admin 部署） - 受限cookie浏览器场景的基于标头的身份验证回退 - 初始连接/重新连接期间弹性WebSocket消息队列

• 审核日志记录： 完整的执行历史记录
• 策略引擎： 每个工具允许/阻止/HITL规则
• 秘密管理： 安全的秘密解决方案 {{secret:KEY}} 模板语法
• 系统LLM能力（管理员管理）： 中央 llm.endpoints 配置内部模块的提供者适配器（OpenAI/OpenAI兼容/Ollama、Anthropic、Google）

- 仅通过admin/config界面公开，而不是 /api/tools/* 端点

• HTTP客户端： 使用SSRF保护、域过滤和秘密注入发出出站HTTP请求
• 知识图谱记忆： 12个用于FTS5搜索和图遍历的持久知识存储工具

- 改进的自然语言记忆搜索召回（问题式查询）

• 计划编排： 基于DAG的多步骤工作流，具有现成的任务发现、任务引用和故障处理功能

- 外部协调人执行任务；后端跟踪计划/任务状态 - 计划参考决议 plan_id （首选）或具有歧义保护的唯一计划名称

• WebSocket支持： 实时通知
• 操作文件： Docker Hub发布指南、LLM系统提示模板和自动生成的工具目录
• 部署示例： 生产组合文件、面向策略的配置变体和机密模板
• 扩展测试套件： 单元、集成、安全和负载测试覆盖率

✅ 管理员仪表板增强功能（完整）

• 工具资源管理器： 使用JSON模式浏览和检查所有可用工具

- 基于OpenAPI合约构建的工具列表（非反射） - 通过有效的策略配置获得准确的HITL指标 - 从请求/响应模型填充的输入/输出模式

• 配置查看器： 查看当前服务器配置和HTTP设置
• 秘密管理： 查看加载的密钥并从UI触发热重新加载
• 增强系统健康： 实时CPU、内存、数据库和工作空间指标
• 审计日志增强功能：

- 将筛选后的日志导出为JSON或CSV - 具有轮询回退功能的实时WebSocket流式传输 - 实时连接状态指示器（实时/轮询/离线） - 新日志通知徽章

• 实时审计流： 用于实时审计事件流的WebSocket端点
• 浏览器通知： HITL审批请求的桌面警报
• 容器日志查看器： 浏览容器和查看其日志的专用页面
• 移动响应： 适用于所有设备尺寸的全响应式设计

✅ MCP协议改进

• 工具奇偶性： 所有工具（包括Docker）现在都通过具有OpenAPI奇偶校验的MCP公开
• 范围限制： MCP仅公开工具端点，不包括admin/auth/系统路由
• 回归测试： 自动测试验证MCP和OpenAPI工具列表是否匹配

______________________________________________________________________

快速开始

1.启动容器

docker compose up -d

2.访问管理员仪表板

http://localhost:8080/admin/

默认密码： admin

• 密码优先级： ANYIDE_ADMIN_PASSWORD > ADMIN_PASSWORD （遗留）> config.yaml auth.admin_password >默认值 admin.

仪表板提供了一个具有可扩展小部件的统一视图：

• HITL审批队列（直接从仪表板审批/拒绝）
• 系统健康状况（实时指标和状态）
• 最近的活动（最近5次工具执行）

单击小部件标题以展开/折叠部分，或使用“查看全部”按钮导航到专用页面进行详细分析。

3.测试工具

# Read a file
curl -X POST http://localhost:8080/api/tools/fs/read \
  -H "Content-Type: application/json" \
  -d '{"path": "README.md"}'

# List directory contents
curl -X POST http://localhost:8080/api/tools/fs/list \
  -H "Content-Type: application/json" \
  -d '{"path": ".", "recursive": true}'

# Search for files
curl -X POST http://localhost:8080/api/tools/fs/search \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "search_type": "both"}'

# Execute a shell command
curl -X POST http://localhost:8080/api/tools/shell/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la"}'

# Check git repository status
curl -X POST http://localhost:8080/api/tools/git/status \
  -H "Content-Type: application/json" \
  -d '{"repo_path": "."}'

# View git commit history
curl -X POST http://localhost:8080/api/tools/git/log \
  -H "Content-Type: application/json" \
  -d '{"repo_path": ".", "max_count": 10}'

# List Docker containers
curl -X POST http://localhost:8080/api/tools/docker/list \
  -H "Content-Type: application/json" \
  -d '{"all": true}'

# Inspect a Docker container
curl -X POST http://localhost:8080/api/tools/docker/inspect \
  -H "Content-Type: application/json" \
  -d '{"container": "anyide"}'

# Get Docker container logs
curl -X POST http://localhost:8080/api/tools/docker/logs \
  -H "Content-Type: application/json" \
  -d '{"container": "anyide", "tail": 50}'

# Write a file (triggers HITL for .conf files)
curl -X POST http://localhost:8080/api/tools/fs/write \
  -H "Content-Type: application/json" \
  -d '{"path": "test.conf", "content": "test=value"}'

# Restart a Docker container (triggers HITL)
curl -X POST http://localhost:8080/api/tools/docker/action \
  -H "Content-Type: application/json" \
  -d '{"container": "nginx", "action": "restart"}'

# Read only a specific function from a source file
curl -X POST http://localhost:8080/api/tools/language/read_file \
  -H "Content-Type: application/json" \
  -d '{"path":"main.py","window":"function:run","format":"numbered"}'

# Validate syntax + lint + type for a Python file
curl -X POST http://localhost:8080/api/tools/language/validate \
  -H "Content-Type: application/json" \
  -d '{"path":"main.py","checks":["syntax","lint","type"]}'

# Validate TypeScript types via LSP
curl -X POST http://localhost:8080/api/tools/language/validate \
  -H "Content-Type: application/json" \
  -d '{"path":"app.ts","checks":["syntax","type"]}'

# List installed local skills (offline-capable)
curl -X POST http://localhost:8080/api/tools/skills/list

# Search remote skills registry
curl -X POST http://localhost:8080/api/tools/skills/search \
  -H "Content-Type: application/json" \
  -d '{"query":"react testing","max_results":5}'

# Install a skill (HITL-gated)
curl -X POST http://localhost:8080/api/tools/skills/install \
  -H "Content-Type: application/json" \
  -d '{"repo":"vercel-labs/agent-skills","skill_name":"vitest"}'

# List configured subagent types
curl -X POST http://localhost:8080/api/tools/subagent/list

# Run a configured subagent
curl -X POST http://localhost:8080/api/tools/subagent/run \
  -H "Content-Type: application/json" \
  -d '{"type":"prompt_optimizer","input":"Improve this prompt","context":"Audience: backend engineers"}'

4.在仪表板中批准

1. 首选http://localhost:8080/admin/
2. 仪表板显示HITL小部件中的待处理请求（黄色发光）
3. 展开小部件以查看请求
4. 直接从仪表板中单击“批准”或“拒绝”
5. 或者单击“查看全部”导航到完整的HITL队列页面

______________________________________________________________________

建筑

┌─────────────────────────────────────────┐
│         Docker Container                │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │  FastAPI Application              │  │
│  │                                   │  │
│  │  • OpenAPI: /api/tools/*          │  │
│  │  • MCP: /mcp                      │  │
│  │  • Admin: /admin/                 │  │
│  │  • WebSocket: /ws/hitl            │  │
│  │                                   │  │
│  │  ┌─────────────────────────────┐ │  │
│  │  │  Tool Execution Engine      │ │  │
│  │  │  • Module Registry          │ │  │
│  │  │  • Policy Enforcer          │ │  │
│  │  │  • HITL Manager             │ │  │
│  │  │  • Secret Resolver          │ │  │
│  │  │  • Audit Logger             │ │  │
│  │  └─────────────────────────────┘ │  │
│  └───────────────────────────────────┘  │
│                                         │
│  Volumes:                               │
│  • /workspace (host directories)        │
│  • /skills (isolated skill storage)     │
│  • /data (SQLite, logs)                 │
│  • /secrets (secrets.env)               │
└─────────────────────────────────────────┘

______________________________________________________________________

配置

环境变量

# Required
ANYIDE_ADMIN_PASSWORD=your-secure-password
# Legacy fallback: ADMIN_PASSWORD=your-secure-password

# Precedence:
# 1) ANYIDE_ADMIN_PASSWORD
# 2) ADMIN_PASSWORD (legacy)
# 3) config.yaml auth.admin_password
# 4) default "admin"

# Optional
ANYIDE_WORKSPACE_BASE_DIR=/workspace
ANYIDE_PORT=8080
ANYIDE_AUDIT_RETENTION_DAYS=30
ANYIDE_LOG_LEVEL=INFO
ANYIDE_HITL_TTL_SECONDS=300
ANYIDE_MODULES=all
ANYIDE_SKILLS_BASE_DIR=/skills
ANYIDE_HOST_SKILLS_DIR=./skills

ANYIDE_MODULES 支持：

• all （默认）：加载所有内置模块
• all,-docker,-http：加载除列出的模块之外的所有模块
• fs,workspace,shell,git,memory,plan,language,skills,subagent：明确的排外主义

模块选择(config.yaml)

modules:
  enabled: []          # empty => all available modules
  disabled: []         # e.g. ["docker", "http"]

环境变量 ANYIDE_MODULES 覆盖 modules.enabled/disabled.

技能存储和连接(config.yaml)

skills:
  base_dir: /skills

• skills.base_dir 与工作区路径隔离，应作为单独的卷装载。
• 离线模式： skills_list, skills_read，以及 skills_read_file 从当地工作 skills.base_dir 内容，包括 .agents/skills 安装。
• 在线模式： skills_search 和 skills_install 需要出站网络访问。
• skills_install 在项目范围内运行（否 --global)因此，已安装的技能仍然不足 /skills 存储。
• skills_install 默认情况下是HITL门控的，因为它下载并执行外部代码。

语言+LSP(config.yaml)

language:
  linters:
    python: "ruff"
  lsp_servers:
    python: "pyright"
    typescript: "typescript-language-server"

• LSP服务器启动缓慢，并保持驻留以供重用。
• 如果服务器二进制文件丢失或初始化失败，语言工具就会退回到树保姆行为。
• 类型诊断返回 lang_validate.type_check.errors 当 checks 包括 "type".

LLM端点(config.yaml)

LLM端点配置是 系统能力 （用于内部模块和管理工作流），而不是工具模块。

llm:
  endpoints:
    - id: "primary"
      provider: "openai"                 # openai | openai_compatible | ollama | anthropic | google
      base_url: "https://api.openai.com/v1"
      api_key_secret: "OPENAI_API_KEY"   # optional for ollama
      default_model: "gpt-4o-mini"
      timeout: 60

仅限管理员的LLM API：

• GET /admin/api/llm/endpoints （经过净化的端点列表）
• POST /admin/api/llm/test （一个端点的连接测试）

次级代理商(config.yaml)

子代理类型在中配置 subagents.types 并通过执行 subagent_run.

subagents:
  types:
    prompt_optimizer:
      display_name: "Prompt Optimizer"
      description: "Improve prompts for clarity and constraints"
      llm_endpoint: "primary"
      model: "gpt-4o-mini"             # optional (falls back to endpoint default)
      temperature: 0.3                 # optional
      max_tokens: 2048                 # optional
      system_prompt_file: "prompts/prompt_optimizer.md"
      response_format: null            # or "json"
      allow_model_override: false
      allow_temperature_override: false

机密文件

创建 secrets.env 与您的敏感值：

# secrets.env — mounted read-only into the container
GITHUB_TOKEN=ghp_your_token_here
DB_PASSWORD=super_secret
API_KEY=your_api_key

使用以下方法在任何工具参数中引用机密 {{secret:KEY}} 语法：

# Use a secret in an HTTP Authorization header
curl -X POST http://localhost:8080/api/tools/http/request \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.github.com/user",
    "method": "GET",
    "headers": {"Authorization": "Bearer {{secret:GITHUB_TOKEN}}"}
  }'

# List loaded secret key names (no values)
curl -X POST http://localhost:8080/api/tools/workspace/secrets/list

HTTP配置(config.yaml)

http:
  block_private_ips: true           # Block RFC 1918 / loopback ranges
  block_metadata_endpoints: true    # Block 169.254.169.254 and similar
  allow_domains: []                 # Empty = allow all (add entries to whitelist)
  block_domains:                    # Always blocked regardless of allowlist
    - "*.internal.example.com"
  max_response_size_kb: 1024        # Truncate responses larger than this
  default_timeout: 30               # Seconds
  max_timeout: 120                  # Hard cap regardless of request value

Docker Compose

services:
  anyide:
    build: .
    ports:
      - "8080:8080"
    environment:
      - ANYIDE_ADMIN_PASSWORD=admin
      # Legacy fallback: ADMIN_PASSWORD=admin
      - WORKSPACE_BASE_DIR=/workspace
      - ANYIDE_SKILLS_BASE_DIR=/skills
    volumes:
      - ./workspace:/workspace
      - ./skills:/skills
      - ./data:/data
      - ./secrets.env:/secrets/secrets.env:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro  # For Docker tools
      - ./config.yaml:/app/config.yaml:ro

______________________________________________________________________

管理仪表盘

特性

• 统一仪表板： 基于小部件的界面，一目了然地显示所有关键信息

- 可扩展/可折叠部分，便于灵活监控 - 通过WebSocket实时更新 - 直接从仪表板小部件快速操作

• HITL审批队列小部件：

- 批准/拒绝不带导航的工具执行 - 倒计时计时器和进度条 - 带有视觉警报的实时通知 - 桌面警报的浏览器通知

• 系统健康小部件：

- 带有颜色编码指示器的整体健康状况 - 关键指标：正常运行时间、待定HITL、执行的工具、错误率 - 快速访问详细的健康页面

• 最近活动小部件：

- 最后5次执行带有状态徽章的工具 - 快速统计：成功、错误、阻止计数 - 链接到带有过滤功能的完整审计日志

• 工具资源管理器页面：

- 按类别浏览所有可用工具 - 查看每个工具的JSON模式 - 见HITL要求和说明

• 配置页面：

- 查看当前服务器配置 - HTTP设置和策略规则 - 工作区和数据库路径 - 山宁泰LLM端点清单和端点测试行动

• 增强的系统健康页面：

- 带有进度条的实时CPU和内存使用情况 - 数据库和工作区磁盘大小 - WebSocket连接计数 - 系统信息：平台、Python版本、框架 - 工具类别状态概述

• 审计日志增强功能：

- 将日志导出为JSON或CSV - 按状态和工具类别筛选 - 大型数据集的分页

• 集装箱管理：

- 列出Docker容器的状态 - 从管理UI查看容器日志

• 专用页面：

- 具有详细请求信息的完整HITL队列管理 - 使用搜索、筛选和导出完成审核日志 - 详细的系统健康状况和性能指标 - 机密管理：列出加载的密钥名称，触发热重新加载

• 高级用户界面：

- 具有3D动画的玻璃形态设计 - 极光背景和浮动粒子 - 完全响应（移动设备、平板电脑、台式机） - 实时WebSocket更新 - 触摸友好交互

访问

http://localhost:8080/admin/

默认着陆： 具有所有小部件的统一仪表板\ 导航： 专用页面的侧栏菜单\ 文档： 看 admin/README.md 获取完整指南

______________________________________________________________________

可用工具

文件系统

• fs_read -使用行范围支持读取文件内容
• fs_write -写入文件内容（HITL用于.conf、.env、.yaml）
• fs_list -使用递归遍历和过滤列出目录内容
• fs_search -使用正则表达式支持按名称或内容搜索文件

外壳

• shell_execute -执行带有安全控制的shell命令

- 安全命令允许列表（ls、cat、echo、git、python、npm、docker等） - 危险元字符检测（；、|、&、>、\ docs/TOOL_CATALOG.md`

______________________________________________________________________

能力参考

核心平台

• FastAPI服务公开MCP(/mcp)OpenAPI(/api/tools/*)来自一个后端的接口。
• SQLite保存审计历史、HITL状态、内存图数据和计划编排状态。
• 统一LLM访问是一种共享系统功能(llm.endpoints + LLMClient)，不是LLM可见的工具类别。

安全与治理

• 工作区边界强制防止路径遍历和范围外文件访问。
• 策略引擎支持每个工具操作的允许、阻止和HITL操作。
• 秘密解决服务器端与 {{secret:KEY}}审计日志存储模板，而不是秘密值。
• HTTP工具包括对私有范围和云元数据端点的SSRF保护。

管理经验

• 密码保护的仪表板，带有实时HITL队列、健康指标和最近的活动。
• 工具资源管理器、配置查看器、审计过滤/导出和容器日志视图。
• 管理配置界面包括LLM端点列表和直接连接测试。
• 会话过期处理将用户重定向到 /admin/login 在未经授权的响应之后。
• 管理员API接受会话cookie，并且 Authorization: Bearer 退路。
• 仪表板API/WebSocket客户端支持反向代理路径前缀。

工具

• 文件系统、shell、git、docker、工作区、HTTP、语言、技能和子代理工具类别。
• 具有全文搜索和关系遍历功能的内存图工具。
• DAG计划编排，包括准备好的任务快照、任务引用和可配置的故障策略。

测试覆盖率快照

• pytest --collect-only -q 报告509个后端测试。
• 内存工具套件：48个测试。
• 计划编排套件：22个测试。
• HITL-WebSocket往返测试：7次测试。
• 工具资源管理器合约测试：13个测试。
• LLM端点/配置覆盖率：配置验证+客户端/适配器规范化+管理端点行为。
• 子代理API覆盖范围：模块注册、运行路径、覆盖控制和故障映射。
• 前端管理身份验证/会话测试使用Vitest+jsdom运行。

______________________________________________________________________

贡献

欢迎捐款。更喜欢集中的拉取请求，包括对行为变化的测试，并将评论/文档集中在持久的行为和操作指导上。

______________________________________________________________________

许可证

\[您的许可证在这里\]

______________________________________________________________________

支持

故障排除

1. 检查容器日志：

   docker compose logs anyide -f

1. 验证健康状况：

   curl http://localhost:8080/health

1. 测试管理员登录：

   curl -X POST http://localhost:8080/admin/api/login \
     -H "Content-Type: application/json" \
     -d '{"password": "admin"}'

1. 检查浏览器控制台 （F12）用于前端错误

常见问题

• 空白管理页面： 检查浏览器控制台，验证资产加载
• 登录失败： 验证有效的密码优先级和容器环境(ANYIDE_ADMIN_PASSWORD 优选地， ADMIN_PASSWORD 遗产）。
• HITL未出现： 在浏览器控制台中检查WebSocket连接
• 工具执行失败： 检查审核日志以了解错误详细信息

______________________________________________________________________

致谢

按照以下设计原则建造：

• 模型上下文协议（MCP）规范
• 打开WebUI OpenAPI工具服务器模式
• 高级UI的灵感来自Magic UI，Aceternity UI，21st.dev

______________________________________________________________________

状态： 生产就绪\ 版本： 0.1.0\ 最后更新时间： 2026年3月3日

______________________________________________________________________

测试

该项目包括全面的测试覆盖。

截至该快照， pytest --collect-only -q 报告 已收集509项测试 穿过：

• 核心模块和工具实现的单元测试
• API和管理端点集成测试
• MCP协议和HITL工作流程测试
• 安全回归测试（路径遍历、SSRF、身份验证强制、输入处理）
• 针对频繁的文件和API操作的负载/并发测试
• Git、Docker、内存图、计划编排、secrets、HTTP和LLM配置/客户端层的特定功能套件
• Tool Explorer合约测试验证基于OpenAPI的工具列表
• HITL WebSocket往返和断开连接弹性测试
• 管理身份验证/会话行为的前端单元测试（Vitest+jsdom）

最新验证运行：

• venv/bin/ruff check . 零皮棉违规通过。
• venv/bin/pytest 通过与 505 passed, 4 skipped 没有警告。
• 前端检查通过： npm test, npx tsc --noEmit，以及 npm run build 在 admin/.
• 打包和依赖性检查通过： python -m build, python -m pip check，以及 python -m compileall.