路径信息工具¶

PathInfo 工具提供单次调用获取文件和目录元数据的接口。

类概述¶

PathInfo - 统一的元数据查询，单次调用返回存在性、类型、大小、修改时间和权限信息。

使用方法¶

基本用法¶

from toolregistry_hub import PathInfo

# 查询文件
info = PathInfo.info("/path/to/file.py")
print(info)
# {
#     "exists": True,
#     "type": "file",
#     "size": 1234,
#     "last_modified": "2026-03-18T12:00:00+00:00",
#     "permissions": "rw-r--r--"
# }

# 查询目录（大小为递归计算）
info = PathInfo.info("/path/to/dir")
print(info["size"])  # 目录下所有文件的总大小

# 不存在的路径
info = PathInfo.info("/does/not/exist")
print(info)  # {"exists": False}

返回值¶

当路径存在时，info() 返回包含以下键的字典：

键	类型	描述
`exists`	`bool`	路径存在时始终为 `True`
`type`	`str`	`"file"`、`"directory"`、`"symlink"` 或 `"other"`
`size`	`int`	大小（字节）。目录为所有内容的递归总大小
`last_modified`	`str`	UTC 时区的 ISO 8601 时间戳
`permissions`	`str`	Unix 风格权限字符串（如 `"rwxr-xr-x"`）

路径不存在时，仅返回 {"exists": False}。

设计理念¶

PathInfo 用单次调用返回多个元数据字段（存在性、类型、大小、修改时间、权限），减少了 Agent 工作流中所需的工具调用次数，因为 LLM 通常需要同时获取多个元数据字段。

MCP 服务端点¶

POST /tools/fs/path_info/info

参数：

参数	类型	必填	描述
`path`	`string`	是	要查询的绝对或相对路径

API 参考¶

toolregistry_hub.path_info.PathInfo ¶

File and directory metadata query.

info `staticmethod` ¶

info(path: str) -> dict

Get metadata for a file or directory in a single call.

Parameters:

Name	Type	Description	Default
`path`	`str`	Absolute or relative path to query.	required

Returns:

Type	Description
`dict`	A dict with keys: - exists (bool) - type ("file" \| "directory" \| "symlink" \| "other") - size (int, bytes) — for directories, total size of contents - last_modified (str, ISO 8601 in UTC) - permissions (str, e.g. "rwxr-xr-x")
`dict`	If path does not exist, returns `{"exists": False}`.

Source code in toolregistry_hub/path_info.py

@staticmethod
def info(path: str) -> dict:
    """Get metadata for a file or directory in a single call.

    Args:
        path: Absolute or relative path to query.

    Returns:
        A dict with keys:
            - exists (bool)
            - type ("file" | "directory" | "symlink" | "other")
            - size (int, bytes) — for directories, total size of contents
            - last_modified (str, ISO 8601 in UTC)
            - permissions (str, e.g. "rwxr-xr-x")

        If path does not exist, returns ``{"exists": False}``.
    """
    p = Path(path)

    if not p.exists():
        return {"exists": False}

    st = p.stat()

    # Determine type
    if p.is_symlink():
        path_type = "symlink"
    elif p.is_file():
        path_type = "file"
    elif p.is_dir():
        path_type = "directory"
    else:
        path_type = "other"

    # Calculate size — recursive for directories
    if p.is_dir():
        size = sum(f.stat().st_size for f in p.rglob("*") if f.is_file())
    else:
        size = st.st_size

    # ISO 8601 timestamp in UTC
    last_modified = datetime.fromtimestamp(st.st_mtime, tz=timezone.utc).isoformat()

    # Human-readable permissions string (e.g. "rwxr-xr-x")
    permissions = stat.filemode(st.st_mode)[1:]  # strip leading type char

    return {
        "exists": True,
        "type": path_type,
        "size": size,
        "last_modified": last_modified,
        "permissions": permissions,
    }