开发工具CLI【免费下载链接】pecoSimplistic interactive filtering tool项目地址https://gitcode.com/gh_mirrors/pe/peco点击查看免费下载peco发音 peh-koh是一款用 Go 编写的简易交互式过滤工具simplistic interactive filtering tool核心价值在于边输入边过滤用户把日志、进程列表、文件清单等通过管道喂给它交互式地缩小结果范围按回车后把选中的行输出到 stdout 继续交给下游命令处理。本文以仓库内面向 Agent 的架构文档 .claude/docs/packages.md 为骨架逐包梳理 peco 的模块划分、关键类型与核心方法签名并结合 README.md 与各源码文件解释其背后的实现机制。读完本文你将掌握 peco 从 CLI 入口到事件循环、过滤器、消息总线、管线、行数据模型的完整架构地图能够快速定位任何功能对应的包与文件也能理解配置项与命令行选项在源码中的落地位置。包总览一张依赖地图peco是一个标准的多包 Go 工程go.mod声明模块github.com/peco/peco根目录下的peco包是交互过滤工具的核心其余包按职责划分为六类类别包路径职责可执行入口cmd/peco、cmd/filterbenchCLI 主程序入口、过滤器性能基准工具核心运行态peco根包全局状态、goroutine 循环、UI 组件配置与过滤config/、filter/配置加载与类型、过滤器算法实现通信与数据hub/、line/、pipeline/、query/、selection/、sig/消息总线、行数据类型、处理管线、查询文本、选择集、信号处理内部工具internal/ansi、internal/buffer、internal/keyseq、internal/utilANSI 解析、缓冲池、键序列匹配、平台工具从包间依赖关系见 .claude/docs/packages.md可以清晰看出分层设计peco根包依赖config、filter、hub、line、pipeline、query、selection、sig以及所有internal/*子包pipeline仅依赖linehub、query、sig、internal/ansi、internal/keyseq、internal/util不依赖任何内部包处于依赖链的最底层便于独立测试与复用。peco根包交互过滤工具的核心根包持有程序的全部全局状态Peco结构体定义于 peco.go是包含运行 peco 所需一切的全局对象输入输出流Stdin/Stdout/Stderr、消息中枢hub、配置config、当前行缓冲currentLineBuffer、过滤器集合filters、查询文本query、选择集selection、屏幕screen、布局layoutType、样式styles等字段一应俱全。值得一提的字段包括enableSep是否解析 NUL 分隔符、negationPrefix负向匹配前缀、execOnFinish--exec外部命令、frozen/follow/zoom三个状态对象对应冻结结果、跟随模式、上下文展开三大特性。生命周期方法方法签名作用New() → *Peco创建新实例根包 peco.go 中New()初始化内存缓冲、ID 生成器、默认屏幕NewTcellScreen()、选择集等(*Peco).Setup() → error从配置/选项初始化依次执行config.Init()、命令行解析、ReadConfig、ApplyConfig最后创建hub.New(5)(*Peco).Run(ctx) → error主事件循环Setup → 启动 ID 生成器与信号监听 →SetupSource→ 启动 Input/View/Filter 三个 goroutine → 等待ctx.Done()(*Peco).ApplyConfig(CLIOptions) → error将 CLI 选项与配置合并应用到实例包括布局、样式、键位、过滤器、高度规格、否定前缀等(*Peco).SetupSource(ctx) → (*Source, error)初始化输入源优先读取位置参数指定的文件否则若 stdin 非 TTY 则读取 stdin(*Peco).PrintResults()将选中的行无选中时取当前行按序输出到 stdout若--print-query则先输出查询串(*Peco).CurrentLineBuffer() → Buffer返回当前活跃的行缓冲原始缓冲或过滤结果缓冲(*Peco).ExecQuery(ctx, func()) → bool带防抖地执行查询空查询时重置缓冲非空时经time.AfterFunc延迟 50ms 合并高频输入Run的启动流程在 peco.go 中有完整实现先Setup再创建可取消的 context、启动 ID 生成器 goroutine 与信号处理器然后SetupSource注释明确指出必须等其他组件就绪后再做否则读取超大缓冲时无法绘制屏幕若指定了--height则改用NewInlineScreen而非默认的NewTcellScreen最后启动Input、View、Filter三个 goroutine 循环并阻塞等待退出。三个早期退出模式--select-1、--exit-0、--select-all三个选项分别由selectOneAndExitIfPossible、exitZeroIfPossible、selectAllAndExitIfPossible实现peco.go通过startEarlyExitHandlers在source.SetupDone()之后异步检查条件恰有一条输入则立即输出并退出输入为空则以状态 1 退出--select-all则全选后以collectResultsError触发结果收集退出。其中selectOneAndExitIfPossible使用了atomic.Bool的 CAS 语义防止多 goroutine 并发触发重复退出。关键类型与接口关键类型Peco、Buffer、FilteredBuffer、MemoryBuffer、Source、Screen、Layout、Action、Keymap、Event、CLIOptions、Location、PageCrop关键接口MessageHub消息中枢抽象生产环境用hub.Hub测试可用替代实现、Screen、Layout、Action、ActionMap、Buffer、Keyseq、ConfigReader配置读取抽象defaultConfigReader为空文件名时跳过读取屏幕实现TcellScreen生产默认、InlineScreen--height限高模式实现见 screen_inline.go、SimScreen测试用布局实现BasicLayout及其三个构造器DefaultLayout、BottomUpLayout、TopDownQueryBottomLayout与 README.md 中--layout top-down|bottom-up|top-down-query-bottom三种模式一一对应相关文件peco.go、action.go、buffer.go、event.go、filter.go、input.go、keymap.go、layout.go、layout_any.go、layout_windows.go、options.go、page.go、screen.go、screen_inline.go、source.go、state.go、view.go、vertical_anchor_gen.gocmd/peco 与 cmd/filterbench入口与基准cmd/pecoCLI 入口cmd/peco/peco.go 是唯一的主程序入口。它通过go-flags解析命令行参数创建peco.New()实例并调用Run(ctx)。退出码处理逻辑清晰util.IsCollectResultsError(err)为真时调用PrintResults()并以 0 退出正常选中结果util.IsIgnorableError(err)为真时返回其携带的退出状态如--exit-0的 1其余错误打印到 stderr 并以 1 退出。main()外层还有recover()兜底避免 panic 直接崩溃。cmd/filterbench过滤器性能基准cmd/filterbench/main.go 是面向开发者与维护者的过滤器性能基准工具仅依赖根包peco、filter、line、pipeline用于在无 UI 环境下测量不同过滤器IgnoreCase、Regexp、Fuzzy、外部命令过滤器等对批量行数据的吞吐表现。相关基准测试用例可参考 filter/bench_test.go 与 hub/bench_test.go。config/配置加载与类型定义config包负责配置文件的加载与全部配置类型的定义config/config.go。核心 APIAPI作用(*Config).Init() → error设置默认值Keymap 初始化为空 map、Prompt默认QUERY常量DefaultPrompt、Layout默认LayoutTypeTopDown(*Config).ReadFilename(string) → error加载配置文件按扩展名分流.yaml/.yml用go-yaml解码其余默认走 JSON 解码LocateRcfile(Locator) → (string, error)按 XDG 规范查找配置文件路径配置文件查找顺序LocateRcfile实现了与 README.md 一致的查找链--rcfile显式指定不存在则报错退出→$XDG_CONFIG_HOME/peco/config.{json,yaml,yml}→$HOME/.config/peco/config.{json,yaml,yml}→$XDG_CONFIG_DIRS列出的每个目录下的peco/config.{json,yaml,yml}→$HOME/.peco/config.{json,yaml,yml}。注意DefaultConfigLocator会在每个目录中依次尝试config.json、config.yaml、config.yml三个文件名config/config.go。关键类型类型说明Config主配置结构Keymap、Action、Style、Layout、CustomFilter、SingleKeyJump、Height、Follow、Filters、NegationPrefix等StyleSet/Style/Attribute样式体系详见style.goOnCancelBehaviorsuccess默认取消退出码 0或error非零退出码实现encoding.TextUnmarshalerColorModeauto解析并渲染输入 ANSI 颜色默认或none禁用同时实现UnmarshalText与UnmarshalFlag因此配置与 CLI 两种途径都能解析CustomFilterConfig外部过滤器配置Cmd命令名须能被exec.LookPath找到、Args参数数组$QUERY占位会被替换、BufferThreshold每批缓冲行数阈值SingleKeyJumpConfigShowPrefix单键跳转hit-a-hint模式是否显示前缀HeightSpec高度规格10绝对行数或50%百分比由height.go的ParseHeightSpec解析颜色与布局常量颜色常量ColorDefault、ColorBlack..ColorWhite属性常量AttrBold、AttrUnderline、AttrReverse、AttrTrueColor与 README.md 的 Styles 章节中bold、underline、reverse、256 色0–255、真彩色#RRGGBB等取值一一对应布局常量LayoutTypeTopDown、LayoutTypeBottomUp、LayoutTypeTopDownQueryBottomfilter/过滤器算法实现filter包是所有内置与外部过滤器的家。根包ApplyConfig中通过populateFilterspeco.go把内置过滤器与自定义过滤器统一注册进filter.Set。核心接口与集合Filter接口filter/filter.goApply(ctx, []line.Line, ChanOutput) → error对行批量应用匹配、BufSize() → int批次缓冲大小、NewContext(ctx, string) → ctx把查询串注入 context、String() → string过滤器名、SupportsParallel() → bool是否可并行处理需要全局状态如排序的过滤器返回 falseCollector接口可选ApplyCollect(ctx, []line.Line) → ([]line.Line, error)直接返回匹配行切片绕过 channel 输出避免并行路径中每块分配 channel 与 goroutine 的开销Setfilter/set.go过滤器集合 旋转Add(Filter)、Rotate()循环切到下一个C-r默认触发、Current() → Filter、SetCurrentByName(string) → error找不到返回ErrFilterNotFound内置过滤器实现构造器行为NewIgnoreCase(...Option)忽略大小写匹配默认过滤器NewCaseSensitive(...Option)大小写敏感匹配NewSmartCase(...Option)查询全小写时忽略大小写否则大小写敏感NewRegexp(...Option)正则匹配NewIRegexp(...Option)忽略大小写的正则匹配NewFuzzy(sortLongest bool, ...Option)模糊匹配FuzzyLongestSort开启时按更长子串 → 更靠左的子串 → 更短的行优先级排序NewExternalCmd(name, cmd string, args []string, threshold int, idgen IDGenerator, enableSep bool)外部命令过滤器Option 与负向匹配WithNegationPrefix(string)选项设置负向词前缀DefaultNegationPrefix为-空前缀即关闭负向匹配filter/option.go。SplitQueryTerms(query, negationPrefix string) → (positive, negative []string)把查询拆成正向词与负向词两组。负向匹配语义README.md 原文要点foo -bar表示匹配含 foo 但不含 bar 的行-foo -bar表示排除所有含 foo 或 bar 的行\-foo反斜杠转义匹配字面量 -foo单独的-匹配连字符本身。负向匹配对所有内置过滤器生效Fuzzy 过滤器的负向词用正则排除而非模糊匹配外部过滤器接收原始查询串自行解析。实现层面base.go 中的isExcluded遍历负向正则列表做排除判断。只有正向词参与命中高亮——例如全负向查询-foo匹配的行不做高亮。外部命令过滤器CustomFilterNewExternalCmdfilter/external.go的默认BufferThreshold为 100常量DefaultCustomFilterBufferThresholdArgs缺省为[]string{$QUERY}。执行流程把缓冲行的DisplayString()写入子进程 stdin读取 stdout 逐行收集匹配enableSep--null开启时还会按显示串索引回原始行以保证Output()返回 NUL 分隔符之后的正确文本。SupportsParallel()返回 false即外部过滤器顺序、分批调用每次调用只见一个批次而非全部输入因此过滤器必须无状态BufferThreshold越大调用次数越少但首屏反馈越慢README.md 的 CustomFilter 章节对此有完整说明。配置示例config.json{ CustomFilter: { MyFilter: { Cmd: /path/to/my-matcher, Args: [ $QUERY ], BufferThreshold: 100 } } }hub/goroutine 通信的消息总线hub包是连接 Input、View、Filter 等 goroutine 的中央消息总线hub/hub.go。New(bufsize int)创建四个带缓冲 channelqueryCh、drawCh、statusMsgCh、pagingChPayload[T]泛型包装消息数据与可选的同步信号通道batch 模式下Done()通知发送方接收方已处理完。核心 APIAPI作用New(bufsize int) → *Hub创建带指定缓冲大小的 hub(*Hub).SendDraw(ctx, *DrawOptions)触发屏幕重绘(*Hub).SendQuery(ctx, string)发送查询变更(*Hub).SendPaging(ctx, PagingRequest)发送翻页/滚动命令(*Hub).SendStatusMsg(ctx, string, time.Duration)显示状态消息如 Running query...可用SuppressStatusMsg关闭(*Hub).Batch(ctx, func(ctx))原子地批量发送多条消息内部加锁且通过 context 值检测嵌套调用避免重复加锁死锁Channel 访问器DrawCh()、PagingCh()、QueryCh()、StatusMsgCh()Paging 请求类型PagingRequestType覆盖全部滚动语义ToLineAbove、ToLineBelow、ToScrollPageDown、ToScrollPageUp、ToScrollLeft、ToScrollRight、ToScrollFirstItem、ToScrollLastItem、ToLineInPage分别对应 README 中的SelectUp/SelectDown、ScrollPageUp/ScrollPageDown、ScrollLeft/ScrollRight、ScrollFirstItem/ScrollLastItem等动作hub/paging.go、hub/paging_request_type_gen.go。paging 相关的性能测试见 hub/bench_test.go。line/显示与选择的行数据类型line包定义所有行数据的统一抽象。接口与工厂API说明Line接口ID() → uint64、Buffer() → string、DisplayString() → string、Output() → string、IsDirty() → bool、SetDirty(bool)并实现btree.Item以支持有序存储NewRaw(id uint64, s string, enableSep bool, stripANSI bool) → *Raw创建原始行enableSep启用 NUL 分隔符解析显示串与输出串分离stripANSI剥离 ANSI 转义NewMatched(Line, [][]int) → *Matched用匹配索引数组包装一行命中高亮用GetMatched(Line, [][]int) → *Matched池化分配sync.Pool配合ReleaseMatched(*Matched)归还以降低分配开销IDGenerator接口Next() → uint64生产实现是根包idgen见 peco.go 的newIDGenMatched的匹配区间[][]int正是Matched样式高亮与上下文行展开ZoomIn的数据基础相关测试见 line/matched_test.go。行缓冲池化在internal/bufferGetLineListBuf/ReleaseLineListBuf其实现 internal/buffer/line.go 直接依赖line包。pipeline/通用的 source→acceptor→destination 管线pipeline包提供把数据源 → 处理阶段 → 终点串成一条链的通用机制pipeline/pipeline.gopeco 的过滤主流程Source 读取 → Filter 处理 → 结果缓冲即建立其上。核心 API 与接口API说明New() → *Pipeline创建管线(*Pipeline).SetSource(Source)设置数据源接口含Start、Reset(*Pipeline).Add(Acceptor)添加处理阶段接口含Accept(*Pipeline).SetDestination(Destination)设置终点接口含Accept、Reset、Done(*Pipeline).Run(ctx) → error执行管线ChanOutputchannel 型输出Send(ctx, line.Line) → error、OutCh() → -chan line.LineNewQueryContext(ctx, string) → ctx/QueryFromContext(ctx) → string通过 context 传递查询串过滤器从 context 中取回当前查询可选的Suspender接口Suspend/Resume为流式/可暂停场景预留了扩展点。注意 root 包sendQuery对无限流IsInfinite()即 stdin 来源与有限输入采取不同策略无限流立即SendQuery并用waitAndCall兜底回调100ms ticker 2s 定时器有限输入则走Hub().Batch同步批量路径peco.go。query/查询文本与光标管理query包管理查询行文本与插入符caret位置支持 peco 的保存/恢复查询机制。API说明Text查询字符串Set(string)、Reset()、SaveQuery()、RestoreSavedQuery()对应ToggleQuery动作的暂存/恢复、DeleteRange(int, int)、InsertAt(rune, int)、String()、Len()、RuneSlice()、RuneAt(int)Caret光标位置Pos() → int、SetPos(int)、Move(int)实现见 query/query.go采用 rune 切片而非字节切片管理保证中文等多字节字符的光标移动与删除语义正确README 也提到 Windows 下非拉丁字体显示问题与光栅字体相关。selection/基于 btree 的有序选择集selection包用 btreegithub.com/google/btree实现有序选择集selection/selection.go保证选中行按输入顺序稳定输出。API说明New() → *Set创建选择集(*Set).Add(line.Line)/Remove(line.Line)增删选中行(*Set).Has(line.Line) → bool成员判断(*Set).Len() → int选中数量(*Set).Ascend(func(line.Line) bool)按序迭代PrintResults即靠它按序输出结果(*Set).Copy(dst *Set)复制全部选中项StickySelection保留选择的实现基础RangeStart范围选择起点标记Valid()、Value()、SetValue(int)、Reset()支撑ToggleRangeMode范围选择模式sig/OS 信号处理sig包提供可测试的信号监听循环New(handler ReceivedHandler, sigs ...os.Signal) → *Handler、(*Handler).Loop(ctx, func()) → error、ReceivedHandler接口Handle(os.Signal)。根包Run中用它注册了一个把任意信号转为p.Exit的处理器peco.go实现见 sig/sig.go。internal/ 子包底层支撑设施internal/ansiANSI 转义序列解析Parse(string) → ParseResult剥离 ANSI 序列并抽取颜色区间ParseResult含Stripped string纯文本与Attrs []AttrSpanExtractSegment([]AttrSpan, start, end int) → []AttrSpan为子串切片属性区间命中高亮渲染的基础AttrSpanFg, Bg Attribute、Length int实现见 internal/ansi/parser.go。ANSI 支持由--color auto|none与配置Color控制默认auto开启时过滤与匹配针对剥离后的纯文本进行选中的行输出保留原始 ANSI 码下游工具仍能收到彩色文本README.md 的 ANSI Color Support 章节。internal/buffer行列表缓冲池GetLineListBuf() → []line.Line、ReleaseLineListBuf([]line.Line)通过sync.Pool复用行切片减少过滤过程中高频分配造成的 GC 压力见 internal/buffer/line.go。internal/keyseq键序列匹配多键绑定如C-x,C-c的匹配核心采用AhoCorasick默认实现由 MURAOKA Taro 贡献自动机一次性匹配全部注册的键序列另有 Trie 与 TernarySearch 两种实现可选。API说明New() → *Keyseq创建匹配器(*Keyseq).Add(KeyList, any)注册键序列 → 动作(*Keyseq).Compile() → error构建匹配自动机(*Keyseq).AcceptKey(Key) → (any, error)喂入按键命中即返回动作ToKeyList(string) → (KeyList, error)解析C-x,C-c格式为键列表KeyEventToString(KeyType, rune, ModifierKey) → (string, error)事件转键名键类型Key、KeyList、KeyType、ModifierKey这解释了 README 中键序列冲突时最长序列优先的规则AhoCorasick 自动机对前缀共享的序列天然支持最长匹配语义。文件internal/keyseq/keyseq.go、internal/keyseq/keys.go、internal/keyseq/trie.go、internal/keyseq/ternary.go、internal/keyseq/ahocorasick.go。internal/util平台工具API说明IsTty(io.Reader) → bool判断输入是否为终端SetupSource用它决定是否读取 stdinHomedir() → (string, error)用户主目录按平台分流homedir_posix.go/homedir_darwin.go/homedir_windows.goShell(ctx, string) → *exec.Cmd创建 shell 命令--exec的底层支持StripANSISequence(string) → string剥离 ANSI 转义已废弃改用internal/ansiIsCollectResultsError(error) → bool判断收集结果哨兵错误cmd/peco 据此调用PrintResultsIsIgnorableError(error) → bool/GetExitStatus(error) → (int, bool)可忽略错误与退出码提取平台文件tty_posix.go、tty_bsd.go、tty_windows.go、shell_unix.go、shell_windows.go。注意tty_posix.go中IsTty通过文件描述符判断终端BSD 系系统走tty_bsd.go的特殊路径。从包结构到功能关键特性在源码中的落点把 .claude/docs/packages.md 的包地图与 README.md 的特性清单对照可以快速定位每个功能的实现位置特性主要落点增量搜索Incremental Search根包ExecQueryhub.SendQuerypipeline过滤链路负向匹配Negative Matchingfilter包WithNegationPrefix/SplitQueryTermsCLI--negation-prefix、配置NegationPrefix多选/范围选择selection.SetToggleRangeMode/ToggleSelection动作冻结结果FreezeResults/UnfreezeResults根包frozen状态与ResetCurrentLineBuffer的冻结分支跟随模式--follow/ToggleFollow根包follow状态journalctl -f -n 1000 \| peco --follow --layout top-down-query-bottom是其典型用法上下文行ZoomIn/ZoomOut根包zoom状态 line.Matched匹配区间 Context样式内联模式--height/配置HeightInlineScreenconfig.ParseHeightSpec值可为5绝对行数或40%百分比最小有效高度 3 行1 结果行 提示行 状态行超高超限自动钳制ANSI 颜色internal/ansi解析 ColorMode配置/--color开关水平滚动hub.PagingRequest的ToScrollLeft/ToScrollRight每次滚动半屏宽单键跳转hit-a-hint根包populateSingleKeyJump前缀映射表基于asdfghjklzxcvbnmqwertyuiop键序外部过滤器filter.NewExternalCmdCustomFilterConfig给读者的一句话总结peco的包结构是一张清晰的分层架构图cmd/提供入口根包peco负责状态编排hub充当 goroutine 间通信总线pipeline提供数据处理骨架filter/line/query/selection分别承担匹配算法、行数据、查询文本与选择存储internal/提供 ANSI 解析、键序列匹配与平台工具等底层能力。无论你要扩展一个过滤器、新增一个动作、调整布局还是排查配置加载问题都可以按本文的包地图迅速定位到对应文件——这正是 .claude/docs/packages.md 作为 Agent 消费型架构文档的价值所在。进一步探索可从 README.md 的功能与配置章节入手配合各包*_test.go测试文件理解行为契约。赞分享开发工具CLI【免费下载链接】pecoSimplistic interactive filtering tool项目地址https://gitcode.com/gh_mirrors/pe/peco点击查看免费下载相关推荐Astro 源码仓库导读从安装方式到 Monorepo 包目录与核心源码结构Astro 源码仓库导读从安装方式到 Monorepo 包目录与核心源码结构 本文以仓库根目录的 README.md https://link.gitcode前端Web框架SSR前端构建AndroidAPS与Nightscout集成教程实时血糖监控与远程管理指南 AndroidAPS与Nightscout集成教程实时血糖监控与远程管理指南 AndroidAPS 作为开源自动胰岛素输注系统与 Nightscout医疗健康智能硬件hexyl核心架构与代码结构解析hexyl核心架构与代码结构解析 hexyl作为一款现代化的命令行十六进制查看器采用Rust语言实现并展现了优秀的架构设计理念。整个项目采用模块化设计遵循R开发工具上一篇探索DragSelect核心功能从基础选择到高级拖放的完整指南下一篇Vue.Draggable自定义拖拽辅助线对齐与吸附功能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考