ARTEXX扩展开发指南:从加载Skills技能到接入远程MCP服务的完整教程

原创2026-10-16 22:45:131,329 阅读

ARTEXX扩展开发指南:从加载Skills技能到接入远程MCP服务的完整教程

ARTEXX 是一款 AI 自主渗透测试系统(Go 后端 + Next.js 前端)。本教程面向新手,完整讲解 ARTEXX 扩展开发的两大核心玩法:加载 Skills 技能与接入远程 MCP 服务——前者让 Agent 学会一套标准作业流程,后者让 Agent 调用外部工具,读完即可独立完成扩展并绑定给指定 Agent。

ARTEXX 仪表盘展示任务、Token 消耗与活动流总览

一、ARTEXX 的扩展机制全景:Skills、MCP 与 Agent 绑定

ARTEXX 的 Agent 能力由内置工具集提供,默认状态下 Agent 只能看到自己的"基础装备"。扩展体系由三个部件组成:

部件 作用 存储位置
Skills 技能 以 Markdown 书写的标准作业流程(SOP),Agent 需要时才加载 ./skills/ 目录
MCP 服务 遵循 Model Context Protocol 的工具服务器,提供可调用工具 数据库 mcp_servers 表
Agent 绑定 决定哪个 Agent 能看到哪些技能与 MCP 数据库 agent_visibility 表

源码中这一装配过程由 agent/assembly.go 完成:ToolAugment 会把某个 Agent 可见的 Skills(打包成一个 Skill 元工具)与可见 MCP(展开为 mcp__服务名__工具名 形式的工具)挂进它的工具集。未绑定时 Agent 保持原样,内置工具永不被过滤。

二、认识 Skills:一个目录 + 一个 SKILL.md

2.1 技能长什么样

ARTEXX 仓库自带了 3 个可直接参考的示例技能:

每个技能就是一个目录,核心是一份 SKILL.md,由 YAML frontmatter + Markdown 正文 两部分组成:

---
name: my-recon
description: 当需要收集目标网站 API 接口时调用该技能。
license: MIT          # 可选
compatibility: go 1.22 # 可选
mcps: my-mcp           # 可选:加载此技能时解锁的 MCP 服务
---

## 操作步骤
1. 第一步做什么
2. 第二步做什么
3. 完成标准是什么

字段规则(实现见 server/server_mgmt.go 的 fsCreateSkill):

  • name:1-64 位小写字母/数字/连字符,不能以连字符开头结尾、不能连续连字符;
  • description:必填,Agent 正是靠它判断何时该加载这个技能,建议写清"什么场景下调用";
  • mcps:可选。填写后,该 MCP 服务的工具在未加载此技能前对 Agent 不可见(schema 延迟下发),加载技能后自动解锁——这就是"技能门控(skill-gated)"机制,可有效控制上下文体积。

正文就是给 Agent 看的操作手册,建议写清楚:任务边界与禁止项、分步骤流程、完成定义。参考 skills/api-recon/SKILL.md 中"边界与禁止"表格的写法,效果很好。

三、三种方式加载你的技能

方式一:Web 页面创建(最简单)

登录后进入 系统配置 → 技能(路由 /system/skills,页面源码 web/src/app/(main)/system/skills/page.tsx/system/skills/page.tsx)),填写名称、描述后一键创建。后端会按 agentskills.io 规范自动骨架化出 SKILL.md,之后可直接在页面上编辑文件。

方式二:上传 zip 压缩包

将技能目录(含 SKILL.md)打包成 zip,通过页面上的上传按钮或 POST /api/skills/upload 接口上传。

打包时有几个"坑"(处理逻辑见 server/skill_zip.go):

要求 说明
必须未加密 AES/LZMA 等加密包会被拒绝
压缩方式 支持 Store、Deflate、bzip2、zstd;若用 7-Zip/WinRAR,请选 Deflate 或存储
中文文件名 工具会自动做 GBK→UTF-8 兜底解码,无需担心乱码
macOS 残留 __MACOSX/、.DS_Store 会被自动忽略

方式三:直接写文件到 skills/ 目录

