Remote Sandbox 方案 V4

package tools

// MaxSandboxFileSize is the maximum file size for ReadFile/WriteFile (500MB).
const MaxSandboxFileSize = 500 * 1024 * 1024

// ExecSpec defines the parameters for a sandbox command execution.
type ExecSpec struct {
    Command   string        // executable or shell command
    Args      []string      // arguments (ignored when Shell=true)
    Shell     bool          // use shell for execution (sh -c)
    Dir       string        // working directory (absolute path in sandbox)
    Env       []string      // environment variables
    Stdin     string        // stdin input
    Timeout   time.Duration // execution timeout
    Workspace string        // workspace root (for sandbox setup)
    UserID    string        // user identity (for sandbox routing)
}

// ExecResult holds the result of a sandbox command execution.
type ExecResult struct {
    Stdout   string // standard output
    Stderr   string // standard error
    ExitCode int    // exit code (-1 if timed out)
    TimedOut bool   // whether execution timed out
}

// SandboxFileInfo is the sandbox equivalent of os.FileInfo.
// Does NOT include Sys() — cross-process metadata is meaningless.
type SandboxFileInfo struct {
    Name    string      // base name
    Size    int64       // length in bytes
    Mode    os.FileMode // file mode bits
    ModTime time.Time   // modification time
    IsDir   bool        // is directory
}

// DirEntry represents a directory entry from ReadDir.
type DirEntry struct {
    Name  string
    IsDir bool
    Size  int64
}

// Sandbox defines the unified interface for all sandbox modes.
// All file path parameters must be absolute paths in sandbox format.
// Path conversion (sandbox↔host) is an internal concern of each implementation.
type Sandbox interface {
    // === Command Execution ===
    Exec(ctx context.Context, spec ExecSpec) (*ExecResult, error)

    // === File I/O ===
    // ReadFile reads the entire file at path. Path must be absolute.
    // Returns os.ErrNotExist if file does not exist.
    ReadFile(ctx context.Context, path string, userID string) ([]byte, error)

    // WriteFile writes data to path. Path must be absolute.
    // Does NOT auto-create parent directories — call MkdirAll first.
    WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode, userID string) error

    // Stat returns file info. Path must be absolute.
    // Returns os.ErrNotExist if file does not exist.
    Stat(ctx context.Context, path string, userID string) (*SandboxFileInfo, error)

    // ReadDir lists directory entries. Path must be absolute.
    ReadDir(ctx context.Context, path string, userID string) ([]DirEntry, error)

    // MkdirAll creates directory tree. Path must be absolute.
    MkdirAll(ctx context.Context, path string, perm os.FileMode, userID string) error

    // Remove removes a file. Path must be absolute.
    Remove(ctx context.Context, path string, userID string) error

    // RemoveAll removes a directory tree. Path must be absolute.
    RemoveAll(ctx context.Context, path string, userID string) error

    // === Shell Configuration ===
    // GetShell returns the preferred shell command for the user/workspace.
    GetShell(userID string, workspace string) (string, error)

    // === Lifecycle ===
    Name() string
    Close() error
    CloseForUser(userID string) error

    // === Export/Import (docker-specific) ===
    IsExporting(userID string) bool
    ExportAndImport(userID string) error
}

// NoneSandbox — all operations are direct os.* calls
type NoneSandbox struct { /* no state */ }

// DockerSandbox — all operations go through docker exec / docker cp
type DockerSandbox struct {
    client    *client.Client
    image     string
    containers sync.Map // userID → containerID
}

// RemoteSandbox — all operations go through WebSocket or HTTP to Runner
type RemoteSandbox struct {
    connections sync.Map // userID → *runnerConnection
    wsServer    *ws.Server
    httpServer  *http.Server
}

// Server → Runner (request)
{"id":"req_001","type":"exec","command":"ls","args":["-la"],"shell":true,"dir":"/workspace","env":[],"stdin":"","timeout":30,"user_id":"ou_xxx"}
{"id":"req_002","type":"read_file","path":"/workspace/src/main.go","user_id":"ou_xxx"}
{"id":"req_003","type":"write_file","path":"/workspace/src/main.go","data":"<base64>","perm":384,"user_id":"ou_xxx"}
{"id":"req_004","type":"stat","path":"/workspace/src/main.go","user_id":"ou_xxx"}
{"id":"req_005","type":"read_dir","path":"/workspace/skills","user_id":"ou_xxx"}
{"id":"req_006","type":"mkdir_all","path":"/workspace/skills/new","perm":493,"user_id":"ou_xxx"}
{"id":"req_007","type":"remove","path":"/workspace/skills/old","user_id":"ou_xxx"}
{"id":"req_008","type":"remove_all","path":"/workspace/skills/old-dir","user_id":"ou_xxx"}

