vimcontext 增强

[loyalpartner]

我想给vim context 提供更丰富的 api 接口

你有什么好的建议吗？

@claude

[claude]

Claude finished @loyalpartner's task —— View job

---

VimContext API Enhancement Analysis

Based on my analysis of the current VimContext implementation in yac.vim, I can provide comprehensive suggestions for enhancing the API with richer interfaces.

Todo List:

• Set up repository and pre-commit hooks (not required for this analysis)
• Analyze current VimContext trait implementation
• Review existing handler usage patterns
• Research common vim operations for LSP functionality
• Provide concrete API enhancement suggestions

当前 VimContext API 分析

当前的 VimContext trait (在 crates/vim/src/lib.rs:231-258) 提供了基础的 vim 操作接口：

现有接口:

#[async_trait]
pub trait VimContext: Send + Sync {
    // 函数调用
    async fn call(&mut self, func: &str, args: Vec<Value>) -> Result<Value>;
    async fn call_async(&mut self, func: &str, args: Vec<Value>) -> Result<()>;
    
    // 表达式执行
    async fn expr(&mut self, expr: &str) -> Result<Value>;
    async fn expr_async(&mut self, expr: &str) -> Result<()>;
    
    // 命令执行
    async fn ex(&mut self, command: &str) -> Result<()>;
    async fn normal(&mut self, keys: &str) -> Result<()>;
    async fn redraw(&mut self, force: bool) -> Result<()>;
    
    // 兼容性接口
    async fn eval(&mut self, expr: &str) -> Result<Value>;
    async fn execute(&mut self, cmd: &str) -> Result<Value>;
}

当前使用模式：

• goto.rs:186: 使用 ctx.ex("edit file") 打开文件
• goto.rs:189: 使用 ctx.call_async("cursor", [line, col]) 移动光标

建议的 VimContext API 增强

1. 文件和缓冲区操作

// 高级文件操作
async fn open_file(&mut self, file: &str) -> Result<i32>; // 返回 buffer number
async fn close_buffer(&mut self, bufnr: i32) -> Result<()>;
async fn switch_to_buffer(&mut self, bufnr: i32) -> Result<()>;
async fn get_current_buffer(&mut self) -> Result<i32>;

// 缓冲区信息
async fn buffer_exists(&mut self, file: &str) -> Result<bool>;
async fn get_buffer_name(&mut self, bufnr: i32) -> Result<String>;
async fn get_buffer_lines(&mut self, bufnr: i32, start: u32, end: u32) -> Result<Vec<String>>;
async fn set_buffer_lines(&mut self, bufnr: i32, start: u32, end: u32, lines: Vec<String>) -> Result<()>;

// 缓冲区属性
async fn get_buffer_var(&mut self, bufnr: i32, name: &str) -> Result<Value>;
async fn set_buffer_var(&mut self, bufnr: i32, name: &str, value: Value) -> Result<()>;

2. 光标和位置操作

// 光标操作
async fn get_cursor_position(&mut self) -> Result<(u32, u32)>; // (line, column)
async fn set_cursor_position(&mut self, line: u32, column: u32) -> Result<()>;
async fn move_cursor_relative(&mut self, line_offset: i32, col_offset: i32) -> Result<()>;

// 位置导航
async fn goto_location(&mut self, file: &str, line: u32, column: u32) -> Result<()>;
async fn jump_to_definition(&mut self, file: &str, line: u32, column: u32) -> Result<()>;
async fn add_to_jumplist(&mut self) -> Result<()>;

// 位置信息
async fn get_current_word(&mut self) -> Result<String>;
async fn get_visual_selection(&mut self) -> Result<String>;

3. 窗口和标签页操作

// 窗口管理
async fn split_window(&mut self, direction: SplitDirection) -> Result<i32>; // 返回 window id
async fn close_window(&mut self, winid: i32) -> Result<()>;
async fn switch_to_window(&mut self, winid: i32) -> Result<()>;
async fn get_current_window(&mut self) -> Result<i32>;

// 标签页管理
async fn new_tab(&mut self) -> Result<i32>; // 返回 tab number
async fn close_tab(&mut self, tabnr: i32) -> Result<()>;
async fn switch_to_tab(&mut self, tabnr: i32) -> Result<()>;

#[derive(Debug, Clone)]
pub enum SplitDirection {
    Horizontal,
    Vertical,
}

4. 用户界面增强

// 弹窗和浮动窗口
async fn create_popup(&mut self, content: Vec<String>, config: PopupConfig) -> Result<i32>;
async fn update_popup(&mut self, popup_id: i32, content: Vec<String>) -> Result<()>;
async fn close_popup(&mut self, popup_id: i32) -> Result<()>;

