@blxzer/cursor-trellis 0.1.0 → 0.1.1

package/dist/templates/trellis/scripts/common/retrieval_agent_instructions.py

@@ -0,0 +1,313 @@
+#!/usr/bin/env python3
+"""
+Render codebase retrieval plan envelopes as agent-executable instructions.
+
+Complements JSON telemetry envelopes from codebase_retrieval_router.py; does not
+invoke tools. Cursor platform maps routes to native tool names (Grep, codegraph,
+built-in semantic search, GO_TO_DEFINITION).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_SYMBOL_CANDIDATE = re.compile(
+    r"\b([A-Za-z_][\w$]{2,})\b|"
+    r"`([^`]+)`|"
+    r"「([^」]+)」",
+)
+
+_SKIP_SYMBOLS = frozenset(
+    {
+        "openclaw",
+        "which",
+        "where",
+        "what",
+        "who",
+        "how",
+        "list",
+        "give",
+        "tell",
+        "define",
+        "defined",
+        "calls",
+        "call",
+        "invoke",
+        "invoked",
+        "file",
+        "files",
+        "module",
+        "modules",
+        "package",
+        "packages",
+        "extension",
+        "extensions",
+        "src",
+        "the",
+        "and",
+        "for",
+        "with",
+        "from",
+        "that",
+        "this",
+        "AGENTS",
+        "README",
+        "Cursor",
+    },
+)
+
+
+def _plan_dict(plan: dict[str, object] | Any) -> dict[str, object]:
+    if isinstance(plan, dict):
+        return plan
+    raise TypeError("plan must be a dict envelope from route_codebase_retrieval")
+
+
+def _symbol_rank(candidate: str) -> int:
+    if re.search(r"[a-z][A-Z]|[A-Z][a-z]", candidate):
+        return 3
+    if "_" in candidate or "$" in candidate:
+        return 2
+    if len(candidate) >= 10:
+        return 1
+    return 0
+
+
+def guess_symbol_from_query(query: str) -> str | None:
+    text = (query or "").strip()
+    if not text:
+        return None
+    best: tuple[int, str] | None = None
+    for match in _SYMBOL_CANDIDATE.finditer(text):
+        candidate = next(g for g in match.groups() if g)
+        if "/" in candidate or "." in candidate and candidate.count(".") > 2:
+            continue
+        if candidate.lower() in _SKIP_SYMBOLS:
+            continue
+        if len(candidate) < 4:
+            continue
+        rank = _symbol_rank(candidate)
+        if best is None or rank > best[0] or (rank == best[0] and len(candidate) > len(best[1])):
+            best = (rank, candidate)
+    return best[1] if best else None
+
+
+def _intent_summary(intents: list[dict[str, object]]) -> str:
+    if not intents:
+        return "（未分类，按默认精确检索）"
+    parts: list[str] = []
+    for item in intents[:4]:
+        ident = str(item.get("id", ""))
+        conf = str(item.get("confidence", ""))
+        parts.append(f"{ident}（{conf}）" if conf else ident)
+    return "、".join(parts)
+
+
+def _cursor_step_for_route(route: dict[str, object], *, symbol: str, query: str) -> str | None:
+    role = str(route.get("role", ""))
+    route_id = str(route.get("id", ""))
+
+    if role == "verification":
+        return None
+
+    if route_id == "caller-chain-ast" or (
+        role == "ast" and "caller" in route_id
+    ):
+        return (
+            f"使用 **codegraph_callers**，符号 `{symbol}`，列出调用链；"
+            "再补 codegraph_explore 若需跨文件流。"
+        )
+    if route_id.startswith("trap-demote") and role == "ast":
+        return (
+            f"使用 **codegraph_search** / **codegraph_explore**，消歧同名符号 `{symbol}`（跨 package trap）。"
+        )
+    if route_id.startswith("extension") and role == "ast":
+        return (
+            f"使用 **codegraph_search**，路径侧重 `extensions/`，符号 `{symbol}`。"
+        )
+    if role == "ast" or route_id in ("ast-codegraph",):
+        return (
+            f"使用 **codegraph_explore** 或 **codegraph_node**（`includeCode=true`），"
+            f"围绕 `{symbol}` 或问题：{query[:120]}"
+        )
+
+    if route_id == "platform-semantic" or (
+        role == "semantic" and str(route.get("sourceFamily")) == "platform-semantic"
+    ):
+        return (
+            "使用 Cursor **内置代码库语义搜索**（Agent 语义搜索能力，等同 @codebase 语义索引；"
+            "**不要**使用 fast-context MCP）。"
+        )
+    if role == "semantic":
+        return (
+            "使用 Cursor **内置代码库语义搜索**（不要用 fast-context MCP）。"
+        )
+
+    if route_id == "lsp-navigation" or role == "lsp":
+        return (
+            f"可选：若宿主暴露 **GO_TO_DEFINITION** / 查找引用，在已有候选上核对 `{symbol}`；"
+            "非 Agent 默认保证，未调用时用 **Read** + **Grep** 验证。"
+        )
+
+    if route_id == "policy-docs-rg" or str(route.get("sourceFamily")) == "policy-docs":
+        return (
+            "使用 **Grep** 在 `AGENTS.md`、`**/AGENTS.md`、`.trellis/spec`、`README.md` "
+            "中搜索策略/边界关键词。"
+        )
+
+    if role == "exact" or "rg" in route_id:
+        return (
+            f"使用 **Grep**（Instant Grep）搜索字面量/路径；优先与 `{symbol}` 或用户给出的路径相关模式。"
+        )
+
+    if route_id == "cross-cutting-discovery" or "deep" in route_id.lower():
+        return (
+            "复杂跨模块探索：可选用 **DEEP_SEARCH** 或 Explore 子任务，再用 Grep/codegraph 验证。"
+        )
+
+    return f"按路由 `{route_id}`（{role}）执行，再 Read 源码确认。"
+
+
+def _generic_step_for_route(route: dict[str, object], *, symbol: str, query: str) -> str | None:
+    role = str(route.get("role", ""))
+    if role == "verification":
+        return None
+    commands = route.get("commands")
+    cmd_hint = ""
+    if isinstance(commands, list) and commands:
+        cmd_hint = str(commands[0])[:160]
+    return f"执行路由 `{route.get('id')}`（{role}）：{cmd_hint or query[:80]}"
+
+
+def render_agent_instructions(
+    plan: dict[str, object],
+    *,
+    locale: str = "zh",
+) -> str:
+    """
+    Turn a route_codebase_retrieval envelope into numbered agent steps.
+    """
+    envelope = _plan_dict(plan)
+    query = str(envelope.get("query", ""))
+    intents = envelope.get("intents")
+    routes = envelope.get("routes")
+    fallback = envelope.get("fallback")
+    verification = envelope.get("verification")
+
+    intent_list = intents if isinstance(intents, list) else []
+    route_list = routes if isinstance(routes, list) else []
+    fallback_list = fallback if isinstance(fallback, list) else []
+    verification_list = verification if isinstance(verification, list) else []
+
+    symbol = guess_symbol_from_query(query) or "<symbol>"
+
+    if locale != "zh":
+        header = "## Codebase retrieval plan\n"
+    else:
+        header = "## 代码库检索计划\n"
+
+    lines = [
+        header.rstrip(),
+        f"问题：{query or '（空）'}",
+        f"意图：{_intent_summary(intent_list)}",
+        "",
+    ]
+
+    step = 0
+    sorted_routes = sorted(
+        route_list,
+        key=lambda r: int(r.get("order", 0)) if isinstance(r, dict) else 0,
+    )
+    for route in sorted_routes:
+        if not isinstance(route, dict):
+            continue
+        text = _cursor_step_for_route(route, symbol=symbol, query=query)
+        if not text:
+            continue
+        step += 1
+        lines.append(f"{step}. {text}")
+
+    if step == 0:
+        step += 1
+        lines.append(
+            f"{step}. 使用 **Grep** 搜索关键词，再 **Read** 打开候选文件验证。"
+        )
+
+    if fallback_list:
+        lines.append("")
+        lines.append("**降级**：")
+        for hint in fallback_list[:3]:
+            if not isinstance(hint, dict):
+                continue
+            when = str(hint.get("when", ""))
+            action = str(hint.get("action", ""))
+            if when and action:
+                lines.append(f"- 当 {when} → {action}")
+
+    if verification_list:
+        lines.append("")
+        lines.append("**验证**（下结论前）：")
+        for ver in verification_list[:4]:
+            if not isinstance(ver, dict):
+                continue
+            req = str(ver.get("requirement", ""))
+            if req:
+                lines.append(f"- {req}")
+
+    lines.append("")
+    lines.append(
+        "**codegraph 独用场景**：调用链、跨包 trap、extension 符号、影响面；"
+        "纯字面搜索用 Grep，单点定义用 GO_TO_DEFINITION。"
+    )
+
+    if any(
+        isinstance(r, dict) and r.get("id") == "platform-semantic" for r in route_list
+    ):
+        lines.append("")
+        if locale != "zh":
+            lines.append("**Semantic compliance (Cursor):**")
+            lines.append(
+                "- When this plan lists **platform-semantic**, run **one** Cursor built-in "
+                "codebase / semantic search before final Top-1 (not fast-context MCP)."
+            )
+            lines.append(
+                "- Log the **exact tool name** from the host (e.g. codebase_search, @codebase) "
+                "in your run notes for semantic_exec_rate."
+            )
+        else:
+            lines.append("**语义合规（Cursor）：**")
+            lines.append(
+                "- 本计划含 **platform-semantic** 时：定 Top-1 前至少执行 **1 次** "
+                "Cursor **内置代码库语义搜索**（不要用 fast-context MCP）。"
+            )
+            lines.append(
+                "- 在 run 记录中写下宿主返回的**真实工具名**（如 codebase_search、@codebase），"
+                "供 semantic_exec 统计。"
+            )
+
+    try:
+        from .semantic_plan_gate import semantic_compliance_gate_hint  # noqa: PLC0415
+
+        gate_hint = semantic_compliance_gate_hint(envelope, locale=locale)
+        if gate_hint:
+            lines.append("")
+            lines.append(gate_hint)
+    except Exception:
+        pass
+
+    try:
+        from .retrieval_result_ranking import (  # noqa: PLC0415
+            intent_ids_from_router_envelope,
+            result_layer_ranking_hint,
+        )
+
+        intent_ids = intent_ids_from_router_envelope(envelope)
+        ranking_hint = result_layer_ranking_hint(intent_ids, locale=locale)
+        if ranking_hint:
+            lines.append("")
+            lines.append(ranking_hint.rstrip())
+    except Exception:
+        pass
+
+    return "\n".join(lines).strip() + "\n"

package/dist/templates/trellis/scripts/common/retrieval_pack.py

@@ -316,11 +316,6 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
         "--root",
         help="Repository root for read-only Smart Search manifest discovery.",
     )
-    parser.add_argument(
-        "--platform",
-        default=None,
-        help="Host platform for platform-adaptive retrieval routing (e.g. cursor, claude-code, codex).",
-    )
     parser.add_argument(
         "--max-items",
         type=int,
@@ -385,7 +380,6 @@ def main(argv: list[str] | None = None) -> int:
             resolve_repo_root(args.root),
             explicit_router=dict_value(payload.get("routerEnvelope")) or None,
             query=string_value(payload.get("query")) or None,
-            platform=args.platform,
         ),
         adapter_hints=normalize_dict_list(list_value(payload.get("adapterHints"))),
     )

package/dist/templates/trellis/scripts/common/retrieval_pack_context.py

@@ -51,7 +51,6 @@ def get_context_retrieval_pack_json(
     max_items: int | None = None,
     max_estimated_tokens: int | None = None,
     include_diagnostics: bool = False,
-    platform: str | None = None,
     project_file_count: int | None = None,
 ) -> dict[str, object]:
     """Build a retrieval pack from session guidance and optional evidence input."""
@@ -92,7 +91,6 @@ def get_context_retrieval_pack_json(
             repo_root,
             explicit_router=dict_value(payload.get("routerEnvelope")) or None,
             query=string_value(payload.get("query")) or None,
-            platform=platform,
             project_file_count=project_file_count,
         ),
         adapter_hints=normalize_dict_list(list_value(payload.get("adapterHints"))),
@@ -107,7 +105,6 @@ def output_retrieval_pack_json(
     max_estimated_tokens: int | None = None,
     include_diagnostics: bool = False,
     pretty: bool = False,
-    platform: str | None = None,
     project_file_count: int | None = None,
 ) -> None:
     """Print retrieval pack JSON to stdout."""
@@ -117,7 +114,6 @@ def output_retrieval_pack_json(
         max_items=max_items,
         max_estimated_tokens=max_estimated_tokens,
         include_diagnostics=include_diagnostics,
-        platform=platform,
         project_file_count=project_file_count,
     )
     if pretty:

package/dist/templates/trellis/scripts/common/retrieval_plan_gate.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Gate whether to inject a per-turn codebase retrieval plan block."""
+
+from __future__ import annotations
+
+import re
+
+from .codebase_retrieval_router import (
+    INTENT_CALLER,
+    INTENT_CONCEPTUAL,
+    INTENT_ENV,
+    INTENT_EXTENSION,
+    INTENT_POLICY,
+    INTENT_TRAP,
+    classify_codebase_retrieval_intents,
+)
+
+_SKIP_EXACT = frozenset(
+    {
+        "继续",
+        "continue",
+        "yes",
+        "y",
+        "ok",
+        "好的",
+        "是的",
+        "可以",
+        "thanks",
+        "thank you",
+    }
+)
+
+_META_PREFIXES = (
+    "[triage:",
+    "/trellis",
+    "/shell",
+)
+
+
+def extract_user_prompt(hook_input: dict[str, object]) -> str:
+    """Best-effort user text from a per-turn hook stdin payload."""
+    for key in ("prompt", "user_message", "text", "message", "content"):
+        raw = hook_input.get(key)
+        if isinstance(raw, str) and raw.strip():
+            return raw.strip()
+    return ""
+
+
+def should_inject_retrieval_plan(query: str) -> bool:
+    """Return True when router-backed plan injection is worth the tokens."""
+    text = (query or "").strip()
+    if not text:
+        return False
+    lowered = text.lower()
+    if lowered in _SKIP_EXACT:
+        return False
+    if any(lowered.startswith(prefix) for prefix in _META_PREFIXES):
+        return False
+    if len(text) < 8 and not re.search(r"[\u4e00-\u9fff]", text):
+        return False
+
+    intents = classify_codebase_retrieval_intents(text)
+    intent_ids = {str(item.get("id", "")) for item in intents}
+    structural = {
+        INTENT_CALLER,
+        INTENT_TRAP,
+        INTENT_EXTENSION,
+        INTENT_ENV,
+        INTENT_POLICY,
+        INTENT_CONCEPTUAL,
+    }
+    if intent_ids & structural:
+        return True
+    if len(text) >= 12:
+        return True
+    return bool(re.search(r"[\u4e00-\u9fff]{3,}", text) and len(text) >= 6)