// Runner → Server (response)
{"id":"req_001","type":"exec_result","stdout":"...","stderr":"...","exit_code":0,"timed_out":false}
{"id":"req_002","type":"file_content","data":"<base64>"}
{"id":"req_002","type":"error","message":"file not found","code":"ENOENT"}
{"id":"req_004","type":"file_info","name":"main.go","size":1234,"mode":420,"mod_time":"2026-03-26T00:00:00Z","is_dir":false}
{"id":"req_005","type":"dir_entries","entries":[{"name":"my-skill","is_dir":true,"size":4096},{"name":"readme.md","is_dir":false,"size":256}]}

xbot-runner --server ws://server:8080/ws --token <auth-token> --workspace /workspace

// WalkSandboxDir 递归遍历 Sandbox 目录，等价于 filepath.WalkDir。
// fn 回调接收相对路径和 DirEntry。只回调文件（跳过目录本身）。
func WalkSandboxDir(ctx context.Context, sb Sandbox, root, userID string, fn func(relPath string, entry DirEntry) error) error {
    return walkSandboxDir(ctx, sb, root, "", userID, fn)
}

func walkSandboxDir(ctx context.Context, sb Sandbox, dir, relBase, userID string, fn func(string, DirEntry) error) error {
    entries, err := sb.ReadDir(ctx, dir, userID)
    if err != nil {
        return err // 目录不存在 → 返回错误
    }
    for _, e := range entries {
        relPath := filepath.Join(relBase, e.Name)
        if e.IsDir {
            if err := walkSandboxDir(ctx, sb, filepath.Join(dir, e.Name), relPath, userID, fn); err != nil {
                return err
            }
        } else {
            if err := fn(relPath, e); err != nil {
                return err
            }
        }
    }
    return nil
}

// OffloadStore 不持有 Sandbox — 通过参数传入（方案 X2）
type OffloadStore struct {
    config   OffloadConfig
    sessions sync.Map
}

// MaybeOffload: 新签名
func (s *OffloadStore) MaybeOffload(
    ctx context.Context,
    sessionKey, toolName, args, result string,
    resolvedReadPath string,  // 由 engine.go 预解析的绝对路径
    fs tools.Sandbox,         // Sandbox 实例
) (OffloadedResult, bool)

// InvalidateStaleReads: 新签名
func (s *OffloadStore) InvalidateStaleReads(
    ctx context.Context,
    sessionKey string,
    fs tools.Sandbox,
) []string

// engine.go (改造后)
resolvedReadPath := ""
if tc.Name == "Read" {
    if p := extractJSONStringField(tc.Arguments, "path"); p != "" {
        cwd := cfg.Session.GetCurrentDir()
        if cwd == "" {
            cwd = cfg.SandboxWorkDir
        }
        if filepath.IsAbs(p) {
            resolvedReadPath = p
        } else {
            resolvedReadPath = filepath.Join(cwd, p)
        }
    }
}
offloaded, wasOffloaded := cfg.OffloadStore.MaybeOffload(
    ctx, offloadSessionKey, tc.Name, tc.Arguments, offloadContent,
    resolvedReadPath, cfg.Sandbox,
)

// 新代码：hash 计算
if resolvedReadPath != "" && fs != nil {
    if rawData, err := fs.ReadFile(ctx, resolvedReadPath, userID); err == nil {
        entry.ContentHash = fmt.Sprintf("%x", sha256.Sum256(rawData))
    }
    // hash 失败 → 不设置 ContentHash → stale 检测不生效
    // 这是正确行为：文件不可读时无法判断是否 stale
}

type SkillStore struct {
    workDir    string
    globalDirs []string
    sandbox    tools.Sandbox
    catalog    *skillCatalog
    catalogTime time.Time
    mu         sync.RWMutex
}

