Agent Pattern MCP

agent-pattern-mcp

一个 MCP（Model Context Protocol）服务，为 AI 编码 Agent 提供 Agent 系统设计方面的专业知识。给定需求字符串和领域后，它会分析问题，从内置的 68 种模式中选出匹配项，生成具体的 Agent 系统设计，包括 Agent、关系、工具契约、状态模型和消息契约，并根据质量属性（可靠性、成本效益、延迟、输出质量、可观测性、安全性、简洁性）进行评估。自行编写实现的编码 Agent 可以调用 analyze_agent_system 获取拓扑结构和经过评分的模式指导，而无需生成设计。

---

目录

• ⚡ 快速开始
• 通过 AI Agent 安装
• 🔌 连接你的 Agent
  • Claude Code
  • OpenCode
  • Codex CLI
• 🧑‍🏫 面向 AI Agent 的 SKILL
• 🧪 使用工具
  • 设计你的第一个 Agent 系统
  • 探索模式目录
• 🛠️ 工具一览
• 📖 模式目录
• 其他安装方式
  • Docker（手动）
  • 本地开发（uv）
• 配置
• 结构化推理（shannonthinking / code-reasoning）
• 通过自定义模式扩展
• 长时间运行的工具和超时
• 故障排除
• 构建与开发
• 发布
• systemd 服务（Linux）
• 许可证

⚡ 快速开始

# 1. Clone
git clone https://github.com/olk/agent-pattern-mcp.git && cd agent-pattern-mcp

# 2. Add your API key (the dev compose reads MINIMAXAI_API_KEY and pins
#    GENERATOR_PROVIDER=minimax)
export MINIMAXAI_API_KEY=sk-...

# 3. Start (needs images: `make docker-build-all` once, or prebuilt pulls
#    per INSTALL.md Path A)
docker compose -f docker/docker-compose.yml up -d

# 4. Demo (analyze-only: fast. For the full design: make client-design)
make client-analyze

服务通过 streamable-http 启动，地址为 http://localhost:8821/mcp（dev compose 主机端口；systemd 使用 8811）。然后连接下方的 Agent。

---

通过 AI Agent 安装

如需让 AI 编码 Agent 从预构建镜像安装 Docker 堆栈（无需本地构建），请将其指向 INSTALL.md——这是非交互式 Agent 操作手册（包含复制粘贴命令、预期输出和验证探测）。

Clone this repo, then follow INSTALL.md Path A (compose stack, port 8821).
My generator API key is: sk-...

在 INSTALL.md 中选择一种路径：

• 路径 A — Compose 堆栈（:8821）：用于评估或开发，无需 sudo。使用独立的 TEI sidecar 副本。
• 路径 B — systemd 堆栈（:8811）：持久化主机服务，开机时启动，需要 sudo。使用共享的 pattern-tei-infra TEI 堆栈。

Agent 需要克隆仓库、安装 Docker ≥ v2.20 并加入相应用户组、预留约 5 GB 可用空间、提供 MINIMAXAI_API_KEY（或使用 INSTALL.md#switching-the-generator-llm 中的其他提供方），并运行在 linux/amd64 上（arm64 上会通过 make docker-build-all 在本地构建）。安装完成后，继续阅读下方的连接你的 Agent。

---

🔌 连接你的 Agent

Claude Code

# Install (one-time)
uv pip install -e .

# Run as stdio subprocess — pass API key via env
claude mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- agent-pattern-mcp --transport stdio

也可以将配置添加到项目中，供整个团队使用：

claude mcp add --scope project agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

OpenCode

OpenCode 使用 HTTP 传输。先启动服务，然后配置 opencode：

# Terminal 1: start the server
docker compose -f docker/docker-compose.yml up --build   # serves :8821
# or locally on the same port:
uv run python -m src.main --port 8821

# Terminal 2: add to ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-pattern": {
      "type": "remote",
      "url": "http://localhost:8821/mcp"
    }
  }
}

注意： GENERATOR_API_KEY 从服务的配置文件（~/.config/agent-pattern-mcp/config.json）读取，而不是从 opencode 的环境中读取。

Codex CLI

# Install (one-time)
uv pip install -e .

添加到 ~/.codex/config.toml：

[mcp_servers.agent-pattern]
command = "agent-pattern-mcp"
args = ["--transport", "stdio"]

[mcp_servers.agent-pattern.env]
GENERATOR_API_KEY = "your_key"
GENERATOR_PROVIDER = "openai"

或者通过 CLI 添加：

codex mcp add agent-pattern \
  -e GENERATOR_API_KEY=your_key \
  -- agent-pattern-mcp --transport stdio

---

🧑‍🏫 面向 AI Agent 的 SKILL

skills/agent-pattern-mcp/ 中的 SKILL 是为 Oh My Pi (OMP) 编写的。在 OMP 中，可通过 xd://mcp__agent_pattern_* 设备访问此服务的工具，且每个 MCP 请求都受截止时间限制（OMP_MCP_TIMEOUT_MS → 每服务的 timeout → 30 s）。它会教 Agent 根据截止时间选择合适的入口、如何读取结果，以及完整的工作流方案。

skills/agent-pattern-mcp/
├── SKILL.md                 # OMP constraints, entry-point decision guide, device quick reference
└── references/
    ├── tools.md             # 9 tool signatures, output schemas, error codes, design-dict shape
    └── workflows.md         # recipes, result interpretation, OMP troubleshooting

为 OMP 安装 — 将 skill 目录复制到用户 skills 根目录，或在 OMP 配置中将 skills.customDirectories 指向此仓库的 skills/ 目录：

cp -r skills/agent-pattern-mcp ~/.omp/agent/skills/

随后，skill 会告诉 Agent：

• 根据 OMP 的截止时间选择合适的入口：默认使用异步任务三件套；只有在提高服务的 timeout 后才使用一次性 design_agent_system（默认 30 s 下，所有 LLM 工具都会中止——submit_agent_design_job 约 0.05 s 即可响应）
• analyze_agent_system 是面向自行编写代码的编码 Agent 的纯分析路径——提供拓扑、评分后的模式和质量指标，不生成设计；而 design_agent_system 适用于需要设计产物的调用方
• 如何将 requirements、domain 和 topology 作为独立的结构化参数来表述
• 如何解读 final_quality_score、attempts > 1 和 evaluation.recommendations
• 连接了同级的 architecture-pattern 服务时，read mcp://pattern://… 存在歧义，因此工具路由（get_agent_pattern）才是权威路径

