ai-ad-code-searcher

name: ai-ad-code-searcher version: "1.0" status: ready_for_production layer: skill owner: wade last_reviewed: 2025-12-17 baseline:

• MASTER.md v3.5
• CODE_FACTORY_REFERENCE_PROJECTS.md v1.0 code_sources:
• project: code-graph-rag github: https://github.com/vitali87/code-graph-rag license: MIT borrowed_concepts:
  • Tree-sitter AST 解析架构
  • UniXcoder 语义向量化
  • 知识图谱存储代码关系
• project: code-rag github: https://github.com/rawveg/code-rag license: MIT borrowed_concepts:
  • RAG 检索架构
  • 自然语言代码搜索
• project: Aider github: https://github.com/paul-gauthier/aider license: Apache-2.0 borrowed_concepts:
  • Repo Map 项目结构索引

<code_sources> 本 Skill 的设计和实现借鉴了以下开源项目：

1. **code-graph-rag** (MIT License)
   - GitHub: https://github.com/vitali87/code-graph-rag
   - 借鉴内容:
     - Tree-sitter AST 解析多语言代码
     - UniXcoder 语义向量化 (按功能描述搜索)
     - 知识图谱存储函数调用/类继承关系

2. **code-rag** (MIT License)
   - GitHub: https://github.com/rawveg/code-rag
   - 借鉴内容:
     - RAG (Retrieval-Augmented Generation) 架构
     - 向量相似度搜索

3. **Aider** (Apache-2.0 License)
   - GitHub: https://github.com/paul-gauthier/aider
   - 借鉴内容:
     - Repo Map 项目结构索引技术
     - 文件依赖关系分析

技术实现参考:
- 向量数据库: Chroma (本地) / FAISS (大规模)
- AST 解析: Tree-sitter (Python/TypeScript/JavaScript)
- 语义编码: UniXcoder / OpenAI Embeddings

</code_sources>

核心原则:
- 🔍 多源搜索: 本项目 > 代码资料库 > GitHub
- 🎯 语义匹配: 按功能描述搜索，非仅关键词匹配
- 📊 相关度排序: 返回按相关度排序的候选列表
- 🏷️ 来源标注: 每个结果都标注来源和适配提示

<input_contract> 必填: { requirement: string // 需求描述 (中英文均可) }

可选:
{
  sources: {
    local_project: boolean,   // 搜索本项目 (默认 true)
    code_library: boolean,    // 搜索代码资料库 (默认 true)
    github: boolean           // 搜索 GitHub (默认 false, 需网络)
  },
  max_candidates: number,     // 最大候选数 (默认 5)
  tech_stack_filter: {        // 技术栈过滤
    language: "python" | "typescript" | "javascript",
    framework: "fastapi" | "nextjs" | "react"
  },
  search_mode: "keyword" | "semantic" | "hybrid"  // 搜索模式 (默认 hybrid)
}

</input_contract>

<output_contract> { success: boolean, data: { candidates: [ { id: string, // 唯一标识 source: "local_project" | "code_library" | "github", path: string, // 文件路径或 URL relevance_score: number, // 0-100 相关度 snippet: string, // 代码片段预览 match_reason: string, // 匹配原因说明 tech_stack_match: number, // 0-100 技术栈匹配度 adaptation_hint: string | null // 适配提示 } ], search_stats: { total_searched: number, local_matches: number, library_matches: number, github_matches: number, search_time_ms: number } }, error: string | null } </output_contract>

<search_strategy> <phase id="KEYWORD_EXTRACTION"> 从需求描述中提取关键词: - 中文关键词 → 英文映射 (导出→export, 分页→pagination) - 技术术语识别 (Excel, API, CRUD) - 业务领域词汇 (日报, 账本, 充值) </phase>

<phase id="LOCAL_PROJECT_SEARCH">
  优先级: ⭐⭐⭐⭐⭐ (最高)

  搜索方式:
  1. 从 inventory YAML 中按 tags 匹配
  2. 使用 grep/glob 在代码中搜索关键词
  3. 解析 AST 查找相关函数/类

  输出: 本项目已有的类似功能
</phase>

<phase id="CODE_LIBRARY_SEARCH">
  优先级: ⭐⭐⭐⭐

  搜索方式:
  1. 从 references YAML 中按 feature 匹配
  2. 从 snippets 目录中搜索代码片段
  3. 从 templates 目录中搜索模板

  输出: 已验证的参考代码
</phase>

<phase id="GITHUB_SEARCH">
  优先级: ⭐⭐⭐ (需网络)

  搜索方式:
  1. GitHub Code Search API
  2. 按 stars/license 过滤
  3. 检查技术栈兼容性

  输出: 外部开源参考
</phase>

<phase id="RANKING">
  综合排序:
  - 来源权重: local_project (1.5x) > code_library (1.2x) > github (1.0x)
  - 相关度权重: relevance_score * 0.4
  - 技术栈匹配权重: tech_stack_match * 0.3
  - 代码质量权重: quality_score * 0.2
  - 适配成本权重: (100 - adaptation_cost) * 0.1
</phase>

</search_strategy>

<keyword_mapping> 中文 → 英文关键词:

| 中文     | 英文                          |
|----------|-------------------------------|
| 导出     | export, download              |
| 导入     | import, upload                |
| 分页     | pagination, page, paginate    |
| 表格     | table, grid, list, data-table |
| 表单     | form, input, field            |
| 上传     | upload, file-upload           |
| 下载     | download, export              |
| 搜索     | search, query, filter         |
| 筛选     | filter, select                |
| 排序     | sort, order                   |
| 图表     | chart, graph, visualization   |
| 认证     | auth, login, jwt              |
| 权限     | permission, rbac, role        |
| 日报     | daily-report, report          |
| 账本     | ledger, accounting            |
| 充值     | topup, recharge, deposit      |

</keyword_mapping>

<forbidden_actions> <forbidden id="CS-001"> <action>返回无关代码作为搜索结果</action> <correct_action>只返回相关度 > 40 的结果</correct_action> </forbidden>

<forbidden id="CS-002">
  <action>不标注代码来源</action>
  <correct_action>每个结果必须包含 source 和 path</correct_action>
</forbidden>

<forbidden id="CS-003">
  <action>返回许可证不兼容的代码</action>
  <correct_action>只返回 MIT/Apache/BSD 等兼容许可证的代码</correct_action>
</forbidden>

<forbidden id="CS-004">
  <action>伪造搜索结果</action>
  <correct_action>只返回实际存在的代码</correct_action>
</forbidden>

</forbidden_actions>

示例 2: 搜索前端组件
「
使用 ai-ad-code-searcher，
requirement = "数据表格组件，支持分页和筛选"，
tech_stack_filter = { language: "typescript", framework: "react" }
」

示例 3: 仅搜索本项目
「
使用 ai-ad-code-searcher，
requirement = "状态机流转逻辑"，
sources = { local_project: true, code_library: false, github: false }
」

<VERSION_NOTES> ### v1.0 (2025-12-17) - 初始版本 - 支持多源搜索 (本项目/代码资料库/GitHub) - 支持关键词和语义混合搜索 - 借鉴 code-graph-rag 的 Tree-sitter + UniXcoder 架构 - 借鉴 Aider 的 Repo Map 概念 </VERSION_NOTES>