@zleap-ai/sag-cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zleap-ai/sag-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Command-line client and diagnostics for SAG knowledge bases",
   "type": "module",
   "bin": {
@@ -9,7 +9,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "README.en.md",
+    "LICENSE",
+    "skill"
   ],
   "scripts": {
     "build": "tsup",

package/skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: sag-knowledge
+description: "通过 sag CLI 检索 SAG 知识库。当用户需要在 SAG 知识库中查找、阅读、引用或核实内容时使用。重要约束：(1)必须先 sag source list 确认范围 (2)引用必须标注 [n] 编号 (3)禁止对整个文件一次性 read，必须分页 (4)无结果时如实告知，禁止编造 (5)文档非 ready 状态不可检索，需提示用户等待处理完成。"
+metadata:
+  sag:
+    emoji: "📚"
+---
+
+# SAG Knowledge Base
+
+通过 `sag` CLI 探索和检索 SAG 知识库。
+
+## 调用方式
+
+```bash
+sag <command> [options]
+```
+
+详细参数与返回格式见 [references/cli-reference.md](references/cli-reference.md)。
+
+## 探索漏斗
+
+每次知识检索按漏斗从宽到窄推进：
+
+```
+sag source list → sag document list → sag outline → sag search/sag grep → sag get-chunk/sag read
+```
+
+能用 `sag search` 回答就不进 `sag get-chunk`。用户追问出处时才展示原文。
+
+## 工具选择决策
+
+| 场景                 | 命令                       | 说明                                  |
+| -------------------- | -------------------------- | ------------------------------------- |
+| 进入任何任务的第一步 | `sag source list`          | 确认范围，即使只有一个信源也要调用    |
+| 概念性问题           | `sag search "<query>"`     | 返回 `[n]` 编号证据块，回答时标注引用 |
+| 精确字符串           | `sag grep "<pattern>"`     | 大小写不敏感，编号/函数名/配置项      |
+| 文档结构             | `sag outline <doc-id>`     | 标题大纲 + chunk_id                   |
+| 读完整文档           | `sag read <doc-id>`        | 分页读取，每次 ≤ 120 行               |
+| 追问出处             | `sag get-chunk <chunk-id>` | 展示对应分块完整原文                  |
+| 人物/组织/概念       | `sag get-entity "<name>"`  | 精确匹配 → 子串匹配                   |
+| 文档状态             | `sag document list/status` | 仅 `ready` 状态可检索                 |
+| 诊断                 | `sag doctor`               | 检查 SAG 实例健康状态                 |
+
+## 禁止项
+
+- **禁止跳过 `sag source list` 直接搜索**——先确认范围
+- **禁止一次 `sag read` 整个文件**——始终分页
+- **禁止编造知识内容**——search/grep 空态时如实告知
+- **禁止向用户暴露技术细节**——不展示 chunk_id、source_id 等技术字段
+- **禁止对非 ready 状态的文档调用 search**——告知用户等待处理完成
+
+## References
+
+| 文件                                                               | 何时看                                      |
+| ------------------------------------------------------------------ | ------------------------------------------- |
+| [references/cli-reference.md](references/cli-reference.md)         | 需要准确的命令参数、返回格式、空态文案      |
+| [references/search-strategies.md](references/search-strategies.md) | 设计复杂多步检索流程、search vs grep 决策树 |
+| [references/citation-rules.md](references/citation-rules.md)       | 引用 `[n]` 编号规范、原文溯源流程、追问处理 |

package/skill/references/citation-rules.md

@@ -0,0 +1,85 @@
+# 引用规范
+
+## 为什么需要引用
+
+SAG 是原文溯源型知识库——每条检索结果都能追溯到原始文档的具体分块。引用规范保证：
+
+- 用户能验证答案的准确性
+- 追问时能快速定位原文
+- Agent 回答有据可查，避免幻觉
+
+---
+
+## 引用标注格式
+
+使用 `sag search` 返回的 `[n]` 编号标注每条外部知识来源。
+
+```
+sag search 返回:
+[1] 授权流程概述（chunk_id=chunk_042）
+授权分为三步：……
+
+[2] 权限模型（chunk_id=chunk_078）
+系统采用 RBAC 模型……
+
+Agent 回答:
+授权分为三步：用户发起、主管审批、系统记录 [1]。
+权限控制基于 RBAC 模型，支持角色、用户组、资源三级粒度 [2]。
+```
+
+### 标注位置
+
+- 标注紧跟被引用的句子或段落末尾。
+- 一句话引用多个来源时并排标注：`[1][3]`。
+- 不要把所有引用堆在段落末尾——逐句标注。
+
+### 标注粒度
+
+- 每条来自知识库的事实都要标注。
+- 常识性内容（如"RBAC 是 Role-Based Access Control 的缩写"这类通用知识）不需要标注。
+- 不确定是否需要标注时，倾向于标注。
+
+---
+
+## 原文溯源流程
+
+当用户追问出处时，按以下步骤展示原文：
+
+```
+用户: 这个授权流程是从哪来的？
+
+Agent:
+1. 确认引用编号 → 上一轮回答引用了 [1]
+2. sag get-chunk chunk_042 → 获取完整分块原文
+3. 展示原文并说明来源文档
+
+回复示例:
+这来自《产品手册》第 2 章「授权流程概述」：
+
+> 授权分为三步：用户发起请求，主管在线审批，
+> 系统自动记录并通知。请求需在 24 小时内完成审批，
+> 超时自动退回。
+```
+
+---
+
+## 追问处理模式
+
+| 追问类型                       | 处理方式                                     |
+| ------------------------------ | -------------------------------------------- |
+| "这个结论从哪来的"             | `sag get-chunk` 展示对应原文                 |
+| "原文怎么说的"                 | `sag get-chunk` 展示对应原文                 |
+| "有没有更详细的内容"           | `sag read` 相关章节（先 `sag outline` 定位） |
+| "还有其他相关的内容吗"         | 扩大 search top_k 或换表述再 search          |
+| "这个人在知识库里还有什么信息" | `sag get-entity` 查看实体上下文              |
+
+---
+
+## 常见错误
+
+| 错误                           | 正确做法                           |
+| ------------------------------ | ---------------------------------- |
+| 回答中不标注任何引用           | 每条知识库事实必须标注 `[n]`       |
+| 标注了 [n] 但 n 是编造的       | [n] 必须来自当次 search 的真实返回 |
+| 用户追问出处时复述而非展示原文 | 用 `sag get-chunk` 展示原文        |
+| 把常识当作知识库内容标注       | 只有来自 SAG 的知识需要标注        |

package/skill/references/cli-reference.md

@@ -0,0 +1,223 @@
+# CLI 命令参考
+
+所有命令返回结构化文本。空态统一返回中文占位文案，不抛异常。
+
+---
+
+## sag source list
+
+列出当前可访问的全部信源。
+
+```bash
+sag source list
+```
+
+**返回**:
+
+```
+可访问的知识来源：
+- 产品文档（source_id=src_prod_001）· 12 文档 · 340 分块
+- 技术博客（source_id=src_blog_002）· 5 文档 · 89 分块
+```
+
+**空态**: `（暂无可用信源）`
+
+---
+
+## sag document list
+
+列出指定信源下的文档列表。
+
+```bash
+sag document list --source <id>
+```
+
+**返回**:
+
+```
+- 产品手册.pdf · id=doc_001 · ready · 120 分块
+- 更新日志.md · id=doc_002 · processing · 0 分块
+```
+
+**空态**: `（暂无文档）`
+
+**文档状态**:
+
+| 状态       | 含义        | 可否检索      |
+| ---------- | ----------- | ------------- |
+| ready      | 处理完成    | ✅            |
+| processing | 解析/抽取中 | ❌ 告知等待   |
+| error      | 处理失败    | ❌ 需重新上传 |
+
+---
+
+## sag document status
+
+查看文档处理进度。
+
+```bash
+sag document status --source <id>           # 信源汇总
+sag document status --source <id> <doc-id>  # 单个文档
+```
+
+---
+
+## sag search
+
+语义检索。自然语言问题 → 带编号证据块。
+
+```bash
+sag search "<query>" --source <id> --top-k 10
+```
+
+**参数**:
+
+| 参数       | 说明                          |
+| ---------- | ----------------------------- |
+| --source   | 限定信源，可重复指定多个      |
+| --top-k    | 返回数量，默认 8，上限 50     |
+| --strategy | vector（快速）/ multi（精确） |
+
+**返回**:
+
+```
+[1] 授权流程概述（chunk_id=chunk_042）
+授权分为三步：用户发起请求，主管在线审批，系统自动记录并通知。
+
+[2] 权限模型设计（chunk_id=chunk_078）
+系统采用 RBAC 模型，支持角色、用户组、资源三级粒度。
+```
+
+**空态**: `（未找到匹配内容）`
+
+**使用规则**:
+
+- 回答时引用 `[n]` 编号标注每条事实
+- search 失败时告知用户检查模型配置
+- 同一轮对话复用已有结果，不要重复调用
+
+---
+
+## sag grep
+
+精确字符串匹配。大小写不敏感，`%` 和 `_` 已自动转义。
+
+```bash
+sag grep "<pattern>" --source <id> --limit 20
+```
+
+**参数**:
+
+| 参数     | 说明                       |
+| -------- | -------------------------- |
+| --source | 限定检索范围               |
+| --limit  | 返回数量，默认 20，上限 50 |
+
+**空态**: `（未找到匹配 "pattern" 的内容）`
+
+**使用规则**: 第一次无结果时可换同义词或缩短 pattern 再试一次。最多 2 次。
+
+---
+
+## sag outline
+
+返回文档的层级大纲（标题 + chunk_id），按阅读顺序排列。
+
+```bash
+sag outline <document-id>
+```
+
+**返回**:
+
+```
+1. 概述（chunk_id=chunk_001）
+  1.1 项目背景（chunk_id=chunk_002）
+  1.2 技术选型（chunk_id=chunk_003）
+2. 快速开始（chunk_id=chunk_004）
+```
+
+**空态/处理中**: `（文档处理中，暂无大纲）`
+
+---
+
+## sag get-chunk
+
+读取单个分块的完整原文。
+
+```bash
+sag get-chunk <chunk-id> --source <id>
+```
+
+**空态**: `（未找到该分块）`
+
+---
+
+## sag read
+
+按行分页读取原始文件。
+
+```bash
+sag read <document-id> --offset 1 --limit 120
+```
+
+**参数**:
+
+| 参数     | 说明                         |
+| -------- | ---------------------------- |
+| --offset | 起始行号，默认 1             |
+| --limit  | 每页行数，默认 120，上限 500 |
+
+**返回**:
+
+```
+第 1-120 行 / 共 560 行
+1 | # 产品手册
+...
+```
+
+**使用规则**: 禁止一次 read 整个文件——始终分页，每次 ≤ 120 行。
+
+---
+
+## sag get-entity
+
+查询实体的相关事件上下文。先精确名称匹配、再子串匹配。
+
+```bash
+sag get-entity "<name>" --source <id>
+```
+
+**返回**:
+
+```
+实体：张三 · 类型：人物
+相关事件：
+- 张三于 2024 年加入团队（chunk_id=chunk_031）
+```
+
+**空态**: `（未找到相关实体）` — 此时建议用 `sag search` 替代。
+
+---
+
+## sag doctor
+
+诊断 SAG 实例健康状态。检查项：API 可达性、数据库状态、LLM 配置。
+
+```bash
+sag doctor
+```
+
+---
+
+## 空态文案速查
+
+| 命令              | 空态/异常返回                     |
+| ----------------- | --------------------------------- |
+| sag source list   | `（暂无可用信源）`                |
+| sag document list | `（暂无文档）`                    |
+| sag outline       | `（文档处理中，暂无大纲）`        |
+| sag search        | `（未找到匹配内容）`              |
+| sag grep          | `（未找到匹配 "pattern" 的内容）` |
+| sag get-chunk     | `（未找到该分块）`                |
+| sag read          | `（文档不存在或无法读取）`        |
+| sag get-entity    | `（未找到相关实体）`              |

package/skill/references/search-strategies.md

@@ -0,0 +1,73 @@
+# 查询策略
+
+## 漏斗范式
+
+每次知识检索按漏斗从宽到窄推进：
+
+```
+sag source list → sag document list → sag outline → sag search / sag grep → sag get-chunk / sag read
+```
+
+| 步骤        | 命令                              | 产出                                |
+| ----------- | --------------------------------- | ----------------------------------- |
+| 1. 确认范围 | `sag source list`                 | 可用的 source_id 列表               |
+| 2. 锁定文档 | `sag document list --source <id>` | 候选 document_id（只看 ready 状态） |
+| 3. 定位章节 | `sag outline <document-id>`       | 目标章节的 chunk_id                 |
+| 4. 召回证据 | `sag search` 或 `sag grep`        | 带编号的证据片段                    |
+| 5. 溯源原文 | `sag get-chunk` 或 `sag read`     | 完整原文                            |
+
+**原则**: 能用第 4 步回答就用第 4 步，用户追问出处时才进第 5 步。
+
+---
+
+## search vs grep 决策树
+
+```
+用户查询是自然语言问句？
+├── 是 → sag search
+│   例："授权流程是怎样的""资料里有没有提到微服务"
+│
+└── 否 → 是精确字符串？
+    ├── 是 → sag grep
+    │   例：编号 INV-2024-0037、函数名 handleAuth、配置项 SAG_MAX_CHUNK
+    │
+    └── 不确定 → sag search（语义覆盖面更广）
+```
+
+**sag search 擅长**: 概念、问句、模糊表述、跨段落相关的内容。
+**sag grep 擅长**: 确定字符串、编号、代码片段、专有名词的精确出现位置。
+
+### 组合使用
+
+1. 先用 `sag search` 找到相关主题范围
+2. 再用 `sag grep` 精确定位关键术语
+
+例：用户问"INV-2024 这批货的审批流程" → 先 `sag search "审批流程"` 理解全貌 → 再 `sag grep "INV-2024"` 确认该批次记录。
+
+---
+
+## 多步检索示例
+
+### 场景 1：用户问"这份资料讲了什么？"
+
+```
+1. sag source list                                  → 确认范围，取得 source_id
+2. sag document list --source <id>                  → 找到目标文档，确认 status = ready
+3. sag outline <doc-id>                             → 获取全书大纲
+4. sag get-chunk chunk_001                          → 读概述章节
+```
+
+### 场景 2：用户问"授权流程是怎样的？"
+
+```
+1. sag search "授权流程" --source <id> → [1] 授权流程概述 [2] 权限管理 ……
+2. 用返回内容回答，标注引用
+3. （用户追问原文）→ sag get-chunk chunk_042
+```
+
+### 场景 3：用户问"INV-2024-0037 这个编号在哪里出现过？"
+
+```
+1. sag grep "INV-2024-0037" → 精确匹配所有出现位置
+2. 如有必要 → sag get-chunk <chunk-id> 读其中某个位置的完整上下文
+```