axi-cli 0.0.3__tar.gz → 0.0.5__tar.gz

{axi_cli-0.0.3 → axi_cli-0.0.5}/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.0.5] - 2026-04-23
+
+### Added
+- Python entry_points 自动发现原生工具：扩展包在 `pyproject.toml` 里声明 `[project.entry-points."axi.native_tools"]` 即可被 axi 自动发现，无需 `axi.json` 登记
+- `docs/configuration.md` 补充 entry_points 机制说明与合并规则（去重、同名 server collision、加载失败降级）
+
+### Changed
+- `load_native_tool_modules` 从 `providers/mcp.py` 搬到 `providers/native.py`，职责回归原生工具 Provider
+- 模块加载失败时不再占位，避免对后续合法包误报 server 名 collision
+
+## [0.0.4] - 2026-04-20
+
+### Added
+- `AXI_CONFIG` 环境变量：自定义 `axi.json` 配置文件路径
+- GitHub Actions workflow：打 `v*` tag 时自动通过 trusted publishing 发布到 PyPI
+- `pyproject.toml` 新增 sdist 打包排除规则（`.github/`、`docs/`、`tests/`、`uv.lock` 等）
+- README 补充 daemon 自动管理、生命周期、状态输出、文件位置等完整说明
+- `docs/architecture.md` 补充 daemon 启动流程、idle watchdog、关闭流程、通信协议章节
+
+### Changed
+- 包名由 `axi` 重命名为 `axi-cli`（PyPI 发布名）
+- 安装方式从 `uv pip install -e .` 改为 `uv sync`
+
 ## [0.0.3] - 2026-04-01
 
 ### Added

{axi_cli-0.0.3 → axi_cli-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axi-cli
-Version: 0.0.3
+Version: 0.0.5
 Summary: Agent eXecution Interface - unified tool layer for AI Agents
 Requires-Python: >=3.12
 Requires-Dist: bm25s>=0.3.3
@@ -29,8 +29,8 @@ Agent eXecution Interface — AI Agent 与外部系统之间的统一工具层
 ## 安装
 
 ```bash
-# 需要 Python 3.12+
-uv pip install -e .
+# 需要 Python 3.12+, uv
+uv sync
 ```
 
 ## 快速开始
@@ -57,28 +57,45 @@ axi run jina/jina_search --query "hello world" --count 3
             "command": "npx",
             "args": ["jina-mcp-tools"],
             "env": { "JINA_API_KEY": "your-key" }
+        },
+        "retrieval": {
+            "url": "http://localhost:8000/mcp"
         }
     },
     "nativeTools": [
         {"module": "my_project.tools"},
         {"module": "./scripts/tools.py", "name": "scripts"}
-    ]
+    ],
+    "search": {
+        "embedding": {
+            "provider": "jina"
+        }
+    },
+    "daemon": {
+        "idleTimeoutMinutes": 30
+    }
 }
 ```
 
-- **mcpServers** — MCP server 配置，key 名作为工具命名空间
+- **mcpServers** — MCP server 配置，key 名作为工具命名空间。支持 `command`（本地进程）和 `url`（HTTP streaming）两种模式
 - **nativeTools** — 原生 Python 工具，`module` 支持文件路径和模块路径，`name` 可选（省略则自动推导）
+- **search** — 搜索配置，`embedding` 段启用语义搜索（支持 Jina/OpenAI）
+- **daemon** — daemon 进程配置，如 idle 超时时间
+
+完整配置参考见 [docs/configuration.md](docs/configuration.md)。
 
 ## CLI 命令
 
 | 命令 | 说明 |
 |------|------|
 | `axi list [server]` | 列出所有 server 及工具 |
-| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k`） |
-| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--top-k`） |
+| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k/-k`） |
+| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--limit/-l`） |
 | `axi describe <tool>` | 查看工具完整 schema |
 | `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
-| `axi daemon start\|status\|stop` | 管理 daemon 进程 |
+| `axi daemon start` | 手动启动 daemon（通常无需手动，CLI 会自动拉起） |
+| `axi daemon status` | 查看 daemon 状态（PID、运行时长、空闲时长、工具数量等） |
+| `axi daemon stop` | 手动停止 daemon |
 
 所有输出统一为紧凑 JSON。`axi run` 返回统一信封：
 
