Skip to content

Commit 8e90746

Browse files
committed
docs(developers): add daemon-mode developer deep-dive documentation set
Adds 20-file bilingual (English + Chinese) developer documentation set under docs/developers/daemon/ for qwen serve daemon mode. Plus one nav entry in docs/developers/_meta.ts and a sub-nav under docs/developers/daemon/_meta.ts. The set complements (not replaces) the existing daemon docs: - docs/users/qwen-serve.md — operator quickstart, flags, threat model - docs/developers/qwen-serve-protocol.md — wire-level HTTP routes - docs/developers/examples/daemon-client-quickstart.md — TS walkthrough - docs/developers/daemon-client-adapters/* — adapter design drafts It is the developer architecture reference that's been missing — a new contributor's path through the system, with one architectural diagram doc and per-component deep-dives in both English and Chinese. Document set: Foundation - 00-index.md navigation, glossary, reading paths - 01-architecture.md system architecture + 6 Mermaid diagrams Server core - 02-serve-runtime.md runQwenServe bootstrap, Express, lifecycle, validatePolicyConfig + InvalidPolicyConfigError - 03-acp-bridge.md @qwen-code/acp-bridge package internals - 04-permission-mediation.md MultiClientPermissionMediator — four policies, N=floor(M/2)+1 quorum + M=2 unanimity edge case, X-Qwen-Client-Id self-declaration security caveat - 05-mcp-transport-pool.md McpTransportPool (F2) including pool-aware snapshot fields (entryCount / entrySummary), MCPCallInterruptedError on silent transport drop, canonicalOAuth fingerprint normalization, extension-uninstall orphan reap via MAX_IDLE_MS, IDE-close drain path, /mcp refresh pool gate - 06-mcp-budget-guardrails.md WorkspaceMcpBudget — modes, hysteresis, refused-batch coalescing, scope: 'pool' future reservation - 07-workspace-filesystem.md WorkspaceFileSystem sandbox + FsError preservation over ACP wire - 08-session-lifecycle.md create/attach/load/resume, identity, heartbeat, eviction - 09-event-schema.md typed event schema v1 (29 known event types) with payloads, reducers, envelope-level metadata (_meta.serverTimestamp), tool-call _meta (provenance + serverId), SDK reducer behavior (awaitingResync flag, RESYNC_PASSTHROUGH_TYPES) - 10-event-bus.md EventBus + Last-Event-ID replay + ring-eviction-on-resume state_resync_required recovery flow - 11-capabilities-versioning.md capability registry, protocol version, conditional advertisement - 12-auth-security.md bearer, host allowlist, mutation gate, --require-auth, /health exemption, device-flow, X-Qwen-Client-Id identity caveat, sanitizeForStderr CVE-2021-42574 defense Clients - 13-sdk-daemon-client.md TypeScript SDK — DaemonClient, DaemonSessionClient, DaemonAuthFlow, SSE, MCP_RESTART_DEFAULT_TIMEOUT_MS 330s rationale - 14-cli-tui-adapter.md DaemonTuiAdapter - 15-channel-adapters.md DaemonChannelBridge + DingTalk / WeChat / Telegram - 16-vscode-ide-adapter.md DaemonIdeConnection (loopback-only) Reference appendices - 17-configuration.md env vars + CLI flags + settings.json keys - 18-error-taxonomy.md typed errors per layer (filesystem boundary, bridge errors, daemon-host error kinds, boot-time config errors, device-flow) - 19-observability.md QWEN_SERVE_DEBUG, debug recipes, /demo console Each topic doc follows the same contract: Overview / Responsibilities / Architecture / Workflow (with Mermaid sequence diagrams) / State & Lifecycle / Dependencies / Configuration / Caveats & Known Limits / References. Pinned to the daemon_mode_b_main code surface (F2 pool, F3 mediator, F4 prereqs). Some referenced files (McpTransportPool, state_resync_ required, validatePolicyConfig, FsError-over-wire, sanitizeForStderr) land on main only when daemon_mode_b_main next batches up — the doc set arrives ahead of the feature merges by design.
1 parent 48b0a8b commit 8e90746

22 files changed

Lines changed: 7153 additions & 0 deletions

docs/developers/_meta.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ export default {
2121
'channel-plugins': 'Channel Plugin Guide',
2222
tools: 'Tools',
2323
'qwen-serve-protocol': 'qwen serve HTTP protocol',
24+
daemon: 'Daemon Mode (Developer Deep Dive)',
2425

2526
examples: {
2627
display: 'hidden',

docs/developers/daemon/00-index.md

Lines changed: 201 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/01-architecture.md

Lines changed: 446 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/02-serve-runtime.md

Lines changed: 285 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/03-acp-bridge.md

Lines changed: 376 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/04-permission-mediation.md

Lines changed: 431 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/05-mcp-transport-pool.md

Lines changed: 553 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/06-mcp-budget-guardrails.md

Lines changed: 267 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/07-workspace-filesystem.md

Lines changed: 419 additions & 0 deletions
Large diffs are not rendered by default.

docs/developers/daemon/08-session-lifecycle.md

Lines changed: 332 additions & 0 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)