axi-cli 0.0.6__tar.gz → 0.0.8__tar.gz

{axi_cli-0.0.6 → axi_cli-0.0.8}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.0.8] - 2026-07-07
+
+### Added
+- `axi.env(name, default=None)`：native 工具的统一变量读取入口。CLI / stdio 形态下读进程环境变量；经 `axi mcp --transport http` 导出为共享 HTTP server 时，每个客户端通过 `Axi-*` 请求头传入的变量按请求隔离、优先于进程环境变量（`Axi-Foo-Bar` → `FOO_BAR`：去前缀、`-`→`_`、转大写）
+- `mcpServers` 新增 `headers` 字段：连接需认证的 HTTP MCP server 时随每个请求附带（如 `Authorization: Bearer xxx`）；stdio 型凭据继续走 `env`，两种 transport 各用各的通道
+
+### Fixed
+- MCP 连接建立中途失败（如 `initialize` 报错、远端拒绝认证）不再泄漏已打开的资源（httpx 客户端 / 流 / session）：改用 `AsyncExitStack.pop_all()` 惯用法，全部成功才移交所有权，失败由 with 自动清理
+
+## [0.0.7] - 2026-07-04
+
+### Added
+- `axi doctor` 自检命令：一次性检查配置、daemon、MCP server 连接、embedding、native 工具来源；配置了 MCP server 时拉起 daemon 验证连接，有问题以非零码退出并在 `issues` 里给出可执行的下一步。`native_tools.from_entry_points` 列出所有经 Python entry_points 自动注入的工具及来源模块，便于审计
+- daemon 请求超时可配置：`daemon.requestTimeout`（默认 120 秒，原硬编码 30 秒）+ `AXI_REQUEST_TIMEOUT` 环境变量（优先），超时信息指向调高方式
+- native 工具加载记录来源日志（模块 / entry_point + server + 工具名），便于审计自动注入
+
+### Fixed
+- 并发多个 axi 进程同时发现 daemon 未运行会各自拉起、互相 unlink socket / 覆盖 PID：改用启动文件锁串行化，只有持锁进程 spawn，其余复查后复用
+- CLI `--key value` 解析忽略工具 schema，把 string 字段的 `false` / `42` / `null` 误转成布尔 / 数字 / 空值：现在按目标字段类型决定是否 JSON 解析（string 字段保留原文，其余照常解析）
+
+### Changed
+- **Breaking**：搜索结果移除 `score` 字段——native 与 MCP 来自两套独立索引、各自归一化，跨源分数不可比，暴露只会误导 Agent；结果按相关性降序返回，顺序本身即信号
+- 搜索栈（bm25s / jieba / numpy）延迟到首次 `search` / `grep` 才 import，`describe` / `run` / `list` 不再付这笔冷启动成本；各引擎按工具集版本号独立重建
+- embedding 缓存从当前目录 `.axi/cache/embeddings.json` 移到 `~/.axi/cache/<配置路径哈希>.json`，按配置隔离、不再依赖 cwd
+- `allowed_types` / `server_tool_counts` 抽为公共函数，消除 cli / daemon / registry 间的重复实现
+
 ## [0.0.6] - 2026-07-03
 
 ### Added

{axi_cli-0.0.6 → axi_cli-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axi-cli
-Version: 0.0.6
+Version: 0.0.8
 Summary: Agent eXecution Interface - unified tool layer for AI Agents
 Requires-Python: >=3.12
 Requires-Dist: bm25s>=0.3.3
@@ -97,6 +97,7 @@ axi run jina/jina_search --query "hello world" --count 3
 | `axi describe <tool>` | 查看工具完整 schema |
 | `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
 | `axi mcp` | 将 axi 工具导出为 MCP server（stdio / HTTP） |
+| `axi doctor` | 自检：配置、daemon、MCP 连接、embedding、native 工具来源；有问题非零退出 |
 | `axi daemon start` | 手动启动 daemon（通常无需手动，CLI 会自动拉起） |
 | `axi daemon status` | 查看 daemon 状态（PID、运行时长、空闲时长、工具数量等） |
 | `axi daemon stop` | 手动停止 daemon |
@@ -169,7 +170,7 @@ axi 提供两种搜索方式：
 - **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
 - **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
 
-搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+结果按相关性排序返回，顺序本身即信号（不含分数：native 与 MCP 来自两套索引、分数不可比）。
 
 ## Daemon 模式
 

{axi_cli-0.0.6 → axi_cli-0.0.8}/README.md

@@ -80,6 +80,7 @@ axi run jina/jina_search --query "hello world" --count 3
 | `axi describe <tool>` | 查看工具完整 schema |
 | `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
 | `axi mcp` | 将 axi 工具导出为 MCP server（stdio / HTTP） |
+| `axi doctor` | 自检：配置、daemon、MCP 连接、embedding、native 工具来源；有问题非零退出 |
 | `axi daemon start` | 手动启动 daemon（通常无需手动，CLI 会自动拉起） |
 | `axi daemon status` | 查看 daemon 状态（PID、运行时长、空闲时长、工具数量等） |
 | `axi daemon stop` | 手动停止 daemon |
@@ -152,7 +153,7 @@ axi 提供两种搜索方式：
 - **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
 - **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
 
-搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+结果按相关性排序返回，顺序本身即信号（不含分数：native 与 MCP 来自两套索引、分数不可比）。
 
 ## Daemon 模式
 

{axi_cli-0.0.6 → axi_cli-0.0.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axi-cli"
-version = "0.0.6"
+version = "0.0.8"
 description = "Agent eXecution Interface - unified tool layer for AI Agents"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -45,3 +45,7 @@ dev = [
     "pytest-asyncio>=1.3.0",
     "ruff>=0.15.8",
 ]
+
+[tool.pytest.ini_options]
+# 只从 tests/ 收集，隔离本地 scratch 的 test/（已 gitignore，不随包分发）
+testpaths = ["tests"]

{axi_cli-0.0.6 → axi_cli-0.0.8}/skills/axi-creator/SKILL.md

@@ -64,6 +64,21 @@ def get_can_data(
 - 复杂输入用 `BaseModel` 嵌套；axi 会把它展开成 object schema
 - **填 `output_example`**：MCP 协议没有 output schema，原生工具是 axi 独有的优势——Agent 能在 `axi describe` 里直接看到返回形状，不用试跑一遍
 
+### 凭据与配置变量：用 `axi.env`，别用 `os.environ`
+
+工具里需要 API Key 等变量时，一律通过 `axi.env(name, default=None)` 读取：
+
+```python
+import axi
+
+@tool(description="调用上游 API")
+def call_api(query: str) -> dict:
+    key = axi.env("API_KEY")   # CLI/stdio 下读环境变量；HTTP 导出时读客户端 Axi-* header
+    ...
+```
+
+CLI 和 stdio 形态下它就是环境变量；但当工具经 `axi mcp --transport http` 导出为共享 HTTP server 时，每个客户端可通过 `Axi-*` 请求头传自己的变量（见下文"导出为 MCP server"），`axi.env` 会优先取当前请求的值。直接 `os.environ` 的工具在 HTTP 形态下拿不到客户端变量。
+
 ### 注册：两种方式，二选一
 
 **方式 1：本项目内用 → `axi.json` 的 `nativeTools`**
@@ -104,13 +119,14 @@ smartlink = "smartlink_axi.tools"
       "env": {"API_KEY": "xxx"}
     },
     "remote": {
-      "url": "http://localhost:8000/mcp"            // 或 HTTP streaming
+      "url": "http://localhost:8000/mcp",           // 或 HTTP streaming
+      "headers": {"Authorization": "Bearer xxx"}    // 可选：远端要求认证时随每个请求附带
     }
   }
 }
 ```
 
-`command` / `url` 二选一。保存后直接 `axi list` 就能看到新工具——daemon 会按需自动拉起连接。
+`command` / `url` 二选一；凭据传递按 transport 选字段——stdio 用 `env`（注入子进程环境），HTTP 用 `headers`（附到每个请求）。保存后直接 `axi list` 就能看到新工具——daemon 会按需自动拉起连接。
 
 ---
 
@@ -125,7 +141,7 @@ axi describe <server>/<tool>                # input_schema 字段、类型、req
 axi run <server>/<tool> --key value          # 跑通，返回 {"status":"success","data":...}
 ```
 
