aura-argus 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.1.0 — 2026-10-21
+
+Initial public beta.
+
+### Added
+
+- Keyless source router: 18 entities / 34 official sources, with aliases and CN→EN term expansion.
+- Evidence contract: per-source passages, scores, URLs, `mode`, attempts, `tookMs`, `cached`.
+- CLI: `search`, `fetch`, `sources`, `doctor`, `serve`, `mcp`; JSON output and typed exit codes.
+- HTTP server: `/health`, `/sources`, `/search`, `/search/batch`, `/fetch`.
+- MCP stdio server: `search`, `search_batch`, `fetch`, `sources`; protocol negotiation and
+  client-agnostic `instructions`.
+- Node library exports: `search`, `searchBatch`, `fetchDocument`, `listEntities`, `matchEntity`,
+  `registryVersion`, `ArgusError`, `CODES`, `toErrorPayload`, `version`.
+- DSH provider adapter (`adapters/dsh`) and an optional MCP server entry.
+- Batch search with bounded concurrency (1–8), page cache, in-flight de-duplication, and a batch
+  budget (MCP 35 s, HTTP 45 s).
+- Retry policy: up to 3 attempts per source for network errors, timeouts, 408/425/429/5xx;
+  exponential backoff with jitter; `Retry-After` support; total budget.
+- `ALL_SOURCES_FAILED` error with per-source attempts (CLI exit 4, HTTP 502, MCP `isError`, DSH
+  provider error).
+- SSRF protection: private/loopback/link-local/metadata targets denied by default; DNS and
+  redirect re-checks; `--allow-private` opt-in.
+- `schema/tools.json` for function-calling agents and `openapi.json` for HTTP integrations.
+
+### Changed
+
+- The 360/Sogou web fallback is now **opt-in** (`--fallback` / `fallback: true`). Registry-only is
+  the default; unregistered questions return `mode: "none"`.
+- MCP instructions and tool descriptions are client-agnostic (no DSH-specific tool names).
+
+### Known limitations
+
+- Coverage is the registry. Unregistered entities return no evidence unless fallback is enabled.
+- No JavaScript rendering, login walls, CAPTCHA solving, or proxy pools.
+- Single-entity routing; multi-entity questions are not composed.
+- DNS rebinding and proxy environments are documented limitations (see `SECURITY.md`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+# AuraArgus
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 agent 的检索层。两个能力，替代传统的 search 与 fetch：
+
+- **search**：把问题路由到注册的官方源，抓回页面，返回**可引用的逐字段落**。
+- **fetch**：取回一个 URL，转成干净的 Markdown 文本。
+
+零 API key、零按次计费、默认只连官方页；Windows / macOS / Linux 同一份代码。
+
+## 为什么不是搜索引擎聚合器
+
+在大陆无代理的实测里，keyless SERP 的召回已经坏了：Bing 对无 cookie 请求返回首词/词典/导航式结果，百度约 30 次请求后跳验证码，DDG / Google 不可达。而**官方页本身可达，正文里就有答案**——失败的是 URL 发现，不是网络。
+
+所以 AuraArgus 不聚合 SERP。它维护一份「实体 → 官方源」注册表，把问题路由到正确的官方页，再抽段、给出处。先看一组 6 题的对照实验：
+
+| 方案 | 命中 |
+|---|---|
+| keyless 链接列表 | 3 / 12 |
+| keyless + 本地选段 | 4 / 12 |
+| 官方 Search API（付费） | 11 / 12 |
+| **AuraArgus** | **13 / 13** |
+
+覆盖评测（18 个实体、中英文、别名、未知实体）是 **31 题 / 141 项硬检查全部通过**；2 项 soft 兜底默认关闭（fallback 改为 opt-in），见 [RESULTS.md](RESULTS.md)。
+
+细节见 [RESULTS.md](RESULTS.md) 与 [POSITIONING.md](POSITIONING.md)。
+
+## 要求
+
+- Node.js **≥ 20**（用到内置 `fetch` / `AbortSignal.timeout`）
+- 零依赖，不需要 `npm install`
+- Windows / macOS / Linux
+
+## 安装
+
+```bash
+npm i -g aura-argus
+aura-argus version
+```
+
+或者直接从源码跑：
+
+```bash
+git clone <repo> && cd aura-argus
+node src/cli.mjs search "SearXNG 对 429 的冷却时间是多少秒？"
+```
+
+## 四种入口
+
+### 1. CLI
+
+```bash
+# 检索：返回证据（JSON）
+aura-argus search "SearXNG 对 429 的冷却时间是多少秒？"
+
+# 人眼可读
+aura-argus search "Tavily 一个 credit 多少钱？" --text
+
+# 取回一页：干净 Markdown
+aura-argus fetch https://docs.searxng.org/dev/search_api.html --max-chars 4000
+
+# 注册表与健康检查
+aura-argus sources
+aura-argus doctor
+```
+
+退出码：`0` 成功、`2` 无证据、`3` 参数错误、`4` 抓取失败、`130` 中断。
+
+### 2. 本地 HTTP（任何语言 / agent）
+
+```bash
+aura-argus serve --port 8787
+# {"ok":true,"url":"http://127.0.0.1:8787"}
+```
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/health` | 版本、源数量、uptime |
+| GET | `/sources` | 注册表 |
+| GET | `/search?q=&maxSources=` | 证据包 |
+| POST | `/search` | `{ "question": "...", "maxSources": 3 }` |
+| POST | `/search/batch` | `{ "questions": ["..."], "concurrency": 3 }` |
+| GET | `/fetch?url=&maxChars=` | 页面文本 |
+| POST | `/fetch` | `{ "url": "...", "maxChars": 20000 }` |
+
+```bash
+curl -s 'http://127.0.0.1:8787/search?q=SearXNG+429' | head -c 400
+curl -s 'http://127.0.0.1:8787/fetch?url=https%3A%2F%2Fdocs.searxng.org%2Fdev%2Fsearch_api.html'
+```
+
+默认只绑 `127.0.0.1`；`--token <t>` 后要求 `Authorization: Bearer <t>`。
+
+### 3. MCP stdio（任何 MCP 客户端）
+
+```bash
+aura-argus mcp
+```
+
+客户端配置（以 Claude Desktop / 任意 MCP host 为例）：
+
+```json
+{
+  "mcpServers": {
+    "aura-argus": {
+      "command": "npx",
+      "args": ["-y", "aura-argus", "mcp"]
+    }
+  }
+}
+```
+
+工具：`search(question, maxSources?)`、`search_batch(questions, concurrency?)`、`fetch(url, maxChars?)`、`sources()`。stdout 只写 JSON-RPC，不混日志。
+
+### 4. DSH（DeepSeek Harness）
+
+仓库自带 `adapters/dsh/index.mjs`。在 `~/.dsh/profiles/web/cordis.patch.yml` 里插入适配器，并把 web 的 provider 指过去：
+
+```yaml
+- insert:
+    - id: web-argus
+      name: 'E:/workspaces/aura-argus/adapters/dsh/index.mjs'   # 换成你的 checkout 路径
+      config:
+        maxSources: 3
+        maxChars: 20000
+        # marker: true   # 验证期打开：snippet 会以 [aura-argus] 开头
+
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: aura-argus
+    fetchProvider: aura-argus-http
+```
+
+重启 dsh web 后生效（运行中的进程不会热加载 patch）。验证：
+
+```bash
+dsh --profile web --dump-config | Select-String searchProvider   # 应显示 aura-argus
+node eval/verify-dsh.mjs --live                                  # 9/9
+aura-argus search "SearXNG 429" --json                           # 终端侧对照
+```
+
+服务端没有 `aura-argus` 时 DSH 会报 `WEB_PROVIDER_CONFIGURED_MISSING`，不会静默回落到计费路径。回滚：删掉 `web-argus` 段，把 `searchProvider` / `fetchProvider` 改回原值（如 `aura-keyless` / `http`），重启。
+
+**这替换的是 provider，不是工具。** `web_search` / `web_fetch` 仍是 `tool-web`，受它的契约限制：最多 4 个 query、合并成一个 sources 列表（丢失逐 query 归属）、只给 snippet（我们的 passages 被压成一条）、没有 `search_batch`、fetch 有它的 SSRF/重定向/大小规则。
+
+要拿回完整契约，把 AuraArgus 的 MCP server 挂进 DSH（profile patch 里已写入 `mcp-aura-argus`）：
+
+- 工具：`mcp__aura-argus__search` / `search_batch` / `fetch` / `sources`
+- 想强制走原生工具：给 `tool-web` 加 `disable: true`（先跑一轮确认 MCP 可用，再禁）
+- 内置工具已并发处理 1–4 个 query；MCP 的增量是逐 query 结果、批量上限 20、passages 与出处完整保留
+- MCP 的 `initialize.instructions` 会被 DSH 的 mcp-client 自动注入 systemPrompt（`mcp:aura-argus` 段），工具描述也会作为元数据进入模型——不需要再手写 AGENTS.md 规则
+
+### 5. Node 库
+
+```js
+import { search, searchBatch, fetchDocument } from 'aura-argus';
+
+const evidence = await search('SearXNG 对 429 的冷却时间是多少秒？');
+const batch = await searchBatch(['q1', 'q2', 'q3'], { concurrency: 3 });
+const page = await fetchDocument('https://docs.searxng.org/dev/search_api.html', { maxChars: 4000 });
+```
+
+## 契约
+
+### search
+
+```json
+{
+  "schemaVersion": 1,
+  "question": "SearXNG 对 429 的冷却时间是多少秒？",
+  "entity": "searxng",
+  "mode": "registry",
+  "evidence": [
+    {
+      "url": "https://docs.searxng.org/admin/settings/settings_search.html",
+      "title": "search: - SearXNG Documentation",
+      "site": "docs.searxng.org",
+      "passages": [{ "text": "… suspended_times: … SearxEngineTooManyRequests: 3600 …", "score": 15 }]
+    }
+  ],
+  "attempts": [{ "url": "…", "ok": true, "ms": 855, "passages": 6 }],
+  "tookMs": 1011,
+  "cached": false
+}
+```
+
+`mode` 取值：`registry`（注册表命中）、`web-fallback`（仅 `--fallback` 时出现的 360/搜狗兜底）、`none`（无证据）。
+
+### fetch
+
+```json
+{
+  "schemaVersion": 1,
+  "url": "https://docs.searxng.org/dev/search_api.html",
+  "finalUrl": "https://docs.searxng.org/dev/search_api.html",
+  "status": 200,
+  "title": "Search API - SearXNG Documentation",
+  "text": "# Search API\n\nSearXNG supports querying…",
+  "chars": 4000,
+  "truncated": true,
+  "contentType": "text/html; charset=utf-8",
+  "tookMs": 312
+}
+```
+
+### 错误码
+
+`BAD_URL`、`BAD_REQUEST`、`PRIVATE_ADDRESS`、`TOO_MANY_REDIRECTS`、`TIMEOUT`、`FETCH_FAILED`、`HTTP_ERROR`、`UNSUPPORTED_CONTENT_TYPE`、`TOO_LARGE`、`NO_ENTITY`、`NO_EVIDENCE`、`ALL_SOURCES_FAILED`。
+
+## 源注册表
+
+`src/registry.json`：**18 个实体 / 34 个源**，全部在 CN 直连下实测可达（`aura-argus doctor`）。
+
+加一个实体：
+
+```json
+"实体": {
+  "aliases": ["名字", "别名"],
+  "sources": [{ "url": "https://官方页", "title": "…", "covers": ["关键词"] }],
+  "discovery": { "type": "sitemap", "url": "https://…/sitemap.xml" }
+}
+```
+
+- `covers` 只用于排序；命中实体后默认抓该实体的全部源（上限 `--max-sources`）。
+- 所有源都失败时，若有 `discovery`（`sitemap` 或站点索引），再走一跳发现。
+- 默认 **registry-only**：未注册实体返回 `mode: "none"`；显式 `--fallback`（CLI）/`fallback: true`（HTTP/库）才走 360/搜狗，只返回链接 + 摘要，标 `mode: "web-fallback"`。
+
+## 跨平台
+
+- 无原生依赖、无 shell 调用、无平台路径写死；只用 `node:` 内置模块。
+- 缓存目录：Windows `%LOCALAPPDATA%\aura-argus\cache`，macOS/Linux `$XDG_CACHE_HOME/aura-argus` 或 `~/.cache/aura-argus`；可用 `AURA_ARGUS_CACHE_DIR` 覆盖。
+- CI 矩阵：`ubuntu / macos / windows × node 20 / 22 / 24`，只跑离线测试与 `npm pack --dry-run`。
+
+## 跨 agent
+
+MCP stdio 与 CLI 都在本地跑，不绑定 DSH：
+
+| agent | 接法 | 实测（2026-10-21） |
+|---|---|---|
+| Codex CLI 0.163 | `codex mcp add aura-argus -- node <abs>/cli.mjs mcp` | `mcp_tool_call` server=`aura-argus` tool=`search`，返回 3600 s + 官方 URL |
+| Hermes 0.21.3 | `hermes mcp add aura-argus --command node --args <abs>/cli.mjs mcp` | 4 tools discovered（1937 ms）；`-z` 明确走 MCP，返回 3600 s + URL |
+| ZCode（Electron） | `~/.zcode/cli/config.json` → `mcp.servers`（stdio） | 配置已加；当前 ZCode 进程早于配置，重启后才会拉起 MCP；CLI/skill 仍作兜底 |
+| Claude Desktop / Cursor / Cline | 标准 stdio：`npx -y aura-argus mcp` | 发布后用 MCP Inspector + 各客户端补测 |
+
+- Windows 下部分客户端要写 `cmd /c npx ...`；配置路径随客户端不同。
+- 任何能跑 shell 的 agent：`aura-argus search "<q>" --json`。
+
+## 失败与重试
+
+- `fetchRaw`：每个源最多 3 次尝试（`retries=2`），只重试网络错误、超时、408/425/429/5xx；其余 4xx 立即失败。
+- 退避：300 ms 起、指数 + 抖动，单次最多 3 s；尊重 `Retry-After`（上限 3 s）；总预算 `max(20 s, 2×timeout)`，到点即停。
+- 一次检索里所有源都失败 → 结果带 `error.code = ALL_SOURCES_FAILED` 和逐源 `attempts`（含 `tries`、`status`）：
+  - CLI 退出码 `4`；HTTP `/search` 返回 `502`；MCP `isError: true`；DSH provider 抛 `WEB_PROVIDER_ERROR`。
+- 批量有 budget：MCP 35 s、HTTP 45 s（CLI `--budget`），超时项标 `BATCH_BUDGET_EXCEEDED`，避免重试把一次工具调用拖过客户端 60 s 超时。
+- 不做跨源的二次重试、不做失败缓存/冷却；失败的下一次调用会重新尝试。
+
+## 安全边界
+
+- 默认拒绝 loopback / 私有网段 / link-local / 组播 / metadata：`127/8`、`10/8`、`172.16/12`、`192.168/16`、`169.254/16`、`::1`、`fc00::/7`、`fe80::/10` 等；DNS 解析后复查，重定向逐跳复检。
+- 显式 opt-in：CLI `--allow-private`，库 `allowPrivate: true`，HTTP `serve --allow-private`，MCP 启动时 `AURA_ARGUS_ALLOW_PRIVATE=1`。
+- 不绕登录/付费墙/验证码；无内置 key、无代理池、无遥测。
+- `serve` 默认绑 `127.0.0.1`；对外暴露时加 `--token`。
+
+## 边界
+
+- **覆盖率 = 注册表**。没收录的实体默认返回无证据；显式开启 fallback 才走网页兜底。
+- 不做 JS 渲染、不登登录墙、不绕验证码、不做代理池。
+- 低频、单机、只读抓取；对目标站点友好是最低要求。
+- 返回证据，不生成答案；答案由调用方的模型写。
+- `web-fallback` 是 opt-in，依赖 360/搜狗，可能被反爬；失败时明确报 `mode: "none"`。
+
+## 性能
+
+`npm run bench`（30 题，无缓存冷启动）：
+
+| 模式 | 总耗时 | 平均 |
+|---|---|---|
+| 串行 | 21.6 s | 721 ms/题 |
+| 批量（concurrency=3，冷） | 6.9 s | 230 ms/题 |
+| 批量（缓存填充） | 6.1 s | 202 ms/题 |
+| 批量（缓存命中） | ~1 ms | — |
+
+- **并发可调**：同一批 30 题，c=6 / c=8 实测约 3.5 s / 2.0 s（无空结果）；默认 3 是为了对官方站点礼貌，不是性能上限。
+- **同题多源并行**：一个问题的 2–3 个官方源同时抓，不再串行等待。
+- **页面缓存 + in-flight 去重**：批内同一 URL 只抓一次；TTL 10 min。
+- **结果缓存**：同一 query 15 min 内直接命中（`--no-cache` 关闭）。
+
+批量入口：
+
+```bash
+  echo '["q1","q2"]' | aura-argus search --batch [--concurrency 3] [--budget 45000]
+curl -X POST localhost:8787/search/batch -d '{"questions":["q1","q2"]}'
+```
+
+## 测试与评测
+
+```bash
+npm test          # 离线：51 个测试（解析 / 选段 / 注册表 / 缓存 / 批量 / 重试 / 私网拦截 / HTTP / MCP / DSH 适配器）
+npm run eval      # 联网：31 题 / 141 项硬检查（+2 项 soft 兜底默认关闭）
+npm run verify    # 联网：34 个源的可用性
+```
+
+## 文件
+
+| 路径 | 作用 |
+|---|---|
+| `src/cli.mjs` | CLI 入口 |
+| `src/core.mjs` | 公共 API |
+| `src/registry.json` | 实体 → 官方源（产品资产） |
+| `src/lib/router.mjs` | 实体匹配 → 抓取 → 选段 → 兜底 |
+| `src/lib/fetch.mjs` | URL 校验 / 限时 / 限大小 / 文档转换 |
+| `src/lib/extract.mjs` | 打分 + 邻行窗口 + 表格/列表块合并 |
+| `src/lib/server.mjs` | HTTP 服务 |
+| `src/lib/mcp.mjs` | MCP stdio |
+| `src/lib/cache.mjs` | 内存 + 磁盘缓存 |
+| `eval/` | 金标准问题、评测脚本、注册表检查 |
+| `test/` | 离线测试 |
+| `docs/integrations/` | Codex / Hermes / ZCode / Claude / Cursor / CLI / HTTP 接法 |
+| `schema/tools.json` | OpenAI / Anthropic function-calling 工具 schema |
+| `openapi.json` | HTTP API 的 OpenAPI 3.1 |
+| `SECURITY.md` | 安全模型、私网拦截、漏洞上报 |
+| `adapters/dsh/` | DSH provider 适配器 |
+| `POSITIONING.md` | 定位、市场对比、实验记录 |
+
+## License
+
+MIT

package/RESULTS.md

@@ -0,0 +1,114 @@
+# 结果（2026-10-21）
+
+环境：大陆直连、Clash 关闭（出口 `123.139.x`）。全部请求只到官方页；无 key、无 SERP、无代理、无按次计费。
+
+## 评测
+
+### 覆盖评测（31 题 / 141 项）
+
+`npm run eval`：**141 / 141 项硬检查全部通过**（另 2 项 soft：网页兜底）。覆盖 18 个实体、中英文、别名、未知实体；总耗时 **27.8 s**（无缓存、串行），证据 77,646 字符；单题最长 2.8 s。fallback 改为 opt-in 后，soft 的 2 项默认关闭；实测 360 跳 captcha、搜狗 403，0/2 不计入发布 gate。
+
+| 类别 | 题数 | 结果 |
+|---|---|---|
+| 注册实体事实（18 个实体） | 24 | 全过 |
+| 别名（深度求索 / nodejs / golang / k8s / 必应） | 5 | 全过 |
+| 未知实体（fallback off） | 1 | `entity:null` / `mode:none` |
+| 网页兜底（soft） | 1 | opt-in；本次 0/2（360 跳 captcha、搜狗 403） |
+
+### 对照实验（6 题，A/B/C/D）
+
+| 方案 | 材料 | 命中 |
+|---|---|---|
+| A · keyless 链接 | 10 条标题 + 摘要 | 3 / 12 |
+| B · keyless + 本地选段 | 逐字段落 | 4 / 12 |
+| C · 官方 Search API | 官方结果 | 11 / 12 |
+| **D · AuraArgus** | 官方源逐字段落 | **13 / 13** |
+
+## 失败与重试（2026-10-21）
+
+- `fetchRaw`：最多 3 次尝试；重试网络错误、超时、408/425/429/5xx，其余 4xx 不重试。
+- 退避 300 ms 起、指数 + 抖动；尊重 `Retry-After`（上限 3 s）；总预算 `max(20 s, 2×timeout)`。
+- 所有源失败：`error.code = ALL_SOURCES_FAILED` + 逐源 `attempts`（`tries` / `status`）；CLI 退出 4、HTTP 502、MCP `isError`、DSH provider 抛 `WEB_PROVIDER_ERROR`。
+- 一次全失败测试（mock fetch）：2 个源各 3 次尝试，结果正确标记，耗时约 1.6 s。
+- 批量 budget：MCP 35 s、HTTP 45 s；超时项标 `BATCH_BUDGET_EXCEEDED`，防止重试把一次工具调用拖过客户端 60 s 超时。
+
+## 安全边界（2026-10-21）
+
+- 默认拒绝 loopback / 私有网段 / link-local / 组播 / metadata；DNS 解析后复查，重定向逐跳复检。
+- opt-in：CLI `--allow-private`、HTTP `serve --allow-private`、库 `allowPrivate: true`、MCP `AURA_ARGUS_ALLOW_PRIVATE=1`。
+- 不绕登录/付费墙/验证码；无 key、无代理池、无遥测。
+- `serve` 默认绑 `127.0.0.1`，对外暴露需 `--token`。
+
+## 性能（`npm run bench`，30 题）
+
+| 模式 | 总耗时 | 平均 |
+|---|---|---|
+| 串行（冷） | 21.62 s | 721 ms/题 |
+| 批量 c=3（冷） | **6.89 s** | 230 ms/题 |
+| 批量 c=3（缓存填充） | 6.05 s | 202 ms/题 |
+| 批量 c=3（缓存命中） | ~1 ms | — |
+
+冷启动批量 **3.14×**；命中结果缓存后 <10 ms。证据数量在三种模式下一致（49 条来源），说明并行/缓存没有改变结果。
+
+并发上限 8：同一批 30 题在 **c=6 / c=8 下约 3.5 s / 2.0 s**（单独实测，仍无空结果）；默认 c=3 是礼貌值，不是性能上限。
+
+## 注册表
+
+`npm run verify`：**18 个实体 / 34 个源**，全部 200。
+
+覆盖：DeepSeek、SearXNG、Tavily、Google CSE、Bing、Python、Node.js（http/fs）、GitHub（REST/Actions）、MDN、React、Vue、Rust、Go、Docker、PostgreSQL、nginx、Kubernetes、Redis。
+
+## 测试
+
+`npm test`：**51 / 51** 通过（解析、块合并、选段、URL 校验、注册表结构、别名、缓存 TTL/磁盘往返、批量、重试/全失败、私网拦截/重定向复检、HTTP 服务、MCP 握手/协议协商/解析错误、DSH 适配器映射）。
+
+`npm run verify-dsh`：静态 **8/8**；`--live` **9/9**（含真检索）。DSH patch 已指向 `aura-argus` / `aura-argus-http`。
+
+## 打包与安装（2026-10-21）
+
+- `npm pack`：**34 files / 41.6 KB compressed / 126.6 KB unpacked**；含 `docs/integrations/`、`schema/tools.json`、`openapi.json`、`SECURITY.md`、`CHANGELOG.md`。
+- tarball 安装到临时 prefix：`aura-argus version` → `0.1.0`；MCP initialize/tools-list → 4 tools + `instructions`。
+- 安装目录清理后无进程/端口残留（仅按需 `serve`）。
+
+## 跨 agent（2026-10-21）
+
+| agent | 版本 | 接法 | 实测 |
+|---|---|---|---|
+| Codex CLI | 0.163.0-alpha.10.2 | `codex mcp add aura-argus -- node .../cli.mjs mcp` | `mcp_tool_call` server=`aura-argus` tool=`search`，返回 3600 s + 官方 URL |
+| Hermes | 0.21.3 | `hermes mcp add aura-argus --command node --args .../cli.mjs mcp` | 4 tools discovered（首测 1937 ms；新代码复测 3656 ms，通用描述）；`hermes -z` 走 MCP，返回 3600 s + URL |
+| ZCode | Electron | `~/.zcode/cli/config.json` → `mcp.servers`（stdio，`type:"stdio"`） | 配置已加；当前进程早于配置，重启后验证；CLI/skill 兜底 |
+
+## DSH 运行态（2026-10-21 重启后）
+
+- `dsh --profile web --dump-config` → `searchProvider: aura-argus` / `fetchProvider: aura-argus-http`
+- `web_search "SearXNG 对 429 的冷却时间是多少秒？"` → 来源 `docs.searxng.org`，snippet 是 600 字符的逐字段落（含 `formats : - html`），不是普通 SERP 摘要
+- `web_fetch https://docs.searxng.org/dev/search_api.html` → Markdown（`# Search API`，无导航条）
+- `node eval/verify-dsh.mjs --live` → 9/9（含 MCP server 插入检查）
+- MCP server 的 `initialize.instructions` 会被 `dsh-mcp-client` 注入 systemPrompt（`mcp:aura-argus`），工具描述也会作为元数据进入模型；`search_batch` 上限 20
+
+> 注：上面的 DSH 运行态是 20:41 那次重启的结果。22:xx 之后又改了 SSRF 默认拒绝、fallback 默认 opt-in、MCP 通用工具描述；**当前 DSH 进程仍是旧代码**，下次重启才加载。Codex/Hermes 每次调用重新拉起 MCP，已用新代码复测（Codex 无异常；Hermes 3656 ms / 4 tools）。
+
+## 交付形态
+
+| 入口 | 命令 / 用法 |
+|---|---|
+| CLI | `aura-argus search …` / `fetch` / `sources` / `doctor` / `serve` / `mcp` |
+| HTTP | `aura-argus serve --port 8787`（`/health` `/sources` `/search` `/search/batch` `/fetch`；`openapi.json`） |
+| MCP stdio | `aura-argus mcp`（tools: search / search_batch / fetch / sources） |
+| Node 库 | `import { search, searchBatch, fetchDocument } from 'aura-argus'` |
+| DSH | `adapters/dsh/index.mjs` + profile patch（`searchProvider: aura-argus` / `fetchProvider: aura-argus-http`） |
+
+## 这张表不能读出的四件事
+
+1. **覆盖率是天花板。** 31 题覆盖 18 个实体；没收录的实体默认返回无证据，显式 `--fallback` 才走 360/搜狗。
+2. **检查的是「事实是否出现在证据里」**，不是「agent 答得对」。C 的 QPS 错误（把 100 答成 5）说明官方索引也会选错源；证据段落 + 出处让调用方能核对。
+3. **registry 是手工资产。** 价值在数据（实体 → 官方源），不在算法；维护成本和覆盖范围是后续工程。
+4. **Google 走了 `.cn` 镜像。** 不是所有被墙的官方源都有镜像。
+
+## 复跑
+
+```bash
+npm test
+npm run eval
+npm run verify
+```

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security
+
+## Supported versions
+
+`0.1.x` is the current public beta line. Security fixes land on the latest `0.1.x`.
+
+## Reporting
+
+Use GitHub private vulnerability reporting (Security → Report a vulnerability) at
+<https://github.com/Ck-epsilon/aura-argus/security/advisories/new>. If that is unavailable,
+open an issue that describes the impact without including a working exploit or secrets.
+
+Please include: affected version, command/tool, expected vs actual behavior, and whether the
+target is local, private-network, or public. We aim to acknowledge within 7 days.
+
+## Security model
+
+AuraArgus is a local, read-only retrieval tool. It does not host a service, does not require an
+API key, and does not send telemetry.
+
+- **Network egress is user-initiated.** `search` only fetches URLs from the local registry (or an
+  explicitly discovered source); `fetch` accepts a URL from the caller.
+- **Private targets are denied by default.** Loopback, RFC1918, CGNAT, link-local, multicast,
+  documentation ranges, cloud metadata addresses, `localhost`, `fc00::/7`, `fe80::/10`, `::1`,
+  and IPv4-mapped private addresses are rejected. DNS is resolved before the request and every
+  redirect hop is re-checked.
+- **Opt-in escape hatch.** `--allow-private` / `allowPrivate: true` / `AURA_ARGUS_ALLOW_PRIVATE=1`
+  disables the private-target check. Only use it for a trusted local source; prompt injection can
+  abuse it if it is enabled by default.
+- **No bypass of access controls.** The tool does not log in, solve CAPTCHAs, bypass paywalls, or
+  rotate proxies. Users are responsible for complying with the target site's terms and robots
+  policy.
+- **HTTP server is local by default.** `serve` binds `127.0.0.1`. When binding to another host,
+  always set `--token`; the token is a bearer secret, not a substitute for network isolation.
+- **Cache is local.** Search results and pages are cached under the user cache directory; use
+  `--no-cache` to bypass the result cache.
+
+## Known limitations
+
+- DNS rebinding is mitigated by pre-resolution checks but not fully eliminated; a hostile DNS
+  server could change answers between the check and the request.
+- Node's built-in `fetch` does not honor `HTTP_PROXY` / `HTTPS_PROXY` automatically. Corporate
+  networks may need `NODE_EXTRA_CA_CERTS` or a custom dispatcher.
+- The 360/Sogou fallback is opt-in and scrapes public result pages; it is subject to anti-bot
+  blocking and may violate a target site's terms if used at scale.
+- `--allow-private` deliberately weakens SSRF protection; it should never be the default in a
+  multi-user deployment.

package/adapters/dsh/index.mjs

@@ -0,0 +1,83 @@
+// DSH 适配器：把 AuraArgus 注册成 ctx.web 的 search / fetch provider。
+// 不依赖 DSH 的源码：只用到 ctx.web.registerSearchProvider / registerFetchProvider。
+import { search, fetchDocument, version } from '../../src/core.mjs';
+
+export const name = 'aura-argus-dsh';
+export const inject = ['web'];
+export const SEARCH_ID = 'aura-argus';
+export const FETCH_ID = 'aura-argus-http';
+
+function providerError(message, code = 'WEB_PROVIDER_ERROR') {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * 构建两个 provider。注入 searchImpl/fetchImpl 便于离线测试。
+ */
+export function createProviders({ searchImpl = search, fetchImpl = fetchDocument, config = {} } = {}) {
+  const maxSources = Math.max(1, Math.min(6, Number(config.maxSources ?? 3)));
+  const maxChars = Math.max(100, Number(config.maxChars ?? 20_000));
+  const marker = config.marker === true;
+  const allowPrivate = config.allowPrivate === true;
+
+  const searchProvider = {
+    id: SEARCH_ID,
+    available() { return true; },
+    async search(request, signal) {
+      if (signal?.aborted) throw providerError('search aborted', 'WEB_ABORTED');
+      const limit = Math.max(1, Math.min(maxSources, Number(request?.maxResults ?? maxSources)));
+      try {
+        const result = await searchImpl(request.query, { maxSources: limit, cache: config.cache !== false, fallback: config.fallback === true });
+        if (result.error) throw providerError(`aura-argus search failed: ${result.error.code} (${result.error.attempts ?? 0} sources)`);
+        const sources = (result.evidence || []).map((entry) => {
+          const raw = entry.passages?.[0]?.text || '';
+          const snippet = marker && raw ? `[aura-argus] ${raw}` : raw;
+          return {
+            url: entry.url,
+            ...(entry.title ? { title: entry.title } : {}),
+            ...(snippet ? { snippet: snippet.slice(0, 600) } : {}),
+          };
+        });
+        return { sources, truncated: false };
+      } catch (error) {
+        throw providerError(`aura-argus search failed: ${error?.message || error}`);
+      }
+    },
+  };
+
+  const fetchProvider = {
+    id: FETCH_ID,
+    available() { return true; },
+    async fetch(request, signal) {
+      if (signal?.aborted) throw providerError('fetch aborted', 'WEB_ABORTED');
+      try {
+        const doc = await fetchImpl(request.url, { maxChars, allowPrivate });
+        return {
+          url: doc.finalUrl || doc.url,
+          statusCode: doc.status,
+          body: { kind: 'text', content: doc.text },
+          truncated: Boolean(doc.truncated),
+        };
+      } catch (error) {
+        // 与 DSH 的约定一致：非 2xx 是结果，不是异常。
+        if (error?.code === 'HTTP_ERROR' && error?.details?.status) {
+          return { url: request.url, statusCode: error.details.status, body: { kind: 'text', content: '' }, truncated: false };
+        }
+        throw providerError(`aura-argus fetch failed: ${error?.message || error}`);
+      }
+    },
+  };
+
+  return { searchProvider, fetchProvider };
+}
+
+export function apply(ctx, config = {}) {
+  const { searchProvider, fetchProvider } = createProviders({ config });
+  ctx.web.registerSearchProvider(searchProvider);
+  ctx.web.registerFetchProvider(fetchProvider);
+  if (config.debug) {
+    process.stderr.write(`[aura-argus] registered ${SEARCH_ID} + ${FETCH_ID} (v${version})\n`);
+  }
+}