tooli (Weisberg)

工具

 ](https://pypi.org/project/tooli/)  

Python的代理原生CLI框架。 编写一个函数，获得一个CLI、一个MCP工具和一个自文档模式。

Tooli将键入的Python函数转换为CLI命令，这些命令同时对人类友好（富输出、shell补全）和机器可消费（JSON模式、结构化输出、MCP兼容性）。您的工具不需要单独的“代理版本”。

名称来源于“tool”+“CLI”=“tooli”。

______________________________________________________________________

问题

AI代理每天调用数千个CLI命令，但标准CLI是为人类设计的：

• 交互式提示挂起代理 无法导航寻呼机或密码对话框
• 非结构化输出浪费代币 --代理使用正则表达式解析文本，而不是读取JSON
• 模糊的错误会妨碍自我纠正 --“错误：无效输入”使代理无法使用
• 无法发现 --特工们对无证工具产生了幻觉

Tooli将CLI视为 结构化协议 而不是文本界面。一个经过修饰的函数生成一个CLI命令、一个JSON模式、一个MCP工具定义、带有恢复建议的结构化错误和自动生成的文档——所有这些都来自一个单一的事实来源。

______________________________________________________________________

当前状态（v6.6.0）

Tooli v6.6.0已准备就绪，并发布于 PyPI该框架实现了其PRD中定义的完整功能集，并在Python 3.10+上扩展了测试套件。

今天有什么船

______________________________________________________________________

安装

pip install tooli

可选附加功能：

pip install tooli[mcp]   # MCP server support (fastmcp)
pip install tooli[api]   # HTTP API server (starlette, uvicorn) -- experimental

______________________________________________________________________

快速开始

from tooli import Tooli, Annotated, Option, Argument
from tooli.annotations import ReadOnly, Idempotent
from pathlib import Path

app = Tooli(
    name="file-tools",
    description="File manipulation utilities",
    version="6.6.0",
)

@app.command(
    annotations=ReadOnly | Idempotent,
    examples=[
        {"args": ["--pattern", "*.py", "--root", "/project"],
         "description": "Find all Python files in a project"},
    ],
)
def find_files(
    pattern: Annotated[str, Argument(help="Glob pattern to match files")],
    root: Annotated[Path, Option(help="Root directory to search from")] = Path("."),
    max_depth: Annotated[int, Option(help="Maximum directory depth")] = 10,
) -> list[dict]:
    """Find files matching a glob pattern in a directory tree."""
    results = []
    for path in root.rglob(pattern):
        results.append({"path": str(path), "size": path.stat().st_size})
    return results

if __name__ == "__main__":
    app()

人类使用

$ file-tools find-files "*.py" --root ./src
┌──────────────────────┬───────┐
│ Path                 │ Size  │
├──────────────────────┼───────┤
│ src/main.py          │ 1,204 │
│ src/utils.py         │   892 │
└──────────────────────┴───────┘

代理使用

$ file-tools find-files "*.py" --root ./src --json
{
  "ok": true,
  "result": [
    {"path": "src/main.py", "size": 1204},
    {"path": "src/utils.py", "size": 892}
  ],
  "meta": {"tool": "file-tools.find-files", "version": "6.6.0", "duration_ms": 34}
}

架构导出

$ file-tools find-files --schema
{
  "name": "find-files",
  "description": "Find files matching a glob pattern in a directory tree.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pattern": {"type": "string", "description": "Glob pattern to match files"},
      "root": {"type": "string", "default": ".", "description": "Root directory to search from"},
      "max_depth": {"type": "integer", "default": 10, "description": "Maximum directory depth"}
    },
    "required": ["pattern"]
  },
  "annotations": {"readOnlyHint": true, "idempotentHint": true}
}

MCP服务器模式

$ file-tools mcp serve --transport stdio
$ file-tools mcp serve --transport http --host 127.0.0.1 --port 8080
$ file-tools mcp serve --transport sse --host 127.0.0.1 --port 8080

添加到MCP客户端配置中，每个命令都会变成一个工具。

______________________________________________________________________

结构化错误

当出现问题时，代理会收到可操作的恢复指导，而不是不透明的消息：

$ file-tools find-files "*.rs" --root ./src --json
{
  "ok": false,
  "error": {
    "code": "E3001",
    "category": "state",
    "message": "No files matched pattern '*.rs' in ./src",
    "suggestion": {
      "action": "retry_with_modified_input",
      "fix": "The directory contains .py files. Try pattern '*.py' instead.",
      "example": "find-files '*.py' --root ./src"
    },
    "is_retryable": true
  }
}

______________________________________________________________________

输出模式

Tooli会自动检测正确的输出格式，也可以显式检测：

______________________________________________________________________

输入统一

这 StdinOr[T] type使文件、URL和管道数据可互换：

from tooli import StdinOr

@app.command()
def process(
    input_data: Annotated[StdinOr[Path], Argument(help="Input file, URL, or stdin")],
) -> dict:
    """Process data from any input source."""
    ...

