Architecture Pattern MCP

architecture-pattern-mcp

一个 MCP（Model Context Protocol）服务，为 AI 编码 Agent 提供架构设计专业知识。给定需求字符串和领域后，它会分析问题，从 128 个内置模式中选出匹配的架构模式，生成包含组件、关系、API 契约、数据模型和事件契约的具体架构设计，并根据质量属性（可维护性、可扩展性、可靠性、安全性、性能）进行评估。

---

目录

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

---

⚡ 快速开始

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

# 2. Add your API key
export GENERATOR_API_KEY=your_key_here

# 3. Start (Docker builds + starts everything)
docker compose -f docker/docker-compose.yml up --build

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

服务会通过 streamable-http 在 http://localhost:8820/mcp 启动（开发 compose 主机端口；systemd 使用 8810）。然后连接下方的 Agent。

---

通过 AI Agent 安装

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

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

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

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

Agent 需要克隆的仓库、Docker ≥ v2.20 并加入 Docker 用户组、约 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 architecture-pattern \
  -e GENERATOR_API_KEY=your_key \
  -e GENERATOR_PROVIDER=openai \
  -- architecture-pattern-mcp --transport stdio

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

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

OpenCode

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

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

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

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

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

Codex CLI

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

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

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

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

也可以通过 CLI 添加：

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

---

🧑‍🏫 面向 AI Agent 的 SKILL

skills/architecture-pattern-mcp/ 中的 SKILL 专为 Oh My Pi (OMP) 编写。在 OMP 中，访问此服务工具的方式是 xd://mcp__architecture_pattern_* 设备，并且每个 MCP 请求都有截止时间（OMP_MCP_TIMEOUT_MS → 每服务的 timeout → 30 s）。它会教 Agent 在该截止时间内选择合适的入口、如何读取结果，以及完整的工作流配方。

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

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

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

随后，SKILL 会告诉 Agent：

• 哪个入口适合 OMP 的截止时间：默认使用异步任务三件套；只有提高服务的 timeout 后才使用一次性调用 design_architecture（单独测得 analyze_architecture 耗时 66 s，evaluate_architecture 耗时 197 s）
• 如何将 requirements、domain 和 style 作为独立的结构化参数来表述
• 如何解读 final_quality_score、attempts > 1 和 evaluation.recommendations
• 当同级的 agent-pattern 服务已连接时，read mcp://pattern://… 存在歧义，因此工具路由（get_architecture_pattern）才是权威入口

references/ 中的工具 schema、错误码和设计字典结构与客户端无关；只有截止时间和设备相关指导是 OMP 专属的。

---

使用工具

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

试用各个工具

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

Build a scalable ETL pipeline for IoT sensor data: ingest 10k events/sec
from Kafka, parse JSON, enrich with geolocation from Redis, write to InfluxDB
and S3.

你的 Agent 会在内部调用 design_architecture。服务会返回完整的架构设计：组件（Kafka 源、JSON 解析器过滤器、地理位置增强器、InfluxDB 接收器、S3 接收器）、质量属性评分（可扩展性：9.1、可维护性：8.2，……）以及具体建议。

这是设计路径：服务的大模型会为你生成设计产物，因此一次调用需要数分钟。如果你的 Agent 自行编写代码，只需要模式方面的专业知识，则改为调用 analyze_architecture——它会返回推荐风格、选定的模式及其评分、需求权重、质量指标和匹配的领域，而不会生成设计。已提交的基准测试数据集中有两项实测结果：生成与评估约占设计调用墙钟时间的 92 %（benchmarks/base-noreasoning/）；两条路径在全部 31 条已完成记录中对风格的判断一致（15 条 base + 16 条 no-reasoning；剩余的一条 base 记录因格式错误的 JSON 验证错误导致设计调用失败，没有生成设计）——调用设计路径得到的是设计产物，而不是更好的模式选择。

也可以直接从你的 Agent 调用工具：