references/ 中的工具 schema、错误代码和 design-dict 结构均与客户端无关；只有截止时间和设备相关的指导针对 OMP。

---

🧪 使用工具

所有工具都接受 requirements（自由文本）和 domain（例如 tool-use-tasks、data-processing、customer-support）作为参数。以下示例展示了确切的工具调用形式，因此你可以在任意 MCP 客户端或 API 调用方中使用。

设计你的第一个 Agent 系统

在 Claude Code（或任意 MCP 客户端）中，粘贴以下自然语言指令：

Build a research assistant agent that answers multi-hop questions by combining
web search results with sandboxed Python computation, iterating until it can
synthesise a final cited answer.

你的 Agent 会在内部调用 design_agent_system。服务会返回完整的 Agent 系统设计：Agent（规划器、搜索器、编码器、综合器）、质量属性评分（可靠性：8.0，输出质量：8.5，……）以及具体建议。

这就是设计路径：服务的大模型会为你生成设计产物，因此调用需要几分钟。如果你的 Agent 会自行编写实现，只需要模式方面的专业知识，则改用 analyze_agent_system——它会返回推荐拓扑、选定模式及其评分、quality_metrics（每项属性评分为 0–10）和匹配的领域，不会生成设计，因此不会运行生成和评估阶段。实测依据：在此主机上进行的一次实时 analyze_agent_system 调用耗时 23.3 s；而已提交的完整流程语料库在 20 个场景中的 p50 约为 304 s，p95 约为 375 s（benchmarks/base/summary.json）。

或者直接从你的 Agent 调用工具：

Call analyze_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

Call generate_agent_system with:
  requirements: "Research assistant: decompose into sub-questions, search or code per sub-question, synthesise cited answer"
  domain: "tool-use-tasks"
  selected_patterns: ["react"]

Call evaluate_agent_system with:
  agent_system: { ... paste a design dict here ... }
  criteria: "reliability, safety"

Call list_agent_patterns()  # all 68 patterns
Call list_agent_patterns(category="multi_agent")  # filter by category
Call get_agent_pattern(name="supervisor-worker")   # full pattern JSON

异步任务模式：submit_agent_design_job + get_agent_design_status

仅适用于请求超时时间较短的客户端（Cursor、Claude Desktop、TS-SDK）。默认设计路径是带心跳防护的 design_agent_system。submit_agent_design_job 会立即返回 job_id；轮询 get_agent_design_status，直到任务完成：

# Step 1: start the job
Call submit_agent_design_job with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

# Step 2: poll every 10-30 seconds
Call get_agent_design_status with:
  job_id: "<job_id from step 1>"

# → status is "pending" | "running" | "completed" | "failed" | "cancelled"
# When status is "completed", the full design is in result.design
# When status is "failed", the error is in result.error

在 Python 中（直接通过 MCP HTTP API——参见 examples/agent_client_async.py）：

import asyncio
from fastmcp import Client

SERVER = "http://localhost:8821/mcp"
POLL_EVERY = 15  # seconds

async def main():
    async with Client(SERVER) as client:
        # Start
        started = await client.call_tool("submit_agent_design_job", {
            "requirements": "Research assistant: web search + sandboxed code for multi-hop questions",
            "domain": "tool-use-tasks",
        })
        job_id = started.data["job_id"]
        print(f"Job started: {job_id}")

        # Poll
        while True:
            await asyncio.sleep(POLL_EVERY)
            status = await client.call_tool("get_agent_design_status", {"job_id": job_id})
            data = status.data
            print(f"  status={data['status']}  message={data['message']}")
            if data["status"] in ("completed", "failed", "cancelled"):
                break

        print(data.get("result", data))  # full design when completed

完整且可运行的示例请参见 examples/agent_client_async.py。运行命令：

docker compose -f docker/docker-compose.yml up --build   # Terminal 1
make client-async                                      # Terminal 2

浏览模式目录

Call list_agent_patterns() with no filters to see all patterns.

也可以获取特定模式的详细信息：

Show me details about the react agent pattern.

---

🛠️ 工具一览

工具	说明
analyze_agent_system	供自行编写代码的 Agent 使用的纯分析路径：需求 + 领域 → 推荐拓扑、带评分的所选模式、质量指标（按属性计分，0–10）、匹配的领域。不生成设计。调用 1 次大模型（实测 23 秒）。非幂等。
generate_agent_system	根据需求和选定的模式生成 Agent 系统设计。长时间运行（大模型调用）。非幂等。
evaluate_agent_system	根据质量属性为现有设计评分。长时间运行（大模型调用）。非幂等。
design_agent_system	设计路径：完整流程（分析 → 生成 → 评估 → 优化，最多尝试 3 次）→ Agent、关系、工具契约、状态模型及评估结果。长时间运行（5–10 分钟）；调用方需要设计产物时使用此工具；如果客户端的请求超时时间较短，则使用这一组三个任务工具。
submit_agent_design_job	启动后台设计任务并立即返回 job_id。仅供请求超时时间较短的客户端使用（Cursor、Claude Desktop、TS-SDK）。其他客户端请使用 design_agent_system。每隔 10–30 秒轮询一次 get_agent_design_status。
get_agent_design_status	轮询任务状态。返回当前状态、进度消息，以及任务completed时的完整设计输出。
cancel_agent_design	取消正在运行的任务（尽力而为；在下一个流程阶段边界生效；可能需要等待最多 1 次大模型调用）。
list_agent_patterns	列出全部 68 个模式；按 category 和／或 domain 筛选
get_agent_pattern	按名称获取特定模式的完整 JSON

领域和拓扑是结构化参数——请将它们作为单独的工具参数传入，不要嵌入需求文本。

提示词示例：

Build a research assistant that answers multi-hop questions by combining
web search with sandboxed code execution, with full audit logging.

Design an agent system for customer-support automation handling 1M
conversations/day. Domain: customer-support. Topology: hierarchical.

Show me details about the reflexion pattern.

Call design_agent_system with:
  requirements: "Research assistant combining web search with sandboxed code execution for multi-hop questions"
  domain: "tool-use-tasks"

---

💬 提示词

此服务还提供四个由用户调用的工作流提示词（MCP 客户端中的斜杠命令）。与工具不同，大模型不会自主调用提示词——用户选择提示词并填写参数。每个提示词都封装了一套经过测试的工具编排方案。

提示词	参数	功能
/design_agent_system_workflow	requirements*	完整的分析 → 生成 → 评估流程
/explore_pattern_catalog	domain、category	通过嵌入的模式名称实时探索目录
/evaluate_my_agent_system	focus	引导评估标准并确定发现的优先级
/compare_agent_topologies	topology_a*、topology_b*、requirements*	并排比较两种设计；Token 成本约为 2 倍

