axi-cli 0.0.4__tar.gz → 0.0.7__tar.gz

axi_cli-0.0.7/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+## [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 mcp` 命令：将 axi 工具导出为 MCP server，实现"写一次，CLI + MCP 两用"
+  - `--transport stdio|http`：stdio（默认，由 MCP 客户端拉起）或 streamable HTTP（`--port`/`--host`）
+  - `--server a,b`：只暴露指定 server 的工具（逗号分隔多个）
+  - 平铺模式：每个工具注册为独立 MCP tool（单 server 用裸名，多 server 加 `server__` 前缀）；元工具模式：只暴露 `search`/`grep`/`describe`/`run` 四个工具，渐进式披露
+  - 缺省形态自动判定：指定 `--server` → 平铺，全量 → 元工具；`--flat`/`--meta` 强制覆盖
+- `axi daemon status` 输出新增 `config_path` 字段
+- 执行前参数校验：native 工具按 Pydantic 参数模型校验并转换（字符串数字 → int、嵌套 dict → BaseModel 实例、多余字段报错）；MCP 工具由 daemon 按 `input_schema` 做 jsonschema 校验。非法参数返回 `{"status":"error","error":"Invalid params: ..."}`，不再触达工具本体
+
+### Fixed
+- MCP 工具返回 `isError` 结果时被包成 `{"status":"success"}` 的问题：现在正确落进 error 信封，且工具级错误不再触发无意义的重连重试
+- `axi mcp` 长驻进程在 daemon idle 超时后 MCP 工具永久不可用：执行路径统一走 `daemon_request`（内含自动重启）
+- 两个模块注册同名 native 工具时相互遮蔽（静默执行错误的函数）：函数/模型注册键改为 full_name
+- `**kwargs` 签名的 `@tool` 函数在参数校验下不可调用：`*args`/`**kwargs` 不再进参数模型，有 `**kwargs` 时放行多余字段
+- 参数校验与 CLI 类型猜测的冲突：native 侧启用 `coerce_numbers_to_str`（`--name 42` → "42"），daemon 侧按 schema 顶层类型做轻量转换（`--port 08080` → 8080）
+- schema 含不可解析 `$ref` 时工具不可调用：校验兜底放宽为除 ValidationError 外一律放行
+- 平铺模式下清洗后同名的工具静默覆盖：按注册顺序加 `_2`/`_3` 后缀
+- `axi mcp --server` 把"配置了但没连上"的 MCP server 误报为"不存在"：现在区分两种情况并指向 daemon 日志
+- cwd 存在 `./axi.json` 但未设 `AXI_CONFIG` 时输出迁移提示（0.0.5 → 0.0.6 升级不再静默丢工具）
+- uvicorn / starlette / httpx 从传递依赖转为显式声明
+
+### Changed
+- **Breaking**：配置文件不再从当前目录读取 `./axi.json`；默认路径改为 `~/.axi/axi.json`，项目级配置通过 `AXI_CONFIG` 环境变量指定
+- **Breaking**：daemon 按配置文件隔离，每份 `AXI_CONFIG` 对应独立 daemon；socket/pid/log 移至 `~/.axi/daemons/<配置路径哈希>.*`（原 `~/.axi/daemon.sock` 废弃）
+
+## [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
+- BM25 关键词搜索（bm25s + jieba 分词，支持中英文）
+- Embedding 语义搜索（Jina/OpenAI，通过 LangChain 接入，可选）
+- 混合搜索（BM25 + Embedding，RRF 融合排序，分数归一化 0-1）
+- `axi grep` 命令：独立的正则表达式搜索
+- `axi daemon status` 输出 JSON 格式状态信息（PID、运行时长、工具统计）
+- Daemon idle 超时自动关闭机制
+- `config.py` 统一配置模块（`axi.json` 解析 + Pydantic 模型）
+- `docs/configuration.md` 配置参考文档
+- Embedding 文件缓存（`.axi/` 目录）
+- MCP 工具调用失败时自动重连一次
+
+### Changed
+- `axi search` 从子串匹配改为 BM25 混合搜索
+- 搜索结果新增 `score` 字段
+- `ToolResolveError` 拆分为 `ToolNotFoundError` 和 `AmbiguousToolError`
+- Daemon 启动不再需要 `--config` 参数，统一从 `axi.json` 读取
+- MCP/原生工具配置统一通过 `config.py` 管理，移除分散的配置解析逻辑
+
+## [0.0.2] - 2026-03-30
+
+### Changed
+- 原生工具 schema 提取改用 Pydantic `create_model`，支持 Literal、Optional、list[T]、嵌套 BaseModel、Annotated[..., Field()] 等高级类型
+- 版本号从 0.1.0 调整为 0.0.2，反映项目早期阶段
+- 代码格式化统一（ruff format）
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- 初始版本：原生工具注册、MCP 对接、daemon 模式

