dshbox/cordis-rs
Runtime-agnostic Rust port of Cordis, the plugin framework at the core of DeepSeek Harness — scoped dependency injection, lifecycle-owned effects, events, structured logging. Zero dependencies.
安装Install
dsh plugin --profile web add github:dshbox/cordis-rs把 dshbox/cordis-rs 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
cordis-rs
English | 简体中文
A runtime-agnostic Rust port of Cordis 4.x — the plugin framework at the core of DeepSeek Harness, vendored there as @deepseek-ai/cordis.
This implementation is based on Cordis 4.0.1 from DeepSeek Harness. Its core structure mirrors the original
Context / Events / Fiber / Logger / Reflect / Registry / Servicemodules and preserves automatic activation when dependencies arrive, automatic unloading when dependencies disappear, scoped isolation, effect cleanup, and all five event dispatch modes as closely as Rust allows.
Cordis is a context-based plugin framework for applications that need explicit dependency injection, scoped services, lifecycle-managed cleanup, structured events, and configuration-driven plugins. cordis-rs preserves that model while replacing JavaScript-only mechanisms (Proxy, prototype inheritance, callable objects, decorators, and any) with explicit Rust APIs, Arc, and checked downcasts.
Status
Rapid development. This project is pre-1.0 and iterates quickly: public APIs, crate boundaries, and naming may change between releases (while the crates are 0.x, breaking changes land as minor bumps). Do not use it in production systems yet.
The crate currently ports the complete core runtime:
| TypeScript Cordis | Rust API | Status |
|---|---|---|
new Context() / extend() |
Context::new() / extend() |
✅ |
isolate() and shared labels |
isolate() / isolate_with() |
✅ |
intercept() |
intercept() / intercepts() |
✅ |
Proxy-backed get/set/provide |
typed get/require/set/provide |
✅ |
| Accessor and mixin reflection | accessor() and explicit alias() |
✅¹ |
| Function/object/class plugins | Plugin, plugin_sync, plugin_async, service adapters |
✅ |
inject dependency epochs |
Inject and automatic unload/reload |
✅ |
FiberState, try_wait, restart, update, dispose |
same lifecycle operations | ✅ |
| Sync/async/generator effects | sync/async disposers and nested effect handles | ✅² |
emit/parallel/serial/bail/waterfall |
same five dispatch modes | ✅ |
| Context listener filters | with_filter() / emit_from() |
✅ |
| Logger buffer/exporters/levels/formatters | corresponding logger APIs | ✅ |
| Standard Schema validation | Plugin::validate_config + validation issues |
✅³ |
internal/plugin, internal/status, internal/service, internal/dispatch |
same meta-events | ✅⁴ |
Intercept meta-events (internal/get/set/config/update/listener) |
not ported | Not included |
| Decorators and callable services | explicit Rust traits/builders | Rust-native |
| Loader / include packages | cordis-include, cordis-group, cordis-loader, cordis-cli |
✅ separate crates |
- Rust cannot dynamically project arbitrary struct fields like a JavaScript Proxy, so
alias()is the explicit counterpart to commonmixin()usage. - Rust plugin code registers multiple effects explicitly;
EffectHandle::adopt()provides the original nested diagnostic/disposal tree. - Validation is trait-based because Standard Schema is a JavaScript protocol.
internal/dispatchcarries(mode, name, args); the upstream fourththisArgargument is omitted. The waterfall/bail interception points used by upstream HMR and config injection (internal/get,internal/set,internal/config,internal/update,internal/listener) are not part of this port, so downstream code relying on them needs a different extension point.
Design goals
- Faithful lifecycle: a plugin remains
Pendinguntil every injected service is active. Replacing/removing a provider changes the dependency epoch, unloads the consumer, and starts it again when possible. - Scoped DI: isolated branches resolve different implementations of the same service. Reusing an
Isolationlabel joins scopes. - Ownership-based cleanup: plugins, listeners, services, exporters, accessors, and child plugins are effects of their creating fiber.
- No executor lock-in: the crate has no third-party dependencies. Futures are accepted through boxed standard-library futures; eager lifecycle operations use a small wake-aware executor.
- Type-checked dynamic values: service, config, and event storage uses
Value(Arc<dyn Any + Send + Sync>) with checked downcasting and useful type errors.
Install
cargo add cordis-rs
[dependencies]
cordis-rs = "0.4"
The package is published as cordis-rs; the library crate is still named cordis, so imports remain use cordis::....
The minimum supported Rust version (MSRV) is Rust 1.85, and the crate uses Rust 2024 Edition. The crate has no external dependencies.
Rust version policy
- MSRV: Rust 1.85. CI and releases must continue to compile and test on this exact version.
- Development toolchain: the latest stable Rust release is used for formatting, Clippy, documentation, and forward-compatibility testing.
- Review cadence: the MSRV is reviewed every six months, around February and August. A review does not imply an automatic version increase.
- Review factors: maintainers consider the compiler shipped by stable Linux distributions, requirements of official plugins and downstream projects, useful language or standard-library improvements, dependency/security constraints, and toolchain versions actually used by downstream users.
- Version changes: the MSRV is raised only when there is a concrete maintenance or ecosystem benefit. An increase is documented in the changelog and release notes and is made in a minor release, never silently in a patch release.
- Workspace consistency: official Cordis crates and plugins should use one shared MSRV unless a documented platform constraint requires an exception.
Quick start
use cordis::{plugin_sync, Context, Inject, LogArg, PluginOutput, Result, Service};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;
struct Counter(AtomicUsize);
impl Service for Counter {
const NAME: &'static str = "counter";
}
fn main() -> Result<()> {
let root = Context::new();
let counter = Arc::new(Counter(AtomicUsize::new(0)));
let _provider = root.provide_service_arc(counter.clone())?;
let greeter = plugin_sync::<(), _>(
"greeter",
Inject::new(["counter"]),
|ctx, _config| {
let counter = ctx.require::<Counter>("counter")?;
let value = counter.0.fetch_add(1, Ordering::SeqCst) + 1;
ctx.logger().info(
"%s #%d",
[LogArg::from("started"), LogArg::from(value)],
);
Ok(PluginOutput::none())
},
);
let fiber = root.plugin_default(greeter);
fiber.try_wait()?;
assert_eq!(counter.0.load(Ordering::SeqCst), 1);
fiber.dispose()?;
root.fiber()?.dispose()?;
Ok(())
}
Dependency injection and reload
Inject controls whether a plugin may be active. Service changes reconcile consumers immediately and deterministically.
use cordis::{plugin_sync, Context, FiberState, Inject, PluginOutput, Result};
fn main() -> Result<()> {
let root = Context::new();
let consumer = plugin_sync::<(), _>(
"consumer",
Inject::new(["database"]),
|ctx, _| {
println!("database = {}", *ctx.require::<String>("database")?);
Ok(PluginOutput::infallible(|| println!("consumer unloaded")))
},
);
let fiber = root.plugin_default(consumer);
assert_eq!(fiber.state(), FiberState::Pending);
let database = root.provide("database", "sqlite://app.db".to_owned())?;
assert_eq!(fiber.state(), FiberState::Active);
database.dispose()?;
assert_eq!(fiber.state(), FiberState::Pending);
Ok(())
}
A plugin can attach per-service intercept config as part of its inject declaration:
use cordis::{Inject, LoggerIntercept, LoggerLevel};
let inject = Inject::new(["database"]).require_with(
"logger",
LoggerIntercept {
name: Some("worker".into()),
level: Some(LoggerLevel::Debug),
},
);
Scoped services
use cordis::{Context, Result};
fn main() -> Result<()> {
let root = Context::new();
let label = root.new_isolation();
let tenant_a = root.isolate_with("cache", label);
let tenant_a_worker = root.isolate_with("cache", label);
let tenant_b = root.isolate("cache");
let _cache = tenant_a.provide("cache", String::from("A"))?;
assert_eq!(tenant_a_worker.require::<String>("cache")?.as_str(), "A");
assert!(tenant_b.get::<String>("cache")?.is_none());
assert!(root.get::<String>("cache")?.is_none());
Ok(())
}
Effects
Every effect is single-shot and fiber-owned. Fiber unloading runs effects in reverse registration order. Cleanup errors are logged and do not prevent the remaining effects from running.
use cordis::{Context, Result};
let root = Context::new();
let handle = root.effect_infallible("temporary file", || {
// remove the file
})?;
assert_eq!(handle.meta().label, "temporary file");
handle.dispose()?; // early cleanup
handle.dispose()?; // no-op
# Ok::<(), cordis::CordisError>(())
Use effect_async() or AsyncDisposer::from_async() for asynchronous cleanup. A child plugin, listener, provided service, logger exporter, or accessor is internally registered as the same kind of effect.
Events
Arguments and bail values are Values. None means “continue”; Some(value) means “bail”.
use cordis::utils::block_on;
use cordis::{Context, Result, Value};
let root = Context::new();
let _listener = root.on("math/double", |event| {
let input = event.arg::<u32>(0)?.unwrap();
Ok(Some(Value::new(*input * 2)))
})?;
let answer = root.events()
.bail("math/double", [Value::new(21_u32)])?
.unwrap()
.downcast::<u32>()?;
assert_eq!(*answer, 42);
block_on(root.events().parallel("tick", []))?;
# Ok::<(), cordis::CordisError>(())
Dispatch modes:
emit: invoke in order and synchronously propagate the first error.parallel: poll every listener concurrently and aggregate errors.serial: await in order and stop on the first bail value.bail: synchronous ordered bail.waterfall/waterfall_async: each listener receivesevent.call_next()and may wrap or veto the rest of the chain.
Reflection
Normal Rust code should prefer typed services. Value, Accessor, and alias() support dynamic framework/loader use cases:
use cordis::{Accessor, Context, Result, Value};
use std::sync::{Arc, Mutex};
let root = Context::new();
let state = Arc::new(Mutex::new(1_u32));
let read = state.clone();
let write = state.clone();
let _property = root.accessor("answer", Accessor::read_write(
move |_| Ok(Some(Value::new(*read.lock().unwrap()))),
move |_, value| {
*write.lock().unwrap() = *value.downcast::<u32>()?;
Ok(())
},
))?;
root.set("answer", 42_u32)?;
assert_eq!(*root.require::<u32>("answer")?, 42);
# Ok::<(), cordis::CordisError>(())
Logger
The logger keeps a bounded chronological buffer and sends structured Messages to effect-owned exporters. It supports Cordis placeholders (%s, %d, %i, %f, %o, %O, %c, %C, and %%), per-name levels, custom formatters, ANSI name colors, and logger intercepts.
use cordis::{default_format, Context, ExporterConfig, LogArg, LoggerLevel, Result};
let root = Context::new();
let mut config = ExporterConfig::default();
config.levels.insert("default".into(), LoggerLevel::Debug);
let render = config.clone();
let _exporter = root.logger_service().exporter_with(config, move |message| {
println!("{}", default_format(&render, message));
})?;
root.named_logger("app").info("listening on %d", [LogArg::from(8080)]);
# Ok::<(), cordis::CordisError>(())
Writing a custom plugin
Closure adapters cover most plugins. Dynamic loaders can implement the object-safe trait directly:
use cordis::utils::BoxFuture;
use cordis::{Config, Context, Inject, Plugin, PluginOutput, Result};
struct Worker {
inject: Inject,
}
impl Plugin for Worker {
fn name(&self) -> &str { "worker" }
fn inject(&self) -> &Inject { &self.inject }
fn apply(&self, ctx: Context, _config: Config)
-> BoxFuture<Result<PluginOutput>>
{
Box::pin(async move {
let _queue = ctx.require::<String>("queue")?;
Ok(PluginOutput::none())
})
}
}
Override validate_config() to normalize config or return CordisError::validation(...). service_sync() and service_async() adapt constructors returning a type that implements Service.
Runtime notes
The original TypeScript implementation schedules lifecycle work through promises. This crate deliberately reconciles lifecycle transitions eagerly: provide, effect disposal, restart, and update return after affected fibers settle. This makes behavior deterministic without requiring Tokio or another executor. async event modes, async plugins, and async disposers remain available; dispose_async is a synchronous pass-through that never yields — awaiting them blocks the calling thread for the duration.
Executor-independent futures work everywhere. If a future creates runtime-specific resources (for example tokio::time::sleep), call Cordis while that runtime is entered.
Two consequences of the eager model: Fiber::try_wait() reports the settled state instead of suspending until dependencies arrive — it returns an error for Pending or disposed fibers. And futures driven by Cordis run on a small blocking executor while a lifecycle transition lock is held, so plugin apply callbacks and disposers must only await work that completes on other threads (never same-thread channels or spawn_blocking joins).
Fiber::update() mirrors upstream on inactive fibers: on an Active fiber it validates the new config, restarts, and reports the startup outcome; on a Pending or Failed fiber it stores the config and reconciles without waiting, so Ok(()) only means the config was accepted — inspect state()/error() for the outcome of the activation it schedules.
A panic in a plugin apply, disposer, or event listener propagates to the caller of the lifecycle operation that triggered it. Internal mutexes recover from poisoning, and a fiber interrupted mid-transition stays in Loading/Unloading — with already-registered effects still owned — until the next lifecycle event or dispose settles it. Context and Fiber do not implement UnwindSafe because their trait objects cannot prove it; when a plugin must not take down its caller, isolate it with std::panic::catch_unwind(std::panic::AssertUnwindSafe(...)).
Ecosystem
The core crate stays dependency-free; the loader stack lives in sibling crates that build on it:
| Crate | Purpose |
|---|---|
cordis-include |
Config entry trees, YAML/JSON loader files, patch lists with provenance dumps (bundle/profile composition), the tag-preserving !!js dialect with expression evaluation, ${{ env.NAME }} interpolation, atomic and debounced writes |
cordis-group |
Group plugin: nested entries with cascading disable |
cordis-loader |
Plugin registry + entry↔fiber state machine, cross-file import entries, document-backed composition sources (with_document / update), hot reload, lifecycle events, debounced write-backs, dynamic-library plugins (dynamic feature) |
cordis-cli |
cordis run executable: daemon/worker exit-code protocol, signals, dotenv, plugin-library hot restarts |
Ported so far: static plugin registry, groups, import sub-files, self-kill
detection, entry-level inject, config hot reload, the loader/* event
family, debounced writes, bundle/profile patch composition with
provenance-aware dumps (apply_entry_patches / compose_layers /
render_config_dump), a tag-preserving !!js YAML dialect with the
expression subset evaluated at config hand-off (including the
disabled: !!js slot), document-backed composition with in-memory
recomposition, the daemon/worker runner, and dynamic-library plugins with
worker-restart HMR (cordis-loader's dynamic feature plus
cordis run --plugin-dir). Not yet ported: isolate / service migration,
arbitrary-JavaScript expressions beyond the shipped subset.
Project layout
The repository is a virtual cargo workspace; the core crate lives in
crates/cordis and mirrors the upstream package:
crates/
├── cordis/ # cordis-rs — this crate (zero dependencies)
│ └── src/
│ ├── context.rs # root/child context and scope overlays
│ ├── events.rs # event bus and five dispatch modes
│ ├── fiber.rs # plugin lifecycle and effect ownership
│ ├── logger.rs # messages, formatters, buffer, exporters
│ ├── reflect.rs # scoped service store and computed properties
│ ├── registry.rs # Plugin, Inject, runtime records
│ ├── service.rs # typed service and constructor adapters
│ ├── effect.rs # disposers, handles, diagnostic trees
│ ├── value.rs # Arc<dyn Any> values
│ └── utils.rs # boxed futures, small executor
├── cordis-include/ # entry trees and config files
├── cordis-group/ # group plugin
├── cordis-loader/ # plugin registry + state machine
└── cordis-cli/ # cordis run executable
Development
# MSRV compatibility
cargo +1.85 check --workspace --all-targets --all-features
cargo +1.85 test --workspace --all-features
# Latest stable quality and forward-compatibility checks
cargo +stable fmt --all -- --check
cargo +stable clippy --workspace --all-targets --all-features -- -D warnings
cargo +stable test --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo +stable doc --workspace --no-deps --all-features
License
MIT. The architecture and behavior are based on Cordis by Shigma and the DeepSeek Harness vendored implementation.
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…