mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 03:13:41 +08:00
docs(webchat): document /wiki/pages endpoint and [[slug]] picker
Add /wiki/pages row to endpoint table and a new "Wiki knowledge-base reference ([[slug]] picker)" section explaining the directive-text mechanism, query parameters, visibility rules (synthesis excluded, 100-page cap, KB-scope fallback), and curl examples (zh + en). Follow-up docs for the wiki picker endpoint shipped in this PR.
This commit is contained in:
倪程伟
matevip
parent
f6156f6093
commit
0ab11f8922
@ -69,6 +69,7 @@ init({ apiKey: 'your-channel-api-key', server: 'https://<your-deployment>' })
|
||||
| POST | `/stream` | API Key | SSE streaming chat (issues visitorToken); the body may include an optional `agentId` to override the channel's bound agent (must be in the same workspace as the channel) |
|
||||
| GET | `/config` | API Key | Get channel config (title/placeholder/...) |
|
||||
| GET | `/skills` | + visitorToken | List skills visible to this agent (for building your own slash picker UI) |
|
||||
| GET | `/wiki/pages` | + visitorToken | List wiki pages visible to this agent (for building your own `[[slug]]` reference picker UI) |
|
||||
| POST | `/sessions` | API Key | Explicitly create an empty session thread |
|
||||
| GET | `/sessions` | + visitorToken | List sessions (excludes archived by default) |
|
||||
| GET | `/sessions/page` | + visitorToken | Paginated + keyword search |
|
||||
@ -231,6 +232,58 @@ curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
|
||||
|
||||
> Note: the directive text relies on the LLM "obeying" and calling `load_skill`. Under complex tasks it occasionally drifts; for production, bind the target skill to the agent and reinforce the system prompt in `AGENTS.md`.
|
||||
|
||||
## Wiki knowledge-base reference (`[[slug]]` picker)
|
||||
|
||||
The knowledge base has a picker parallel to the slash-skill one — using the **Obsidian / Wikipedia wikilink convention `[[slug]]`**. The user types `[[` in the input box to open a picker, selects a page, and a `[[<slug>]]` token is inserted. On submit the input is rewritten into a directive text, and the LLM calls `wiki_read_page(slug=...)` to read the referenced page before answering. The backend **does no `[[` parsing** — webchat uses the exact same agent runtime as the admin console.
|
||||
|
||||
Directive text format (**exact**):
|
||||
|
||||
- English: `Reference the wiki page [[<slug>]]: <user message>`
|
||||
- Chinese: `参考知识库页面 [[<slug>]]：<用户消息>`
|
||||
|
||||
Multiple references are supported naturally (just list them):
|
||||
|
||||
```
|
||||
Reference the wiki pages [[auth-design]], [[webchat-integration]]: how do these two work together?
|
||||
```
|
||||
|
||||
To build your own picker, first list the pages via the new endpoint:
|
||||
|
||||
```bash
|
||||
curl "https://mate.example.com/api/v1/channels/webchat/wiki/pages?visitorId=v1" \
|
||||
-H "X-MC-Key: your-api-key" \
|
||||
-H "X-MC-Visitor-Token: <token>"
|
||||
# returns [{"kbId":1,"kbName":"MateClaw Docs","slug":"webchat-integration",
|
||||
# "title":"WebChat Integration Guide","summary":"...","pageType":"source"}, ...]
|
||||
```
|
||||
|
||||
Optional query parameters:
|
||||
|
||||
| Parameter | Required | Notes |
|
||||
|---|---|---|
|
||||
| `visitorId` | yes | Visitor ID |
|
||||
| `agentId` | no | Override the channel's bound agent; must be in the same workspace as the channel |
|
||||
| `keyword` | no | Filter, matches `slug` OR `title` (LIKE) |
|
||||
|
||||
Behavior:
|
||||
|
||||
- **Scope**: KBs explicitly bound to the agent (`mate_agent_wiki_kb`); with no bindings, falls back to every KB in the workspace (mirrors the wiki-tool default)
|
||||
- **Page filter**: excludes `pageType=synthesis` (LLM intermediate artifacts)
|
||||
- **100-page cap**: when exceeded (and no `keyword`), returns `422` asking the caller to narrow with a keyword
|
||||
- **Returned fields**: only `kbId / kbName / slug / title / summary / pageType`; **no** content, embedding, sourceRawIds, or outgoingLinks (admin-console-only)
|
||||
- **Ordering**: by `slug` ascending
|
||||
|
||||
After a user picks a page, construct the message (English directive example):
|
||||
|
||||
```bash
|
||||
curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
|
||||
-H "X-MC-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"visitorId":"v1","message":"Reference the wiki page [[webchat-integration]]: summarize the integration flow"}'
|
||||
```
|
||||
|
||||
> Note: `[[slug]]` is a convention hint for the LLM (documented in the `wiki_read_page` `@Tool` description), but the LLM can still drift under complex tasks. For production, reinforce the system prompt in `AGENTS.md`, or bind the target KB to a dedicated agent to narrow the retrieval space.
|
||||
|
||||
## curl examples
|
||||
|
||||
**Step 1: send the first message**
|
||||
|
||||
@ -69,6 +69,7 @@ init({ apiKey: 'your-channel-api-key', server: 'https://<你的部署地址>' })
|
||||
| POST | `/stream` | API Key | SSE 流式对话(签发 visitorToken);请求体可选传 `agentId` 覆盖渠道绑定的 agent(必须与渠道同 workspace) |
|
||||
| GET | `/config` | API Key | 拿渠道配置(title/placeholder/...) |
|
||||
| GET | `/skills` | + visitorToken | 列出该 agent 绑定的可见技能(供下游自建 slash picker UI) |
|
||||
| GET | `/wiki/pages` | + visitorToken | 列出该 agent 可见的 wiki 页面(供下游自建 `[[slug]]` 引用 picker UI) |
|
||||
| POST | `/sessions` | API Key | 显式创建空会话线程 |
|
||||
| GET | `/sessions` | + visitorToken | 列出会话(默认排除 archived) |
|
||||
| GET | `/sessions/page` | + visitorToken | 分页 + 关键词搜索 |
|
||||
@ -236,6 +237,58 @@ curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
|
||||
|
||||
> 注意:指令文本依赖 LLM "听话"调用 `load_skill`。复杂任务下偶发漂移,生产环境建议把目标技能**绑定**到 agent(`agentId` 对应的)并在 `AGENTS.md` 里强化系统提示。
|
||||
|
||||
## Wiki 知识库引用(`[[slug]]` picker)
|
||||
|
||||
跟技能调用一样,wiki 知识库也可以通过 picker 显式指代——用 **Obsidian / Wikipedia 风格的 `[[slug]]` 链接语法**。用户在输入框敲 `[[` 触发 picker,选中后插入 `[[<slug>]]` token,发送时改写为指令文本,LLM 收到后调 `wiki_read_page(slug=...)` 读取该页面再做答。后端**不做任何 `[[` 解析**,webchat 走的是和主控台完全一样的 agent runtime。
|
||||
|
||||
指令文本格式(**精确**):
|
||||
|
||||
- 中文:`参考知识库页面 [[<slug>]]:<用户消息>`
|
||||
- 英文:`Reference the wiki page [[<slug>]]: <user message>`
|
||||
|
||||
多引用天然支持(并列写即可):
|
||||
|
||||
```
|
||||
参考知识库页面 [[auth-design]]、[[webchat-integration]]:这两套怎么协同?
|
||||
```
|
||||
|
||||
下游集成方要自建 picker UI,先用端点拿页面清单:
|
||||
|
||||
```bash
|
||||
curl "https://mate.example.com/api/v1/channels/webchat/wiki/pages?visitorId=v1" \
|
||||
-H "X-MC-Key: your-api-key" \
|
||||
-H "X-MC-Visitor-Token: <token>"
|
||||
# 返回 [{"kbId":1,"kbName":"MateClaw 文档","slug":"webchat-integration",
|
||||
# "title":"WebChat 接入指南","summary":"...","pageType":"source"}, ...]
|
||||
```
|
||||
|
||||
可选 query 参数:
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `visitorId` | 是 | 访客 ID |
|
||||
| `agentId` | 否 | 显式指定 agent,缺省回落到渠道绑定;必须与渠道同 workspace |
|
||||
| `keyword` | 否 | 关键词过滤,匹配 `slug` 或 `title`(LIKE) |
|
||||
|
||||
行为约束:
|
||||
|
||||
- **可见范围**:agent 显式绑定的 KB(`mate_agent_wiki_kb` 表);无绑定时回落到该 workspace 全部 KB(跟 wiki 工具的默认行为一致)
|
||||
- **页面过滤**:排除 `pageType=synthesis`(LLM 中间产物,对终端访客无意义)
|
||||
- **100 页上限**:超出时(且未传 `keyword`)返回 `422`,要求传 `keyword` 收窄
|
||||
- **返回字段**:仅 `kbId / kbName / slug / title / summary / pageType`;**不包含**正文、embedding、sourceRawIds、outgoingLinks(这些只走管理控制台)
|
||||
- **排序**:按 `slug` 字母序
|
||||
|
||||
选中后构造消息(中文 directive 示例):
|
||||
|
||||
```bash
|
||||
curl -N -X POST https://mate.example.com/api/v1/channels/webchat/stream \
|
||||
-H "X-MC-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"visitorId":"v1","message":"参考知识库页面 [[webchat-integration]]:总结这套接入流程"}'
|
||||
```
|
||||
|
||||
> 注意:`[[slug]]` 是给 LLM 看的约定提示(`wiki_read_page` 的 `@Tool` description 里写明了),但 LLM 仍可能漂移——复杂任务下建议同时在 `AGENTS.md` 里强化提示,或把目标 KB **绑定**到专用 agent 收窄检索空间。
|
||||
|
||||
## curl 示例
|
||||
|
||||
**第一步:发首条消息**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user