{axi_cli-0.0.4 → axi_cli-0.0.7}/PKG-INFO

@@ -1,15 +1,18 @@
 Metadata-Version: 2.4
 Name: axi-cli
-Version: 0.0.4
+Version: 0.0.7
 Summary: Agent eXecution Interface - unified tool layer for AI Agents
 Requires-Python: >=3.12
 Requires-Dist: bm25s>=0.3.3
 Requires-Dist: jieba>=0.42.1
+Requires-Dist: jsonschema>=4.26.0
 Requires-Dist: langchain-community>=0.4.1
 Requires-Dist: langchain-openai>=1.1.12
 Requires-Dist: mcp>=1.26.0
 Requires-Dist: pydantic>=2.12.5
+Requires-Dist: starlette>=1.0.0
 Requires-Dist: typer>=0.24.1
+Requires-Dist: uvicorn>=0.42.0
 Description-Content-Type: text/markdown
 
 # axi
@@ -48,7 +51,7 @@ axi run jina/jina_search --query "hello world" --count 3
 
 ## 配置
 
-在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
+配置文件默认为 `~/.axi/axi.json`；项目级配置通过 `AXI_CONFIG` 环境变量指定（如 `export AXI_CONFIG=/path/to/project/axi.json`，或写进 direnv 的 `.envrc`）。每份配置对应一个独立的 daemon，多项目互不干扰。格式参考 `axi.json.example`：
 
 ```json
 {
@@ -93,6 +96,8 @@ axi run jina/jina_search --query "hello world" --count 3
 | `axi grep <pattern>` | 正则表达式搜索工具（支持 `--limit/-l`） |
 | `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 |
@@ -127,6 +132,37 @@ search = tool("jina/jina_search")
 results = search(query="python async", count=5)
 ```
 
+## 导出为 MCP server
+
+用 axi 封装的工具写一次，既能 CLI 调用，也能一条命令变成 MCP server 给任何 MCP 客户端（Claude Desktop、Claude Code 等）使用：
+
+```bash
+axi mcp                                  # 全部工具，元工具模式（search/grep/describe/run）
+axi mcp --server mytools                 # 只暴露一组工具，平铺模式
+axi mcp --server a,b --transport http --port 8321   # HTTP 长驻服务
+```
+
+两种暴露形态（互斥）：
+
+- **平铺**（指定 `--server` 时默认）— 每个工具注册为独立 MCP tool，对端直接看到并调用。单 server 用裸工具名，多 server 加 `server__` 前缀
+- **元工具**（全量导出时默认）— 只暴露 `search` / `grep` / `describe` / `run` 四个工具，对端以渐进式披露的方式发现和调用，上下文占用恒定，工具再多也不吃 context
+
+`--flat` / `--meta` 可强制覆盖默认判定。
+
+MCP 客户端配置示例（stdio 由客户端拉起，用 `AXI_CONFIG` 锚定项目）：
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "axi",
+      "args": ["mcp", "--server", "mytools"],
+      "env": { "AXI_CONFIG": "/path/to/project/axi.json" }
+    }
+  }
+}
+```
+
 ## 搜索
 
 axi 提供两种搜索方式：
