优雅代码守卫

它解决什么问题

大型仓库里"改一行、查半天"是常态：入口文件越开越多，路由、接口名、类型名散落在前后端各处，凭记忆拼出的链路迟早要为错误买单。elegant-code 把"定位功能链路"从一次性的人工搜索变成可复用的派生缓存：启动时扫描项目，之后仅在源文件变化时重建地图。

核心能力

• 项目地图：首次运行 Python 脚本（py -3.14 不可用时回退到当前环境可用的解释器），生成 workskill/，缓存符号、导入、路由、请求、配置与测试关系；源文件未变则直接复用。
• 先查后读：检索前用地图查询高辨识度事实——路由、接口名、类型名、组件名、错误码、配置键或用户给定的精确词，再按返回的路径、符号与关系定位候选代码。
• 证据优先：缺失的链路一律标记为未确认，不按常见架构补全；跨前后端改动必须逐环节确认页面、请求、路由、业务层、数据契约与测试。
• 按需阅读：只有当前证据不足以决定下一步时，才继续读取上下游内容。

生成与验证规则

• 以项目已有 formatter、linter、类型规则和惯用写法为最高优先级；先确定数据流、返回值与错误边界，再动手写代码。
• 能直接返回就不引入临时变量；仅在多步骤处理、状态累积、异步控制或复杂分支时使用循环或额外抽象。
• 复用现有类型、工具、错误模型与配置入口，不为单次逻辑造包装层、DTO、helper 或 class。
• 对外接口、组件、服务与复杂业务函数使用中文功能注释；异常在边界处理——前端请求层归一化错误，后端入口统一映射响应，不吞异常、不重复记录、不丢失原始原因。
• 配置集中读取并在启动时校验；保持已有编码，新建文本文件默认 UTF-8。

注意点

workskill/ 是本地派生缓存，默认不提交版本控制，也不会上传源码。地图只负责定位候选功能，最终链路必须由图关系、类型或接口契约确认。质量门禁只执行与改动相关的项目原生命令，不安装新的格式化或静态检查依赖；完成后只报告验证摘要与可操作的失败片段，通过的工具不输出完整日志。