Menu
语义分析与多语言解释 — 三层降级深度确保跨语言不翻车；AST 边界分块 + 结构化 JSON + 两阶段检索实现零依赖轻量 RAG。repo-decompose Phase 2 的语义卡来源，mvp-approach 的方向收束依据。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
代码优化循环总控 — 10 阶段调度器（Observe→Understand→Diagnose→Plan→Bound→Fix→Verify→SelfReview→Learn→Decide）。核心目标：优化现有代码，非构建新功能。内置安全审计、风格画像、自我审查。
循环日志管理 — 每个阶段产出结构化 markdown 日志，格式统一、内容精简、可追溯。自动保存到 .loop-log/，支持按阶段/日期/关键词检索。
GitHub 仓库需求拆分 — 两阶段调度（架构先跑 → 数据+逻辑并行），按仓库规模自适应分片，所有子 agent 通过共享上下文同步信息，主 agent 空闲期拉取 knowledge-graph 和 semantic-rag。
代码知识图谱 — 四层递进分析（符号表→调用链→数据流→模块依赖），产出结构化 JSON 供 repo-decompose 交叉验证和 mvp-approach 边界推导。可独立使用，也可被 repo-decompose 主 agent 在 Phase 2 空闲期调用。
Baseado na classificação ocupacional SOC
| name | semantic-rag |
| description | 语义分析与多语言解释 — 三层降级深度确保跨语言不翻车；AST 边界分块 + 结构化 JSON + 两阶段检索实现零依赖轻量 RAG。repo-decompose Phase 2 的语义卡来源，mvp-approach 的方向收束依据。 |
| argument-hint | explain [repo] in Chinese | what does [project] do | ask [repo] where is auth logic |
| triggers | ["这个项目是做什么的","解释一下这个仓库","用中文解释","项目架构","认证逻辑在哪"] |
两步走：
零外部依赖。 不需要向量数据库、embedding API、Chroma/Pinecode。索引是 50–600KB 的纯 JSON 文件。
集成方式：
repo-decompose Phase 2 空闲期调用 → 写入共享上下文 supplements.semanticRAGmvp-approach Step 1 用它收束方向.semantic-rag.json本 skill 有两种运行模式，根据上下文自动选择：
检查: .repo-decompose-context.json 是否存在？
YES → PIPELINE 模式:
- 读取 meta 中的 repo 路径、语言、框架
- Phase 1 跳过（meta 已有语言信息）
- 输出写入 supplements.semanticRAG 字段
- 不需要询问用户任何问题
NO → STANDALONE 模式:
- 需要用户提供代码路径或 GitHub URL
- 输出写入 .semantic-rag.json
- 从 Phase 1 完整开始
决不允许的行为：
诚实面对不同语言的理解不对称。
| 层级 | 涵盖语言 | 工具 | 分析粒度 | 可靠性 |
|---|---|---|---|---|
| L1 | TS, JS, Python, Go, Rust, Java | get_symbols (tree-sitter) | 函数/类/方法 | 高 |
| L2 | C, C++, C#, Kotlin, Swift, PHP, Ruby | search_content + 语言约定正则 | 文件 | 中 |
| L3 | 其他所有语言 | read_file + 注释/文档 | 目录 | 有限 |
降级决策（Phase 1 自动执行）：
输出中诚实标注： 🔬 L1 精确 / 📄 L2 文件级 / 📁 L3 目录级
分块规则:
L1: 每个函数/类/方法 = 1 chunk
L2: 每个源文件 = 1 chunk
L3: 每个目录 = 1 chunk
Chunk 结构:
{
"id": "src/auth/login.ts:handleLogin",
"type": "function",
"name": "handleLogin",
"module": "src/auth",
"summary": "验证用户凭证并返回 JWT token",
"keywords": ["auth", "login", "jwt", "token"],
"source": "src/auth/login.ts:12-45",
"langLevel": "L1"
}
摘要规则：
索引大小：
| 仓库 | 文件数 | Chunk 数 | JSON 大小 |
|---|---|---|---|
| S | <100 | ~200 | ~50 KB |
| M | 100–500 | ~800 | ~150 KB |
| L | 500–2000 | ~3000 | ~400 KB |
| XL | >2000 | ~5000 | ~600 KB |
用户: "认证逻辑在哪里？"
Pass 1 — 关键词命中:
分词 → 匹配 name/summary/keywords → 800→12 候选
Pass 2 — Agent 语义排序:
给 Agent 12 个候选的 {id, summary, keywords}
Agent 对比用户问题排序 → Top 5
输出:
🔍 "认证逻辑":
1. src/auth/login.ts:handleLogin — 验证凭证返回 JWT
2. src/auth/middleware.ts:authMiddleware — 拦截请求校验 token
3. src/auth/session.ts:createSession — 创建会话写入 Redis
4. src/auth/oauth.ts:oauthCallback — 处理 OAuth 回调
5. src/middleware/cors.ts:validateOrigin — 校验请求来源
追问 "展开第2个" → read_file src/auth/middleware.ts
为什么不用 embedding： 摘要是 Agent 自己写的——Agent 读自己写的摘要做排序不需要"翻译层"。
不询问用户，不依赖配置。 自动检测：
| 识别项 | 方法 |
|---|---|
| 语言 | 文件扩展名分布 → 确定 L1/L2/L3 |
| 运行时 | package.json / go.mod / Cargo.toml |
| 框架 | 依赖列表匹配 (Next.js, Django, Gin, Actix...) |
| 入口 | main 字段 / bin 字段 / 约定入口 |
| 目录约定 | src/ lib/ cmd/ pkg/ app/ |
| 测试框架 | jest/vitest/pytest/go test 检测 |
| 数据库 | 依赖名匹配 (pg, mysql, prisma, gorm...) |
出口 — 项目身份卡：
🆔 项目身份
仓库: owner/repo
语言: TypeScript (87%) + CSS (13%)
运行时: Node.js 20+
框架: Next.js 14 (App Router)
入口: src/app/layout.tsx, src/app/api/
数据库: PostgreSQL + Prisma
🔬 L1 精确分析
只分析关键文件。 总量控制 ≤ 20 个。
| 优先级 | 文件类型 | 数量 | 原因 |
|---|---|---|---|
| P0 | README/CONTRIBUTING | ≤3 | 项目自述 |
| P0 | 主入口文件 | ≤2 | 启动路径起点 |
| P1 | 顶级配置 | ≤3 | 依赖和部署信息 |
| P1 | 核心业务目录入口 | ≤5 | 模块入口 |
| P2 | 路由/API 定义 | ≤5 | 对外接口 |
| P3 | 核心类型定义 | ≤3 | 数据模型 |
README 是"意图声明"，不是"事实源"。 很多项目的 README 宣称支持高级能力，但源码并未实现。必须三重交叉验证：
事实层级（高→低）:
L0 — 构建文件 (Makefile / CMakeLists / Cargo.toml / package.json scripts)
→ 确认真实模块列表（被编译/链接的才是真实存在的）
L1 — 源码入口 (main / index / 导出点)
→ 确认架构边界（实际暴露了什么）
L2 — README / 文档
→ 仅用于识别项目意图，不可作为模块存在性的单一证据
降权规则:
README 声称的模块名 → 必须在构建文件中找到编译目标 → 才能在语义卡中列出
README 声称的能力 → 必须在源码入口中找到导出 → 才能写入 RAG 摘要
不同时满足 → 标注 "⚠️ README 声称但未在构建/源码中确认"
示例： README 说"支持高级语义分析和自动重构"，但 Makefile 只编译 foundation, extraction, pipeline, store, mcp 五个模块。语义卡中只列这五个，并标注 ⚠️ README 声称的"自动重构"未在构建目标中找到。
每个关键文件回答三问：
出口 — 模块语义卡：
{
"modules": [
{
"path": "src/auth",
"responsibility": "用户认证和会话管理",
"role": "核心业务",
"upstream": ["src/middleware"],
"downstream": ["src/db", "src/cache"]
}
],
"architecturePattern": "分层 (middleware → handler → service → db)",
"dataFlow": "请求 → 认证 → 路由 → 业务 → ORM → PostgreSQL"
}
结构固定：
📖 [owner/repo] 概览
[一段话 — 是什么、解决什么、怎么解决。≤5 句。]
🏗️ 架构: [识别到的模式]
src/auth/ — 用户认证和会话管理
src/db/ — 数据库访问 (Prisma)
src/api/ — REST API 路由
src/ui/ — React 组件和页面
📊 数据: [核心模型], PostgreSQL + Redis
🔑 入口: src/app/layout.tsx, src/app/api/
🔬 L1 精确分析
约束： S 仓库 ≤30 行，M ≤50 行，L ≤80 行。不输出源代码片段。
执行摄入算法。独立使用时输出 .semantic-rag.json；被调用时写入共享上下文。
自检： 抽 5 个 chunk，每个摘要 ≤25 字且非程序员也能理解。
| # | Agent 借口 | 反驳 |
|---|---|---|
| 1 | "L2 语言用 search_content 凑合就行" | 降级≠不做。L2 仍需读关键文件写摘要，只是粒度从函数降到文件 |
| 2 | "RAG 索引太大，先不生成" | 索引是分析的自然产物——摘要写完索引就有了，不是额外工作 |
| 3 | "L3 语言我完全不懂，跳过" | L3 降级到目录+README。README 总是人类语言，没有语言障碍 |
| 4 | "摘要太长，复杂逻辑说不清" | ≤25 字是硬约束。说不清 → 标注 ⚠️ 职责复杂 而不写长摘要 |
| 5 | "关键词不准，用 embedding 替代" | embedding 引入外部依赖。关键词不准 → 加更多同义词进 keywords 数组 |
| 6 | "先不做 RAG，等用户追问再说" | 追问时再做 = 每次追问都要重新扫全仓库。索引 = 一次扫描，N 次查询 |