-**搜不到比跑不通更常见**——description 太短、只写了类名或方法名都会导致 BM25/Embedding 召回差。看着 `axi search` 返回列表里有没有你的工具，score 是不是高位。
+**搜不到比跑不通更常见**——description 太短、只写了类名或方法名都会导致 BM25/Embedding 召回差。用几个真实查询跑 `axi search`，看你的工具有没有出现、排得够不够靠前。
 
 ---
 
@@ -155,6 +171,23 @@ axi mcp --server a,b --transport http --port 8321    # HTTP 长驻服务
 }
 ```
 
+### HTTP 形态下给每个客户端传变量：`Axi-*` header
+
+stdio 是一客户端一进程，变量走 `env` 即可；HTTP 是共享进程，进程环境变量在启动时定死，**每个客户端的变量改走请求头**。约定：`Axi-<名字>` 映射为变量名（去前缀、`-`→`_`、转大写），工具内用 `axi.env` 读取，请求级值优先于进程环境变量：
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "url": "http://your-host:8321/mcp",
+      "headers": { "Axi-API-KEY": "sk_xxx", "Axi-REGION": "cn" }
+    }
+  }
+}
+```
+
+工具里 `axi.env("API_KEY")` 即得 `sk_xxx`，不同客户端互不可见。注意：这解决的是"客户端带变量进来"，不是服务端准入控制——公网暴露时另需网关层鉴权。
+
 ---
 
 ## 反模式
@@ -163,7 +196,7 @@ axi mcp --server a,b --transport http --port 8321    # HTTP 长驻服务
 - 所有参数都写 `str` — 失去类型约束和枚举提示，Agent 要靠 describe 里的自然语言猜
 - `description` 只写一个词（"搜索"、"查询"）— BM25 召回差、Embedding 语义稀薄
 - 返回不稳定结构（同一工具有时返 list 有时返 dict）— 下游 Agent 没法写聚合逻辑
-- 把敏感配置（API Key）硬编码在 `@tool` 函数里 — 走环境变量或 `mcpServers[...].env`
+- 把敏感配置（API Key）硬编码在 `@tool` 函数里 — 用 `axi.env` 读取（MCP server 的凭据走 `mcpServers[...].env` / `headers`）
 - entry_points 的 value 写成文件路径 `"pkg/tools.py"` — 必须是可 import 的模块路径 `"pkg.tools"`
 
 ---

{axi_cli-0.0.6 → axi_cli-0.0.8}/skills/axi-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: axi-use
-description: 通过 `axi` CLI（或在 Python 中使用 `from axi import tool`）发现并调用工具。当任务需要执行外部工具（当前拥有plane任务管理工具）请使用此skill。核心工作流程为：`axi search <query>` → `axi describe <tool>` → `axi run <tool> --key value`；当任务涉及多次调用之间的循环、聚合或后处理时，请优先使用 Python 进行处理。
+description: 通过 `axi` CLI（或在 Python 中使用 `from axi import tool`）发现并调用工具。当任务需要执行外部工具（当前拥有<changeme>）请使用此skill。核心工作流程为：`axi search <query>` → `axi describe <tool>` → `axi run <tool> --key value`；当任务涉及多次调用之间的循环、聚合或后处理时，请优先使用 Python 进行处理。
 ---
 
 # axi — Agent 使用手册