Call analyze_architecture with:
  requirements: "Real-time data processing pipeline for 10k events/sec IoT sensor data"
  domain: "data-processing"

Call generate_architecture with:
  requirements: "ETL pipeline: Kafka → JSON parse → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"
  selected_patterns: ["pipe-and-filter"]

Call evaluate_architecture with:
  architecture: { ... paste a design dict here ... }
  criteria: "scalability, reliability"

Call list_architecture_patterns()  # all 128 patterns
Call list_architecture_patterns(category="messaging")  # filter by category
Call get_architecture_pattern(name="event-driven")   # full pattern JSON

异步任务模式：submit_architecture_design_job + get_architecture_design_status

仅适用于请求超时较短的客户端（Cursor、Claude Desktop、TS-SDK）。默认使用带心跳防护的 design_architecture。submit_architecture_design_job 会立即返回 job_id；轮询 get_architecture_design_status，直到任务完成：

# Step 1: start the job
Call submit_architecture_design_job with:
  requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"

# Step 2: poll every 10-30 seconds
Call get_architecture_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/architecture_client_async.py）：

import asyncio, aiohttp

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

async def main():
    async with aiohttp.ClientSession() as sess:
        # Start
        async with sess.post(SERVER, json={
            "jsonrpc": "2.0",
            "method": "tools/call",
            "params": {
                "name": "submit_architecture_design_job",
                "arguments": {
                    "requirements": "ETL pipeline for IoT: Kafka → JSON → Redis → InfluxDB + S3",
                    "domain": "data-processing",
                }
            },
            "id": 1
        }) as resp:
            job_id = (await resp.json())["result"]["content"][0]["data"]["job_id"]

        print(f"Job started: {job_id}")

        # Poll
        while True:
            await asyncio.sleep(POLL_EVERY)
            async with sess.post(SERVER, json={
                "jsonrpc": "2.0",
                "method": "tools/call",
                "params": {"name": "get_architecture_design_status", "arguments": {"job_id": job_id}},
                "id": 2
            }) as resp:
                result = (await resp.json())["result"]["content"][0]["data"]
                print(f"  status={result['status']}")
                if result["status"] in ("completed", "failed", "cancelled"):
                    break

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

完整的可运行示例请参见 examples/architecture_client_async.py。运行方式：

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

浏览模式目录

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

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

Show me details about the event-driven architecture pattern.

---

🛠️ 工具一览

工具	描述
analyze_architecture	面向自行编写代码的 Agent 的仅分析路径：需求 + 领域 → 推荐风格、选定模式、质量指标、匹配的领域。不生成设计。一次轻量级大模型调用。非幂等。
generate_architecture	根据需求和选定的模式生成架构设计。运行时间较长（大模型调用）。非幂等。
evaluate_architecture	根据质量属性为现有设计评分。运行时间较长（大模型调用）。非幂等。
design_architecture	面向需要生成设计的调用方的设计产物路径：分析 → 生成 → 评估 → 优化，最多尝试 3 次，返回组件、关系、API 契约和数据模型。运行时间较长（5–10 分钟）；除非客户端的请求超时时间较短，否则请使用此工具。
submit_architecture_design_job	启动后台设计任务并立即返回 job_id。仅供请求超时时间较短的客户端使用（Cursor、Claude Desktop、TS-SDK）。其他客户端请使用 design_architecture。每隔 10–30 秒轮询一次 get_architecture_design_status。
get_architecture_design_status	轮询任务状态。返回当前状态、进度消息，以及任务 completed 时的完整设计输出。
cancel_architecture_design	取消正在运行的任务（尽力而为；在下一个流水线阶段边界生效；最多可能需要一次大模型调用）。
list_architecture_patterns	列出全部 128 种模式；可按 category 和／或 domain 筛选
get_architecture_pattern	按名称获取特定模式的完整 JSON

Domain 和 Style 是结构化参数——请将它们作为独立的工具参数传入，而不是嵌入需求文本中。

提示词示例：

