Product handbook

Purpose of this document: Explain, in language people can understand, how to create agents, build and maintain a knowledge base, and embed and use the assistant from a third-party system, and point to the specification and contract originals in the repo.

Source of truth: Product capabilities and flows follow the wording in the header of docs/产品规格.md; embedding follows sdk/host-embed/SDK契约.md; knowledge-index generation follows docs/core-mechanisms/AI重建知识索引规则.md.

Implementation detail: API paths, field names, and runtime directories appear only in parentheses or in a dedicated subsection when needed; the main text does not replace user-visible copy.

---

1. Who this handbook is for

This edition is mainly for company admins / ops and host-system developers / architects. Suggested reading:

---

2. How to create an agent

2.1 Three ideas to start with

• Workspace: the bound of your team’s collaboration. Before many agent- and conversation-related capabilities, you usually pick the current workspace first (this is not the same idea as “each agent instance’s own file directory at runtime”, which is an implementation phrase).
• User agent (“My agents”): an assistant instance you (and workspace policy) use, which can bind description and preferences, a knowledge base, and skills/tools. When talking, you choose the agent — or pass binding information — so the assistant answers as that instance.
• Market templates (if enabled): reusable templates published by others or the platform; you create your own copy from a template, then rename it, change the description, swap the knowledge base, and so on.

2.2 Ways to create (product flow)

Current environment (premise for this edition): the Agent market is not yet the public main path; day to day you build agents yourself. If the market goes live later, operations notes for “create from a template” can be added.

1. Create a blank / self-built agent (current main path)

- In My agents (or the equivalent entry) choose New → fill in a name and a basic description → save. - Then as needed: upload or write a knowledge base, bind workspace knowledge, configure skills (follow the current product UI).

1. Create from the market (if it is open to you)

- In the Agent market, pick a template → follow the prompts to create your instance. - After creation, keep editing description, knowledge, tools, and so on in My agents.

1. How binding works in conversation

- New conversation: you need to select (or implicitly bind) which agent to use. When you change assistants, the product rule is generally to start a new conversation and pick another, rather than switching inside the same conversation without a prompt (see 产品规格.md §7.4.5). - Embed: the host’s init parameters fix one agent-instance identifier (see §4).

2.3 Mapping to backend interfaces (for integration or scripts)

The REST summary in the specification is in 产品规格.md §7.3–7.4: list/create/update user agents, create an instance from a template, trigger training jobs, and so on. Actual paths and request bodies follow the current deployment’s OpenAPI / backend; this handbook does not copy fields one by one, to avoid drifting from the version.

---

3. Knowledge base: how to build and maintain it

Host-page embed: Markdown written by the business for an embedded agent is also covered in Host knowledge-document writing requirements (user-facing language, feature-navigation action table, checklist).

3.0 Who does what (this company, this edition)

3.1 Three layers of knowledge (how people talk about it)

The product calls structured knowledge files that agents retrieve a knowledge base, in three layers (产品规格.md §3.2.1):

When maintaining: after you add, change, or delete documents at a layer, if the system uses a retrieval index, refresh the index per §3.3 (or wait for the product/job’s automatic rebuild policy).

3.2 One agent’s “knowledge base” (Markdown + index)

Each user agent can have its own knowledge tree (on disk this lives under the service’s runtime directory; to people you can say “maintain it in that agent’s knowledge management”):

1. What to put: mainly Markdown (.md); content should be instructions, processes, interface conventions, and similar that the assistant can cite when answering.
2. Directory layout (recommended)

- Several .md files can sit directly at the root. - You can also make subfolders by top-level topic, with several .md files in each (easier to split work and retrieve).

1. Two-level index (for the system)

- Root index.json: an overview of “which documents sit at the root, which top-level topic folders exist”, plus summaries and keywords. - index.json inside each top-level topic folder: lists paths and summaries of documents under that topic. - Rule detail (allowlist, no .. in paths, generate root then subfolders, and so on) is in AI重建知识索引规则.md.

How to say it to users: after you change documents, run “regenerate the index with AI” (or a full rebuild); otherwise conversation may still pick articles from the old index and miss new content.

3.3 Refresh the index (maintenance flow)

1. Edit, upload, or delete .md files; keep UTF-8 and sensible paths.
2. Use the product’s “rebuild knowledge index” capability (or a background job). Step-by-step interface examples related to implementation (preview → root index → each topic sub-index → one-shot) are in the “step-by-step generation and progress” table at the end of AI重建知识索引规则.md; HTTP paths hang on routes such as /api/v1/user-agents/{id}/knowledge/reindex... (follow current routing).
3. On failure, use the returned explanation: whether a model is configured, whether the disk path is readable, whether a .md file is damaged, and so on.

3.4 How this works with workspace and global knowledge

