diff --git a/mateclaw-server/src/main/resources/docs/en/agents.md b/mateclaw-server/src/main/resources/docs/en/agents.md index 93f847e4..f785ee94 100644 --- a/mateclaw-server/src/main/resources/docs/en/agents.md +++ b/mateclaw-server/src/main/resources/docs/en/agents.md @@ -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. diff --git a/mateclaw-server/src/main/resources/docs/en/api.md b/mateclaw-server/src/main/resources/docs/en/api.md index 8bd22fad..576e8082 100644 --- a/mateclaw-server/src/main/resources/docs/en/api.md +++ b/mateclaw-server/src/main/resources/docs/en/api.md @@ -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": ""` | 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 diff --git a/mateclaw-server/src/main/resources/docs/zh/agents.md b/mateclaw-server/src/main/resources/docs/zh/agents.md index a2feb22c..d880e9bf 100644 --- a/mateclaw-server/src/main/resources/docs/zh/agents.md +++ b/mateclaw-server/src/main/resources/docs/zh/agents.md @@ -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 里——这些部分你不用自己写。 diff --git a/mateclaw-server/src/main/resources/docs/zh/api.md b/mateclaw-server/src/main/resources/docs/zh/api.md index f67c6c76..1ce7b953 100644 --- a/mateclaw-server/src/main/resources/docs/zh/api.md +++ b/mateclaw-server/src/main/resources/docs/zh/api.md @@ -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": ""` | 设为指定 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` 控制绑定。 +::: + --- ## 多模态