@linkmind_claw/openclaw-faq-kb 1.3.2 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkmind_claw/openclaw-faq-kb",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "OpenClaw Plugin - FAQ Knowledge Base: one-click document training & intelligent Q&A",
   "type": "module",
   "main": "dist/index.js",

package/skills/faq-kb/SKILL.md

@@ -1,124 +1,151 @@
 ---
 name: faq-knowledge-base
-description: FAQ 知识库 — 上传文档自动训练，智能问答，FAQ 增删改查
+description: FAQ 知识库 — 自动登录、上传文档训练、智能问答、权限管理
 ---
 
 # FAQ Knowledge Base Skill
 
-You have access to a FAQ Knowledge Base system that lets you:
+FAQ 知识库系统，支持文档自动训练、智能问答、用户权限管理。
 
-1. **Create & train** a knowledge base from a document (PDF/DOCX/TXT/MD)
-2. **Ask questions** against a trained knowledge base
-3. **Manage FAQ items** (create, update, delete, list)
-4. **Browse knowledge bases** (list, detail, delete, system status)
+## 认证机制
+
+- **所有操作自动完成认证**，无需用户手动登录
+- 系统通过用户的渠道 ID（如 Telegram user ID）自动识别身份
+- 首次操作时自动注册为 viewer 角色，后续自动登录
+- 用户无需关心认证流程，直接使用即可
 
 ## Available Tools
 
+### `faq_account_register`
+
+OAuth 用户注册/登录（通常由系统自动调用，无需手动触发）。
+
+**Parameters:**
+- `channel_type` (required): 渠道类型 — telegram / discord / slack / web
+- `channel_user_id` (required): 渠道用户唯一 ID
+- `display_name` (optional): 显示名称
+- `channel_bot_id` (optional): Bot 标识，默认 "default"
+
+### `faq_account_manage`
+
+系统管理员权限操作（仅 admin 可用）。
+
+**When to use:**
+- 需要给用户授予全局角色
+- 需要列出所有渠道用户
+- 需要查看自己的身份信息
+
+**Parameters:**
+- `action` (required): `grant_role` / `list_users` / `my_info`
+- `target_channel_user_id`: 目标用户 ID（grant_role 必填）
+- `role`: 要授予的角色 — viewer / editor / reviewer / admin
+
 ### `faq_kb_create_and_train`
 
-Use this when the user wants to create a new knowledge base from a document.
+一键创建知识库并完成全部训练流程。
 
 **When to use:**
 - User says "create a knowledge base from this document"
 - User provides a file URL and wants to set up a Q&A system
-- User wants to "train" or "build" a knowledge base
 
 **Parameters:**
-- `kb_name` (required): Name for the knowledge base
-- `file_url` (required): URL to the document file (PDF/DOCX/DOC/TXT/MD)
-- `description` (optional): Description of the knowledge base
-- `tag_name` (optional): Tag for categorization
+- `kb_name` (required): 知识库名称
+- `file_url` (required): 文档 URL（支持 PDF / DOCX / DOC / TXT / MD）
+- `description` (optional): 知识库描述
+- `tag_name` (optional): 分类标签
 
 **Notes:**
-- This tool runs the full pipeline and may take 2-10 minutes
-- It returns the `kb_id` which you need for subsequent queries
-- The pipeline stages are: upload → AI extract → build tree → confirm → index
-
-**Example:**
-```
-faq_kb_create_and_train({
-  kb_name: "产品手册FAQ",
-  file_url: "https://example.com/product-manual.pdf",
-  description: "产品使用手册的FAQ知识库"
-})
-```
+- 训练耗时 2-10 分钟，取决于文档大小
+- 创建者自动成为该知识库的 owner
+- Pipeline: 上传 → AI 提取 → 构建知识树 → 建索引
 
 ### `faq_kb_query`
 
-Use this when the user wants to ask a question against an existing knowledge base.
+向知识库提问并获取 AI 回答。
 
 **When to use:**
-- User asks a question and you know which knowledge base to query
+- User asks a question about a specific knowledge base
 - User says "search the knowledge base for..."
-- User wants an answer from a specific FAQ collection
 
 **Parameters:**
-- `kb_id` (required): The knowledge base ID (from create or list)
-- `question` (required): The question to ask
-- `enable_polish` (optional): Set to `true` for LLM-polished answers that synthesize multiple FAQ matches
-- `user_id` (optional): For access control
-- `session_id` (optional): For conversation context tracking
+- `kb_name` (optional, recommended): 知识库名称，支持模糊匹配
+- `kb_id` (optional): 知识库 ID，精确匹配
+- `question` (required): 要查询的问题
+- `enable_polish` (optional): true 时 LLM 综合多个 FAQ 生成更自然的回答
 
 **Notes:**