• An agent’s private .md + index: closest to that assistant’s work; suited to a role-specific voice.
• Workspace knowledge: suited to several people building together and several agents sharing; upload/authorize in the product at workspace scope.
• Global help: operations configures the mount directory and root index file (see §3.5); it mainly serves the help assistant when no workspace is selected.

3.5 Operations: global help-document directory (implementation names)

When deploying Cadau you can point the help-side static document root and index filename with environment variables, for example:

• HELP_DOCS_DIR: global help-document root (default help)
• HELP_DOCS_INDEX_FILE: root index filename (default index.json)

The exact load logic is in backend/internal/config. These are ops / integration terms; to end users you can simply say that site-wide help knowledge is mounted on the server.

---

4. How a third party embeds “My agents”

4.1 Who does what

Full fields, TypeScript types, action allowlist, error codes, and sequence are in sdk/host-embed/SDK契约.md (required reading). Deliverable integration notes (including init examples, feature navigation, server-side token minting) are in sdk/host-embed/网站集成说明.md; how to write host-side knowledge documents is in sdk/host-embed/宿主知识文档撰写要求.md.

Auth (recommended, for host architecture): after the user signs in to the host, the host backend exchanges with Cadau (or a Cadau-recognized issuer) for a short-lived embed token, then hands token and expires_at to frontend init; the browser does not hold a long-lived secret. Prototypes may inject environment variables as in the examples; before production, converge on backend ticket exchange. If you have a sequence diagram or internal wiki, add a title + link in §6 “Further reading” below; do not paste secrets or full claims in the handbook body.

4.2 Minimum frontend steps

1. Include the script:

https://<mindlink-domain>/embed/mindlink-widget.min.js

1. After signing in to the host and obtaining a short-lived token, run:

window.MindLinkWidget.init({ base_url, user_agent_id, auth: { token }, host_actor?, app_id?, api_base_url?, workspace_id?, theme?, position?, locale?, entry? }) Path A needs only base_url + user_agent_id + auth.token at minimum. Path B must pass host_actor (the signed-in user’s identity). entry.auto_execute_navigation defaults to true: when the user clearly says “open … for me”, the first mindlink://action/ navigation runs automatically after the reply (the host must implement an action allowlist).

1. When the token is about to expire: the host refreshes it and calls updateAuth; when the signed-in user changes, call updateHostActor (see WidgetHostApi in the contract).

4.3 Theme and position aligned with the host page

• theme: light | dark | auto.
• auto: follow the host page’s <html data-theme="dark|light"> first, then the .dark class on html/body, then the system prefers-color-scheme (see sdk/host-embed/SDK契约.md §6.2).
• position: bottom-right (default), bottom-left, middle-right (vertically centered on the right), center (middle of the page), inline (needs a container).

4.4 Example: HR multi-tenant workbench (in the repo)

• Embed BFF and assignment: examples/hr-multi-tenant/docs/嵌入智能体接入指南.md (embed-session, server-side token minting, user↔agent assignment).
• Host knowledge documents (Chinese articles): examples/hr-multi-tenant/docs/宿主知识文档/导读.md.
• Dev-time environment-variable injection: examples/hr-multi-tenant/web/README.md. Do not commit a .env with real tokens to a public repo.

4.5 Integration and security checks (summary)

Embed contract §8 integration checklist, §9 error codes; product design bounds: do not run arbitrary script on the embed side, do not hold a long-lived secret, and actions are limited to allowlisted types such as open_url / open_module / emit_event.

---

5. Using the product (everyday members)

1. Sign in: mobile number or email + password or verification code (产品规格.md §1.5.2).
2. Pick a workspace (if the account is in several teams): the current workspace decides which workspace knowledge, collaboration resources, and so on you see.
3. Chat: start or continue a conversation; pick an agent before asking when you need to.
4. Action assistant (on the main site): a floating help entry in workspace scenes (exact copy and capabilities follow the UI; mechanism in 产品规格.md §4.1.5 and 工作区帮助快捷一句.md).
5. Human support: after you enable human support for an agent (a local seat or an authorized support team), people can tap “Human support” in conversation; support colleagues take tickets at the support desk (see 人工客服.md, help/product-features/human-customer-service.md).
6. Embedded assistant: use the §4 component on a third-party page; the conversation and token are independent of the main-site Web, but talk still goes through the Cadau backend.

---

6. Further reading (when maintaining this handbook)

---

7. Premises of this edition (confirmed with readers)

---

*Version: 1.3 (aligned with repo docs; embedding follows sdk/host-embed/SDK契约.md V1.5.10 and sdk/host-embed/网站集成说明.md. Interfaces and UI follow the deployed instance. §7 is a snapshot of agreements; revise it when they change.)*