codeabc 0.1.0__py3-none-any.whl

backend/prompts/edit.py

@@ -0,0 +1,62 @@
+"""Prompt + helper for natural-language code editing.
+
+CodeABC never writes to the user's files; this produces a *suggested* edited
+version of a snippet that the reader can review and copy. The prompt asks the
+model to apply a plain-language instruction (e.g. "把茅台换成比亚迪") and
+return only the modified code, which `extract_code_block` then unwraps.
+"""
+
+from __future__ import annotations
+
+_MAX_CODE_CHARS = 8000
+
+
+def build_edit_prompt(
+    instruction: str,
+    code: str,
+    *,
+    file_path: str = "",
+    language: str = "",
+) -> str:
+    """Build the LLM prompt for applying a natural-language edit to *code*."""
+    code = code.strip()
+    if len(code) > _MAX_CODE_CHARS:
+        code = code[:_MAX_CODE_CHARS] + "\n…（代码较长，已截断）"
+
+    where = f"（来自文件 `{file_path}`）" if file_path else ""
+    fence = language or ""
+
+    return f"""你是一个细心的编程助手。下面是一段{language}代码{where}：
+
+```{fence}
+{code}
+```
+
+用户想这样修改它：
+{instruction.strip()}
+
+请按用户的要求修改代码，遵守：
+1. 只做用户要求的改动，其余部分**原样保留**，不要顺手重构、改风格或加注释。
+2. 保持原有缩进、命名习惯和语言不变。
+3. 如果要求不清楚或在这段代码里无法完成，就原样返回代码不要乱改。
+
+只输出修改后的**完整代码**，用一个 ```{fence} 代码块``` 包裹，前后不要写任何解释或多余文字。"""
+
+
+def extract_code_block(text: str) -> str:
+    """Unwrap a fenced code block from LLM output; fall back to stripped text.
+
+    Tolerates an optional language tag after the opening fence and any stray
+    prose the model adds outside the fence.
+    """
+    text = text.strip()
+    start = text.find("```")
+    if start == -1:
+        return text
+    # skip the opening fence line (which may carry a language tag)
+    newline = text.find("\n", start)
+    if newline == -1:
+        return text
+    end = text.find("```", newline)
+    inner = text[newline + 1 : end] if end != -1 else text[newline + 1 :]
+    return inner.strip("\n")

backend/prompts/overview.py

@@ -0,0 +1,57 @@
+"""Prompt for generating project overview ("项目说明书")."""
+
+from __future__ import annotations
+
+
+def build_overview_prompt(files: list[dict]) -> str:
+    """Build the LLM prompt for project overview generation.
+
+    Args:
+        files: list of {"path": str, "size": int, "language": str, "preview": str}
+    """
+    # build file context
+    file_sections = []
+    for f in files:
+        preview = f.get("preview", "").strip()
+        if not preview:
+            file_sections.append(f"### {f['path']} ({f['language']}, {f['size']} bytes)\n(empty)")
+            continue
+        # truncate very long previews
+        if len(preview) > 3000:
+            preview = preview[:3000] + "\n... (truncated)"
+        file_sections.append(
+            f"### {f['path']} ({f['language']}, {f['size']} bytes)\n```\n{preview}\n```"
+        )
+
+    files_context = "\n\n".join(file_sections)
+
+    return f"""你是一个耐心的编程导师，正在帮一个完全不懂代码的人理解一个项目。
+请用中文、大白话来解释，不要使用任何编程专业术语。
+如果必须提到技术概念，请用日常生活的类比来解释（比如把函数比作"一个做特定事情的小助手"）。
+
+下面是这个项目的文件列表和部分内容：
+
+{files_context}
+
+请根据以上信息，生成一份"项目说明书"。严格输出以下 JSON 格式（不要输出其他内容）：
+
+{{
+  "summary": "一句话说明这个项目做什么（20字以内）",
+  "description": "用2-3句大白话详细解释这个项目的用途，让完全不懂代码的人也能理解",
+  "files": [
+    {{"path": "文件路径", "role": "大白话描述作用", "importance": "high/medium/low"}}
+  ],
+  "how_to_run": [
+    "步骤1：...",
+    "步骤2：..."
+  ],
+  "quick_tips": [
+    "如果你只想做XX，去YY文件改ZZ就行"
+  ]
+}}
+
+注意：
+- files 数组要包含所有重要文件，按重要性排序
+- importance 为 high 的是核心文件（入口、主要逻辑），medium 是辅助文件，low 是配置/资源
+- how_to_run 要写得足够具体，让不懂代码的人也能照着做
+- quick_tips 给出1-3个最实用的提示"""

