@zleap-ai/sag-cli 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.en.md +28 -7
  2. package/README.md +28 -8
  3. package/dist/cli.js +436 -192
  4. package/dist/cli.js.map +1 -1
  5. package/package.json +3 -2
  6. package/skill/SKILL.md +69 -0
  7. package/skill/references/citation-rules.md +85 -0
  8. package/skill/references/cli-reference.md +223 -0
  9. package/skill/references/search-strategies.md +73 -0
package/README.en.md CHANGED
@@ -21,12 +21,12 @@ For release notes see [CHANGELOG.md](CHANGELOG.md).
21
21
  | Task | Requirement |
22
22
  | ------------------------------------ | ------------------------------------------------------------------------- |
23
23
  | Install and run the CLI | Node.js **≥ 20.19** |
24
- | Sign in and search via the HTTP API | A reachable SAG origin (e.g. `http://localhost:8000`) plus a SAG JWT |
24
+ | Sign in and search via the HTTP API | A reachable SAG origin (e.g. `http://localhost:8000`) |
25
25
  | Use the local Docker token-less path | Docker CLI, with a SAG API container running `sag_api.mcp.server` locally |
26
26
  | Wire into Codex | Codex CLI (≥ 0.145) installed |
27
27
  | Wire into Claude Code | Claude Code (≥ 2.1) installed |
28
28
 
29
- **Where to get the JWT**: sign in to SAG Web → **Settings → Integrations** and copy the JWT. The CLI hides the input and prefers the OS credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service). When that is unavailable the token stays only in the current process; use the `SAG_TOKEN` environment variable in automation.
29
+ **HTTP API sign-in**: the CLI calls SAG's existing name-login API and stores the returned JWT in the OS credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service). No SAG Web page or copied Token is required; automation can still use the `SAG_TOKEN` environment variable.
30
30
 
31
31
  ## Install
32
32
 
@@ -75,7 +75,7 @@ Undo an integration:
75
75
  sag agent disconnect codex
76
76
  ```
77
77
 
78
- ### Path B: HTTP API + JWT (across machines, or no Docker)
78
+ ### Path B: HTTP API direct sign-in (across machines, or no Docker)
79
79
 
80
80
  Authenticate and search against SAG's HTTP API directly.
81
81
 
@@ -84,8 +84,8 @@ Authenticate and search against SAG's HTTP API directly.
84
84
  sag profile add local http://localhost:8000
85
85
  sag profile use local
86
86
 
87
- # 2. Sign in (prompts for the JWT)
88
- sag auth login
87
+ # 2. Sign in (no browser or copied Token)
88
+ sag auth login --name "Your name"
89
89
  sag auth status
90
90
 
91
91
  # 3. Health check and browse
@@ -99,6 +99,20 @@ sag search "how to wire MCP" --source <source-id> --top-k 5
99
99
 
100
100
  A profile stores only `scheme://host[:port]`. The `/api/v1` prefix is added by the CLI — do not put it in the URL yourself.
101
101
 
102
+ ## Use with the Skill
103
+
104
+ The Skill files (`skill/`) ship alongside this CLI. Copy them into your Agent's skills directory:
105
+
106
+ ```bash
107
+ # Claude Code
108
+ SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
109
+ cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
110
+
111
+ # Codex
112
+ SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
113
+ cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
114
+ ```
115
+
102
116
  ## Command reference
103
117
 
104
118
  ```text
@@ -184,10 +198,17 @@ Tokens never appear in JSON, logs, or error output. Full error and exit codes li
184
198
 
185
199
  ## Further reading
186
200
 
201
+ ### Using the CLI
202
+
203
+ - [CHANGELOG.md](CHANGELOG.md) — release notes
187
204
  - Architecture and exit codes: [English](docs/architecture.md) / [简体中文](docs/architecture.zh-CN.md)
205
+ - [SKILL.md](SKILL.md) — teaches an Agent how to explore SAG efficiently
206
+
207
+ ### Developing and contributing
208
+
188
209
  - Local development and debugging: [English](docs/development.md) / [简体中文](docs/development.zh-CN.md)
189
210
  - Compatibility matrix: [English](docs/compatibility.md) / [简体中文](docs/compatibility.zh-CN.md)
190
211
  - OAuth and MCP authorization: [English](docs/oauth.md) / [简体中文](docs/oauth.zh-CN.md)
191
212
  - Release process: [English](docs/release.md) / [简体中文](docs/release.zh-CN.md)
192
- - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
193
- - Changelog: [CHANGELOG.md](CHANGELOG.md)
213
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
214
+ - [SECURITY.md](SECURITY.md)
package/README.md CHANGED
@@ -21,12 +21,12 @@
21
21
  | 你想做的事 | 需要准备 |
22
22
  | --------------------------- | ----------------------------------------------------------- |
23
23
  | 安装并运行 CLI | Node.js **≥ 20.19** |
24
- | 用 HTTP API 登录、搜索 | 一个可访问的 SAG Origin（如 `http://localhost:8000`）+ JWT |
24
+ | 用 HTTP API 登录、搜索 | 一个可访问的 SAG Origin（如 `http://localhost:8000`） |
25
25
  | 用本机 Docker 免 Token 路径 | Docker CLI，且本机运行着含 `sag_api.mcp.server` 的 SAG 容器 |