Build a scalable distributed system for processing IoT sensor data with
100k events per second throughput, written in Python, deployed on Kubernetes.

Design an architecture for an e-commerce platform handling flash-sales events.
Domain: e-commerce. Style: microservices.

Show me details about the blackboard pattern.

Call design_architecture with:
  requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
  domain: "data-processing"

---

💬 提示词

此服务还提供 4 个由用户调用的工作流提示词（在 MCP 客户端中以斜杠命令的形式呈现）。与工具不同，大模型不会自主调用提示词——用户会选择一个并填写其参数。每个提示词都包含经过测试的工具编排方案。

提示词	参数	功能
/design_architecture_workflow	requirements*	完整的分析 → 生成 → 评估流水线
/explore_pattern_catalog	domain、category	实时探索目录，并嵌入模式名称
/evaluate_my_architecture	focus	指导评估标准并确定发现的优先级
/compare_architecture_styles	style_a*、style_b*、requirements*	并排比较两种设计；令牌成本约为 2 倍

* = 必填参数

仅支持工具的客户端

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

---

📖 模式目录

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

list_architecture_patterns()                                  # all 128 patterns
list_architecture_patterns(category="messaging")               # filter by category
list_architecture_patterns(domain="microservices")            # filter by domain
get_architecture_pattern(name="event-driven")                 # full pattern JSON

有效的 category 值：messaging、structural、cloud、data、ai_cognitive、specialized、api_gateway、coordination、dataflow、presentation。

通过 MCP 资源

mcp_list_resources(server="architecture-pattern")
mcp_read_resource(server="architecture-pattern", uri="pattern://microservices")

模式 JSON 结构

每种模式都包含：name、category、context、benefits、tradeoffs、quality_attributes（可扩展性／可维护性／可靠性／安全性／性能／简洁性，评分为 1–10）、suitable_domains、component_types、technology_stack、design_principles、best_practices。

---

与 design-pattern-mcp-local 协同工作

此服务回答 要构建哪种系统形态（架构）；同系列的 design-pattern-mcp-local 回答 如何编写其中的各个单元（设计模式）。架构模式用于构建整个系统的结构——其组件、组件间的关系，以及 API/数据/事件契约（例如 event-driven、pipe-and-filter、microservices，从上方的 128 种模式目录中选择）。设计模式解决单个组件内部反复出现的实现问题——其参与者、交互方式，以及与语言绑定的代码（例如 observer、process-manager、circuit-breaker，从同系列的 438 种模式目录中选择，每种模式各有 13 种语言绑定）。

建议顺序——先宏观，再微观：

1. Call design_architecture with:
     requirements: "ETL pipeline for IoT: Kafka → JSON → Redis geo-enrich → InfluxDB + S3"
     domain: "data-processing"
   # → components (Kafka source, parser filter, enricher, sinks),
   #   relationships, API contracts, data models, event contracts

2. For each component with non-trivial internal logic, call the sibling's
   select_design_patterns with:
     description: "<component name + responsibilities + constraints from step 1>"
     language: "python"
   # → primary + supporting patterns, participants, implementation_steps,
   #   code_sketch with the bound language variant

以 IoT 示例为例，具体交接方式如下：此服务会生成 pipe-and-filter 架构（Kafka 源 → JSON 解析器过滤器 → 地理位置增强器 → InfluxDB/S3 接收器，并在契约中规定至少一次投递和背压）。随后，地理位置增强器的缓存未命中路径会调用 select_design_patterns（“使用 Redis 回退进行缓存旁路增强，Python”）——例如，采用 circuit-breaker + retry 设计，并包含参与者、implementation_steps 和 Python code_sketch——架构层级的组件契约会引用这些内容，但不会实现它们。

同时运行两个服务（开发主机端口为架构 :8820、设计模式 :8062；systemd 端口为 :8810 / :8062）。两者相互独立——探索时可按任意顺序使用——但先设计架构可保持组件边界稳定，同时由设计服务补充内部实现。