@@ -28,8 +28,9 @@ axi 是当前环境里的工具调用层。有工具需求时，**先 `axi searc
 
 ```bash
 axi search "web" --top-k 3
-# [{"name":"jina/jina_search","description":"Search the web. ...","source":"mcp","score":1.0},
-#  {"name":"jina/jina_reader","description":"Read and extract content from web page.","source":"mcp","score":0.92}]
+# [{"name":"jina/jina_search","description":"Search the web. ...","source":"mcp"},
+#  {"name":"jina/jina_reader","description":"Read and extract content from web page.","source":"mcp"}]
+# 结果按相关性排序（越靠前越相关），不含分数
 
 axi grep "^jina/" --limit 5
 # 精确列出 jina server 下所有工具

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/__init__.py

@@ -4,9 +4,10 @@ import logging
 from typing import Any, Callable
 
 from axi.cli import get_executor, get_registry
+from axi.context import env
 from axi.providers.native import register_tool
 
-__all__ = ["tool"]
+__all__ = ["tool", "env"]
 
 # 包级 logger：各子模块通过 logging.getLogger(__name__) 自动继承
 _logger = logging.getLogger("axi")

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/cli.py

@@ -2,13 +2,12 @@
 
 import json
 import logging
-from collections import Counter
 from enum import Enum
 
 import typer
 from pydantic import BaseModel
 
