An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
TypeScript agentic-aiai-agentknowledge-baselocal-firstmarkdownmcpmindmapnote-takingself-hostedsiyuanworkspace
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later
package tools
import (
"bufio"
"context"
"encoding/json"
"errors"
"fmt"
"math"
"os"
"path/filepath"
"regexp"
"slices"
"strings"
"unicode/utf8"
"github.com/siyuan-note/siyuan/kernel/model"
"github.com/siyuan-note/siyuan/kernel/util"
"github.com/88250/gulu"
"github.com/siyuan-note/logging"
)
var FileTool = &Tool{
Name: "file",
Description: "Workspace file operations (paths relative to workspace; debugging/log reading and approved plugin development only — never use for workspace data). Actions: list, read, write, edit, delete, rename, copy, grep, find, stat. read defaults to legacy plain text/200 lines; withMetadata=true returns bounded JSON with whole-file SHA256, UTF-8 byte range, truncation and nextOffsetByte. Continue with byteOffset and the same expectedRevision; only startByte=0/endByte=totalBytes/truncated=false is a complete read. edit requires expectedRevision and unique nonempty oldText/newText anchors against the original file; conflicts reject the entire edit. write may opt into ifAbsent=true or expectedRevision for safe conditional writes (including empty data); parent directories must exist. Safe text operations reject links, binary/non-UTF-8 and files above 8 MiB. Approved managed plugin sources always require safe conditions and trusted workflow context; copy/directory mutation is unavailable there.",
InputSchema: ToolSchema{
Type: "object",
Properties: map[string]Property{
"action": {Type: "string", Description: "Operation", Enum: []string{"list", "read", "write", "edit", "delete", "rename", "copy", "grep", "find", "stat"}},
"path": {Type: "string", Description: "Relative path within workspace (for list, read, write, edit, delete, grep, find, stat)"},
"data": {Type: "string", Description: "File content (for write)"},
"offset": {Type: "number", Description: "Line number to start reading from (for read, 1-based). Negative means N lines from the end. Default: 0 (read from beginning)."},
"limit": {Type: "number", Description: "Maximum lines/files/entries to return (for read, list, find, grep). Default: 200 lines when offset and limit are both 0 for read, 200 for list/find/grep. Use 0 or negative for unlimited."},
"old": {Type: "string", Description: "Source path (for rename)"},
"new": {Type: "string", Description: "Destination path (for rename)"},
"src": {Type: "string", Description: "Source path (for copy)"},
"dst": {Type: "string", Description: "Destination path (for copy)"},
"pattern": {Type: "string", Description: "Regex pattern to search for (for grep)"},
"include": {Type: "string", Description: "File glob pattern to filter files (for grep, find; e.g. \"*.go\", \"*.{ts,tsx}\")"},
"context": {Type: "number", Description: "Number of context lines before and after each match (for grep, default 0)"},
"withMetadata": {Type: "boolean", Description: "Opt-in bounded JSON read with complete file revision and exact UTF-8 byte range"},
"byteOffset": {Type: "integer", Description: "UTF-8 byte boundary for a metadata read; cannot combine with offset"},
"lineLimit": {Type: "integer", Description: "Optional metadata read line limit; default 200, nonpositive for unlimited subject to JSON budget"},
"expectedRevision": {Type: "string", Description: "Raw whole-file SHA256 from metadata read; required for edit and managed replace/delete/rename"},
"ifAbsent": {Type: "boolean", Description: "Conditional write: create only if no target exists; mutually exclusive with expectedRevision"},
"dryRun": {Type: "boolean", Description: "Preview an edit without applying it; still requires normal write permissions"},
"edits": {Type: "array", Description: "1 to 128 exact replacements against the original file", Items: &Property{Type: "object", Properties: map[string]Property{
"oldText": {Type: "string", Description: "Nonempty anchor occurring exactly once"},
"newText": {Type: "string", Description: "Replacement text; may be empty"},
}, Required: []string{"oldText", "newText"}}},
},
Required: []string{"action"},
},
EffectScope: EffectScopeLocal,
ActionEffects: map[string]ToolEffects{
"list": {LocalRead: true}, "read": {LocalRead: true}, "grep": {LocalRead: true}, "find": {LocalRead: true}, "stat": {LocalRead: true},
"write": {LocalRead: true, LocalWrite: true}, "edit": {LocalRead: true, LocalWrite: true},
"delete": {LocalRead: true, LocalWrite: true}, "rename": {LocalRead: true, LocalWrite: true}, "copy": {LocalRead: true, LocalWrite: true},
},
Handler: fileHandler,
ContextHandler: fileContextHandler,
}
func init() {
register(FileTool)
}
func fileHandler(args map[string]any) (CallToolResult, error) {
return fileContextHandler(context.Background(), args)
}
func fileContextHandler(ctx context.Context, args map[string]any) (CallToolResult, error) {
if err := ctx.Err(); err != nil {
return fileSafeError(err)
}
action, _ := args["action"].(string)
if dryRun, _ := args["dryRun"].(bool); dryRun && action != "edit" {
return fileSafeError(fileInvalid("invalid_argument", "dryRun is supported only for edit"))
}
for _, key := range []string{"path", "old", "new", "src", "dst"} {
if p, ok := args[key].(string); ok && p != "" && util.IsPluginProjectPath(filepath.Join(util.WorkspaceDir, filepath.FromSlash(p))) {
return fileManaged(ctx, args)
}
}
switch action {
case "list":
return fileList(args)
case "read":
return fileRead(args)
case "write":
if fileConditionalWrite(args) {
return fileMutate(ctx, args)
}
return fileWrite(args)
case "edit":
return fileMutate(ctx, args)
case "delete":
return fileDelete(args)
case "rename":
return fileRename(args)
case "copy":
return fileCopy(args)
case "grep":
return fileGrep(args)
case "find":
return fileFind(args)
case "stat":
return fileStat(args)
}
return CallToolResult{
Content: []ContentItem{{Type: "text", Text: "unknown action '" + action + "', expected one of: [list, read, write, edit, delete, rename, copy, grep, find, stat]"}},
IsError: true,
}, nil
}
func resolvePath(rel string) (string, error) {
rel = filepath.Clean(strings.ReplaceAll(rel, "/", string(os.PathSeparator)))
abs := filepath.Join(util.WorkspaceDir, rel)
if err := authorizePath(abs, rel); err != nil {
return "", err
}
return abs, nil
}
// authorizePath 校验单个最终路径是否允许访问,display 仅用于错误信息:顶层调用传工作区相对路径,
// 递归遍历、目录拷贝和压缩包解压传最终路径本身。
func authorizePath(abs, display string) error {
if !gulu.File.IsSubPath(util.WorkspaceDir, abs) {
return fmt.Errorf("path escapes workspace: %s", display)
}
// 拒绝加密笔记本目录:MCP 文件工具不能读写加密 box 下的文件(防止密文泄漏或明文破坏加密格式)
if boxID, encrypted := rejectEncryptedPath(abs); encrypted {
return fmt.Errorf("path belongs to encrypted notebook [%s]: %s", boxID, display)
}
// 防止 symlink 逃逸工作区:解析符号链接后再次检查
if resolved := util.ResolveLongestExistingParent(abs); resolved != abs && !gulu.File.IsSubPath(util.WorkspaceDir, resolved) {
return fmt.Errorf("symlink escapes workspace: %s", display)
}
// 禁止访问敏感文件(conf/conf.json、data/snippets/conf.json、data/templates、data/.siyuan/publishAccess.json),
// 与 HTTP 文件 API 共用同一黑名单(见 kernel/util/path_guard.go 的 IsForbiddenAbsPath)
if util.IsForbiddenAbsPath(abs) {
return fmt.Errorf("access to sensitive workspace file is forbidden: %s", display)
}
return nil
}
// authorizeFinalPath 对即将打开或创建的最终路径做授权。resolvePath 只覆盖调用方给出的路径,
// 容器路径合法不代表其后代合法:递归遍历、复制、解压、删除、重命名都必须对每一个后代路径再次调用本函数。
func authorizeFinalPath(abs string) error {
return authorizePath(abs, abs)
}
// authorizeSubtree 校验路径及其全部后代,任一后代被拒绝即整体拒绝。删除和重命名是目录级操作,
// 只校验目录本身会让受保护的后代被删除或搬出黑名单范围(例如 file.delete("conf"))。
// 使用 Lstat:删除和重命名不会跟随符号链接,与 os.RemoveAll、os.Rename 的语义保持一致。
func authorizeSubtree(abs string) error {
if util.IsPluginDevelopmentRawPathForbidden(abs, true) {
return fmt.Errorf("raw modification of managed plugin or agent state paths is forbidden: %s", abs)
}
if err := authorizeFinalPath(abs); err != nil {
return err
}
info, err := os.Lstat(abs)
if err != nil {
if os.IsNotExist(err) {
return nil
}
return err
}
if !info.IsDir() {
return nil
}
entries, err := os.ReadDir(abs)
if err != nil {
return err
}
for _, entry := range entries {
if err = authorizeSubtree(filepath.Join(abs, entry.Name())); err != nil {
return err
}
}
return nil
}
// authorizeCopyTree 预检整棵复制树:源与目标的每一个最终路径都必须通过授权,任一被拒绝即整体拒绝。
// 这样可以同时避免把受保护的后代复制到普通路径后绕过读取限制,以及被拒绝时的部分复制。
// 使用 Stat:复制会跟随符号链接,与 copyPath 的语义保持一致。
func authorizeCopyTree(src, dst string) error {
if util.IsPluginDevelopmentRawPathForbidden(src, true) || util.IsPluginDevelopmentRawPathForbidden(dst, true) {
return fmt.Errorf("raw copy of managed plugin or agent state paths is forbidden")
}
if err := authorizeFinalPath(src); err != nil {
return err
}
if err := authorizeFinalPath(dst); err != nil {
return err
}
info, err := os.Stat(src)
if err != nil {
return err
}
if !info.IsDir() {
return nil
}
entries, err := os.ReadDir(src)
if err != nil {
return err
}
for _, entry := range entries {
if err = authorizeCopyTree(filepath.Join(src, entry.Name()), filepath.Join(dst, entry.Name())); err != nil {
return err
}
}
return nil
}
// rejectEncryptedPath 检查路径是否属于加密笔记本(含 symlink 绕过),返回 boxID 和是否为加密 box。
func rejectEncryptedPath(absPath string) (boxID string, encrypted bool) {
boxID = model.EncryptedRawPathBoxID(absPath)
return boxID, boxID != ""
}
func fileList(args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
dir, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
entries, err := os.ReadDir(dir)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "read dir failed: " + err.Error()}}, IsError: true}, nil
}
// 受保护的后代不出现在列表中,避免经允许目录枚举出敏感文件
visible := make([]os.DirEntry, 0, len(entries))
for _, entry := range entries {
if authorizeFinalPath(filepath.Join(dir, entry.Name())) != nil {
continue
}
visible = append(visible, entry)
}
entries = visible
max := resolveLimit(args, 200)
total := len(entries)
if max > 0 && max < total {
entries = entries[:max]
}
var sb strings.Builder
fmt.Fprintf(&sb, "Directory: %s (%d entries)\n\n", p, total)
for _, e := range entries {
info, _ := e.Info()
size := ""
if info != nil {
size = fmt.Sprintf("%d", info.Size())
}
fmt.Fprintf(&sb, "- %s [%s] %s\n", e.Name(), typeLabel(e.IsDir()), size)
}
if max > 0 && max < total {
fmt.Fprintf(&sb, "\n...output limited to %d of %d entries. Use limit parameter to adjust.", max, total)
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: sb.String()}}}, nil
}
func getFloat64Arg(args map[string]any, key string) float64 {
if v, ok := args[key]; ok {
if f, ok := v.(float64); ok {
return f
}
}
return 0
}
func resolveLimit(args map[string]any, defaultLimit int) int {
if _, exists := args["limit"]; !exists {
return defaultLimit
}
return int(getFloat64Arg(args, "limit"))
}
func fileRead(args map[string]any) (CallToolResult, error) {
if metadata, _ := args["withMetadata"].(bool); metadata {
return fileReadMetadata(args)
}
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
data, err := os.ReadFile(abs)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "read file failed: " + err.Error()}}, IsError: true}, nil
}
return fileLegacyReadContent(args, data)
}
func fileLegacyReadContent(args map[string]any, data []byte) (CallToolResult, error) {
offset := int(getFloat64Arg(args, "offset"))
limit := int(getFloat64Arg(args, "limit"))
if offset == 0 && limit == 0 {
limit = 200
}
lines := strings.Split(string(data), "\n")
total := len(lines)
if offset < 0 {
offset = max(total+offset, 0)
} else {
offset--
if offset < 0 {
offset = 0
}
}
end := total
if limit > 0 {
end = min(offset+limit, total)
}
if offset >= total {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: fmt.Sprintf("(file has %d lines, offset out of range)", total)}}, IsError: true}, nil
}
result := strings.Join(lines[offset:end], "\n")
return CallToolResult{Content: []ContentItem{{Type: "text", Text: result}}}, nil
}
func fileWrite(args map[string]any) (CallToolResult, error) {
if fileConditionalWrite(args) {
return fileMutate(context.Background(), args)
}
p, _ := args["path"].(string)
dataStr, _ := args["data"].(string)
if p == "" || dataStr == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path and data are required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
if util.IsPluginDevelopmentRawWriteForbidden(abs) {
return fileSafeError(fileInvalid(util.TextFileInvalidPath, "raw write to a managed plugin or delivery path is forbidden"))
}
if err := os.MkdirAll(filepath.Dir(abs), 0755); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "mkdir failed: " + err.Error()}}, IsError: true}, nil
}
if err := os.WriteFile(abs, []byte(dataStr), 0644); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "write file failed: " + err.Error()}}, IsError: true}, nil
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "file written: " + p}}}, nil
}
const fileJSONBudget = 32000
type fileReadPage struct {
Path string `json:"path"`
Revision string `json:"revision"`
TotalBytes int `json:"totalBytes"`
TotalLines int `json:"totalLines"`
StartByte int `json:"startByte"`
EndByte int `json:"endByte"`
Content string `json:"content"`
Truncated bool `json:"truncated"`
NextOffsetByte *int `json:"nextOffsetByte"`
Encoding string `json:"encoding"`
Newline string `json:"newline"`
}
func fileSafeError(err error) (CallToolResult, error) {
var failure *util.TextFileError
if !errors.As(err, &failure) {
failure = &util.TextFileError{Code: util.TextFileWriteFailed, Message: err.Error()}
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
failure.Code = util.TextFileCancelled
} else if errors.Is(err, os.ErrNotExist) {
failure.Code = util.TextFileInvalidPath
}
}
// 系统错误可能包含输入路径;复制后限制错误文本,避免共享输出截断器破坏错误 JSON 或修改调用方对象。
copy := *failure
failure = ©
if len(failure.Message) > 4000 {
end := 4000
for end > 0 && !utf8.RuneStart(failure.Message[end]) {
end--
}
failure.Message = failure.Message[:end] + "..."
}
encoded, _ := json.Marshal(failure)
return CallToolResult{Content: []ContentItem{{Type: "text", Text: string(encoded)}}, StructuredContent: failure, StructuredContentSet: true, IsError: true, ExecutionUnknown: failure.Code == util.TextFileResultUnknown}, nil
}
func fileInvalid(code, message string) error {
return &util.TextFileError{Code: code, Message: message}
}
func fileJSONResult(value any) (CallToolResult, error) {
encoded, err := json.Marshal(value)
if err != nil {
return fileSafeError(err)
}
if len(encoded) >= fileJSONBudget {
return fileSafeError(fileInvalid(util.TextFileTooLarge, "serialized result exceeds safe response budget"))
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: string(encoded)}}, StructuredContent: value, StructuredContentSet: true}, nil
}
func fileIntegerArg(args map[string]any, key string, fallback int) (int, error) {
value, exists := args[key]
if !exists {
return fallback, nil
}
var number float64
switch n := value.(type) {
case float64:
number = n
case int:
return n, nil
case json.Number:
var err error
number, err = n.Float64()
if err != nil {
return 0, fileInvalid("invalid_argument", key+" must be an integer")
}
default:
return 0, fileInvalid("invalid_argument", key+" must be an integer")
}
if math.IsNaN(number) || math.IsInf(number, 0) || math.Trunc(number) != number || number > MaxSafeFileInteger || number < -MaxSafeFileInteger {
return 0, fileInvalid("invalid_argument", key+" must be a bounded integer")
}
return int(number), nil
}
const MaxSafeFileInteger = 1 << 30
func fileReadMetadata(args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if err := util.ValidateTextFilePath(p); err != nil {
return fileSafeError(err)
}
if _, err := resolvePath(p); err != nil {
return fileSafeError(fileInvalid(util.TextFileInvalidPath, err.Error()))
}
root, err := os.OpenRoot(util.WorkspaceDir)
if err != nil {
return fileSafeError(err)
}
defer root.Close()
content, err := util.ReadTextFile(root, p)
if err != nil {
return fileSafeError(err)
}
return fileMetadataContent(args, content)
}
func fileMetadataContent(args map[string]any, content string) (CallToolResult, error) {
if _, exists := args["offset"]; exists {
return fileSafeError(fileInvalid("invalid_argument", "metadata reads cannot use legacy offset; use byteOffset"))
}
revision := util.TextFileRevision([]byte(content))
if expected, exists := args["expectedRevision"]; exists && expected != revision {
return fileSafeError(fileInvalid(util.TextFileRevisionConflict, "file changed; restart the read with its current revision"))
}
offset, err := fileIntegerArg(args, "byteOffset", 0)
if err != nil {
return fileSafeError(err)
}
if offset < 0 || offset > len(content) || offset < len(content) && !utf8.RuneStart(content[offset]) {
return fileSafeError(fileInvalid("invalid_argument", "byteOffset must be a UTF-8 boundary within the file"))
}
limit, err := fileIntegerArg(args, "limit", 200)
if err == nil {
limit, err = fileIntegerArg(args, "lineLimit", limit)
}
if err != nil {
return fileSafeError(err)
}
p, _ := args["path"].(string)
page := fileReadPage{Path: p, Revision: revision, TotalBytes: len(content), TotalLines: strings.Count(content, "\n") + 1, StartByte: offset, Encoding: "UTF-8", Newline: fileNewline(content)}
end := len(content)
if limit > 0 {
cursor := offset
for lines := 0; lines < limit; lines++ {
index := strings.IndexByte(content[cursor:], '\n')
if index < 0 {
cursor = len(content)
break
}
cursor += index + 1
}
end = cursor
}
setEnd := func(value int) {
page.EndByte = value
page.Content = content[offset:value]
page.Truncated = offset != 0 || value != len(content)
page.NextOffsetByte = nil
if value < len(content) {
next := value
page.NextOffsetByte = &next
}
}
// 按转义后的实际 JSON 计算预算;以字节长度保守约束共享截断器的 40,000 字符上限。
low, high := offset, min(end, offset+fileJSONBudget)
best := offset
for low <= high {
candidate := low + (high-low)/2
for candidate > offset && candidate < len(content) && !utf8.RuneStart(content[candidate]) {
candidate--
}
setEnd(candidate)
encoded, _ := json.Marshal(page)
if len(encoded) < fileJSONBudget {
best = candidate
low = candidate + 1
for low < len(content) && !utf8.RuneStart(content[low]) {
low++
}
} else {
high = candidate - 1
}
}
setEnd(best)
if best == offset && offset < len(content) {
return fileSafeError(fileInvalid(util.TextFileTooLarge, "metadata leaves no room for content"))
}
return fileJSONResult(page)
}
func fileNewline(content string) string {
crlf := strings.Count(content, "\r\n")
lf := strings.Count(content, "\n") - crlf
cr := strings.Count(content, "\r") - crlf
kinds, label := 0, "none"
for name, count := range map[string]int{"CRLF": crlf, "LF": lf, "CR": cr} {
if count > 0 {
kinds++
label = name
}
}
if kinds > 1 {
return "mixed"
}
return label
}
func fileConditionalWrite(args map[string]any) bool {
_, revision := args["expectedRevision"]
_, absent := args["ifAbsent"]
return revision || absent
}
func fileMutationRequest(args map[string]any) (util.TextFileMutation, error) {
request := util.TextFileMutation{}
request.ExpectedRevision, _ = args["expectedRevision"].(string)
request.IfAbsent, _ = args["ifAbsent"].(bool)
request.DryRun, _ = args["dryRun"].(bool)
action, _ := args["action"].(string)
switch action {
case "edit":
raw, ok := args["edits"].([]any)
if !ok || len(raw) == 0 || len(raw) > 128 {
return request, fileInvalid("invalid_edit", "edits must contain 1 to 128 replacements")
}
request.Edits = make([]util.TextEdit, len(raw))
for i, item := range raw {
edit, ok := item.(map[string]any)
if !ok {
return request, fileInvalid("invalid_edit", "each edit must be an oldText/newText object")
}
oldText, oldOK := edit["oldText"].(string)
newText, newOK := edit["newText"].(string)
if !oldOK || !newOK || oldText == "" {
return request, fileInvalid("invalid_edit", "oldText must be nonempty and newText must be present")
}
request.Edits[i] = util.TextEdit{OldText: oldText, NewText: newText}
}
case "write", "":
var ok bool
request.Content, ok = args["data"].(string)
if !ok {
return request, fileInvalid("invalid_argument", "data must be present and a string (empty is allowed)")
}
}
return request, nil
}
func fileMutationResult(result util.TextFileMutationResult) (CallToolResult, error) {
for {
encoded, _ := json.Marshal(result)
if len(encoded) < fileJSONBudget {
return fileJSONResult(result)
}
if len(result.Diff) == 0 {
return fileSafeError(fileInvalid(util.TextFileTooLarge, "edit result exceeds response budget"))
}
end := len(result.Diff) / 2
for end > 0 && !utf8.RuneStart(result.Diff[end]) {
end--
}
result.Diff = result.Diff[:end]
result.DiffTruncated = true
}
}
func fileMutate(ctx context.Context, args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if err := util.ValidateTextFilePath(p); err != nil {
return fileSafeError(err)
}
abs, err := resolvePath(p)
if err != nil {
return fileSafeError(fileInvalid(util.TextFileInvalidPath, err.Error()))
}
if util.IsPluginDevelopmentRawWriteForbidden(abs) {
return fileSafeError(fileInvalid(util.TextFileInvalidPath, "raw write to a managed plugin or delivery path is forbidden"))
}
request, err := fileMutationRequest(args)
if err != nil {
return fileSafeError(err)
}
root, err := os.OpenRoot(util.WorkspaceDir)
if err != nil {
return fileSafeError(err)
}
defer root.Close()
request.Validate = func() error {
abs, err := resolvePath(p)
if err != nil {
return err
}
if util.IsPluginDevelopmentRawWriteForbidden(abs) {
return fileInvalid(util.TextFileInvalidPath, "raw write to a managed plugin or delivery path is forbidden")
}
return nil
}
result, err := util.MutateTextFile(ctx, root, p, request)
if err != nil {
return fileSafeError(err)
}
return fileMutationResult(result)
}
func fileManaged(ctx context.Context, args map[string]any) (result CallToolResult, resultErr error) {
action, _ := args["action"].(string)
if action != "read" && action != "write" && action != "edit" && action != "delete" && action != "rename" {
return fileSafeError(fileInvalid(util.TextFileInvalidPath, "managed sources support only read, conditional write/edit and file-only delete/rename"))
}
write := action != "read"
err := util.WithPluginProjectSource(ctx, write, func(grant *util.PluginDevelopmentGrant, root *os.Root) error {
key := "path"
if action == "rename" {
key = "old"
}
p, _ := args[key].(string)
rel, err := fileManagedRelative(grant, p)
if err != nil {
return err
}
if action == "read" {
content, err := util.ReadTextFile(root, rel)
if err != nil {
return err
}
if metadata, _ := args["withMetadata"].(bool); metadata {
result, resultErr = fileMetadataContent(args, content)
} else {
result, resultErr = fileLegacyReadContent(args, []byte(content))
}
return resultErr
}
request, err := fileMutationRequest(args)
if err != nil {
return err
}
request.Validate = func() error {
current, err := util.RequirePluginDevelopment(ctx, "write")
if err != nil {
return err
}
if current.TaskID != grant.TaskID || current.SessionID != grant.SessionID || current.PlanHash != grant.PlanHash || current.PlanVersion != grant.PlanVersion || current.SkillDigest != grant.SkillDigest || current.SourceRoot != grant.SourceRoot {
return fileInvalid(util.TextFileRevisionConflict, "approved plugin plan changed during operation")
}
_, err = fileManagedRelative(current, p)
if err == nil && action == "rename" {
newPath, _ := args["new"].(string)
_, err = fileManagedRelative(current, newPath)
}
return err
}
target := ""
if action == "rename" {
newPath, _ := args["new"].(string)
target, err = fileManagedRelative(grant, newPath)
if err != nil {
return err
}
}
request.BeforeCommit = func(oldRevision, newRevision string, temporaryPaths ...string) error {
if oldRevision == "" {
oldRevision = "missing"
}
changes := map[string]util.PluginProjectMutation{rel: {OldRevision: oldRevision, NewRevision: newRevision}}
if action == "rename" {
changes[rel] = util.PluginProjectMutation{OldRevision: oldRevision, NewRevision: "missing"}
changes[target] = util.PluginProjectMutation{OldRevision: "missing", NewRevision: newRevision}
}
return util.BeginPluginProjectMutations(grant, changes, temporaryPaths...)
}
request.AfterCommit = func() error {
paths := []string{rel}
if target != "" {
paths = append(paths, target)
}
return util.FinishPluginProjectMutations(grant, paths)
}
var mutation util.TextFileMutationResult
if action == "delete" || action == "rename" {
mutation, err = util.MutateTextFileName(ctx, root, rel, target, request)
} else {
mutation, err = util.MutateTextFile(ctx, root, rel, request)
}
if err != nil {
return err
}
result, resultErr = fileMutationResult(mutation)
return resultErr
})
if err != nil {
return fileSafeError(err)
}
return result, resultErr
}
func fileManagedRelative(grant *util.PluginDevelopmentGrant, p string) (string, error) {
if err := util.ValidateTextFilePath(p); err != nil {
return "", err
}
abs := filepath.Join(util.WorkspaceDir, filepath.FromSlash(p))
if grant.SourceRoot == "" || filepath.Clean(grant.SourceRoot) != filepath.Join(util.PluginProjectRoot(grant.TaskID), "source") {
return "", fileInvalid(util.TextFileInvalidPath, "invalid host-owned source root")
}
rel, err := filepath.Rel(grant.SourceRoot, abs)
if err != nil {
return "", fileInvalid(util.TextFileInvalidPath, "path is outside approved source")
}
rel = filepath.ToSlash(rel)
if err = util.ValidateTextFilePath(rel); err != nil {
return "", err
}
if slices.Contains(grant.AllowFiles, rel) {
return rel, nil
}
return "", fileInvalid(util.TextFileInvalidPath, "file is outside the approved project allowlist")
}
func fileDelete(args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
// 删除目录会连带删除全部后代,必须逐个授权,避免 file.delete("conf") 抹掉 conf/conf.json 与 TLS 密钥
if err = authorizeSubtree(abs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
info, err := os.Stat(abs)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "stat failed: " + err.Error()}}, IsError: true}, nil
}
if info.IsDir() {
err = os.RemoveAll(abs)
} else {
err = os.Remove(abs)
}
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "delete failed: " + err.Error()}}, IsError: true}, nil
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "deleted: " + p}}}, nil
}
func fileRename(args map[string]any) (CallToolResult, error) {
old, _ := args["old"].(string)
newP, _ := args["new"].(string)
if old == "" || newP == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "old and new are required"}}, IsError: true}, nil
}
oldAbs, err := resolvePath(old)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
newAbs, err := resolvePath(newP)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
// 重命名目录会连带搬移全部后代,必须逐个授权,避免把受保护文件搬到黑名单范围之外
if err = authorizeSubtree(oldAbs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
if err = authorizeSubtree(newAbs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
if err := os.MkdirAll(filepath.Dir(newAbs), 0755); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "mkdir failed: " + err.Error()}}, IsError: true}, nil
}
if err := os.Rename(oldAbs, newAbs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "rename failed: " + err.Error()}}, IsError: true}, nil
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: fmt.Sprintf("renamed: %s -> %s", old, newP)}}}, nil
}
func fileCopy(args map[string]any) (CallToolResult, error) {
src, _ := args["src"].(string)
dst, _ := args["dst"].(string)
if src == "" || dst == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "src and dst are required"}}, IsError: true}, nil
}
srcAbs, err := resolvePath(src)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
dstAbs, err := resolvePath(dst)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
// 复制目录会连带复制全部后代,先整树预检,避免受保护的后代被复制到普通路径后可直接读取
if err = authorizeCopyTree(srcAbs, dstAbs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
if err := util.CopyPath(srcAbs, dstAbs); err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "copy failed: " + err.Error()}}, IsError: true}, nil
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: fmt.Sprintf("copied: %s -> %s", src, dst)}}}, nil
}
func typeLabel(isDir bool) string {
if isDir {
return "DIR"
}
return "FILE"
}
func fileGrep(args map[string]any) (CallToolResult, error) {
pattern, _ := args["pattern"].(string)
if pattern == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "pattern is required"}}, IsError: true}, nil
}
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
include, _ := args["include"].(string)
ctx := int(getFloat64Arg(args, "context"))
max := resolveLimit(args, 200)
results, err := grepGuarded(abs, include, pattern, ctx, max)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "grep failed: " + err.Error()}}, IsError: true}, nil
}
var sb strings.Builder
fmt.Fprintf(&sb, "Found %d lines:\n\n", len(results))
for _, r := range results {
rel, relErr := filepath.Rel(util.WorkspaceDir, r.File)
if relErr != nil {
rel = r.File
}
sep := ":"
if r.Context {
sep = "-:"
}
fmt.Fprintf(&sb, "%s:%d%s %s\n", rel, r.Line, sep, r.Text)
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: sb.String()}}}, nil
}
// grepGuarded 在 Gulu grep 语义(跳过隐藏目录、include 过滤、上下文行、结果上限)之上,
// 对每个即将打开的文件做最终路径授权:被拒绝的后代静默跳过,避免经允许目录递归读出敏感文件内容。
func grepGuarded(root, include, pattern string, context, maxResults int) ([]*gulu.GrepResult, error) {
re, err := regexp.Compile(pattern)
if err != nil {
return nil, err
}
var results []*gulu.GrepResult
info, err := os.Stat(root)
if err != nil {
return nil, err
}
if !info.IsDir() {
if err = authorizeFinalPath(root); err != nil {
return nil, err
}
grepGuardedFile(root, re, context, &results, maxResults)
return results, nil
}
err = filepath.WalkDir(root, func(path string, d os.DirEntry, walkErr error) error {
if walkErr != nil {
return nil
}
if d.IsDir() {
if skipTraversalDir(d.Name()) {
return filepath.SkipDir
}
return nil
}
if !d.Type().IsRegular() {
return nil
}
if include != "" && !util.MatchGlob(d.Name(), include) {
return nil
}
if authorizeFinalPath(path) != nil {
// 敏感、加密或逃逸工作区的后代直接跳过,不中断整次搜索也不返回其内容
return nil
}
grepGuardedFile(path, re, context, &results, maxResults)
return nil
})
if err != nil {
return results, err
}
if maxResults > 0 && len(results) > maxResults {
results = results[:maxResults]
}
return results, nil
}
// grepGuardedFile 逐行匹配单个文件并收集上下文行,语义与 gulu 的 grep 保持一致。
func grepGuardedFile(path string, re *regexp.Regexp, context int, results *[]*gulu.GrepResult, maxResults int) {
if maxResults > 0 && len(*results) >= maxResults {
return
}
f, err := os.Open(path)
if err != nil {
return
}
defer f.Close()
type bufEntry struct {
lineNum int
text string
}
beforeBuf := make([]bufEntry, 0, context+1)
afterRemaining := 0
flushBeforeBuf := func() {
for _, e := range beforeBuf {
if maxResults > 0 && len(*results) >= maxResults {
return
}
*results = append(*results, &gulu.GrepResult{File: path, Line: e.lineNum, Text: e.text, Context: true})
}
beforeBuf = beforeBuf[:0]
}
emit := func(lineNum int, text string, isContext bool) {
if maxResults > 0 && len(*results) >= maxResults {
return
}
*results = append(*results, &gulu.GrepResult{File: path, Line: lineNum, Text: text, Context: isContext})
}
scanner := bufio.NewScanner(f)
scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
lineNum := 0
for scanner.Scan() {
if maxResults > 0 && len(*results) >= maxResults {
return
}
lineNum++
line := scanner.Text()
if re.MatchString(line) {
flushBeforeBuf()
emit(lineNum, line, false)
afterRemaining = context
} else if afterRemaining > 0 {
emit(lineNum, line, true)
afterRemaining--
} else {
beforeBuf = append(beforeBuf, bufEntry{lineNum, line})
if len(beforeBuf) > context {
copy(beforeBuf, beforeBuf[1:])
beforeBuf = beforeBuf[:len(beforeBuf)-1]
}
}
}
if scanErr := scanner.Err(); scanErr != nil {
logging.LogErrorf("scan file [%s] failed: %s", path, scanErr)
}
}
// skipTraversalDir 判断遍历时是否跳过该目录,与 Gulu 的隐藏目录跳过规则保持一致。
func skipTraversalDir(name string) bool {
return name == ".git" || name == ".svn" || name == ".hg" || strings.HasPrefix(name, ".")
}
func fileFind(args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
include, _ := args["include"].(string)
max := resolveLimit(args, 200)
var results []string
total := 0
err = filepath.WalkDir(abs, func(path string, d os.DirEntry, err error) error {
if err != nil {
return nil
}
if d.IsDir() {
if skipTraversalDir(d.Name()) {
return filepath.SkipDir
}
return nil
}
if !d.Type().IsRegular() {
return nil
}
if include != "" && !util.MatchGlob(d.Name(), include) {
return nil
}
if authorizeFinalPath(path) != nil {
// 受保护的后代不出现在结果中,避免经允许目录枚举出敏感文件
return nil
}
total++
if max <= 0 || len(results) < max {
rel, relErr := filepath.Rel(util.WorkspaceDir, path)
if relErr != nil {
rel = path
}
results = append(results, rel)
}
if max > 0 && total >= max {
return filepath.SkipAll
}
return nil
})
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "find failed: " + err.Error()}}, IsError: true}, nil
}
var sb strings.Builder
if max > 0 && max < total {
fmt.Fprintf(&sb, "Found %d files (showing first %d):\n\n", total, max)
} else {
fmt.Fprintf(&sb, "Found %d files:\n\n", len(results))
}
for _, r := range results {
sb.WriteString(r)
sb.WriteString("\n")
}
if max > 0 && max < total {
fmt.Fprintf(&sb, "\n...output limited to %d of %d files. Use limit parameter to adjust.", max, total)
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: sb.String()}}}, nil
}
func fileStat(args map[string]any) (CallToolResult, error) {
p, _ := args["path"].(string)
if p == "" {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "path is required"}}, IsError: true}, nil
}
abs, err := resolvePath(p)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: err.Error()}}, IsError: true}, nil
}
info, err := os.Stat(abs)
if err != nil {
return CallToolResult{Content: []ContentItem{{Type: "text", Text: "stat failed: " + err.Error()}}, IsError: true}, nil
}
return CallToolResult{Content: []ContentItem{{Type: "text", Text: fmt.Sprintf(
"Path: %s\nSize: %d\nIsDir: %v\nModTime: %s",
p, info.Size(), info.IsDir(), info.ModTime().Format("2006-01-02 15:04:05"),
)}}}, nil
}