read

功能

读取指定路径的文件内容。支持偏移量和行数限制，适合读取大文件的部分内容。

参数

使用示例

# 读取完整文件
read(path: "src/main.rs")

# 读取前50行
read(path: "src/main.rs", limit: 50)

# 从第100行开始读取
read(path: "src/main.rs", offset: 100, limit: 50)

write

功能

写入文件内容。若文件不存在则创建，若存在则覆盖。单次写入最大 10MB。

参数

使用示例

# 创建新文件
write(path: "lib.rs", content: "pub fn hello() {\n    println!(\"Hello!\");\n}")

# 写入配置文件
write(path: "config.json", content: "{\n  \"debug\": true\n}")

edit

功能

在文件中查找精确匹配的字符串并替换为新内容。适合单处代码修改。

参数

使用示例

# 修改函数名
edit(path: "main.rs", old_string: "fn main() {", new_string: "fn run() {")

# 修改导入路径
edit(path: "lib.rs", old_string: "use crate::old;", new_string: "use crate::new;")

multi_edit

功能

对单个文件应用多处精确字符串替换，一次性原子写入。若任一编辑失败，文件不会被修改。

参数

使用示例

# 批量替换多处
multi_edit(path: "lib.rs", edits: [
    {old_string: "fn old1()", new_string: "fn new1()"},
    {old_string: "fn old2()", new_string: "fn new2()"},
    {old_string: "// TODO", new_string: "// DONE"}
])

ls

功能

列出目录的直接条目。每行一个条目，目录在前（以 / 结尾），文件在后并显示字节大小。不递归。

参数

使用示例

# 列出当前目录
ls()

# 列出指定目录
ls(path: "./src")

# 输出示例：
# src/
# tests/
# Cargo.toml  524
# README.md   2841

glob

功能

通过 glob 模式查找文件路径。支持 *、? 和递归 **。返回匹配路径，按修改时间排序。

参数

使用示例

# 查找所有 Rust 文件
glob(pattern: "**/*.rs")

# 查找配置文件
glob(pattern: "*.toml", path: "./config")

# 查找测试文件
glob(pattern: "**/test*.rs")

grep

功能

搜索文本内容（错误消息、注释、字符串等）。支持正则表达式和文件类型过滤。

适用场景

• 搜错误信息（如 'failed to connect'、'panic'）
• 找注释内容（如 'TODO'、'FIXME'）
• 搜字符串常量、日志文本

参数

使用示例

# 搜索 unwrap 使用
grep(pattern: "unwrap()", type: "rs")

# 搜索 TODO 注释
grep(pattern: "TODO", path: "./src")

# 忽略大小写搜索错误
grep(pattern: "error", -i: true)

# 搜索并显示上下文
grep(pattern: "fn main", -C: 3)

search

功能

在文件内容中搜索匹配的文本模式。与 grep 类似，支持 glob 文件过滤。

参数

bash

功能

在当前工作目录执行 shell 命令。支持构建、测试、git、包管理器操作。

适用场景

• 构建和测试：cargo build、cargo test
• Git 操作：git status、git log
• 包管理：npm install、pip install
• 系统命令：ls -la、find、tree

参数

使用示例

# 构建项目
bash(command: "cargo build --release")

# 运行测试
bash(command: "cargo test")

# Git 状态
bash(command: "git status")

# 长时间运行的命令
bash(command: "cargo build", timeout_ms: 300000)

code_status

功能

检查 CodeGraph 索引状态。返回文件数、节点数、边数、支持的语言等信息。

使用示例

# 检查索引状态
code_status()

# 输出示例：
# Files: 45
# Nodes: 523
# Edges: 1024
# Languages: Rust, TypeScript

code_sync

功能

手动同步 CodeGraph 索引。当代码库有变化但自动同步未触发时使用。

websearch

功能

使用 DuckDuckGo 搜索网络信息。返回标题、URL 和摘要的搜索结果列表。

参数

使用示例

# 搜索 Rust 最佳实践
websearch(query: "Rust async best practices")

# 搜索文档
websearch(query: "tokio documentation", max_results: 10)

webfetch

功能

从 URL 获取内容并返回为文本。适合获取文档、API 说明等。

参数

使用示例

# 获取文档
webfetch(url: "https://docs.rs/tokio")

# 获取 API 说明
webfetch(url: "https://api.example.com/docs")

task

功能

启动新代理处理复杂的多步骤任务。每个代理独立运行，可并行处理不同任务。

适用场景

• 需要多次查询的研究任务
• 可在后台运行的长时间操作
• 需与主上下文隔离的任务
• 可并行执行的多个独立任务

参数

使用示例

# 启动研究任务
task(description: "研究依赖", prompt: "分析项目的依赖关系和版本兼容性")

# 后台运行任务
task(description: "生成文档", prompt: "...", run_in_background: true)

monitor

功能

监控外部进程或等待状态变化。

适用场景

• 等待构建/测试完成
• 监视文件变化
• 监控后台服务
• 跟踪进程状态

参数

todo_write

功能

维护结构化待办列表，用于规划和跟踪多步骤工作。

适用场景

• 多步骤任务（3步以上）需要展示进度
• 复杂实现需要规划

参数

使用示例

todo_write(todos: [
    {content: "分析代码结构", activeForm: "正在分析代码结构", status: "in_progress"},
    {content: "设计重构方案", activeForm: "正在设计重构方案", status: "pending"},
    {content: "实现重构", activeForm: "正在实现重构", status: "pending"}
])

ask

功能

当遇到不确定或多种选择时，向用户提问以获取明确指示。

何时使用

• 用户请求含义模糊
• 存在多种可行方案需要选择
• 决策可能对项目产生重大影响
• 用户说 "怎么处理"、"选哪个"、"你觉得呢" 时

何时不使用

• 简单问题不需要确认（明显最优、低风险、可逆）
• 任务可以直接执行不需要用户决策
• 用户说 "开始做"、"直接改" 时

skill

功能

加载指定技能的完整指令。技能匹配用户请求时，必须在生成任何其他响应前调用。

可用技能

• om - 分步规划模式
• refactor - 代码重构技能

使用示例

# 加载重构技能
skill(name: "refactor")

plan_mode (enter_plan_mode / exit_plan_mode)

功能

进入规划模式，在执行前设计实现方案。

适用场景

• 需要规划的非 trivial 实现任务
• 可受益于架构考量的问题
• 可能产生重大影响的变更