func (s *SkillStore) GetCatalog(ctx context.Context, senderID string) string {
    s.mu.RLock()
    if s.catalog != nil && time.Since(s.catalogTime) < 5*time.Minute {
        cat := s.catalog
        s.mu.RUnlock()
        return cat.render(senderID)
    }
    s.mu.RUnlock()
    return s.refreshCatalog(ctx, senderID)
}

func (s *SkillStore) refreshCatalog(ctx context.Context, senderID string) string {
    var entries []skillEntry

    // 1. 全局 skill → server 本地 os.ReadDir + os.ReadFile
    for _, dir := range s.globalDirs {
        entries = append(entries, s.scanGlobalSkills(dir)...)
    }

    // 2. 用户 skill → Sandbox.ReadDir + Sandbox.ReadFile
    if s.sandbox != nil {
        userSkillsDir := "/workspace/skills"
        if dirEntries, err := s.sandbox.ReadDir(ctx, userSkillsDir, senderID); err == nil {
            for _, de := range dirEntries {
                if de.IsDir {
                    entry := s.readSkillDefViaSandbox(ctx, filepath.Join(userSkillsDir, de.Name), senderID)
                    entries = append(entries, entry)
                }
            }
        }
    }

    s.mu.Lock()
    s.catalog = buildCatalog(entries)
    s.catalogTime = time.Now()
    s.mu.Unlock()

    return s.catalog.render(senderID)
}

func (s *SkillStore) InvalidateCache() {
    s.mu.Lock()
    s.catalog = nil
    s.mu.Unlock()
}

type RegistryManager struct {
    workDir     string
    sharedStore *sqlite.SharedStore
    sandbox     tools.Sandbox  // 新增
}

func (rm *RegistryManager) installSkill(ctx context.Context, entry *sqlite.SharedEntry, senderID string) error {
    destDir := filepath.Join("/workspace/skills", entry.Name)

    // 检查目标：Sandbox
    if _, err := rm.sandbox.Stat(ctx, destDir, senderID); err == nil {
        return fmt.Errorf("skill %q already installed", entry.Name)
    }

    // 读源：server cache (os.WalkDir 递归读)
    var files []struct{ RelPath string; Data []byte }
    err := filepath.WalkDir(entry.SourcePath, func(path string, d fs.DirEntry, err error) error {
        if err != nil { return err }
        if d.IsDir() { return nil }
        rel, _ := filepath.Rel(entry.SourcePath, path)
        data, err := os.ReadFile(path) // follow symlink automatically
        if err != nil { return err }
        files = append(files, struct{ RelPath string; Data []byte }{rel, data})
        return nil
    })
    if err != nil { return fmt.Errorf("read cache: %w", err) }

    // 写目标：Sandbox（递归创建目录 + 写文件）
    for _, f := range files {
        dstPath := filepath.Join(destDir, f.RelPath)
        if err := rm.sandbox.MkdirAll(ctx, filepath.Dir(dstPath), 0o755, senderID); err != nil {
            return fmt.Errorf("mkdir: %w", err)
        }
        if err := rm.sandbox.WriteFile(ctx, dstPath, f.Data, 0o644, senderID); err != nil {
            return fmt.Errorf("write: %w", err)
        }
    }
    return nil
}

func (rm *RegistryManager) publishSkill(ctx context.Context, name, author string) error {
    skillDir := rm.findSkillDirForUser(ctx, name, author)
    if skillDir == "" {
        return fmt.Errorf("skill %q not found", name)
    }

    cacheDir := rm.registryCacheDir("skill", name)

    // 读源：Sandbox 递归读（WalkSandboxDir）
    var files []struct{ RelPath string; Data []byte }
    err := WalkSandboxDir(ctx, rm.sandbox, skillDir, author, func(relPath string, entry DirEntry) error {
        fullPath := filepath.Join(skillDir, relPath)
        data, err := rm.sandbox.ReadFile(ctx, fullPath, author)
        if err != nil { return err }
        files = append(files, struct{ RelPath string; Data []byte }{relPath, data})
        return nil
    })
    if err != nil { return fmt.Errorf("read skill: %w", err) }

    // 写目标：server cache (os.*)
    if err := os.RemoveAll(cacheDir); err != nil && !os.IsNotExist(err) {
        return fmt.Errorf("clean cache: %w", err)
    }
    for _, f := range files {
        dstPath := filepath.Join(cacheDir, f.RelPath)
        if err := os.MkdirAll(filepath.Dir(dstPath), 0o755); err != nil {
            return fmt.Errorf("mkdir cache: %w", err)
        }
        if err := os.WriteFile(dstPath, f.Data, 0o644); err != nil {
            return fmt.Errorf("write cache: %w", err)
        }
    }
    // ... publish to shared store
}