// 快速修复列表
async fn set_quickfix_list(&mut self, items: Vec<QuickfixItem>) -> Result<()>;
async fn open_quickfix(&mut self) -> Result<()>;
async fn close_quickfix(&mut self) -> Result<()>;

// 状态栏和消息
async fn show_message(&mut self, msg: &str, level: MessageLevel) -> Result<()>;
async fn update_statusline(&mut self, left: &str, right: &str) -> Result<()>;

#[derive(Debug, Clone)]
pub struct PopupConfig {
    pub line: Option<u32>,
    pub col: Option<u32>, 
    pub width: Option<u32>,
    pub height: Option<u32>,
    pub border: bool,
    pub title: Option<String>,
}

#[derive(Debug, Clone)]
pub enum MessageLevel {
    Info,
    Warning,
    Error,
}

5. 文本操作和编辑

// 文本查找和替换
async fn search_text(&mut self, pattern: &str, flags: SearchFlags) -> Result<Vec<Position>>;
async fn replace_text(&mut self, pattern: &str, replacement: &str, flags: ReplaceFlags) -> Result<u32>;

// 文本插入和修改
async fn insert_text(&mut self, line: u32, col: u32, text: &str) -> Result<()>;
async fn delete_text(&mut self, start: Position, end: Position) -> Result<()>;
async fn replace_range(&mut self, start: Position, end: Position, text: &str) -> Result<()>;

// 选择和操作
async fn select_range(&mut self, start: Position, end: Position) -> Result<()>;
async fn get_selected_text(&mut self) -> Result<String>;

#[derive(Debug, Clone)]
pub struct Position {
    pub line: u32,
    pub column: u32,
}

bitflags::bitflags! {
    pub struct SearchFlags: u32 {
        const CASE_SENSITIVE = 1;
        const WHOLE_WORD = 2;
        const BACKWARD = 4;
    }
}

6. 高亮和语法

// 语法高亮
async fn add_highlight(&mut self, group: &str, line: u32, col_start: u32, col_end: u32) -> Result<i32>;
async fn clear_highlights(&mut self, group: &str) -> Result<()>;
async fn create_highlight_group(&mut self, name: &str, attrs: HighlightAttrs) -> Result<()>;

// 文本属性 (Vim 8.1+)
async fn add_text_prop(&mut self, prop_type: &str, line: u32, col: u32, length: u32, text: &str) -> Result<i32>;
async fn remove_text_prop(&mut self, prop_id: i32) -> Result<()>;
async fn define_prop_type(&mut self, name: &str, attrs: TextPropAttrs) -> Result<()>;

#[derive(Debug, Clone)]
pub struct HighlightAttrs {
    pub ctermfg: Option<String>,
    pub ctermbg: Option<String>, 
    pub guifg: Option<String>,
    pub guibg: Option<String>,
    pub gui: Option<String>, // bold, italic, etc.
}

7. 事件和回调

// 事件监听
async fn add_autocmd(&mut self, events: Vec<String>, pattern: &str, callback: &str) -> Result<i32>;
async fn remove_autocmd(&mut self, id: i32) -> Result<()>;

// 键映射
async fn add_keymap(&mut self, mode: &str, lhs: &str, rhs: &str, options: KeymapOptions) -> Result<()>;
async fn remove_keymap(&mut self, mode: &str, lhs: &str) -> Result<()>;

#[derive(Debug, Clone, Default)]
pub struct KeymapOptions {
    pub silent: bool,
    pub noremap: bool,
    pub buffer_local: bool,
}

8. 诊断和 LSP 特定功能

// 诊断显示
async fn show_diagnostics(&mut self, diagnostics: Vec<Diagnostic>) -> Result<()>;
async fn clear_diagnostics(&mut self, namespace: &str) -> Result<()>;

// 虚拟文本
async fn set_virtual_text(&mut self, line: u32, text: &str, highlight: &str) -> Result<i32>;
async fn clear_virtual_text(&mut self, line: u32) -> Result<()>;

// 内联提示
async fn show_inlay_hints(&mut self, hints: Vec<InlayHint>) -> Result<()>;
async fn clear_inlay_hints(&mut self) -> Result<()>;

#[derive(Debug, Clone)]
pub struct Diagnostic {
    pub line: u32,
    pub column: u32,
    pub severity: DiagnosticSeverity,
    pub message: String,
    pub source: Option<String>,
}

#[derive(Debug, Clone)]  
pub struct InlayHint {
    pub line: u32,
    pub column: u32,
    pub text: String,
    pub hint_type: InlayHintType,
}

实现建议

1. 渐进式增强

• 保持当前接口的向后兼容性
• 新接口作为扩展 trait 实现
• 逐步将现有代码迁移到高级接口

2. 错误处理改进