# All equivalent:
$ file-tools process data.csv
$ file-tools process https://example.com/data.csv
$ cat data.csv | file-tools process -

______________________________________________________________________

试运行计划

执行前预览副作用：

from tooli import dry_run_support, record_dry_action

@app.command(annotations=Destructive)
@dry_run_support
def deploy(target: str) -> dict:
    record_dry_action("upload", target, details={"size": "12MB"})
    record_dry_action("restart", f"{target}-service")
    # ... actual deployment logic

$ file-tools deploy production --dry-run --json
{
  "ok": true,
  "result": [
    {"action": "upload", "target": "production", "details": {"size": "12MB"}},
    {"action": "restart", "target": "production-service"}
  ],
  "meta": {"dry_run": true}
}

______________________________________________________________________

自动生成的文档

# Agent-readable skill documentation (external package)
$ tooli-docs skill examples/docq/app.py:app --output SKILL.md
$ tooli-docs claude-md examples/docq/app.py:app --output CLAUDE.md
$ tooli-docs agents-md examples/docq/app.py:app --output AGENTS.md

# Framework wrappers (external package)
$ tooli-export openai examples/docq/app.py:app --mode import > tools_openai.py
$ tooli-export langchain examples/docq/app.py:app --mode import > tools_langchain.py

# LLM-friendly docs (llms.txt standard)
$ file-tools docs llms

# Unix man page
$ file-tools docs man

有用的验证和自动化流程：

• 使用 --schema 对于严格的指挥合同。
• 使用 tooli-docs ... --from-schema schema.json 对于模式驱动的文档。
• 围绕信封形状使用CI断言(ok/result/meta)以及错误代码。

迁移指南：请参阅 MIGRATION_v5_to_v6.md （v5至v6）。旧指南存档于 docs/archive/migration/.

______________________________________________________________________

全球旗帜

每个Tooli命令都会自动获得：

--output, -o       auto|json|jsonl|text|plain
--json/--jsonl     Convenience aliases
--quiet, -q        Suppress non-essential output
--verbose, -v      Increase verbosity (-vvv)
--dry-run          Preview without executing
--yes              Skip confirmation prompts (for automation/agents)
--no-color         Disable colors (also respects NO_COLOR)
--print0           Emit NUL-separated output for list types in text/plain modes
--timeout          Max execution time in seconds
--null             Parse NUL-delimited list input from stdin (list-processing)
--schema           Print JSON Schema and exit
--response-format  concise|detailed
--help-agent       Token-optimized help for agents

______________________________________________________________________

建筑

Tooli构建在Python类型+装饰器管道的基础上，添加了一个并行模式生成路径：

          @app.command()
     Python function + type hints
            |              |
            v              v
      CLI Pipeline    Schema Pipeline
     -> CLI params     -> Pydantic model
     -> CLI parser     -> JSON Schema
            |              |
            v              v
      CLI Output       Agent Output
      Rich tables      MCP tool schema
      Completions      SKILL.md / JSON

关键设计决策：

• 库-第一个API --公共界面是Tooli原生的（没有框架对象泄露到用户代码中）
• Pydantic模式 --与FastAPI和FastMCP相同的管道
• 函数保持可调用性 --无突变；测试与 CliRunner 或者直接用Python调用

______________________________________________________________________

示例

这 examples/ 目录包含18个使用Tooli构建的完整CLI应用程序，每个应用程序都展示了不同的功能：

请参阅 示例README 查看18个应用程序的完整列表和使用指南。

______________________________________________________________________

版本历史

• v6.6.0 （当前）--错误修复版本：CLI崩溃 T | None 参数、恢复的触发器/反触发程序/规则元数据（#202、#203）。
• v6.5.0版本 --v6发布线，包括核心清理、提取跟进和可靠性改进。
• v6.0 --提取和清理释放。文档和导出生成转移到外部包(tooli-docs, tooli-export)；拆下了弃用的内部垫片。
• v5.0 --通用代理工具接口。添加了Python API、功能、切换元数据和AGENTS.md生成。
• v4.1 --呼叫者感知代理运行时。 TOOLI_CALLER 常规、5类启发式检测， detect-context 内置、信封/遥测/录音中的呼叫者元数据、自适应确认和帮助格式化。
• v4.0 --Agent Skill Platform基础和模式优先工作流。
• v2.0 --代理环境接口。MCP桥、编排运行时、延迟发现、令牌预算、Python eval模式。
• v1.0 --核心框架。双模输出、结构化错误、JSON模式、MCP服务器、注释、分页、可观察性。

看 更改日志.md 了解完整细节和 docs/MIGRATION_v5_to_v6.md 了解最新的升级步骤。

______________________________________________________________________

发展

# Clone and install for development
git clone https://github.com/weisberg/tooli.git
cd tooli
pip install -e ".[dev]"

# Run tests
pytest

# Lint and type check
ruff check .
mypy tooli

看 贡献.md 作为指导方针。

许可证

MIT许可证。看 许可证 了解详情。