@blxzer/cursor-trellis 0.1.1 → 0.1.3

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

@@ -12,6 +12,8 @@ from __future__ import annotations
 import re
 from typing import Any
 
+from .cursor_retrieval_env import ENV_BYOK, detect_cursor_retrieval_env
+
 _SYMBOL_CANDIDATE = re.compile(
     r"\b([A-Za-z_][\w$]{2,})\b|"
     r"`([^`]+)`|"
@@ -104,7 +106,13 @@ def _intent_summary(intents: list[dict[str, object]]) -> str:
     return "、".join(parts)
 
 
-def _cursor_step_for_route(route: dict[str, object], *, symbol: str, query: str) -> str | None:
+def _cursor_step_for_route(
+    route: dict[str, object],
+    *,
+    symbol: str,
+    query: str,
+    cursor_env: str,
+) -> str | None:
     role = str(route.get("role", ""))
     route_id = str(route.get("id", ""))
 
@@ -126,6 +134,11 @@ def _cursor_step_for_route(route: dict[str, object], *, symbol: str, query: str)
         return (
             f"使用 **codegraph_search**，路径侧重 `extensions/`，符号 `{symbol}`。"
         )
+    if route_id == "lsp-navigation":
+        return (
+            f"使用 **codegraph_node**（`includeCode=true`）或 **codegraph_search** 定位 `{symbol}` "
+            "的定义/引用（Agent 无 GO_TO_DEFINITION）；再用 **Read** 验证行号与正文。"
+        )
     if role == "ast" or route_id in ("ast-codegraph",):
         return (
             f"使用 **codegraph_explore** 或 **codegraph_node**（`includeCode=true`），"
@@ -135,21 +148,27 @@ def _cursor_step_for_route(route: dict[str, object], *, symbol: str, query: str)
     if route_id == "platform-semantic" or (
         role == "semantic" and str(route.get("sourceFamily")) == "platform-semantic"
     ):
+        backend = str(route.get("semanticBackend", ""))
+        if cursor_env == ENV_BYOK or backend == "fast-context-mcp":
+            return (
+                "使用 **fast_context_search**（fast-context MCP）做概念/代码库语义检索；"
+                "**不要**假设 @codebase 或内置 SemanticSearch 可用；**不要**用 WebSearch 答代码库问题。"
+            )
         return (
-            "使用 Cursor **内置代码库语义搜索**（Agent 语义搜索能力，等同 @codebase 语义索引；"
-            "**不要**使用 fast-context MCP）。"
+            "使用 Cursor **内置代码库语义搜索**（宿主工具常为 **SemanticSearch**；"
+            "**`target_directories`** 为目录 glob 数组，省略会报错；**`[]`** = 不缩范围、搜全工作区索引；"
+            "若计划或 Grep/codegraph 已指向子树可传如 `['Trellis/packages/cli']`；"
+            "无路径线索的概念题优先 **`[]`**；Native 下 **不要**用 fast-context MCP 顶替）。"
         )
     if role == "semantic":
+        if cursor_env == ENV_BYOK:
+            return (
+                "使用 **fast_context_search**（fast-context MCP）；勿用 WebSearch 答代码库问题。"
+            )
         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` "
@@ -162,6 +181,10 @@ def _cursor_step_for_route(route: dict[str, object], *, symbol: str, query: str)
         )
 
     if route_id == "cross-cutting-discovery" or "deep" in route_id.lower():
+        if cursor_env == ENV_BYOK:
+            return (
+                "复杂跨模块探索：使用 **Task** 子代理（explore），再用 Grep/codegraph/Read 验证。"
+            )
         return (
             "复杂跨模块探索：可选用 **DEEP_SEARCH** 或 Explore 子任务，再用 Grep/codegraph 验证。"
         )
@@ -201,6 +224,7 @@ def render_agent_instructions(
     verification_list = verification if isinstance(verification, list) else []
 
     symbol = guess_symbol_from_query(query) or "<symbol>"
+    cursor_env = str(envelope.get("cursorEnv") or detect_cursor_retrieval_env())
 
     if locale != "zh":
         header = "## Codebase retrieval plan\n"
@@ -211,6 +235,7 @@ def render_agent_instructions(
         header.rstrip(),
         f"问题：{query or '（空）'}",
         f"意图：{_intent_summary(intent_list)}",
+        f"检索环境（cursorEnv）：{cursor_env}",
         "",
     ]
 
@@ -222,7 +247,9 @@ def render_agent_instructions(
     for route in sorted_routes:
         if not isinstance(route, dict):
             continue
-        text = _cursor_step_for_route(route, symbol=symbol, query=query)
+        text = _cursor_step_for_route(
+            route, symbol=symbol, query=query, cursor_env=cursor_env
+        )
         if not text:
             continue
         step += 1
@@ -257,34 +284,52 @@ def render_agent_instructions(
 
     lines.append("")
     lines.append(
-        "**codegraph 独用场景**：调用链、跨包 trap、extension 符号、影响面；"
-        "纯字面搜索用 Grep，单点定义用 GO_TO_DEFINITION。"
+        "**codegraph 独用场景**：调用链、跨包 trap、extension 符号、影响面、定义/引用定位；"
+        "纯字面搜索用 Grep（勿用 GO_TO_DEFINITION，Agent 未暴露）。"
     )
 
     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."
-            )
+        if cursor_env == ENV_BYOK:
+            if locale != "zh":
+                lines.append("**Semantic compliance (Cursor++ BYOK):**")
+                lines.append(
+                    "- Run **one** `fast_context_search` before final Top-1 when "
+                    "**platform-semantic** is listed; log the MCP tool name."
+                )
+            else:
+                lines.append("**语义合规（Cursor++ BYOK）：**")
+                lines.append(
+                    "- 本计划含 **platform-semantic** 时：定 Top-1 前至少 **1 次** "
+                    "**fast_context_search**（fast-context MCP），并记录工具名。"
+                )
         else:
-            lines.append("**语义合规（Cursor）：**")
-            lines.append(
-                "- 本计划含 **platform-semantic** 时：定 Top-1 前至少执行 **1 次** "
-                "Cursor **内置代码库语义搜索**（不要用 fast-context MCP）。"
-            )
-            lines.append(
-                "- 在 run 记录中写下宿主返回的**真实工具名**（如 codebase_search、@codebase），"
-                "供 semantic_exec 统计。"
-            )
+            if locale != "zh":
+                lines.append("**Semantic compliance (Cursor Native):**")
+                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 Native）：**")
+                lines.append(
+                    "- 本计划含 **platform-semantic** 时：定 Top-1 前至少执行 **1 次** "
+                    "Cursor **内置代码库语义搜索**（不要用 fast-context MCP）。"
+                )
+                lines.append(
+                    "- 在 run 记录中写下宿主返回的**真实工具名**（如 SemanticSearch、codebase_search、@codebase），"
+                    "供 semantic_exec 统计。"
+                )
+                lines.append(
+                    "- 若工具为 **SemanticSearch**：**必须提供** **`target_directories`**；"
+                    "**`[]`** = 全库；已知子目录时用 glob 收窄（勿省略该字段）。"
+                )
 
     try:
         from .semantic_plan_gate import semantic_compliance_gate_hint  # noqa: PLC0415

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

@@ -88,7 +88,13 @@ class ClassifiedToolCalls:
     cursor_fast_context_misuse: bool = False
 
 
-def classify_tool_calls(raw: list[str], *, platform: str = "cursor") -> ClassifiedToolCalls:
+def classify_tool_calls(
+    raw: list[str],
+    *,
+    platform: str = "cursor",
+    cursor_env: str | None = None,
+    route_ids: list[str] | None = None,
+) -> ClassifiedToolCalls:
     tools_called = list(raw)
     grep_count = 0
     read_count = 0
@@ -115,13 +121,22 @@ def classify_tool_calls(raw: list[str], *, platform: str = "cursor") -> Classifi
         if is_platform_semantic_tool_name(trimmed):
             platform_semantic_executed = True
 
+    env = (cursor_env or "").strip().lower()
     if plat == "cursor":
-        semantic_executed = platform_semantic_executed
+        if env == "byok":
+            semantic_executed = platform_semantic_executed or fast_context_count > 0
+        else:
+            semantic_executed = platform_semantic_executed
     else:
         semantic_executed = platform_semantic_executed or fast_context_count > 0
 
     semantic_attempted = semantic_executed or fast_context_count > 0
-    misuse = plat == "cursor" and fast_context_count > 0
+
+    misuse = (
+        plat == "cursor"
+        and fast_context_count > 0
+        and env != "byok"
+    )
 
     return ClassifiedToolCalls(
         tools_called=tools_called,

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

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from typing import Any
 
+from .cursor_retrieval_env import ENV_BYOK, detect_cursor_retrieval_env
+
 
 def platform_semantic_order_from_envelope(envelope: dict[str, Any]) -> int | None:
     routes = envelope.get("routes")
@@ -37,6 +39,22 @@ def semantic_compliance_gate_hint(
     if not any(isinstance(r, dict) and r.get("id") == "platform-semantic" for r in routes):
         return ""
 
+    cursor_env = str(envelope.get("cursorEnv") or detect_cursor_retrieval_env())
+
+    if cursor_env == ENV_BYOK:
+        if locale != "zh":
+            return (
+                "**Plan gate (REC-11, BYOK):** `platform-semantic` is step "
+                f"#{order}. Before Top-1 you MUST run one **fast_context_search** "
+                "(fast-context MCP). Do not use WebSearch for codebase questions. "
+                "Corroborate hits with Read."
+            )
+        return (
+            "**计划门控（REC-11，BYOK）：** 本问 `platform-semantic` 为第 "
+            f"{order} 步。定 Top-1 前 **必须** 执行 1 次 **fast_context_search**（fast-context MCP）；"
+            "**禁止** 用 WebSearch 答代码库问题。命中路径后须 **Read** 验证。"
+        )
+
     if locale != "zh":
         return (
             "**Plan gate (REC-11):** `platform-semantic` is step "
@@ -48,5 +66,6 @@ def semantic_compliance_gate_hint(
         "**计划门控（REC-11）：** 本问 `platform-semantic` 为第 "
         f"{order} 步。定 Top-1 前 **必须** 执行 1 次 Cursor **内置代码库语义搜索**，"
         "并在记录中写下宿主工具名；**禁止** fast-context MCP。"
+        "若工具为 **SemanticSearch**，须传 **`target_directories`**（`[]` 全库，或已知子目录 glob 收窄）。"
         "语义命中路径后须 **Read** 验证候选片段（verified 层）。"
     )

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

@@ -125,7 +125,7 @@ def main(argv: list[str] | None = None) -> int:
             print_manifest(manifest, args.json)
             return 4
         doctor_data = parse_json_output(doctor_result.stdout)
-        if doctor_result.returncode != 0 or doctor_data.get("ok") is False:
+        if doctor_result.returncode != 0 or not doctor_data.get("ok"):
             manifest = build_manifest(
                 repo_root=repo_root,
                 query=args.query,
@@ -188,7 +188,7 @@ class CommandResult:
         self.not_found = not_found
 
 
-def run_command(command: list[str], cwd: Path) -> CommandResult:
+def run_command(command: list[str], cwd: Path, timeout: int = 120) -> CommandResult:
     try:
         completed = subprocess.run(
             command,
@@ -198,8 +198,11 @@ def run_command(command: list[str], cwd: Path) -> CommandResult:
             errors="replace",
             capture_output=True,
             check=False,
+            timeout=timeout,
         )
         return CommandResult(completed.returncode, completed.stdout or "", completed.stderr or "")
+    except subprocess.TimeoutExpired:
+        return CommandResult(124, "", f"Command timed out after {timeout}s")
     except FileNotFoundError as error:
         return CommandResult(127, "", str(error), not_found=True)