mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-13 03:13:41 +08:00
docs(agent): document per-agent primary knowledge base binding (1.5.0)
Add the user-facing and API-reference docs that explain how an employee
can declare a primary knowledge base, what the runtime fallback chain
looks like, and how the binding is driven from the API.
agents.md (zh + en)
- New section "Knowledge base binding (per-agent primary KB)" right after
the tool-binding section, with a 1.5.0 New In badge
- Lays out the design intent explicitly: KBs stay workspace-shared, the
binding only chooses a default target, multiple agents may pick the
same KB as primary
- Documents the runtime resolution order used by wiki tools: explicit
kbName/kbId, agent.primaryKbId, most-recently-updated workspace KB
- Migration note about the legacy kb.agent_id to agent.primary_kb_id
backfill and the visibility change for anyone who relied on the old
one-to-one isolation
api.md (zh + en)
- Under Agents: document the primaryKbId field with the three-state PUT
semantics (omit / null / value) and example curl calls
- Under LLM Wiki: document GET /api/v1/wiki/knowledge-bases/bindable and
the explicit warning that PUT /api/v1/wiki/knowledge-bases/{id} no
longer processes the agentId field
This commit is contained in:
matevip
parent
69bea272dd
commit
0141b00270
@ -215,6 +215,41 @@ UI: `Agents → pick employee → Tools`.
|
||||
|
||||
Implementation details: see [MCP](./mcp#per-agent-tool-binding).
|
||||
|
||||
### Knowledge base binding (per-agent primary KB)
|
||||
|
||||
::: tip New in 1.5.0
|
||||
The employee editor has a new "Knowledge Base" tab where you can pick a **primary KB** for each employee. Knowledge bases stay workspace-shared — binding only declares "this is the one I default to," it doesn't restrict other employees' access.
|
||||
:::
|
||||
|
||||
**Short version: each employee can pick one knowledge base as their "primary KB" — the default they query. Or pick none.**
|
||||
|
||||
The model (worth reading once so it doesn't surprise you later):
|
||||
|
||||
- **Knowledge bases are workspace-shared.** A KB belongs to the workspace it was created in; every employee in that workspace can see it. Binding a KB to an employee does **not** make it exclusive — other employees can still use it
|
||||
- **The "primary KB" is just a default.** It tells the wiki tools (`wiki_search` / `wiki_read` / `wiki_backlinks` / ...): "when the caller doesn't specify `kbName` / `kbId`, use this one"
|
||||
- **Multiple employees can pick the same KB as primary.** They don't interfere — each one's binding is its own, the KB itself isn't mutated
|
||||
- **Not binding is fine.** With no primary set, the runtime falls back to the most-recently-updated KB in the workspace
|
||||
|
||||
UI: `Employees → pick employee → Edit → Knowledge Base`.
|
||||
|
||||
| Option | Behavior |
|
||||
|--------|----------|
|
||||
| **🚫 No primary KB** | Clear the binding; the next time the employee's wiki tools omit `kbName`, the runtime falls back to the workspace's most-recently-active KB |
|
||||
| **📚 <KB name>** | Set this KB as primary; wiki tools default to it. The row also shows the KB's page count |
|
||||
|
||||
Each row shows: icon, name, description, page count. The list is the **full set** of KBs in the current workspace — including ones already picked as primary by other employees.
|
||||
|
||||
#### How the runtime decides "which KB to read"
|
||||
|
||||
When an employee invokes a wiki tool, the resolution order is:
|
||||
|
||||
1. The tool call explicitly carried `kbName` / `kbId` — use that
|
||||
2. No explicit target → check the employee's `primaryKbId`; if it points to a workspace-visible KB, use that
|
||||
3. No `primaryKbId` either → pick the most-recently-updated KB from the workspace's visible set
|
||||
4. The workspace has zero KBs → tool returns empty, the LLM decides what to do next
|
||||
|
||||
Migration note: early versions persisted the binding on `mate_wiki_knowledge_base.agent_id` (one-to-one, exclusive semantics). Starting with the V130 migration, every legacy `kb.agent_id` is backfilled into the corresponding `agent.primary_kb_id`; the old column stays around as a read-only fallback, but new writes only touch `agent.primary_kb_id`. If you relied on `kb.agent_id` to isolate a KB to a specific agent, revisit those bindings in the editor — KBs are now visible to every employee in the workspace.
|
||||
|
||||
### System prompt best practices
|
||||
|
||||
The system prompt is the employee's voice, priorities, and constraints. **Role / Goal / Backstory**, skill instructions, and workspace memory all get automatically appended to the final prompt — you don't write those yourself.
|
||||
|
||||
@ -119,6 +119,40 @@ GET /api/v1/agents/templates # List templates
|
||||
POST /api/v1/agents/templates/{id} # Create from template
|
||||
```
|
||||
|
||||
### Field: `primaryKbId` (1.5.0+)
|
||||
|
||||
Every employee can declare a **primary knowledge base** to act as the default target for wiki tools. The field is typed `string | null` (Snowflake ID, always handled as a string on the frontend).
|
||||
|
||||
`PUT /api/v1/agents/{id}` is **three-state**:
|
||||
|
||||
| Request body has | Behavior |
|
||||
|------------------|----------|
|
||||
| no `primaryKbId` key | leave the current value unchanged |
|
||||
| `"primaryKbId": "<kbId>"` | set to the specified KB |
|
||||
| `"primaryKbId": null` | clear it (wiki tools then fall back to the workspace's default KB) |
|
||||
|
||||
The server distinguishes "field missing" from "explicit null" via `body.containsKey("primaryKbId")`; the entity carries `@TableField(updateStrategy = FieldStrategy.ALWAYS)` so a null actually reaches the database (MyBatis-Plus's default `NOT_NULL` strategy would otherwise silently skip it).
|
||||
|
||||
Design intent: **KBs are workspace-shared. `primaryKbId` only chooses the default target for *this* employee's wiki tools — it does not change KB ownership or visibility.** Multiple employees can pick the same KB as primary without interfering.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Set the primary KB
|
||||
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "X-Workspace-Id: 1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"primaryKbId": "2054907618529591298", ...other fields}'
|
||||
|
||||
# Clear it
|
||||
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "X-Workspace-Id: 1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"primaryKbId": null, ...other fields}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
@ -193,6 +227,28 @@ GET /api/v1/wiki/pages/{id}/backlinks # Backlinks
|
||||
|
||||
Agent-callable wiki tools (`wiki_search`, `wiki_read`, `wiki_backlinks`) resolve `kbId` automatically.
|
||||
|
||||
### Per-agent primary knowledge base (1.5.0+)
|
||||
|
||||
PR #237 / migration V130 introduced the per-employee "primary knowledge base" mechanism. New endpoint:
|
||||
|
||||
```
|
||||
GET /api/v1/wiki/knowledge-bases/bindable # List KBs in the current workspace that can be picked as primary
|
||||
```
|
||||
|
||||
This returns **every** KB in the workspace, including ones already picked as primary by other employees — the binding semantics are "which one do I default to," not "I own this one." The shape matches `GET /api/v1/wiki/knowledge-bases` (list-by-workspace); the dedicated name exists to be self-documenting in the UI.
|
||||
|
||||
The bind action itself **does not** go through the wiki API — it's written to the agent entity:
|
||||
|
||||
```
|
||||
PUT /api/v1/agents/{id} # body carries the primaryKbId field
|
||||
```
|
||||
|
||||
Field semantics and three-state behavior: see the [`primaryKbId` section under Agents](#field-primarykbid-150) above.
|
||||
|
||||
::: warning Legacy `kb.agentId` field
|
||||
Versions before 1.5.0 stored the binding on `mate_wiki_knowledge_base.agent_id` (one-to-one, exclusive). The V130 migration backfills those values into `agent.primary_kb_id`; the old column is kept as a read-only fallback — **`PUT /api/v1/wiki/knowledge-bases/{id}` no longer processes the `agentId` field** and silently ignores it if sent. New code should drive the binding only through `agent.primaryKbId`.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Multimodal
|
||||
|
||||
@ -215,6 +215,41 @@ UI 入口：`Agents → 选员工 → 工具`。
|
||||
|
||||
技术细节见 [MCP](./mcp#per-agent-工具绑定)。
|
||||
|
||||
### 知识库绑定（per-agent 主知识库）
|
||||
|
||||
::: tip 1.5.0 新增
|
||||
员工编辑器新增"知识库"标签页，可以为每个员工指定一个**主知识库**。知识库本身仍是工作空间共享资源，绑定只是声明"我默认查哪一个"——不影响其他员工的访问。
|
||||
:::
|
||||
|
||||
**简单版本：每个员工可以指定一个"主知识库"作为它默认查的 KB。可以不指定。**
|
||||
|
||||
要点（这是设计模型，看完省得困惑）：
|
||||
|
||||
- **知识库是工作空间共享的。** 一个 KB 创出来就归属当前 workspace，workspace 里所有员工都看得见。给员工"绑"一个 KB 不会把它变成专属——其他员工照样能调
|
||||
- **"主知识库"只是一个默认值。** 它告诉 wiki 工具（`wiki_search` / `wiki_read` / `wiki_backlinks` ...）："不显式说 `kbName` / `kbId` 时，默认去这个 KB"
|
||||
- **多个员工可以选同一个 KB 作主库。** 互不影响，谁切谁的，KB 本身不动
|
||||
- **不绑也行。** 没指定主库时，运行时按 workspace 里最近更新的 KB 兜底
|
||||
|
||||
UI 入口：`员工 → 选员工 → 编辑 → 知识库`。
|
||||
|
||||
| 选项 | 行为 |
|
||||
|------|------|
|
||||
| **🚫 未指定主库** | 清空绑定；下次员工的 wiki 工具不带 `kbName` 时，按 workspace 最近活跃 KB 回退 |
|
||||
| **📚 <KB 名>** | 设这个 KB 为主库；之后 wiki 工具默认查它，列表上同时显示页面数 |
|
||||
|
||||
每个 KB 行展示：图标、名字、描述、页面数。列表内容就是当前 workspace 里所有 KB 的完整集合（包括已被其他员工选作主库的）。
|
||||
|
||||
#### 运行时怎么解析"该读哪个 KB"
|
||||
|
||||
员工调 wiki 工具时，解析顺序如下：
|
||||
|
||||
1. 工具调用显式带了 `kbName` / `kbId`——直接用那个
|
||||
2. 没显式说 → 看员工的 `primaryKbId`，命中则用它
|
||||
3. `primaryKbId` 也没有 → 在 workspace 可见 KB 集合里取最近更新的那个
|
||||
4. workspace 一个 KB 都没有 → 工具返回空，员工 LLM 自己判断要不要换思路
|
||||
|
||||
迁移备注：早期版本的"绑定"是写在 `mate_wiki_knowledge_base.agent_id` 上的（一对一独占语义）。从 V130 迁移开始，所有老的 `kb.agent_id` 都被回填到 `agent.primary_kb_id`，老字段保留作 fallback 读取，但新的写入只走 `agent.primary_kb_id`。如果你之前依赖"KB 只给某个 agent 看"的隔离，请到员工管理面板重新审视一遍——KB 现在对 workspace 内全员可见。
|
||||
|
||||
### System Prompt 最佳实践
|
||||
|
||||
System prompt 是数字员工的声音、优先级、约束的来源。**角色 / 目标 / 背景故事**和技能指令、工作空间记忆系统会自动拼接到最终 prompt 里——这些部分你不用自己写。
|
||||
|
||||
@ -119,6 +119,40 @@ GET /api/v1/agents/templates # 列出模板
|
||||
POST /api/v1/agents/templates/{id} # 从模板创建
|
||||
```
|
||||
|
||||
### 字段：`primaryKbId`（1.5.0+）
|
||||
|
||||
每个员工可以指定一个**主知识库**作为 wiki 工具的默认目标。字段类型 `string | null`（雪花 ID，前端始终按字符串处理）。
|
||||
|
||||
`PUT /api/v1/agents/{id}` 的语义是**三态**的：
|
||||
|
||||
| 请求体里 | 行为 |
|
||||
|---------|------|
|
||||
| 不带 `primaryKbId` 这个字段 | 保留原值，不动 |
|
||||
| `"primaryKbId": "<kbId>"` | 设为指定 KB |
|
||||
| `"primaryKbId": null` | 清空（之后 wiki 工具按 workspace 默认 KB 回退） |
|
||||
|
||||
服务端用 `body.containsKey("primaryKbId")` 区分"字段缺失"和"显式 null"，entity 上配 `@TableField(updateStrategy = FieldStrategy.ALWAYS)` 保证 null 真的写到数据库（不会被 MyBatis-Plus 默认 `NOT_NULL` 策略静默跳过）。
|
||||
|
||||
设计语义：**KB 是工作空间共享的，`primaryKbId` 只决定该员工 wiki 工具的默认目标，不改变 KB 的归属或可见性。** 多个员工可以选同一个 KB 作主库，互不影响。
|
||||
|
||||
请求示例：
|
||||
|
||||
```bash
|
||||
# 设为某个 KB
|
||||
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "X-Workspace-Id: 1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"primaryKbId": "2054907618529591298", ...其余字段}'
|
||||
|
||||
# 清空绑定
|
||||
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "X-Workspace-Id: 1" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"primaryKbId": null, ...其余字段}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工具
|
||||
@ -193,6 +227,28 @@ GET /api/v1/wiki/pages/{id}/backlinks # 反向链接
|
||||
|
||||
Agent 可调的 wiki 工具（`wiki_search`、`wiki_read`、`wiki_backlinks`）自动解析 `kbId`。
|
||||
|
||||
### 员工绑定主知识库（1.5.0+）
|
||||
|
||||
PR #237 / V130 迁移引入了员工的"主知识库"机制。新的端点：
|
||||
|
||||
```
|
||||
GET /api/v1/wiki/knowledge-bases/bindable # 列当前 workspace 可绑定为主库的 KB
|
||||
```
|
||||
|
||||
返回的是当前 workspace 的**全部** KB（包含已被其他员工选作主库的），因为绑定语义是"我默认查哪一个"——不是独占。返回 shape 跟 `GET /api/v1/wiki/knowledge-bases`（按 workspace 列出）一致，单独命名只是为了在 UI 语义上更清晰。
|
||||
|
||||
绑定动作本身**不走** wiki 接口，而是写在员工实体上：
|
||||
|
||||
```
|
||||
PUT /api/v1/agents/{id} # body 里带 primaryKbId 字段
|
||||
```
|
||||
|
||||
字段语义、三态行为见上面 [Agent 段的 `primaryKbId` 说明](#字段-primarykbid150)。
|
||||
|
||||
::: warning 旧字段 `kb.agentId` 的去留
|
||||
1.5.0 之前的版本曾把绑定关系写在 `mate_wiki_knowledge_base.agent_id` 上（一对一独占）。V130 迁移把旧值回填到了 `agent.primary_kb_id`，老字段保留作 fallback 读取——**`PUT /api/v1/wiki/knowledge-bases/{id}` 不再处理 `agentId` 字段**，传上去会被忽略。新代码请只通过 `agent.primaryKbId` 控制绑定。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 多模态
|
||||
|
||||
Loading…
Reference in New Issue
Block a user