@@ -110,18 +127,80 @@ search = tool("jina/jina_search")
 results = search(query="python async", count=5)
 ```
 
+## 搜索
+
+axi 提供两种搜索方式：
+
+- **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
+- **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
+
+搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+
 ## Daemon 模式
 
-MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。执行 `axi search/describe/run` 时自动启动 daemon，无需手动管理。
+MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。
 
 ```
 axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
                                    ──(stdio)──> MCP server B
 ```
 
+### 自动管理
+
+执行 `axi search`、`describe`、`run` 等命令时，CLI 会自动检测 daemon 是否运行，未运行则自动拉起。大多数情况下无需手动管理。
+
+### 生命周期
+
+| 阶段 | 行为 |
+|------|------|
+| **启动** | 加载 `axi.json` → 连接所有 MCP server → 创建 Unix socket → 写入 PID 文件 → 启动 idle watchdog |
+| **运行** | 通过 `~/.axi/daemon.sock` 监听请求，路由到对应 MCP server 执行 |
+| **空闲关闭** | 默认 30 分钟无活动自动关闭（每 60 秒检查一次；`status` 和 `shutdown` 请求不重置计时器） |
+| **手动关闭** | `axi daemon stop` 发送关闭指令，daemon 优雅退出 |
+| **信号关闭** | 收到 SIGTERM / SIGINT 时优雅关闭（清理 socket 和 PID 文件） |
+
+空闲超时可通过 `axi.json` 的 `daemon.idleTimeoutMinutes` 配置：
+
+```json
+{ "daemon": { "idleTimeoutMinutes": 60 } }
+```
+
+### 手动管理
+
+```bash
+axi daemon start     # 手动启动（通常不需要）
+axi daemon status    # 查看状态
+axi daemon stop      # 手动停止
+```
+
+`axi daemon status` 输出示例：
+
+```json
+{
+  "status": "running",
+  "pid": 12345,
+  "uptime_seconds": 1800,
+  "idle_seconds": 120,
+  "idle_timeout_seconds": 1800,
+  "idle_remaining_seconds": 1680,
+  "server_tools": { "jina": 5, "browser": 3 },
+  "native_tools": 2
+}
+```
+
+### 文件位置
+
+daemon 运行时文件位于 `~/.axi/`：
+
+| 文件 | 说明 |
+|------|------|
+| `daemon.sock` | Unix socket，CLI 与 daemon 的通信通道 |
+| `daemon.pid` | daemon 进程 PID，用于检测是否存活 |
+| `daemon.log` | daemon 启动和错误日志 |
+
 ## 技术栈
 
-Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
+Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) / [bm25s](https://github.com/xhluca/bm25s) + [jieba](https://github.com/fxsjy/jieba) / [LangChain](https://python.langchain.com/)（Embedding）
 
 ## License
 

axi_cli-0.0.5/README.md

@@ -0,0 +1,193 @@
+# axi
+
+Agent eXecution Interface — AI Agent 与外部系统之间的统一工具层。
+
+通过 CLI 作为万能适配器，将 MCP server 和 Python 函数统一为可搜索、可描述、可调用的命令。Agent 无需猜测命令格式或解析人类可读输出，所有交互都是结构化 JSON。
+
+## 核心理念
+
+几乎所有主流 Agent 框架都把 bash 作为基础能力。axi 在这个"万能通道"之上建一层 Agent-native 的工具层：
+
+- **渐进式披露** — `search → describe → run`，按需获取信息，不吃 context window
+- **Agent-first 输出** — 统一紧凑 JSON，无表格、无颜色、无进度条
+- **双来源统一** — MCP server 和原生 Python 工具，对 Agent 来说是同一套接口
+
+## 安装
+
+```bash
+# 需要 Python 3.12+, uv
+uv sync
+```
+
+## 快速开始
+
+```bash
+# 搜索工具
+axi search "web"
+
+# 查看工具详情
+axi describe jina/jina_search
+
+# 执行工具
+axi run jina/jina_search --query "hello world" --count 3
+```
+
+## 配置
+
+在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
+
+```json
+{
+    "mcpServers": {
+        "jina": {
+            "command": "npx",
+            "args": ["jina-mcp-tools"],
+            "env": { "JINA_API_KEY": "your-key" }
+        },
+        "retrieval": {
+            "url": "http://localhost:8000/mcp"
+        }
+    },
+    "nativeTools": [
+        {"module": "my_project.tools"},
+        {"module": "./scripts/tools.py", "name": "scripts"}
+    ],
+    "search": {
+        "embedding": {
+            "provider": "jina"
+        }
+    },
+    "daemon": {
+        "idleTimeoutMinutes": 30
+    }
+}
+```
+
+- **mcpServers** — MCP server 配置，key 名作为工具命名空间。支持 `command`（本地进程）和 `url`（HTTP streaming）两种模式
+- **nativeTools** — 原生 Python 工具，`module` 支持文件路径和模块路径，`name` 可选（省略则自动推导）
+- **search** — 搜索配置，`embedding` 段启用语义搜索（支持 Jina/OpenAI）
+- **daemon** — daemon 进程配置，如 idle 超时时间
+
+完整配置参考见 [docs/configuration.md](docs/configuration.md)。
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `axi list [server]` | 列出所有 server 及工具 |
+| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k/-k`） |
+| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--limit/-l`） |
+| `axi describe <tool>` | 查看工具完整 schema |
+| `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
+| `axi daemon start` | 手动启动 daemon（通常无需手动，CLI 会自动拉起） |
+| `axi daemon status` | 查看 daemon 状态（PID、运行时长、空闲时长、工具数量等） |
+| `axi daemon stop` | 手动停止 daemon |
+
+所有输出统一为紧凑 JSON。`axi run` 返回统一信封：
+
+```json
+{"status": "success", "data": "..."}
+{"status": "error", "error": "错误信息"}
+```
+
+## 注册原生工具
+
+```python
+from axi import tool
+
+@tool(name="query_orders", description="按区域查询订单")
+def query_orders(region: str, limit: int = 10) -> dict:
+    return {"orders": [...], "total": 42}
+```
+
+装饰器自动从函数签名提取参数 schema。注册后同时获得 CLI 调用和 PTC 调用能力。
+
+## PTC（Programmatic Tool Calling）
+
+Agent 可以写 Python 代码批量调用工具，在本地做数据过滤和聚合，避免反复 LLM round-trip：
+
+```python
+from axi import tool
+
+search = tool("jina/jina_search")
+results = search(query="python async", count=5)
+```
+
+## 搜索
+
+axi 提供两种搜索方式：
+
+- **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
+- **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
+
+搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+
+## Daemon 模式
+
+MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。
+
+```
+axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
+                                   ──(stdio)──> MCP server B
+```
+
+### 自动管理
+
+执行 `axi search`、`describe`、`run` 等命令时，CLI 会自动检测 daemon 是否运行，未运行则自动拉起。大多数情况下无需手动管理。
+
+### 生命周期
+
+| 阶段 | 行为 |
+|------|------|
+| **启动** | 加载 `axi.json` → 连接所有 MCP server → 创建 Unix socket → 写入 PID 文件 → 启动 idle watchdog |
+| **运行** | 通过 `~/.axi/daemon.sock` 监听请求，路由到对应 MCP server 执行 |
+| **空闲关闭** | 默认 30 分钟无活动自动关闭（每 60 秒检查一次；`status` 和 `shutdown` 请求不重置计时器） |
+| **手动关闭** | `axi daemon stop` 发送关闭指令，daemon 优雅退出 |
+| **信号关闭** | 收到 SIGTERM / SIGINT 时优雅关闭（清理 socket 和 PID 文件） |
+
+空闲超时可通过 `axi.json` 的 `daemon.idleTimeoutMinutes` 配置：
+
+```json
+{ "daemon": { "idleTimeoutMinutes": 60 } }
+```
+
+### 手动管理
+
+```bash
+axi daemon start     # 手动启动（通常不需要）
+axi daemon status    # 查看状态
+axi daemon stop      # 手动停止
+```
+
+`axi daemon status` 输出示例：
+
+```json
+{
+  "status": "running",
+  "pid": 12345,
+  "uptime_seconds": 1800,
+  "idle_seconds": 120,
+  "idle_timeout_seconds": 1800,
+  "idle_remaining_seconds": 1680,
+  "server_tools": { "jina": 5, "browser": 3 },
+  "native_tools": 2
+}
+```
+
+### 文件位置
+
+daemon 运行时文件位于 `~/.axi/`：
+
+| 文件 | 说明 |
+|------|------|
+| `daemon.sock` | Unix socket，CLI 与 daemon 的通信通道 |
+| `daemon.pid` | daemon 进程 PID，用于检测是否存活 |
+| `daemon.log` | daemon 启动和错误日志 |
+
+## 技术栈
+
+Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) / [bm25s](https://github.com/xhluca/bm25s) + [jieba](https://github.com/fxsjy/jieba) / [LangChain](https://python.langchain.com/)（Embedding）
+
+## License
+
+MIT

{axi_cli-0.0.3 → axi_cli-0.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axi-cli"
-version = "0.0.3"
+version = "0.0.5"
 description = "Agent eXecution Interface - unified tool layer for AI Agents"
 readme = "README.md"
 requires-python = ">=3.12"

{axi_cli-0.0.3 → axi_cli-0.0.5}/src/axi/cli.py

@@ -34,7 +34,7 @@ _executor = Executor(_registry)
 @app.callback(invoke_without_command=True)
 def main_callback(ctx: typer.Context) -> None:
     """CLI 启动时加载 axi.json 中配置的原生工具模块。"""
-    from axi.providers.mcp import load_native_tool_modules
+    from axi.providers.native import load_native_tool_modules
 
     load_native_tool_modules()
     if ctx.invoked_subcommand is None:

{axi_cli-0.0.3 → axi_cli-0.0.5}/src/axi/providers/mcp.py

@@ -1,13 +1,11 @@
 """MCP Provider：读取 axi.json，连接 MCP server，注册工具。"""
 
 import asyncio
-import importlib.util
 import json
 import logging
 import os
 import threading
 from contextlib import AsyncExitStack
-from pathlib import Path
 from typing import Any, Self
 
 from mcp import ClientSession, StdioServerParameters
@@ -15,11 +13,7 @@ from mcp.client.stdio import stdio_client
 from mcp.client.streamable_http import streamable_http_client
 from pydantic import Field, model_validator
 
-from axi.config import (
-    MCPServerConfig as MCPServerBaseConfig,
-    NativeToolEntry,
-    app_config,
-)
+from axi.config import MCPServerConfig as MCPServerBaseConfig, app_config
 from axi.models import RunResult, ToolMeta, ToolSource
 
 logger = logging.getLogger(__name__)
@@ -220,59 +214,6 @@ def run_async(coro: Any) -> Any:
     return future.result()
 
 
-def _import_from_file(file_path: str) -> None:
-    """通过文件路径 import 模块，触发 @tool 注册。"""
-    path = Path(file_path).resolve()
-    if not path.exists():
-        raise FileNotFoundError(f"File not found: {file_path}")
-    module_name = path.stem
-    spec = importlib.util.spec_from_file_location(module_name, path)
-    if spec is None or spec.loader is None:
-        raise ImportError(f"Cannot load module from: {file_path}")
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-
-
-def _resolve_server_name(entry: NativeToolEntry) -> str:
-    """推导 native tool 的 server 名称。"""
-    if entry.name is not None:
-        return entry.name
-    if entry.module.endswith(".py"):
-        return Path(entry.module).stem
-    return entry.module.rsplit(".", 1)[-1]
-
-
-def load_native_tool_modules() -> None:
-    """从全局配置的 nativeTools 列表中加载模块，触发 @tool 注册。"""
-    entries = app_config.native_tools
-    if not entries:
-        return
-
-    from axi.cli import get_registry
-
-    registry = get_registry()
-
-    for entry in entries:
-        try:
-            server_name = _resolve_server_name(entry)
-
-            # 记录导入前已有的工具
-            before = set(registry.list_names())
-
-            if entry.module.endswith(".py"):
-                _import_from_file(entry.module)
-            else:
-                importlib.import_module(entry.module)
-
-            # 为新增的工具设置 server
-            new_names = [k for k in registry.list_names() if k not in before]
-            for name in new_names:
-                registry.set_server(name, server_name)
-
-        except Exception:
-            logger.exception("Failed to load native tool '%s'", entry)
-
-
 def load_mcp_tools_sync() -> tuple[MCPProvider, list[ToolMeta]]:
     """同步包装：加载配置并连接所有 MCP server。"""
     provider = MCPProvider()

axi_cli-0.0.5/src/axi/providers/native.py

@@ -0,0 +1,194 @@
+"""原生工具 Provider：通过 @tool 装饰器注册 Python 函数，
+并负责从 axi.json 的 nativeTools 与 Python entry_points 加载工具模块。"""
+
+import importlib
+import importlib.metadata
+import importlib.util
+import inspect
+import logging
+from pathlib import Path
+from typing import Any, Callable, get_type_hints
+
+from pydantic import create_model
+
+from axi.config import NativeToolEntry, app_config
+from axi.models import ToolMeta, ToolSource
+
+logger = logging.getLogger(__name__)
+
+# 全局注册表，存储原生工具的函数引用
+_native_functions: dict[str, Callable] = {}
+
+
+# ── 工具注册（@tool 装饰器的执行层）────────────────────────────
+
+
+def _extract_input_schema(func: Callable) -> dict[str, Any]:
+    """从函数签名和 type hints 提取 JSON Schema。
+
+    利用 Pydantic 的 create_model 动态构建模型，
+    自动支持 Literal、Optional、list[T]、嵌套 BaseModel、Annotated[..., Field()] 等。
+    """
+    hints = get_type_hints(func, include_extras=True)
+    sig = inspect.signature(func)
+    fields: dict[str, Any] = {}
+
+    for name, param in sig.parameters.items():
+        hint = hints.get(name, Any)
+        if param.default is inspect.Parameter.empty:
+            fields[name] = (hint, ...)
+        else:
+            fields[name] = (hint, param.default)
+
+    model = create_model(func.__name__, **fields)
+    schema = model.model_json_schema()
+
+    # 移除 Pydantic 自动添加的 title 字段，保持输出紧凑
+    schema.pop("title", None)
+    for prop in schema.get("properties", {}).values():
+        prop.pop("title", None)
+
+    return schema
+
+
+def register_tool(
+    func: Callable,
+    name: str | None = None,
+    description: str | None = None,
+    output_example: Any | None = None,
+) -> ToolMeta:
+    """注册一个原生 Python 函数为 axi 工具。"""
+    tool_name = name or func.__name__
+    tool_desc = description or func.__doc__ or ""
+
+    meta = ToolMeta(
+        name=tool_name,
+        description=tool_desc,
+        input_schema=_extract_input_schema(func),
+        output_example=output_example,
+        source=ToolSource.NATIVE,
+    )
+
+    _native_functions[tool_name] = func
+    return meta
+
+
+def get_native_function(name: str) -> Callable | None:
+    """获取已注册的原生函数。"""
+    return _native_functions.get(name)
+
+
+# ── 模块发现与加载 ─────────────────────────────────────────────
+
+NATIVE_TOOLS_ENTRY_POINT_GROUP = "axi.native_tools"
+
+
+def _import_from_file(file_path: str) -> None:
+    """通过文件路径 import 模块，触发 @tool 注册。"""
+    path = Path(file_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+    module_name = path.stem
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load module from: {file_path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+
+def _resolve_server_name(entry: NativeToolEntry) -> str:
+    """推导 native tool 的 server 名称。"""
+    if entry.name is not None:
+        return entry.name
+    if entry.module.endswith(".py"):
+        return Path(entry.module).stem
+    return entry.module.rsplit(".", 1)[-1]
+
+
+def _load_native_entry(
+    registry: Any,
+    module: str,
+    server_name: str,
+    loaded: dict[str, str],
+    source: str,
+) -> None:
+    """加载单个原生工具模块并把新增工具归到 server_name 下。
+
+    ``loaded`` 以 "模块路径 → server 名" 映射**仅记录成功加载**的模块：
+    - 模块路径重复 → 跳过（axi.json 与 entry_points 声明同一个模块是预期情况）
+    - 导入抛异常 → logger.exception 后 return，不占坑也不让一个坏包搞崩 CLI
+    - 加载成功但 server 名被别的模块占了 → logger.warning，继续挂到该 server 下
+
+    失败的模块不写入 ``loaded`` 可以避免对后续合法包误报 collision。
+    """
+    if module in loaded:
+        return
+    try:
+        before = set(registry.list_names())
+        if module.endswith(".py"):
+            _import_from_file(module)
+        else:
+            importlib.import_module(module)
+        new_names = [n for n in registry.list_names() if n not in before]
+    except Exception:
+        logger.exception(
+            "Failed to load native tool module '%s' (from %s)", module, source
+        )
+        return
+    if server_name in loaded.values():
+        other = next(m for m, s in loaded.items() if s == server_name)
+        logger.warning(
+            "Server name collision: '%s' already claimed by module '%s'; "
+            "tools from '%s' (%s) will be merged under the same server",
+            server_name,
+            other,
+            module,
+            source,
+        )
+    loaded[module] = server_name
+    for name in new_names:
+        registry.set_server(name, server_name)
+
+
+def load_native_tool_modules() -> None:
+    """从 axi.json 的 nativeTools 与 Python entry_points 加载原生工具模块。
+
+    合并规则：
+    - axi.json 先遍历，entry_points 后遍历；按**模块路径**去重（同一个模块只加载一次）
+    - 因此重复声明时 axi.json 的 server 名赢
+    - 不同模块声明同一个 server 名时仅 log warning，两边工具都会注册到该 server
+    """
+    from axi.cli import get_registry
+
+    registry = get_registry()
+    loaded: dict[str, str] = {}
+
+    # 来源 1：axi.json 的 nativeTools（显式配置，优先级更高）
+    for entry in app_config.native_tools:
+        _load_native_entry(
+            registry,
+            entry.module,
+            _resolve_server_name(entry),
+            loaded,
+            source="axi.json",
+        )
+
+    # 来源 2：Python entry_points group="axi.native_tools"
+    # 任何 pip 安装的包在 pyproject.toml 里声明就会被自动发现，
+    # 无需在 axi.json 里重复登记。
+    try:
+        eps = importlib.metadata.entry_points(group=NATIVE_TOOLS_ENTRY_POINT_GROUP)
+    except Exception:
+        logger.exception(
+            "Failed to query entry_points for %s", NATIVE_TOOLS_ENTRY_POINT_GROUP
+        )
+        eps = []
+    for ep in eps:
+        module_path = ep.value.split(":", 1)[0].strip()
+        _load_native_entry(
+            registry,
+            module_path,
+            ep.name,
+            loaded,
+            source=f"entry_points:{ep.name}",
+        )

axi_cli-0.0.3/README.md

@@ -1,114 +0,0 @@
-# axi
-
-Agent eXecution Interface — AI Agent 与外部系统之间的统一工具层。
-
-通过 CLI 作为万能适配器，将 MCP server 和 Python 函数统一为可搜索、可描述、可调用的命令。Agent 无需猜测命令格式或解析人类可读输出，所有交互都是结构化 JSON。
-
-## 核心理念
-
-几乎所有主流 Agent 框架都把 bash 作为基础能力。axi 在这个"万能通道"之上建一层 Agent-native 的工具层：
-
-- **渐进式披露** — `search → describe → run`，按需获取信息，不吃 context window
-- **Agent-first 输出** — 统一紧凑 JSON，无表格、无颜色、无进度条
-- **双来源统一** — MCP server 和原生 Python 工具，对 Agent 来说是同一套接口
-
-## 安装
-
-```bash
-# 需要 Python 3.12+
-uv pip install -e .
-```
-
-## 快速开始
-
-```bash
-# 搜索工具
-axi search "web"
-
-# 查看工具详情
-axi describe jina/jina_search
-
-# 执行工具
-axi run jina/jina_search --query "hello world" --count 3
-```
-
-## 配置
-
-在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
-
-```json
-{
-    "mcpServers": {
-        "jina": {
-            "command": "npx",
-            "args": ["jina-mcp-tools"],
-            "env": { "JINA_API_KEY": "your-key" }
-        }
-    },
-    "nativeTools": [
-        {"module": "my_project.tools"},
-        {"module": "./scripts/tools.py", "name": "scripts"}
-    ]
-}
-```
-
-- **mcpServers** — MCP server 配置，key 名作为工具命名空间
-- **nativeTools** — 原生 Python 工具，`module` 支持文件路径和模块路径，`name` 可选（省略则自动推导）
-
-## CLI 命令
-
-| 命令 | 说明 |
-|------|------|
-| `axi list [server]` | 列出所有 server 及工具 |
-| `axi search <query>` | 混合搜索工具（BM25 + Embedding，支持 `--top-k`） |
-| `axi grep <pattern>` | 正则表达式搜索工具（支持 `--top-k`） |
-| `axi describe <tool>` | 查看工具完整 schema |
-| `axi run <tool> --key value` | 执行工具（也支持 `-j '{...}'` 传 JSON） |
-| `axi daemon start\|status\|stop` | 管理 daemon 进程 |
-
-所有输出统一为紧凑 JSON。`axi run` 返回统一信封：
-
-```json
-{"status": "success", "data": "..."}
-{"status": "error", "error": "错误信息"}
-```
-
-## 注册原生工具
-
-```python
-from axi import tool
-
-@tool(name="query_orders", description="按区域查询订单")
-def query_orders(region: str, limit: int = 10) -> dict:
-    return {"orders": [...], "total": 42}
-```
-
-装饰器自动从函数签名提取参数 schema。注册后同时获得 CLI 调用和 PTC 调用能力。
-
-## PTC（Programmatic Tool Calling）
-
-Agent 可以写 Python 代码批量调用工具，在本地做数据过滤和聚合，避免反复 LLM round-trip：
-
-```python
-from axi import tool
-
-search = tool("jina/jina_search")
-results = search(query="python async", count=5)
-```
-
-## Daemon 模式
-
-MCP 工具通过后台 daemon 长连接执行，支持有状态 MCP server（如 browser MCP）。执行 `axi search/describe/run` 时自动启动 daemon，无需手动管理。
-
-```
-axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
-                                   ──(stdio)──> MCP server B
-```
-
-## 技术栈
-
-Python 3.12+ / [Typer](https://typer.tiangolo.com/) / [Pydantic](https://docs.pydantic.dev/) / [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
-
-## License
-
-MIT

axi_cli-0.0.3/src/axi/providers/native.py

@@ -1,66 +0,0 @@
-"""原生工具注册 Provider：通过 @tool 装饰器注册 Python 函数。"""
-
-import inspect
-from typing import Any, Callable, get_type_hints
-
-from pydantic import create_model
-
-from axi.models import ToolMeta, ToolSource
-
-# 全局注册表，存储原生工具的函数引用
-_native_functions: dict[str, Callable] = {}
-
-
-def _extract_input_schema(func: Callable) -> dict[str, Any]:
-    """从函数签名和 type hints 提取 JSON Schema。
-
-    利用 Pydantic 的 create_model 动态构建模型，
-    自动支持 Literal、Optional、list[T]、嵌套 BaseModel、Annotated[..., Field()] 等。
-    """
-    hints = get_type_hints(func, include_extras=True)
-    sig = inspect.signature(func)
-    fields: dict[str, Any] = {}
-
-    for name, param in sig.parameters.items():
-        hint = hints.get(name, Any)
-        if param.default is inspect.Parameter.empty:
-            fields[name] = (hint, ...)
-        else:
-            fields[name] = (hint, param.default)
-
-    model = create_model(func.__name__, **fields)
-    schema = model.model_json_schema()
-
-    # 移除 Pydantic 自动添加的 title 字段，保持输出紧凑
-    schema.pop("title", None)
-    for prop in schema.get("properties", {}).values():
-        prop.pop("title", None)
-
-    return schema
-
-
-def register_tool(
-    func: Callable,
-    name: str | None = None,
-    description: str | None = None,
-    output_example: Any | None = None,
-) -> ToolMeta:
-    """注册一个原生 Python 函数为 axi 工具。"""
-    tool_name = name or func.__name__
-    tool_desc = description or func.__doc__ or ""
-
-    meta = ToolMeta(
-        name=tool_name,
-        description=tool_desc,
-        input_schema=_extract_input_schema(func),
-        output_example=output_example,
-        source=ToolSource.NATIVE,
-    )
-
-    _native_functions[tool_name] = func
-    return meta
-
-
-def get_native_function(name: str) -> Callable | None:
-    """获取已注册的原生函数。"""
-    return _native_functions.get(name)