sp-rag 0.6.5 → 0.6.7

package/README.md

@@ -17,7 +17,7 @@ CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 ## Trạng thái package
 
 - package npm public: `sp-rag`
-- version đang publish: `0.6.5`
+- version đang publish: `0.6.7`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -71,6 +71,7 @@ Ghi chú:
 - với `cursor` và `vscode` ở `scope project`, nếu Sếpp đang đứng sẵn trong repo thì có thể bỏ `--cwd`
 - CLI sẽ tự dùng thư mục hiện tại cho cả MCP lẫn skill
 - rule/agent mới đã được tăng độ ưu tiên MCP-first, giảm khả năng model nhảy thẳng sang grep/read file local
+- skill mới cũng dặn model tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`; không bê nguyên `answer_brief`
 
 Ví dụ:
 
@@ -159,7 +160,7 @@ npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN
 - `antigravity` -> `SKILL.md`
 - `opencode` -> `SKILL.md`
 - `cursor` -> `.cursor/rules/sp-rag.mdc`
-- `vscode` -> `.github/agents/sp-rag.agent.md` hoặc `~/.copilot/agents/sp-rag.agent.md`
+- `vscode` -> `.github/agents/sp-rag.agent.md` + `.github/copilot-instructions.md` hoặc `~/.copilot/agents/sp-rag.agent.md` + `~/.copilot/instructions/sp-rag.instructions.md`
 
 Ghi chú:
 
@@ -189,8 +190,8 @@ Ghi chú:
 - `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md`
 - `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md`
 - `cursor` project: `.cursor/rules/sp-rag.mdc`
-- `vscode` project: `.github/agents/sp-rag.agent.md`
-- `vscode` global: `~/.copilot/agents/sp-rag.agent.md`
+- `vscode` project: `.github/agents/sp-rag.agent.md` và `.github/copilot-instructions.md`
+- `vscode` global: `~/.copilot/agents/sp-rag.agent.md` và `~/.copilot/instructions/sp-rag.instructions.md`
 
 ## Luồng khuyên dùng cho dev mới
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { runEvaluationSuite } from './lib/eval.js';
 import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, resolveMcpConfigPath, } from './lib/mcp-config.js';
 import { fetchJson, fetchText, runDoctor } from './lib/http.js';
 import { installSkill, resolveSkillInstallTarget, } from './lib/skill.js';
-const cliVersion = '0.6.5';
+const cliVersion = '0.6.7';
 function parseArgv(argv) {
     const positionals = [];
     const options = {};
@@ -368,6 +368,9 @@ async function runSkillInstall(parsed, defaults, explicitClient) {
         docsUrl: optionString(parsed, 'docs-url') ?? defaults.docsUrl,
     });
     process.stdout.write(`Đã cài skill cho ${result.client} tại ${result.path}\n`);
+    for (const extraPath of result.paths.slice(1)) {
+        process.stdout.write(`Đã cài thêm hướng dẫn cho ${result.client} tại ${extraPath}\n`);
+    }
 }
 async function saveResolvedConfig(defaults) {
     return saveCliConfig(buildCliConfig(defaults), defaults.homeDir);

package/dist/lib/skill.js

@@ -85,11 +85,13 @@ Docs URL: \`${context.docsUrl}\`
 3. Use \`get_rendered_docs\` for public, function, or dev docs that were already rendered from the latest graph.
 4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` when you need to verify commit freshness, investigate failures, or inspect operational history.
 5. Only call \`trigger_code_graph_sync\` when the user explicitly asks to refresh the graph or when a stale graph is the confirmed blocker.
+6. After \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`. Treat \`answer_brief\` as a hint only.
 
 ## Guardrails
 
 - You must call SP-RAG MCP tools first for codebase or domain questions before using local workspace search, grep, or file reads.
 - Prefer MCP-grounded answers before relying on memory.
+- Treat \`answer_brief\` as a hint only. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
 - If the evidence may be stale, say so clearly and mention that the graph or docs may need a refresh.
 - Do not trigger sync or import actions unless the user asked for it or the workflow truly requires it.
 - When rendered docs already answer the question, cite or summarize those docs instead of rewriting everything from scratch.
@@ -108,6 +110,7 @@ alwaysApply: true
 - You must call the \`${context.serverAlias}\` MCP server first before using local workspace search, grep, or file reads for codebase and domain questions.
 - Use rendered docs from \`${context.docsUrl}\` when documentation already answers the question.
 - For architecture, domain, entities, relations, and business workflow questions, query MCP first and only then synthesize the answer.
+- Treat \`answer_brief\` only as a hint. Build the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
 - For freshness or operational questions, check sync status, recent runs, and metrics before assuming the graph is current.
 - Only trigger codegraph sync when the user explicitly asks for it or stale evidence is the confirmed blocker.
 - If the evidence may be stale, say so clearly.
@@ -134,10 +137,12 @@ You must call an SP-RAG MCP tool before using local workspace search, grep, or f
 3. Use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
 4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` for freshness, incident review, or operational debugging.
 5. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
