@zleap-ai/sag-cli 0.2.1 → 0.3.0

package/README.en.md

@@ -99,6 +99,20 @@ sag search "how to wire MCP" --source <source-id> --top-k 5
 
 A profile stores only `scheme://host[:port]`. The `/api/v1` prefix is added by the CLI — do not put it in the URL yourself.
 
+## Use with the Skill
+
+The Skill files (`skill/`) ship alongside this CLI. Copy them into your Agent's skills directory:
+
+```bash
+# Claude Code
+SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
+cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
+
+# Codex
+SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
+cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
+```
+
 ## Command reference
 
 ```text
@@ -184,10 +198,17 @@ Tokens never appear in JSON, logs, or error output. Full error and exit codes li
 
 ## Further reading
 
+### Using the CLI
+
+- [CHANGELOG.md](CHANGELOG.md) — release notes
 - Architecture and exit codes: [English](docs/architecture.md) / [简体中文](docs/architecture.zh-CN.md)
+- [SKILL.md](SKILL.md) — teaches an Agent how to explore SAG efficiently
+
+### Developing and contributing
+
 - Local development and debugging: [English](docs/development.md) / [简体中文](docs/development.zh-CN.md)
 - Compatibility matrix: [English](docs/compatibility.md) / [简体中文](docs/compatibility.zh-CN.md)
 - OAuth and MCP authorization: [English](docs/oauth.md) / [简体中文](docs/oauth.zh-CN.md)
 - Release process: [English](docs/release.md) / [简体中文](docs/release.zh-CN.md)
-- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
-- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)

package/README.md

@@ -99,6 +99,20 @@ sag search "MCP 如何接入" --source <source-id> --top-k 5
 
 Profile URL 只保存 `scheme://host[:port]`。API 前缀 `/api/v1` 由 CLI 自动补齐，不要自己写。
 
+## 搭配 Skill 使用
+
+Skill 文件（`skill/`）随本 CLI 一起发布。安装 CLI 后复制到 Agent 的 skills 目录：
+
+```bash
+# Claude Code
+SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
+cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
+
+# Codex
+SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
+cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
+```
+
 ## 命令一览
 
 ```text
@@ -184,10 +198,17 @@ Token 不会出现在 JSON、日志或错误输出里。完整错误码与退出
 
 ## 深入阅读
 
+### 使用指南
+
+- [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
 - 架构与退出码：[中文](docs/architecture.zh-CN.md) / [English](docs/architecture.md)
+- [SKILL.md](SKILL.md) — 教 Agent 怎么高效探索 SAG 知识库
+
+### 开发与贡献
+
 - 本地开发与调试：[中文](docs/development.zh-CN.md) / [English](docs/development.md)
 - 兼容性矩阵：[中文](docs/compatibility.zh-CN.md) / [English](docs/compatibility.md)
 - OAuth 与 MCP 授权：[中文](docs/oauth.zh-CN.md) / [English](docs/oauth.md)
 - 发布流程：[中文](docs/release.zh-CN.md) / [English](docs/release.md)
-- 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
-- 变更记录：[CHANGELOG.md](CHANGELOG.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)

package/dist/cli.js

@@ -6,7 +6,7 @@ import { confirm, password, select } from "@inquirer/prompts";
 // package.json
 var package_default = {
   name: "@zleap-ai/sag-cli",
-  version: "0.2.1",
+  version: "0.3.0",
   description: "Command-line client and diagnostics for SAG knowledge bases",
   type: "module",
   bin: {
@@ -16,7 +16,8 @@ var package_default = {
     "dist",
     "README.md",
     "README.en.md",
-    "LICENSE"
+    "LICENSE",
+    "skill"
   ],
   scripts: {
     build: "tsup",
@@ -1354,6 +1355,43 @@ var mcpDescriptorSchema = z6.object({
     headers: z6.record(z6.string(), z6.string())
   }).passthrough()
 }).passthrough();
+var outlineItemSchema = z6.object({
+  rank: z6.number().int(),
+  heading: z6.string(),
+  chunk_id: z6.string()
+}).passthrough();
+var outlineSchema = z6.object({
+  document_id: z6.string(),
+  filename: z6.string(),
+  outline: z6.array(outlineItemSchema)
+}).passthrough();
+var grepMatchSchema = z6.object({
+  chunk_id: z6.string(),
+  heading: z6.string(),
+  snippet: z6.string()
+}).passthrough();
+var grepResponseSchema = z6.object({
+  pattern: z6.string(),
+  matches: z6.array(grepMatchSchema),
+  count: z6.number().int().nonnegative()
+}).passthrough();
+var readResponseSchema = z6.object({
+  document_id: z6.string(),
+  filename: z6.string(),
+  total_lines: z6.number().int().nonnegative(),
+  offset: z6.number().int().positive(),
+  limit: z6.number().int().positive(),
+  lines: z6.array(z6.string())
+}).passthrough();
+var entityContextSchema = z6.object({
+  entity_id: z6.string(),
+  name: z6.string(),
+  type: z6.string(),
+  description: z6.string(),
+  context: z6.string(),
+  source_id: z6.string(),
+  source_name: z6.string()
+}).passthrough();
 
 // src/api/client.ts
 var SagClient = class {
@@ -1415,6 +1453,42 @@ var SagClient = class {
       body: input
     });
   }
+  outline(sourceId, documentId) {
+    const params = new URLSearchParams({ document_id: documentId });
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/outline?${params}`,
+      outlineSchema
+    );
+  }
+  grep(sourceId, pattern, limit) {
+    const params = new URLSearchParams({ pattern });
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/grep?${params}`,
+      grepResponseSchema
+    );
+  }
+  readDocument(sourceId, documentId, offset, limit) {
+    const params = new URLSearchParams();
+    if (offset !== void 0) {
+      params.set("offset", String(offset));
+    }
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/documents/${encodeURIComponent(documentId)}/read?${params}`,
+      readResponseSchema
+    );
+  }
+  getEntityContext(sourceId, name) {
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/entities/${encodeURIComponent(name)}/context`,
+      entityContextSchema
+    );
+  }
   async #request(path5, schema, options = {}) {
     const authenticated = options.authenticated ?? true;
     if (authenticated && !this.#token) {
@@ -2133,6 +2207,44 @@ async function documentStatus(client, sourceId, documentId) {
   };
 }
 
+// src/commands/knowledge.ts
+function requiredIdentifier2(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new CliError("INVALID_ARGUMENT", `${label} is required`, {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return normalized;
+}
+async function outline(client, sourceId, documentId) {
+  return client.outline(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(documentId, "Document ID")
+  );
+}
+async function grep(client, sourceId, pattern, limit) {
+  return client.grep(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(pattern, "Pattern"),
+    limit
+  );
+}
+async function read(client, sourceId, documentId, offset, limit) {
+  return client.readDocument(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(documentId, "Document ID"),
+    offset,
+    limit
+  );
+}
+async function getEntityContext(client, sourceId, name) {
+  return client.getEntityContext(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(name, "Entity name")
+  );
+}
+
 // src/commands/mcp.ts
 async function testLocalMcp(runtime2, input) {
   const container = await discoverSagContainer({
@@ -2681,6 +2793,45 @@ function renderLocalMcp(value) {
   ].join("\n")}
 `;
 }