// 更具体的错误类型
#[derive(Debug, thiserror::Error)]
pub enum VimContextError {
    #[error("Buffer not found: {0}")]
    BufferNotFound(i32),
    #[error("Invalid position: line {line}, col {col}")]
    InvalidPosition { line: u32, col: u32 },
    #[error("Vim command failed: {0}")]
    CommandFailed(String),
    #[error("Feature not supported in this Vim version")]
    FeatureNotSupported,
}

3. 类型安全改进

// 强类型 ID
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BufferId(i32);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]  
pub struct WindowId(i32);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PopupId(i32);

使用示例

// 当前方式
ctx.ex(format!("edit {}", location.file).as_str()).await?;
ctx.call_async("cursor", vec![json!(location.line + 1), json!(location.column + 1)]).await?;

// 增强后的方式  
ctx.goto_location(&location.file, location.line, location.column).await?;

// 或者更高级的操作
let buffer_id = ctx.open_file(&location.file).await?;
ctx.switch_to_buffer(buffer_id).await?;
ctx.set_cursor_position(location.line, location.column).await?;
ctx.add_to_jumplist().await?;

这些增强将使 VimContext 更加强大和易用，同时保持 yac.vim 的简洁性和性能。

[loyalpartner]

@claude 我觉得接口可以更贴近 vim 的提供的函数接口， 你觉得呢？

[claude]

Claude finished @loyalpartner's task —— View job

---

VimContext API Enhancement - Making Interfaces More Vim-Native

Todo List:

• Set up repository and analyze current VimContext implementation
• Research native Vim function interfaces and patterns
• Provide recommendations for Vim-native API design
• Compare pros/cons with current high-level abstractions

完全同意你的建议！

经过分析当前实现，我发现让 VimContext 接口更贴近 Vim 原生函数确实是更好的设计方式。

当前问题分析

现有 VimContext 的问题：

// 当前的通用接口 - 不够直观
ctx.call("expand", vec![json!("%:p")]).await?;
ctx.call("bufnr", vec![json!("%")]).await?;
ctx.call("getline", vec![json!(line_num)]).await?;

Vim 插件中大量使用的原生函数：
从 vim/autoload/lsp_bridge.vim 分析发现频繁使用：

• expand('%:p') - 获取文件路径 (出现17次)
• bufnr('%'), bufname(), bufexists() - 缓冲区操作 (出现40+次)
• getline(), setline() - 行操作 (出现10+次)
• prop_add(), prop_remove() - 文本属性 (出现15+次)

建议的 Vim-Native VimContext API

1. 直接映射 Vim 内置函数

#[async_trait]
pub trait VimContext: Send + Sync {
    // ============ File and Path Functions ============
    async fn expand(&mut self, expr: &str) -> Result<String>;
    async fn fnamemodify(&mut self, fname: &str, mods: &str) -> Result<String>;
    async fn resolve(&mut self, filename: &str) -> Result<String>;
    async fn globpath(&mut self, path: &str, expr: &str) -> Result<String>;
    
    // ============ Buffer Functions ============
    async fn bufnr(&mut self, expr: &str) -> Result<i32>;
    async fn bufname(&mut self, nr: i32) -> Result<String>;
    async fn bufexists(&mut self, expr: &str) -> Result<bool>;
    async fn buflisted(&mut self, nr: i32) -> Result<bool>;
    async fn bufloaded(&mut self, nr: i32) -> Result<bool>;
    async fn getbufline(&mut self, expr: &str, lnum: i32, end: Option<i32>) -> Result<Vec<String>>;
    async fn setbufline(&mut self, expr: &str, lnum: i32, text: Vec<String>) -> Result<i32>;
    
    // ============ Window Functions ============  
    async fn winid(&mut self, nr: i32) -> Result<i32>;
    async fn winnr(&mut self, expr: Option<&str>) -> Result<i32>;
    async fn winheight(&mut self, nr: i32) -> Result<i32>;
    async fn winwidth(&mut self, nr: i32) -> Result<i32>;
    async fn winsaveview(&mut self) -> Result<Value>;
    async fn winrestview(&mut self, view: Value) -> Result<()>;
    
    // ============ Cursor and Position Functions ============
    async fn line(&mut self, expr: &str) -> Result<i32>;
    async fn col(&mut self, expr: &str) -> Result<i32>;
    async fn cursor(&mut self, line: i32, col: i32) -> Result<()>;
    async fn getpos(&mut self, expr: &str) -> Result<Vec<i32>>;
    async fn setpos(&mut self, expr: &str, list: Vec<i32>) -> Result<i32>;
    