安装替代方案

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/architecture-pattern-mcp/config.json
# Edit ~/.config/architecture-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 后）：

architecture-pattern-mcp --transport stdio

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

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

TEI 启动： 两个旁路服务镜像（docker/Dockerfile.tei-embed、docker/Dockerfile.tei-rerank）都附带自行构建的 TEI 路由器（v1.9.4 + 未合并的 PR #884），默认设置为 WARMUP_TOKENS=0——这会跳过合成预热过程（实测嵌入约 131 秒／重排约 78 秒），让容器仅在加载权重后就绪。可通过 TEI_WARMUP_TOKENS／TEI_RERANK_WARMUP_TOKENS 分别覆盖各旁路服务的设置（正数 N 会改为使用 N 个 token 预热；大于 MAX_BATCH_TOKENS 的值会在启动时被拒绝）。

GPU TEI： 随附的旁路服务镜像是 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 服务指向它们并跳过旁路服务（docker/docker-compose.hub.yml 只启动 MCP 服务，并按此方式进行配置）。远程嵌入器必须是提供相同模型的 TEI——保留 EMBEDDER_PROVIDER=tei，并将 EMBEDDER_BASE_URL 设为其 OpenAI 兼容路由（开发环境 compose 约定使用 http://<host>:8080/v1；config.json 的默认值是裸地址 http://pattern-tei-embed:8080）。此服务的嵌入器配置没有 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/architecture-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://127.0.0.1:8080"
    }
  },
  "retrieval": {
    "bm25_top_k": 0,
    "dense_top_k": 0,
    "top_k_patterns": 5,
    "min_quality_score": 50.0
  },
  "pattern_directory": "~/.config/architecture-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	(必填)	LLM 提供商的 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://127.0.0.1:8080	TEI 嵌入器 URL
EMBEDDER_BATCH_SIZE	16	嵌入批次大小
EMBEDDER_QUERY_INSTRUCTION	(空)	查询指令前缀
EMBEDDER_TEXT_INSTRUCTION	(空)	文本指令前缀
EMBEDDING_CACHE	image：/var/cache/architecture-pattern-mcp/embedding-index · host：~/.config/architecture-pattern-mcp/embedding-index	稠密检索快照路径：重启时重新加载（无需重新嵌入语料）；嵌入器、语料或探测器发生任何变化时都会重建。设为 0/false/off/no 可禁用。请参阅 嵌入索引缓存
RETRIEVAL_BM25_TOP_K	0	BM25 第 1 阶段召回上限（0=完整语料）
RETRIEVAL_DENSE_TOP_K	0	稠密检索第 1 阶段召回上限（0=完整语料）
RETRIEVAL_DENSE_WEIGHT	0.7	第 1 阶段融合分支权重，应用于稠密检索分支。与 RETRIEVAL_BM25_WEIGHT 配对使用；两者都必须大于 0，且总和为 1.0（±1e-3，启动时验证）。任一权重小于 0.05 时会记录启动警告。此权重不同于第 2 阶段选择融合权重（RETRIEVAL_ANALYSIS_BLEND_WEIGHT / RETRIEVAL_FUSION_BLEND_WEIGHT）。注意：旧版镜像不认识的配置键会导致启动快速失败。
RETRIEVAL_BM25_WEIGHT	0.3	第 1 阶段融合分支权重，应用于 BM25 分支。请参阅 RETRIEVAL_DENSE_WEIGHT。
RETRIEVAL_TOP_K_PATTERNS	5	要选择的模式数量
RETRIEVAL_MIN_FUSION_SCORE	0.0	rank_fusion 融合值的相关性下限（范围为 [0, 2/60] ≈ [0, 0.033]）。默认值为 0.0（禁用门控）。高于融合值上限的值会在启动时被拒绝。
RETRIEVAL_RERANK_TOP_N	10	重排前 N 个结果（CE 后按 slug 截断）
RETRIEVAL_USE_LEAN_WIRE_SCHEMA	false	使用精简响应架构
RETRIEVAL_STYLE_SCORE_THRESHOLD	50.0	风格推荐的最低分析分数
REASONING_ENABLED	false	服务端推理 MCP 集成——选择启用，默认关闭（请参阅结构化推理）
REASONING_SPAWN_TIMEOUT_SECONDS	10	每个推理工具的子进程启动超时时间
REASONING_STEP_TIMEOUT_SECONDS	20	每次思考的工具调用超时时间
REASONING_MAX_TOTAL_STEPS	8	每个阶段的推理步骤数硬上限
REASONING_QUIET_STDERR	true	静默推理子进程的标准错误输出（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	3	设计循环最大尝试次数
RETRIEVAL_MIN_QUALITY_SCORE	50.0	提前停止的质量阈值
RERANKER_BASE_URL	(默认重排器 URL)	TEI 重排器端点（host:port）；模型固定为 gte-reranker-modernbert-base
RERANKER_TIMEOUT	30.0	重排器超时时间（秒）
RERANKER_MAX_BATCH_SIZE	48	每次 TEI /rerank 请求的最大文本数；必须 ≤ 重排器 sidecar 的 min(MAX_CLIENT_BATCH_SIZE, MAX_CONCURRENT_REQUESTS)。HybridPatternRetriever 会自动对大型候选池分块。
PATTERN_DIRECTORY	~/.config/architecture-pattern-mcp/pattern	模式文件目录
VALIDATION_MAX_RETRIES	2	自愈重试的最大次数
VALIDATION_RETRY_ON_FAIL	true	验证失败时重试
ARCHITECTURE_PATTERN_JOBS_DB	~/.config/architecture-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 绑定端口
LOGGING_LEVEL	INFO	日志级别
LOGGING_FORMAT	json	日志格式：json、text
CONFIG_PATH	~/.config/architecture-pattern-mcp/config.json	配置文件路径

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

