docs: Refresh daemon developer docs#4412
Merged
Merged
Conversation
Contributor
📋 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. |
Contributor
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.
Contributor
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. |
wenshao
requested changes
May 22, 2026
doudouOUC
force-pushed
the
docs/daemon-developer-deep-dive
branch
from
8e90746 to
fa42983
Compare
Collaborator
Author
|
Force-push 重写说明 刚 force-push 把整个 PR 从「bilingual EN+ZH」改成「Chinese-only + 新增运维手册」。改动：
如果需要回到 EN 版本，git 历史里 |
wenshao
reviewed
May 22, 2026
wenshao
requested changes
May 22, 2026
wenshao
requested changes
May 22, 2026
wenshao
reviewed
May 24, 2026
wenshao
reviewed
May 24, 2026
wenshao
reviewed
May 24, 2026
wenshao
reviewed
May 24, 2026
wenshao
reviewed
May 24, 2026
wenshao
reviewed
May 24, 2026
This was referenced May 24, 2026
wenshao
reviewed
May 24, 2026
doudouOUC
force-pushed
the
docs/daemon-developer-deep-dive
branch
2 times, most recently
from
056a38c to
4147aa8
Compare
Collaborator
Author
|
根据 daemon_mode_b_main 最新代码同步（force-push at 6 个新 commit 进了
最重要的：#4328 删除了 本次文档变化：
23 files / +4,428 lines（前次 4,366）。无 stale |
doudouOUC
force-pushed
the
docs/daemon-developer-deep-dive
branch
from
4147aa8 to
b4810d1
Compare
Collaborator
Author
|
Round 2 review fold-in（force-push at 逐 commit review 时发现两处描述不准 / 一处漏： 1.
|
doudouOUC
force-pushed
the
docs/daemon-developer-deep-dive
branch
from
b4810d1 to
88c66de
Compare
Collaborator
Author
|
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
requested changes
May 24, 2026
doudouOUC
commented
Jun 12, 2026
doudouOUC
commented
Jun 12, 2026
doudouOUC
force-pushed
the
docs/daemon-developer-deep-dive
branch
from
b71ca2c to
377c209
Compare
doudouOUC
changed the title
Collaborator
Author
qwen-code-ci-bot
requested changes
Jun 12, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
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
commented
Jun 13, 2026
doudouOUC
left a comment
doudouOUC
left a comment
Collaborator
Author
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>
Collaborator
|
@qwen-code /triage |
Collaborator
|
Thanks for the PR! Template looks good ✓ — all required headings present, bilingual structure intact. On direction: daemon developer docs are squarely within scope. The daemon surface has grown substantially and contributors need a current reference — this fills a real gap. The doc set explicitly positions itself as a complement to (not replacement of) existing user-facing and protocol docs, which is the right call. On approach: 21 documents covering the full daemon stack is ambitious but the reading-path organization (by persona: new contributor, adapter author, pool developer, debugger) keeps it navigable. The index doc with cross-reference tables and a glossary is well-structured. The bilingual format means every future edit needs to update two sections, but that's a project-wide convention. Count accuracy — verified against current
All counts in the doc files match current source. Previous triage's stale-count findings have been resolved in this refresh. Minor nit (non-blocking): the PR description body still says "66 feature tags and 10 conditional tags" and "25 current Moving on to code review. 🔍 中文说明感谢贡献！ 模板完整 ✓ —— 所有必需章节齐全，双语结构完好。 方向：daemon 开发者文档完全在项目范围内。daemon 功能已经大幅增长，贡献者需要一份当前有效的参考 —— 这个文档集填补了真实缺口。文档集明确定位为对现有用户文档和协议文档的补充（而非替代），这个定位是对的。 方案：21 篇文档覆盖完整 daemon 栈，规模不小，但按角色（新贡献者、适配器作者、池开发者、调试者）组织的阅读路径让导航保持清晰。索引文档的交叉引用表和术语表结构合理。双语文档意味着每次后续编辑都需要更新两个语言版本，但这是项目级的统一规范。 计数准确性 —— 已按当前
文档文件中的所有计数与当前源码一致。此前 triage 提出的过期计数问题已在本轮刷新中修复。 小问题（不阻塞）： PR 描述正文中的数字已与文档和源码一致。无需修改。 进入代码审查 🔍 — Qwen Code · qwen3.7-max |
Collaborator
Code ReviewIndependent proposal (before reading the diff): For daemon developer docs, I'd expect an architecture overview with process topology and sequence diagrams, per-component docs for each major subsystem (bridge, permissions, MCP pool, events, capabilities, auth, filesystem), SDK/adapter guides for client authors, a configuration reference, a quickstart/operations guide, and an index with reading paths by persona. Comparison with the diff: The PR matches and exceeds this baseline. The 21-doc set covers every major subsystem with bilingual content, 7 Mermaid diagrams in the architecture doc, persona-based reading paths, and comprehensive cross-references. Correctness spot-checks:
Forward-reference audit (disclosed caveat): The PR explicitly warns that some cross-references point to docs on
These are deliberate forward references, not broken links. They resolve once the No critical blockers found. The architecture descriptions, component relationships, code references, wire protocol documentation, and reading paths are all accurate against the current codebase. AGENTS.md compliance: No issues. Docs-only — no runtime code changes, no new abstractions. Bilingual format follows project convention. File naming uses kebab-case. The Real-Scenario TestingN/A — docs-only change. No runtime behavior to test. 中文说明代码审查独立方案（阅读 diff 之前）：对于 daemon 开发者文档，我期望看到：包含进程拓扑和时序图的架构概览、各主要子系统（bridge、权限、MCP 池、事件、能力、认证、文件系统）的专题文档、面向客户端作者的 SDK/适配器指南、配置参考、快速上手/运维手册、以及按角色组织的索引和阅读路径。 与 diff 的对比：PR 匹配并超出了这个基线。21 篇文档集覆盖了每个主要子系统，双语内容、架构文档中 7 张 Mermaid 图、按角色的阅读路径、以及全面的交叉引用。 正确性抽查：
向前引用审计（已披露的注意项）： PR 明确警告部分交叉引用指向 未发现关键阻塞问题。 架构描述、组件关系、代码引用、wire 协议文档和阅读路径均与当前代码库一致。 AGENTS.md 合规性： 无问题。仅文档变更 —— 无运行时修改、无新增抽象。双语文档遵循项目规范。文件命名使用 kebab-case。 真实场景测试N/A —— 仅文档变更，无运行时行为需要测试。 — Qwen Code · qwen3.7-max |
Collaborator
ReflectionStepping back: this is a comprehensive documentation effort that fills a real gap. The daemon surface has grown substantially (43 event types, 66 feature tags, 25 serve flags), and having a current developer reference will meaningfully lower the ramp-up cost for new contributors. The PR's approach matches my independent proposal and exceeds it in scope — the bilingual format, 7 Mermaid diagrams, persona-based reading paths, the "what this doc set intentionally does NOT cover" section, and the glossary all show thoughtful design. Every source file path I spot-checked resolves. The architecture doc's three trust boundaries (HTTP entry, bridge↔ACP child, agent↔MCP server) are exactly the right framing for someone trying to understand where security-relevant decisions happen. Previous triage blocked on stale counts — that's now resolved. All five count claims (events, feature tags, conditional tags, serve flags, UI event types) match current The only residual risk is the forward-reference caveat the PR honestly discloses: four cross-referenced doc paths exist on Verdict: the previous blockers are resolved. This is ready to ship. Approving. ✅ 中文说明反思退一步看：这是一份全面的文档工作，填补了真实缺口。daemon 功能已经大幅增长（43 种事件类型、66 个 feature tag、25 个 serve flag），有一份当前有效的开发者参考会显著降低新贡献者的上手成本。 PR 的方案与我的独立方案匹配并在范围上超出 —— 双语文档、7 张 Mermaid 图、按角色的阅读路径、"本文档集故意不覆盖的内容"章节、以及术语表都体现了用心的设计。我抽查的每个源文件路径都能正确解析。架构文档中的三条信任边界正是帮助新人理解安全相关决策发生位置的正确框架。 此前 triage 因过期计数而阻塞 —— 现已修复。所有五项计数声明（event、feature tag、条件 tag、serve flag、UI 事件类型）均与当前 唯一剩余风险是 PR 已诚实披露的向前引用注意项：四个交叉引用的文档路径存在于 结论：此前的阻塞问题已解决。可以合入。批准。✅ — Qwen Code · qwen3.7-max |
qwen-code-ci-bot
requested changes
Jun 14, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Needs count accuracy fixes before merging — see my notes above. The structure and coverage are solid; four stale numbers and two undocumented flags stand between this and a merge. 🙏
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
Collaborator
|
@qwen-code /triage |
wenshao
approved these changes
Jun 14, 2026
qwen-code-ci-bot
approved these changes
Jun 14, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, looks ready to ship. ✅ All count claims verified accurate against current source. Previous blockers resolved.
Collaborator
|
Qwen Code review did not complete successfully: Qwen review aborted with an API error before posting comments. See workflow logs. |
doudouOUC
added a commit
that referenced
this pull request
Jun 15, 2026
* docs: Refresh daemon developer docs Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: Address daemon review feedback Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * docs: Address daemon review suggestions Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * codex: address PR review feedback (#4412) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * codex: address PR review feedback (#4412) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> * codex: address PR review feedback (#4412) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com> --------- Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 66 feature tags and 10 conditional tags, and the configuration/quickstart pages list all 25 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 页面是否记录 66 个 feature tag 和 10 个条件 tag，configuration/quickstart 页面是否列出当前 25 个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.