style: apply ruff format across entire codebase

Standardize type hints (Optional[X] -> X | None, Dict -> dict),
sort imports, and fix trailing newlines across 51 files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Seaual

.gitignore

@@ -88,3 +88,4 @@ demo_papers*.json
 
 # Redis dump
 dump.rdb
+.gitnexus

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["gitnexus@latest", "mcp"]
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **meta-knowledge-graph-main** (1781 symbols, 5293 relationships, 149 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/meta-knowledge-graph-main/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/meta-knowledge-graph-main/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/meta-knowledge-graph-main/clusters` | All functional areas |
+| `gitnexus://repo/meta-knowledge-graph-main/processes` | All execution flows |
+| `gitnexus://repo/meta-knowledge-graph-main/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

CLAUDE.md

@@ -0,0 +1,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **meta-knowledge-graph-main** (1781 symbols, 5293 relationships, 149 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/meta-knowledge-graph-main/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/meta-knowledge-graph-main/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/meta-knowledge-graph-main/clusters` | All functional areas |
+| `gitnexus://repo/meta-knowledge-graph-main/processes` | All execution flows |
+| `gitnexus://repo/meta-knowledge-graph-main/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

backend/__init__.py

@@ -1 +1 @@
-# Backend package
+# Backend package

backend/dependencies.py

@@ -4,7 +4,6 @@
 """
 
 from pathlib import Path
-from typing import Optional
 
 # 延迟导入避免循环依赖
 _db_instance = None
@@ -83,4 +82,4 @@ def get_dedup_service():
 def get_research_service():
     """获取 ResearchService 实例"""
     from .services.research_service import ResearchService
-    return ResearchService(get_db(), get_s2_client())
+    return ResearchService(get_db(), get_s2_client())

backend/routes/__init__.py

@@ -1 +1 @@
-# Routes package
+# Routes package

backend/routes/agent.py

@@ -2,29 +2,26 @@
 Agent API routes
 """
 
-from fastapi import APIRouter, HTTPException
-from fastapi.responses import StreamingResponse
-from typing import Dict, Any, Optional, List, AsyncGenerator
-from pydantic import BaseModel
-import sys
 import json
-import asyncio
+import sys
 import threading
 import uuid
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
 
-from backend.schemas import AgentChatRequest, AgentChatResponse, AgentMessage
-from backend.dependencies import get_db, get_s2_client, get_pdf_parser
-from mkg.llm import init_llm_from_db, reset_llm
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
 # LangGraph imports
-from langchain_core.messages import HumanMessage, AIMessage
+from langchain_core.messages import AIMessage, HumanMessage
 
+from backend.dependencies import get_db, get_pdf_parser, get_s2_client
+from backend.schemas import AgentChatRequest, AgentChatResponse
 from mkg.agent.graph import get_agent_graph, reset_graph
 from mkg.agent.state import AgentState
-from mkg.agent.tools import ALL_TOOLS
+from mkg.llm import init_llm_from_db, reset_llm
 
 router = APIRouter(prefix="/api/agent", tags=["agent"])
 
@@ -51,14 +48,14 @@ class DeepResearchStartRequest(BaseModel):
     targetType: str
     targetName: str
     query: str
-    dimensions: Optional[List[str]] = None
+    dimensions: list[str] | None = None
 
 
 class DeepResearchStatusResponse(BaseModel):
     status: str
     progress: int
-    dimensions: List[str]
-    completedDimensions: List[str]
+    dimensions: list[str]
+    completedDimensions: list[str]
 
 
 @router.post("/chat", response_model=AgentChatResponse)
@@ -137,8 +134,8 @@ def chat(request: AgentChatRequest):
 @router.post("/deep-research/start")
 def start_deep_research(request: DeepResearchStartRequest):
     """启动深入研究任务（异步，后台运行）"""
-    from mkg.agent.tools import deep_research
     from mkg.agent.research_graph import get_deep_research_progress
+    from mkg.agent.tools import deep_research
 
     # 生成唯一 session_id
     session_id = str(uuid.uuid4())[:12]
@@ -291,4 +288,4 @@ def reset_agent():
     """重置 Agent 图（用于重新加载配置）"""
     reset_llm()
     reset_graph()
-    return {"status": "ok"}
+    return {"status": "ok"}

backend/routes/concepts.py

@@ -46,4 +46,4 @@ def get_concept_papers(
 ):
     """获取概念关联的论文"""
     papers = service.get_papers(concept_id, limit)
-    return {"concept_id": concept_id, "papers": papers, "total": len(papers)}
+    return {"concept_id": concept_id, "papers": papers, "total": len(papers)}

backend/routes/concepts_research.py

@@ -3,8 +3,8 @@
 研究路由 - 研究点发现和论文推荐相关端点
 """
 
+
 from fastapi import APIRouter, Depends, HTTPException
-from typing import Optional
 
 from ..dependencies import get_research_service
 from ..services.research_service import ResearchService
@@ -15,8 +15,8 @@
 @router.get("/{concept_id}/search-papers")
 def search_papers_by_concept(
     concept_id: str,
-    year: Optional[str] = None,
-    min_citations: Optional[int] = None,
+    year: str | None = None,
+    min_citations: int | None = None,
     limit: int = 10,
     service: ResearchService = Depends(get_research_service)
 ):
@@ -36,4 +36,4 @@ def discover_research_points(
     result = service.discover_research_points(concept_id)
     if "error" in result:
         raise HTTPException(status_code=400, detail=result["error"])
-    return result
+    return result