Subagents MCP

子代理MCP服务器（Go）

在stdio/JSON-RPC上运行1.23 MCP服务器，暴露出两个由Markdown定义的角色（YAML frontmatter）和可插拔运行器（Codex、Copilot、Gemini或Cursor-CLI）支持的工具。

概述

• 工具： list_agents 和 delegate_task 注册日期 tools/list 和 tools/call.
• 跑步者：离开 --runner 取消设置以尝试所有可用的CLI（Codex→ 副驾驶→ 双子座→ 默认情况下为光标）。通过 --runner 通过以下方式固定首选CLI，同时仍允许配置回退 --runner-config.
• 显式模型路由：当代理声明 model，跑步者支持必须明确列出在 --runner-config未知/未映射的模型会快速失败，并出现明显的选择器错误。
• 代理来源：绝对Markdown文件 --agents-dir；每个文件都包含用于元数据的YAML frontmatter(description，可选 model)以及身体中的角色内容（或 persona 在前台）。
• 护栏：代理目录和委托工作目录的绝对、现有、非根路径；相对路径被拒绝。
• 协议：MCP 2024-11-05使用服务器信息和工具功能初始化响应。

项目结构

• cmd/subagents –入口点解析标志和连接服务器。
• internal/agents –代理模型和Markdown frontmatter存储库加载器。
• internal/mcp JSON-RPC处理程序、工具模式、服务器循环、MCP错误。
• internal/runner –代理运行器接口以及Codex、Copilot、Gemini和Cursor实现。
• internal/validate –路径验证助手（绝对、存在、非根）。
• internal/logging –zap记录器设置。
• examples/agents –示例代理Markdown定义。

安装和设置

建议通过Go进行（全局）安装：

make install                         # go install ./cmd/subagents
echo 'export PATH="$(go env GOPATH)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc                      # pick up the PATH change
subagents --help

这将CLI编译为 $(go env GOPATH)/bin，Go工具已经期望将其放在您的PATH中。重新运行 make install 每当你提交新的提交时。

替代方案：保留一个repo本地二进制文件，并将该目录添加到PATH中：

make build-local                     # emits ./bin/subagents
echo 'export PATH="/absolute/path/to/subagents-mcp/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
subagents --help

如果你不想碰，这很方便 $(go env GOPATH)/bin；只要确保仓库在PATH入口点的任何地方都保持不变。

前提条件：

• 转到1.23+
• PATH上的Codex CLI并经过身份验证（用于 --runner codex)
• PATH上的GitHub Copilot CLI并经过身份验证（用于 --runner copilot)
• Gemini CLI位于PATH上并经过身份验证（用于 --runner gemini)
• PATH上的游标代理CLI并经过身份验证(curl https://cursor.com/install -fsS | bash那么 cursor-agent login 或出口 CURSOR_API_KEY)for --runner cursor

用法

运行服务器（自动选择运行程序）：

./subagents --agents-dir /abs/path/to/agents

更喜欢特定的跑步者（Copilot示例）：

./subagents --agents-dir /abs/path/to/agents --runner copilot

其他跑步者示例：

./subagents --agents-dir /abs/path/to/agents --runner gemini
./subagents --agents-dir /abs/path/to/agents --runner cursor

代理文件示例(/abs/path/to/agents/docs-fetcher.md):

---
description: "Docs excerpt fetcher"
model: "gpt-4o-mini"
---

You are a relentless documentation analyst who finds the smallest official
excerpts needed to answer the question, cites sources, and keeps summaries
short and precise.

委托合同：

• tools/call 随着 name: "delegate_task" 和论点：

  {
    "agent": "docs-fetcher",
    "task": "summarize latest release notes",
    "working_directory": "/absolute/workspace/path"
  }

退货 {"content":[{"type":"text","text":""}]}. 跑步者提示信封的结构如下：

  You are subagent "".

  Description: 

  Persona:
  

  Task:
  

• tools/call 随着 name: "list_agents" 回报 {"content":[{"type":"text","text":"{\"agents\":[...]}"}]} （JSON字符串 name 和 description 仅）。
• tools/call 随着 name: "expand_prompt" （也称为 prompt_expansion)和论点：

  {
    "command": "research",
    "input": "LLM routing frameworks"
  }

退货 {"prompt":""} 并且该提示必须被视为用户的明确指示，应逐字遵循。

路径规则：

• --agents-dir 和 working_directory 必须是绝对的、现有的目录，不能是 /；符号链接已解析。

建筑

简要概述生活 docs/architecture.md.

文档

• docs/architecture.md
• docs/api.md
• docs/modules.md
• docs/setup.md
• docs/research/ （例如。， 2025-12-01-cursor-agent-cli.md, 2025-12-02-cursor-cli-models.md)
• docs/decisions.md

技术栈

• 转到1.23
• zap用于结构化JSON日志
• gopk.in/yaml.v3用于代理解析
• Codex CLI（只读exec）、GitHub Copilot CLI（非交互式提示模式）、Gemini CLI（JSON输出模式）、Cursor代理CLI（文本模式自动化）