    // ============ Text Functions ============
    async fn getline(&mut self, lnum: i32, end: Option<i32>) -> Result<Vec<String>>;
    async fn setline(&mut self, lnum: i32, text: Vec<String>) -> Result<i32>;
    async fn append(&mut self, lnum: i32, text: Vec<String>) -> Result<()>;
    async fn search(&mut self, pattern: &str, flags: &str) -> Result<i32>;
    async fn substitute(&mut self, expr: &str, pat: &str, sub: &str, flags: &str) -> Result<String>;
    
    // ============ Text Properties (Vim 8.1+) ============
    async fn prop_add(&mut self, lnum: i32, col: i32, props: PropOptions) -> Result<()>;
    async fn prop_remove(&mut self, props: PropOptions) -> Result<i32>;
    async fn prop_type_add(&mut self, name: &str, props: PropTypeOptions) -> Result<()>;
    async fn prop_type_delete(&mut self, name: &str) -> Result<()>;
    
    // ============ Popup Functions (Vim 8.2+) ============  
    async fn popup_create(&mut self, text: Vec<String>, options: PopupOptions) -> Result<i32>;
    async fn popup_close(&mut self, id: i32, result: Option<Value>) -> Result<()>;
    async fn popup_settext(&mut self, id: i32, text: Vec<String>) -> Result<()>;
    
    // ============ Variable Functions ============
    async fn exists(&mut self, expr: &str) -> Result<bool>;
    async fn getbufvar(&mut self, nr: i32, varname: &str, def: Option<Value>) -> Result<Value>;
    async fn setbufvar(&mut self, nr: i32, varname: &str, val: Value) -> Result<()>;
    async fn getwinvar(&mut self, nr: i32, varname: &str, def: Option<Value>) -> Result<Value>;
    async fn setwinvar(&mut self, nr: i32, varname: &str, val: Value) -> Result<()>;
    
    // ============ Core Functions (保留现有接口) ============
    async fn call(&mut self, func: &str, args: Vec<Value>) -> Result<Value>;
    async fn expr(&mut self, expr: &str) -> Result<Value>;
    async fn ex(&mut self, command: &str) -> Result<()>;
    async fn normal(&mut self, keys: &str) -> Result<()>;
}

// 支持结构体
#[derive(Debug, Clone, Default)]
pub struct PropOptions {
    pub id: Option<i32>,
    pub r#type: Option<String>,
    pub length: Option<i32>, 
    pub end_lnum: Option<i32>,
    pub end_col: Option<i32>,
    pub bufnr: Option<i32>,
    pub all: Option<bool>,
}

#[derive(Debug, Clone, Default)]
pub struct PropTypeOptions {
    pub highlight: Option<String>,
    pub priority: Option<i32>,
    pub combine: Option<bool>,
    pub start_incl: Option<bool>,
    pub end_incl: Option<bool>,
}

#[derive(Debug, Clone, Default)]  
pub struct PopupOptions {
    pub line: Option<i32>,
    pub col: Option<i32>,
    pub pos: Option<String>,  // "topleft", "topright", etc.
    pub width: Option<i32>,
    pub height: Option<i32>, 
    pub border: Option<Vec<i32>>,
    pub title: Option<String>,
    pub close: Option<String>,
    pub highlight: Option<String>,
    pub time: Option<i32>,
    pub moved: Option<String>,
}

2. 使用示例对比

当前方式 (不直观):

// 获取当前文件路径
let file = ctx.call("expand", vec![json!("%:p")]).await?;

// 获取缓冲区号
let bufnr = ctx.call("bufnr", vec![json!("%")]).await?;

// 获取行内容  
let line = ctx.call("getline", vec![json!(line_num)]).await?;

// 移动光标
ctx.call_async("cursor", vec![json!(line), json!(col)]).await?;

建议的 Vim-Native 方式 (直观):

// 获取当前文件路径
let file = ctx.expand("%:p").await?;

// 获取缓冲区号
let bufnr = ctx.bufnr("%").await?;

// 获取行内容
let lines = ctx.getline(line_num, None).await?;

// 移动光标
ctx.cursor(line, col).await?;

// 添加文本属性
ctx.prop_add(line, col, PropOptions {
    r#type: Some("error".to_string()),
    length: Some(5),
    ..Default::default()
}).await?;

// 创建弹窗
let popup_id = ctx.popup_create(
    vec!["Error: syntax error".to_string()],
    PopupOptions {
        line: Some(line),
        col: Some(col + 10),
        pos: Some("topleft".to_string()),
        border: Some(vec![1, 1, 1, 1]),
        ..Default::default()
    }
).await?;

优势分析

✅ Vim-Native 方式的优势

1. 直观性: 与 VimScript 代码完全对应，无需心理转换
2. 文档一致性: 直接参考 :help functions 文档
3. 类型安全: Rust 类型系统确保参数正确性
4. IDE 支持: 函数名自动补全、参数提示
5. 维护性: 新 Vim 版本的函数可以直接添加
6. 性能: 避免了字符串解析和动态调用的开销
7. 可扩展性: 容易添加新的 Vim 函数映射