* = 必填参数

仅支持工具的客户端

仅支持工具协议（不支持原生 prompts/list 或 prompts/get）的客户端，可以通过生成的 list_prompts 和 get_prompt 工具访问全部四个工作流提示词；这些工具会经过服务端的中间件链路，与原生提示词调用完全相同。

---

📖 模式目录

通过 MCP 工具（推荐——适用于所有客户端）

list_agent_patterns()                                  # all 68 patterns
list_agent_patterns(category="multi_agent")            # filter by category
list_agent_patterns(domain="tool-use-tasks")           # filter by domain
get_agent_pattern(name="supervisor-worker")            # full pattern JSON

有效的 category 值：reasoning、tool_use、planning、reflection、research_synthesis、multi_agent、memory、retrieval、safety_control、observability。

通过 MCP 资源

pattern://                    → list of all patterns
pattern://{name}              → full pattern JSON
template://{name}             → curated design templates (react, supervisor-worker, multi-agent-debate, agentic-rag)
component://{type}            → component blueprints derived from pattern data

**注意：**如果同时连接了同级的 architecture-pattern-mcp 服务，pattern://{name} 会产生歧义（两个服务都注册了该协议）；应以工具路由（get_agent_pattern）为准。

模式 JSON 结构

每个模式包含：name、category、topology、context、benefits、tradeoffs、quality_attributes（reliability/cost_efficiency/latency/output_quality/observability/safety/simplicity，数值评分）、suitable_domains、component_types、technology_stack、design_principles、best_practices。

必填字段：name、context、category、topology、suitable_domains、quality_attributes（全部 7 个键）。

---

安装替代方案

Docker（手动）

# Build the image
make docker-build

# Run with your API key
MINIMAXAI_API_KEY=your_key docker compose -f docker/docker-compose.yml up -d

本地开发（uv）

前置条件： Python 3.12+、uv

# Install
make install

# Configure
cp config/config.json ~/.config/agent-pattern-mcp/config.json
# Edit ~/.config/agent-pattern-mcp/config.json and set your GENERATOR_API_KEY

# Run the server
uv run python -m src.main --transport stdio              # for Claude Code / Codex
uv run python -m src.main --port 8050                    # for OpenCode (HTTP, default)

或者使用已安装的控制台脚本（在执行 make install 后）：

agent-pattern-mcp --transport stdio

领域范围模式检索需要 TEI 嵌入器（Qwen3-Embedding-0.6B）。没有它时，服务会回退到默认模式。Docker compose 会自动启动它；本地用户必须单独在端口 8080 上运行它。

检索分支在服务启动时构建：始终构建 BM25；若存在有效快照，则从嵌入索引缓存构建 FAISS 稠密检索分支（否则从头开始嵌入）。启动保持快速失败——每次启动都会执行一次探测嵌入调用，因此配置错误或无法访问的 TEI sidecar 会中止预热，而不是导致用户的首次设计请求失败。Docker compose 的 service_healthy 依赖顺序可确保 TEI 在应用启动前就绪。

TEI 启动： 两个 sidecar 镜像（docker/Dockerfile.tei-embed、docker/Dockerfile.tei-rerank）都包含自行构建的 TEI 路由器（v1.9.4 + 尚未合并的 PR #884），默认设置 WARMUP_TOKENS=0——这会跳过合成预热阶段（实测嵌入约需 131 s / 重排约需 78 s），使容器仅在权重加载完成后就绪。可通过 TEI_WARMUP_TOKENS / TEI_RERANK_WARMUP_TOKENS 分别覆盖每个 sidecar 的设置（正整数 N 会使用 N 个 token 进行预热；大于 MAX_BATCH_TOKENS 的值会在启动时被拒绝）。

GPU TEI： 随附的 sidecar 是 CPU 镜像（FROM ghcr.io/huggingface/text-embeddings-inference:cpu-1.9，ORT 后端——此模型的批次上限为 8），Stage-0 路由器也仅针对 CPU 构建（--features ort,http）。本仓库不提供 GPU 构建方案——若要在 CUDA 上运行，需要将运行时基础镜像改为 :cuda-1.9，并使用 CUDA 功能集重新构建路由器；这不是本仓库支持的方案（只有 design-pattern-mcp-local 提供此方案：make docker-build-tei-embed-gpu）。不包含 PR #884 的上游标准 TEI 镜像会静默忽略 WARMUP_TOKENS。

已在运行的嵌入器/重排器： 如果嵌入和重排端点已在其他服务上运行，可将 MCP 服务指向这些端点并跳过 sidecar（docker/docker-compose.hub.yml 只会启动 MCP 服务，并按此方式配置）。远程嵌入器必须是提供相同模型的 TEI——保持 EMBEDDER_PROVIDER=tei，并将 EMBEDDER_BASE_URL 设为其 OpenAI 兼容路由（http://<host>:8080/v1，即 config.json 中的默认值）。此服务的嵌入器配置没有 model 字段（src/patterns/embedder.py::build_embedder 会为非 tei 提供方发送空模型名称），因此 openai / ollama / vllm / hosted_vllm 无法在不修改代码的情况下指定任意远程模型。重排器不是 LiteLLM 客户端——它会直接向 {RERANKER_BASE_URL}/rerank 发送 POST 请求（默认值为 http://pattern-tei-rerank:8080，没有 /v1）；LiteLLM 嵌入文档中的提供方/模型语法仅适用于嵌入器。EMBEDDER_API_KEY 会作为 LiteLLM 的 api_key 转发（任意非空字符串都可用于无需身份验证的 TEI）。

---

配置

config.json

服务会读取 ~/.config/agent-pattern-mcp/config.json（可使用 --config-path 覆盖）：

