[OSS26] 读取文件内容 read_file_by_path

接口介绍

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

工具名

read_file_by_path

背景与目标

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

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

输入参数

输出结构

{
  "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 人日(适合新手)

Start by locating the TypeScript entry point and tool registration for read_file_by_path, then inspect how existing tools validate inputs and return errors. Add unit tests for path traversal, outside-repository paths, binary and empty files, and truncation; done means the listed metadata and line-range behavior are covered and unsafe reads are rejected.