# 设计方案 3: Worker Runtime (Context Shell & Utilities)

## 1. 定位与目标

Worker Runtime 是连接底层文档系统 (DocOS) 与上层业务逻辑 (LLM Worker) 的桥梁。
如果说 VGCS 是硬盘，DocOS 是文件系统，那么 Worker Runtime 就是 **Shell (命令行工具集)**。

它的核心任务是：**高效地检索、过滤、组装上下文，为大模型准备输入 (Prompt Context)。**

## 2. 核心设计：Context Shell

我们借鉴 Linux Coreutils 及现代 Rust CLI 工具（如 `fd`, `ripgrep`, `exa`）的理念，提供一组高效、强类型、支持结构化输出的原语。

### 2.1 接口定义 (Rust Trait)

```rust
pub enum OutputFormat {
    Text, // 人类/LLM 可读的文本 (如 ASCII Tree)
    Json, // 程序可读的结构化数据 (类似 jq 输入)
}

pub trait ContextShell {
    /// [tree]: 生成目录树视图
    /// depth: 递归深度
    /// format: Text (ASCII Tree) | Json (Nested Objects)
    fn tree(&self, path: &str, depth: Option<usize>, format: OutputFormat) -> Result<String>;

    /// [find]: 基于元数据的快速查找 (不读取内容)
    /// name_pattern: Glob (如 "*.rs")
    /// min_size/max_size: 大小过滤
    fn find(&self, name_pattern: &str, options: FindOptions) -> Result<Vec<NodeMetadata>>;

    /// [grep]: 全文检索 (读取内容)
    /// pattern: Regex
    /// paths: 限制搜索的文件列表 (通常由 find 的结果输入)
    fn grep(&self, pattern: &str, paths: Option<Vec<String>>) -> Result<Vec<GrepMatch>>;

    /// [cat]: 读取并组装内容
    /// 自动处理 Blob 下载，拼接多个文件，添加 header
    fn cat(&self, paths: &[&str]) -> Result<String>;

    /// [wc]: 统计元数据 (行数, 字节数)
    fn wc(&self, paths: &[&str]) -> Result<Vec<FileStats>>;

    /// [patch]: 局部修补 (新增)
    /// 基于精确文本匹配的替换，避免全量读写。
    /// original: 必须在文件中唯一存在的原文片段
    /// replacement: 替换后的新文本
    fn patch(&self, path: &str, original: &str, replacement: &str) -> Result<()>;
}
```

### 2.2 数据结构 (Serializable)

```rust
#[derive(Serialize, Deserialize)]
pub struct NodeMetadata {
    pub path: String,
    pub kind: NodeKind, // File | Dir
    pub size: u64,
    // pub modified: bool, // TODO: Implement diff check against base
}

#[derive(Serialize, Deserialize)]
pub struct FindOptions {
    pub recursive: bool,
    pub max_depth: Option<usize>,
    pub type_filter: Option<String>, // "File" or "Dir"
    pub min_size: Option<u64>,
    pub max_size: Option<u64>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct GrepMatch {
    pub path: String,
    pub line_number: usize,
    pub content: String,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct FileStats {
    pub path: String,
    pub lines: usize,
    pub bytes: usize,
}
```

## 3. 详细功能设计

### 3.1 tree (Structure Awareness)
*   **场景**: LLM 需要先看一眼 "Map" 才能知道去哪找宝藏。
*   **Text Mode**: 生成经典的 ASCII Tree，直接作为 Prompt 的一部分。
*   **Json Mode**: 嵌套的 JSON 对象，供代码逻辑分析结构。

### 3.2 find (Fast Filter)
*   **场景**: 效率优化。不要一开始就 `grep` 全文。
*   **原理**: 只遍历 Git Tree 对象（元数据），**不解压 Blob**。速度极快。

### 3.3 grep (Content Search)
*   **场景**: RAG (Retrieval) 环节。
*   **优化**: 接受 `find` 的输出作为 `paths` 参数，避免全盘扫描。
*   **并行**: 利用 Rayon 并行读取 Blob 并匹配。

### 3.4 cat (Assemble)
*   **场景**: 组装 Prompt Context。
*   **格式**: 使用 XML tags 包裹，明确文件边界。

### 3.5 patch (Atomic Update)
*   **场景**: 修正笔误或更新局部数据。
*   **逻辑**:
    1. 读取文件内容。
    2. 查找 `original` 字符串。
    3. **Fail Fast**: 如果找不到，或者找到多处（歧义），直接报错，防止改错位置。
    4. 执行替换并在内存中生成新 Blob，更新 Index。
*   **优势**: 相比 `write_file`，它不需要 Worker 回传整个文件内容，节省网络传输和 Token。

## 4. Tool Definition Schema (AI Configuration)

为了让 LLM 能够直接使用这些工具，Runtime 将提供一个方法导出标准的 JSON Schema (OpenAI Compatible)。

```rust
impl WorkerContext {
    pub fn get_tool_definitions() -> serde_json::Value {
        serde_json::json!([
            {
                "type": "function",
                "function": {
                    "name": "tree",
                    "description": "List directory structure. Use this first to understand the file layout.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "path": { "type": "string", "description": "Root path to list (default: root)" },
                            "depth": { "type": "integer", "description": "Recursion depth" }
                        }
                    }
                }
            },
            {
                "type": "function",
                "function": {
                    "name": "patch",
                    "description": "Replace a specific text block in a file. Use this for small corrections.",
                    "parameters": {
                        "type": "object",
                        "required": ["path", "original", "replacement"],
                        "properties": {
                            "path": { "type": "string" },
                            "original": { "type": "string", "description": "Exact text to look for. Must be unique in file." },
                            "replacement": { "type": "string", "description": "New text to insert." }
                        }
                    }
                }
            }
            // ... defined for grep, cat, find, etc.
        ])
    }
}
```

## 5. 高效工作流示例 (The Funnel Pattern)

采用了类似 "漏斗" 的筛选机制，层层递进，效率最高。

```rust
// 1. 全局感知 (Tree)
let structure = ctx.tree("/", Some(2), OutputFormat::Text)?;

// 2. 快速定位 (Find)
let json_files = ctx.find("**/*.json", FindOptions::default())?;

// 3. 精确检索 (Grep)
let matches = ctx.grep("NetProfit", Some(json_files.map(|f| f.path)))?;

// 4. 局部修正 (Patch)
// 假设我们在 matches 中发现了一个拼写错误 "NetProft"
ctx.patch("data/financials.json", "\"NetProft\":", "\"NetProfit\":")?;

// 5. 组装阅读 (Cat)
let context = ctx.cat(&distinct_files)?;
```