{
  "generator": {
    "provider": "openai",
    "config": {
      "model": "gpt-4o-mini",
      "base_url": "https://api.openai.com/v1",
      "api_key": "{env:GENERATOR_API_KEY}",
      "temperature": 0.1,
      "top_p": 1.0,
      "top_k": 20
    }
  },
  "embedder": {
    "provider": "tei",
    "config": {
      "base_url": "http://pattern-tei-embed:8080/v1"
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "min_quality_score": 50.0
  },
  "pattern_directory": "~/.config/agent-pattern-mcp/pattern",
  "transport": "streamable-http",
  "host": "0.0.0.0",
  "port": 8050,
  "logging_level": "INFO",
  "logging_format": "json"
}

{env:VAR:-default} 语法会在加载时展开环境变量。

生成器大模型（LlamaIndex LiteLLM）

生成器大模型通过 LlamaIndex LiteLLM 集成（llama-index-llms-litellm）访问。因此，所有提供商设置均遵循 LiteLLM 的模型语法：<provider>/<model>（例如 openai/gpt-4o-mini、anthropic/claude-sonnet-4-5、openrouter/minimax/minimax-m2）。

服务端根据你的配置，将 LiteLLM 模型字符串组合为 generator.provider + generator.config.model：

配置 / 环境变量	示例	生成的 LiteLLM 模型字符串
provider: "openai"，model: "gpt-4o-mini"	GENERATOR_PROVIDER=openai，GENERATOR_MODEL=gpt-4o-mini	openai/gpt-4o-mini
provider: "anthropic"，model: "claude-sonnet-4-5"	GENERATOR_PROVIDER=anthropic，GENERATOR_MODEL=claude-sonnet-4-5	anthropic/claude-sonnet-4-5
provider: "openrouter"，model: "minimax/minimax-m2"	GENERATOR_PROVIDER=openrouter，GENERATOR_MODEL=minimax/minimax-m2	openrouter/minimax/minimax-m2

如果配置的模型已包含提供商前缀（例如 openai/gpt-4o-mini），则会去除该前缀，并替换为配置的 provider。

• 提供商列表、模型名称和确切的 <provider>/<model> 语法： LiteLLM 提供商文档
• 自定义 / OpenAI 兼容端点（代理、vLLM、Ollama 等）：设置 GENERATOR_BASE_URL（generator.config.base_url）——该值会作为 LiteLLM 的 api_base 传入
• GENERATOR_API_KEY 会作为 LiteLLM 的 api_key 传入；temperature、top_p、top_k 和 stream 会映射到相应的 LiteLLM 参数

关键环境变量

变量	默认值	描述
GENERATOR_API_KEY	(必填)	大模型提供商的 API 密钥（作为 api_key 传递给 LiteLLM）
GENERATOR_PROVIDER	openai	LiteLLM 提供商前缀：openai、anthropic、openrouter、… — 请参阅 LiteLLM 提供商
GENERATOR_BASE_URL	https://api.openai.com/v1	API 基础 URL（作为 api_base 传递给 LiteLLM）
GENERATOR_MODEL	gpt-4o-mini	模型名称；最终模型字符串为 <GENERATOR_PROVIDER>/<GENERATOR_MODEL>（LiteLLM 语法）
GENERATOR_TEMPERATURE	0.1	采样温度
GENERATOR_TOP_P	1.0	Top-p 采样
GENERATOR_TOP_K	20	Top-k 采样
GENERATOR_STREAM	false	启用流式响应
EMBEDDER_PROVIDER	tei	嵌入器提供商
EMBEDDER_BASE_URL	http://pattern-tei-embed:8080/v1	TEI 嵌入器 URL
EMBEDDER_BATCH_SIZE	16	嵌入批次大小
EMBEDDER_QUERY_INSTRUCTION	(空)	查询指令前缀
EMBEDDER_TEXT_INSTRUCTION	(空)	文本指令前缀
EMBEDDING_CACHE	image: /var/cache/agent-pattern-mcp/embedding-index · host: ~/.config/agent-pattern-mcp/embedding-index	Dense-leg 快照路径：重启时重新加载（无需重新嵌入语料），嵌入器、语料或探测发生任何变化时重建。设为 0/false/off/no 可禁用。请参阅 嵌入索引缓存
RETRIEVAL_BM25_TOP_K	0	BM25 第一阶段召回上限（0=完整语料）
RETRIEVAL_DENSE_TOP_K	0	Dense 第一阶段召回上限（0=完整语料）
RETRIEVAL_DENSE_WEIGHT	0.7	第一阶段融合中 Dense 部分的权重。与 RETRIEVAL_BM25_WEIGHT 配合使用；两者都必须大于 0，且总和为 1.0。
RETRIEVAL_BM25_WEIGHT	0.3	第一阶段融合中 BM25 部分的权重。请参阅 RETRIEVAL_DENSE_WEIGHT。
RETRIEVAL_TOP_K_PATTERNS	5	要选择的模式数量
RETRIEVAL_MIN_FUSION_SCORE	0.0	rank_fusion 融合值的相关性下限。默认值为 0.0（禁用门限）。
RETRIEVAL_RERANK_TOP_N	10	重排前 N 项（CE 后按 slug 截断）
RETRIEVAL_USE_LEAN_WIRE_SCHEMA	false	使用精简响应架构（省略自由格式契约列表；dev/systemd compose 文件中，此项对于 MiniMax 生成器默认设为 true）
RETRIEVAL_TOPOLOGY_SCORE_THRESHOLD	50.0	拓扑推荐的最低分析分数
REASONING_ENABLED	true	服务端推理 MCP 集成 — 默认开启（请参阅 结构化推理）
REASONING_SPAWN_TIMEOUT_SECONDS	10	每个推理工具的子进程启动超时
REASONING_STEP_TIMEOUT_SECONDS	20	每次思考工具调用的超时时间
REASONING_MAX_TOTAL_STEPS	8	每个阶段推理步数的硬性上限
REASONING_QUIET_STDERR	true	隐藏推理子进程的 stderr（ASCII 进度框、[info] 横幅）；设为 false 可调试启动失败问题
REASONING_FAIL_FAST	true	推理工具无法访问时，服务器启动失败
REASONING_SHANNONTHINKING_CMD	(内置)	shannonthinking 的 JSON 列表命令（例如 ["npx","-y","server-shannon-thinking@latest"]）
REASONING_CODE_REASONING_CMD	(内置)	code-reasoning 的 JSON 列表命令
RETRIEVAL_ANALYSIS_BLEND_WEIGHT	0.7	融合中分析分数的权重
RETRIEVAL_FUSION_BLEND_WEIGHT	0.3	融合中融合分数的权重
RETRIEVAL_WEIGHT_SMOOTHING_ALPHA	0.7	权重平滑 alpha
PIPELINE_TIMEOUT_SECONDS	1200	一次完整设计运行的墙钟时间预算（秒）——包括所有阶段（分析 → 生成 → 评估 → 改进）和每次重试。超时后运行将取消，工具调用会失败并返回 WorkflowTimeoutError；部分设计结果将被丢弃。若在速度较慢的提供商上启用 REASONING_ENABLED=true，请调高此值；若要快速失败，请调低此值。配置键：pipeline.timeout_seconds。
RETRIEVAL_VERBOSE_TIMING	false	以 INFO 级别记录各阶段耗时
RETRIEVAL_MAX_TRIES	2	设计循环的最大尝试次数
RETRIEVAL_MIN_QUALITY_SCORE	50.0	提前停止的质量阈值
RERANKER_BASE_URL	http://pattern-tei-rerank:8080	TEI 重排器端点
RERANKER_TIMEOUT	30.0	重排器超时时间（秒）
RERANKER_MAX_BATCH_SIZE	48	每个 TEI /rerank 请求的最大文本数；必须 ≤ 重排器 sidecar 的 MAX_CLIENT_BATCH_SIZE 和 MAX_CONCURRENT_REQUESTS 中的较小值。HybridPatternRetriever 会自动对大型候选池分块。
PATTERN_DIRECTORY	~/.config/agent-pattern-mcp/pattern	模式文件目录
VALIDATION_MAX_RETRIES	2	自我修复的最大重试次数
VALIDATION_RETRY_ON_FAIL	true	验证失败时重试
AGENT_PATTERN_JOBS_DB	~/.config/agent-pattern-mcp/jobs.db	异步任务三件套的 SQLite 路径。可覆盖此值以隔离测试
TASKS_HEARTBEAT_ENABLED	true	工具调用耗时较长时发送进度通知
TASKS_HEARTBEAT_INTERVAL_SECONDS	30	心跳间隔（秒；应低于客户端空闲超时时间）
TRANSPORT	streamable-http	传输模式：stdio、streamable-http
HOST	0.0.0.0	HTTP 绑定主机
PORT	8050	HTTP 绑定端口（容器内；dev compose 发布的主机端口为 8821，systemd 发布的端口为 8811）
LOGGING_LEVEL	INFO	日志级别
LOGGING_FORMAT	json	日志格式：json、text
CONFIG_PATH	~/.config/agent-pattern-mcp/config.json	配置文件路径

注意： dev 和 systemd compose 文件将 RETRIEVAL_BM25_TOP_K=20 / RETRIEVAL_DENSE_TOP_K=20（每路第 1 阶段上限）和 RETRIEVAL_MIN_FUSION_SCORE=0.015 设为高于上述配置默认值的值。已部署的 MiniMax 生成器配置块（GENERATOR_PROVIDER=minimax、GENERATOR_MODEL=minimax/MiniMax-M2.7、GENERATOR_BASE_URL=https://api.minimax.io/v1、RETRIEVAL_USE_LEAN_WIRE_SCHEMA=true）也与 OpenAI 配置默认值不同。

嵌入索引缓存（密集检索快照）

密集检索路径是一个覆盖目录中所有领域 slug 的 FAISS 索引（已发布的 68 个模式目录中有 36 个）。冷启动构建后，其嵌入会保存到磁盘，并在下次启动时重新加载，因此热启动只需生成一个探测嵌入，而无需遍历整个语料库（在开发用 TEI sidecar 容器上测得，36 个 slug：3.3 s → 0.28 s）。BM25 开销很低，每次启动都会重新构建。

• 路径：EMBEDDING_CACHE。镜像内置路径为 /var/cache/agent-pattern-mcp/embedding-index；主机运行（uv）使用 ~/.config/agent-pattern-mcp/embedding-index。
• 文件所在位置：日志中显示的路径是容器内视图。Docker 会将命名卷存储在 /var/lib/docker/volumes/<volume-name>/_data （由 root 拥有），因此主机上的 /var/cache 按设计会保持为空。无需 sudo 即可检查： docker exec <container> ls /var/cache/agent-pattern-mcp/embedding-index，或使用 docker volume inspect -f '{{.Mountpoint}}' <volume-name> 查看主机端路径。
• 容器会将缓存持久化到命名卷 （agent-pattern-mcp-dev-embedding-index / agent-pattern-mcp-systemd-embedding-index），因此快照在镜像重建、容器重建和 docker compose down 后仍会保留。使用 docker compose down -v 或 docker volume rm <name> 重置；直接使用 docker run 时需要添加 -v agent-pattern-mcp-embedding-index:/var/cache/agent-pattern-mcp/embedding-index。
• 以下情况会自动重建：嵌入函数发生变化（提供方、 base_url、解析后的模型名称、查询/文本指令前缀），slug 语料库发生变化，或探测向量表明未更改的配置背后使用了不同模型 （例如重新部署的 TEI sidecar）。日志行： Embedding index cache hit: N slugs, 0 corpus embed calls (snapshot <cache-dir>) / Embedding index cache miss (<reason>); embedding corpus / Embedding index snapshot written: N slugs (path <cache-dir>)——在嵌入处理完成后立即输出，早于其他任何启动步骤；关闭缓存时则输出 Embedding index cache disabled; embedding corpus（绝不会报告缓存未命中）。
• 单写入者：不加锁——每个缓存目录只运行一个服务进程。 快照写入失败时只会记录警告；服务会在无缓存状态下运行，启动不会失败。
• 运维说明（卷、权限、禁用开关）：INSTALL.md。

CLI 标志

标志	描述
--transport {stdio,streamable-http}	覆盖传输模式
--host	覆盖 HTTP 绑定主机（默认：0.0.0.0）
--port	覆盖 HTTP 端口（默认：8050）
--config-path	配置文件路径
--health	运行健康检查并退出

---

结构化推理（shannonthinking / code-reasoning）

在每个 LLM 阶段调用（ANALYZE / GENERATE / EVALUATE / RETRY）之前，服务可选择运行有界的 ThoughtGenerator 循环：使用生成器自己的 LLM（LlamaIndex LiteLLM；每个步骤完成一次调用）编写每个推理步骤，并将其提交给 shannonthinking 和/或 code-reasoning MCP 服务——这些结构化思考暂存区会验证、编号并记录每个步骤。生成的轨迹会作为 <reasoning_context> 块注入阶段提示词中。约定：每个思考 = 1 次 LLM 调用 + 1 次 MCP 工具调用，上限由 REASONING_MAX_TOTAL_STEPS 限定（默认为 8）。

主要特性：

• 嵌入 Docker — build-mcps 阶段会将两个 npm 包（[email protected]、@mettamatt/[email protected]）打包到镜像的 /usr/local/lib/node_modules/... 中；运行时通过 node 直接调用（无需网络，也不使用 npx）。
• 在 Docker 外自动回退到 npx — 如果找不到嵌入的入口点，客户端会回退到 npx -y <pkg>（首次调用时会下载）。
• 每次调用均隔离进程 — 每次工具调用都会在新的子进程中运行（keep_alive=False）；调用之间不会保留任何内容。
• 单次调用静默降级 — 任何启动、超时或工具故障都会记录一条 WARNING，阶段则会继续使用降级的提示词内思考脚手架（分解 → 分类 → 校准 → 解决 → 验证）；不会引发异常。
• 启动时明确报错 — 生命周期健康检查会探测这两个工具；如果其中一个无法访问，就会记录一条 ERROR（并提供解决建议）。设置 REASONING_FAIL_FAST=true 可改为让启动失败。
• 轨迹缓存 — 每个设计请求只计算一次 ANALYZE 和 GENERATE 轨迹，并在设计循环的多次尝试中复用。

启用与调整

在此仓库部署的堆栈中，推理默认已启用（两个 compose 文件都设置了 REASONING_ENABLED=true）：

export REASONING_ENABLED=true           # enable the reasoning MCP integration
export REASONING_FAIL_FAST=true         # refuse to start with broken MCPs

各阶段的工具选择（默认值位于 src/reasoning/config.py::_default_per_phase）： analyze 使用 ["code", "shannon"] × 4 个思考步骤，generate 使用 ["code"] × 3 个思考步骤，evaluate 使用 ["shannon"] × 3 个思考步骤，refine 使用 ["code", "shannon"] × 2 个思考步骤。 一次完整的设计运行最多会发起 24 次推理工具调用，均以串行子进程运行——耗时是几分钟，而不是几秒钟。

本地（非 Docker）开发需要 Node.js；可以全局安装这些包（npm install -g server-shannon-thinking @mettamatt/code-reasoning），也可以让 npx 回退机制在首次使用时下载它们。

设置 LOGGING_LEVEL=DEBUG，即可捕获每次逐步推理调用所编写的 thought 和工具响应。Docker/systemd 堆栈默认使用 INFO；运行 make docker-up 前请导出 LOGGING_LEVEL=DEBUG。

---

使用自定义模式扩展

模式文件从 ~/.config/agent-pattern-mcp/pattern/ 加载（可通过 PATTERN_DIRECTORY 配置）。将 JSON 文件放在 68 个内置模式旁即可。

最简模式结构：

{
  "category": "tool_use",
  "name": "my-custom-pattern",
  "topology": "single-agent-loop",
  "context": "Describe when this pattern applies.",
  "benefits": ["Benefit 1", "Benefit 2"],
  "tradeoffs": ["Tradeoff 1"],
  "quality_attributes": {
    "reliability": 7,
    "cost_efficiency": 6,
    "latency": 7,
    "output_quality": 7,
    "observability": 6,
    "safety": 7,
    "simplicity": 5
  },
  "suitable_domains": ["tool-use-tasks"]
}

必需字段：name、context、category、topology、suitable_domains、quality_attributes（全部 7 个键）。

有效的 category 值：reasoning、tool_use、planning、reflection、research_synthesis、multi_agent、memory、retrieval、safety_control、observability。

包含所有枚举值的完整 JSON Schema：docs/pattern-schema.json

---

长时间运行的工具与超时

design_agent_system 会运行多阶段大模型流水线，每次调用可能需要 5–10 分钟。单阶段工具的开销要小得多：analyze_agent_system 只进行一次分析大模型调用（在此主机上测得为 23.3 秒），返回拓扑结构和评分后的模式，不会生成设计；而 generate_agent_system 和 evaluate_agent_system 则各进行一次大型补全。设计调用耗时长是任务本身所致，并非错误：生成器大模型必须处理大量输入内容——从 68 种模式目录中选出的模式定义、你的需求，以及前面每个阶段的完整输出——然后逐个生成大型、严格遵循结构的 JSON 文档（包括 Agent、关系、工具契约、状态模型、消息契约和质量评分）。design_agent_system 流水线会重复执行生成 → 评估，最多三次，因此单次调用可能包含 9 次以上大模型往返。

超时问题

MCP 客户端（AI 编码 Agent、MCP SDK）位于服务端和大模型之间。许多客户端实现了客户端空闲超时：如果 HTTP 连接在一段时间内（通常为 30–120 秒）没有收到数据，客户端就会中止请求。此时服务端仍在工作——大模型仍在生成——但客户端会关闭连接，并向 Agent 报告超时错误。

这是客户端行为，而非服务端行为。服务端会正确处理完整请求；只是客户端在收到响应前放弃了。

受影响的客户端（超时时间较短且硬编码）：

客户端	超时时间	备注
Claude Desktop（TS-SDK）	60 秒	硬编码；不会因进度通知而重置
Cursor（TS-SDK）	60 秒	与 Claude Desktop 相同
其他基于 TS-SDK 的 Agent	不定	大多数上限为 60–120 秒

这些客户端无法配置为接受更长的超时时间——超时限制已内置于 SDK 中。

心跳防护机制支持的客户端：

客户端	超时时间	防护机制
Claude Code	约 300 秒	每 30 秒发送一次心跳，重置空闲计时器
OpenCode	约 300 秒	每 30 秒发送一次心跳，重置空闲计时器
Codex CLI	约 300 秒	每 30 秒发送一次心跳，重置空闲计时器
其他 HTTP 传输 Agent	不定	大多数会在收到任何数据时重置计时器

这些客户端适用此机制，因为它们的空闲计时器会在收到任何数据时重置——服务端通过并行异步任务发送的心跳 progress 通知会被客户端接收，从而重置计时器。

心跳防护机制（默认启用）

每个长时间运行的工具都会通过并行协程每 30 秒发送一次 progress 通知（可通过 TASKS_HEARTBEAT_INTERVAL_SECONDS 配置）。只要客户端会在收到任何数据时重置空闲计时器，请求就能在整个流水线运行期间保持连接。

TS-SDK 客户端（Claude Desktop、Cursor 等）不会因进度通知而重置超时时间。

异步任务三件套（适用于受超时限制的客户端）

为全面控制并兼容受超时限制的客户端，三个工具提供了持久化任务句柄：

submit_agent_design_job(requirements, domain, override_topology)  → job_id
get_agent_design_status(job_id)                                     → {status, result, error}
cancel_agent_design(job_id)                                         → {cancelled, status}

submit_agent_design_job 会在几毫秒内返回一个 job_id。流水线会在后台任务中运行。每隔 10–30 秒轮询一次 get_agent_design_status(job_id)。状态为 completed 时，完整设计会位于 result 字段中。取消操作尽力而为——任务会在下一个流水线阶段边界退出。

这是唯一适用于 TS-SDK 客户端（Claude Desktop、Cursor）的解决方案。

任务存储为 SQLite 数据库，位于 ~/.config/agent-pattern-mcp/jobs.db（可通过 AGENT_PATTERN_JOBS_DB 配置）。

使用直接 HTTP 客户端绕过客户端超时

examples/agent_client.py 中的示例客户端是一个直接 Python HTTP 客户端，并不是 MCP Agent。它通过 HTTP 调用服务，不使用 MCP SDK，因此没有客户端空闲超时：它会发起一个阻塞请求，并等待完整响应。

# Start the server (from project root)
docker compose -f docker/docker-compose.yml up --build

# In another terminal: fast analyze demo / full design demo (minutes)
make client-analyze        # analyze_agent_system only
make client-design         # design_agent_system, the long synchronous call

两个目标都使用同一个直接客户端（--tool analyze|design）。make client-design 演示了服务能够正确完成长时间运行的请求——超时问题纯粹出在客户端。在生产环境中使用 MCP Agent 时，心跳防护可覆盖大多数客户端；异步作业三件套是通用的备用方案。

---

故障排除

服务已启动，但看不到工具

1. 检查 Agent 的 MCP 连接：Claude Code 使用 /mcp，OpenCode 使用 opencode mcp list，Codex 使用 codex mcp list
2. 验证服务进程已启动：compose 日志应显示 MCPAgentPatternServer initialized
3. 确认 TEI 嵌入器运行正常：docker exec agent-pattern-mcp python -c "import urllib.request; print(urllib.request.urlopen('http://pattern-tei-embed:8080/health').status)"

出现“Connection refused”或超时错误

服务会等待 TEI 嵌入器运行正常：

docker compose -f docker/docker-compose.yml logs agent-pattern-mcp

LLM 提供商错误（502 / 401）

• 确认已设置 GENERATOR_API_KEY 且未过期
• 验证 GENERATOR_BASE_URL 与你的提供商端点一致
• 如果使用代理，请检查容器内部是否可以访问

未加载 Pattern JSON 文件

• 文件必须使用 .json 扩展名，并匹配 *-pattern.json
• 必需字段：name、context、category、topology、suitable_domains、quality_attributes（全部 7 个键）
• 检查启动日志中是否有 Pattern validation failed 警告

---

构建与开发

常用 make 目标（完整参考：docs/make_rules.md）：

目标	说明
make install	以可编辑模式安装软件包及开发依赖
make check-lint	运行 ruff 代码检查
make check-static-typing	对 src/ 运行 mypy --strict 类型检查
make check-all	运行所有 check-* 质量门禁（代码检查、类型检查、死代码、依赖项）
make test-unit	使用 uv 运行单元测试（tests/unit/）
make test-oracles	运行可执行验证 oracle（tests/verification/）
make client-analyze	运行仅分析的 MCP 客户端演示（需要服务正在运行）
make client-design	运行同步 design_agent_system 客户端演示（长时间运行；需要服务正在运行）
make client-async	运行异步作业三件套演示（需要服务正在运行）
make docker-build	构建 MCP 服务 Docker 镜像
make docker-build-all	构建 MCP 服务、TEI 嵌入器和重排器镜像
make docker-publish	将镜像推送到 Docker Hub 和 GHCR（版本标签 + latest）
make docker-up	构建并启动所有服务
make docker-down	停止所有服务

开发工作流：

make install                      # First-time setup
uv run pre-commit install         # First-time setup: commit hook
make check-all                    # Before pushing (lint + types + dead code + deps)
make docker-build-all             # Build both images (first time and after code changes)
make docker-up                    # Start services
make docker-logs-follow           # Watch logs
make docker-down                  # Stop

---

发布

全部三个镜像会同时发布到两个镜像仓库：

镜像	Docker Hub	GHCR	标签
MCP 服务	olkowa/agent-pattern-mcp	ghcr.io/olk/agent-pattern-mcp	$(DOCKER_TAG)、latest
TEI 嵌入器	olkowa/pattern-tei-embed	ghcr.io/olk/pattern-tei-embed	$(DOCKER_TAG)、latest
TEI 重排器	olkowa/pattern-tei-rerank	ghcr.io/olk/pattern-tei-rerank	$(DOCKER_TAG)、latest

全部三个镜像共用同一个 $(DOCKER_TAG)（来自 pyproject.toml 的版本号），因此 tei:1.0.3 总是与 mcp:1.0.3 一同发布。Blob 去重让未更改的 TEI 镜像重新打标签的成本很低。

**带宽说明：**TEI 嵌入器镜像约为 5 GB（内置 ONNX fp32 权重）。首次推送到每个镜像仓库时，上传量约为 5 GB。后续推送为增量推送，只传输有更改的层。

前提条件

Docker Hub——已在本地完成身份验证（docker login）。

GitHub Container Registry——需要一个具有 write:packages 作用域的经典 PAT。启用双重身份验证不影响使用——PAT 可绕过它。登录后，令牌会被丢弃；凭据会一直保存在 ~/.docker/config.json 中，直到你注销。

发布（一次性设置 + 每个会话）

# 1. Login to GHCR (interactive — paste token at the password prompt)
docker login ghcr.io -u olk

# 2. Build and push all three images (MCP + TEI embedder + TEI reranker)
#    The umbrella target builds the MCP image, tags it, pushes it, creates the git tag,
#    then builds and pushes each TEI image in sequence.
make docker-publish-all

# 3. Logout from GHCR immediately after publishing
#    (removes the ghcr.io credential from ~/.docker/config.json)
docker logout ghcr.io

后续发布时，重复步骤 1–3。如果 PAT 已过期，请通过上方链接生成新的 PAT。

首次推送——将软件包设为公开（仅限 GHCR）

GHCR 软件包默认为私有。首次运行 make docker-publish-all 后，将所有三个软件包设为公开：

软件包	设置 URL
MCP 服务	https://github.com/users/olk/packages/container/agent-pattern-mcp/settings
TEI 嵌入器	https://github.com/users/olk/packages/container/pattern-tei-embed/settings
TEI 重排器	https://github.com/users/olk/packages/container/pattern-tei-rerank/settings

将每个软件包设为公开并保存。

部分失败后的恢复

如果推送中途失败（例如，未配置 GHCR 身份验证），Docker Hub 层已经上传。修复身份验证后，重新运行 make docker-publish-all 是安全的——每个注册表都会对已上传的层报告缓存命中，并完成剩余推送。若要定向重试，可使用 make docker-publish-tei 或 make docker-publish-tei-rerank 推送单个镜像。

---

systemd 服务（Linux）

服务器可作为 systemd 服务运行在任何基于 systemd 的 Linux 主机上。它会在启动时自动启动 Docker Compose 堆栈。

文件布局

systemd/ 目录包含三个文件：

文件	用途
systemd/agent-pattern-mcp.service	systemd 单元
systemd/docker-compose.yml	生产环境 Compose 变体（无 build:，使用绝对路径）
systemd/README.md	包含安装、验证和故障排查的完整操作手册

生产环境 Compose 文件是 docker/docker-compose.yml 的部署变体：它没有 build: 部分（镜像必须预先构建），使用绝对路径，并存放在主机的 /etc/agent-pattern-mcp/ 下。由 systemd 管理的项目使用独立名称 agpmcp-systemd，与开发环境 Compose 以及同级的 architecture-pattern-mcp systemd 堆栈（apmcp-systemd）均不相同，因此任一堆栈的 up -d --remove-orphans 都不会将另一堆栈的容器视为孤立容器。

此堆栈未定义 TEI 侧车容器——pattern-tei-embed 嵌入器和 pattern-tei-rerank 重排器容器位于共享的 pattern-tei-infra 堆栈中。此堆栈拥有 pattern-tei-shared Docker 网络，并通过 http://pattern-tei-embed:8080/v1（嵌入器）和 http://pattern-tei-rerank:8080（重排器）提供侧车容器服务。systemd MCP 堆栈会加入该网络，并通过这些 DNS 名称连接它们。

前置条件——一次性设置 TEI 基础设施：

# 克隆基础设施堆栈（如果主机上尚未克隆）
git clone https://github.com/olk/pattern-tei-infra.git ~/pattern-tei-infra

# 安装并启用 pattern-tei-infra systemd 单元
sudo install -m 644 ~/pattern-tei-infra/pattern-tei-infra.service \
                /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service
# 等待约 2 分钟，让 TEI 侧车容器变为健康状态

仅当 pattern-tei-infra.service 状态为 active (running) 后，才启动 agent-pattern-mcp.service。完整详情请参阅 pattern-tei-infra/README.md。

前提条件

• 基于 systemd 的 Linux 主机，并已安装 Docker（docker compose version）。
• <user> 属于 docker 组。
• 两个镜像均已在本地预先构建（在仓库中运行 make docker-build-all）。
• 已安装并启用共享 TEI 基础设施堆栈（参见 tei-infra README）。

安装

# 0. Install + enable shared TEI infra (once)
sudo install -m 644 {HOME}/pattern-tei-infra/pattern-tei-infra.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pattern-tei-infra.service

# 1. Build images (once)
make docker-build-all

# 2. Deploy /etc/agent-pattern-mcp/
sudo install -d /etc/agent-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/agent-pattern-mcp/
sudo install -m 644 ~/.config/agent-pattern-mcp/config.json /etc/agent-pattern-mcp/config/

# 3. Create the .env file (root:docker 640) and edit it.
#     640 root:docker — not 600 root:root — so the systemd service
#     running as User=graemer (a member of the `docker` group) can read this
#     file when docker compose auto-loads it.  The `docker` group is
#     effectively privileged; this is the standard trade-off for non-root
#     systemd services that manage Docker containers.
sudo install -o root -g docker -m 640 /dev/null /etc/agent-pattern-mcp/.env
sudo $EDITOR /etc/agent-pattern-mcp/.env
# Contents:
#   MINIMAXAI_API_KEY=sk-...
#   COMPOSE_PROJECT_NAME=agpmcp-systemd

# 4. Install and enable the service.
sudo install -m 644 systemd/agent-pattern-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agent-pattern-mcp.service

**预构建镜像快捷方式：**如需从 Docker Hub 安装，无需构建 （拉取并重新标记、JSON-RPC 探测、日常运维），请参阅 INSTALL.md 中的路径 B。

验证

systemctl status 会在几秒内显示 active (exited)，但容器需要最多约 40 秒才能变为健康状态（MCP 的 start_period: 40s；TEI 就绪状态由 pattern-tei-infra 管理，其 start_period: 120s）。 该单元不会等待健康检查。

systemctl status agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 50
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml ps
docker inspect -f '{{.State.Health.Status}}' agent-pattern-mcp  # "healthy"
# Probe the MCP endpoint — must print 200 (GET /health is 404 by design).
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8811/mcp" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.0"}},"id":1}'

