[OSS26] 读取文件内容 read_file_by_path

[ponyha]

接口介绍

给定文件路径,在仓库范围内安全读取文件内容,支持按行号区间读取大文件;返回内容连同元数据(语言、编码、行数、是否截断)。强制拒绝路径穿越与越界读取。

工具名

read_file_by_path

背景与目标

LLM Agent 在拿到代码位置之后第一时间要"看代码"。虽然 host 本身可能有文件读取能力,但通过 MCP tool 暴露的读取有三点价值:

1. 范围约束:限定只允许读 repository_path 内的文件,避免越权
2. 行级范围:支持指定行号区间读取,适合大文件场景
3. 代码模式:返回时带元数据(语言、编码、行数),便于 Agent 后续工具串接

输入参数

参数	类型	必填	说明
file_path	string	是	文件路径,必须在 repository_path 下
repository_path	string	是	仓库根目录(用于路径合法性校验)
start_line	int	否	起始行,1-based,不填读全文
end_line	int	否	结束行,1-based,包含。不填配合 start_line 时读到文件尾
max_bytes	int	否	默认 1MB,超出截断

输出结构

{
  "file_path": "src/main/java/com/example/UserController.java",
  "language": "java",
  "encoding": "utf-8",
  "total_lines": 245,
  "returned_lines": {"start": 1, "end": 245},
  "size_bytes": 8912,
  "content": "package com.example;\n\nimport ...\n\npublic class UserController { ... }\n",
  "truncated": false
}

验收标准

• 拒绝 .. 路径穿越攻击
• 拒绝读取 repository_path 之外的路径
• 二进制文件返回错误而不是乱码内容
• start_line / end_line 范围超界自动 clamp
• 单元测试覆盖:路径越权、二进制文件、空文件、超大文件截断

预估工作量

0.5-1 人日(适合新手)