-from axi.config import app_config
+from axi.config import CONFIG_PATH, app_config
 from axi.daemon.client import (
     LOG_PATH,
     daemon_request,
@@ -18,7 +17,7 @@ from axi.daemon.client import (
 )
 from axi.daemon.protocol import DaemonRequest
 from axi.executor import Executor
-from axi.models import RunResult, SearchResult
+from axi.models import RunResult, SearchResult, allowed_types
 from axi.registry import (
     AmbiguousToolError,
     Registry,
@@ -128,16 +127,10 @@ def daemon_status() -> None:
         _output_json({"status": "error", "error": resp.error})
         raise typer.Exit(code=1)
 
-    data = resp.data
-    # 原生工具按 server 统计
-    native_server_tools = dict(
-        Counter(meta.server or "unknown" for meta in _registry.list_all())
-    )
-
     result = {
         "status": "running",
-        **data,
-        "native_tools": native_server_tools,
+        **resp.data,
+        "native_tools": _registry.server_tool_counts(),
     }
     _output_json(result)
 
@@ -159,9 +152,9 @@ def _search_and_merge(
     elif resp.status == "error":
         logger.warning("Daemon search failed: %s", resp.error)
 
-    combined = [r.model_dump(exclude_none=True) for r in local_results] + (
-        mcp_results or []
-    )
+    # native（本地 registry）与 MCP（daemon）是两套独立索引，分数不可比，
+    # 无法跨源真正排序；各自已取回 top_k，直接并列拼接（本地在前）。
+    combined = [r.model_dump() for r in local_results] + mcp_results
     typer.echo(json.dumps(combined, ensure_ascii=False))
 
 
@@ -286,6 +279,14 @@ def _resolve_tool(name: str) -> dict:
     return {"error": resp.error or f"Tool not found: {name}"}
 
 
+def _daemon_input_schema(tool_name: str) -> dict:
+    """从 daemon 取 MCP 工具的 input_schema；取不到返回 {}（解析退回 JSON 猜类型）。"""
+    resp = daemon_request(DaemonRequest(method="describe", tool_name=tool_name))
+    if resp.status == "success" and isinstance(resp.data, dict):
+        return resp.data.get("input_schema") or {}
+    return {}
+
+
 @app.command()
 def describe(
     tool_name: str = typer.Argument(help="工具完整名称（逗号分隔多个）"),
@@ -319,25 +320,32 @@ def run(
 
     json_str, args = _extract_option(args, "--json", "-j")
 
+    # 先解析工具一次：本地命中 → 原生（进程内执行，schema 就在 meta 上）；
+    # 未命中 → 走 daemon（MCP）。避免解析参数和执行各 resolve 一遍。
+    try:
+        meta = _registry.resolve(tool_name)
+    except AmbiguousToolError as e:
+        _output_json({"error": str(e)})
+        raise typer.Exit(code=1)
+    except ToolNotFoundError:
+        meta = None
+
     if json_str:
         try:
             parsed = json.loads(json_str)
         except json.JSONDecodeError as e:
             _output_json(RunResult.fail(f"Invalid JSON argument: {e}"))
             raise typer.Exit(code=1)
+    elif not args:
+        parsed = {}
     else:
-        parsed = _parse_params(args)
+        # 按目标 schema 解析 --key value（string 字段保留原文）；MCP schema 问 daemon
+        schema = meta.input_schema if meta else _daemon_input_schema(tool_name)
+        parsed = _parse_params(args, schema)
 
-    try:
-        meta = _registry.resolve(tool_name)
-        result = _executor.run(meta.full_name, parsed)
-        _output_json(result)
+    if meta is not None:
+        _output_json(_executor.run(meta.full_name, parsed))
         return
-    except AmbiguousToolError as e:
-        _output_json({"error": str(e)})
-        raise typer.Exit(code=1)
-    except ToolNotFoundError:
-        pass  # 本地未找到，继续尝试 daemon
 
     resp = daemon_request(
         DaemonRequest(method="call_tool", tool_name=tool_name, params=parsed)
@@ -380,6 +388,98 @@ def mcp_command(
     )
 
 
+@app.command()
+def doctor() -> None:
+    """自检：配置、daemon、MCP 连接、embedding、native 工具来源。
+
+    有问题时以非零码退出并在 ``issues`` 里给出可执行的下一步。
+    配置了 MCP server 时会拉起 daemon 以验证连接。
+    """
+    import importlib.metadata
+
+    from axi.providers.native import NATIVE_TOOLS_ENTRY_POINT_GROUP
+
+    issues: list[str] = []
+
+    # native 工具及其来源（entry_points 自动发现 = 任何已装包都可能注入工具，需可见）
+    try:
+        eps = list(
+            importlib.metadata.entry_points(group=NATIVE_TOOLS_ENTRY_POINT_GROUP)
+        )
+    except Exception:
+        eps = []
+    server_counts = _registry.server_tool_counts()
+    native = {
+        "total": sum(server_counts.values()),
+        "servers": server_counts,
+        "from_config": [e.module for e in app_config.native_tools],
+        "from_entry_points": [{"name": ep.name, "value": ep.value} for ep in eps],
+    }
+
+    # embedding
+    emb = app_config.search.embedding
+    if emb.provider:
+        embedding = {
+            "provider": emb.provider,
+            "api_key": "present" if emb.api_key else "missing",
+            "model": emb.model,
+        }
+        if not emb.api_key:
+            env_name = "JINA_API_KEY" if emb.provider == "jina" else "OPENAI_API_KEY"
+            issues.append(
+                f"Embedding provider '{emb.provider}' set but no API key. Put it in "
+                f"axi.json search.embedding.apiKey or the {env_name} env var."
+            )
+    else:
+        embedding = {"provider": None, "note": "BM25-only, no semantic search"}
+
+    # daemon + MCP 连接（仅在配置了 MCP server 时拉起 daemon 验证）
+    configured = set(app_config.mcp_servers)
+    mcp_servers: list[dict] = []
+    if configured:
+        resp = daemon_request(DaemonRequest(method="status"))
+        if resp.status == "success":
+            connected = resp.data.get("server_tools", {})
+            daemon = {
+                "running": True,
+                "pid": resp.data.get("pid"),
+                "uptime_seconds": resp.data.get("uptime_seconds"),
+            }
+            for name in sorted(configured):
+                if name in connected:
+                    mcp_servers.append(
+                        {
+                            "server": name,
+                            "status": "connected",
+                            "tools": connected[name],
+                        }
+                    )
+                else:
+                    mcp_servers.append({"server": name, "status": "not_connected"})
+                    issues.append(
+                        f"MCP server '{name}' configured but not connected. "
+                        f"Check daemon log: {LOG_PATH}"
+                    )
+        else:
+            daemon = {"running": False, "error": resp.error}
+            issues.append(f"Daemon unavailable: {resp.error}. Check log: {LOG_PATH}")
+    else:
+        daemon = {"running": is_daemon_running()}
+
+    report = {
+        "ok": not issues,
+        "config": {"path": str(CONFIG_PATH), "exists": CONFIG_PATH.exists()},
+        "daemon": daemon,
+        "native_tools": native,
+        "mcp_servers": mcp_servers,
+        "embedding": embedding,
+        "issues": issues,
+    }
+    _output_json(report)
+    if issues:
+        raise typer.Exit(code=1)
+
+
 # ── 参数解析辅助函数 ──────────────────────────────────────────────
 
 
@@ -397,7 +497,33 @@ def _extract_option(args: list[str], *names: str) -> tuple[str | None, list[str]
     return value, remaining
 
 
-def _parse_params(params: list[str]) -> dict:
+def _schema_field_types(schema: dict, key: str) -> set[str]:
+    """取字段在 schema 里声明的类型集合；字段不存在或无 schema 返回空集。"""
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        return set()
+    prop = props.get(key)
+    return allowed_types(prop) if isinstance(prop, dict) else set()
+
+
+def _coerce_cli_value(key: str, value: str, schema: dict) -> object:
+    """按目标字段类型决定是否 JSON 解析。
+
+    字段声明为 string → 原样保留，避免 ``true``/``42``/``null`` 被解析成
+    非字符串类型（``--title false`` 应是字符串 "false"）。其余（含未知字段、
+    无 schema）尝试 JSON 解析，让 ``--count 42``→42、``--flag true``→True、
+    ``--data {...}``→dict 正常工作，失败落回原字符串。
+    """
+    if "string" in _schema_field_types(schema, key):
+        return value
+    try:
+        return json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        return value
+
+
+def _parse_params(params: list[str], schema: dict | None = None) -> dict:
+    schema = schema or {}
     parsed: dict = {}
     i = 0
     while i < len(params):
@@ -405,11 +531,7 @@ def _parse_params(params: list[str]) -> dict:
         if arg.startswith("--"):
             key = arg[2:]
             if i + 1 < len(params) and not params[i + 1].startswith("--"):
-                value = params[i + 1]
-                try:
-                    parsed[key] = json.loads(value)
-                except (json.JSONDecodeError, ValueError):
-                    parsed[key] = value
+                parsed[key] = _coerce_cli_value(key, params[i + 1], schema)
                 i += 2
             else:
                 parsed[key] = True

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/config.py

@@ -1,5 +1,6 @@
 """axi 配置中心：Pydantic 模型化，统一加载 axi.json，全局共享。"""
 
+import hashlib
 import json
 import logging
 import os
@@ -10,9 +11,13 @@ from pydantic import BaseModel, Field, model_validator
 
 logger = logging.getLogger(__name__)
 
+AXI_HOME = Path("~/.axi").expanduser()
 CONFIG_PATH = (
-    Path(os.environ.get("AXI_CONFIG", "~/.axi/axi.json")).expanduser().resolve()
+    Path(os.environ.get("AXI_CONFIG", AXI_HOME / "axi.json")).expanduser().resolve()
 )
+# 每份配置的隔离键：daemon socket/pid/log 与 embedding 缓存都按它分目录，
+# 多项目（多份 AXI_CONFIG）互不干扰。
+CONFIG_HASH = hashlib.sha256(str(CONFIG_PATH).encode()).hexdigest()[:12]
 
 
 # ── 子配置模型 ──────────────────────────────────────────────
@@ -77,6 +82,24 @@ class DaemonConfig(BaseModel):
     idle_timeout_minutes: int = Field(
         default=30, alias="idleTimeoutMinutes", description="空闲自动关闭（分钟）"
     )
+    request_timeout: float = Field(
+        default=120,
+        alias="requestTimeout",
+        description="CLI 等待 daemon 单个请求的超时（秒），含工具调用",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def override_with_env(cls, values: dict) -> dict:
+        # 环境变量 AXI_REQUEST_TIMEOUT 优先于 axi.json（长工具调用可临时调高）
+        if isinstance(values, dict):
+            env = os.environ.get("AXI_REQUEST_TIMEOUT")
+            if env:
+                try:
+                    values["requestTimeout"] = float(env)
+                except ValueError:
+                    logger.warning("Ignoring invalid AXI_REQUEST_TIMEOUT=%r", env)
+        return values
 
 
 class MCPServerConfig(BaseModel):
@@ -86,6 +109,7 @@ class MCPServerConfig(BaseModel):
     args: list[str] = Field(default_factory=list)
     env: dict[str, str] | None = None
     url: str | None = None
+    headers: dict[str, str] | None = None
 
 
 class NativeToolEntry(BaseModel):

axi_cli-0.0.8/src/axi/context.py

@@ -0,0 +1,36 @@
+"""请求级变量：native 工具的统一变量读取入口。
+
+stdio / CLI 形态下变量来自进程环境变量；HTTP MCP 形态下 server 是共享进程，
+每个客户端的变量通过 ``Axi-*`` header 随请求传入，按请求隔离。
+"""
+
+import os
+from collections.abc import Mapping
+from contextvars import ContextVar
+
+_request_env: ContextVar[dict[str, str]] = ContextVar("axi_request_env", default={})
+
+_ENV_HEADER_PREFIX = "axi-"
+
+
+def set_request_env(headers: Mapping[str, str] | None) -> None:
+    """从 ``Axi-*`` header 提取当前请求的变量：``Axi-Foo-Bar`` → ``FOO_BAR``。
+
+    由 mcp_serve 在每次 native 工具调用前调用；``None``（stdio 无请求）置空。
+    ASGI 规范保证 header 名已小写。
+    """
+    _request_env.set(
+        {
+            name.removeprefix(_ENV_HEADER_PREFIX).replace("-", "_").upper(): value
+            for name, value in headers.items()
+            if name.startswith(_ENV_HEADER_PREFIX)
+        }
+        if headers
+        else {}
+    )
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    """读取变量：请求级（HTTP header）优先，其次进程环境变量。"""
+    value = _request_env.get().get(name)
+    return value if value is not None else os.environ.get(name, default)

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/daemon/client.py

@@ -1,14 +1,16 @@
 """daemon 客户端：CLI 侧通过 Unix socket 与 daemon 通信。"""
 
 import asyncio
+import fcntl
 import logging
 import os
 import subprocess
 import sys
 import time
 
-from axi.config import CONFIG_PATH
+from axi.config import CONFIG_PATH, app_config
 from axi.daemon.protocol import (
+    LOCK_PATH,
     LOG_PATH,
     SOCKET_DIR,
     SOCKET_PATH,
@@ -21,7 +23,6 @@ logger = logging.getLogger(__name__)
 
 _DAEMON_START_POLL_RETRIES = 30
 _DAEMON_START_POLL_INTERVAL = 0.1  # seconds
-_DAEMON_REQUEST_TIMEOUT = 30  # seconds
 
 
 def is_daemon_running() -> bool:
@@ -38,13 +39,8 @@ def is_daemon_running() -> bool:
         return False
 
 
-def ensure_daemon() -> bool:
-    """确保 daemon 已启动。未运行时自动启动，返回是否就绪。"""
-    if is_daemon_running():
-        return True
-
-    os.makedirs(SOCKET_DIR, exist_ok=True)
-
+def _spawn_and_wait() -> bool:
+    """拉起 daemon 子进程并轮询直到就绪。调用方需持有启动锁。"""
     with open(LOG_PATH, "a") as log_file:
         subprocess.Popen(
             [sys.executable, "-m", "axi.daemon.server"],
@@ -62,6 +58,26 @@ def ensure_daemon() -> bool:
     return False
 
 
+def ensure_daemon() -> bool:
+    """确保 daemon 已启动。未运行时自动启动，返回是否就绪。
+
+    并行的多个 axi 进程可能同时发现 daemon 未运行。用文件锁串行化启动：
+    只有拿到锁的进程 spawn，其余进程阻塞在锁上，拿到锁后复查发现已就绪即返回。
+    否则会多进程各拉起一个 daemon、互相 unlink socket、覆盖 PID 文件。
+    """
+    if is_daemon_running():
+        return True
+
+    os.makedirs(SOCKET_DIR, exist_ok=True)
+
+    with open(LOCK_PATH, "w") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        # 锁内复查：可能刚才另一个进程已经把 daemon 拉起来了
+        if is_daemon_running():
+            return True
+        return _spawn_and_wait()
+
+
 def send_request(req: DaemonRequest) -> DaemonResponse:
     """向 daemon 发送请求并获取响应。"""
     return asyncio.run(_send(req))
@@ -86,16 +102,16 @@ async def _send(req: DaemonRequest) -> DaemonResponse:
         writer.write(req.model_dump_json().encode() + b"\n")
         await writer.drain()
 
-        line = await asyncio.wait_for(
-            reader.readline(), timeout=_DAEMON_REQUEST_TIMEOUT
-        )
+        timeout = app_config.daemon.request_timeout
+        line = await asyncio.wait_for(reader.readline(), timeout=timeout)
         if not line:
             return DaemonResponse.fail("Daemon connection closed unexpectedly")
 
         return DaemonResponse.model_validate_json(line)
     except asyncio.TimeoutError:
         return DaemonResponse.fail(
-            f"Daemon request timed out after {_DAEMON_REQUEST_TIMEOUT}s"
+            f"Daemon request timed out after {timeout}s. Raise it via "
+            "AXI_REQUEST_TIMEOUT or axi.json daemon.requestTimeout."
         )
     finally:
         writer.close()

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/daemon/protocol.py

@@ -1,20 +1,19 @@
 """daemon 通信协议：JSON 行格式的请求/响应。"""
 
-import hashlib
 import os
 from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
-from axi.config import CONFIG_PATH
+from axi.config import AXI_HOME, CONFIG_HASH
 from axi.models import ResultEnvelope
 
 # 每份配置对应一个独立 daemon，socket/pid/log 按配置路径 hash 隔离
-SOCKET_DIR = os.path.expanduser("~/.axi/daemons")
-_CONFIG_HASH = hashlib.sha256(str(CONFIG_PATH).encode()).hexdigest()[:12]
-SOCKET_PATH = os.path.join(SOCKET_DIR, f"{_CONFIG_HASH}.sock")
-PID_PATH = os.path.join(SOCKET_DIR, f"{_CONFIG_HASH}.pid")
-LOG_PATH = os.path.join(SOCKET_DIR, f"{_CONFIG_HASH}.log")
+SOCKET_DIR = str(AXI_HOME / "daemons")
+SOCKET_PATH = os.path.join(SOCKET_DIR, f"{CONFIG_HASH}.sock")
+PID_PATH = os.path.join(SOCKET_DIR, f"{CONFIG_HASH}.pid")
+LOG_PATH = os.path.join(SOCKET_DIR, f"{CONFIG_HASH}.log")
+LOCK_PATH = os.path.join(SOCKET_DIR, f"{CONFIG_HASH}.lock")
 
 
 class DaemonRequest(BaseModel):

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/daemon/server.py

@@ -5,7 +5,6 @@ import logging
 import os
 import signal
 import time
-from collections import Counter
 from typing import Any
 
 import jsonschema
@@ -19,7 +18,7 @@ from axi.daemon.protocol import (
     DaemonResponse,
     DaemonStatus,
 )
-from axi.models import ToolSource
+from axi.models import ToolSource, allowed_types
 from axi.providers.mcp import MCPProvider
 from axi.registry import Registry, ToolResolveError
 
@@ -28,20 +27,6 @@ logger = logging.getLogger(__name__)
 _IDLE_EXEMPT_METHODS = frozenset({"status", "shutdown"})
 
 
-def _allowed_types(prop: dict) -> set[str]:
-    """提取属性 schema 允许的原始类型，覆盖 type 为字符串/列表及 anyOf 分支。"""
-    types: set[str] = set()
-    t = prop.get("type")
-    if isinstance(t, str):
-        types.add(t)
-    elif isinstance(t, list):
-        types.update(x for x in t if isinstance(x, str))
-    for branch in prop.get("anyOf", []):
-        if isinstance(branch, dict):
-            types |= _allowed_types(branch)
-    return types
-
-
 def _coerce_to_schema(params: dict, schema: dict) -> dict:
     """按 schema 顶层类型做轻量转换，弥合 CLI 参数解析的类型猜测与严格校验的间隙。
 
@@ -57,7 +42,7 @@ def _coerce_to_schema(params: dict, schema: dict) -> dict:
         prop = props.get(key)
         if not isinstance(prop, dict):
             continue
-        allowed = _allowed_types(prop)
+        allowed = allowed_types(prop)
         if (
             "string" in allowed
             and not ({"integer", "number"} & allowed)
@@ -288,11 +273,6 @@ class DaemonServer:
         idle = now - self._last_activity
         idle_remaining = max(0.0, self._idle_timeout - idle)
 
-        # 按 server 统计工具数量
-        server_tools = dict(
-            Counter(t.server or "unknown" for t in self.registry.list_all())
-        )
-
         status = DaemonStatus(
             pid=os.getpid(),
             config_path=str(CONFIG_PATH),
@@ -300,7 +280,7 @@ class DaemonServer:
             idle_seconds=int(idle),
             idle_timeout_seconds=int(self._idle_timeout),
             idle_remaining_seconds=int(idle_remaining),
-            server_tools=server_tools,
+            server_tools=self.registry.server_tool_counts(),
         )
         return DaemonResponse.success(status.model_dump())
 

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/mcp_serve.py

@@ -18,6 +18,7 @@ import mcp.types as types
 from mcp.server.lowlevel import Server
 
 from axi.config import app_config
+from axi.context import set_request_env
 from axi.daemon.client import daemon_request
 from axi.daemon.protocol import LOG_PATH, DaemonRequest
 from axi.executor import Executor
@@ -87,10 +88,18 @@ def build_registry(
 
 
 async def _execute(
-    registry: Registry, executor: Executor, name: str, params: dict[str, Any]
+    server: Server,
+    registry: Registry,
+    executor: Executor,
+    name: str,
+    params: dict[str, Any],
 ) -> RunResult:
     """按来源分发执行：native 进程内，MCP 转发 daemon。
 
+    native 执行前把当前 HTTP 请求的 Axi-* header 写入请求级变量
+    （stdio 无请求对象，置空）；MCP 工具在 daemon 进程执行，读不到
+    contextvar，不捕获。
+
     Executor.run 与 send_request 内部都会 asyncio.run，
     必须放到 worker 线程执行以避免嵌套事件循环。
     """
@@ -100,6 +109,8 @@ async def _execute(
         return RunResult.fail(str(e))
 
     if meta.source == ToolSource.NATIVE:
+        request = server.request_context.request
+        set_request_env(request.headers if request else None)
         return await asyncio.to_thread(executor.run, meta.full_name, params)
 
     # daemon_request 内含 ensure_daemon：daemon idle 自杀后长驻 serve 进程可自动重启它
@@ -174,7 +185,7 @@ def _build_flat_server(registry: Registry, executor: Executor) -> Server:
             raise ValueError(
                 f"Unknown tool: {name}. Call tools/list to see the available tools."
             )
-        result = await _execute(registry, executor, full_name, arguments)
+        result = await _execute(server, registry, executor, full_name, arguments)
         if result.status == "error":
             raise RuntimeError(result.error)
         return _text(result.data)
@@ -269,7 +280,11 @@ def _build_meta_server(registry: Registry, executor: Executor) -> Server:
             return _text(out[0] if len(out) == 1 else out)
         if name == "run":
             result = await _execute(
-                registry, executor, arguments["name"], arguments.get("params") or {}
+                server,
+                registry,
+                executor,
+                arguments["name"],
+                arguments.get("params") or {},
             )
             return _text(result.model_dump(exclude_none=True))
         raise ValueError(

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/models.py

@@ -6,6 +6,20 @@ from typing import Any, Literal, Self
 from pydantic import BaseModel, Field, model_validator
 
 
+def allowed_types(prop: dict) -> set[str]:
+    """提取属性 schema 允许的原始类型，覆盖 type 为字符串/列表及 anyOf 分支（递归）。"""
+    types: set[str] = set()
+    t = prop.get("type")
+    if isinstance(t, str):
+        types.add(t)
+    elif isinstance(t, list):
+        types.update(x for x in t if isinstance(x, str))
+    for branch in prop.get("anyOf", []):
+        if isinstance(branch, dict):
+            types |= allowed_types(branch)
+    return types
+
+
 class ToolSource(str, Enum):
     """工具来源类型。"""
 
@@ -66,9 +80,13 @@ class RunResult(ResultEnvelope):
 
 
 class SearchResult(BaseModel):
-    """搜索结果条目。"""
+    """搜索结果条目。
+
+    不含相关性分数：native（本地）与 MCP（daemon）来自两套独立索引、
+    各自归一化，跨源分数不可比，暴露出来只会误导 Agent。结果按相关性
+    排序即可，顺序本身就是信号。
+    """
 
     name: str = Field(description="工具完整名称")
     description: str = Field(description="工具描述")
     source: ToolSource = Field(description="工具来源")
-    score: float | None = Field(default=None, description="相关性分数")

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/providers/mcp.py

@@ -8,6 +8,7 @@ import threading
 from contextlib import AsyncExitStack
 from typing import Any, Self
 
+import httpx
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 from mcp.client.streamable_http import streamable_http_client
@@ -49,27 +50,40 @@ class MCPConnection:
         self._exit_stack: AsyncExitStack | None = None
 
     async def connect(self) -> None:
-        """建立连接并初始化 session。"""
-        self._exit_stack = AsyncExitStack()
-
-        if self.config.url:
-            read_stream, write_stream, _ = await self._exit_stack.enter_async_context(
-                streamable_http_client(self.config.url)
-            )
-        else:
-            server_params = StdioServerParameters(
-                command=self.config.command,
-                args=self.config.args,
-                env=self.config.env,
-            )
-            devnull = self._exit_stack.enter_context(open(os.devnull, "w"))
-            read_stream, write_stream = await self._exit_stack.enter_async_context(
-                stdio_client(server_params, errlog=devnull)
+        """建立连接并初始化 session。中途失败时 with 退出自动清理已打开的资源。"""
+        async with AsyncExitStack() as stack:
+            if self.config.url:
+                http_client = None
+                if self.config.headers:
+                    # 超时与 SDK 默认客户端（create_mcp_http_client）一致：
+                    # 读超时 300s 是 SSE 长调用的存活窗口，不能用整体 30s
+                    http_client = await stack.enter_async_context(
+                        httpx.AsyncClient(
+                            headers=self.config.headers,
+                            timeout=httpx.Timeout(30, read=300),
+                            follow_redirects=True,
+                        )
+                    )
+                read_stream, write_stream, _ = await stack.enter_async_context(
+                    streamable_http_client(self.config.url, http_client=http_client)
+                )
+            else:
+                server_params = StdioServerParameters(
+                    command=self.config.command,
+                    args=self.config.args,
+                    env=self.config.env,
+                )
+                devnull = stack.enter_context(open(os.devnull, "w"))
+                read_stream, write_stream = await stack.enter_async_context(
+                    stdio_client(server_params, errlog=devnull)
+                )
+            session = await stack.enter_async_context(
+                ClientSession(read_stream, write_stream)
             )
-        self.session = await self._exit_stack.enter_async_context(
-            ClientSession(read_stream, write_stream)
-        )
-        await self.session.initialize()
+            await session.initialize()
+            # 全部成功才接管资源所有权；此前任何一步抛出都由 with 清理
+            self._exit_stack = stack.pop_all()
+            self.session = session
 
     async def list_tools(self) -> list[ToolMeta]:
         """获取该 server 的所有工具。"""

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/providers/native.py

@@ -183,6 +183,15 @@ def _load_native_entry(
     for name in new_names:
         registry.set_server(name, server_name)
         _rekey_native_tool(name, f"{server_name}/{name}")
+    # 记录来源，便于审计：entry_points 自动发现意味着任何已安装的包都可能注入工具
+    logger.info(
+        "Loaded %d native tool(s) from '%s' (%s) under server '%s': %s",
+        len(new_names),
+        module,
+        source,
+        server_name,
+        ", ".join(new_names),
+    )
 
 
 def load_native_tool_modules() -> None:

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/registry.py

@@ -2,12 +2,17 @@
 
 from __future__ import annotations
 
+from collections import Counter
+from typing import TYPE_CHECKING
+
 from axi.config import SearchConfig
 from axi.models import SearchResult, ToolMeta
 from axi.search.cache import EmbeddingCache
 from axi.search.embedding import EmbeddingProvider, create_embedding_provider
-from axi.search.hybrid import HybridSearch
-from axi.search.regex import RegexSearch
+
+if TYPE_CHECKING:
+    from axi.search.hybrid import HybridSearch
+    from axi.search.regex import RegexSearch
 
 
 def split_names(value: str) -> list[str]:
@@ -38,14 +43,19 @@ class Registry:
         weight_embedding: float = 0.7,
     ) -> None:
         self._tools: dict[str, ToolMeta] = {}
-        self._regex = RegexSearch()
-        self._hybrid = HybridSearch(
-            embedding_provider=embedding_provider,
-            embedding_cache=embedding_cache,
-            weight_bm25=weight_bm25,
-            weight_embedding=weight_embedding,
-        )
-        self._dirty = True
+        # 搜索引擎按需构建：bm25s/jieba/numpy 是重 import，describe/run/list
+        # 完全用不到，延迟到 search()/grep() 首次调用时才付这笔冷启动成本。
+        self._embedding_provider = embedding_provider
+        self._embedding_cache = embedding_cache
+        self._weight_bm25 = weight_bm25
+        self._weight_embedding = weight_embedding
+        self._regex: RegexSearch | None = None
+        self._hybrid: HybridSearch | None = None
+        # 工具集每变一次 _version +1；各引擎记住自己上次 build 的 version，
+        # 只在落后时重建——晚建的引擎不再拖着已是最新的另一引擎陪跑一次。
+        self._version = 0
+        self._regex_version = -1
+        self._hybrid_version = -1
 
     @classmethod
     def from_search_config(cls, cfg: SearchConfig) -> Registry:
@@ -61,7 +71,7 @@ class Registry:
     def register(self, meta: ToolMeta) -> None:
         """注册一个工具。"""
         self._tools[meta.full_name] = meta
-        self._dirty = True
+        self._version += 1
 
     def get(self, full_name: str) -> ToolMeta | None:
         """按完整名称获取工具元数据。"""
@@ -104,6 +114,10 @@ class Registry:
         """列出所有工具的 full_name。"""
         return list(self._tools.keys())
 
+    def server_tool_counts(self) -> dict[str, int]:
+        """按 server 统计工具数量（无 server 归入 "unknown"）。"""
+        return dict(Counter(m.server or "unknown" for m in self._tools.values()))
+
     def set_server(self, full_name: str, server: str) -> None:
         """更新工具的 server 名，同时更新注册 key。"""
         meta = self._tools.pop(full_name, None)
@@ -111,22 +125,31 @@ class Registry:
             return
         updated = meta.model_copy(update={"server": server})
         self._tools[updated.full_name] = updated
-        self._dirty = True
+        self._version += 1
 
     def search(self, query: str, top_k: int = 5) -> list[SearchResult]:
         """混合搜索工具（BM25 + Embedding）。"""
-        self._rebuild_index()
+        if self._hybrid is None:
+            from axi.search.hybrid import HybridSearch
+
+            self._hybrid = HybridSearch(
+                embedding_provider=self._embedding_provider,
+                embedding_cache=self._embedding_cache,
+                weight_bm25=self._weight_bm25,
+                weight_embedding=self._weight_embedding,
+            )
+        if self._hybrid_version != self._version:
+            self._hybrid.build(list(self._tools.values()))
+            self._hybrid_version = self._version
         return self._hybrid.search(query, top_k=top_k)
 
     def grep(self, pattern: str, top_k: int = 10) -> list[SearchResult]:
         """正则表达式搜索工具。"""
-        self._rebuild_index()
-        return self._regex.search(pattern, top_k=top_k)
+        if self._regex is None:
+            from axi.search.regex import RegexSearch
 
-    def _rebuild_index(self) -> None:
-        if not self._dirty:
-            return
-        tools = list(self._tools.values())
-        self._regex.build(tools)
-        self._hybrid.build(tools)
-        self._dirty = False
+            self._regex = RegexSearch()
+        if self._regex_version != self._version:
+            self._regex.build(list(self._tools.values()))
+            self._regex_version = self._version
+        return self._regex.search(pattern, top_k=top_k)

axi_cli-0.0.8/src/axi/search/__init__.py

@@ -0,0 +1,6 @@
+"""搜索模块。
+
+子模块按需直接 import（``from axi.search.bm25 import BM25Search``）。
+此处不做包级 re-export，避免 ``import axi.search.cache`` 这类轻量导入
+连带把 bm25s/jieba/numpy 拖进来——describe/run/list 完全用不到搜索栈。
+"""

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/search/cache.py

@@ -7,10 +7,13 @@ import json
 import logging
 from pathlib import Path
 
+from axi.config import AXI_HOME, CONFIG_HASH
+
 logger = logging.getLogger(__name__)
 
-CACHE_DIR = Path(".axi/cache")
-CACHE_FILE = CACHE_DIR / "embeddings.json"
+# 缓存随配置隔离，落在 ~/.axi 下（与 daemon 文件同处），不再依赖 cwd
+CACHE_DIR = AXI_HOME / "cache"
+CACHE_FILE = CACHE_DIR / f"{CONFIG_HASH}.json"
 
 
 def content_hash(text: str) -> str:

{axi_cli-0.0.6 → axi_cli-0.0.8}/src/axi/search/hybrid.py

@@ -37,14 +37,14 @@ def _rrf_fuse(
 def _to_results(
     tools: list[ToolMeta], scored: list[tuple[int, float]]
 ) -> list[SearchResult]:
+    # scored 已按分数降序；分数只用于排序，不进入结果（跨源不可比）。
     return [
         SearchResult(
             name=tools[idx].full_name,
             description=tools[idx].description,
             source=tools[idx].source,
-            score=round(score, 4),
         )
-        for idx, score in scored
+        for idx, _score in scored
     ]
 
 

axi_cli-0.0.6/src/axi/search/__init__.py

@@ -1,7 +0,0 @@
-"""搜索模块。"""
-
-from axi.search.bm25 import BM25Search
-from axi.search.hybrid import HybridSearch
-from axi.search.regex import RegexSearch
-
-__all__ = ["BM25Search", "HybridSearch", "RegexSearch"]