ARTEXX扩展开发指南:从加载Skills技能到接入远程MCP服务的完整教程
ARTEXX扩展开发指南:从加载Skills技能到接入远程MCP服务的完整教程
ARTEXX 是一款 AI 自主渗透测试系统(Go 后端 + Next.js 前端)。本教程面向新手,完整讲解 ARTEXX 扩展开发的两大核心玩法:加载 Skills 技能与接入远程 MCP 服务——前者让 Agent 学会一套标准作业流程,后者让 Agent 调用外部工具,读完即可独立完成扩展并绑定给指定 Agent。
一、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 个可直接参考的示例技能:
- skills/api-recon/SKILL.md —— 前端 API 接口侦察
- skills/playwright-cli/SKILL.md —— 浏览器自动化
- skills/scopesentry/SKILL.md —— 资产同步
每个技能就是一个目录,核心是一份 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 维度隔离,互不影响。
两个实用技巧:
- 技能门控 MCP:在
SKILL.md的 frontmatter 里给技能加上mcps: 服务名,则该服务的工具平时对 Agent 隐身,只有当 Agent 加载这个技能时才解锁——上下文更省、误调用更少(延迟/解锁机制见 agent/deferred.go 与 agent/assembly.go); - 查看谁用了什么:技能列表上带有调用次数、涉及任务数与最近使用时间的统计(
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 调教成专属于你的"定向侦察手"。动手写第一个技能试试吧!