+function renderOutline(value) {
+  const filename = typeof value.filename === "string" ? value.filename : "Unknown";
+  const items = Array.isArray(value.outline) ? value.outline.filter(isRecord) : [];
+  const lines = items.map(
+    (item) => `${String(item.rank ?? 0).padStart(3)}. ${item.heading || "(untitled)"}  (chunk_id=${item.chunk_id})`
+  );
+  return `${filename}
+${lines.join("\n")}
+`;
+}
+function renderGrep(value) {
+  const matches = Array.isArray(value.matches) ? value.matches.filter(isRecord) : [];
+  const lines = matches.map(
+    (match, index) => `[${index + 1}] ${match.heading || "Match"}
+${match.snippet}`
+  );
+  return lines.length ? `${lines.join("\n\n")}
+` : "No matches.\n";
+}
+function renderRead(value) {
+  const filename = typeof value.filename === "string" ? value.filename : "Unknown";
+  const total = typeof value.total_lines === "number" ? value.total_lines : 0;
+  const offset = typeof value.offset === "number" ? value.offset : 1;
+  const lines = Array.isArray(value.lines) ? value.lines.map(String) : [];
+  const header = `${filename} \xB7 lines ${offset}-${offset + lines.length - 1} / ${total}`;
+  return `${header}
+${lines.join("")}`;
+}
+function renderEntityContext(value) {
+  const name = typeof value.name === "string" ? value.name : "Unknown";
+  const type = typeof value.type === "string" ? value.type : "";
+  const source = typeof value.source_name === "string" ? value.source_name : "";
+  const context = typeof value.context === "string" ? value.context : "";
+  return `Entity: ${name}${type ? ` (${type})` : ""}
+Source: ${source}
+
+${context}
+`;
+}
 function renderHuman(value, quiet = false) {
   if (quiet) {
     if (Array.isArray(value)) {
@@ -2703,6 +2854,18 @@ function renderHuman(value, quiet = false) {
   if (isRecord(value) && Array.isArray(value.sections) && "query" in value) {
     return renderSearch(value);
   }
+  if (isRecord(value) && Array.isArray(value.outline) && "filename" in value) {
+    return renderOutline(value);
+  }
+  if (isRecord(value) && Array.isArray(value.matches) && "pattern" in value) {
+    return renderGrep(value);
+  }
+  if (isRecord(value) && Array.isArray(value.lines) && "total_lines" in value) {
+    return renderRead(value);
+  }
+  if (isRecord(value) && "entity_id" in value && "context" in value) {
+    return renderEntityContext(value);
+  }
   if (isRecord(value) && value.provider === "docker-stdio" && "protocolVersion" in value && "container" in value) {
     return renderLocalMcp(value);
   }
@@ -2946,6 +3109,46 @@ function addKnowledgeCommands(program, dependencies2) {
       );
     }
   );
+  program.command("outline").argument("<document-id>").requiredOption("--source <source-id>").action(async (documentId, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await outline(context.client, options.source, documentId)
+    );
+  });
+  program.command("grep").argument("<pattern>").requiredOption("--source <source-id>").option("--limit <number>", "Maximum result count", parseInteger).action(async (pattern, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await grep(context.client, options.source, pattern, options.limit)
+    );
+  });
+  program.command("read").argument("<document-id>").requiredOption("--source <source-id>").option("--offset <number>", "Starting line (1-based)", parseInteger).option("--limit <number>", "Lines to read", parseInteger).action(
+    async (documentId, options) => {
+      const context = await runtime(program, dependencies2);
+      emit(
+        program,
+        dependencies2,
+        await read(
+          context.client,
+          options.source,
+          documentId,
+          options.offset,
+          options.limit
+        )
+      );
+    }
+  );
+  program.command("get-entity").argument("<name>").requiredOption("--source <source-id>").action(async (name, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await getEntityContext(context.client, options.source, name)
+    );
+  });
 }
 function addLocalMcpCommands(program, dependencies2) {
   const mcp = program.command("mcp").description("Verify local SAG MCP");