docs: Refresh daemon developer docs#4412
Conversation
📋 Review SummaryThis PR adds a comprehensive 20-file bilingual developer documentation set for qwen-code daemon mode, totaling ~7,130 lines across 22 files. The documentation covers the complete daemon architecture including 🔍 General Feedback
🎯 Specific Feedback🟡 High
🟢 Medium
🔵 Low
✅ Highlights
🔍 Verification Checklist (for maintainers)Before merging, verify:
Recommendation: This is a high-quality documentation PR that significantly improves the developer experience for contributing to the daemon codebase. The minor discrepancies noted above (diagram count in PR description, glossary completeness) are easily addressable and don't block the merge. Consider merging after the PR description diagram count is corrected from 6 to 7. |
There was a problem hiding this comment.
Pull request overview
This PR adds a new developer deep-dive documentation set under docs/developers/daemon/ (bilingual EN/ZH) intended to document the qwen serve daemon architecture, its protocol surface, SDK client, and adapters, plus wires it into the developer docs navigation.
Changes:
- Added a 20-file daemon-mode deep-dive documentation set (
docs/developers/daemon/*.md) with diagrams, workflows, and component references. - Added daemon sub-navigation (
docs/developers/daemon/_meta.ts) and a top-level nav entry (docs/developers/_meta.ts).
Reviewed changes
Copilot reviewed 22 out of 22 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/developers/_meta.ts | Adds the top-level “Daemon Mode (Developer Deep Dive)” nav entry. |
| docs/developers/daemon/_meta.ts | Adds the daemon-docs sidebar ordering/titles. |
| docs/developers/daemon/00-index.md | Index, reading order, glossary, and scope notes for the doc set. |
| docs/developers/daemon/01-architecture.md | System overview + Mermaid diagrams for major daemon flows. |
| docs/developers/daemon/02-serve-runtime.md | Documents qwen serve bootstrap/runtime responsibilities and flows. |
| docs/developers/daemon/03-acp-bridge.md | Describes the bridge layer and how daemon↔ACP communication is structured. |
| docs/developers/daemon/04-permission-mediation.md | Documents multi-client permission mediation policies and flows. |
| docs/developers/daemon/05-mcp-transport-pool.md | Documents the workspace-scoped MCP transport pool design/operation. |
| docs/developers/daemon/06-mcp-budget-guardrails.md | Documents MCP budget controller behavior and emitted events. |
| docs/developers/daemon/07-workspace-filesystem.md | Documents workspace filesystem boundary rules and error handling. |
| docs/developers/daemon/08-session-lifecycle.md | Documents session lifecycle, identity, and terminal frames. |
| docs/developers/daemon/09-event-schema.md | Documents the typed daemon event schema and reducers. |
| docs/developers/daemon/10-event-bus.md | Documents the in-memory SSE EventBus and backpressure behavior. |
| docs/developers/daemon/11-capabilities-versioning.md | Documents /capabilities, feature tags, and versioning rules. |
| docs/developers/daemon/12-auth-security.md | Documents auth middleware, host/CORS defenses, and device-flow auth. |
| docs/developers/daemon/13-sdk-daemon-client.md | Documents the TypeScript daemon client SDK architecture/surfaces. |
| docs/developers/daemon/14-cli-tui-adapter.md | Documents the CLI TUI daemon adapter behavior and event mapping. |
| docs/developers/daemon/15-channel-adapters.md | Documents IM channel adapters and their daemon bridge layer. |
| docs/developers/daemon/16-vscode-ide-adapter.md | Documents VSCode companion daemon adapter and loopback constraint. |
| docs/developers/daemon/17-configuration.md | Consolidated daemon configuration reference (flags/env/settings). |
| docs/developers/daemon/18-error-taxonomy.md | Error taxonomy + remediation guidance across daemon layers. |
| docs/developers/daemon/19-observability.md | Observability/debugging surfaces and operational recipes. |
Comments suppressed due to low confidence (2)
docs/developers/daemon/19-observability.md:21
- The table references
PermissionAuditRingatpermissionAudit.ts:1-60, butpackages/cli/src/serve/permissionAudit.tsdoes not exist in this branch. Please update the reference to the actual implementation (if renamed/moved) or mark the audit ring as not yet implemented here.
| `/demo` debug console | `GET /demo` (`packages/cli/src/serve/demo.ts`) | Browser-accessible single-page console (chat + event log + workspace inspector + permission UX). Open `http://127.0.0.1:4170/demo` on loopback — the fastest way to exercise the daemon end-to-end without writing SDK code. See [`02-serve-runtime.md`](./02-serve-runtime.md) for the loopback-vs-auth registration rules. |
| `PermissionAuditRing` | `permissionAudit.ts:1-60` | In-memory FIFO (512 entries) of permission decisions. |
| `mediator`'s `decisionReason` audit trail | `permissionMediator.ts:80-100+` | Internal structured "why did this resolve like that" records. |
docs/developers/daemon/17-configuration.md:57
- This row also mentions
InvalidPolicyConfigErrorforpolicy.consensusQuorum, but that error type isn't defined in this branch. Please update the described validation/behavior to what the current implementation actually enforces, so operators know whether invalid values fail boot or are ignored.
| `policy.consensusQuorum` | positive integer | N for the `consensus` mediator policy. **Default:** `floor(M/2) + 1` of `votersAtIssue.size` (unanimity for M=2; supermajority for larger even M). Setting this under a non-`consensus` strategy is silently ignored — a stderr warning fires at boot. Non-positive-integer values throw `InvalidPolicyConfigError`. See [`04-permission-mediation.md`](./04-permission-mediation.md). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
8e90746 to
fa42983
Compare
|
Force-push 重写说明 刚 force-push 把整个 PR 从「bilingual EN+ZH」改成「Chinese-only + 新增运维手册」。改动:
如果需要回到 EN 版本,git 历史里 |
056a38c to
4147aa8
Compare
|
根据 daemon_mode_b_main 最新代码同步(force-push at 6 个新 commit 进了
最重要的:#4328 删除了 本次文档变化:
23 files / +4,428 lines(前次 4,366)。无 stale |
4147aa8 to
b4810d1
Compare
|
Round 2 review fold-in(force-push at 逐 commit review 时发现两处描述不准 / 一处漏: 1.
|
b4810d1 to
88c66de
Compare
|
Round 3 重构:从「review fold-in 切分」改成「功能视角」(force-push at 上一轮把 PR #4411 拆成 R9 / W11 / W12 / R10 / R2 / R3 T3 / WR4 / WR5 / WR6 一一列,太按 PR review 内部结构组织 —— 读者要的是「daemon mode b 是个什么完整功能」,不是「这一轮 review 改了哪 6 件事」。本轮把 daemon_mode_b 作为完整产品重新组织。 Doc 05 (
|
wenshao
left a comment
There was a problem hiding this comment.
[Critical] QWEN_SERVE_NO_MCP_POOL env var is referenced across 8 docs (02, 05, 06, 09, 11, 17, 19, 20-quickstart-operations) but has zero matches in packages/ source code on main. This is a carryover from R9 — still unresolved.
— qwen3.7-max via Qwen Code /review
DragonnZhang
left a comment
There was a problem hiding this comment.
LGTM. Documentation-only PR (21 new daemon deep-dive docs + nav entries + protocol doc additions). All 8 CI checks pass. No code changes, no security concerns.
Note: PR body self-discloses doc-rot (event count 29 vs current 38 on daemon_mode_b_main, drifted line numbers). This is acknowledged by the author and acceptable for a docs-ahead-of-code landing.
Reviewed commit: 431d9d6
431d9d6 to
b71ca2c
Compare
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
doudouOUC
left a comment
There was a problem hiding this comment.
12 Critical findings identified by cross-referencing documentation against source code. The most impactful issues are fabricated API signatures (docs 14, 15, 16), wrong behavioral descriptions (docs 06, 07), and an entirely undocumented rate limiter feature across all 21 daemon docs.
Additionally:
-
docs/developers/development/telemetry.mddeletes 93 lines of security-relevantoutboundCorrelationcontent (W3Ctraceparentpropagation,UndiciInstrumentationclient-side HTTP spans) without preserving it in any other developer reference doc — documentation regression. -
docs/developers/examples/daemon-client-quickstart.md:152— ring buffer size says 4000 but actualDEFAULT_RING_SIZE = 8000ineventBus.ts:92.
— qwen3.7-max via Qwen Code /review
b71ca2c to
377c209
Compare
qwen-code-ci-bot
left a comment
There was a problem hiding this comment.
Hey @doudouOUC — thanks for this substantial documentation effort. The content itself is impressive, but the PR body doesn't follow the PR template. Two issues:
- Missing
<details><summary>中文说明</summary>...</details>block — the template requires a Chinese translation of the English body inside this collapsible section. Your PR has inline bilingual notes, but not the structured 中文说明 block. - Section headings diverge from template — the template prescribes
What this PR does,Why it's needed,Reviewer Test Plan(withHow to verify/Evidence (Before & After)/Tested on),Risk & Scope, andLinked Issues. Your PR usesSummary,Validation,Scope / Risk,Testing Matrix, andLinked Issues / Bugs. The information is all there, but the structure helps reviewers scan quickly.
Could you reshape the PR body to match the template? The actual doc content looks solid — this is just about making the review process smoother.
中文说明
@doudouOUC 你好——感谢这份高质量的文档工作。内容本身很好,但 PR 正文没有遵循 PR 模板,有两个问题:
- 缺少
<details><summary>中文说明</summary>...</details>区块 —— 模板要求在折叠区块内提供英文正文的中文翻译。你的 PR 有零散的中英双语注释,但没有结构化的中文说明区块。 - 章节标题与模板不一致 —— 模板规定使用
What this PR does、Why it's needed、Reviewer Test Plan(含How to verify/Evidence/Tested on)、Risk & Scope、Linked Issues。你的 PR 用的是Summary、Validation、Scope / Risk等自定义标题。信息都齐了,但统一结构方便 reviewer 快速定位。
请按模板重新组织 PR 正文即可,文档内容本身没有问题。
— Qwen Code · qwen3.7-max
doudouOUC
left a comment
There was a problem hiding this comment.
Review: PR #4412 — docs: Refresh daemon developer docs
Verdict: Approve (downgraded to Comment — self-PR)
The documentation is thorough and accurate — all key factual claims (API paths, constants, event counts, behavioral descriptions, security limitations) verified against the actual source code. Build and CI all pass.
Suggestions
1. 04-permission-mediation.md — Security limitations under-emphasized
The self-reported client ID (no proof-of-possession) and cross-strategy cancel sentinel are documented honestly but buried in technical sections. An operator skimming the doc will miss that designated/consensus modes have no identity verification in v1, and that cancel bypasses all strategies including local-only.
→ Add a prominent "
2. 07-workspace-filesystem.md — Symlink rejection needs migration note
Doc correctly notes symlinks are outright rejected (deviation from F1 behavior). No migration guidance for agents that depended on symlink traversal.
→ Add a migration note: "If your agent writes through symlinks, resolve paths to real paths first."
3. 01-architecture.md:25 — Package map cross-package dependency direction
The package map Mermaid diagram correctly shows BR2 (bridge) being referenced from runQwenServe.ts, but readers unfamiliar with package structure may be confused by the cross-package dependency. Could use a brief note explaining the separation.
4. 09-event-schema.md — formatSseFrame line reference outdated
Doc references server.ts:2602 but actual location has drifted to ~4186. Consider using function name reference instead of brittle line number.
5. 06-mcp-budget-guardrails.md — Reservation vs live count distinction
Doc accurately explains hysteresis is based on reservation count, not live CONNECTED count. Operators monitoring live connections may see different numbers than budget events suggest.
→ Add a sentence: "Reservation count may exceed live connection count during reconnect storms."
— qwen3-max via Qwen Code /review
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
What this PR does
This PR adds the daemon developer documentation set under the Developer Guide and refreshes the existing daemon adapter draft so it matches the current
mainbranch. The documentation now covers theqwen serveruntime, ACP bridge, MCP transport pool and budget guardrails, workspace filesystem boundary, session lifecycle, typed event schema, capabilities, TypeScript SDK daemon client, shared UI transcript layer, channel and VSCode adapters, configuration, error taxonomy, observability, and quickstart operations.Why it's needed
The previous draft was written against an older daemon branch and drifted from
main: event and capability counts were stale, newer serve flags and rate-limit settings were missing, runtime MCP server mutation routes were described with an outdated path, and the legacy CLIDaemonTuiAdapterwas described as deleted even though it still exists. Bringing the docs up to date gives contributors a current reference for reviewing and extending daemon mode.Reviewer Test Plan
How to verify
Review the Developer Guide navigation and confirm the daemon section appears under
docs/developers. Check that the event schema documents 43 known daemon events, the capabilities page documents 65 feature tags and 9 conditional tags, and the configuration/quickstart pages list all 23 currentqwen serveflags. Confirm the legacyDaemonTuiAdapterlanguage says it still exists as a CLI-side legacy adapter while the SDK shared UI transcript layer is the reuse direction.Evidence (Before & After)
N/A — docs-only change.
Tested on
Environment (optional)
N/A — docs-only change. Local validation ran Prettier, staged diff whitespace checks, a source-count consistency script for daemon events/capabilities/UI event types, and a relative-link existence check.
Risk & Scope
Linked Issues
References #4175. Supersedes #5056.
中文说明
What this PR does
本 PR 在 Developer Guide 下新增 daemon 开发者文档集,并刷新既有 daemon adapter 草案,使其与当前
main分支一致。文档现在覆盖qwen serve运行时、ACP bridge、MCP transport 池与预算护栏、workspace 文件系统边界、session 生命周期、typed event schema、capabilities、TypeScript SDK daemon client、共享 UI transcript 层、channel 与 VSCode 适配器、配置、错误分类、可观测性和快速上手运维手册。Why it's needed
此前草案基于较早的 daemon 分支编写,已经和
main发生漂移:event 与 capability 数量过期,新的 serve flags 和 rate-limit 设置缺失,运行时 MCP server mutation 路由仍写成旧路径,并且把仍然存在的 legacy CLIDaemonTuiAdapter描述成已删除。更新后,贡献者在 review 和扩展 daemon mode 时能有一份当前有效的参考文档。Reviewer Test Plan
How to verify
检查 Developer Guide 导航,确认 daemon 章节出现在
docs/developers下。检查 event schema 是否记录 43 种已知 daemon event,capabilities 页面是否记录 65 个 feature tag 和 9 个条件 tag,configuration/quickstart 页面是否列出当前 23 个qwen serveflag。确认 legacyDaemonTuiAdapter的表述为它仍作为 CLI 侧 legacy adapter 存在,而 SDK 共享 UI transcript 层是复用方向。Evidence (Before & After)
N/A — 仅文档变更。
Tested on
Environment (optional)
N/A — 仅文档变更。本地验证运行了 Prettier、staged diff 空白检查、daemon event/capability/UI event type 的源码计数一致性脚本,以及相对链接存在性检查。
Risk & Scope
Linked Issues
References #4175. Supersedes #5056.