@linkmind_claw/openclaw-faq-kb 2.0.3 → 3.1.0

package/skills/faq-kb/SKILL.md

@@ -1,69 +1,173 @@
 ---
 name: faq-knowledge-base
-description: LinkMind 智能知识库 — 管理员绑定、文档训练、智能问答、权限控制
+description: FAQ 知识库 — 社媒用户注册、权限管理、文档训练、智能问答
 ---
 
-# LinkMind Knowledge Base Skill
+# FAQ Knowledge Base Skill
 
-## 核心概念：管理员机制
+You have access to a FAQ Knowledge Base system with **user identity & permission management** that lets you:
 
-一个 OpenClaw 实例 = 一个管理员（Owner）。
+1. **Register / login** social-media channel users (Telegram, Discord, etc.)
+2. **Manage permissions** — grant roles and knowledge base access
+3. **Create & train** a knowledge base from a document (PDF/DOCX/TXT/MD)
+4. **Ask questions** against a trained knowledge base
+5. **Browse knowledge bases** — list accessible KBs
 
-- 无论连接了多少个 bot，它们共享同一个管理员
-- 管理员通过 Telegram user ID 绑定
-- 管理员拥有全部权限：创建/训练/删除知识库、管理用户权限
-- 其他用户只能查询管理员开放给他的知识库 + 公开知识库
+## Permission Model
 
-### 绑定管理员流程
+```
+Role        │ Capabilities
+────────────┼──────────────────────────────────
+viewer      │ Query knowledge bases, list KBs
+editor      │ + Create KB, train, manage FAQ
+reviewer    │ + Delete FAQ, view audit logs
+admin       │ + Delete KB, manage users, grant roles
+```
+
+- New users from social-media channels default to **viewer** (query-only).
+- The Bot Owner (first admin) can promote users via `faq_account_manage`.
+- `kb_scope` controls which KBs a user can access (null = all).
+
+## Available Tools
+
+### `faq_account_register`
+
+Auto-register or login a social-media channel user.
+
+**When to use:**
+- A new user interacts with the bot for the first time
+- You need to establish the user's identity before other operations
+- The user explicitly asks to register or log in
+
+**Parameters:**
+- `channel_type` (required): telegram / discord / slack / web / whatsapp / line
+- `channel_user_id` (required): The user's unique ID on that platform
+- `channel_bot_id` (optional): Bot identifier (default "default")
+- `display_name` (optional): User display name
+- `role` (optional): Initial role for new users (default "viewer")
+
+**Notes:**
+- Returns `is_new: true` for first-time users with a freshly generated `api_key`
+- The API Key is automatically cached; all subsequent requests use this user's identity
+- Existing users just get their current identity info (no new key)
+
+### `faq_account_manage`
+
+Admin-level account management.
+
+**When to use:**
+- Bot Owner wants to promote a user: "让用户 X 也能建库"
+- Admin wants to see who's registered: "看看都有谁在用"
+- User wants to check their own permissions: "我能做什么"
+
+**Parameters:**
+- `action` (required): `grant_role` / `list_users` / `my_info`
+- `target_channel_user_id`: Required for `grant_role`
+- `target_channel_type`: Channel type of the target (default "telegram")
+- `role`: The role to grant (required for `grant_role`)
+- `kb_scope`: Array of KB IDs the user can access (null = all)
+
+**Notes:**
+- `grant_role` and `list_users` require **admin** permission
+- `my_info` works for any authenticated user
+
+### `faq_kb_create_and_train`
+
+One-click knowledge base creation + full training pipeline.
 
-1. 服务器首次启动时生成一次性密钥
-2. 第一个与 bot 对话的用户会自动收到密钥
-3. 用户发送 `/linkmind_claim <密钥>` 完成绑定，成为管理员
+**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
 
-## Slash Commands
+**Parameters:**
+- `kb_name` (required): Name for the knowledge base
+- `file_url` (required): URL to the document (PDF/DOCX/DOC/TXT/MD)
+- `description` (optional): Description
+- `tag_name` (optional): Tag for categorization
 
-| 命令 | 功能 | 权限 |
-|------|------|------|
-| `/linkmind_help` | 使用帮助（根据身份显示不同内容） | 任何人 |
-| `/linkmind_claim <密钥>` | 绑定管理员身份 | 未绑定时任何人 |
-| `/linkmind_me` | 查看身份信息 | 任何人 |
-| `/linkmind_create <名称> <URL>` | 创建知识库并训练 | 仅管理员 |
-| `/linkmind_query <名称> <问题>` | 知识库问答 | 任何人 |
-| `/linkmind_share <KB名> <用户ID> <角色>` | 管理 KB 权限 | 仅管理员 |
-| `/linkmind_list` | 列出可访问的知识库 | 任何人 |
+**Notes:**
+- Requires **editor** or above permission
+- Runs 2-10 minutes; polls progress internally
+- Returns `kb_id` for subsequent queries
 
