AutoRAG Agent工作流

System Prerequisites

• No Java required: Document parsing (HWP/HWPX/HWPML, PDF, DOCX, XLSX/XLS) runs in-process through kordoc.
• Rust Toolchain (Optional): Automatically compiles Jikji (jikji-cli) if installed.
• MinSync: Automatically downloaded and installed into <workspace>/.autorag/bin on first run.
• Everything (Windows only, bundled): The package ships the portable Everything 1.4.1.1032 and its ES 1.1.0.38 CLI (x64 and ARM64, SHA-256 pinned). On Windows, AutoRAG extracts them into <workspace>/.autorag/everything/ and runs a private, user-level instance that indexes only your configured search roots: no administrator rights, no Everything service, no whole-drive scan, no HTTP/ETP server, and no change to any Everything you already run. Set "everything": false in the config to turn it off. macOS and Linux are not affected.
• filee-cli (file conversion, automatic): autorag setup and the TUI download the pinned filee-cli release (~85 MB, SHA-256 verified) into <AUTORAG_HOME>/tools/filee-cli/<version>/, so the agent can convert between 255 formats offline with convert_files. A filee/filee-cli already on PATH is used instead. Set "filee": { "autoInstall": false } to forbid the download or "filee": { "enabled": false } to remove the tools. Filee fetches its own engines (FFmpeg, Pandoc, LibreOffice, calibre, Ghostscript; hundreds of MB, only when a conversion needs one) on first use.
• FSearch (macOS/Linux only, separate install): Install fsearch-cli yourself (e.g. brew install NomaDamas/fsearch-mac/fsearch-mac (installs the fsearch-cli binary); GPL-2.0, spawned as a separate process, never bundled or linked). On macOS and Linux, AutoRAG builds a per-workspace database at <workspace>/.autorag/fsearch/ indexing only your configured search roots, and keeps a fsearch-cli watch daemon live (FSEvents/inotify) for sub-second name search. It never touches the FSearch app's own database. Without fsearch-cli, name search falls back to a slow bounded filesystem walk. Set "fsearch": false in the config to turn it off. Windows is not affected (Everything covers it).

---

Installation & Setup

AutoRAG Agent is published as @autorag/librarian (requires Node.js ≥ 24 or Bun):

```bash

Install CLI globally

bun install -g @autorag/librarian

Index documents (parses PDFs/Markdown, builds BM25 and MinSync vectors)

autorag refresh

🤖 For AI Agents & LLMs: Setup & Skills

If you are an AI coding agent or LLM (Claude Code, Cursor, Windsurf, Codex, Senpi, Pi, etc.) tasked with installing, configuring, or querying AutoRAG Agent, use our built-in skills located in the skills/ directory:

Install the skills into your coding agent

Skills are not auto-discovered — copy only the setup skill when an agent needs to bootstrap AutoRAG. Routine AutoRAG Lite retrieval is provided by MCP tools, not by a autorag-lite-search skill or shell command.

```bash

From a global install — the npm package ships the same skills/ folder

AUTORAG_SKILLS="$(npm root -g)/@autorag/librarian/skills"

Bun global installs live at ~/.bun/install/global/node_modules/@autorag/librarian/skills