稠密检索部分是一个涵盖所有目录域 slug（约 254 个）的 FAISS 索引。冷启动构建后，嵌入向量会快照到磁盘，并在下次启动时重新加载，因此热启动只需 一次探测嵌入，而不必遍历整个语料库（在开发 compose 栈上测得：16.5 s → 0.3 s）。BM25 开销很低，每次启动都会重新构建。

• 路径：EMBEDDING_CACHE。镜像预置在 /var/cache/architecture-pattern-mcp/embedding-index；在主机上运行（uv）时使用 ~/.config/architecture-pattern-mcp/embedding-index。
• 文件所在位置：日志中显示的路径是容器内视图。Docker 会将命名卷存储在 /var/lib/docker/volumes/<volume-name>/_data （由 root 所有），因此主机上的 /var/cache 按设计会保持为空。无需 sudo 即可检查： docker exec <container> ls /var/cache/architecture-pattern-mcp/embedding-index；或者运行 docker volume inspect -f '{{.Mountpoint}}' <volume-name> 查看主机侧路径。
• 容器使用命名卷持久化缓存 （architecture-pattern-mcp-dev-embedding-index / architecture-pattern-mcp-systemd-embedding-index），因此镜像重建、容器重新创建和执行 docker compose down 后，快照仍会保留。使用 docker compose down -v 或 docker volume rm <name> 重置；直接运行 docker run 时需要 -v apmcp-embedding-index:/var/cache/architecture-pattern-mcp/embedding-index。
• 以下情况会自动重建：嵌入函数发生变化（提供方、 base_url、解析出的模型名称、查询/文本指令前缀），slug 语料库发生变化，或探测向量显示配置未变但后端模型已不同 （例如重新部署了 TEI 侧车）。日志行如下： 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。

---

结构化推理（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 跟踪记录，并在设计循环的各次尝试中复用。

启用 / 调优

