Skip to content

[PR] docs: live architecture hub — overall diagram + module pages with diagrams + file-map CI guard - #5924

Merged
ranxianglei merged 9 commits into
2026-11-08_docs-centralizationfrom
2026-11-08_architecture-docs
Nov 8, 2026
Merged

ranxianglei merged 9 commits into
2026-11-08_docs-centralizationfrom
2026-11-08_architecture-docs

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

(ai: sglang-gpu0/qwen3.8-27b)

Owner request 2026-11-08: one architecture diagram (canonical), plus per-module docs — responsibility, basic principles, how-it-works — each with its own diagram, bilingual, live-maintained.

What this PR ships

1. docs/architecture/ becomes the live architecture hub

2. reference/architecture.md file map completed + CI-enforced

3. Live-maintenance mechanism (the "实时维护" half)

  • New CI lane architecture-docs (tools/check-architecture-docs.mjs, zero-dep node):
    1. file map covers all src/ files (no missing, no ghosts);
    2. hub ledger rows ↔ module page pairs (en + .zh-CN), no orphan pages;
    3. every page links its svg-first diagram + png fallback (all present);
    4. every SVG basic-well-formed (an unescaped & once shipped a broken English diagram — the check exists because of that).
  • AGENTS.md "Documentation Layout" gains the live rule: any PR that adds/removes/renames a src/ module or changes a depicted data flow / table / lane / wire path MUST update the page(s) + diagram(s) + ledger row + file map in the same PR. Visual freshness rides on that rule + review; the mechanical half is red-or-green in CI.
  • docs/index.md / index.zh-CN.md entries; CHANGELOG entry.

Scope