克隆代码后(如需拉取仓库:git clone https://gitcode.com/gh_mirrors/ar/ARTEXX),在 ./skills/ 下新建目录放入 SKILL.md 即可,列表接口 GET /api/skills 会实时扫描该目录。Docker 部署时 ./skills 已做绑定挂载,升级不会丢失。

四、接入 MCP 服务:三种传输方式一次讲清

进入 系统配置 → MCP(路由 /system/mcp,页面源码 web/src/app/(main)/system/mcp/page.tsx/system/mcp/page.tsx)),点击新增,选择传输方式即可。连接与工具发现逻辑集中在 server/mcpdiscover.go。

4.1 stdio(本地进程)

适合运行在 ARTEXX 本机的 MCP 服务(如 npx 启动的浏览器 MCP):

  • 命令:可执行文件,如 npx -y @some/browser-mcp;
  • 参数:JSON 数组形式;
  • 环境变量:如 API_KEY=xxxx。

⚠️ 命令必须在 ARTEXX 所在环境(含 Docker 镜像)中可直接执行,找不到命令是最常见的"工具发现失败"原因。

4.2 http(远程 Streamable HTTP,推荐)

接入远程 MCP 服务的标准方式:

  • 远程 URL:如 https://mcp.example.com/mcp;
  • 请求头:按 键=值 逐行填写,例如 Authorization=Bearer xxxx;
  • insecure:自签证书场景可开启"跳过 TLS 校验"。

4.3 sse(旧版 SSE 兼容)

旧版 SSE 服务通过 GET /sse 建立事件流,再用服务返回的 /message?sessionId=... 接收 JSON-RPC 请求。配置时将 URL 填为 /sse 端点,请求头按 Authorization=Bearer <token> 填写。

4.4 工具自动发现与刷新

保存一个新启用的 MCP 后,后端会在 45 秒超时内自动连接它、拉取 tools/list 并缓存到 mcp_tools_cache 表(表结构见 db/schema.sql),页面随即展示工具清单,无需常驻连接。

  • 之前发现失败?点击卡片上的刷新按钮即可重新发现(POST /api/mcp/{id}/refresh);
  • 服务重启后,启用但缓存为空的 MCP 会在启动时后台自动补发现(见 discoverEmptyMCPsOnStartup)。

系统还预置了一个占位服务 ScopeSentry(http 传输、X-API-Key 请求头、默认未启用),填入地址与 Key 后即可用于资产同步。

五、把技能与 MCP 绑定给 Agent

扩展做好了,最后一步是"发装备":进入 系统配置 → Agent 管理(/system/agents,源码 web/src/app/(main)/system/agents/page.tsx/system/agents/page.tsx)),在对应 Agent(如 worker / mainagent)的配置里勾选它可见的 Skills 与 MCP。绑定关系写入 agent_visibility 表,按 Agent 维度隔离,互不影响。

ARTEXX Agent 管理页面,为指定 Agent 配置可见的 Skills 技能与 MCP 服务

两个实用技巧:

  1. 技能门控 MCP:在 SKILL.md 的 frontmatter 里给技能加上 mcps: 服务名,则该服务的工具平时对 Agent 隐身,只有当 Agent 加载这个技能时才解锁——上下文更省、误调用更少(延迟/解锁机制见 agent/deferred.go 与 agent/assembly.go);
  2. 查看谁用了什么:技能列表上带有调用次数、涉及任务数与最近使用时间的统计(GET /api/skills/{name}/usage);系统还会记录 Agent"想调用但不存在"的技能名(GET /api/skills/missing)——这张"缺口清单"就是你最该补写的下一个技能。

六、常见问题速查

现象 处理办法
zip 上传报"不支持的压缩方式" 改用 Deflate/存储重新打包,去掉加密
保存 MCP 后工具列表为空 先确认服务可达、命令可执行,再点"刷新"
远程 http 连接报证书错误 自签证书时勾选 insecure 跳过校验
Agent 看不到新加的工具 检查是否已在 Agent 管理中绑定,或该工具被技能门控未加载
重启后配置没了? 不会:mcp_servers 在数据库、./skills 在磁盘,升级均保留

七、小结

ARTEXX 的扩展路径非常清晰:写一个 SKILL.md → 放进 skills/ 或页面创建/上传 → 接一个 MCP 服务(stdio/http/sse)→ 在 Agent 管理中绑定。用技能沉淀你的操作流程,用 MCP 接入外部工具,再靠技能门控精细控制工具的可见性,就能把一个通用渗透 Agent 调教成专属于你的"定向侦察手"。动手写第一个技能试试吧!

登录后查看全文
ARTEXX