推理功能默认禁用：在 Stage-0 基准测试中，它占端到端设计延迟的约 55%（每次运行中位数为 286 s / 517 s；若没有跟踪记录，生成器还会额外耗时约 77 s），但没有带来选择质量提升——在 16 个场景中，命中率和可接受的首选 F1 均相同。通过 REASONING_ENABLED=true 启用。

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

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

延迟说明：一次设计运行会发起 14 次推理工具调用（analyze 8 次、generate 3 次、evaluate 3 次），每次均作为串行子进程运行。在 Stage-0 基准测试中测得（MiniMax-M2.7 生成器）：每次调用耗时 14–30 s，每次运行的推理中位耗时为 286 s — 是几分钟，而不是几秒。跟踪记录缓存会消除设计循环各次尝试之间重复的 ANALYZE/GENERATE 工作，但首次运行仍需执行。

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

CLI 标志

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

---

使用自定义模式扩展

模式文件从 ~/.config/architecture-pattern-mcp/pattern/ 加载（可通过 PATTERN_DIRECTORY 配置）。将 JSON 文件放在 128 个内置模式所在目录中即可。

最简模式结构：

{
  "category": "structural",
  "name": "my-custom-pattern",
  "context": "Describe when this pattern applies.",
  "benefits": ["Benefit 1", "Benefit 2"],
  "tradeoffs": ["Tradeoff 1"],
  "quality_attributes": {
    "scalability": 7,
    "maintainability": 8,
    "reliability": 7,
    "security": 6,
    "performance": 7,
    "simplicity": 5
  }
}

必填字段：category、name、context、benefits、tradeoffs、quality_attributes。

有效的 category 值：messaging、structural、cloud、data、ai_cognitive、specialized、api_gateway、coordination、dataflow、presentation。

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

---

长时间运行的工具与超时

design_architecture 及其作业三件套对应工具会运行多阶段 LLM 流程，每次调用可能需要 5–10 分钟。单阶段工具耗时要短得多：analyze_architecture 只需一次轻量级 LLM 调用（在已提交的基准测试语料上平均约 20 s，在负载较高的主机上测得 66 s），而 generate_architecture / evaluate_architecture 各需一次大型生成（约 2–3 分钟）。设计调用耗时较长是工作负载本身所致，并非错误：生成器 LLM 必须处理大型输入负载——从 128 种模式目录中选出的模式定义、你的需求，以及前面每个阶段的完整输出——并逐个 token 生成大型且结构严格的 JSON 文档（包括组件、关系、API 契约、数据模型、事件契约、质量评分）。design_architecture 流程最多会重复执行三次 generate → evaluate，因此单次调用可能包含 9 次以上 LLM 往返。

超时问题

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

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

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

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

这些客户端无法重新配置以接受更长的超时时间——超时设置已固化在 SDK 中。

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

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

这些客户端之所以可用，是因为它们的空闲计时器会在收到任何数据时重置——客户端收到服务端并行异步任务发送的心跳 progress 通知后，计时器就会重置。

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

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

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

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

如需完全控制并兼容受超时限制的客户端，可使用三个工具来获取持久化作业句柄：

submit_architecture_design_job(requirements, domain, override_style)  → job_id
get_architecture_design_status(job_id)                                  → {status, result, error}
cancel_architecture_design(job_id)                                      → {cancelled, status}

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

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

作业存储为 SQLite 数据库，位于 ~/.config/architecture-pattern-mcp/jobs.db（可通过 ARCHITECTURE_PATTERN_JOBS_DB 配置）。

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

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

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

# In another terminal: fast analyze demo / full design demo (5-10 min)
make client-analyze        # analyze_architecture only
make client-design         # design_architecture, the long synchronous call

两个目标都使用同一个直接客户端（--tool analyze|design）。make client-design 演示了服务能够正确完成长时间运行的请求——超时问题纯粹是客户端的问题。封装了 MCP 的宿主应用（Claude Desktop、Cursor，等等）会施加自己的超时；在这些应用中，请使用异步作业三件套。

故障排除

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