❌ 当前抽象方式的问题

1. 认知负担: 需要记住如何用 call() 调用每个函数
2. 参数不安全: Vec<Value> 参数容易出错
3. IDE 支持差: 无法提供有意义的自动补全
4. 调试困难: 错误信息不够直观
5. 文档分散: 需要在 Rust 文档和 Vim 文档间切换

实现策略

阶段 1: 扩展现有接口

// 保持向后兼容，添加新的 Vim-native 方法
impl VimClient {
    // 现有方法保持不变
    pub async fn call(&mut self, func: &str, args: Vec<Value>) -> Result<Value> { ... }
    
    // 新增 Vim-native 方法
    pub async fn expand(&mut self, expr: &str) -> Result<String> {
        let result = self.call("expand", vec![json!(expr)]).await?;
        Ok(result.as_str().unwrap_or("").to_string())
    }
    
    pub async fn bufnr(&mut self, expr: &str) -> Result<i32> {
        let result = self.call("bufnr", vec![json!(expr)]).await?;
        Ok(result.as_i64().unwrap_or(-1) as i32)
    }
}

阶段 2: 迁移现有代码

逐步将 handlers 中的代码迁移到新接口：

// 修改前
let file = ctx.call("expand", vec![json!("%:p")]).await?
    .as_str().unwrap_or("").to_string();

// 修改后  
let file = ctx.expand("%:p").await?;

建议实现优先级

高优先级 (当前最常用):

• expand(), bufnr(), bufname(), bufexists()
• getline(), setline(), cursor()
• line(), col()

中优先级 (LSP 功能需要):

• prop_add(), prop_remove(), prop_type_add()
• popup_create(), popup_close()
• getbufvar(), setbufvar()

低优先级 (未来扩展):

• winid(), winnr(), 窗口操作函数
• search(), substitute() 等文本操作函数

这种设计既保持了向后兼容性，又提供了更直观、类型安全的 API。你觉得这个方向如何？

---

[loyalpartner]

可以研究下 /usr/share/vim/*/doc/builtin.txt @claude

[claude]

Claude finished @loyalpartner's task —— View job

---

VimContext API Enhancement - Researching Vim builtin.txt

Todo List:

• Set up repository and pre-commit hooks
• Locate and analyze /usr/share/vim/*/doc/builtin.txt documentation
• Study Vim builtin function patterns and categories
• Provide updated VimContext API recommendations based on builtin.txt research
• Compare findings with previous recommendations

---

基于 Vim builtin.txt 的 VimContext API 设计建议

通过分析 /usr/share/vim/vim91/doc/builtin.txt，我发现了 Vim 内置函数的完整分类和设计模式，这为设计更贴近 Vim 原生的 VimContext API 提供了宝贵指导。

Vim 内置函数分类分析

📋 缓冲区操作函数 (Buffer Functions)

// 核心缓冲区函数 - 按使用频率排序
async fn bufnr(&mut self, expr: &str) -> Result<i32>;           // 最常用
async fn bufname(&mut self, expr: Option<i32>) -> Result<String>;
async fn bufexists(&mut self, expr: &str) -> Result<bool>;
async fn buflisted(&mut self, expr: i32) -> Result<bool>;
async fn bufloaded(&mut self, expr: i32) -> Result<bool>;
async fn bufadd(&mut self, name: &str) -> Result<i32>;
async fn bufload(&mut self, buf: i32) -> Result<i32>;

// 缓冲区内容操作
async fn getbufline(&mut self, buf: &str, lnum: i32, end: Option<i32>) -> Result<Vec<String>>;
async fn getbufoneline(&mut self, buf: &str, lnum: i32) -> Result<String>;
async fn setbufline(&mut self, buf: &str, lnum: i32, text: Vec<String>) -> Result<i32>;
async fn appendbufline(&mut self, buf: &str, lnum: i32, text: Vec<String>) -> Result<i32>;
async fn deletebufline(&mut self, buf: &str, first: i32, last: Option<i32>) -> Result<i32>;

// 缓冲区变量
async fn getbufvar(&mut self, buf: i32, varname: &str, def: Option<Value>) -> Result<Value>;
async fn setbufvar(&mut self, buf: i32, varname: &str, val: Value) -> Result<()>;

// 缓冲区窗口关联
async fn bufwinid(&mut self, buf: &str) -> Result<i32>;
async fn bufwinnr(&mut self, buf: &str) -> Result<i32>;

🪟 窗口操作函数 (Window Functions)