Docs + one guard script + one CI job + AGENTS/CHANGELOG/index lines. No src/ behavior change, no config surface change, no kernel change. Stacked on the docs-centralization branch (base = 2026-11-08_docs-centralization, PR #5920) so the hub lands on top of the docs/ hub structure; merge order: #5920 first.

Verification

  • node tools/check-architecture-docs.mjs → all green (map 305/305, ledger 8 modules / 1 active / page set matches, diagrams + SVG well-formedness).
  • All 4 SVGs parse as XML; all 4 PNGs rendered and visually verified (chromium headless + margin probe).
  • ci.yml YAML parses.

@ranxianglei ranxianglei changed the title docs: live architecture hub — overall diagram + module pages with diagrams + file-map CI guard [PR] docs: live architecture hub — overall diagram + module pages with diagrams + file-map CI guard Nov 8, 2026
@ranxianglei
ranxianglei force-pushed the 2026-11-08_docs-centralization branch from 4d1c3c0 to f5269e4 Compare November 8, 2026 05:36
ranxianglei and others added 2 commits November 8, 2026 13:46
…rams, file-map CI guard (owner request 2026-11-08)
…NTS.md

Found during the #5924 conflict rebase: the hub commit added the same
Documentation Layout bullet twice (identical text back-to-back). Keep one.
@ranxianglei
ranxianglei force-pushed the 2026-11-08_architecture-docs branch from 78b94cc to 8d29ecd Compare November 8, 2026 05:50
…/architecture/assets/ (owner report: 整体架构不显示); guard now checks hub diagram links
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复 —— 本任务为既有 PR(上游 #5924)的合并冲突修复,未新建任何 issue/PR。

Conflict resolved. The PR (2026-11-08_architecture-docs) now merges cleanly into its base branch 2026-11-08_docs-centralization — verified live after push: mergeable: true, new head 8d29ecd5.

Root cause: the base branch had itself been rebased onto newer master meanwhile, so three of the PR's lower commits were already contained in the base (two byte-identical by patch-id; the centralization commit replaced by a strict superset absorbing master-side changes from #5918/#5921). Only the top hub commit was genuinely new.

What I did:

  • Cherry-picked only that one new commit onto the current base head (f5269e46) instead of replaying the stale ~9.4k-line diff (which risked duplicate-content partial application). Applied clean, original authorship preserved.
  • Found and fixed a small pre-existing defect in passing (separate labeled commit): the hub commit added the "Architecture docs are LIVE" bullet twice back-to-back in AGENTS.md → Documentation Layout; dropped the duplicate.
  • Pre-push verification: node tools/check-architecture-docs.mjs all green (file map covers all 305 src files, ledger↔page set matches, diagrams present, SVG well-formedness); .github/workflows/ci.yml parses as valid YAML; final diff vs base = exactly the intended 19 files (+1016/−2), nothing else.
  • Push discipline: fetched first, confirmed no concurrent pushes on the branch, force-pushed with --force-with-lease pinned to the old head.

Check state now (mirror cache): 7 file-gated e2e gate jobs queued after the push, 0 failed. Note: because the PR is stacked on a feature branch (not master), only these gated lanes fire at this stage; the full core matrix runs once the stack lands on master (#5920 first, then this one). If any gate turns red I'll pick it up on the next pass.


中文结构化结论(八问):

  1. 是什么问题:该 PR 与其目标分支冲突(GitHub merge state = dirty),无法合并。
  2. 什么原因导致的:目标分支自身被 rebase 到了更新的 master 上,PR 的 3 个底层提交已包含在目标分支内(其中 2 个按 patch-id 完全相同,1 个被含 master 侧变更的超集取代);PR 的旧 base 指针仍指向旧提交,git 因此判为冲突。真正的新内容只有顶部的 hub 提交。
  3. 影响范围与严重程度:仅影响本 PR 的可合并性(docs + CI guard 车道,无 src 行为变更);属「特定条件下有问题」——冲突存在期间 PR 不可合并;对运行时用户无影响。
  4. 怎么修复的:不做全量 rebase(避免重放过期 9.4k 行 diff 产生重复内容),只把唯一新提交 cherry-pick 到新 base 头上(干净落地、保留原作者);顺手修掉一个既有小缺陷(AGENTS.md 中 "Architecture docs are LIVE" 条目被 hub 提交连续加了两次,删其一,独立标注 commit);带 lease 保护的 force-push。
  5. 是否有回归问题:无。逐项核过:最终对 base 的 diff 仅含原计划 19 个文件(+1016/−2);新增的 architecture-docs guard 脚本本地全项通过;ci.yml YAML 解析通过;去重修复仅删一行纯文本重复、无语义变化。
  6. 是否破坏缓存:不涉及(纯文档 + CI workflow,未触碰缓存/重试/游标/去重逻辑)。
  7. 是否改了设计方向:不涉及(未改架构/边界/数据流,只是把 PR 恢复为可合并状态)。
  8. 是否引入了新的配置:不涉及(无新 env/config/默认值)。

判定:冲突已解决,PR 恢复可合并状态(checks 排队中,0 失败);合并与否由 owner 决定。

…ure/, hub is in docs/ (owner report: docs/storage.md 不存在)
…, hub is in docs/ (owner report: storage.md 404)
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] CI fix verified green ✓

- pipeline / lanes / kernel / identity / fastpaths / webui / update:
  en + zh-CN page each, structure = responsibility / principles / how it
  works / hard rules / key entries / related
- 14 module diagrams (svg primary + png fallback, one pair per module)
- hub ledger: all 8 rows active; CI guard checks the ledger <-> pages <->
  diagrams stay in lockstep
…, triage table to reference/triage.md (owner request 2026-11-08)
…deps; src/server/ + src/storage/ in module map, architecture-docs CI lane)
[PR] docs: slim AGENTS.md — KDD full text to reference/design-decisions.md, triage table to reference/triage.md
@ranxianglei
ranxianglei merged commit 88ecef4 into 2026-11-08_docs-centralization Nov 8, 2026
15 checks passed
ranxianglei pushed a commit that referenced this pull request Nov 10, 2026
The new src/fold-summary-ccr.ts module added by the #6111 POC must be listed
in reference/architecture.md or the architecture-docs CI lane fails (full-src
coverage guard, #5924). Adds the file-map row next to the other fold helpers.
ranxianglei pushed a commit that referenced this pull request Nov 10, 2026
)

The #5924 architecture-docs guard (landed on master via the branch sync)
requires every tracked src/ file in reference/architecture.md; the new block-ops
host executor module was added by this PR without its map row, so the guard
failed on the merged head. One-line registration next to the acp-* cluster;
guard passes locally (320 src files covered, no ghosts).
ranxianglei pushed a commit that referenced this pull request Nov 12, 2026
The new src/fold-summary-ccr.ts module added by the #6111 POC must be listed
in reference/architecture.md or the architecture-docs CI lane fails (full-src
coverage guard, #5924). Adds the file-map row next to the other fold helpers.
ranxianglei pushed a commit that referenced this pull request Nov 12, 2026
… the file map (#5767)

The new anthropic-lane Claude Code auto-compact detector landed without a
reference/architecture.md row, tripping the architecture-docs guard
(#5924). Add the file-map entry; it is a small support module under the
server/ group (no hub ledger row / module page needed, matching the other
per-lane guard modules).
ranxianglei pushed a commit that referenced this pull request Nov 13, 2026
The new src/fold-summary-ccr.ts module added by the #6111 POC must be listed
in reference/architecture.md or the architecture-docs CI lane fails (full-src
coverage guard, #5924). Adds the file-map row next to the other fold helpers.
ranxianglei pushed a commit that referenced this pull request Nov 15, 2026
The architecture-docs CI lane (tools/check-architecture-docs.mjs, #5924)
requires every tracked src/ file in the file map. The v6 lane added
src/server/fastpath-v6.ts and src/server/fastpath-v6-render.ts without
map rows, reding the lane on the merged head.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant