开发 unix-goto 类高性能 Shell 导航工具时…

为 unix-goto 这类高性能 Shell 导航系统开发新功能、优化缓存、添加书签/历史命令并满足性能与测试要求时使用。

适用场景

解决思路

1. 按 9 步标准流程添加功能：1) 规划功能（回答解决什么问题、用户接口、性能目标、依赖、测试、文档，并填写规划模板）；2) 创建模块（使用模块模板，公共函数无前缀、内部函数用双下划线前缀、全局变量大写、局部变量小写，环境变量提供默认值，返回码 0=成功/1=一般错误/2=多匹配）；3) 在 goto.sh 中按依赖顺序加载模块（无依赖的先加载，主 goto-function.sh 最后加载）；4) 在 lib/goto-function.sh 的 goto() 中用 case 路由命令到新模块；5) 编写测试（单元、集成、边界、性能四类，100% 覆盖，使用 pass/fail 计数器和测试模板）；6) 在 docs/API.md 中记录 API（签名、子命令、性能、示例、返回码、实现文件）；7) 在 README.md 中更新用户文档；8) 用 goto benchmark 和 time 验证性能达标（缓存导航 <100ms、书签查找 <10ms、加速比 >20x、命中率 >90%、缓存构建 <5s）；9) 更新 Linear 问题并按规定格式提交（feat/fix/perf/refactor/test/docs/chore 前缀，包含功能、性能、测试信息）。
2. 遵循模块代码风格：函数先声明 local 参数并校验输入，主逻辑后 echo 结果并 return 0；用 if ! command 检查命令成功；错误信息带 emoji 和具体路径；注释解释为什么而非做什么。
3. 数据文件使用管道分隔加元数据头格式（# Version、# Built、# Format、#--- 后跟数据行）。
4. 性能优化：所有查找走缓存、限制递归搜索深度、避免冗余文件系统操作、用 grep 做快速文本匹配；缓存文件控制在 100KB 以内、不启动常驻进程。
5. 调试技巧：用 set -x / set +x 跟踪执行；用 declare -f 检查函数是否加载；用 cat ~/.goto_index、stat -f %m ~/.goto_index、goto index rebuild 排查缓存问题。
6. 遵循 Linear 工作流：从 Phase 3 backlog 取问题 → 移到 In Progress → 建 feature/CET-XX-feature-name 分支 → 按 9 步实现 → 测试 → 提交 → 更新 Linear → 移到 Complete；使用 Linear 问题模板（Problem/Solution/Acceptance Criteria/Performance Targets/Dependencies）。
7. 提交前核对功能清单：实现完成、已在 goto.sh 加载、已集成到主 goto 函数、测试通过且 100% 覆盖、API.md 已记录、README.md 已更新、性能已验证、Linear 已更新、提交信息格式正确。
8. 使用常用命令：source goto.sh 加载、goto index rebuild 重建缓存、bash test-cache.sh / test-benchmark.sh 跑测试、goto benchmark all 跑基准、time goto project 测导航、goto index status 查缓存健康。

适用边界 · 注意事项

• 通用 bash 脚本开发（应使用通用 bash 技能）
• 非导航类 Shell 工具
• 没有性能要求的项目或简单一次性 Shell 脚本