1. 项目概述YangDuck一个为AI开发者量身打造的本地化工具集如果你和我一样每天都在和Cursor、Claude Code这类AI编程助手打交道那你肯定也遇到过类似的困扰想快速查看一下项目目录结构得在终端里敲tree想搜索某个特定文件得切到Finder或者用find命令想预览一下Markdown文件还得打开一个专门的编辑器。这些操作本身不复杂但频繁地在AI编辑器、终端和系统应用之间切换思路很容易被打断效率也高不起来。YangDuck也叫Yduck就是为了解决这个痛点而生的。它本质上是一个运行在终端里的本地工具集通过一套统一的命令行接口把开发者日常高频使用的文件操作、项目浏览、内容预览等功能打包起来。更重要的是它遵循了MCPModel Context Protocol规范这意味着它能被Claude Desktop、Cursor等支持MCP的AI助手直接调用。你可以直接在AI聊天窗口里说“帮我看看src目录下有哪些Python文件”AI就能通过YangDuck获取到结果并展示给你整个过程无需离开编辑器。简单来说YangDuck扮演了AI助手与你本地文件系统之间的“翻译官”和“执行者”。它让AI从只能“纸上谈兵”变得可以“动手操作”极大地扩展了AI编程助手的实用边界。这个项目特别适合macOS平台上的全栈开发者、独立开发者或任何深度依赖AI辅助编程的工程师尤其是那些厌倦了上下文切换、追求极致工作流效率的人。2. 核心设计思路为什么是MCP与TUI的结合在深入安装和配置之前理解YangDuck背后的设计哲学至关重要。这能帮你判断它是否真的适合你的工作流以及未来如何更好地扩展它。2.1 拥抱MCP为AI赋予“手和眼”MCP模型上下文协议是由Anthropic提出的一套开放协议旨在标准化AI模型与外部工具、数据源之间的交互方式。在MCP出现之前每个AI应用如Cursor、Claude Desktop想要接入本地工具都需要自己实现一套插件系统开发者需要为每个应用单独适配非常麻烦。YangDuck选择基于MCP构建是一个极具前瞻性的决定。这意味着一次开发多处使用只要一个AI应用支持MCP这个列表正在快速增长YangDuck就能无缝接入无需为每个应用重写适配层。能力标准化MCP协议定义了工具Tools和资源Resources等核心概念。YangDuck将文件列表、文件内容、命令执行等能力包装成标准的MCP工具AI模型能以统一、安全的方式调用它们。安全性MCP服务器即YangDuck运行在本地AI模型通过安全的进程间通信IPC来请求数据或执行操作。你的代码和文件数据永远不会离开你的机器这解决了使用AI时最核心的数据隐私顾虑。所以YangDuck不是另一个孤立的命令行工具它是你本地AI生态的基础设施。2.2 双模交互CLI与TUI的互补YangDuck提供了两种使用方式这体现了其设计上的实用性考量CLI命令行界面这是基础。你可以直接在终端运行yduck ls、yduck find等命令。这对于编写脚本、自动化流程或者在不需要AI介入的纯手动操作场景下非常有用。它确保了工具本身的独立性和可用性。TUI终端用户界面这是亮点。通过yduck tui命令你可以启动一个全屏的、交互式的终端界面。在这里你可以用键盘导航目录、预览文件、甚至执行内置命令。TUI模式非常适合快速浏览不熟悉的项目结构或者在不想记忆复杂命令参数时进行探索性操作。更重要的是这两种模式共享同一套核心引擎。无论是你手动在TUI里按下一个键还是AI通过MCP发送一个请求最终调用的都是YangDuck底层相同的文件遍历、内容读取模块。这种设计保证了行为的一致性也降低了维护成本。2.3 工具选型Rust语言的优势浏览YangDuck的仓库你会发现它是一个Rust项目。这并非偶然。对于这类需要高性能文件I/O、长期运行作为后台服务器、并且强调安全性的系统工具Rust具有天然优势零成本抽象与高性能文件系统操作可能涉及大量小文件读写Rust能保证在提供高级抽象的同时不引入运行时性能开销响应速度极快。内存安全与并发安全作为MCP服务器需要稳定处理并发请求。Rust的所有权和生命周期机制能在编译期就消除数据竞争和内存错误这对于需要长期稳定运行的工具至关重要。丰富的终端/TUI生态Rust社区有ratatui原tui-rs这样成熟的TUI库以及clap这样强大的命令行参数解析库能帮助开发者快速构建出既美观又健壮的终端应用。选择Rust意味着YangDuck在追求功能强大的同时也把稳定性和效率放在了核心位置。3. 从零开始在macOS上部署与配置YangDuck理论讲完了我们开始动手。以下是在macOS上从零开始安装、配置YangDuck并接入Cursor的完整流程。我假设你已经有基本的终端使用经验。3.1 环境准备与依赖安装首先确保你的系统已经安装了必要的构建工具。安装Homebrew这是macOS上不可或缺的包管理器。如果你还没有安装打开终端Terminal.app或iTerm2运行以下命令/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装完成后按照终端输出的提示将Homebrew添加到你的PATH环境变量中通常是执行两行echo eval...命令。安装Rust工具链YangDuck使用Rust编写因此我们需要rustc编译器和cargo包管理器。最推荐的方式是通过rustup进行安装它能方便地管理多个Rust版本。curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh运行后按照提示选择默认安装选项通常按1即可。安装完成后关闭并重新打开终端或者执行source $HOME/.cargo/env来使cargo命令生效。可以通过rustc --version和cargo --version来验证安装是否成功。注意如果你的网络环境导致rustup安装缓慢或失败可以尝试设置镜像源。在中国大陆一个常用的方法是设置环境变量export RUSTUP_DIST_SERVERhttps://rsproxy.cn export RUSTUP_UPDATE_ROOThttps://rsproxy.cn/rustup然后再执行上面的curl安装命令。或者你也可以通过Homebrew安装Rust (brew install rust)但rustup是更官方和推荐的方式。3.2 获取并编译YangDuck源码现在我们来获取YangDuck的源代码并编译它。克隆仓库使用git克隆项目到本地。你可以选择一个你喜欢的目录比如~/Developer。cd ~/Developer git clone https://github.com/ByGroover/YangDuck.git cd YangDuck编译项目使用cargo进行编译。--release参数会进行优化生成性能更好的可执行文件虽然编译时间稍长但为了日常使用的流畅性这是值得的。cargo build --release这个过程会下载并编译YangDuck及其所有依赖项。首次编译可能需要几分钟时间请耐心等待。安装到系统路径编译完成后可执行文件位于target/release/目录下名为yduck。为了方便在任何地方都能调用我们把它链接到系统可执行路径中比如/usr/local/bin需要管理员权限。sudo cp target/release/yduck /usr/local/bin/输入你的系统密码后安装就完成了。现在你可以在终端的任何位置直接输入yduck --help来验证安装是否成功。你应该能看到完整的命令帮助信息。3.3 配置Cursor以使用YangDuckMCP集成这是让YangDuck发挥其最大价值的关键一步——让Cursor AI能够调用它。定位Cursor配置目录Cursor的MCP服务器配置通常位于用户配置目录下。打开终端使用以下命令创建或编辑配置文件# 使用你喜欢的编辑器比如VS Code、Vim或Nano code ~/.cursor/mcp.json如果~/.cursor目录或mcp.json文件不存在编辑器会自动创建。编辑MCP配置文件在mcp.json文件中你需要添加YangDuck作为MCP服务器。配置文件是一个JSON数组每个元素代表一个MCP服务器。以下是基本的配置示例[ { mcpServers: { yangduck: { command: yduck, args: [mcp-server], env: {} } } } ]command: yduck这里假设yduck命令已经在你的PATH中我们上一步cp操作就是为了实现这个。如果出现找不到命令的错误你可以在这里使用绝对路径例如/usr/local/bin/yduck。args: [mcp-server]这个参数告诉yduck以MCP服务器模式启动。env: {}这里可以定义需要传递给YangDuck的环境变量一般情况下留空即可。重启Cursor并验证保存mcp.json文件后完全关闭Cursor应用然后重新打开。这是必须的因为Cursor只在启动时读取MCP配置。打开Cursor后新建或打开一个聊天窗口。如果配置成功你应该能在输入框上方或模型选择区域附近看到除了“文件”、“搜索”等默认工具外出现了新的工具图标或提示名称可能为“yangduck”或“Yduck”。更直接的验证方法是在聊天框中输入“你能用yangduck工具帮我列出当前目录的文件吗”。如果AI回复它可以使用相关工具并可能向你请求更多信息如具体目录路径那就说明集成成功了。实操心得第一次配置MCP时最容易出错的地方就是路径和重启。务必确保yduck命令全局可用或者你在配置中使用了绝对路径。另外每次修改mcp.json后都必须重启Cursor才能生效这一点很容易被忽略。4. 核心功能解析与实战应用安装配置好后我们来深入看看YangDuck到底能做什么。我会结合CLI和AI调用两种方式展示其核心功能。4.1 文件系统导航与浏览lstree这是最基本也是最常用的功能。在TUI模式下你可以使用方向键、j/k键在文件列表中导航按Enter进入目录或预览文件。但在与AI协作时我们更关注如何通过指令来操作。CLI直接使用# 列出当前目录下的文件和目录基础列表 yduck ls # 以树状图形式列出当前目录结构深度为2层 yduck tree --depth 2 # 列出指定目录如~/Projects下的所有文件包括隐藏文件 yduck ls ~/Projects -a通过AICursor调用 在Cursor聊天框中你可以用自然语言发出指令。例如“请使用yangduck以树状结构展示我桌面Desktop文件夹的内容深度显示3级。”AI会理解你的意图并通过MCP调用yduck tree --depth 3 ~/Desktop。结果会以清晰格式化的文本形式返回到聊天窗口中。这比你自己打开终端、切换路径、输入命令要直观和快速得多尤其当你不确定具体路径或命令参数时。4.2 智能文件搜索与查找findgrep在大型项目中快速定位文件或内容是开发者的高频需求。CLI直接使用# 在当前目录及子目录中按名称查找所有.js文件 yduck find --name *.js # 在src目录中查找包含“TODO”或“FIXME”注释的文件 yduck grep TODO|FIXME src/ # 结合使用查找所有.py文件并在其中搜索“import pandas” yduck find --name *.py --exec yduck grep import pandas {} \;find命令支持按名称、类型、大小等过滤grep支持基本的正则表达式两者结合威力很大。通过AI调用 你可以向AI描述复杂的搜索需求“帮我在这个项目里找找有没有哪个Python文件里既导入了requests库又定义了名为fetch_data的函数”AI需要将这个需求分解为多个步骤可能先find所有的.py文件然后对每个文件grep两次。虽然最终执行的命令可能稍复杂但对你来说只需要用一句话描述需求即可。AI处理了命令的拼接和结果的整理。4.3 文件内容预览与查看catheadtail快速查看文件内容而无需打开重型编辑器。CLI直接使用# 查看一个配置文件的内容 yduck cat ~/.zshrc # 查看日志文件的前10行 yduck head -n 10 /var/log/system.log # 实时监控一个正在增长的日志文件类似tail -f yduck tail -f /path/to/app.log在TUI模式下选中文件后按Enter通常就会进入一个只读的预览视图支持语法高亮如果文件类型被识别体验很好。通过AI调用 当你和AI讨论一段特定代码时可以直接让它“看看”“打开当前项目下src/utils/logger.py这个文件告诉我setup_logger这个函数是怎么实现的。”AI会调用yduck cat获取文件内容然后对其进行分析和解释。这比你自己找到文件、复制代码片段、再粘贴到聊天框里要连贯得多。4.4 高级功能与“Recipes”配方除了上述基础文件操作YangDuck更强大的地方在于其“Recipes”配方概念。你可以将一系列复杂的、多步骤的操作组合成一个简单的命令。项目文档或代码中可能预置了一些有用的recipes。例如一个名为“clean-project”的recipe可能依次执行以下操作删除所有node_modules目录。删除所有.pyc缓存文件。删除dist、build等构建产物目录。最后打印出清理了多大的空间。CLI调用Recipeyduck run-recipe clean-project通过AI调用“我感觉项目目录有点乱能用yangduck的清理配方帮我整理一下吗”AI会识别出可用的clean-project配方并执行它。“Recipes”是高度可定制的你可以根据自己项目的需求编写自己的配方通常需要修改YangDuck的配置文件或源码从而将你的个性化工作流固化下来并通过AI一键触发。5. 深度定制与高级配置指南基础使用只能发挥YangDuck一半的功力。要让它真正融入你的血脉成为思维的一部分必须进行深度定制。5.1 配置文件详解与环境变量YangDuck的行为可以通过配置文件和环境变量来调整。配置文件通常位于~/.config/yangduck/config.tomlLinux/macOS或%APPDATA%\yangduck\config.tomlWindows。如果不存在可以手动创建。一个典型的配置文件可能包含以下部分# ~/.config/yangduck/config.toml [ui] # TUI模式下的主题颜色可选 dark, light, auto (跟随系统) theme dark # 在文件列表中忽略的文件模式支持通配符 ignore_patterns [ **/node_modules, **/.git, **/*.pyc, **/__pycache__, .DS_Store ] [search] # 默认的find命令是否忽略隐藏文件 ignore_hidden true # 默认的grep搜索是否区分大小写 case_sensitive false [mcp] # MCP服务器监听的地址和端口通常不需要修改除非有冲突 # bind_address 127.0.0.1 # port 8080 # 预定义的Recipes配方 [recipes.my-clean] description 清理我的工作空间 steps [ { command find, args [., -name, node_modules, -type, d, -exec, rm, -rf, {}, ] }, { command find, args [., -name, *.log, -delete] }, { command echo, args [工作空间已清理] } ]通过编辑这个文件你可以让YangDuck默认忽略那些你永远不想在列表里看到的目录如node_modules设置你喜欢的搜索行为以及定义你自己的专属配方。5.2 创建自定义Recipes配方自定义配方是YangDuck的杀手级特性。它允许你将任何重复性的文件系统操作序列化。配方定义在配置文件的[recipes]部分如上例所示。每个配方recipe包含名称[recipes.my-clean]中的my-clean就是配方名通过yduck run-recipe my-clean调用。描述description字段帮助你和AI理解这个配方的用途。步骤steps是一个数组每个元素是一个“命令”对象。命令对象通常包含command可执行命令如find,rm,echo, 甚至是yduck自身和args参数列表。设计配方的技巧安全第一涉及删除rm、移动mv等破坏性操作的配方务必先在steps里加入echo或ls命令进行“预演”确认无误后再执行真实操作。甚至可以先实现一个--dry-run模拟运行模式。参数化高级用法中你可以让配方接受外部参数。例如一个“备份日志”的配方可以接受日期参数。这通常需要更复杂的脚本支持或者等待YangDuck未来支持更高级的配方语法。组合现有命令多使用yduck find、yduck grep等自身命令来构建配方保证跨平台一致性。定义好配方后不仅你可以用CLI调用还可以直接告诉AI“运行一下那个‘my-clean’配方”。AI通过MCP看到这个配方后就能直接执行它。5.3 性能调优与忽略规则当你用YangDuck遍历一个包含数万文件的大型项目如包含完整依赖的Node.js或Java项目时性能可能会成为问题。优化主要从两方面入手精细化配置ignore_patterns这是最重要的优化手段。把你项目中所有已知的、无需关心的庞大目录和文件类型加入忽略列表。通用的如**/node_modules,**/.git,**/target(Rust),**/build(C/C),**/.idea,**/.vscode。项目特定的如**/vendor(PHP),**/dist,**/coverage等。这能极大减少需要扫描的文件数量。限制搜索范围在使用find或grep时养成好习惯尽量指定一个具体的起始目录而不是总是从根目录.开始。例如yduck find src --name *.ts比yduck find . --name *.ts高效得多。注意TUI模式TUI模式需要实时渲染界面在超大目录下首次加载可能会有卡顿。对于这种目录更推荐先通过CLI或AI进行精准搜索而不是直接在TUI中打开。6. 常见问题排查与实战技巧即使按照指南操作在实际使用中也可能遇到一些问题。这里记录了一些我踩过的坑和解决方案。6.1 MCP集成失败排查表问题现象可能原因解决方案Cursor重启后看不到YangDuck工具1.mcp.json配置错误。2.yduck命令不在PATH。3. Cursor未正确重启。1. 检查mcp.json的JSON语法可用jsonlint在线工具。确保command路径正确可尝试用绝对路径。2. 在终端执行which yduck确认命令是否存在。如果不存在重新执行sudo cp ...安装步骤。3.确保完全退出Cursor包括Dock图标再重新启动。AI提示“无法连接到MCP服务器”或“工具调用失败”1. YangDuck的MCP服务器进程启动失败。2. 端口冲突。1. 在终端手动运行yduck mcp-server看是否有错误输出。常见错误是依赖缺失或配置语法问题。2. 检查配置文件中port是否被其他应用占用。可尝试更换端口。工具可用但执行命令时报“权限被拒绝”YangDuck以当前用户权限运行试图访问无权限的文件/目录。这是正常的安全限制。AI无法越权访问。你需要确保操作的文件在当前用户权限范围内。对于系统文件AI也无能为力。6.2 CLI/TUI使用中的常见问题TUI中键盘快捷键无效确保你处于正确的“模式”。通常刚启动TUI时是“浏览模式”方向键导航。有些操作如搜索需要先按/键进入“搜索模式”。留意TUI底部的状态栏提示。中文文件名显示乱码这通常是由于终端或系统区域设置问题。确保你的终端如iTerm2、Terminal的编码设置为UTF-8。在macOS上这通常是默认设置但如果遇到问题可以在~/.zshrc或~/.bash_profile中添加export LANGen_US.UTF-8。find或grep结果不符合预期首先检查你的忽略规则ignore_patterns是否过滤掉了目标文件。其次确认通配符*,?的使用是否正确。在CLI中模式字符串通常需要用引号括起来以防止shell提前展开。6.3 与AI协作的最佳实践心得指令要具体上下文要清晰当要求AI使用YangDuck时尽量提供完整路径。不要说“看看那个工具类”而应该说“用yangduck查看src/utils/helper.py这个工具类文件”。AI的上下文理解能力很强但明确的路径能100%避免歧义。分步进行复杂操作对于非常复杂的文件操作例如“把A目录下所有包含特定字符串的JSON文件提取某个字段然后重命名并移动到B目录”不要指望AI能通过一个MCP调用完成。更好的方式是先让AI用find和grep帮你定位目标文件列表确认无误后再指导你或由AI生成一个可执行的Shell脚本或YangDuck Recipe。AI是副驾驶你仍是掌控方向盘的司机。安全边界意识时刻记住AI通过YangDuck获得的权限就是你当前用户的权限。永远不要让AI执行你不理解的、尤其是涉及rm -rf、chmod、sudo等高风险命令。在让AI执行任何修改性或删除性操作前先让它用cat或ls展示一下将要操作的对象。组合使用其他工具YangDuck不是万能的。它擅长文件系统操作。对于代码分析、版本控制Git、包管理npm, cargo你需要结合其他MCP服务器如Git MCP Server或AI内置工具。向AI清晰地描述你的最终目标它可能会组合调用多个工具来达成。YangDuck这个项目其精妙之处不在于它实现了多么惊天动地的功能——ls,find,grep这些命令本身都平淡无奇。它的价值在于通过MCP协议将这些琐碎但高频的本地操作变成了AI助手可编程、可组合的“原子能力”。它填补了AI对话与本地环境之间的最后一道鸿沟。从我个人的使用体验来看最大的改变不是节省了几次键盘敲击而是思维流的中断被大幅减少了。以前需要停下来、思考、切换窗口、执行、再切换回来的那些“微任务”现在只需要在聊天框里用一句话描述。这种流畅感一旦习惯就再也回不去了。如果你也重度使用AI编程花点时间配置好YangDuck绝对是值得的投资。从今天起让你的AI助手真正开始“动手”帮你干活吧。