@@ -134,7 +170,7 @@ axi 提供两种搜索方式：
 - **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
 - **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
 
-搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+结果按相关性排序返回，顺序本身即信号（不含分数：native 与 MCP 来自两套索引、分数不可比）。
 
 ## Daemon 模式
 
@@ -154,7 +190,7 @@ axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
 | 阶段 | 行为 |
 |------|------|
 | **启动** | 加载 `axi.json` → 连接所有 MCP server → 创建 Unix socket → 写入 PID 文件 → 启动 idle watchdog |
-| **运行** | 通过 `~/.axi/daemon.sock` 监听请求，路由到对应 MCP server 执行 |
+| **运行** | 通过 `~/.axi/daemons/<hash>.sock` 监听请求，路由到对应 MCP server 执行 |
 | **空闲关闭** | 默认 30 分钟无活动自动关闭（每 60 秒检查一次；`status` 和 `shutdown` 请求不重置计时器） |
 | **手动关闭** | `axi daemon stop` 发送关闭指令，daemon 优雅退出 |
 | **信号关闭** | 收到 SIGTERM / SIGINT 时优雅关闭（清理 socket 和 PID 文件） |
@@ -179,6 +215,7 @@ axi daemon stop      # 手动停止
 {
   "status": "running",
   "pid": 12345,
+  "config_path": "/path/to/project/axi.json",
   "uptime_seconds": 1800,
   "idle_seconds": 120,
   "idle_timeout_seconds": 1800,
@@ -190,13 +227,15 @@ axi daemon stop      # 手动停止
 
 ### 文件位置
 
-daemon 运行时文件位于 `~/.axi/`：
+daemon 按配置文件隔离：每份 `AXI_CONFIG` 对应一个独立 daemon，运行时文件位于 `~/.axi/daemons/`，文件名为配置文件绝对路径的哈希：
 
 | 文件 | 说明 |
 |------|------|
-| `daemon.sock` | Unix socket，CLI 与 daemon 的通信通道 |
-| `daemon.pid` | daemon 进程 PID，用于检测是否存活 |
-| `daemon.log` | daemon 启动和错误日志 |
+| `<hash>.sock` | Unix socket，CLI 与 daemon 的通信通道 |
+| `<hash>.pid` | daemon 进程 PID，用于检测是否存活 |
+| `<hash>.log` | daemon 启动和错误日志 |
+
+`axi daemon status` 的 `config_path` 字段显示当前 daemon 服务的配置文件。
 
 ## 技术栈
 

{axi_cli-0.0.4 → axi_cli-0.0.7}/README.md

@@ -34,7 +34,7 @@ axi run jina/jina_search --query "hello world" --count 3
 
 ## 配置
 
-在项目根目录创建 `axi.json`（参考 `axi.json.example`）：
+配置文件默认为 `~/.axi/axi.json`；项目级配置通过 `AXI_CONFIG` 环境变量指定（如 `export AXI_CONFIG=/path/to/project/axi.json`，或写进 direnv 的 `.envrc`）。每份配置对应一个独立的 daemon，多项目互不干扰。格式参考 `axi.json.example`：
 
 ```json
 {
@@ -79,6 +79,8 @@ axi run jina/jina_search --query "hello world" --count 3
 | `axi grep <pattern>` | 正则表达式搜索工具（支持 `--limit/-l`） |
 | `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 |
@@ -113,6 +115,37 @@ search = tool("jina/jina_search")
 results = search(query="python async", count=5)
 ```
 
+## 导出为 MCP server
+
+用 axi 封装的工具写一次，既能 CLI 调用，也能一条命令变成 MCP server 给任何 MCP 客户端（Claude Desktop、Claude Code 等）使用：
+
+```bash
+axi mcp                                  # 全部工具，元工具模式（search/grep/describe/run）
+axi mcp --server mytools                 # 只暴露一组工具，平铺模式
+axi mcp --server a,b --transport http --port 8321   # HTTP 长驻服务
+```
+
+两种暴露形态（互斥）：
+
+- **平铺**（指定 `--server` 时默认）— 每个工具注册为独立 MCP tool，对端直接看到并调用。单 server 用裸工具名，多 server 加 `server__` 前缀
+- **元工具**（全量导出时默认）— 只暴露 `search` / `grep` / `describe` / `run` 四个工具，对端以渐进式披露的方式发现和调用，上下文占用恒定，工具再多也不吃 context
+
+`--flat` / `--meta` 可强制覆盖默认判定。
+
+MCP 客户端配置示例（stdio 由客户端拉起，用 `AXI_CONFIG` 锚定项目）：
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "axi",
+      "args": ["mcp", "--server", "mytools"],
+      "env": { "AXI_CONFIG": "/path/to/project/axi.json" }
+    }
+  }
+}
+```
+
 ## 搜索
 
 axi 提供两种搜索方式：
@@ -120,7 +153,7 @@ axi 提供两种搜索方式：
 - **`axi search`** — 混合搜索，默认 BM25 关键词搜索（bm25s + jieba 分词，支持中英文）。配置 `search.embedding` 后启用 BM25 + Embedding 混合搜索（RRF 融合排序，分数归一化 0-1）
 - **`axi grep`** — 正则表达式搜索，按工具名和描述匹配
 
-搜索结果包含 `score` 字段，便于 Agent 判断相关性。
+结果按相关性排序返回，顺序本身即信号（不含分数：native 与 MCP 来自两套索引、分数不可比）。
 
 ## Daemon 模式
 
@@ -140,7 +173,7 @@ axi CLI ──(Unix socket)──> daemon ──(stdio)──> MCP server A
 | 阶段 | 行为 |
 |------|------|
 | **启动** | 加载 `axi.json` → 连接所有 MCP server → 创建 Unix socket → 写入 PID 文件 → 启动 idle watchdog |
-| **运行** | 通过 `~/.axi/daemon.sock` 监听请求，路由到对应 MCP server 执行 |
+| **运行** | 通过 `~/.axi/daemons/<hash>.sock` 监听请求，路由到对应 MCP server 执行 |
 | **空闲关闭** | 默认 30 分钟无活动自动关闭（每 60 秒检查一次；`status` 和 `shutdown` 请求不重置计时器） |
 | **手动关闭** | `axi daemon stop` 发送关闭指令，daemon 优雅退出 |
 | **信号关闭** | 收到 SIGTERM / SIGINT 时优雅关闭（清理 socket 和 PID 文件） |
@@ -165,6 +198,7 @@ axi daemon stop      # 手动停止
 {
   "status": "running",
   "pid": 12345,
+  "config_path": "/path/to/project/axi.json",
   "uptime_seconds": 1800,
   "idle_seconds": 120,
   "idle_timeout_seconds": 1800,
@@ -176,13 +210,15 @@ axi daemon stop      # 手动停止
 
 ### 文件位置
 
-daemon 运行时文件位于 `~/.axi/`：
+daemon 按配置文件隔离：每份 `AXI_CONFIG` 对应一个独立 daemon，运行时文件位于 `~/.axi/daemons/`，文件名为配置文件绝对路径的哈希：
 
 | 文件 | 说明 |
 |------|------|
-| `daemon.sock` | Unix socket，CLI 与 daemon 的通信通道 |
-| `daemon.pid` | daemon 进程 PID，用于检测是否存活 |
-| `daemon.log` | daemon 启动和错误日志 |
+| `<hash>.sock` | Unix socket，CLI 与 daemon 的通信通道 |
+| `<hash>.pid` | daemon 进程 PID，用于检测是否存活 |
+| `<hash>.log` | daemon 启动和错误日志 |
+
+`axi daemon status` 的 `config_path` 字段显示当前 daemon 服务的配置文件。
 
 ## 技术栈
 

{axi_cli-0.0.4 → axi_cli-0.0.7}/pyproject.toml

@@ -1,17 +1,20 @@
 [project]
 name = "axi-cli"
-version = "0.0.4"
+version = "0.0.7"
 description = "Agent eXecution Interface - unified tool layer for AI Agents"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
     "bm25s>=0.3.3",
     "jieba>=0.42.1",
+    "jsonschema>=4.26.0",
     "langchain-community>=0.4.1",
     "langchain-openai>=1.1.12",
     "mcp>=1.26.0",
     "pydantic>=2.12.5",
+    "starlette>=1.0.0",
     "typer>=0.24.1",
+    "uvicorn>=0.42.0",
 ]
 
 [project.scripts]
@@ -37,7 +40,12 @@ exclude = [
 
 [dependency-groups]
 dev = [
+    "httpx>=0.28.1",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "ruff>=0.15.8",
 ]
+
+[tool.pytest.ini_options]
+# 只从 tests/ 收集，隔离本地 scratch 的 test/（已 gitignore，不随包分发）
+testpaths = ["tests"]

axi_cli-0.0.7/skills/axi-creator/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: axi-creator
+description: Expose an existing capability (Python function, HTTP API, third-party SDK, or MCP server) as an axi tool, or export registered axi tools as an MCP server. Use when the user wants to "add a tool to axi", "wrap an API for axi", "register a function", "make X callable via `axi run`", "expose these tools over MCP / hook them to Claude Desktop" (`axi mcp`), or needs to build a new `@tool` / configure `mcpServers` / publish a native-tool package. Covers decorator usage, schema quality via type hints, registration via `axi.json` vs `pyproject.toml` entry_points, MCP export, and end-to-end self-verification. Use `axi-use` instead when the task is to call existing tools rather than register new ones.
+---
+
+# axi — 工具接入手册
+
+把一个能力变成 axi 工具，**先选路径，再写注册，最后自测**。
+
+## 选路径（按起点决定）
+
+| 起点 | 走哪条 | 工作量 |
+|---|---|---|
+| 已有 MCP server（能跑命令或暴露 HTTP 端点） | **Path B：改 `axi.json` 的 `mcpServers`** | 1 行 JSON |
+| 有 Python 函数 / 想包装 HTTP API 或第三方 SDK | **Path A：写 `@tool` 装饰器** | 函数 + 几行注册 |
+| 要把工具以 pip 包分发给别人 | Path A + entry_points | 加 1 段 pyproject.toml |
+
+---
+
+## Path A：`@tool` 装饰器
+
+最小示例（放进任意 Python 文件，比如 `my_tools.py`）：
+
+```python
+from axi import tool
+
+@tool(
+    name="query_orders",                      # 可选，缺省用函数名
+    description="按区域查询订单",              # 可选，缺省用 docstring
+    output_example={"orders": [...], "total": 1},  # 可选，但强烈建议写
+)
+def query_orders(region: str, limit: int = 10) -> dict:
+    return {"orders": [...], "total": 1}
+```
+
+**就这一步就够了——函数被 import 时自动注册。** `input_schema` 由 axi 从 type hints 提取（用 Pydantic `create_model`），不用自己写 JSON Schema。
+
+### 写出好 schema（决定 Agent 用起来的难度）
+
+axi 支持 Pydantic 能支持的一切。**越严格，Agent 传错参数的概率越低**：
+
+```python
+from typing import Annotated, Literal
+from pydantic import BaseModel, Field
+
+class TimeRange(BaseModel):
+    start: str
+    end: str
+
+@tool(description="查询设备的 CAN 数据")
+def get_can_data(
+    device_id: Annotated[str, Field(description="设备唯一 ID", min_length=8)],
+    region: Literal["cn", "jp", "us"],              # 枚举 → agent 不会猜错
+    range: TimeRange,                               # 嵌套 object schema
+    fields: list[str] | None = None,                # 可选 list
+    limit: Annotated[int, Field(ge=1, le=1000)] = 100,
+) -> dict: ...
+```
+
+要点：
+- **必传参数不给默认值**；可选参数一律给默认值（Agent 会省略）
+- 用 `Literal[...]` 表达枚举，比 `str` + 文档说明更可靠
+- 用 `Annotated[T, Field(description=...)]` 在 schema 里塞字段说明；**`description` 文本会被 BM25/Embedding 搜到**——写清楚利己利人
+- 复杂输入用 `BaseModel` 嵌套；axi 会把它展开成 object schema
+- **填 `output_example`**：MCP 协议没有 output schema，原生工具是 axi 独有的优势——Agent 能在 `axi describe` 里直接看到返回形状，不用试跑一遍
+
+### 注册：两种方式，二选一
+
+**方式 1：本项目内用 → `axi.json` 的 `nativeTools`**
+
+```json
+{
+  "nativeTools": [
+    { "module": "./tools/my_tools.py" },          // 文件路径，server 名自动推导为 my_tools
+    { "module": "my_pkg.tools", "name": "my" }    // 模块路径，显式指定 server
+  ]
+}
+```
+
+`axi.json` 是 `AXI_CONFIG` 环境变量指向的文件（缺省 `~/.axi/axi.json`，**不会从当前目录发现**）。项目级配置在项目里放一份 axi.json 并 `export AXI_CONFIG=/path/to/axi.json`（direnv 最省事）。
+
+**方式 2：分发给别人用 → pip 包 + `pyproject.toml` entry_points**
+
+```toml
+[project.entry-points."axi.native_tools"]
+smartlink = "smartlink_axi.tools"
+```
+
+装完 `pip install <你的包>` 后，**无需 axi.json** 也能 `axi list` 看到；group 名必须是 `axi.native_tools`，value 必须是模块路径（不要写 `.py` 文件）。
+
+合并规则：同模块两边都声明时 `axi.json` 赢；不同模块声明同一个 server 名会 log warning 但照常挂载（工具合并）。
+
+---
+
+## Path B：接入已有 MCP server
+
+编辑 `AXI_CONFIG` 指向的 `axi.json`（缺省 `~/.axi/axi.json`）：
+
+```json
+{
+  "mcpServers": {
+    "myserver": {                                   // key 就是 server 名
+      "command": "npx", "args": ["some-mcp-tool"],  // 本地进程
+      "env": {"API_KEY": "xxx"}
+    },
+    "remote": {
+      "url": "http://localhost:8000/mcp"            // 或 HTTP streaming
+    }
+  }
+}
+```
+
+`command` / `url` 二选一。保存后直接 `axi list` 就能看到新工具——daemon 会按需自动拉起连接。
+
+---
+
+## 自测（三步，必做）
+
+注册完后走一遍 Agent 视角的发现→调用路径，验证 schema 生成正确：
+
+```bash
+axi list                                    # 新 server / 工具出现了？
+axi search "你的工具描述里的关键词"           # 能被语义搜到？搜不到 → description 要改
+axi describe <server>/<tool>                # input_schema 字段、类型、required 对不对？
+axi run <server>/<tool> --key value          # 跑通，返回 {"status":"success","data":...}
+```
+
+**搜不到比跑不通更常见**——description 太短、只写了类名或方法名都会导致 BM25/Embedding 召回差。用几个真实查询跑 `axi search`，看你的工具有没有出现、排得够不够靠前。
+
+---
+
+## 导出为 MCP server（写一次，CLI + MCP 两用）
+
+注册进 axi 的工具（native 和 MCP 都行）可以一条命令变成 MCP server，挂给 Claude Desktop / Claude Code 等任何 MCP 客户端：
+
+```bash
+axi mcp --server my_tools    # 平铺：每个工具是独立 MCP tool（单 server 用裸名，多 server 加 server__ 前缀）
+axi mcp                      # 元工具：只暴露 search/grep/describe/run 四个工具，工具再多也不吃对端 context
+axi mcp --server a,b --transport http --port 8321    # HTTP 长驻服务
+```
+
+缺省形态自动判定：指定了 `--server` → 平铺，全量 → 元工具；`--flat` / `--meta` 强制覆盖。
+
+客户端配置示例——stdio 进程由客户端拉起、cwd 不可控，**必须在 env 里用 `AXI_CONFIG` 锚定配置**：
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "command": "axi",
+      "args": ["mcp", "--server", "my_tools"],
+      "env": { "AXI_CONFIG": "/path/to/axi.json" }
+    }
+  }
+}
+```
+
+---
+
+## 反模式
+
+- 函数签名用 `**kwargs` 或 `*args` — schema 提取不到参数，Agent 看到空 schema 会乱传
+- 所有参数都写 `str` — 失去类型约束和枚举提示，Agent 要靠 describe 里的自然语言猜
+- `description` 只写一个词（"搜索"、"查询"）— BM25 召回差、Embedding 语义稀薄
+- 返回不稳定结构（同一工具有时返 list 有时返 dict）— 下游 Agent 没法写聚合逻辑
+- 把敏感配置（API Key）硬编码在 `@tool` 函数里 — 走环境变量或 `mcpServers[...].env`
+- entry_points 的 value 写成文件路径 `"pkg/tools.py"` — 必须是可 import 的模块路径 `"pkg.tools"`
+
+---
+
+需要更多配置细节（`search` embedding、`daemon` idle 超时、`AXI_CONFIG` 环境变量改 axi.json 路径等）时，直接读源码：axi 包里的 `config.py` 是 Pydantic 模型，字段和默认值一目了然；`axi --help` 查命令参数。

axi_cli-0.0.7/skills/axi-use/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: axi-use
+description: 通过 `axi` CLI（或在 Python 中使用 `from axi import tool`）发现并调用工具。当任务需要执行外部工具（当前拥有<changeme>）请使用此skill。核心工作流程为：`axi search <query>` → `axi describe <tool>` → `axi run <tool> --key value`；当任务涉及多次调用之间的循环、聚合或后处理时，请优先使用 Python 进行处理。
+---
+
+# axi — Agent 使用手册
+
+axi 是当前环境里的工具调用层。有工具需求时，**先 `axi search`，再 `axi describe`，最后 `axi run`**，不要去翻代码或自己实现。
+
+## 何时用
+
+- 任务需要外部能力：web 搜索、知识库检索、注册过的 Python 函数、任何 MCP server 暴露的工具
+- 用户让你"调用某工具 / 搜索某工具 / 查某工具怎么用"
+
+工具可以来自三种渠道（对使用者透明，直接 `axi search` 就能找到）：`axi.json` 的 `mcpServers` / `nativeTools`，或 Python 包通过 entry_points 自动注册。配置文件位置由 `AXI_CONFIG` 环境变量指定，缺省 `~/.axi/axi.json`——**不会从当前目录自动发现**，项目级配置需要 `export AXI_CONFIG=/path/to/axi.json`。没有配置文件也不影响使用。
+
+## 三步工作流
+
+### 1. 发现工具 — `axi search` 或 `axi grep`
+
+两个命令覆盖两种场景，**按你当前知道什么来选**：
+
+| 你掌握的线索 | 用哪个 | 为什么 |
+|---|---|---|
+| 只有意图 / 能力描述（"web 搜索"、"查订单"） | `axi search` | BM25 + embedding 混合，支持中英文自然语言语义匹配 |
+| 已知工具名或 server 名的片段 / 模式 | `axi grep` | 正则直匹，精确、无语义噪声 |
+| 想看某个 server 下所有工具 | `axi list [server]` | 纯枚举，不做匹配（最后查找不到的兜底手段） |
+
+```bash
+axi search "web" --top-k 3
+# [{"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 list jina
+# [{"server":"jina","tools":["jina_reader","jina_search"]}]
+```
+
+### 2. 查看参数 — `axi describe`
+
+拿到候选后，用完整名（`server/tool` 或原生工具的短名）查 schema：
+
+```bash
+axi describe jina/jina_search
+```
+
+返回：
+
+```json
+{"name":"jina_search","server":"jina","description":"...",
+ "input_schema":{"type":"object",
+   "properties":{"query":{"type":"string","minLength":1},
+                 "count":{"type":"number","default":5},
+                 "siteFilter":{"type":"string"}},
+   "required":["query"]},
+ "source":"mcp"}
+```
+
+**只看 `input_schema.required` 就知道必传什么**；可选参数用默认值即可。
+
+### 3. 执行 — `axi run`
+
+两种传参方式，**优先用 `--key value`**：
+
+```bash
+# 推荐：键值对，自动 JSON 解析数字 / 布尔 / JSON 字面量（`--count 3` 就是 int，别加引号）
+axi run jina/jina_search --query "python async" --count 3
+
+# 复杂嵌套参数时：整体 JSON
+axi run jina/jina_search --json '{"query":"python async","count":3}'
+```
+
+返回统一信封：
+
+```json
+{"status":"success","data": ...}
+{"status":"error","error":"..."}
+```
+
+**`status` 字段决定分支**，不要靠退出码判断业务错误。
+
+## 易踩坑
+
+| 坑 | 正确做法 |
+|---|---|
+| `axi daemon start`（手动启动） | **不要。** MCP 工具首次调用自动拉起 daemon，空闲 30 分钟自动回收 |
+| MCP 工具没有 `output_example` | 批量处理前先 `axi run` 探一次真实返回结构，再写后续代码 |
+| 工具完整名搞错 | 直接用 `axi search` 返回的 `name` 字段作为完整名，不要自己拼接；所有工具（含原生）都有 `server/tool` 形式 |
+| MCP server 名和 npm 包名混淆 | 以 `axi.json` 里 `mcpServers` 的 **key** 为准（例如 key 是 `jina`，不是 `jina-mcp-tools`） |
+
+## 何时切 Python
+
+**单次调用走 CLI；需要循环 / 聚合 / 跨调用后处理时走 Python。** 别在 Python 里 `subprocess` 调 CLI（冷启进程 + 反复 JSON 序列化，既慢又费 token）——直接 import：
+
+```python
+from axi import tool
+
+search = tool("jina/jina_search")   # 返回可调用句柄，参数跟 `axi run --key value` 相同
+results = search(query="python best practices", count=3)
+```
+
+## 命令速查
+
+| 命令 | 用途 | 典型例子 |
+|---|---|---|
+| `axi search <q> [--top-k N]` | 按语义 / 意图找工具 | `axi search "订单" -k 5` |
+| `axi grep <regex> [--limit N]` | 按工具名 / 描述字面模式找工具 | `axi grep "retrieval"` |
+| `axi list [server]` | 枚举工具 | `axi list jina` |
+| `axi describe <tool>` | 查 input_schema | `axi describe jina/jina_search` |
+| `axi run <tool> --k v` 或 `--json '…'` | 执行 | `axi run jina/jina_search --query hi` |
+| `axi daemon status` | 看 daemon 是否在跑 | 调试 MCP 卡顿时用 |
+| `axi --help` / `axi <cmd> --help` | 查任何命令的完整参数 | 拿不准选项时首选 |
+
+> **下游项目**：如果你的仓库基于 axi 构建且有业务契约（时区、字段语义、输出结构约定等），在自己仓库再写一份项目级 SKILL.md 补这些——本 skill 只覆盖 axi 自身的调用接口。

{axi_cli-0.0.4 → axi_cli-0.0.7}/src/axi/__init__.py

@@ -64,14 +64,11 @@ def tool(
 
 def _make_daemon_caller(tool_name: str) -> Callable:
     """创建通过 daemon 调用 MCP 工具的 PTC 函数。"""
-    from axi.daemon.client import ensure_daemon, send_request
+    from axi.daemon.client import daemon_request
     from axi.daemon.protocol import DaemonRequest
 
     def _daemon_caller(**kwargs: Any) -> Any:
-        if not ensure_daemon():
-            raise RuntimeError("Daemon is not running. Start it with: axi daemon start")
-
-        resp = send_request(
+        resp = daemon_request(
             DaemonRequest(method="call_tool", tool_name=tool_name, params=kwargs)
         )
         if resp.status == "error":