func (rm *RegistryManager) findSkillDirForUser(ctx context.Context, name, senderID string) string {
    // 先查全局（server 本地）
    if dir := rm.findSkillDir(name); dir != "" {
        return dir
    }
    // 再查用户目录（Sandbox）
    if senderID != "" && rm.sandbox != nil {
        path := filepath.Join("/workspace/skills", name)
        if _, err := rm.sandbox.Stat(ctx, filepath.Join(path, "SKILL.md"), senderID); err == nil {
            return path
        }
    }
    return ""
}

// DownloadFile (Feishu → 用户本机)
func downloadAndSave(ctx context.Context, sandbox tools.Sandbox, userID, filePath string, feishuData []byte) error {
    if err := sandbox.MkdirAll(ctx, filepath.Dir(filePath), 0o755, userID); err != nil {
        return err
    }
    return sandbox.WriteFile(ctx, filePath, feishuData, 0o644, userID)
}

// UploadFile/SendFile (用户本机 → Feishu)
func uploadFile(ctx context.Context, sandbox tools.Sandbox, userID, filePath string) (string, error) {
    data, err := sandbox.ReadFile(ctx, filePath, userID)
    if err != nil { return "", err }
    return feishuClient.UploadFile(data, filepath.Base(filePath))
}

type RunConfig struct {
    // ... 现有字段 ...
    Sandbox    tools.Sandbox  // Sandbox 实例引用
    SandboxMode string        // "none", "docker", "remote"（配置时决策）
}

type ToolContext struct {
    // ... 现有字段 ...
    Sandbox tools.Sandbox  // V4 新增
    // SandboxMode 不加 — 用 Sandbox.Name() 代替
}

// 旧代码：所有模式都做 workspaceRoot → sandboxWorkDir 转换
if cwd != "" && cfg.SandboxEnabled && cfg.WorkspaceRoot != "" && cfg.SandboxWorkDir != "" {
    if strings.HasPrefix(cwd, cfg.WorkspaceRoot) {
        cwd = cfg.SandboxWorkDir + cwd[len(cfg.WorkspaceRoot):]
    }
}

// 新代码：remote 模式下跳过转换
// 原因：remote 模式下 CWD 由 Cd 工具设置，已经是 sandbox 格式的绝对路径（/workspace/...）。
// Cd 工具在所有模式下统一使用 Sandbox.Stat 验证路径，返回的路径已经是 sandbox 路径。
// docker 模式仍需转换：docker 模式下 Cd 工具返回的是 host 路径（因为 path_guard 基于 WorkspaceRoot）。
if cwd != "" && cfg.SandboxMode != "remote" && cfg.WorkspaceRoot != "" && cfg.SandboxWorkDir != "" {
    if strings.HasPrefix(cwd, cfg.WorkspaceRoot) {
        cwd = cfg.SandboxWorkDir + cwd[len(cfg.WorkspaceRoot):]
    }
}

// 旧代码
func (t *GlobTool) Execute(ctx *ToolContext, args ...) {
    if ctx.SandboxEnabled { return t.executeInSandbox(ctx, args) }
    return t.executeLocal(ctx, args)
}

// 新代码
func (t *GlobTool) Execute(ctx *ToolContext, args ...) {
    return t.executeViaSandbox(ctx, args)
}

// 旧代码：base64 hack
func sandboxWriteFile(ctx *ToolContext, path, content string) {
    encoded := base64.StdEncoding.EncodeToString([]byte(content))
    executeInSandboxRaw(ctx, fmt.Sprintf("mkdir -p %s", dir))
    executeInSandboxRaw(ctx, fmt.Sprintf("echo '%s' | base64 -d > %s", encoded, path))
}

// 新代码
func sandboxWriteFile(ctx context.Context, sandbox tools.Sandbox, userID, path string, data []byte, perm os.FileMode) error {
    dir := filepath.Dir(path)
    if err := sandbox.MkdirAll(ctx, dir, 0o755, userID); err != nil {
        return err
    }
    return sandbox.WriteFile(ctx, path, data, perm, userID)
}