Tianyi Cui
6227cfd03d
architecture.md is the behavior map: layering, service map, seam pattern, and the loop — everything else defers to its owning tier. - Seam narrations compress to two-to-four sentences plus links to the RFC and type-catalog homes that carry the detail (turn-end variant semantics -> session.md, derivation mapping -> session.md, StreamChunk conventions -> llm-streaming.md + source). - The MVP feature-to-mechanism checklist moves de-statused into the extension cookbook as 'The feature -> mechanism map' — mechanisms only, no implementation-status bolding to rot; the microkernel RFC's proof-obligation pointer follows it. - The layering diagram describes layers by family instead of enumerating packages (the stale 'future plugins: hooks, compaction' row is gone); the dependency rule defers to packages/README.md. - The loop pseudocode, the three externally-cited anchors (the vocabulary, event taxonomy, waterfall semantics), and the filename are unchanged. - Budget ratchet: docs/architecture.md 3897 -> 1800 (now 1,797 words); the doc-tiers RFC's deferred list prunes the item this ships.
1.9 KiB
RFC: Microkernel — extension via Cordis event taxonomy, one concrete loop
Status: implemented (accepted 2026-06-11)
Context
The product principle (see the 微内核Harness实现思路 design doc) is "everything is a plugin": hooks, /goal, /loop, dynamic workflows, compaction, sandboxing, permissions, UI, persistence, MCP, skills must all be writable as plugins without modifying the core. Candidate mechanisms considered: a purpose-built middleware stack (koa-compose style), an explicit phase state machine plugins can insert into, or Cordis's native event system.
Decision
Pure Cordis event taxonomy. The loop's extension seams are typed events with deliberate dispatch modes:
- waterfall (around-middleware) where plugins mutate or veto:
agent/prompt-submit,agent/request,agent/step-result,agent/turn-continuation,tools/pre-execute,tools/post-execute,llm/stream,system-prompt/assemble. - emit (sync fire-and-forget) for notifications: turn/step boundaries, stream chunks, lifecycle, errors.
- parallel (awaited) for the one durability checkpoint:
session/flush.
The event vocabulary lives in interface packages (dsh-agent declares the agent/* events); @deepseek-ai/dsh-agent-loop is the only concrete loop plugin and is itself swappable — nothing outside it may depend on it.
Consequences
- Every MVP feature maps to a listener (the feature → mechanism map is the proof obligation, kept current).
- HMR and disposal come free: listeners and registrations are Cordis effects.
- Waterfall semantics (call
next()or short-circuit) are non-obvious and must be taught — documented in AGENTS.md and covered by composition tests. - The loop must be defensive: plugin exceptions are contained at turn level, steering from any seam is never stranded (regression-tested).