@linkmind_claw/openclaw-faq-kb 3.0.0 → 3.2.0

package/skills/faq-kb/SKILL.md

@@ -1,77 +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:
 
-| 角色 | 说明 | 管理 KB | 设 public/private | 分享 viewer | 管理用户角色 | 查询 |
-|------|------|---------|-------------------|-------------|-------------|------|
-| Admin | 系统管理员 | 全部 | 是 | 是 | 是 | 全部 |
-| Editor | 管理员 | 全部 | 是 | 是 | 否 | 全部 |
-| Viewer | 查看者（按 KB 授权） | 否 | 否 | 否 | 否 | 被授权的 KB |
-| 无权限 | 普通用户 | 否 | 否 | 否 | 否 | 仅 public KB |
+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
 
-- Admin: 通过 `/linkmind_claim` 绑定，或数据库 `role=admin`
-- Editor: 由 Admin 通过 `/linkmind_role` 提升
-- Viewer: 由 Admin/Editor 通过 `/linkmind_share` 授予（按知识库）
+## Permission Model
 
-## Slash Commands
+```
+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.
+
+**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
+
+**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
+
+**Notes:**
+- Requires **editor** or above permission
+- Runs 2-10 minutes; polls progress internally
+- Returns `kb_id` for subsequent queries
+
+### `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
 
-| 命令 | 功能 | 权限 |
-|------|------|------|
-| `/linkmind_help` | 使用帮助（按身份展示不同内容） | 所有人 |
-| `/linkmind_claim <密钥>` | 绑定 Admin 身份 | 未绑定时第一个用户 |
-| `/linkmind_me` | 查看身份信息 | 所有人 |
-| `/linkmind_role <用户ID> <editor/user>` | 设置用户角色 | 仅 Admin |
-| `/linkmind_create <名称> <URL>` | 创建知识库并训练 | Admin / Editor |
-| `/linkmind_share <KB名> public/private` | 切换知识库可见性 | Admin / Editor |
-| `/linkmind_share <KB名> <用户ID> viewer/revoke` | 授予/撤销查看权限 | Admin / Editor |
-| `/linkmind_query <KB名> <问题>` | 知识库问答 | 所有人（按权限过滤） |
-| `/linkmind_list` | 列出可访问的知识库 | 所有人（按权限过滤） |
+**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)
 
 ```
-1. 服务器启动，安装 Plugin
-2. 第一个用户发送任意命令 → 自动展示密钥
-3. /linkmind_claim <密钥> → 成为 Admin
-4. /linkmind_create 客服知识库 https://example.com/doc.pdf → 训练
-5. /linkmind_share 客服知识库 public → 设为公开
+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
 ```
 
-### Admin 管理团队
+### Workflow 2: Bot Owner sets up a new KB
 
 ```
-1. /linkmind_role <用户ID> editor → 提升为管理员
-2. Editor 可自行创建和管理知识库
-3. /linkmind_role <用户ID> user → 降为普通用户
+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
 
 ```
-/linkmind_share 客服知识库 123456789 viewer → 授予查看权限
-/linkmind_share 客服知识库 123456789 revoke → 撤销权限
-/linkmind_share 客服知识库 public → 所有人可查询
-/linkmind_share 客服知识库 private → 仅授权用户可查询
+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_list → 查看可访问的知识库
-2. /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` 即可了解所有功能
-- 服务器未绑定 Admin 时密钥会自动展示给第一个用户
-- Admin 创建的知识库默认私有，需通过 `/linkmind_share` 开放
-- Editor 不能管理用户角色，只有 Admin 可以
-- 普通用户只能查询 public 知识库和被授权的知识库
+- **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.