Yuque | Alephant Documentation

The Yuque connector brings approved Yuque knowledge-base pages and optional attachments into AIvis retrieval. It is scoped by repository path and reads only repositories explicitly entered by an administrator.

Use cases

Scenario	Recommendation
Product documentation Q&A	Create one connector per product knowledge base.
Project wiki retrieval	Use separate connectors and document sets per project space.
Engineering policy lookup	Sync only published policy documents intended for the target audience.
Attachment retrieval	Enable attachments only when files are approved and parseable.
Mixed-permission spaces	Split repositories or connectors by audience.

What it indexes

Yuque data	Indexing behavior
Pages	Reads document lists and details, converts HTML bodies to searchable text, and stores title, updated time, and source link.
Hierarchy nodes	Emits each page as a page node so search results identify the source.
Attachments	Optional child documents under their parent Yuque pages.

The connector accepts 1 to 100 unique repositories in namespace/slug format. It does not index unlisted repositories, team membership, comments, collaboration history, drafts, trash, export packages, or space-level analytics.

Prerequisites

Prepare a Yuque token that can read the target repositories.
Collect repository paths such as acme/product-handbook from Yuque URLs.
Confirm the token account can read document details and attachment download URLs.
Decide whether attachments should be indexed.
Decide the AIvis access group before indexing private content.
Allow the AIvis backend to reach www.yuque.com.

Where to get configuration values

Configuration value	Where to get it
Yuque token	Sign in to Yuque and create a dedicated token from the Token settings page. Grant only the permissions needed for indexing.
Repository path `namespace/slug`	Open the target repository and take `{namespace}/{slug}` from `https://www.yuque.com/{namespace}/{slug}`. You can also use the Yuque developer documentation to verify repository / docs API path parameters.
Document detail and attachment readability	Use the same token against Yuque document-detail APIs, or open the target document in Yuque, to confirm the token owner can read the body and attachment download URLs.

Configure in AIvis

In the Admin panel, open Connectors, select Yuque, create or choose a Yuque credential, and then enter repository paths and the attachment switch.

Field	How to fill it	Notes
Yuque token	Paste a dedicated token	Used for Yuque API access.
Yuque repositories	One `namespace/slug` per line, such as `acme/product-handbook`	Only listed repositories are indexed.
Include attachments	Enabled by default	Reads parseable attachments found in document details.

Do not enter a full URL, profile URL, or namespace-only value. Each repository path must contain both namespace and repository slug.

Sync behavior

The standard Admin-created Yuque connector runs as a polling connector with checkpoint resume.

Stage	Behavior
Document list	Reads summaries for each configured repository and builds a stable inventory.
Document detail	Fetches each page detail and converts HTML body content into searchable text.
Attachments	Emits attachments as child documents; each page is capped at 1000 attachments.
Incremental window	Pages outside the sync updated-time window are skipped.

Attachment URLs must be safe HTTPS URLs. Documents or attachments that cannot be processed are recorded as item failures.

Permissions

The Yuque token determines what AIvis can ingest, but this connector does not synchronize Yuque organizations, teams, repository members, or per-page permissions into AIvis.

AIvis access setting	Meaning
Private groups	Only selected AIvis groups can search documents produced by this connector. Recommended for internal repositories.
Public	Every eligible AIvis user can search indexed content. Use only for repositories that can be shared with that audience.
Auto permission sync	Yuque is not supported for this mode.

Use AIvis Private groups for internal repositories. Use Public only when every eligible AIvis user may search every indexed page and attachment. Yuque is not available as an auto permission-sync source.

Verify

Create a connector with one test repository.
Search known page titles, body keywords, and source links.
If attachments are enabled, upload a small parseable attachment and confirm it is searchable.
Search unlisted repositories or private pages and confirm they are absent.
Test assigned and outside AIvis users.
Modify a test page and confirm the next sync updates it.

Troubleshooting

Symptom	What to check
Authentication fails	Token value, expiration, and revocation state.
Repository validation fails	Repository path must be `namespace/slug` and readable by the token account.
Pages are empty or missing	Check that the page is in the configured repository, within the sync window, and readable via detail API.
Attachments are missing	Check the attachment switch, download URL reachability, file type, and size.
Users can search content they should not see	Restrict AIvis access groups or split connectors by repository/audience.

Security and maintenance

Use a dedicated Yuque token instead of a broad personal token.
Review repository list, attachment switch, token owner, and AIvis groups regularly.
Rotate or revoke the token if it may have leaked.
Update and revalidate the connector after repository moves, renames, or permission changes.
Disable the connector before revoking unused tokens.

Official references

Yuque developer documentation