// 核心窗口标识和导航
async fn winnr(&mut self, expr: Option<&str>) -> Result<i32>;
async fn win_getid(&mut self, win: Option<i32>, tab: Option<i32>) -> Result<i32>;
async fn win_gotoid(&mut self, id: i32) -> Result<i32>;
async fn win_id2win(&mut self, id: i32) -> Result<i32>;
async fn win_id2tabwin(&mut self, id: i32) -> Result<Vec<i32>>;

// 窗口信息
async fn winbufnr(&mut self, nr: i32) -> Result<i32>;
async fn winheight(&mut self, nr: i32) -> Result<i32>;
async fn winwidth(&mut self, nr: i32) -> Result<i32>;
async fn win_screenpos(&mut self, nr: i32) -> Result<Vec<i32>>;
async fn win_gettype(&mut self, nr: Option<i32>) -> Result<String>;

// 窗口操作
async fn win_execute(&mut self, id: i32, command: &str, silent: Option<bool>) -> Result<String>;
async fn win_findbuf(&mut self, bufnr: i32) -> Result<Vec<i32>>;

// 窗口视图管理
async fn winsaveview(&mut self) -> Result<Value>;
async fn winrestview(&mut self, dict: Value) -> Result<()>;
async fn winrestcmd(&mut self) -> Result<String>;

// 窗口布局
async fn winlayout(&mut self, tabnr: Option<i32>) -> Result<Value>;
async fn win_move_separator(&mut self, nr: i32, offset: i32) -> Result<i32>;
async fn win_move_statusline(&mut self, nr: i32, offset: i32) -> Result<i32>;

📑 标签页操作函数 (Tab Functions)

// 标签页核心函数
async fn tabpagenr(&mut self, arg: Option<&str>) -> Result<i32>;
async fn tabpagebuflist(&mut self, arg: Option<i32>) -> Result<Vec<i32>>;
async fn tabpagewinnr(&mut self, tabarg: i32, arg: Option<&str>) -> Result<i32>;

// 标签页变量
async fn gettabvar(&mut self, nr: i32, varname: &str, def: Option<Value>) -> Result<Value>;
async fn settabvar(&mut self, nr: i32, varname: &str, val: Value) -> Result<()>;
async fn gettabwinvar(&mut self, tabnr: i32, winnr: i32, name: &str, def: Option<Value>) -> Result<Value>;
async fn settabwinvar(&mut self, tabnr: i32, winnr: i32, varname: &str, val: Value) -> Result<()>;

📍 位置和光标函数 (Position/Cursor Functions)

// 行列信息 - 最基础的函数
async fn line(&mut self, expr: &str) -> Result<i32>;              // line('.')最常用
async fn col(&mut self, expr: &str) -> Result<i32>;               // col('.')最常用
async fn charcol(&mut self, expr: &str, winid: Option<i32>) -> Result<i32>;

// 光标操作
async fn cursor(&mut self, lnum: i32, col: i32, off: Option<i32>) -> Result<i32>;
async fn cursor_list(&mut self, list: Vec<i32>) -> Result<i32>;   // cursor([line, col])

// 位置获取和设置
async fn getpos(&mut self, expr: &str) -> Result<Vec<i32>>;
async fn setpos(&mut self, expr: &str, list: Vec<i32>) -> Result<i32>;
async fn getcurpos(&mut self, winnr: Option<i32>) -> Result<Vec<i32>>;
async fn getcursorcharpos(&mut self, winnr: Option<i32>) -> Result<Vec<i32>>;
async fn setcharpos(&mut self, expr: &str, list: Vec<i32>) -> Result<i32>;
async fn setcursorcharpos(&mut self, list: Vec<i32>) -> Result<i32>;

// 屏幕位置
async fn wincol(&mut self) -> Result<i32>;
async fn winline(&mut self) -> Result<i32>;
async fn screencol(&mut self) -> Result<i32>;
async fn screenrow(&mut self) -> Result<i32>;
async fn screenpos(&mut self, winid: i32, lnum: i32, col: i32) -> Result<Value>;

📄 文本操作函数 (Text Functions)

// 基础行操作 - 最高频使用
async fn getline(&mut self, lnum: i32, end: Option<i32>) -> Result<Vec<String>>;
async fn setline(&mut self, lnum: i32, text: Vec<String>) -> Result<i32>;
async fn append(&mut self, lnum: i32, text: Vec<String>) -> Result<()>;

// 文本搜索
async fn search(&mut self, pattern: &str, flags: Option<&str>, stopline: Option<i32>, timeout: Option<i32>) -> Result<i32>;
async fn searchpos(&mut self, pattern: &str, flags: Option<&str>, stopline: Option<i32>, timeout: Option<i32>) -> Result<Vec<i32>>;
async fn searchpair(&mut self, start: &str, middle: &str, end: &str, flags: Option<&str>) -> Result<i32>;
async fn searchpairpos(&mut self, start: &str, middle: &str, end: &str, flags: Option<&str>) -> Result<Vec<i32>>;