+6. After \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`. Treat \`answer_brief\` as a hint.
 
 ## Guardrails
 
 - Prefer MCP-grounded evidence before answering from memory.
+- Treat \`answer_brief\` as a hint. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
 - Do not use local workspace search, grep, or file reads until SP-RAG MCP has been tried first for the current question.
 - When evidence may be stale, say so clearly and mention that a refresh might be needed.
 - Do not trigger sync or import actions unless the workflow truly requires it.
@@ -145,6 +150,19 @@ You must call an SP-RAG MCP tool before using local workspace search, grep, or f
 - Only fall back to local workspace search or file reads after MCP is unavailable or clearly lacks the needed evidence, and say that you are falling back.
 `;
 }
+function renderVsCodeAlwaysOnInstructions(context) {
+    return `# SP-RAG workspace instructions
+
+- Always use the \`${context.serverAlias}\` MCP server first for codebase, domain, architecture, workflow, and operational questions before local workspace search, grep, or file reads.
+- Start with \`healthz\` only when connectivity is uncertain or the session is new.
+- Use \`query_context\` first for feature, entity, relation, and business-flow questions.
+- When \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
+- Treat \`answer_brief\` as a hint only, not the final answer.
+- Use \`get_rendered_docs\` when rendered docs can answer the question faster than raw code inspection.
+- Only trigger codegraph sync when the user explicitly asks for it or stale graph evidence is the confirmed blocker.
+- If MCP is unavailable or clearly lacks evidence, say so explicitly before falling back to local workspace search or file reads.
+`;
+}
 function renderSkillArtifact(context) {
     switch (context.client) {
         case 'cursor':
@@ -164,24 +182,45 @@ function renderSkillArtifact(context) {
             };
     }
 }
+function createSkillContext(options = {}, client) {
+    return {
+        client: client ?? options.client ?? 'codex',
+        serverAlias: options.serverAlias?.trim() || 'sp-rag',
+        mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
+        docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
+    };
+}
+function resolveAdditionalSkillArtifacts(options, resolved, context) {
+    if (resolved.client !== 'vscode') {
+        return [];
+    }
+    const workspaceRoot = resolved.scope === 'project'
+        ? requireProjectCwd('vscode', options.cwd)
+        : undefined;
+    const instructionsPath = resolved.scope === 'project'
+        ? path.join(workspaceRoot, '.github', 'copilot-instructions.md')
+        : path.join(os.homedir(), '.copilot', 'instructions', 'sp-rag.instructions.md');
+    return [
+        {
+            path: instructionsPath,
+            content: renderVsCodeAlwaysOnInstructions(context),
+        },
+    ];
+}
 export function resolveSkillInstallTarget(options = {}) {
     const client = options.client ?? 'codex';
     const scope = normalizeScope(client, options.scope);
     const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
-    const artifact = renderSkillArtifact({
-        client,
-        serverAlias: options.serverAlias?.trim() || 'sp-rag',
-        mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
-        docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
-    });
+    const artifact = renderSkillArtifact(createSkillContext(options, client));
     return {
         client,
         scope,
         path: path.join(targetDir, artifact.fileName),
+        paths: [path.join(targetDir, artifact.fileName)],
     };
 }
 export function renderSkill(options) {
-    return renderSkillArtifact(options).content;
+    return renderSkillArtifact(createSkillContext(options, options.client)).content;
 }
 export function renderCodexSkill(options) {
     return renderSkill({
@@ -191,17 +230,20 @@ export function renderCodexSkill(options) {
 }
 export async function installSkill(options = {}) {
     const resolved = resolveSkillInstallTarget(options);
-    const artifact = renderSkillArtifact({
-        client: resolved.client,
-        serverAlias: options.serverAlias?.trim() || 'sp-rag',
-        mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
-        docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
-    });
+    const context = createSkillContext(options, resolved.client);
+    const artifact = renderSkillArtifact(context);
+    const additionalArtifacts = resolveAdditionalSkillArtifacts(options, resolved, context);
     await mkdir(path.dirname(resolved.path), { recursive: true });
     await writeFile(resolved.path, artifact.content, 'utf8');
+    for (const extra of additionalArtifacts) {
+        await mkdir(path.dirname(extra.path), { recursive: true });
+        await writeFile(extra.path, extra.content, 'utf8');
+    }
+    const paths = [resolved.path, ...additionalArtifacts.map((entry) => entry.path)];
     return {
         client: resolved.client,
         path: resolved.path,
+        paths,
     };
 }
 export async function installCodexSkill(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sp-rag",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG",
   "type": "module",
   "files": [