日常使用

sudo systemctl start|stop|restart|reload agent-pattern-mcp
journalctl -u agent-pattern-mcp -n 200 -f
docker compose -p agpmcp-systemd -f /etc/agent-pattern-mcp/docker-compose.yml logs -f

更新技术栈

make docker-build-all                     # rebuild both images
sudo systemctl reload agent-pattern-mcp   # recreate containers

卸载

sudo systemctl disable --now agent-pattern-mcp.service
sudo rm /etc/systemd/system/agent-pattern-mcp.service
sudo systemctl daemon-reload
sudo rm -rf /etc/agent-pattern-mcp

如需查看完整的故障排查、网络详情和共存指南，请参阅 systemd/README.md。

---

验证计划

该仓库包含分层验证计划（请参阅 docs/verification.md 和 docs/testing-strategies.md）：

层级	验证内容	入口点
L1	单元测试套件（行为判定基准）+ 秘密信息金丝雀	make test-unit
L1b	MCP 工具表面边界模糊测试	make test-oracles
L2	针对决策模块的 Hypothesis 属性判定基准	make test-oracles
L3	变异测试（mutmut 递进门槛）+ 人为植入错误的测试集	make test-mutations（每晚）
L4	FizzBee 穷举模型检查 + FG 规范测试集	make verify-fizz、make verify-fizz-garden
L6	针对作业存储的确定性模拟竞态测试	make test-oracles
L8	属性 ID 台账 + NL-Doc 交叉一致性	make verify-ledger、make verify-cross-consistency
L9	LLM 输出的结构不变量（可选实时流水线）	uv run pytest tests/eval/ -m llm（AGENT_BENCH_LLM=1）
L10	性能冒烟金丝雀（RUN_PERF=1）	每晚工作流

快速检查：make check-all（lint + 类型检查 + 死代码检查 + 依赖项检查）和 make test-all（单元测试 + 判定基准）。每晚金丝雀任务位于 .github/workflows/verification.yml。

---

许可证

MIT 许可证。请参阅 LICENSE。