xiuxian-artisan-workshop

May 21, 2026 · View on GitHub

xiuxian-artisan-workshop is a Rust-first monorepo for native agent infrastructure. It brings together knowledge and retrieval (Wendao), workflow and control-plane execution (Qianji), context and persona rendering (Qianhuan), memory, vector/search, storage, and thin Python consumer packages. Telegram and Discord bot runtime ownership has moved to the external lingchong-bot repository.

This README is the repository entry map. Detailed contracts live in package READMEs, RFCs, and the documentation index.

Current Architecture

flowchart TB
    Operators["Operators, agents, CLIs"]
    Zhenfa["xiuxian-zhenfa<br/>native tool and routing substrate"]
    Qianji["xiuxian-qianji<br/>workflow, Flowhub, BPMN control"]
    Qianhuan["xiuxian-qianhuan<br/>context and persona rendering"]
    Wendao["xiuxian-wendao<br/>knowledge/search/gateway domain"]
    WendaoCore["xiuxian-wendao-core<br/>stable shared contracts"]
    WendaoRuntime["xiuxian-wendao-runtime<br/>config, transport, Arrow Flight host runtime"]
    WendaoSql["xiuxian-wendao-sql<br/>bounded SQL helpers"]
    WendaoJulia["xiuxian-wendao-julia<br/>Julia and Modelica repo-intelligence bridge"]
    Storage["vector, Lance, DataFusion, DuckDB, Valkey<br/>retrieval and runtime storage substrate"]
    Python["packages/python<br/>thin Arrow consumers and workflow contracts"]

    Operators --> Qianji
    Operators --> Zhenfa
    Operators --> Wendao
    Qianji --> Qianhuan
    Qianji --> Wendao
    Wendao --> WendaoCore
    Wendao --> WendaoRuntime
    Wendao --> WendaoSql
    Wendao --> WendaoJulia
    Wendao --> Storage
    Python --> WendaoRuntime

The current repository is not organized around the old "Trinity" narrative. The practical boundary is package ownership:

Rust is the source of truth for execution, routing, retrieval, indexing, transport, server/runtime configuration, and persistent contracts.
Python is a utility and consumer layer for Arrow Flight access, workflow payload contracts, adapter tests, and analysis helpers. It is not a second runtime kernel.
Wendao is split into contract, runtime, and domain packages so shared DTOs do not accumulate host behavior or deployment-specific concerns.
Bot runtimes reach Wendao through gateway/client contracts from the external lingchong-bot repository rather than embedding Wendao business logic in-process.
Julia and Modelica repo-intelligence integration is owned by xiuxian-wendao-julia, with Rust gateway code consuming the managed service boundary.

Primary Package Groups

Area	Package surfaces	Responsibility
Knowledge and retrieval	`xiuxian-wendao`, `xiuxian-wendao-core`, `xiuxian-wendao-runtime`, `xiuxian-wendao-sql`, `xiuxian-wendao-julia`, `xiuxian-wendao-client`	Wendao domain logic, stable shared contracts, host/runtime behavior, bounded SQL helpers, Julia/Modelica repo intelligence, and local CLI surfaces.
Workflow and orchestration	`xiuxian-qianji`, `qianji-bpmn-engine`, `xiuxian-qianhuan`	Flowhub and BPMN control, workflow validation, persona/context rendering, and execution-facing contract assembly.
Agent and tool runtime	`xiuxian-zhenfa`, `xiuxian-llm`, `xiuxian-security`, `xiuxian-sandbox`	Native tool routing, LLM orchestration, execution plumbing, and sandbox/security surfaces. Bot/channel runtime lives in `lingchong-bot`.
Data and memory substrate	`xiuxian-vector`, `xiuxian-lance`, `xiuxian-db-store`, `xiuxian-memory-engine`, `xiuxian-memory`	Vector retrieval, Lance-backed search, database storage helpers, episodic memory, and memory-facing runtime contracts.
Repository and parser substrate	`xiuxian-git-repo`, `xiuxian-wendao-parsers`, `xiuxian-ast`	Git/repository access, parser ownership, AST tooling, and syntax-aware project-policy gates.
Python adapters	`packages/python`	Thin Arrow, workflow-contract, analyzer, and compatibility packages around Rust-owned contracts.

The root Cargo.toml is the canonical Rust workspace manifest. The package-level READMEs describe package ownership more precisely than this entry map.

Where To Start

docs/index.md: top-level documentation index.
docs/rfcs/: durable architecture and governance decisions.
packages/rust/README.md: Rust workspace index.
packages/python/README.md: Python package boundary and adapter policy.
packages/rust/crates/xiuxian-wendao/docs/06_roadmap/417_wendao_package_boundary_matrix.md: Wendao package-boundary matrix.
docs/testing/README.md: test and validation documentation.
AGENTS.md: repository engineering protocol for agents and automated contributors.

Development

Use the project environment for repository-scoped commands:

direnv allow
direnv exec . scripts/rust/cargo_exec.sh fmt --all --check
direnv exec . scripts/rust/cargo_exec.sh nextest run --workspace --exclude xiuxian-core-rs --no-fail-fast
direnv exec . bash scripts/rust/test_xiuxian_core_rs.sh --lib --no-fail-fast

Common focused checks:

direnv exec . scripts/rust/cargo_exec.sh nextest run -p xiuxian-wendao --lib
direnv exec . scripts/rust/cargo_exec.sh clippy -p xiuxian-wendao-runtime --tests --features transport -- -D warnings
direnv exec . uv run pytest

The GitHub Actions baseline follows the same shape: Rust formatting, workspace clippy with warnings denied, process-managed Wendao service probes, workspace cargo nextest, and the PyO3 bridge library test lane.

Documentation Rules

Canonical repository docs should describe stable package, RFC, and README surfaces. Do not link canonical docs to transient runtime, cache, or local data directories. Use package README files and RFCs for durable architecture contracts; use local tracking files only for active execution state.

When package boundaries change, update this README only as the entry map. The owning package README or RFC should hold the detailed contract.