// 文本替换
async fn substitute(&mut self, expr: &str, pat: &str, sub: &str, flags: &str) -> Result<String>;

// 字符串工具
async fn match_(&mut self, expr: &str, pat: &str, start: Option<i32>, count: Option<i32>) -> Result<i32>;
async fn matchend(&mut self, expr: &str, pat: &str, start: Option<i32>, count: Option<i32>) -> Result<i32>;
async fn matchstr(&mut self, expr: &str, pat: &str, start: Option<i32>, count: Option<i32>) -> Result<String>;
async fn matchlist(&mut self, expr: &str, pat: &str, start: Option<i32>, count: Option<i32>) -> Result<Vec<String>>;

🎨 文本属性和弹窗函数 (Text Properties & Popup)

// 文本属性 (Vim 8.1+) - 按builtin.txt顺序
async fn prop_add(&mut self, lnum: i32, col: i32, props: PropOptions) -> Result<()>;
async fn prop_add_list(&mut self, props: PropOptions, positions: Vec<Vec<i32>>) -> Result<()>;
async fn prop_clear(&mut self, lnum: i32, lnum_end: Option<i32>, props: Option<PropOptions>) -> Result<()>;
async fn prop_find(&mut self, props: PropOptions, direction: Option<&str>) -> Result<Value>;
async fn prop_list(&mut self, lnum: i32, props: Option<PropOptions>) -> Result<Vec<Value>>;
async fn prop_remove(&mut self, props: PropOptions, lnum: Option<i32>, lnum_end: Option<i32>) -> Result<i32>;

// 属性类型管理
async fn prop_type_add(&mut self, name: &str, props: PropTypeOptions) -> Result<()>;
async fn prop_type_change(&mut self, name: &str, props: PropTypeOptions) -> Result<()>;
async fn prop_type_delete(&mut self, name: &str, props: Option<PropOptions>) -> Result<()>;
async fn prop_type_get(&mut self, name: &str, props: Option<PropOptions>) -> Result<Value>;
async fn prop_type_list(&mut self, props: Option<PropOptions>) -> Result<Vec<String>>;

