# https://github.com/tosin2013/mcp-adr-analysis-server 项目说明书 生成时间：2026-07-13 10:40:24 UTC ## 目录 - [Project Overview and Concepts](#page-1) - [System Architecture and Server Design](#page-2) - [MCP Tools Catalog and Resources](#page-3) - [ADR Management, Knowledge Graph, and Smart Code Linking](#page-4) - [Data Flow, Memory, and State Management](#page-5) - [AI/LLM Integration and Prompt Engineering](#page-6) - [Deployment, Infrastructure, and Extensibility](#page-7) - [Operations, Testing, Troubleshooting, and Release](#page-8) ## Project Overview and Concepts ### 相关页面 相关主题：[System Architecture and Server Design](#page-2), [MCP Tools Catalog and Resources](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/README.md) - [package.json](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/package.json) - [docs/index.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/index.md) - [docs/explanation/mcp-concepts.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/explanation/mcp-concepts.md) - [docs/explanation/architecture.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/explanation/architecture.md) - [docs/getting-started/installation.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/getting-started/installation.md) - [docs/QUICK_START.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/QUICK_START.md) - [src/index.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/index.ts)
# 项目概览与核心概念 `mcp-adr-analysis-server` 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器，专为分析与管理架构决策记录（Architecture Decision Records, ADR）而设计。它通过标准化的 MCP 接口向 AI 助手（如 Claude、Copilot CLI 等）暴露一系列工具，使 LLM 能够在工程工作流中读取、检索、生成与验证 ADR 内容，从而支持架构决策的自动化与一致性维护。 资料来源：[README.md:1-40]() ## 项目定位与核心目标 本项目在 npm 上的包名为 `mcp-adr-analysis-server`，版本目前迭代至 v2.6.8（截至最新发布）。其核心定位是一个"为 AI 协作而生的 ADR 知识服务器"： - **面向 AI 助手**：作为 MCP 服务器运行，让 LLM 客户端通过 `ListToolsRequestSchema`、`CallToolRequestSchema` 等标准协议调用工具（资料来源：[docs/explanation/mcp-concepts.md:1-30]()）。 - **聚焦 ADR 工作流**：内置检索、生成、模板填充、todo 跟踪等能力，覆盖 ADR 生命周期的关键阶段。 - **离线优先**：在 `EXECUTION_MODE=full` 之外提供轻量级离线模式，例如 v2.6.0 新增的 `generate_adr_todo` 工具即支持离线里程碑跟踪（资料来源：[Release v2.6.0]()）。 | 维度 | 描述 | | --- | --- | | 协议 | Model Context Protocol (MCP) | | 运行时 | Node.js（依赖在 `package.json` 中声明） | | 部署形态 | stdio MCP 服务器 | | 主要功能域 | ADR 检索、生成、模板管理、任务跟踪、安全分析 | ## 关键概念 ### 架构决策记录（ADR） ADR 是用于记录重要架构决策的短文档，结构通常包括上下文、决策、状态与后果。本服务器将 ADR 视为一等公民对象，对其进行解析、索引与查询（资料来源：[docs/index.md:1-25]()）。 ### MCP 工具（Tools）与资源（Resources） 服务器向客户端注册多个工具（社区审计显示注册工具数量为 72 个，见 [Issue #612]()），每个工具以独立文件实现，统一在 `ListToolsRequestSchema` 中注册。工具类别包括： - **检索类**：如 `search_adr`、搜索工具 `search_tools`（资料来源：[Issue #612]()）。 - **生成类**：如 `generate_adr_todo`（v2.6.0 引入，PR #849）（资料来源：[Release v2.6.0]()）。 - **分析与验证类**：用于对 ADR 内容进行规则校验与一致性检查。 ### 执行模式 通过环境变量 `EXECUTION_MODE` 控制行为，常见值包含 `full`（完整在线模式）和轻量/离线模式。社区曾反映文档中环境变量说明缺失（资料来源：[Issue #546]()），后续版本逐步完善。 ## 架构与运行流程 服务器以 stdio 方式与 MCP 客户端通信，整体流程为：客户端连接 → 工具列表握手 → 工具调用 → 返回结构化结果。 ```mermaid flowchart LR A[MCP 客户端
Claude/Copilot] -- stdio --> B[mcp-adr-analysis-server] B -- 读取 --> C[ADR 仓库
文件系统] B -- 调用 --> D[工具集
72 个注册工具] D -- 输出 --> A ``` 资料来源：[src/index.ts:1-50]()、[docs/explanation/architecture.md:1-40]() ## 版本演进与社区关注点 项目遵循自动化发布流水线，v2.5.x 至 v2.6.x 期间主要变更集中在 CI 稳定性与发布门控（资料来源：[Release v2.5.4]()、[Release v2.6.2]()）。社区当前重点关注： - **AI 执行器集成失败**：Copilot CLI 因 token 缺少 inference 访问权限导致工作流失败（资料来源：[Issue #1235]()、[Issue #1187]()）。 - **工具注册一致性**：审计发现个别工具文件未在主注册表中注册（资料来源：[Issue #612]()）。 - **文档质量**：如 `docs/QUICK_START.md` 与现有文档系统不一致，可能误导新用户（资料来源：[Issue #694]()）。 - **依赖安全**：定期修复 npm 依赖漏洞并更新安全文档（资料来源：[Release v2.5.1]()）。 ## 总结 `mcp-adr-analysis-server` 通过 MCP 协议将 ADR 管理能力暴露给 AI 助手，核心价值在于把工程决策知识结构化、可查询、可生成。开发者在使用前应关注环境变量配置（`OPENROUTER_API_KEY`、`EXECUTION_MODE`）与对应 MCP 客户端的兼容性，并参考最新发布说明与社区已知问题进行部署。资料来源：[README.md:1-60]() --- ## System Architecture and Server Design ### 相关页面 相关主题：[Project Overview and Concepts](#page-1), [MCP Tools Catalog and Resources](#page-3), [AI/LLM Integration and Prompt Engineering](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/index.ts) - [src/server.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/server.ts) - [src/config/ai-config.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/config/ai-config.ts) - [src/utils/tool-dispatcher.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/tool-dispatcher.ts) - [src/utils/config.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/config.ts) - [src/utils/logger.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/logger.ts) - [src/types/mcp.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/types/mcp.ts) - [package.json](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/package.json) - [docs/explanation/server-architecture.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/explanation/server-architecture.md) - [docs/explanation/mcp-architecture-flow.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/explanation/mcp-architecture-flow.md)
# System Architecture and Server Design ## 概述 `mcp-adr-analysis-server` 是一个基于 Model Context Protocol (MCP) 协议实现的服务端应用，专为 Architecture Decision Records (ADR) 提供分析与检索能力。该服务作为大语言模型客户端（如 Claude Desktop、IDE 插件）的工具提供方，通过标准化的 JSON-RPC 接口暴露一组结构化工具，使 LLM 能够在对话上下文中读取、搜索、生成并跟踪仓库中的架构决策记录 资料来源：[docs/explanation/server-architecture.md:1-15]()。 当前主版本为 `v2.6.8`，包入口文件定义为 `dist/index.js`，由 Node.js 运行时加载，并通过 stdio 与 MCP 客户端进行双向通信 资料来源：[package.json:1-25]()。该设计使得服务以"无状态进程"方式运行，无需独立的 HTTP 服务器或数据库，显著降低了部署复杂度。 ## 高层架构 服务整体遵循"MCP 传输层 → 路由分发层 → 工具实现层 → 领域服务层"四层架构。下图展示了请求从 MCP 客户端到达具体业务工具的主要数据流： ```mermaid flowchart LR A[MCP 客户端
Claude/IDE] -->|stdio/JSON-RPC| B[index.ts
入口] B --> C[Server
ListTools/CallTool] C --> D[ToolDispatcher
路由] D --> E[Tool 实现
tools/*] E --> F[领域服务
ADR 解析/AI 调用] F -->|结果| E E -->|JSON 响应| C C -->|stdio/JSON-RPC| A ``` 核心入口位于 `src/index.ts`，负责初始化 Server 实例并注册所有可用工具；请求到来时由 MCP SDK 完成协议编解码，再交由 `src/server.ts` 中的请求处理器分派到对应的工具模块 资料来源：[src/index.ts:1-50]() 资料来源：[src/server.ts:20-80]()。所有工具需要先通过 `ListToolsRequestSchema` 在握手阶段完成自描述注册，从而保证与 MCP 规范的兼容性 资料来源：[docs/explanation/mcp-architecture-flow.md:1-30]()。 ## 模块结构 模块化设计主要体现在 `src/` 目录的清晰切分： - **入口与传输**：`src/index.ts` 负责 stdio 传输握手、信号处理与优雅关闭。 - **服务核心**：`src/server.ts` 负责注册 `ListToolsRequestSchema` 与 `CallToolRequestSchema` 处理器，并集中错误返回逻辑。 - **工具分发**：`src/utils/tool-dispatcher.ts` 提供统一的工具查找与调用包装器，消除 `server.ts` 中重复的 `switch/case` 逻辑 资料来源：[src/utils/tool-dispatcher.ts:1-40]()。 - **配置加载**：`src/utils/config.ts` 与 `src/config/ai-config.ts` 负责读取环境变量、解析 `EXECUTION_MODE`，并在 AI 模式下注入 OpenRouter 兼容的模型参数 资料来源：[src/utils/config.ts:1-60]() 资料来源：[src/config/ai-config.ts:1-50]()。 - **类型定义**：`src/types/mcp.ts` 集中描述工具参数、上下文与响应结构，避免跨模块的 TypeScript 类型漂移 资料来源：[src/types/mcp.ts:1-30]()。 模块之间通过显式导入通信，不存在全局单例或隐式耦合，便于单元测试和按需替换实现。 ## MCP 协议集成 Server 通过 MCP SDK 注册三类核心能力：工具列表（`tools/list`）、工具调用（`tools/call`）与日志通知（`notifications/message`）。当请求到达 `CallToolRequestSchema` 时，`server.ts` 将其参数透传给 `ToolDispatcher`，后者根据工具名称选择对应的处理函数 资料来源：[src/server.ts:60-95]()。每个工具必须返回标准化的 `CallToolResult` 结构，其中 `content` 字段为文本或资源引用数组，便于客户端进行多模态展示 资料来源：[docs/explanation/mcp-architecture-flow.md:40-70]()。 如果工具抛出未捕获异常，Server 会捕获并将错误以 `isError: true` 形式返回给客户端，从而避免协议层崩溃，这种设计在社区多次 CI 失败场景下保证了服务的可恢复性 资料来源：[src/server.ts:100-120]()。 ## 配置与扩展 配置的单一来源是环境变量与 `.env` 文件，主要键包括 `OPENROUTER_API_KEY`、`EXECUTION_MODE`（取值 `lite` / `full`）以及部分可选的遥测开关 资料来源：[src/utils/config.ts:20-60]()。`ai-config.ts` 根据 `EXECUTION_MODE` 决定是否启用 AI 驱动的工具，例如 `generate_adr_todo` 与智能搜索 资料来源：[src/config/ai-config.ts:10-40]()。在 `lite` 模式下，系统完全离线运行，仅提供基于文件系统的工具，符合社区对"无外网依赖即可使用"的需求 资料来源：[docs/explanation/server-architecture.md:50-80]()。 扩展新工具的标准流程为：在 `src/tools/` 下新增实现文件，将元信息（名称、描述、输入 Schema）注册到 `ToolDispatcher` 的映射表中，并在文档侧补全对应条目。`logger.ts` 提供了分级日志能力，错误级别消息会自动通过 MCP 通知推送到客户端，便于 LLM 进行自我纠错 资料来源：[src/utils/logger.ts:1-30]()。这种"协议原生日志 + 显式扩展点"的组合，使项目能够在保持核心精简的同时承载大量领域工具。 ## 已知问题与注意事项 社区中的 `mcp-tool-check` 审计曾发现个别工具未在 `ListToolsRequestSchema` 中注册，导致其无法被客户端发现；该问题提醒新增工具时必须在两处（实现与注册）保持同步 资料来源：[docs/explanation/server-architecture.md:90-110]()。同时，`docs/QUICK_START.md` 中的配置示例与当前 `config.ts` 的实际行为存在差异，部署前应参考 `src/utils/config.ts` 的最新实现而非过时文档 资料来源：[src/utils/config.ts:1-20]()。 --- ## MCP Tools Catalog and Resources ### 相关页面 相关主题：[System Architecture and Server Design](#page-2), [ADR Management, Knowledge Graph, and Smart Code Linking](#page-4), [Data Flow, Memory, and State Management](#page-5)
相关源码文件 以下源码文件用于生成本页说明： - [src/tools/tool-catalog.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/tool-catalog.ts) - [src/tools/tool-dispatcher.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/tool-dispatcher.ts) - [src/tools/tool-chain-orchestrator.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/tool-chain-orchestrator.ts) - [src/resources/resource-router.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/resources/resource-router.ts) - [src/resources/index.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/resources/index.ts) - [docs/reference/analysis-tools.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/reference/analysis-tools.md)
# MCP Tools Catalog and Resources ## 概述 MCP Tools Catalog and Resources 是 `mcp-adr-analysis-server` 项目中负责**工具注册、调度与资源暴露**的核心子系统。它通过 Model Context Protocol（MCP）协议向客户端（如 IDE、AI 代理或 CLI）暴露一组可调用的"工具（tools）"以及一组可读取的"资源（resources）"，从而支撑架构决策记录（ADR）的分析、生成与验证流程。 该子系统的设计目标包括： - **集中注册**：所有 MCP 工具通过统一的目录（catalog）进行注册与发现，避免重复定义或遗漏注册。 - **统一调度**：通过调度器（dispatcher）将工具调用请求路由到具体实现，并支持链式编排（chain orchestration）。 - **资源路由**：对 URI 形式的资源请求进行解析与响应，支持 AD 缓存、模板、验证报告等结构化数据的读取。 - **离线优先**：在 `EXECUTION_MODE=full` 之外的场景下，工具仍可基于本地缓存运行（参见 `generate_adr_todo` 的离线里程碑跟踪能力）。 社区一致性审计（Issue #612）显示，仓库扫描到 34 个工具源文件、`ListToolsRequestSchema` 中注册了 72 个工具；任何新增工具若未在目录中注册，会被审计流程识别为缺失项（如 `search_tools` 的注册问题）。这一约束直接体现了 Tool Catalog 的强制性作用。 资料来源：[src/tools/tool-catalog.ts:1-40]() ## 工具目录（Tool Catalog）架构 `src/tools/tool-catalog.ts` 是整个工具子系统的入口点。它以集中方式声明所有可用工具的元数据（名称、描述、输入 schema、所属分类），并对外提供查询接口。工具被划分为若干领域，例如： - **分析类（Analysis）**：对代码库与 ADR 进行静态分析。 - **生成类（Generation）**：生成新的 ADR、待办列表或决策草案。 - **验证类（Validation）**：检查 ADR 的一致性、完整性与合规性。 - **搜索/发现类（Discovery）**：在知识库与缓存中检索相关内容。 `tool-catalog.ts` 在被加载时会聚合各分类目录中的工具描述，并构建一个不可变的"目录快照"。客户端在启动时通过 MCP 的 `ListToolsRequestSchema` 获取该快照，从而无需逐个发现工具。资料来源：[src/tools/tool-catalog.ts:40-120]() 文档侧由 [docs/reference/analysis-tools.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/reference/analysis-tools.md) 维护每个工具的可读说明、参数语义与示例调用，形成"代码即真相、文档即解释"的双层结构。 ## 调度器与链式编排 `src/tools/tool-dispatcher.ts` 负责将来自 MCP 客户端的工具调用（`CallToolRequestSchema`）按工具名称转发至对应处理器。其内部维护一张名称到处理器函数的映射表，并在调用前后执行统一的预处理（如参数校验、缓存查找、日志埋点）与后处理（如结果归一化、错误封装）。资料来源：[src/tools/tool-dispatcher.ts:1-80]() 对于需要按顺序执行多个工具的复合任务（例如：先分析代码 → 再生成 ADR 草案 → 最后校验一致性），系统通过 `src/tools/tool-chain-orchestrator.ts` 提供链式编排能力。编排器接受一个声明式的步骤序列，每一步可以引用目录中的任意工具，并支持： - **短路条件**：当某步返回特定结果时跳过后续步骤。 - **上下文传递**：将前序工具的输出注入后续工具的输入。 - **失败重试与回退**：在工具抛出可恢复错误时按策略重试。 资料来源：[src/tools/tool-chain-orchestrator.ts:30-110]() ## 资源路由（Resource Router） 与工具的"调用即执行"不同，MCP 的 resources 是"读取即返回"的只读数据视图。`src/resources/resource-router.ts` 负责将客户端的 `ReadResourceRequestSchema` 请求按 URI scheme 分发到对应提供者，例如： - `adr://list`：枚举已知 ADR 列表（可能来自缓存或文件系统）。 - `adr://{id}`：返回指定 ADR 的完整内容。 - `template://{name}`：返回生成新 ADR 时所使用的模板。 - `validation://report`：返回最近一次一致性验证的结构化报告。 路由表在 `src/resources/index.ts` 中集中注册，每个资源提供者在被调用时返回符合 MCP 规范的 `contents` 数组（含 `uri`、`mimeType` 与 `text`/`blob`）。资料来源：[src/resources/resource-router.ts:1-70]() 资料来源：[src/resources/index.ts:1-50]() 下表给出 Tools 与 Resources 的核心差异速览： | 维度 | Tools | Resources | | --- | --- | --- | | 交互方式 | 客户端主动调用并传入参数 | 客户端按 URI 读取，无参数 | | 副作用 | 可写（生成 ADR、写入缓存） | 只读 | | 注册入口 | `tool-catalog.ts` | `resources/index.ts` | | 调度入口 | `tool-dispatcher.ts` / `tool-chain-orchestrator.ts` | `resource-router.ts` | ## 注册一致性约束 社区中常见的两类问题与本子系统密切相关： 1. **工具遗漏注册**：Issue #612 的审计脚本会对比工具源文件数量与 `ListToolsRequestSchema` 中的注册数量，任何差异常常意味着新增工具未接入目录。开发者新增工具时，应同时更新 `tool-catalog.ts` 与 `docs/reference/analysis-tools.md`。 2. **文档与代码不同步**：Issue #694、`docs/QUICK_START.md` 描述了过时工具集，导致新开发者按文档操作时找不到对应工具。文档与 catalog 必须以代码为准，避免"文档孤儿"。 资料来源：[docs/reference/analysis-tools.md:1-60]() 通过以上四层结构——**目录（catalog）→ 调度（dispatcher）→ 编排（orchestrator）→ 资源（resources）**——MCP Tools Catalog and Resources 为 `mcp-adr-analysis-server` 提供了一个可发现、可调用、可观测且易于审计的工具与资源能力面，是整个 ADR 分析工作流的协议层入口。 --- ## ADR Management, Knowledge Graph, and Smart Code Linking ### 相关页面 相关主题：[MCP Tools Catalog and Resources](#page-3), [Data Flow, Memory, and State Management](#page-5), [AI/LLM Integration and Prompt Engineering](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [src/tools/adr-suggestion-tool.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/adr-suggestion-tool.ts) - [src/tools/generate-adr-todo-tool.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/generate-adr-todo-tool.ts) - [src/tools/adr-bootstrap-validation-tool.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/tools/adr-bootstrap-validation-tool.ts) - [src/utils/adr-discovery.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/adr-discovery.ts) - [src/utils/knowledge-graph-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/knowledge-graph-manager.ts) - [src/utils/tree-sitter-analyzer.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/tree-sitter-analyzer.ts)
# ADR Management, Knowledge Graph, and Smart Code Linking ## 概述 `mcp-adr-analysis-server` 是一个基于 Model Context Protocol（MCP）的服务器，其核心职责是让 AI Agent 能够对项目中的 **架构决策记录（ADR）** 进行检索、生成、校验与关联分析。本专题覆盖三大支柱能力：**ADR 管理**、**知识图谱（Knowledge Graph）**、**智能代码链接（Smart Code Linking）**。三者协同，使 ADR 不再是孤立的 markdown 文件，而是可被查询、可被推理、可被反向追溯到具体代码符号的语义网络。资料来源：[src/utils/adr-discovery.ts:1-40]() ## ADR 管理 ADR 管理模块负责 ADR 的发现、引导、校验与建议生成，对应一组 MCP 工具与底层工具函数。 - **发现（Discovery）**：`adr-discovery.ts` 提供目录扫描与结构解析能力，用于在仓库的 `docs/adrs/` 或自定义目录中定位 ADR 文件并提取元数据（编号、标题、状态、日期）。资料来源：[src/utils/adr-discovery.ts:1-80]() - **引导校验（Bootstrap Validation）**：`adr-bootstrap-validation-tool.ts` 在项目初始化阶段检查 ADR 目录结构与必备模板字段是否齐全，避免后续分析出现空目录或格式不一致问题。资料来源：[src/tools/adr-bootstrap-validation-tool.ts:1-60]() - **建议生成（Suggestion）**：`adr-suggestion-tool.ts` 基于当前代码改动与现有 ADR 内容，向 Agent 推荐是否需要新增或更新 ADR。资料来源：[src/tools/adr-suggestion-tool.ts:1-90]() - **离线 TODO 生成**：v2.6.0 引入的 `generate_adr_todo` 工具（见 Release v2.6.0）将 ADR 拆解为离线可追踪的里程碑任务，便于无 LLM 推理环境下继续推进。资料来源：[src/tools/generate-adr-todo-tool.ts:1-120]() ## 知识图谱 知识图谱将 ADR、概念标签（topic tags）、相关代码模块、负责人等节点统一建模为有向图，使 Agent 能够回答诸如"哪些 ADR 影响鉴权模块？"或"A 决策与哪些历史决策相矛盾？"之类的关系型问题。 - `knowledge-graph-manager.ts` 负责节点的增删改查、边的构建以及序列化输出（JSON / GraphML）。资料来源：[src/utils/knowledge-graph-manager.ts:1-100]() - 图谱的输入来自三处：ADR 文档的元数据、代码分析结果（见下一节）、Agent 在对话中显式声明的关系。资料来源：[src/utils/knowledge-graph-manager.ts:60-140]() - 节点典型字段包括 `adrId`、`title`、`status`、`supersedes`、`linksToCode`；边类型覆盖 `supersedes`、`relates-to`、`implements`、`contradicts`。资料来源：[src/utils/knowledge-graph-manager.ts:40-90]() ## 智能代码链接 智能代码链接通过 `tree-sitter` 解析多语言源代码，抽取函数、类、模块等符号，并与 ADR 中提及的关键词进行匹配，从而在"决策"与"实现"之间建立可验证的桥接。 - `tree-sitter-analyzer.ts` 封装对 JS/TS、Python、Go 等语言的 AST 遍历，输出 `Symbol` 列表（名称、位置、签名）。资料来源：[src/utils/tree-sitter-analyzer.ts:1-80]() - 匹配阶段采用轻量级相似度（命名 + 注释关键词）将符号与 ADR 文本中的"受影响组件"段落对齐，生成 `adr → symbol` 的有向边并写回知识图谱。资料来源：[src/utils/tree-sitter-analyzer.ts:80-150]() - 当代码发生迁移时，重新分析可更新链接状态，从而支撑影响面分析（impact analysis）与漂移检测（drift detection）。资料来源：[src/utils/tree-sitter-analyzer.ts:150-200]() ## 端到端工作流 下图描述一次典型的"代码改动 → ADR 建议 → 知识图谱更新"闭环： ```mermaid flowchart LR A[代码改动] --> B[tree-sitter-analyzer] B --> C[提取符号] C --> D[knowledge-graph-manager] D --> E{匹配既有 ADR?} E -- 命中 --> F[更新链接] E -- 未命中 --> G[adr-suggestion-tool] G --> H[建议新 ADR] H --> I[generate_adr_todo] I --> J[离线里程碑] D --> K[知识图谱查询 API] ``` ## 已知限制与社区关注 社区多次出现"AI Executor Integration failed"（#1187、#1235）类工作流失败，其根因是 Copilot CLI 在受限组织中无推理权限；该问题会同时阻断依赖 LLM 的 `adr-suggestion-tool` 调用，但不影响纯本地工具（如 `generate_adr_todo` 与 `adr-bootstrap-validation`）。另外，文档审查问题 #546 指出环境变量配置（`OPENROUTER_API_KEY` 等）说明缺失，使用本模块前应先确认对应密钥已正确注入。资料来源：[issues/1187](), [issues/1235](), [issues/546]() ## 小结 - **ADR 管理** 提供发现、校验、建议、离线 TODO 完整链路。资料来源：[src/tools/adr-bootstrap-validation-tool.ts:1-60]() - **知识图谱** 是连接 ADR 与外部实体（代码、标签、人员）的语义中枢。资料来源：[src/utils/knowledge-graph-manager.ts:40-90]() - **智能代码链接** 通过 tree-sitter 把决策反向锚定到代码符号，实现可验证的影响面分析。资料来源：[src/utils/tree-sitter-analyzer.ts:80-150]() --- ## Data Flow, Memory, and State Management ### 相关页面 相关主题：[System Architecture and Server Design](#page-2), [ADR Management, Knowledge Graph, and Smart Code Linking](#page-4), [AI/LLM Integration and Prompt Engineering](#page-6)
相关源码文件 以下源码文件用于生成本页说明： - [src/utils/conversation-memory-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/conversation-memory-manager.ts) - [src/utils/memory-entity-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/memory-entity-manager.ts) - [src/utils/knowledge-graph-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/knowledge-graph-manager.ts) - [src/utils/state-reinforcement-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/state-reinforcement-manager.ts) - [src/utils/tiered-response-manager.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/tiered-response-manager.ts) - [src/utils/cache.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/cache.ts)
# Data Flow, Memory, and State Management `mcp-adr-analysis-server` 在分析 ADR（Architecture Decision Records，架构决策记录）的过程中，需要在多个工具调用之间保留上下文、对历史分析进行推理、并把结果按层级返回给调用方。本页面围绕数据在系统中的流动方式、记忆系统的分层结构、以及跨调用的状态维持机制展开。 ## 系统中的三层记忆模型 服务器的记忆体系分为三个相互协作的层次，每层由独立的工具模块负责： 1. **会话记忆层（Conversation Memory）**：由 `conversation-memory-manager.ts` 管理，负责记录 MCP 工具调用产生的请求与响应序列，使后续调用能够引用先前结果 资料来源：[src/utils/conversation-memory-manager.ts:1-120]()。 2. **实体记忆层（Entity Memory）**：由 `memory-entity-manager.ts` 负责，将 ADR 中的概念（例如"技术选型"、"约束条件"、"决策后果"）抽象为实体对象，并提供增删改查接口 资料来源：[src/utils/memory-entity-manager.ts:1-150]()。 3. **知识图谱层（Knowledge Graph）**：由 `knowledge-graph-manager.ts` 构建实体间的关系边，把孤立的实体连接成可推理的结构 资料来源：[src/utils/knowledge-graph-manager.ts:1-200]()。 三层之间存在单向的数据沉淀关系：会话记忆捕获原始交互 → 实体记忆从中抽取结构化条目 → 知识图谱进一步把条目组织为关系网络 资料来源：[src/utils/memory-entity-manager.ts:40-95]()。 ## 数据流动：从 MCP 请求到响应返回 下表梳理一次典型的工具调用所经过的核心组件： | 阶段 | 主要组件 | 输入 | 输出 | |------|----------|------|------| | 请求接入 | MCP Server (`ListToolsRequestSchema`) | 工具名称 + 参数 | 路由到对应工具 | | 上下文装载 | `conversation-memory-manager.ts` | 历史会话 | 上下文摘要 | | 实体检索 | `memory-entity-manager.ts` + `knowledge-graph-manager.ts` | 当前 ADR | 关联实体与关系 | | 状态强化 | `state-reinforcement-manager.ts` | 弱信号 | 加权后的状态向量 | | 响应分级 | `tiered-response-manager.ts` | 完整结果 | 压缩/精简响应 | | 缓存写入 | `cache.ts` | 计算结果键值对 | 后续命中 | 状态强化阶段是服务器的特色设计：分析过程中会产生大量"弱信号"（例如重复出现的关键词、跨工具引用），`state-reinforcement-manager.ts` 负责把这些信号累计并放大，使关键的架构决策不易被噪声淹没 资料来源：[src/utils/state-reinforcement-manager.ts:30-110]()。 ## 分层响应与缓存策略 为了适配不同 LLM 客户端的上下文窗口限制，`tiered-response-manager.ts` 把响应分为多档：完整响应、摘要响应、要点响应。该模块在生成内容前会检查当前上下文的剩余容量，并自动选择合适的输出层级 资料来源：[src/utils/tiered-response-manager.ts:1-80]()。 `cache.ts` 提供基于键值的内存缓存，用于存储昂贵的计算结果（例如跨多个 ADR 的依赖分析、知识图谱遍历结果等）。缓存键通常由工具名称与参数哈希组合而成，确保相同输入直接命中，避免重复计算 资料来源：[src/utils/cache.ts:20-90]()。当会话记忆被清理时，缓存也会根据配置的失效策略同步淘汰 资料来源：[src/utils/cache.ts:95-140]()。 ## 跨调用的状态维持 服务器的状态在三个时间维度上得到维持： - **请求内**：通过函数参数与局部变量直接传递。 - **会话内**：依赖 `conversation-memory-manager.ts` 与 `memory-entity-manager.ts` 持久化的会话上下文。 - **会话间**：通过 `state-reinforcement-manager.ts` 的强化状态以及磁盘/缓存层共同承载，使后续会话能够继承前次分析结论。 社区审计记录（issue #612）显示，"mcp-tool-check" 工具一致性报告中曾发现 `search_tools` 工具注册缺失问题，提示所有涉及记忆与状态的工具必须正确接入 `ListToolsRequestSchema`，否则状态维持链路会出现断点 资料来源：[issue #612 — MCP Tool Consistency Report]()。同样地，文档审查（issue #546 与 #694）多次指出环境变量与执行模式配置不清晰可能影响 `EXECUTION_MODE=full` 下的状态保留行为，开发者应在调用前正确设置 `OPENROUTER_API_KEY` 等关键环境变量 资料来源：[issue #546 — Documentation Review]()。 ## 关键设计要点 - **单一职责**：每个管理器只负责一个层级的职责，便于单独替换或测试。 - **可观测性**：所有记忆操作都暴露日志与指标接口，便于追踪状态变化。 - **降级能力**：当上游 LLM 不可用时，`tiered-response-manager.ts` 与 `cache.ts` 协同提供离线响应能力（v2.6.0 引入的 `generate_adr_todo` 即具备此特性）资料来源：[Release v2.6.0]()。 - **一致性约束**：知识图谱层与实体记忆层之间通过实体 ID 关联，任何一方的不一致都会触发同步校验。 --- ## AI/LLM Integration and Prompt Engineering ### 相关页面 相关主题：[Project Overview and Concepts](#page-1), [MCP Tools Catalog and Resources](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/utils/ai-executor.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/ai-executor.ts) - [src/utils/automatic-prompt-engineering.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/automatic-prompt-engineering.ts) - [src/utils/reflexion.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/reflexion.ts) - [src/utils/apply-cot-enhancement.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/apply-cot-enhancement.ts) - [src/utils/chain-of-thought-template.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/chain-of-thought-template.ts) - [src/utils/prompt-execution.ts](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/src/utils/prompt-execution.ts)
# AI/LLM 集成与提示工程 ## 概述与职责范围 本项目的 AI/LLM 集成层为 MCP ADR 分析服务器提供"模型无关"的可执行接口,使各类架构决策记录(ADR)分析工具能够通过统一的抽象调用大语言模型。核心目标包括:统一 OpenRouter、本地模型、Copilot CLI 等多种后端;提供自动提示工程(APE)、思维链(CoT)增强、反思(Reflexion)等提示优化手段;以及为上层工具提供一致的超时、重试与脱机降级策略。资料来源：[src/utils/ai-executor.ts:1-80]() `ai-executor.ts` 模块定义了 `callAIModel`、`executeWithFallback`、`getExecutionConfig` 等关键入口,集中处理环境变量 `EXECUTION_MODE`、`OPENROUTER_API_KEY` 等配置,并在缺失推理凭据时主动抛出可识别的错误,以避免静默失败。资料来源：[src/utils/ai-executor.ts:40-120]() ## 提示工程组件 ### 自动提示工程 (APE) `automatic-prompt-engineering.ts` 实现了一种基于候选生成与评分筛选的提示优化管线:首先生成若干候选指令,再用一个评分函数(通常结合目标任务的样本输出)挑选最优指令,最后将优化后的提示作为系统消息注入到后续调用中。该模块常被用于"生成 ADR 摘要"、"提取决策上下文"等需要稳定输出的工具。资料来源：[src/utils/automatic-prompt-engineering.ts:1-60]() ### 思维链 (Chain-of-Thought) 增强 `chain-of-thought-template.ts` 提供标准化的 CoT 模板,包含"角色定义 → 任务说明 → 推理步骤 → 输出格式"四段结构。`apply-cot-enhancement.ts` 则负责在运行时将 CoT 模板按工具上下文进行参数化注入,确保不同工具(如 `analyze_adr`、`generate_adr_todo`)既能共享推理骨架,又能保留各自的领域语义。资料来源：[src/utils/chain-of-thought-template.ts:1-50]() [src/utils/apply-cot-enhancement.ts:1-50]() ### 反思机制 (Reflexion) `reflexion.ts` 引入了自我评估-重试循环:模型首轮输出后,系统会根据预设的"质量判据"(例如 ADR 必填字段完整性、引用准确性)对结果打分;若未达标,则把评判意见作为附加反馈回传模型,触发二次生成。该机制显著降低了在结构化输出场景下的格式错误率。资料来源：[src/utils/reflexion.ts:30-90]() ## 执行管线与降级策略 `prompt-execution.ts` 是上层工具与 AI 执行器之间的桥梁,负责封装"提示组装 → 调用 ai-executor → 结果校验 → 缓存/降级"的完整生命周期。下图展示了典型的执行流: ```mermaid flowchart LR A[Tool 调用] --> B[prompt-execution 组装提示] B --> C{是否启用 CoT?} C -- 是 --> D[apply-cot-enhancement 注入模板] C -- 否 --> E[直接使用 APE 优化后的提示] D --> F[ai-executor 调用模型] E --> F F --> G{是否启用 Reflexion?} G -- 是 --> H[反思评分与重试] G -- 否 --> I[返回结果] H --> I ``` 执行层支持多种 `EXECUTION_MODE`,例如 `full`、`local-only`、`offline`。在 `offline` 模式下,系统跳过模型调用,改为返回基于规则的回退结果,以保证 CI 与文档站验证流程不会因凭据缺失而中断。资料来源：[src/utils/ai-executor.ts:80-160]() [src/utils/prompt-execution.ts:40-100]() ## 已知限制与社区反馈 社区中已记录的 `AI Executor Integration` 工作流多次出现"Inference Access Denied"错误,通常发生在 Copilot CLI 使用的令牌不具备推理权限时(#1187、#1235)。这属于上游凭据配置问题,而非本仓库代码缺陷;在自托管场景下,可改用 `OPENROUTER_API_KEY` 或本地模型后端绕过。此外,文档站审计(#542)与"无经验开发者"测试(#546、#694)曾指出,环境变量说明在多版 README 中不够明确,建议在部署前显式设置 `OPENROUTER_API_KEY` 与 `EXECUTION_MODE` 以避免运行时降级。资料来源：[issue #1235]() [issue #1187]() [issue #546]() --- ## Deployment, Infrastructure, and Extensibility ### 相关页面 相关主题：[System Architecture and Server Design](#page-2), [MCP Tools Catalog and Resources](#page-3), [Operations, Testing, Troubleshooting, and Release](#page-8)
相关源码文件 以下源码文件用于生成本页说明： - [docs/DEPLOYMENT_GUIDE.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/DEPLOYMENT_GUIDE.md) - [docs/DOCKER_SETUP.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/DOCKER_SETUP.md) - [docs/docker-compose.yml](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/docker-compose.yml) - [docs/Dockerfile](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/Dockerfile) - [scripts/install-rhel.sh](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/scripts/install-rhel.sh) - [patterns/infrastructure/aws.yaml](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/patterns/infrastructure/aws.yaml)
# 部署、基础设施与可扩展性 ## 1. 部署范围与设计目标 `mcp-adr-analysis-server` 是一个基于模型上下文协议（MCP）的 Node.js 服务器，向客户端暴露 ADR（架构决策记录）分析工具。为覆盖本地开发、CI、桌面端与生产云环境，仓库在 `docs/` 目录集中提供统一的多形态部署说明：主指南 `DEPLOYMENT_GUIDE.md` 给出总体策略与运行模式，`DOCKER_SETUP.md` 描述容器化路径 资料来源：[docs/DEPLOYMENT_GUIDE.md:1-40]()。在 v2.5–v2.6 系列中，发布流水线经历了多次修补：v2.5.4（PR #810）将 `publish.yml` 改造为“单一事实来源”的发布闸门；v2.6.2（PR #863）修复其 `workflow_call` 检测；v2.6.6（PR #890）允许发布机器人在 PR 关闭后再次打开时继续轮询 资料来源：[docs/DEPLOYMENT_GUIDE.md:60-110]()。 ## 2. 容器化部署 容器路径由 `docs/Dockerfile` 与 `docs/docker-compose.yml` 共同定义。`Dockerfile` 采用多阶段构建以减小最终镜像体积，并固定与 `package.json` 中一致的 Node 基础镜像版本 资料来源：[docs/Dockerfile:1-30]()。`docker-compose.yml` 将服务器、可选推理服务与挂载卷编排为单一栈，使 `docker compose up` 即可复现接近生产的环境 资料来源：[docs/docker-compose.yml:1-45]()。 部署栈的组件关系如下： ```mermaid flowchart LR A[mcp-adr-analysis-server 容器] --> B[(本地 ADR 目录挂载)] A --> C[OpenRouter 推理 API] A --> D[(缓存/产物卷)] A --> E[GitHub MCP / AI Executor] ``` 容器运行支持通过 `EXECUTION_MODE` 在 `full` 与只读分析模式之间切换，相关环境变量约定见 `DOCKER_SETUP.md` 资料来源：[docs/DOCKER_SETUP.md:20-55]()。 ## 3. 基础设施即代码：AWS 模式 仓库在 `patterns/infrastructure/aws.yaml` 中提供基础设施即代码模板，使用 AWS 原生格式描述 VPC、子网、IAM 角色、ECR 仓库以及用于运行容器的计算资源 资料来源：[patterns/infrastructure/aws.yaml:1-80]()。与 `DEPLOYMENT_GUIDE.md` 中云端部署章节配合，可将本地 `docker-compose.yml` 描述的服务拓扑平滑迁移到 ECS Fargate 或 EKS 资料来源：[docs/DEPLOYMENT_GUIDE.md:120-180]()。 社区报告（#690 “CI Doctor”）指出：`aws.yaml` 触发的部署曾因 `gh-aw` 锁文件不一致以及 npm 依赖漏洞而失败，修复后需要重新触发工作流并校验镜像 tag。 ## 4. 主机安装与 CI/CD 流水线 针对无法使用容器的环境，`scripts/install-rhel.sh` 在 RHEL/CentOS 系列上自动安装 Node、克隆仓库并配置 systemd 单元，使服务以守护进程方式运行 资料来源：[scripts/install-rhel.sh:1-60]()。该脚本与 Docker 路径共享同一份环境变量约定（`OPENROUTER_API_KEY`、`EXECUTION_MODE` 等），便于在不同形态间保持行为一致 资料来源：[scripts/install-rhel.sh:60-110]()。 CI/CD 侧，发布由 `publish.yml` 驱动：v2.5.4 统一发布闸门，v2.5.3 与 v2.6.2 多次修补 tag→npm 同步以及 `workflow_call` 识别逻辑，v2.6.6 让 bump PR 在关闭后仍能被继续轮询 资料来源：[docs/DEPLOYMENT_GUIDE.md:200-280]()。社区观察的 AI Executor Integration 失败（#1187、#1235）说明：尽管发布闸门已统一，Copilot CLI 推理访问令牌仍是工作流稳定性的外部依赖，仓库通过 Dependabot（如 PR #910 升级 `github/gh-aw-actions`）持续缓解该风险。 ## 5. 可扩展性实践 扩展此服务的常见路径包括： - 在 `docker-compose.yml` 中新增 sidecar 容器（如向量库或缓存代理）； - 在 `aws.yaml` 中追加 Fargate Service、目标组与自动伸缩策略； - 新增 `scripts/install-*.sh` 覆盖更多 Linux 发行版； - 在 `ListToolsRequestSchema` 中注册自定义 MCP 工具（参考 #612 一致性审计所记录的 `search_tools` 缺失问题）。 所有扩展都应与 `DEPLOYMENT_GUIDE.md` 中定义的环境变量与运行模式保持一致。社区在 #546 “Documentation Noob Test” 中也指出，环境变量设置与运行模式说明需要在 README 中显式给出，否则新用户将无法正确启动容器或主机部署。 --- ## Operations, Testing, Troubleshooting, and Release ### 相关页面 相关主题：[Project Overview and Concepts](#page-1), [System Architecture and Server Design](#page-2), [Deployment, Infrastructure, and Extensibility](#page-7)
相关源码文件 以下源码文件用于生成本页说明： - [docs/how-to-guides/troubleshooting.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/troubleshooting.md) - [docs/how-to-guides/testing-guide.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/how-to-guides/testing-guide.md) - [docs/TESTING_GUIDE.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/TESTING_GUIDE.md) - [docs/VERSION_MANAGEMENT.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/docs/VERSION_MANAGEMENT.md) - [RELEASES.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/RELEASES.md) - [CHANGELOG.md](https://github.com/tosin2013/mcp-adr-analysis-server/blob/main/CHANGELOG.md)
# Operations, Testing, Troubleshooting, and Release 本页面系统化介绍 `mcp-adr-analysis-server` 项目在运维、测试、故障排查与版本发布四个维度的工程实践。该项目是一个基于模型上下文协议（Model Context Protocol, MCP）的架构决策记录（Architecture Decision Records, ADR）分析服务器，提供了 70+ 个工具来辅助架构分析、知识管理及代码智能处理。由于工具面广、依赖模型推理与 GitHub Actions 自动化，构建一个可重复、可观察、可回滚的工程体系至关重要 资料来源：[RELEASES.md:1-40]()。 ## 1. 运维（Operations） 项目的日常运维主要围绕 GitHub Actions 工作流展开，涵盖持续集成、安全扫描、依赖更新与发布流水线四个核心工作流。 ### 1.1 AI Executor Integration 工作流 `AI Executor Integration` 工作流是项目最关键的自动化入口之一，用于驱动 Copilot CLI 执行模型推理任务。在最近的多次运行中（例如 #29143226313、#28649312387），该工作流频繁出现 `Inference Access Denied` 错误，原因是令牌未配置对推理端点的访问权限。资料来源：[docs/how-to-guides/troubleshooting.md:1-60]()。运维人员应确保： - 组织或仓库已为 Copilot CLI 启用模型推理能力； - 工作流使用的 `GITHUB_TOKEN` 拥有足够的 `models:read` 权限作用域； - 私有组织需要在设置中显式开启「Allow access to models in this organization」开关。 ### 1.2 依赖与构建更新 `@dependabot[bot]` 负责周期性地拉起依赖升级 PR，例如 `github/gh-aw-actions` 从 0.71.1 升级到 0.71.4 的 PR #910、 `@rollup/rollup-win32-x64-msvc` 从 4.60.2 到 4.60.4 的 PR #929，均通过自动发布流水线直接生成对应版本标签 资料来源：[CHANGELOG.md:1-20]()。 ## 2. 测试（Testing） 测试体系分为单元测试、工具一致性审计与文档无障碍测试三层，确保每次发布前变更既不破坏 API 契约，也保障新开发者上手顺畅。 ### 2.1 工具一致性审计 `mcp-tool-check` 工作流会扫描 34 个工具源文件并与 `ListToolsRequestSchema` 中注册的 72 个工具对比。最新一次审计发现 `search_tools` 工具存在「工具未注册」问题（issue #612），提示开发者在新增工具时必须同步更新中心化的注册表与模式声明 资料来源：[docs/how-to-guides/testing-guide.md:1-80]()。 ### 2.2 文档无障碍测试 `docs-noob` 自动化测试以新开发者视角审视 `docs/` 目录下的 171–172 份 Markdown 文件。在 2026-04-19 与 2026-02-21 的两次扫描中，分别发现了 19 项和 47 项问题，其中关键问题包括 `docs/QUICK_START.md` 描述了与现状不符的文档系统，以及环境变量配置说明缺失 资料来源：[docs/TESTING_GUIDE.md:1-60]()。 ## 3. 故障排查（Troubleshooting） 常见故障集中在三类：CI 失败、文档与代码不一致、以及 AI Executor 推理拒绝。 | 故障类别 | 典型表现 | 排查起点 | |----------|---------|---------| | CI 依赖漏洞 | `npm audit` 报错、依赖锁定文件冲突 | issue #690 中 `CI Doctor` 报告 | | 工具注册缺失 | MCP 客户端调用 `search_tools` 失败 | `mcp-tool-check` 工作流 | | 推理访问被拒 | `AI Executor Integration` 步骤立即退出 | GitHub 组织模型访问设置 | `CI Doctor` 自动诊断工作流（如 #24636103297）将两类故障聚合在同一份报告中，运维者只需按其引用的提交 `8f650881f6db2dbe131f4472da3192de4eec7a3f` 回溯 bisect 即可定位根因 资料来源：[docs/how-to-guides/troubleshooting.md:60-140]()。 ## 4. 发布（Release） 发布流水线以 `publish.yml` 为唯一权威闸门（single source of truth），任何到 `main` 分支的合并都会触发自动版本号提升与 npm 发布。 ### 4.1 版本管理策略 `docs/VERSION_MANAGEMENT.md` 定义了语义化版本（SemVer）规则：次要版本用于新增功能（如 v2.6.0 引入 `generate_adr_todo` 工具），补丁版本用于修复 CI/发布管线问题（例如 v2.6.6 的「容忍 bump PR 的 close+reopen」、v2.6.2 的 `workflow_call` 检测修复） 资料来源：[docs/VERSION_MANAGEMENT.md:1-80]()。 ### 4.2 发布管线演化 项目曾在 v2.5.3 之前遇到 GitHub 标签未正确同步到 npm 的问题（PR #808），后续在 v2.5.4 通过「将 publish gate 作为单一真实来源」彻底重构，确保标签、CHANGELOG 与 npm 包版本三者始终一致 资料来源：[RELEASES.md:1-60]()。 ### 4.3 文档站点验证 `docs-site` 工作流对部署到 GitHub Pages 的站点执行每周一次的爬取校验。2026-02-20 的运行（issue #542）抓取 7 个页面样本并发现 3 处问题，运维团队据此向文档作者派发修复工单 资料来源：[docs/how-to-guides/testing-guide.md:80-140]()。 --- **小结**：通过将 AI Executor、依赖更新、工具注册、文档无障碍测试与发布闸门串联在同一套 GitHub Actions 体系下，本项目在不牺牲发布频率的前提下，最大化了变更可追溯性与故障可定位性。开发者在提交 PR 前应主动运行本地 `npm test`、`mcp-tool-check` 与 `docs-noob` 三类检查，以减少上游工作流的失败重试成本 资料来源：[docs/TESTING_GUIDE.md:60-120]()。 --- --- ## Doramagic 踩坑日志 项目：tosin2013/mcp-adr-analysis-server 摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: [aw] AI Executor Integration failed。 ## 1. 安全/权限坑 · 失败模式：security_permissions: [aw] AI Executor Integration failed - 严重度：high - 证据强度：source_linked - 发现：Developers should check this security_permissions risk before relying on the project: [aw] AI Executor Integration failed - 对用户的影响：Developers may expose sensitive permissions or credentials: [aw] AI Executor Integration failed - 证据：failure_mode_cluster:github_issue | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1235 | [aw] AI Executor Integration failed, failure_mode_cluster:github_issue | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1187 | [aw] AI Executor Integration failed ## 2. 安全/权限坑 · 来源证据：[aw] AI Executor Integration failed - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[aw] AI Executor Integration failed - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/tosin2013/mcp-adr-analysis-server/issues/1235 | 来源类型 github_issue 暴露的待验证使用条件。 ## 3. 安装坑 · 失败模式：installation: Release v2.5.1 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Release v2.5.1 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.1 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.1 | Release v2.5.1 ## 4. 安装坑 · 失败模式：installation: Release v2.5.3 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Release v2.5.3 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.3 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.3 | Release v2.5.3 ## 5. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/tosin2013/mcp-adr-analysis-server | host_targets=mcp_host, claude, cursor ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/tosin2013/mcp-adr-analysis-server | README/documentation is current enough for a first validation pass. ## 7. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/tosin2013/mcp-adr-analysis-server | no_demo; severity=medium ## 9. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/tosin2013/mcp-adr-analysis-server | no_demo; severity=medium ## 10. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | issue_or_pr_quality=unknown ## 11. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/tosin2013/mcp-adr-analysis-server | release_recency=unknown ## 12. 维护坑 · 失败模式：maintenance: Release v2.5.2 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.5.2 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.2 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.2 | Release v2.5.2 ## 13. 维护坑 · 失败模式：maintenance: Release v2.5.4 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.5.4 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.5.4 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.5.4 | Release v2.5.4 ## 14. 维护坑 · 失败模式：maintenance: Release v2.6.0 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.0 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.0 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.0 | Release v2.6.0 ## 15. 维护坑 · 失败模式：maintenance: Release v2.6.1 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.1 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.1 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.1 | Release v2.6.1 ## 16. 维护坑 · 失败模式：maintenance: Release v2.6.2 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.2 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.2 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.2 | Release v2.6.2 ## 17. 维护坑 · 失败模式：maintenance: Release v2.6.7 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.7 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.7 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.7 | Release v2.6.7 ## 18. 维护坑 · 失败模式：maintenance: Release v2.6.8 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: Release v2.6.8 - 对用户的影响：Upgrade or migration may change expected behavior: Release v2.6.8 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.8 | Release v2.6.8 ## 19. 维护坑 · 失败模式：maintenance: v2.6.6 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this maintenance risk before relying on the project: v2.6.6 - 对用户的影响：Upgrade or migration may change expected behavior: v2.6.6 - 证据：failure_mode_cluster:github_release | https://github.com/tosin2013/mcp-adr-analysis-server/releases/tag/v2.6.6 | v2.6.6