backend/prompts/qa.py

@@ -0,0 +1,45 @@
+"""Prompt for answering a reader's question about a piece of code."""
+
+from __future__ import annotations
+
+_MAX_CODE_CHARS = 8000
+
+
+def build_qa_prompt(
+    question: str,
+    code: str,
+    *,
+    file_path: str = "",
+    language: str = "",
+) -> str:
+    """Build the LLM prompt for Q&A about a code selection.
+
+    Args:
+        question: the reader's question, in their own words.
+        code: the selected code (or whole file) the question is about.
+        file_path: optional path, to ground the answer.
+        language: optional language name, for the code fence.
+    """
+    code = code.strip()
+    if len(code) > _MAX_CODE_CHARS:
+        code = code[:_MAX_CODE_CHARS] + "\n…（代码较长，已截断）"
+
+    where = f"（来自文件 `{file_path}`）" if file_path else ""
+    fence = language or ""
+    code_block = f"```{fence}\n{code}\n```\n\n" if code else ""
+
+    return f"""你是一个耐心的编程导师，正在帮一个不太懂编程的人读懂一段代码。
+
+下面是用户选中的代码{where}：
+
+{code_block}用户的问题是：
+{question.strip()}
+
+请用中文、大白话回答：
+1. 直接回答问题，先给结论再展开，别绕圈子。
+2. 尽量少用编程术语；必须用时，顺手用一句日常类比解释清楚。
+3. 只依据给出的代码和通用编程常识回答；代码里看不出来的，就如实说"这段代码里看不出来"，不要编造。
+4. 如果问题和这段代码无关，礼貌说明并尽量给出有用的方向。
+5. 回答简洁，控制在几段以内，必要时可用短列表。
+
+直接输出答案正文，不要重复问题、不要加多余的客套。"""

backend/routers/analyze.py