26
26
  | 接入 Codex | 已安装 Codex CLI（≥ 0.145） |
27
27
  | 接入 Claude Code | 已安装 Claude Code（≥ 2.1） |
28
28
 
29
- **JWT 从哪拿**：登录 SAG Web → **Settings → Integrations**，复制其中的 JWT。CLI 会隐藏输入并优先保存到系统凭据存储（macOS Keychain、Windows Credential Manager、Linux Secret Service）；不可用时只保留在当前进程，自动化环境请改用 `SAG_TOKEN` 环境变量。
29
+ **HTTP API 登录方式**：CLI 直接调用 SAG 现有的名称登录接口，并把返回的 JWT 保存到系统凭据存储（macOS Keychain、Windows Credential Manager、Linux Secret Service）。不需要打开 SAG Web 或复制 Token；自动化场景仍可使用 `SAG_TOKEN` 环境变量。
30
30
 
31
31
  ## 安装
32
32
 
@@ -75,7 +75,7 @@ sag agent connect codex --dry-run
75
75
  sag agent disconnect codex
76
76
  ```
77
77
 
78
- ### 路径 B：HTTP API + JWT（跨机器、或本机没有 Docker）
78
+ ### 路径 B：HTTP API 直连（跨机器、或本机没有 Docker）
79
79
 
80
80
  用 SAG 的 HTTP API 做认证、查询、检索。
81
81
 
@@ -84,8 +84,8 @@ sag agent disconnect codex
84
84
  sag profile add local http://localhost:8000
85
85
  sag profile use local
86
86
 
87
- # 2. 登录（会提示输入 JWT）
88
- sag auth login
87
+ # 2. 登录（不打开浏览器、不复制 Token）
88
+ sag auth login --name "你的名字"
89
89
  sag auth status
90
90
 
91
91
  # 3. 体检 + 看信源
@@ -99,6 +99,20 @@ sag search "MCP 如何接入" --source <source-id> --top-k 5
99
99
 
100
100
  Profile URL 只保存 `scheme://host[:port]`。API 前缀 `/api/v1` 由 CLI 自动补齐，不要自己写。
101
101
 
102
+ ## 搭配 Skill 使用
103
+
104
+ Skill 文件（`skill/`）随本 CLI 一起发布。安装 CLI 后复制到 Agent 的 skills 目录：
105
+
106
+ ```bash
107
+ # Claude Code
108
+ SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
109
+ cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
110
+
111
+ # Codex
112
+ SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
113
+ cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
114
+ ```
115
+
102
116
  ## 命令一览
103
117
 
104
118
  ```text
@@ -184,10 +198,16 @@ Token 不会出现在 JSON、日志或错误输出里。完整错误码与退出
184
198
 
185
199
  ## 深入阅读
186
200
 
201
+ ### 使用指南
202
+
203
+ - [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
187
204
  - 架构与退出码：[中文](docs/architecture.zh-CN.md) / [English](docs/architecture.md)
205
+ - [SKILL.md](SKILL.md) — 教 Agent 怎么高效探索 SAG 知识库
206
+
207
+ ### 开发与贡献
208
+
188
209
  - 本地开发与调试：[中文](docs/development.zh-CN.md) / [English](docs/development.md)
189
210
  - 兼容性矩阵：[中文](docs/compatibility.zh-CN.md) / [English](docs/compatibility.md)
190
- - OAuth 与 MCP 授权：[中文](docs/oauth.zh-CN.md) / [English](docs/oauth.md)
191
211
  - 发布流程：[中文](docs/release.zh-CN.md) / [English](docs/release.md)
192
- - 贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)
193
- - 变更记录：[CHANGELOG.md](CHANGELOG.md)
212
+ - [CONTRIBUTING.md](CONTRIBUTING.md)
213
+ - [SECURITY.md](SECURITY.md)