package/dist/templates/trellis/scripts/common/retrieval_result_ranking.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Result-layer ranking for B/E/D intents (mirrors retrieval-result-ranking.ts)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+RankingIntent = str
+
+INTENT_CALLER = "caller-chain"
+INTENT_TRAP = "trap-package-disambiguation"
+INTENT_ENV = "env-config-literal"
+INTENT_EXACT = "exact-symbol-path"
+INTENT_PRESERVE = "protocol-platform-preserve"
+
+
+def _norm(path: str) -> str:
+    return path.replace("\\", "/").lower()
+
+
+def _includes(intents: list[str], target: str) -> bool:
+    return target in intents
+
+
+def _is_assembly_only(candidate: dict[str, Any]) -> bool:
+    path = _norm(str(candidate.get("path", "")))
+    role = str(candidate.get("sourceRole") or candidate.get("source_role") or "")
+    evidence = str(candidate.get("evidenceType") or candidate.get("evidence_type") or "")
+    if evidence == "assembly":
+        return True
+    if re.search(r"(?:facade|loader|barrel|runtime|registry|snapshot)", role, re.I):
+        return True
+    return bool(re.search(r"(?:facade|loader|barrel|runtime|registry|snapshot)", path, re.I))
+
+
+def _is_concrete_caller(candidate: dict[str, Any]) -> bool:
+    evidence = str(candidate.get("evidenceType") or candidate.get("evidence_type") or "")
+    role = str(candidate.get("sourceRole") or candidate.get("source_role") or "")
+    if evidence == "caller-callsite":
+        return True
+    return bool(re.search(r"caller|callsite", role, re.I))
+
+
+def _is_trap(candidate: dict[str, Any]) -> bool:
+    path = _norm(str(candidate.get("path", "")))
+    if candidate.get("trapHint") is True or candidate.get("trap_hint") is True:
+        return True
+    evidence = str(candidate.get("evidenceType") or candidate.get("evidence_type") or "")
+    if evidence == "trap":
+        return True
+    if re.search(r"plugin-registry-snapshot|registry-snapshot|snapshot\.ts$", path):
+        return True
+    return "/src/agents/" in path
+
+
+def _is_env_priority(candidate: dict[str, Any]) -> bool:
+    path = _norm(str(candidate.get("path", "")))
+    return bool(
+        re.search(
+            r"(^|/)(scripts|e2e|bench|benches|\.github|ci|config|configs|test|tests)(/|$)",
+            path,
+        )
+    )
+
+
+def _is_generic_env_impl(candidate: dict[str, Any]) -> bool:
+    path = _norm(str(candidate.get("path", "")))
+    return bool(re.search(r"(^|/)src/(auth|paths?|state|config)(/|\.|$)", path))
+
+
+def _base_score(candidate: dict[str, Any]) -> float:
+    if isinstance(candidate.get("score"), (int, float)):
+        return float(candidate["score"])
+    base_rank = int(candidate.get("baseRank") or candidate.get("base_rank") or 0)
+    return float(1000 - base_rank)
+
+
+def score_candidate(
+    candidate: dict[str, Any],
+    intents: list[str],
+) -> dict[str, Any]:
+    adjusted = _base_score(candidate)
+    reasons: list[str] = []
+    matched = candidate.get("matchedIntents") or candidate.get("matched_intents") or []
+    if not isinstance(matched, list):
+        matched = []
+
+    exact_preserve = (
+        candidate.get("exactPreserve") is True
+        or candidate.get("exact_preserve") is True
+        or INTENT_PRESERVE in matched
+        or INTENT_EXACT in matched
+    )
+
+    if exact_preserve:
+        adjusted += 1000
+        reasons.append("exact-preserve-protected")
+
+    if not exact_preserve and _includes(intents, INTENT_CALLER):
+        evidence = str(candidate.get("evidenceType") or candidate.get("evidence_type") or "")
+        if evidence == "codegraph-caller":
+            adjusted += 30
+            reasons.append("codegraph-caller-boost")
+        if _is_concrete_caller(candidate):
+            adjusted += 150
+            reasons.append("concrete-caller-boost")
+        if _is_assembly_only(candidate):
+            adjusted -= 120
+            reasons.append("assembly-only-demotion")
+
+    if not exact_preserve and _includes(intents, INTENT_TRAP):
+        if _is_trap(candidate) and not candidate.get("expectedHint") and not candidate.get(
+            "expected_hint"
+        ):
+            adjusted -= 250
+            reasons.append("trap-demotion")
+        if candidate.get("corroborated") and not _is_trap(candidate):
+            adjusted += 80
+            reasons.append("corroborated-non-trap-boost")
+
+    if not exact_preserve and _includes(intents, INTENT_ENV):
+        if _is_env_priority(candidate):
+            adjusted += 140
+            reasons.append("env-script-priority")
+        if _is_generic_env_impl(candidate):
+            adjusted -= 100
+            reasons.append("generic-env-implementation-demotion")
+
+    out = dict(candidate)
+    out["adjustedScore"] = adjusted
+    out["adjusted_score"] = adjusted
+    out["rankingReasons"] = reasons
+    out["ranking_reasons"] = reasons
+    return out
+
+
+def rank_retrieval_result_candidates(
+    candidates: list[dict[str, Any]],
+    *,
+    intents: list[str],
+    top_k: int = 5,
+    expanded_pool_size: int | None = None,
+    caller_pool_expansion: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    top_k = max(1, top_k)
+    pool_size = expanded_pool_size if expanded_pool_size is not None else max(top_k * 3, top_k)
+    warnings: list[str] = []
+
+    ranked = [
+        score_candidate(c, intents)
+        for c in candidates
+    ]
+    ranked.sort(
+        key=lambda c: (
+            -float(c.get("adjustedScore") or c.get("adjusted_score") or 0),
+            int(c.get("baseRank") or c.get("base_rank") or 0),
+        ),
+    )
+
+    expanded_pool = ranked[:pool_size]
+
+    expansion = caller_pool_expansion or {}
+    if expansion.get("enabled") and _includes(intents, INTENT_CALLER):
+        min_concrete = int(expansion.get("minConcreteCallers") or expansion.get("min_concrete_callers") or 0)
+        concrete_in_pool = [c for c in expanded_pool if _is_concrete_caller(c)]
+        seen_paths = {_norm(str(c.get("path", ""))) for c in concrete_in_pool}
+
+        if min_concrete > 0 and len(concrete_in_pool) < min_concrete:
+            for candidate in ranked[pool_size:]:
+                if not _is_concrete_caller(candidate):
+                    continue
+                key = _norm(str(candidate.get("path", "")))
+                if key in seen_paths:
+                    continue
+                expanded_pool.append(candidate)
+                seen_paths.add(key)
+                if len([c for c in expanded_pool if _is_concrete_caller(c)]) >= min_concrete:
+                    break
+
+        final_count = len([c for c in expanded_pool if _is_concrete_caller(c)])
+        if min_concrete > 0 and final_count < min_concrete:
+            warnings.append(
+                f"caller-pool-expansion: only {final_count} concrete callers found, "
+                f"below minConcreteCallers={min_concrete}"
+            )
+
+    return {
+        "expandedPoolSize": pool_size,
+        "expanded_pool_size": pool_size,
+        "expandedPool": expanded_pool,
+        "expanded_pool": expanded_pool,
+        "topCandidates": expanded_pool[:top_k],
+        "top_candidates": expanded_pool[:top_k],
+        "warnings": warnings,
+    }
+
+
+def intent_ids_from_router_envelope(plan: dict[str, Any]) -> list[str]:
+    raw = plan.get("intents")
+    if not isinstance(raw, list):
+        return []
+    ids: list[str] = []
+    for item in raw:
+        if isinstance(item, dict) and item.get("id"):
+            ids.append(str(item["id"]))
+    return ids
+
+
+def result_layer_ranking_hint(intents: list[str], *, locale: str = "zh") -> str:
+    """Short agent guidance appended to retrieval plans when B/E/D intents fire."""
+    lines: list[str] = []
+    if locale != "zh":
+        lines.append("**Result-layer ranking (before Top-1 / Top-5):**")
+    else:
+        lines.append("**结果层排序（定 Top-1 / Top-5 前）：**")
+
+    if INTENT_CALLER in intents:
+        if locale != "zh":
+            lines.append(
+                "- Caller-chain: keep an expanded pool (codegraph callers + rg); "
+                "prefer concrete call sites over facade/barrel/runtime/registry assembly files."
+            )
+        else:
+            lines.append(
+                "- 调用链：先扩大候选池（codegraph callers + rg），"
+                "具体调用点优先于 facade/barrel/runtime/registry 等装配文件。"
+            )
+    if INTENT_TRAP in intents:
+        if locale != "zh":
+            lines.append(
+                "- Trap: demote snapshot/registry overlay and cross-package name collisions "
+                "unless Read confirms the asked layer."
+            )
+        else:
+            lines.append(
+                "- 干扰项：压低 snapshot/registry/overlay 与跨包同名；"
+                "除非 Read 确认就是所问层级。"
+            )
+    if INTENT_ENV in intents:
+        if locale != "zh":
+            lines.append(
+                "- Env literals: prefer scripts/e2e/bench/test harness paths over generic src/auth/paths."
+            )
+        else:
+            lines.append(
+                "- 环境变量/配置字面量：优先 scripts/e2e/bench/test 等路径，"
+                "低于泛化 src/auth/paths 实现文件。"
+            )
+
+    if len(lines) <= 1:
+        return ""
+    return "\n".join(lines) + "\n"