@zleap-ai/sag-cli 0.2.0 → 0.3.0

package/README.en.md

@@ -0,0 +1,214 @@
+# SAG CLI
+
+[简体中文](README.md) | English
+
+`@zleap-ai/sag-cli` is a command-line client and diagnostics tool for SAG knowledge bases. From your terminal it lets you:
+
+- Sign in to and validate a running SAG instance;
+- Inspect sources and document processing status, and search knowledge directly;
+- Verify the local Docker SAG knowledge-base MCP and wire it into Codex and Claude Code with a single command.
+
+For release notes see [CHANGELOG.md](CHANGELOG.md).
+
+## Is this tool for you
+
+- You already have a SAG instance (local Docker or remote HTTP) and want to query, diagnose, and expose it to coding agents from the terminal.
+- You are developing or operating SAG and need diagnostics such as `doctor` and `mcp test`.
+- You want to use SAG for retrieval inside Codex or Claude Code without hand-writing an MCP config.
+
+## Prerequisites
+
+| Task                                 | Requirement                                                               |
+| ------------------------------------ | ------------------------------------------------------------------------- |
+| Install and run the CLI              | Node.js **≥ 20.19**                                                       |
+| Sign in and search via the HTTP API  | A reachable SAG origin (e.g. `http://localhost:8000`) plus a SAG JWT      |
+| Use the local Docker token-less path | Docker CLI, with a SAG API container running `sag_api.mcp.server` locally |
+| Wire into Codex                      | Codex CLI (≥ 0.145) installed                                             |
+| Wire into Claude Code                | Claude Code (≥ 2.1) installed                                             |
+
+**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.
+
+## Install
+
+```bash
+npm install --global @zleap-ai/sag-cli
+sag --help
+sag version
+```
+
+## Quick start: pick the path that fits you
+
+The CLI offers two independent paths. Pick one based on your situation.
+
+### Path A: Local Docker, no token required (recommended for local dev)
+
+Requires a SAG API container running locally in Docker. The CLI discovers the container, talks to it over stdio MCP via `docker exec`, and never needs the JWT.
+
+```bash
+# 1. Verify the local Docker SAG MCP works
+sag mcp test
+
+# 2. Wire it into an agent (either or both)
+sag agent connect codex
+sag agent connect claude-code
+
+# 3. Check status any time
+sag agent status
+```
+
+Scope to a single source with `--source-id`:
+
+```bash
+sag mcp test --source-id <source-id>
+sag agent connect codex --source-id <source-id>
+```
+
+Preview the plan with `--dry-run` before writing anything:
+
+```bash
+sag agent connect codex --dry-run
+```
+
+Undo an integration:
+
+```bash
+sag agent disconnect codex
+```
+
+### Path B: HTTP API + JWT (across machines, or no Docker)
+
+Authenticate and search against SAG's HTTP API directly.
+
+```bash
+# 1. Register a SAG instance
+sag profile add local http://localhost:8000
+sag profile use local
+
+# 2. Sign in (prompts for the JWT)
+sag auth login
+sag auth status
+
+# 3. Health check and browse
+sag doctor
+sag source list
+sag document status --source <source-id>
+
+# 4. Search
+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
+sag version
+sag auth login | status | logout
+sag profile add | list | use | show | remove
+sag doctor
+sag source list | get | status
+sag document list | get | status
+sag search <query>
+sag mcp test
+sag agent list
+sag agent connect <codex | claude-code>
+sag agent status [codex | claude-code]
+sag agent disconnect <codex | claude-code>
+```
+
+Common examples:
+
+```bash
+sag profile list --json
+sag source get <source-id>
+sag document list --source <source-id>
+sag search "how to wire MCP" --source <source-id> --strategy multi
+sag mcp test --container sag-api-1 --timeout 15000
+sag agent connect claude-code --name sag-knowledge-local
+```
+
+## Global options
+
+```text
+--profile <name>   Select a profile
+--url <origin>     Override the SAG origin for one command
+--json             Emit stable JSON (schema: sag.cli.v1)
+--quiet            Print only the essential value
+--yes              Confirm a safe local configuration operation
+```
+
+## Environment variables and resolution order
+
+Priority: **CLI flag > environment variable > current profile > local default probe**.
+
+```bash
+SAG_URL=http://localhost:8000
+SAG_TOKEN=<jwt>
+SAG_PROFILE=local
+```
+
+Profile storage locations:
+
+| Platform | Path                                                                      |
+| -------- | ------------------------------------------------------------------------- |
+| macOS    | `~/Library/Application Support/sag-cli/config.yaml`                       |
+| Linux    | `$XDG_CONFIG_HOME/sag-cli/config.yaml` or `~/.config/sag-cli/config.yaml` |
+| Windows  | `%APPDATA%\sag-cli\config.yaml`                                           |
+
+Agent-integration managed state is kept in `managed-connections.yaml` (mode `0600`). Do not edit it by hand.
+
+## Agent integration safety
+
+- SAG CLI **never** writes the JWT into agent configuration. The local Docker path needs no token at all.
+- The default MCP entry name is `sag-knowledge-<profile>`, or `sag-knowledge-local` when no profile is active.
+- The CLI only removes MCP entries it created whose fingerprint is unchanged. Same-name user entries and external edits block overwrite and delete.
+- `--dry-run` shows the plan only; `--yes` skips confirmation but never skips conflict checks.
+
+## JSON output and exit codes
+
+Under `--json`, both success and failure use a fixed schema:
+
+```json
+{ "schema": "sag.cli.v1", "ok": true, "data": {} }
+```
+
+```json
+{
+  "schema": "sag.cli.v1",
+  "ok": false,
+  "error": { "code": "AUTH_REQUIRED", "message": "No SAG token is configured" }
+}
+```
+
+Tokens never appear in JSON, logs, or error output. Full error and exit codes live in the architecture docs.
+
+## 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.md](CONTRIBUTING.md)
+- [SECURITY.md](SECURITY.md)

