@zleap-ai/sag-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sag contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# SAG CLI
+
+`@zleap-ai/sag-cli` 是运行中 SAG 实例的命令行客户端与诊断工具。除 Profile、
+认证、知识状态和检索外，v0.2 还可以验证本机 Docker SAG 的知识库 MCP，并自动
+接入 Codex 和 Claude Code。
+
+## 安装与运行
+
+需要 Node.js 20.19 或更高版本：
+
+```bash
+npx @zleap-ai/sag-cli version
+npm install --global @zleap-ai/sag-cli
+sag --help
+```
+
+## 最短使用路径
+
+只验证和接入本机 Docker SAG MCP，不需要从 SAG Web 复制 Token：
+
+```bash
+sag mcp test
+sag agent connect codex
+sag agent connect claude-code
+sag agent status
+```
+
+需要先安装 Docker CLI，并运行包含 `sag_api.mcp.server` 的 SAG API 容器。
+接入某一个信源：
+
+```bash
+sag mcp test --source-id <source-id>
+sag agent connect codex --source-id <source-id>
+```
+
+原有 HTTP API 与知识检索路径：
+
+```bash
+sag profile add local http://localhost:8000
+sag auth login
+sag doctor
+sag source list
+sag document status --source <source-id>
+sag search "查询内容"
+```
+
+`auth login` 会隐藏输入 SAG JWT，验证成功后优先保存到 macOS Keychain、
+Windows Credential Manager 或 Linux Secret Service。无法使用系统凭据存储时，
+Token 只保留在当前进程；自动化环境应使用 `SAG_TOKEN`。
+
+## 命令
+
+```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>
+```
+
+常用示例：
+
+```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 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
+--quiet            只输出核心值
+--yes              确认安全的本地配置操作
+```
+
+## 环境变量
+
+配置优先级为：命令行参数 > 环境变量 > 当前 Profile > 本地默认探测。
+
+```bash
+SAG_URL=http://localhost:8000
+SAG_TOKEN=<jwt>
+SAG_PROFILE=local
+```
+
+Profile URL 只保存 `scheme://host[:port]`。CLI 自动为 API 添加 `/api/v1`，
+不要求用户手工填写接口前缀。
+
+## Agent MCP 接入行为
+
+CLI 自动发现 Compose `api` 服务，优先选择项目名为 `sag` 的健康容器，并验证
+八个 SAG 只读 MCP 工具和 `list_sources` 调用。实际保存到 Agent 的命令是：
+
+```text
+docker exec -i <container> python -m sag_api.mcp.server
+```
+
+默认 MCP 名称为 `sag-knowledge-<profile>`；没有 Profile 时为
+`sag-knowledge-local`。`--dry-run` 只展示计划，`--yes` 跳过确认但不会跳过
+冲突和安全检查。
+
+SAG CLI 不会把 JWT 写入 Agent 配置。它只删除自己创建且指纹未变化的 MCP
+条目；检测到同名用户配置或外部修改时会拒绝覆盖或删除。受管状态保存在平台配置
+目录的 `managed-connections.yaml` 中，权限为 `0600`。
+
+## JSON 契约
+
+成功与失败都包含固定 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" }
+}
+```
+
+JSON、日志和错误输出不会包含 Token。退出码和错误分类见架构说明：
+[中文](docs/architecture.zh-CN.md) / [English](docs/architecture.md)。
+
+## 开发
+
+```bash
+npm install
+npm run dev -- --help
+npm run check
+```
+
+本地运行、认证、知识库搜索、断点调试、测试和 Docker MCP 验证见开发指南：
+[中文](docs/development.zh-CN.md) / [English](docs/development.md)。
+
+贡献规则见 [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)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }