ads-help-mcp

面向 Keysight ADS 帮助资料的本地、多版本 RAG MCP 服务。首期支持 2025 和 2026-update1，后续版本通过新增 release TOML 接入，不需要修改检索器或 MCP 服务代码。

本项目只负责资料采集、规范化、索引、检索和版本差异。ADS GUI/AEL 自动化仍由原 ADS2025_help 项目负责，两个项目可独立运行和回退。

版本语义

• 精确版本 ID 是不可变快照，例如 2025、2026-update1。
• 2026 和 ads2026 解析为已配置的最高 2026 版本。
• latest 解析为所有配置中的最高版本。
• 未指定版本时固定使用 2026-update1；新增 ADS2027 不会改变默认值。
• 别名解析后的版本如果没有索引会直接报错，绝不跨版本降级。

每个精确版本的数据和索引都位于独立的 data/<release>/ 目录。data/ 整体被 Git 忽略。

环境要求与安装

• Windows 本地 Python >=3.12,<3.14
• 可执行 ssh IC_Server，服务器安装目录为 /opt/eda/agilent/ADS*
• 首次构建索引时可联网下载 Chroma 默认 ONNX all-MiniLM-L6-v2 模型；MCP 启动不会下载模型、处理语料或重建索引

cd D:\Users\Administrator\Documents\GitHub\ads-help-mcp
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\ads-help.exe doctor

如果机器不能联网，请事先把 Chroma ONNX 模型放入 doctor 输出的任一缓存路径。

构建首期语料

完整流水线会通过 SSH 仅采集 HTML、Python API 源码/存根和配置的 Python/AEL 示例，然后在本地处理并建立隔离索引：

.\.venv\Scripts\ads-help.exe build --release 2025
.\.venv\Scripts\ads-help.exe build --release 2026-update1
.\.venv\Scripts\ads-help.exe diff --from 2025 --to 2026-update1

也可以分阶段执行，便于检查中间产物：

.\.venv\Scripts\ads-help.exe sync --release 2026-update1
.\.venv\Scripts\ads-help.exe process --release 2026-update1
.\.venv\Scripts\ads-help.exe index --release 2026-update1
.\.venv\Scripts\ads-help.exe index --release 2026-update1 --incremental

sync 先将归档解压到 staging，逐文件验证大小和 SHA-256 后才原子替换旧快照。 普通内容变化可使用增量索引；处理器、配置、切块策略或 embedding 指纹不兼容时会 自动全量重建。

运行与注册 MCP

直接运行 stdio 服务（默认方式）：

.\.venv\Scripts\ads-help.exe serve

在 Codex 中注册本地 stdio MCP：

codex mcp add ads-help -- D:\Users\Administrator\Documents\GitHub\ads-help-mcp\.venv\Scripts\ads-help.exe serve
codex mcp list

Codex MCP CLI 语法参见官方 OpenAI 文档。 其他支持 stdio MCP 的客户端使用相同的 executable 和 serve 参数即可。

也可使用 Streamable HTTP 供同一局域网的另一台电脑连接。HTTP 默认仅监听本机； 需要局域网访问时，显式绑定所有网络接口：

.\.venv\Scripts\ads-help.exe serve --transport streamable-http --host 0.0.0.0 --port 8000

在运行服务的电脑上，以管理员身份在 Windows 防火墙中仅为“专用”网络放行端口：

New-NetFirewallRule -DisplayName "ads-help-mcp LAN" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000 -Profile Private

在另一台同一 Wi-Fi 的电脑上，将 <服务端局域网IP> 替换为运行服务电脑的 IPv4 地址：

codex mcp add ads-help --url http://<服务端局域网IP>:8000/mcp

HTTP 服务端电脑必须保持运行且不能休眠。此模式没有 Bearer Token、TLS 或 OAuth 鉴权， 仅适用于受信任的局域网；不要在公共 Wi-Fi、互联网或不可信网络中开放该端口。

公开工具：

• list_versions()
• list_categories(version=None)
• search_docs(query, version=None, category=None, n_results=8)
• get_ael_function(function_name, version=None)
• compare_versions(query, from_version, to_version, change_type=None, n_results=8)

检索结果始终回显请求版本、解析后的精确版本、分类、模块、逻辑路径、来源 URI、 章节和文本。版本、分类、索引或差异索引不可用时会返回结构化错误及准确修复命令。

接入 ADS2027 及后续版本

先发现远端目录并生成候选配置：

.\.venv\Scripts\ads-help.exe release discover --id 2027 --install-root /opt/eda/agilent/ADS2027

检查生成的 configs/releases/ads2027.toml，按实际安装补充 Python/AEL 示例目录， 然后执行：

.\.venv\Scripts\ads-help.exe build --release 2027
.\.venv\Scripts\ads-help.exe diff --from 2026-update1 --to 2027

Update 版本使用精确 ID，例如 2027-update1。发现器会检查 Help 根目录、统一 doc/python 和模块级 */python/docs 回退目录；如果发现 DITA、CHM、PDF 等未知 主文档格式，会停止并要求人工确认，不会静默跳过。

数据布局与 Git 策略

data/
├─ 2025/
│  ├─ raw/
│  ├─ processed/
│  ├─ manifests/
│  └─ index/{chroma,bm25.pkl,stats.json,index_manifest.json}
├─ 2026-update1/
└─ _comparisons/2025__2026-update1/

厂商原始资料、处理语料、ChromaDB、BM25、manifest、统计文件、embedding 模型、 虚拟环境和运行产物均不得提交 Git。新仓库保留筛选后的原项目代码演进历史，但没有 配置远端；配置新远端时不得复用 ADS2025_help 的远端 URL。

开发验证

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src
.\.venv\Scripts\python.exe -m compileall -q src

核心包采用浅层 src/ads_help_mcp 结构，公共对象通过 __all__ 显式导出。