package/README.md

@@ -1,68 +1,133 @@
 # SAG CLI
 
-`@zleap-ai/sag-cli` 是运行中 SAG 实例的命令行客户端与诊断工具。除 Profile、
-认证、知识状态和检索外，v0.2 还可以验证本机 Docker SAG 的知识库 MCP，并自动
-接入 Codex 和 Claude Code。
+简体中文 | [English](README.en.md)
 
-## 安装与运行
+`@zleap-ai/sag-cli` 是 SAG 知识库的命令行客户端与诊断工具。它帮你在终端里：
 
-需要 Node.js 20.19 或更高版本：
+- 登录并验证一个正在运行的 SAG 实例；
+- 查看信源、文档处理状态，直接检索知识内容；
+- 验证本机 Docker SAG 的知识库 MCP，并把它一键接入 Codex 和 Claude Code。
+
+版本变更记录见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 你适不适合用它
+
+- 你手上已经有一个 SAG 实例（本机 Docker 或远程 HTTP），想在终端里查它、调它、把它接给编码 Agent。
+- 你在开发或运维 SAG，需要 `doctor`、`mcp test` 这类诊断能力。
+- 你只是想在 Codex 或 Claude Code 里用 SAG 做知识检索，又不想手写 MCP 配置。
+
+## 前置条件
+
+| 你想做的事                  | 需要准备                                                    |
+| --------------------------- | ----------------------------------------------------------- |
+| 安装并运行 CLI              | Node.js **≥ 20.19**                                         |
+| 用 HTTP API 登录、搜索      | 一个可访问的 SAG Origin（如 `http://localhost:8000`）+ JWT  |
+| 用本机 Docker 免 Token 路径 | Docker CLI，且本机运行着含 `sag_api.mcp.server` 的 SAG 容器 |
+| 接入 Codex                  | 已安装 Codex CLI（≥ 0.145）                                 |
+| 接入 Claude Code            | 已安装 Claude Code（≥ 2.1）                                 |
+
+**JWT 从哪拿**：登录 SAG Web → **Settings → Integrations**，复制其中的 JWT。CLI 会隐藏输入并优先保存到系统凭据存储（macOS Keychain、Windows Credential Manager、Linux Secret Service）；不可用时只保留在当前进程，自动化环境请改用 `SAG_TOKEN` 环境变量。
+
+## 安装
 
 ```bash
-npx @zleap-ai/sag-cli version
 npm install --global @zleap-ai/sag-cli
 sag --help
+sag version
 ```
 
