@surething/cockpit 1.0.213 → 1.0.214

package/.next-prod/server/chunks/7828.js

@@ -383,7 +383,45 @@ curl -fsS "{{BASE_URL}}/api/projectGraph/coedit?cwd=$PWD&filePath=<REL_PATH>"
 ## 技术契约
 - 接口只返坐标，源码用 Read 自取：\`Read offset=startLine limit=endLine-startLine+1\`
 - qname 用 \`Parent>Child\` 形式（不是 \`.\`），直接复用 search 返回的 \`qualifiedName\`
-- 同名符号跨多文件时响应里 \`ambiguousIn\` 列出，加 \`&filePath=<rel>\` 消歧`,en:`Enter project graph exploration mode (CodeGraph).
+- 同名符号跨多文件时响应里 \`ambiguousIn\` 列出，加 \`&filePath=<rel>\` 消歧
+
+## 3 个进阶接口（智能排序 / 关联 / 风险）
+
+当基础 6 个接口的纯结构信息不够用 —— 尤其在"探索式追代码"或"评估影响范围"时 —— 用这 3 个接口拿到带相关性评分和风险标注的结果。
+
+| 问题 | 接口 |
+|---|---|
+| 这个问题/光标位置相关的代码在哪？ | context?query=&cursor= |
+| 看 X 时，还应该顺手看哪些相关代码？ | related?qname=X |
+| 改 X 真正高风险的少数节点是哪些？哪些测试要跑？ | risk?qname=X |
+| 改了这些文件，CI 应该跑哪些测试文件？（保守闭包） | affected?files=… |
+
+# context: 多源种子语义检索（query / cursor / openFiles 任传其一）
+# 返回 Top-K 相关坐标 + signals（query-match / ppr / pagerank / open）
+curl -fsS "{{BASE_URL}}/api/projectGraph/context?cwd=$PWD&query=<TEXT>&cursor=<FILE>::<QNAME>&topK=15"
+
+# related: 比 callers/callees 更广，纳入 coedit / PPR 邻居 / Louvain 社区
+# 每个结果带 relations 数组：caller / callee / ppr-neighbor / frequent-coedit / sibling-in-community
+# 同名跨多文件时响应里 ambiguousIn 列出，加 &filePath=<rel> 消歧（同 callers/callees 行为）
+curl -fsS "{{BASE_URL}}/api/projectGraph/related?cwd=$PWD&qname=<QNAME>&topK=10"
+
+# risk: impact 的风险化版本
+# 返回 highRisk（按 risk.score 降序） + suggestedTests 建议运行的测试文件
+# risk.score = callFreq + coeditProb + (hasTest ? 0 : penalty) + pagerank，按 depth 衰减
+curl -fsS "{{BASE_URL}}/api/projectGraph/risk?cwd=$PWD&qname=<QNAME>&depth=2&topK=20"
+
+# affected: 给定一组改动文件，沿 importedBy 闭包返回受影响的测试文件
+# 与 risk 互补：risk 给人/LLM 看（按符号、精准），affected 给 CI/管道用（按文件、保守）
+# 多文件输入用 POST，URL 太长用 POST；要纯文本输出用 format=plain
+curl -fsS "{{BASE_URL}}/api/projectGraph/affected?cwd=$PWD&files=<a.ts,b.ts>&depth=10"
+
+## 进阶接口契约
+- \`score\` / \`risk.score\` 只用于排序参考，无绝对意义
+- \`signals\` / \`relations\` / \`tags\` 是"为什么相关"的解释，引用时可直接告诉用户
+- \`degraded: true\` 时结果仍可用，但精度降低；\`degradedReason\` 给出原因（\`analytics-warming\` 表示后台索引还在预热，\`coedit-unavailable\` 表示 git 历史信号不可用，回落手工挑测试）
+- **risk / related 响应里已经带 \`coedit\` 字段**（target 文件的 coedit 历史），同一文件不要再单独发 /coedit 请求
+- related 响应若有 \`ambiguousIn\`，表示同名符号跨多文件，下次调用补 \`&filePath=\`
+- 这 3 个接口同样只返坐标，源码用 Read 自取`,en:`Enter project graph exploration mode (CodeGraph).
 
 CodeGraph = pre-built symbol + call-graph index + git co-edit view. Six endpoints, each answers one class of question:
 
@@ -420,6 +458,45 @@ curl -fsS "{{BASE_URL}}/api/projectGraph/coedit?cwd=$PWD&filePath=<REL_PATH>"
 ## Technical contract
 - Endpoints return coordinates only. Fetch source with Read: \`Read offset=startLine limit=endLine-startLine+1\`
 - qname uses \`Parent>Child\` form (not \`.\`); copy \`qualifiedName\` from search's response directly
-- Cross-file name collisions are listed in \`ambiguousIn\` — pass \`&filePath=<rel>\` to disambiguate`,labelZh:"探索问题：",labelEn:"Exploration: "}};function e(a,b="en",c){var f,g;let h,i=a.trimStart(),j=i.match(/^\/([a-zA-Z]+)(?:\s+|$)/);if(!j)return a;let k=j[1],l=b.startsWith("zh")?"zh":"en",m=d[k],n=m?.[l];if(!n)return a;let o=function(a){if(a){let b=new URL(a.url),c=a.headers.get("x-forwarded-proto"),d=a.headers.get("x-forwarded-host");return c||d?`${c??b.protocol.replace(":","")}://${d??b.host}`:b.origin}let b=process.env.COCKPIT_PORT||process.env.PORT||"3457";return`http://localhost:${b}`}(c),p=n.replaceAll("{{BASE_URL}}",o),q=i.slice(j[0].length).trimStart(),r=(f=m,(h="zh"===(g=l)?f.labelZh:f.labelEn)||("zh"===g?"问题：":"Question: "));return q?`${p}
+- Cross-file name collisions are listed in \`ambiguousIn\` — pass \`&filePath=<rel>\` to disambiguate
+
+## Three advanced endpoints (smart ranking / relatedness / risk)
+
+When the six base endpoints' pure structural data isn't enough — especially when exploring code or evaluating change impact — use these to get scored, signal-annotated results.
+
+| Question | Endpoint |
+|---|---|
+| Where is the code related to this question / cursor? | context?query=&cursor= |
+| What else should I read while looking at X? | related?qname=X |
+| Changing X — which few nodes truly matter? Which tests to run? | risk?qname=X |
+| Changed these files — which tests should CI run? (conservative closure) | affected?files=… |
+
+# context: multi-source semantic retrieval (query / cursor / openFiles — at least one)
+# Returns Top-K relevant coordinates + signals (query-match / ppr / pagerank / open)
+curl -fsS "{{BASE_URL}}/api/projectGraph/context?cwd=$PWD&query=<TEXT>&cursor=<FILE>::<QNAME>&topK=15"
+
+# related: broader than callers/callees — includes coedit / PPR neighbours / Louvain community
+# Each result carries a relations[] array: caller / callee / ppr-neighbor / frequent-coedit / sibling-in-community
+# Cross-file name collisions are listed in ambiguousIn — pass &filePath=<rel> to disambiguate (same as callers/callees)
+curl -fsS "{{BASE_URL}}/api/projectGraph/related?cwd=$PWD&qname=<QNAME>&topK=10"
+
+# risk: risk-scored impact
+# Returns highRisk (sorted by risk.score desc) + suggestedTests
+# risk.score = callFreq + coeditProb + (hasTest ? 0 : penalty) + pagerank, decayed by depth
+curl -fsS "{{BASE_URL}}/api/projectGraph/risk?cwd=$PWD&qname=<QNAME>&depth=2&topK=20"
+
+# affected: file-level reverse-import closure → test files transitively affected
+# Sister to /risk: risk is symbol-centric + precision-oriented (for analysis),
+# affected is file-centric + recall-oriented (for CI / selective-test pipelines).
+# Use POST when files list is large; use format=plain for newline-separated paths.
+curl -fsS "{{BASE_URL}}/api/projectGraph/affected?cwd=$PWD&files=<a.ts,b.ts>&depth=10"
+
+## Advanced endpoint contract
+- \`score\` / \`risk.score\` are for ranking only; absolute values have no meaning
+- \`signals\` / \`relations\` / \`tags\` explain WHY each result is relevant — feel free to cite them to the user
+- \`degraded: true\` means results are still usable but lower precision; \`degradedReason\` gives the cause (\`analytics-warming\` = backing index warming up; \`coedit-unavailable\` = git history signal unavailable, fall back to manually picking tests)
+- **risk / related responses already include a \`coedit\` field** (target file's coedit history) — DO NOT issue a separate /coedit request for the same file
+- If related returns \`ambiguousIn\`, the same qname exists in multiple files — retry with \`&filePath=<rel>\`
+- These three endpoints also return coordinates only; fetch source with Read`,labelZh:"探索问题：",labelEn:"Exploration: "}};function e(a,b="en",c){var f,g;let h,i=a.trimStart(),j=i.match(/^\/([a-zA-Z]+)(?:\s+|$)/);if(!j)return a;let k=j[1],l=b.startsWith("zh")?"zh":"en",m=d[k],n=m?.[l];if(!n)return a;let o=function(a){if(a){let b=new URL(a.url),c=a.headers.get("x-forwarded-proto"),d=a.headers.get("x-forwarded-host");return c||d?`${c??b.protocol.replace(":","")}://${d??b.host}`:b.origin}let b=process.env.COCKPIT_PORT||process.env.PORT||"3457";return`http://localhost:${b}`}(c),p=n.replaceAll("{{BASE_URL}}",o),q=i.slice(j[0].length).trimStart(),r=(f=m,(h="zh"===(g=l)?f.labelZh:f.labelEn)||("zh"===g?"问题：":"Question: "));return q?`${p}
 
 ${r}${q}`:p}}};