-- The knowledge base must be trained (is_active=true) before querying
-- The response includes the answer, confidence score, and source references
-- A `log_id` is returned for submitting feedback later
+- 推荐用 `kb_name` 而非 `kb_id`，对用户更友好
+- 名称有多个匹配时会返回候选列表供选择
+- 只能查询用户有权限的知识库
 
-### `faq_kb_manage`
-
-Use this when the user wants to manage individual FAQ items.
+### `faq_kb_list`
 
-**When to use:**
-- User wants to add a new Q&A pair
-- User wants to edit or delete an existing FAQ
-- User wants to browse FAQs in a knowledge base
+列出当前用户可访问的知识库。
 
 **Parameters:**
-- `action` (required): One of `create`, `update`, `delete`, `list`, `get`
-- `kb_id` (required): Knowledge base ID
-- `faq_id`: Required for `update`, `delete`, `get`
-- `question`, `answer`: Required for `create`; at least one required for `update`
-- `keyword`, `page`, `page_size`: For `list` filtering
+- `keyword` (optional): 按名称搜索
+- `tag_name` (optional): 按标签筛选
+- `page`, `page_size` (optional): 分页
 
-### `faq_kb_list`
+## Slash Commands
 
-Use this when the user wants to see available knowledge bases or system info.
+所有命令自动完成身份认证，用户直接使用即可。
 
-**When to use:**
-- User asks "what knowledge bases do I have?"
-- User wants details about a specific knowledge base
-- User wants to delete a knowledge base
-- User asks about system status
+| 命令 | 功能 | 用法 |
+|------|------|------|
+| `/faq_register` | 查看我的身份信息 | `/faq_register` |
+| `/faq_create` | 创建知识库并训练 | `/faq_create <名称> <文档URL>` |
+| `/faq_query` | 知识库问答 | `/faq_query <知识库名称> <问题>` |
+| `/faq_share` | 管理知识库权限 | `/faq_share <KB名> <用户ID> <角色>` |
+| `/faq_list` | 列出我的知识库 | `/faq_list` |
 
-**Parameters:**
-- `action` (required): One of `list`, `detail`, `delete`, `system_status`
-- `kb_id`: Required for `detail` and `delete`
-- `keyword`, `tag_name`: Optional filters for `list`
+### `/faq_share` 详细用法
+
+```
+/faq_share 客服知识库 123456789 viewer   — 分享给某人（只读）
+/faq_share 客服知识库 123456789 editor   — 授予或升级为编辑权限
+/faq_share 客服知识库 123456789 revoke   — 撤销权限
+```
+
+角色说明：
+- **viewer**: 只读，可查询
+- **editor**: 可编辑，可创建/修改 FAQ
+- **revoke**: 撤销该用户的访问权限
+
+只有知识库的 **owner**（创建者）可以管理权限。
 
 ## Typical Workflows
 
-### Workflow 1: Build a knowledge base from scratch
+### Workflow 1: 创建并使用知识库
+
 ```
-1. faq_kb_create_and_train(kb_name="...", file_url="...")  → get kb_id
-2. faq_kb_query(kb_id="...", question="...")               → get answer
+1. /faq_create 产品手册 https://example.com/manual.pdf
+   → 自动注册 + 创建 + 训练（2-10 min）
+2. /faq_query 产品手册 如何退款？
+   → 获取答案
 ```
 
-### Workflow 2: Query an existing knowledge base
+### Workflow 2: 查询已有知识库
+
 ```
-1. faq_kb_list(action="list")                              → find kb_id
-2. faq_kb_query(kb_id="...", question="...")               → get answer
+1. /faq_list
+   → 查看我有权限的知识库
+2. /faq_query 客服知识库 营业时间是什么？
+   → 获取答案
 ```
 
-### Workflow 3: Manually build FAQ content
+### Workflow 3: 分享知识库给团队
+
 ```
-1. faq_kb_list(action="list")                              → find kb_id
-2. faq_kb_manage(action="create", kb_id="...", question="...", answer="...")
-3. faq_kb_manage(action="list", kb_id="...")               → verify
+1. /faq_share 客服知识库 987654321 viewer
+   → 分享给同事（只读）
+2. /faq_share 客服知识库 987654321 editor
+   → 升级为编辑权限
 ```
 
 ## Important Notes
 
-- All knowledge base IDs are UUIDs (e.g., `a1b2c3d4-e5f6-...`)
-- The `faq_kb_create_and_train` tool is long-running (minutes). Be patient.
-- Always check if a knowledge base exists before querying it.
-- The API server is at `67.212.146.21:8999` by default.
+- 所有操作基于用户渠道 ID 自动认证，无需手动登录
+- 知识库使用名称查询，无需记忆 UUID
+- 创建知识库后自动成为 owner，可通过 `/faq_share` 管理他人权限
+- 只能查询和操作自己有权限的知识库