-### `/linkmind_share` 用法
+### `faq_kb_query`
+
+Ask a question against a trained knowledge base.
+
+**When to use:**
+- User asks a question and you know which KB to query
+- User says "search the knowledge base for..."
+
+**Parameters:**
+- `kb_id` (required): Knowledge base ID
+- `question` (required): The question
+- `enable_polish` (optional): LLM-polished multi-FAQ answer
+- `user_id`, `session_id` (optional): For tracking
+
+**Notes:**
+- Requires **viewer** or above permission
+- KB must be trained (is_active=true)
+
+### `faq_kb_list`
+
+List accessible knowledge bases.
+
+**When to use:**
+- User asks "what knowledge bases do I have?"
+- You need to find a kb_id before querying
+
+**Parameters:**
+- `keyword` (optional): Search by name
+- `tag_name` (optional): Filter by tag
+- `page`, `page_size` (optional): Pagination
+
+## Typical Workflows
+
+### Workflow 1: First-time user (social media)
 
 ```
-/linkmind_share 客服知识库 123456789 viewer   — 分享（只读）
-/linkmind_share 客服知识库 123456789 editor   — 授予编辑权限
-/linkmind_share 客服知识库 123456789 revoke   — 撤销权限
+1. faq_account_register(channel_type="telegram", channel_user_id="12345")
+   → registers as viewer, API Key cached
+2. faq_kb_list()
+   → shows available knowledge bases
+3. faq_kb_query(kb_id="...", question="...")
+   → gets answer
 ```
 
-## Typical Workflows
+### Workflow 2: Bot Owner sets up a new KB
+
+```
+1. faq_account_register(channel_type="telegram", channel_user_id="owner_id", role="admin")
+   → registers as admin
+2. faq_kb_create_and_train(kb_name="客服FAQ", file_url="https://...")
+   → creates and trains KB, returns kb_id
+3. faq_kb_query(kb_id="...", question="退款政策是什么？")
+   → verifies the KB works
+```
 
-### 首次部署
+### Workflow 3: Owner grants access to a friend
 
 ```
-1. 服务器启动，安装 Plugin，连接 Bot
-2. 用户首次发送任意命令 → 自动展示密钥和绑定指引
-3. /linkmind_claim <密钥> → 绑定成功，成为管理员
-4. /linkmind_create 客服知识库 https://example.com/doc.pdf → 训练
-5. /linkmind_query 客服知识库 如何退款？ → 查询
+1. (Friend) faq_account_register(channel_type="telegram", channel_user_id="friend_id")
+   → friend registers as viewer
+2. (Owner) faq_account_manage(action="grant_role",
+     target_channel_user_id="friend_id", role="editor", kb_scope=["kb_abc"])
+   → friend can now create/edit in kb_abc
 ```
 
-### 普通用户使用
+### Workflow 4: Check permissions when denied
 
 ```
-1. /linkmind_help → 查看可用功能
-2. /linkmind_list → 查看可访问的知识库
-3. /linkmind_query 客服知识库 问题 → 查询
+1. User tries faq_kb_create_and_train → gets permission error
+2. faq_account_manage(action="my_info")
+   → shows role=viewer, can only read
+3. Tell user: "你当前是 viewer 角色，只能查询。请联系管理员提升权限。"
 ```
 
 ## Important Notes
 
-- 首次使用发 `/linkmind_help` 即可了解所有功能
-- 服务器未绑定管理员时，所有命令会提示先完成绑定
-- 密钥会自动展示给第一个与 bot 对话的用户
-- 管理员创建的知识库默认私有，需通过 /linkmind_share 开放
-- 普通用户无法创建/删除知识库
+- **Always register first**: Before any KB operation, ensure the user has an identity via `faq_account_register`.
+- **Permission errors**: When a 403 error occurs, guide the user to check their role or contact the admin.
+- **KB IDs are UUIDs**: e.g., `a1b2c3d4-e5f6-...`
+- **API server**: `67.212.146.21:8999` by default.
+- The `faq_kb_create_and_train` tool is long-running (minutes). Be patient.