@@ -0,0 +1,271 @@
+"""Analysis routes: generate project overview and file annotations."""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+from backend.models import EditRequest, QARequest
+from backend.prompts.annotate import build_annotation_prompt
+from backend.prompts.edit import build_edit_prompt, extract_code_block
+from backend.prompts.overview import build_overview_prompt
+from backend.prompts.qa import build_qa_prompt
+from backend.routers.project import get_project_data
+from backend.services import cache
+from backend.services.llm import call_llm, is_error_text, stream_llm
+
+logger = logging.getLogger(__name__)
+router = APIRouter(tags=["analyze"])
+
+
+def _extract_json(text: str) -> dict | list | None:
+    """Try to parse JSON from LLM output, handling markdown code fences."""
+    text = text.strip()
+    # strip ```json ... ``` wrapper
+    if text.startswith("```"):
+        first_nl = text.find("\n")
+        last_fence = text.rfind("```")
+        if first_nl != -1 and last_fence > first_nl:
+            text = text[first_nl + 1 : last_fence].strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    # fallback: find first [ or { and extract
+    for opener, closer in [("[", "]"), ("{", "}")]:
+        start = text.find(opener)
+        end = text.rfind(closer)
+        if start != -1 and end > start:
+            try:
+                return json.loads(text[start : end + 1])
+            except json.JSONDecodeError:
+                continue
+    return None
+
+
+def _coerce_annotation_list(parsed: dict | list | None) -> list:
+    """Normalize the model's parsed JSON into a list of annotations.
+
+    The prompt asks for a bare JSON array, but models sometimes wrap it in an
+    object (``{"annotations": [...]}``, ``{"批注": [...]}``, ...). Salvage the
+    array in that case instead of silently dropping every annotation and showing
+    the reader a file with no explanations.
+    """
+    if isinstance(parsed, list):
+        return parsed
+    if isinstance(parsed, dict):
+        for value in parsed.values():
+            if isinstance(value, list):
+                return value
+    return []
+
+
+def _client_ip(request: Request) -> str:
+    """Get the real client IP, respecting X-Forwarded-For behind a proxy."""
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+async def _enforce_rate_limit(request: Request):
+    """Raise 429 if the free-tier user has exceeded the daily limit.
+
+    BYOK users (with x-api-key header) are never rate-limited.
+    """
+    if request.headers.get("x-api-key"):
+        return  # user brought their own key, no limit
+
+    ip = _client_ip(request)
+    allowed, remaining = await cache.check_rate_limit(ip)
+    if not allowed:
+        raise HTTPException(
+            429,
+            "今日免费额度已用完（每天 20 次）。点击右上角设置，填入自己的 API Key 即可无限使用。",
+        )
+    # bump count now (before the actual LLM call)
+    await cache.increment_rate_limit(ip)
+
+
+@router.get("/project/{project_id}/overview")
+async def get_overview(project_id: str, request: Request):
+    """Generate or return cached project overview. Streams SSE."""
+    proj = await get_project_data(project_id)
+    if not proj:
+        raise HTTPException(404, "Project not found")
+
+    # build a cache key from file paths + sizes
+    files_sig = "|".join(f"{f['path']}:{f['size']}" for f in proj["files"])
+    cache_key = f"overview:{cache.content_hash(files_sig)}"
+
+    # check cache first (cached results are free, no rate limit)
+    cached = await cache.get(cache_key)
+    if cached:
+
+        async def cached_stream():
+            yield f"data: {json.dumps({'result': cached}, ensure_ascii=False)}\n\n"
+            yield "data: [DONE]\n\n"
+
+        return StreamingResponse(cached_stream(), media_type="text/event-stream")
+
+    # not cached -> requires LLM call -> check rate limit
+    await _enforce_rate_limit(request)
+
+    prompt = build_overview_prompt(proj["files"])
+    api_key = request.headers.get("x-api-key")
+
+    async def generate():
+        full_response = ""
+        errored = False
+        async for chunk in stream_llm(prompt, api_key=api_key):
+            full_response += chunk
+            # Don't stream a raw "[LLM Error: ...]" into the reader's view; once
+            # we see the sentinel, hold it back and report it as an error below.
+            if is_error_text(full_response):
+                errored = True
+                continue
+            yield f"data: {json.dumps({'chunk': chunk}, ensure_ascii=False)}\n\n"
+
+        if errored:
+            yield f"data: {json.dumps({'error': full_response}, ensure_ascii=False)}\n\n"
+            yield "data: [DONE]\n\n"
+            return
+
+        # try to parse and cache the full response
+        parsed = _extract_json(full_response)
+        if parsed and isinstance(parsed, dict):
+            await cache.put(cache_key, parsed)
+            yield f"data: {json.dumps({'result': parsed}, ensure_ascii=False)}\n\n"
+        else:
+            yield f"data: {json.dumps({'raw': full_response}, ensure_ascii=False)}\n\n"
+
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(generate(), media_type="text/event-stream")
+
+
+@router.get("/project/{project_id}/file/{file_path:path}/annotations")
+async def get_annotations(project_id: str, file_path: str, request: Request):
+    """Generate or return cached annotations for a file."""
+    proj = await get_project_data(project_id)
+    if not proj:
+        raise HTTPException(404, "Project not found")
+
+    content = proj.get("file_contents", {}).get(file_path)
+    if content is None:
+        raise HTTPException(404, f"File not found: {file_path}")
+
+    # detect language
+    lang = "python"
+    for f in proj["files"]:
+        if f["path"] == file_path:
+            lang = f["language"]
+            break
+
+    # cache by file content (cached results are free)
+    cache_key = f"annotate:{cache.content_hash(content)}"
+    cached = await cache.get(cache_key)
+    if cached:
+        return {"path": file_path, "language": lang, "annotations": cached}
+
+    # not cached -> LLM call -> rate limit
+    await _enforce_rate_limit(request)
+
+    prompt = build_annotation_prompt(content, lang)
+    api_key = request.headers.get("x-api-key")
+
+    result = await call_llm(prompt, api_key=api_key)
+
+    parsed = _extract_json(result)
+    annotations = _coerce_annotation_list(parsed)
+
+    if annotations:
+        await cache.put(cache_key, annotations)
+
+    return {"path": file_path, "language": lang, "annotations": annotations}
+
+
+@router.post("/project/{project_id}/qa")
+async def ask_question(project_id: str, req: QARequest, request: Request):
+    """Answer a free-form question about a selected piece of code.
+
+    Powers "select code and ask questions". Caches by question+code so a
+    repeated question is free and doesn't count against the rate limit.
+    """
+    proj = await get_project_data(project_id)
+    if not proj:
+        raise HTTPException(404, "Project not found")
+
+    question = req.question.strip()
+    if not question:
+        raise HTTPException(400, "Question must not be empty")
+
+    combined = question + "\x00" + req.code
+    cache_key = f"qa:{cache.content_hash(combined)}"
+    cached = await cache.get(cache_key)
+    if isinstance(cached, dict) and cached.get("answer"):
+        return {"answer": cached["answer"]}
+
+    await _enforce_rate_limit(request)
+
+    prompt = build_qa_prompt(
+        question,
+        req.code,
+        file_path=req.file_path,
+        language=req.language,
+    )
+    api_key = request.headers.get("x-api-key")
+    answer = (await call_llm(prompt, api_key=api_key)).strip()
+    if is_error_text(answer):
+        raise HTTPException(502, answer)
+
+    if answer:
+        await cache.put(cache_key, {"answer": answer})
+
+    return {"answer": answer}
+
+
+@router.post("/project/{project_id}/edit")
+async def edit_code(project_id: str, req: EditRequest, request: Request):
+    """Apply a natural-language instruction to a code snippet.
+
+    Returns a *suggested* edited version (CodeABC never writes to disk).
+    Cached by instruction+code so repeats are free.
+    """
+    proj = await get_project_data(project_id)
+    if not proj:
+        raise HTTPException(404, "Project not found")
+
+    instruction = req.instruction.strip()
+    if not instruction:
+        raise HTTPException(400, "Instruction must not be empty")
+    if not req.code.strip():
+        raise HTTPException(400, "Code must not be empty")
+
+    combined = instruction + "\x00" + req.code
+    cache_key = f"edit:{cache.content_hash(combined)}"
+    cached = await cache.get(cache_key)
+    if isinstance(cached, dict) and cached.get("edited_code"):
+        return {"edited_code": cached["edited_code"]}
+
+    await _enforce_rate_limit(request)
+
+    prompt = build_edit_prompt(
+        instruction,
+        req.code,
+        file_path=req.file_path,
+        language=req.language,
+    )
+    api_key = request.headers.get("x-api-key")
+    raw = await call_llm(prompt, api_key=api_key)
+    if is_error_text(raw):
+        raise HTTPException(502, raw)
+    edited = extract_code_block(raw)
+
+    if edited:
+        await cache.put(cache_key, {"edited_code": edited})
+
+    return {"edited_code": edited}