# 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
  启动不会下载模型、处理语料或重建索引

```powershell
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
示例，然后在本地处理并建立隔离索引：

```powershell
.\.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
```

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

```powershell
.\.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 服务（默认方式）：

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

在 Codex 中注册本地 stdio MCP：

```powershell
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 文档](https://learn.chatgpt.com/docs/developer-commands#codex-mcp)。
其他支持 stdio MCP 的客户端使用相同的 executable 和 `serve` 参数即可。

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

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

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

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

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

```powershell
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 及后续版本

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

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

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

```powershell
.\.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 策略

```text
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。

## 开发验证

```powershell
.\.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__` 显式导出。