-## 最短使用路径
+## 快速上手：选一条适合你的路径
+
+CLI 提供两条互相独立的路径，按你的场景选。
+
+### 路径 A：本机 Docker，免 Token（推荐给本地开发者）
 
-只验证和接入本机 Docker SAG MCP，不需要从 SAG Web 复制 Token：
+前提是本机 Docker 已经在跑 SAG API 容器。CLI 会自动发现容器，通过 `docker exec` 走 stdio MCP，全程不需要 JWT。
 
 ```bash
+# 1. 验证本机 Docker SAG MCP 可以工作
 sag mcp test
+
+# 2. 把它接入你的 Agent（选一个或两个都接）
 sag agent connect codex
 sag agent connect claude-code
+
+# 3. 随时看接入状态
 sag agent status
 ```
 
-需要先安装 Docker CLI，并运行包含 `sag_api.mcp.server` 的 SAG API 容器。
-接入某一个信源：
+只想验证 / 接入某一个信源时加 `--source-id`：
 
 ```bash
 sag mcp test --source-id <source-id>
 sag agent connect codex --source-id <source-id>
 ```
 
-原有 HTTP API 与知识检索路径：
+不放心可以先 `--dry-run` 看计划：
+
+```bash
+sag agent connect codex --dry-run
+```
+
+想撤掉接入：
 
 ```bash
+sag agent disconnect codex
+```
+
+### 路径 B：HTTP API + JWT（跨机器、或本机没有 Docker）
+
+用 SAG 的 HTTP API 做认证、查询、检索。
+
+```bash
+# 1. 记录一个 SAG 实例
 sag profile add local http://localhost:8000
+sag profile use local
+
+# 2. 登录（会提示输入 JWT）
 sag auth login
+sag auth status
+
+# 3. 体检 + 看信源
 sag doctor
 sag source list
 sag document status --source <source-id>
-sag search "查询内容"
+
+# 4. 检索
+sag search "MCP 如何接入" --source <source-id> --top-k 5
 ```
 
-`auth login` 会隐藏输入 SAG JWT，验证成功后优先保存到 macOS Keychain、
-Windows Credential Manager 或 Linux Secret Service。无法使用系统凭据存储时，
-Token 只保留在当前进程；自动化环境应使用 `SAG_TOKEN`。
+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
 sag version
-sag auth login|status|logout
-sag profile add|list|use|show|remove
+sag auth login | status | logout
+sag profile add | list | use | show | remove
 sag doctor
-sag source list|get|status
-sag document list|get|status
+sag source list | get | status
+sag document list | get | status
 sag search <query>
 sag mcp test
 sag agent list
-sag agent connect <codex|claude-code>
-sag agent status [codex|claude-code]
-sag agent disconnect <codex|claude-code>
+sag agent connect <codex | claude-code>
+sag agent status [codex | claude-code]
+sag agent disconnect <codex | claude-code>
 ```
 
 常用示例：
@@ -70,30 +135,25 @@ sag agent disconnect <codex|claude-code>
 ```bash
 sag profile list --json
 sag source get <source-id>
-sag source status [source-id]
 sag document list --source <source-id>
-sag document get <document-id> --source <source-id>
-sag document status [document-id] --source <source-id>
-sag search "MCP 如何接入" --source <source-id> --top-k 5 --strategy multi
+sag search "MCP 如何接入" --source <source-id> --strategy multi
 sag mcp test --container sag-api-1 --timeout 15000
-sag agent connect codex --dry-run
 sag agent connect claude-code --name sag-knowledge-local
-sag agent disconnect codex
 ```
 
-全局参数：
+## 全局参数
 
 ```text
 --profile <name>   选择 Profile
 --url <origin>     临时指定 SAG Origin
---json             输出稳定 JSON
+--json             输出稳定 JSON（schema: sag.cli.v1）
 --quiet            只输出核心值
 --yes              确认安全的本地配置操作
 ```
 
-## 环境变量
+## 环境变量与配置优先级
 
-配置优先级为：命令行参数 > 环境变量 > 当前 Profile > 本地默认探测。
+优先级：**命令行参数 > 环境变量 > 当前 Profile > 本地默认探测**。
 
 ```bash
 SAG_URL=http://localhost:8000