// 弹窗函数 (Vim 8.2+) - 完整API
async fn popup_create(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;
async fn popup_close(&mut self, id: i32, result: Option<Value>) -> Result<()>;
async fn popup_settext(&mut self, id: i32, text: Vec<String>) -> Result<()>;
async fn popup_setoptions(&mut self, id: i32, options: PopupOptions) -> Result<()>;
async fn popup_getoptions(&mut self, id: i32) -> Result<Value>;
async fn popup_getpos(&mut self, id: i32) -> Result<Value>;
async fn popup_show(&mut self, id: i32) -> Result<()>;
async fn popup_hide(&mut self, id: i32) -> Result<()>;
async fn popup_move(&mut self, id: i32, options: PopupOptions) -> Result<()>;
async fn popup_clear(&mut self) -> Result<()>;
async fn popup_list(&mut self) -> Result<Vec<i32>>;

// 特殊弹窗类型
async fn popup_atcursor(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;
async fn popup_beval(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;
async fn popup_menu(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;
async fn popup_dialog(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;
async fn popup_notification(&mut self, what: Vec<String>, options: PopupOptions) -> Result<i32>;

🗂️ 文件和路径函数 (File/Path Functions)

// 路径展开 - 最重要的函数
async fn expand(&mut self, expr: &str, nosuf: Option<bool>, list: Option<bool>) -> Result<Value>;
async fn expandcmd(&mut self, string: &str, options: Option<Value>) -> Result<String>;
async fn fnamemodify(&mut self, fname: &str, mods: &str) -> Result<String>;
async fn resolve(&mut self, filename: &str) -> Result<String>;
async fn simplify(&mut self, filename: &str) -> Result<String>;
async fn fnameescape(&mut self, fname: &str) -> Result<String>;

// 文件信息
async fn filereadable(&mut self, file: &str) -> Result<bool>;
async fn filewritable(&mut self, file: &str) -> Result<bool>;
async fn getfsize(&mut self, fname: &str) -> Result<i64>;
async fn getftime(&mut self, fname: &str) -> Result<i64>;
async fn getftype(&mut self, fname: &str) -> Result<String>;
async fn getfperm(&mut self, fname: &str) -> Result<String>;

// 目录操作
async fn isdirectory(&mut self, directory: &str) -> Result<bool>;
async fn getcwd(&mut self, winnr: Option<i32>, tabnr: Option<i32>) -> Result<String>;
async fn haslocaldir(&mut self, winnr: Option<i32>, tabnr: Option<i32>) -> Result<bool>;

// 文件查找
async fn findfile(&mut self, name: &str, path: Option<&str>, count: Option<i32>) -> Result<String>;
async fn finddir(&mut self, name: &str, path: Option<&str>, count: Option<i32>) -> Result<String>;
async fn glob(&mut self, expr: &str, nosuf: Option<bool>, list: Option<bool>, alllinks: Option<bool>) -> Result<Value>;
async fn globpath(&mut self, path: &str, expr: &str, nosuf: Option<bool>, list: Option<bool>, alllinks: Option<bool>) -> Result<String>;

🔧 通用工具函数 (Utility Functions)

// 存在性检查
async fn exists(&mut self, expr: &str) -> Result<bool>;
async fn has(&mut self, feature: &str, check: Option<bool>) -> Result<bool>;
async fn executable(&mut self, expr: &str) -> Result<bool>;

// 变量操作
async fn getwinvar(&mut self, nr: i32, varname: &str, def: Option<Value>) -> Result<Value>;
async fn setwinvar(&mut self, nr: i32, varname: &str, val: Value) -> Result<()>;

// 高亮和匹配
async fn hlexists(&mut self, name: &str) -> Result<bool>;
async fn hlid(&mut self, name: &str) -> Result<i32>;
async fn matchadd(&mut self, group: &str, pattern: &str, priority: Option<i32>, id: Option<i32>) -> Result<i32>;
async fn matchdelete(&mut self, id: i32, win: Option<i32>) -> Result<i32>;
async fn clearmatches(&mut self, win: Option<i32>) -> Result<()>;

// 输入输出
async fn input(&mut self, prompt: &str, text: Option<&str>, completion: Option<&str>) -> Result<String>;
async fn confirm(&mut self, msg: &str, choices: Option<&str>, default: Option<i32>, r#type: Option<&str>) -> Result<i32>;

设计原则和模式发现

🎯 Vim 原生 API 设计模式

1. 参数重载模式:

   • line('.') vs line('$') vs line([bufnr, lnum])
   • expand('%') vs expand('%:p') vs expand('%:t')

2. 可选参数模式:

   • getline(lnum) vs getline(lnum, end)
   • 大部分函数都有可选的第三、四个参数

3. 返回类型一致性:

   • 位置函数返回 Vec<i32> (line, col, off, curswant)
   • 列表函数返回 Vec<String>
   • 存在性函数返回 bool
   • ID 函数返回 i32

4. 错误处理模式:

   • 不存在的缓冲区返回 -1 或空字符串
   • 无效位置返回 0
   • 可选 {def} 参数提供默认值

最终推荐的 VimContext API

基于 builtin.txt 分析，建议按 Vim 原生函数 1:1 映射：

#[async_trait]
pub trait VimContext: Send + Sync {
    // ============ 最高频核心函数 ============
    async fn expand(&mut self, expr: &str) -> Result<String>;
    async fn line(&mut self, expr: &str) -> Result<i32>;
    async fn col(&mut self, expr: &str) -> Result<i32>;
    async fn bufnr(&mut self, expr: &str) -> Result<i32>;
    async fn bufname(&mut self, expr: Option<i32>) -> Result<String>;
    async fn getline(&mut self, lnum: i32, end: Option<i32>) -> Result<VimValue>;
    async fn setline(&mut self, lnum: i32, text: Vec<String>) -> Result<i32>;
    async fn cursor(&mut self, line: i32, col: i32) -> Result<i32>;

    // ============ 扩展的完整API ============
    // ... (上面详细列出的所有函数分类)
    
    // ============ 兼容现有接口 ============
    async fn call(&mut self, func: &str, args: Vec<Value>) -> Result<Value>;
    async fn expr(&mut self, expr: &str) -> Result<Value>;
    async fn ex(&mut self, command: &str) -> Result<()>;
    async fn normal(&mut self, keys: &str) -> Result<()>;
}

// 统一返回类型，避免 Value 解析
#[derive(Debug, Clone)]
pub enum VimValue {
    String(String),
    Number(i32),
    Float(f64),
    List(Vec<VimValue>),
    Dict(std::collections::HashMap<String, VimValue>),
    Bool(bool),
}

与之前建议的对比

方面	之前的高级抽象	基于 builtin.txt 的原生映射
学习曲线	需要学习新API	直接使用已知的Vim函数
文档	需要单独文档	直接参考 :help function-name
IDE支持	有限的补全	完整的函数名和参数补全
扩展性	手动添加包装函数	自动映射新Vim函数
调试	抽象层增加复杂度	与VimScript行为完全一致
维护性	需要维护映射关系	直接映射，维护成本低

结论: 基于 builtin.txt 的原生函数映射方式明显优于高级抽象，完全符合你"更贴近vim原生接口"的建议。

---