1. 检查 Agent 的 MCP 连接：Claude Code 使用 /mcp，OpenCode 使用 opencode mcp list，Codex 使用 codex mcp list
2. 验证服务进程是否已启动：compose 日志中应显示 MCPArchitectServer initialized
3. 确认 TEI 嵌入器运行正常：在容器内运行 curl http://127.0.0.1:8080/health

“连接被拒绝”或超时错误

服务会等待 TEI 嵌入器进入健康状态：

docker compose -f docker/docker-compose.yml logs pattern-tei

LLM 提供商错误（502 / 401）

• 确认已设置 GENERATOR_API_KEY 且尚未过期
• 确认 GENERATOR_BASE_URL 与你的提供商端点匹配
• 如果使用代理，请检查从容器内部能否访问

未加载模式 JSON 文件

• 文件必须使用 .json 扩展名
• 必填字段：category、name、context、benefits、tradeoffs、quality_attributes
• 根据 docs/pattern-schema.json 验证文件

---

构建与开发

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

目标	描述
make install	以可编辑模式安装软件包及开发依赖
make check-lint	运行 ruff lint 检查
make check-static-typing	对 src/ 运行 mypy --strict 类型检查
make check-all	运行所有 check-* 质量关卡（lint、类型、死代码、依赖项）
make test-unit	使用 uv 运行单元测试（tests/unit/）
make client-analyze	运行仅用于分析的 MCP 客户端演示（需要服务正在运行）
make client-design	运行同步的 design_architecture 客户端演示（长时间运行；需要服务正在运行）
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/architecture-pattern-mcp	ghcr.io/olk/architecture-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 权限范围的 classic 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 已过期，请通过上方链接生成一个新的。

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

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

软件包	设置 URL
MCP 服务	https://github.com/users/olk/packages/container/architecture-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 的 Linux 主机上作为 systemd 服务运行。它会在启动时自动启动 Docker Compose 堆栈。

文件布局

systemd/ 目录包含三个文件：

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

生产环境 Compose 文件是 docker/docker-compose.yml 的部署变体：它不包含 build: 部分（镜像必须预先构建），使用绝对路径，并位于主机上的 /etc/architecture-pattern-mcp/ 下。systemd 管理的项目使用独立名称 apmcp-systemd，因此必要时可以与开发环境 Compose 共存。

此堆栈中未定义 TEI sidecar — pattern-tei-embed 嵌入器和 pattern-tei-rerank 重排器容器位于共享的 pattern-tei-infra 堆栈中。此 堆栈负责管理 pattern-tei-shared Docker 网络，并通过以下地址公开 sidecar： 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 sidecar 健康就绪

仅当 pattern-tei-infra.service 状态为 active (running) 后，才启动 architecture-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/architecture-pattern-mcp/
sudo install -d /etc/architecture-pattern-mcp/config
sudo install -m 644 systemd/docker-compose.yml /etc/architecture-pattern-mcp/
sudo install -m 644 ~/.config/architecture-pattern-mcp/config.json /etc/architecture-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/architecture-pattern-mcp/.env
sudo $EDITOR /etc/architecture-pattern-mcp/.env
# Contents:
#   MINIMAXAI_API_KEY=sk-...
#   COMPOSE_PROJECT_NAME=apmcp-systemd

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

验证

systemctl status 会在几秒内显示 active (exited)，但容器需要最多约 2 分钟才能达到健康状态（TEI 嵌入器的 start_period: 120s）。该单元不会等待健康检查完成。

systemctl status architecture-pattern-mcp
journalctl -u architecture-pattern-mcp -n 50
docker compose -p apmcp-systemd -f /etc/architecture-pattern-mcp/docker-compose.yml ps
# GET /health is 404 by design; the JSON-RPC initialize POST is the probe.
curl -s -o /dev/null -w '%{http_code}\n' -X POST "http://localhost:8810/mcp" \

日常使用

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

更新堆栈

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

卸载

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

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

---

许可证

MIT 许可证。请参阅 LICENSE。