@@ -101,29 +161,26 @@ SAG_TOKEN=<jwt>
 SAG_PROFILE=local
 ```
 
-Profile URL 只保存 `scheme://host[:port]`。CLI 自动为 API 添加 `/api/v1`，
-不要求用户手工填写接口前缀。
+Profile 配置存放位置：
 
-## Agent MCP 接入行为
+| 平台    | 路径                                                                      |
+| ------- | ------------------------------------------------------------------------- |
+| macOS   | `~/Library/Application Support/sag-cli/config.yaml`                       |
+| Linux   | `$XDG_CONFIG_HOME/sag-cli/config.yaml` 或 `~/.config/sag-cli/config.yaml` |
+| Windows | `%APPDATA%\sag-cli\config.yaml`                                           |
 
-CLI 自动发现 Compose `api` 服务，优先选择项目名为 `sag` 的健康容器，并验证
-八个 SAG 只读 MCP 工具和 `list_sources` 调用。实际保存到 Agent 的命令是：
+Agent 接入的受管状态另存于 `managed-connections.yaml`（权限 `0600`），不要手工编辑。
 
-```text
-docker exec -i <container> python -m sag_api.mcp.server
-```
-
-默认 MCP 名称为 `sag-knowledge-<profile>`；没有 Profile 时为
-`sag-knowledge-local`。`--dry-run` 只展示计划，`--yes` 跳过确认但不会跳过
-冲突和安全检查。
+## Agent 接入的安全约束
 
-SAG CLI 不会把 JWT 写入 Agent 配置。它只删除自己创建且指纹未变化的 MCP
-条目；检测到同名用户配置或外部修改时会拒绝覆盖或删除。受管状态保存在平台配置
-目录的 `managed-connections.yaml` 中，权限为 `0600`。
+- SAG CLI **不会** 把 JWT 写入 Agent 配置。本机 Docker 路径无需 Token。
+- 默认 MCP 名称为 `sag-knowledge-<profile>`，无 Profile 时为 `sag-knowledge-local`。
+- 只删除自己创建、指纹未变化的 MCP 条目；检测到同名用户配置或外部改动会拒绝覆盖。
+- `--dry-run` 只展示计划；`--yes` 跳过确认但不跳过冲突检查。
 
-## JSON 契约
+## JSON 输出与退出码
 
-成功与失败都包含固定 Schema：
+`--json` 下成功与失败使用固定 Schema：
 
 ```json
 { "schema": "sag.cli.v1", "ok": true, "data": {} }
@@ -137,24 +194,21 @@ SAG CLI 不会把 JWT 写入 Agent 配置。它只删除自己创建且指纹未
 }
 ```
 
-JSON、日志和错误输出不会包含 Token。退出码和错误分类见架构说明：
-[中文](docs/architecture.zh-CN.md) / [English](docs/architecture.md)。
+Token 不会出现在 JSON、日志或错误输出里。完整错误码与退出码见架构文档。
 
-## 开发
+## 深入阅读
 
-```bash
-npm install
-npm run dev -- --help
-npm run check
-```
+### 使用指南
 
-本地运行、认证、知识库搜索、断点调试、测试和 Docker MCP 验证见开发指南：
-[中文](docs/development.zh-CN.md) / [English](docs/development.md)。
+- [CHANGELOG.md](CHANGELOG.md) — 版本变更记录
+- 架构与退出码：[中文](docs/architecture.zh-CN.md) / [English](docs/architecture.md)
+- [SKILL.md](SKILL.md) — 教 Agent 怎么高效探索 SAG 知识库
 
-贡献规则见 [CONTRIBUTING.md](CONTRIBUTING.md)。其他文档：
+### 开发与贡献
 
-- 发布：[中文](docs/release.zh-CN.md) / [English](docs/release.md)
-- 兼容性：[中文](docs/compatibility.zh-CN.md) /
-  [English](docs/compatibility.md)
-- OAuth 与 MCP 授权：[中文](docs/oauth.zh-CN.md) /
-  [English](docs/oauth.md)
+- 本地开发与调试：[中文](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)
+- [SECURITY.md](SECURITY.md)