mkdir -p .claude/skills cp -R "$AUTORAG_SKILLS/autorag-lite-setup" .claude/skills/ ```

Run the setup skill once to register the stdio server with the host. Reload the agent, then discover the actual tool names and schemas with MCP tools/list. The normal Lite path is autorag.status → autorag.refresh when needed → autorag.search; use autorag.report and autorag.evidence for the optional curation lifecycle. Copy skills/autorag and skills/autorag-setup only when the agent should also drive the model-backed librarian, and skills/autorag-doctor for diagnostics. Other agents read their own skill directories; copy the same setup folder there and reload the agent session so it picks up the MCP registration instructions. Do not copy or retain the removed autorag-lite-search skill. The package also ships internal-skills/, which holds the librarian's own turn rules (for example internal-skills/organize/) — those are never parent-agent skills, so do not copy them into another agent.

Quick Start

3. Programmatic Usage (TypeScript API)

import { AutoRAGAgent } from "@autorag/librarian";

// Initialize librarian agent
const agent = new AutoRAGAgent({
  searchPaths: ["/path/to/documents"],
});

// Run curated search loop
const response = await agent.searchDocuments("Summarize recent compliance updates");

console.log("Answer:", response.answer);
for (const result of response.results) {
  console.log(`[${result.number}] ${result.title} (${result.source})`);
  console.log(`    ${result.summary}`);
}

A caller can steer a search while it runs, the way Enter steers a TUI search, and stop it:

const run = (async () => {
  for await (const event of agent.searchDocumentsStream("When is the launch?")) {
    if (event.type === "preliminary") console.log("Quick:", event.response.answer);
    if (event.type === "complete") console.log("Final:", event.response.answer);
  }
})();

// A correction of the running search, not a new question. false = no search to steer.
agent.steer("Use the June plan, not the April one.");
// agent.abort() stops the whole search, including every later phase.
await run;

steer() reaches the search's next model request (also between phases), cuts in-flight retrieval and the baseline prefetch short, and always runs verification, whose prompt restates the correction. It returns false when no search is running, the search was stopped, or it is past its last model request; ask the text as a new question then.

A refresh can be cancelled and observed from code:

const controller = new AbortController();
try {
  await agent.refresh(false, {
    signal: controller.signal, // controller.abort() stops it
    onProgress: ({ phase, processed, total, currentVirtualPath }) => {
      console.log(`${phase} ${processed}/${total}`, currentVirtualPath ?? "");
    },
  });
} catch (error) {
  if (controller.signal.aborted) console.log("refresh cancelled");
  else throw error;
}

signal is checked between files and between phases, kills an in-flight parse worker, and terminates the MinSync, Jikji and datasource child processes (and their descendants). The refresh then rejects with the signal's reason and is recorded as failed; files already mirrored are kept and not re-parsed on the next run. onProgress reports parsed (processed/total are files, currentVirtualPath is the file about to be processed) and datasources (processed/total are datasource skills). During the parse phase .autorag/refresh-progress.json also carries the running sourceFiles.total and parsedCounts, refreshed every 25 files rather than per file. The marker is replaced with a retried rename (an in-place overwrite if a reader keeps the destination held, as on Windows). Without these options a refresh behaves as before.

---

Initialize configuration for your documents folder

autorag init --search-paths ~/Documents/research

Perform a curated search (uses your configured reasoning model)

autorag search "What are our primary Q3 deliverables?"

CLI Command Reference

---

Quick Agent Workflow

1. Install CLI:

   command -v autorag >/dev/null || bun install -g @autorag/librarian
   

   autorag status --json        # check corpus freshness and index readiness
   autorag duplicates --json    # scan for exact or near-duplicate document families
   

   autorag search "your question" --json
   

---

Troubleshooting

When search returns nothing, a datasource disappears from results, refresh hangs, or the embedder is unavailable, run the autorag-doctor agent skill (skills/autorag-doctor/SKILL.md). Point your coding agent at it and say "check AutoRAG" — it walks the full diagnose-and-repair procedure and ends with a per-datasource status table showing what is indexed and what actually returns hits.

The first three commands cover most of it:

autorag status --json          # freshness, per-component state, diagnostics
autorag health --json          # model resolution + one live completion probe
autorag setup                   # resolves the embedding backend and reports it

Indexing is not the same thing as searchability, so always confirm retrieval itself through the connected Lite MCP server:

autorag.status {}
autorag.refresh {}
autorag.search {"query":"a word that certainly appears","topK":3}
autorag.search {"query":"recent topic","scope":"/discord/local/**","topK":3}

The CLI equivalents remain available for terminal repair, but do not use them as the agent's normal Lite search path.

Common failures and their fix:

Native datasource stores stay owned by their CLIs — AutoRAG never rebuilds them. Fix a broken archive with lazykatok doctor, discrawl --json metadata, slacrawl --json doctor, wacrawl --json doctor, telecrawl --json doctor, notcrawl doctor, or mailcrawl doctor, then re-run autorag refresh --method datasources --json.

---