System knowledge base and retrieval index

Audience: platform admins (admin console System knowledge base workspace).

What you maintain

• Body: Markdown under help/ (new-user guide, product capabilities, admin operations). English UI prefers help/en/ when that tree’s index.json exists.
• Index: each layer’s index.json (root + each theme subfolder), so the help agent picks a topic, then reads the body.

After changing Markdown, tap Generate index with AI (or Force regenerate). Without a rebuilt index, the help agent may still answer from old summaries.

Cadau’s interface can be Chinese or English. The help agent answers in the user’s interface language.

What the index contains

Each document in the index usually has:

Two layers: root index.json lists theme folders; each theme folder has its own index.json listing articles in that theme.

Optional: load only for a scene (paths)

If an article is needed only in certain scenes (e.g. “frontend component conventions” only when discussing .tsx files), you can add optional paths on the index entry:

{
  "id": "frontend-rules",
  "title": "Frontend component conventions",
  "path": "guides/frontend-rules.md",
  "summary": "React component naming, Tailwind usage",
  "tags": ["frontend", "React"],
  "paths": ["**/*.tsx", "**/*.jsx"]
}

Meaning (user-facing):

• No paths: general notes; chat still matches by question keywords, as before.
• With paths: inject that article only when the user’s message mentions a related file path, or an attachment filename hits the glob — so unrelated scenes do not fill context.
• New-user intros, account notes, three-layer knowledge split, and other everyone-reads material: do not fill paths.

When using Generate index with AI, the model may suggest paths for conditional docs; you can also hand-edit that theme’s index.json after generate.

Admin console steps

1. Sign in to the admin console → System knowledge base (/system-knowledge).
2. Pick a folder in the left tree, a file in the middle list, edit Markdown on the right.
3. After a batch of body edits → Generate index with AI (server LLM must be configured).
4. If index summaries/tags are clearly wrong, or you just upgraded index rules → Force regenerate.

Writes and reindex are recorded in the admin audit log.

Common questions

Help agent still answers old content? Confirm the index was rebuilt, and the help-docs directory in deploy config points at the current help/ (English: help/en/ when present).

A “frontend conventions” article is never cited? If that index entry has paths, it will not inject when the user did not attach .tsx or mention a related path in the message — expected. Remove paths for general material.

Relation to workspace / agent knowledge? This section is system layer only (help agent). Team material is maintained in Workspace collaboration; personal material in My agents → Knowledge base. Three-layer split: Three layers of the knowledge base.

Details

• Index generation rules (implementation): repo docs/core-mechanisms/AI重建知识索引规则.md
• How chat picks knowledge: repo docs/core-mechanisms/智能体调用知识文档的方式.md

---

Checklist after a release or help change

After updating help/ body or index rules in test / production, run in order (about 5–10 minutes):

Before

• [ ] Backend LLM is configured (same as main-site chat, e.g. OPENAI_API_KEY); admin console Generate index with AI is usable, not “AI service not configured”.
• [ ] Confirm help_docs.dir / HELP_DOCS_DIR points at this deploy’s help/ (wrong directory means the help agent reads old files). English answers need help/en/index.json.

Rebuild the index

• [ ] Sign in to the admin console → open System knowledge base (/system-knowledge).
• [ ] (Optional) Browse the left tree before Generate index with AI and confirm new .md files are visible on disk.
• [ ] Tap Force regenerate (or ordinary Generate index with AI if preview says “documents changed”).
• [ ] Wait for progress; the page top shows “Index generated:…”; note whether it includes index.json and each theme subfolder’s index.json.
• [ ] If you only changed one theme folder (e.g. admin-ops/), at least refresh root index.json and that theme’s admin-ops/index.json (force rebuild does both).

Spot-check index content

• [ ] In the editor open admin-ops/index.json (or another changed theme sub-index); confirm new articles are in documents with non-empty summary / tags.
• [ ] If you used paths, confirm glob spelling (e.g. /*.tsx); general intro entries have no** paths.

Verify the help agent

• [ ] On the main site with no workspace selected (or pick the help agent in Messages), start a new conversation.
• [ ] Ask natural language close to what you just updated, e.g. “what are system knowledge index paths”, “how does an admin rebuild the help index”.
• [ ] The answer should cite points from the new summary; if it still looks like the old version, Force regenerate again and confirm the help_docs directory.
• [ ] (Optional) Ask a question that includes a .tsx filename and confirm a paths-gated article is cited only in related scenes (no path → do not force-feed frontend conventions).

Wrap-up

• [ ] In admin console Audit / Overview (if present) confirm events like admin.system_knowledge.reindex.
• [ ] Send this release note to ops: which help themes changed, whether new paths rules are involved.

When to use Force instead of ordinary generate? Just merged code, hand-edited index.json, or preview still says “documents unchanged” but you know summaries/tags are stale → Force regenerate.