Skip to content

Commit 5f27632

Browse files
JacobinwweyJacobinwwey
committed
chore: sync documentation and reader runtime updates
1 parent 8f945db commit 5f27632

18 files changed

Lines changed: 1449 additions & 9 deletions

‎AGENTS.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,16 @@ Android (Windows): run `build_apk.bat` (requires Node.js, Java JDK 17+, and Andr
3434
- **TypeScript `strict`**: Enabled natively (`tsconfig.json`). Keep public APIs rigorously typed to prevent parsing failures at the IPC/WebSocket boundary.
3535
- **Naming Pattern**: `PascalCase.ts` with matching `PascalCase.test.ts` for modules. Godot prefers standard `snake_case` patterns for GDScript.
3636

37+
## Mermaid Compatibility Baseline (Obsidian)
38+
39+
- Canonical Mermaid authoring format is Obsidian fenced Markdown: a standalone line starting with \`\`\`mermaid and a standalone closing \`\`\`.
40+
- This fenced format must remain render-compatible across Web reader, Tauri runtime, and Godot reader flows.
41+
- `$$```mermaid` (or any non-line-start Mermaid fence concatenation) is treated as malformed content and must be fixed at source data level.
42+
- Default remediation for `$$```mermaid`: split into two lines (`$$` then ` ```mermaid`), or run `npm run fix:markdown:mermaid:fence -- Knowledge_Base/testconcept`.
43+
- Reader runtime guardrail: on Markdown reader open, run lightweight self-check and auto-heal `$$```mermaid` to `$$` + newline + ` ```mermaid` before rendering.
44+
- Godot Mermaid runtime path must use renderer preference that allows fallback (`auto`), so missing frontend bridge does not break diagram display.
45+
- Any interface/runtime change touching markdown parsing or Mermaid rendering must preserve this baseline and re-verify it on `Knowledge_Base/testconcept`.
46+
3747
## Testing Guidelines
3848

3949
- Framework: Jest with `ts-jest` arrayed in `jest.config.js`.

‎README.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -309,14 +309,21 @@ index_cache_ttl_sec = 1800
309309
max_doc_bytes = 100663296
310310
```
311311

312-
### Markdown Reader Protocol (v1.6.6)
312+
### Markdown Reader Protocol (v1.6.8)
313313

314314
- **Dual-engine gray release**:
315315
- `markdown_engine = "auto"`: prefer `pulldown-cmark`, fallback to legacy on failure.
316316
- `markdown_engine = "pulldown"`: keep automatic fallback to legacy to avoid blank readers.
317317
- `markdown_engine = "legacy"`: force original parser path.
318318
- **Unified cross-window behavior**: Tauri reader and Godot reader now both consume the same sidecar markdown protocol (`index/chunk/resolve-node/resolve-wiki`).
319319
- **Large file stability**: reader no longer requires single-shot full markdown payloads and supports block-based incremental loading.
320+
- **Mermaid reliability hardening**:
321+
- Godot reader Mermaid rendering now uses `renderer = "auto"` so it can prefer frontend bridge and automatically fallback to local `resvg` when bridge render is unavailable.
322+
- Mermaid fences must start on a new line; inline `$$```mermaid` patterns can break block classification.
323+
- Use `npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept` to catch malformed inline Mermaid fences before release.
324+
- **Local MCP web-debug baseline (Runbrowser)**:
325+
- Build locally from source: `pnpm --filter @jiweiyuan/runbrowser-server build`, `pnpm --filter @jiweiyuan/runbrowser-core build`, `pnpm --filter @jiweiyuan/runbrowser-mcp build`.
326+
- Run local MCP entrypoint: `node E:\Knowledge_project\tools\runbrowser\packages\mcp\bin.js`.
320327
321328
## 🏗️ Build & Deployment
322329
@@ -1242,14 +1249,21 @@ index_cache_ttl_sec = 1800
12421249
max_doc_bytes = 100663296
12431250
```
12441251
1245-
### Markdown 阅读协议（v1.6.6）
1252+
### Markdown 阅读协议（v1.6.8）
12461253
12471254
- **双引擎灰度发布**：
12481255
- `markdown_engine = "auto"`：优先 `pulldown-cmark`，失败自动回退 legacy。
12491256
- `markdown_engine = "pulldown"`：仍保留自动回退 legacy，避免阅读器空白。
12501257
- `markdown_engine = "legacy"`：强制使用旧解析链路。
12511258
- **双窗口统一行为**：Tauri 阅读器与 Godot 阅读器都统一消费 sidecar Markdown 协议（`index/chunk/resolve-node/resolve-wiki`）。
12521259
- **大文档稳定性提升**：阅读链路不再依赖单次整文全量载入，改为块级增量加载。
1260+
- **Mermaid 稳定性加固**：
1261+
- Godot 阅读器 Mermaid 渲染已切换为 `renderer = "auto"`，优先走前端桥接渲染，桥接不可用时自动回退本地 `resvg`。
1262+
- Mermaid fenced code 必须独占新行起始；`$$```mermaid` 这类行内拼接会导致分块识别失败。
1263+
- 发布前可执行 `npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept`，提前拦截异常 Mermaid fence。
1264+
- **本地 MCP 网页调试基线（Runbrowser）**：
1265+
- 建议按源码本地构建：`pnpm --filter @jiweiyuan/runbrowser-server build`、`pnpm --filter @jiweiyuan/runbrowser-core build`、`pnpm --filter @jiweiyuan/runbrowser-mcp build`。
1266+
- 本地 MCP 入口：`node E:\Knowledge_project\tools\runbrowser\packages\mcp\bin.js`。
12531267
12541268
## 🏗️ 构建与部署 (Build & Deployment)
12551269

‎docs/diataxis-map.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,18 @@
6262
"diataxis": "docs/diataxis/zh/how-to/configure-app-config.md"
6363
}
6464
},
65+
{
66+
"id": "godot-notemd-markdown-workflows",
67+
"category": "how-to",
68+
"en": {
69+
"canonical": ["docs/en/User_Manual.md", "docs/en/Interface Document.md"],
70+
"diataxis": "docs/diataxis/en/how-to/godot-notemd-markdown-workflows.md"
71+
},
72+
"zh": {
73+
"canonical": ["docs/zh/User_Manual.md", "docs/zh/Interface Document.md"],
74+
"diataxis": "docs/diataxis/zh/how-to/godot-notemd-markdown-workflows.md"
75+
}
76+
},
6577
{
6678
"id": "interfaces-and-runtime",
6779
"category": "reference",
@@ -74,6 +86,18 @@
7486
"diataxis": "docs/diataxis/zh/reference/interfaces-and-runtime.md"
7587
}
7688
},
89+
{
90+
"id": "godot-notemd-markdown-interfaces",
91+
"category": "reference",
92+
"en": {
93+
"canonical": ["docs/en/Interface Document.md", "docs/en/User_Manual.md"],
94+
"diataxis": "docs/diataxis/en/reference/godot-notemd-markdown-interfaces.md"
95+
},
96+
"zh": {
97+
"canonical": ["docs/zh/Interface Document.md", "docs/zh/User_Manual.md"],
98+
"diataxis": "docs/diataxis/zh/reference/godot-notemd-markdown-interfaces.md"
99+
}
100+
},
77101
{
78102
"id": "app-config-schema",
79103
"category": "reference",

‎docs/diataxis/en/explanation/startup-node-update-acceleration-plan.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Startup Node Update Acceleration Plan (Cross-Platform + Windows Pilot)
2+
3+
## Context
4+
5+
This document solidifies the optimization strategy for improving node initialization/update speed after app launch.
6+
7+
Scope:
8+
- Frontend graph startup path (`src/frontend/app.js`)
9+
- Simulation worker tick/update path (`src/frontend/simulationWorker.js`)
10+
- Runtime profiles across desktop and mobile runtimes
11+
12+
## 1) Problem Definition
13+
14+
Users experience slow perceived startup because the first interactive graph frame and first stable layout arrive too late.
15+
16+
System-level startup latency model:
17+
18+
`T_start = T_data_prepare + T_worker_init + T_tick_transfer + T_first_interactive_render + T_settle`
19+
20+
Primary user-facing KPIs:
21+
- `TTI` (Time to Interactive graph)
22+
- `TFS` (Time to First Stable readable layout)
23+
- Startup frame-drop rate in first 3 seconds
24+
25+
## 2) Hypotheses
26+
27+
1. Full-payload tick transfer (`all nodes every tick`) is a major startup bottleneck.
28+
2. Full edge rendering in the first 0.3–1.2s adds heavy cost with limited user value.
29+
3. Missing persisted layout snapshots forces repeated cold-start relaxation.
30+
4. Platform runtimes (Windows/macOS/Android WebView) need different startup limits.
31+
32+
## 3) Constraints and Unknowns
33+
34+
### Constraints
35+
- Must keep behavior consistent across Tauri desktop and APK runtime.
36+
- Must not break existing focus/highlight/path mode interactions.
37+
- Must remain rollback-safe with feature flags.
38+
39+
### Unknowns
40+
- Current P50/P95 startup metrics are not centrally collected.
41+
- Device capability distribution per platform is not yet quantified.
42+
43+
## 4) Subproblem Decomposition
44+
45+
1. Data preparation cost on main thread.
46+
2. Worker initialization + simulation settle speed.
47+
3. Worker→UI transfer volume and frequency.
48+
4. Startup render strategy (nodes-first vs edges-first).
49+
5. Warm-start memory (layout snapshot persistence).
50+
51+
## 5) Three Candidate Options
52+
53+
### Option A: Quick Throttle + Staged Rendering
54+
- Add startup edge delay.
55+
- Cap tick frequency.
56+
- Keep protocol unchanged.
57+
58+
Expected gain: medium (fast to deliver, low risk).
59+
60+
### Option B: Balanced Target (Recommended)
61+
- Option A +
62+
- Add persisted layout snapshots (warm start).
63+
- Add delta tick transfer strategy (or reduced-frequency transfer).
64+
- Add platform runtime profiles.
65+
66+
Expected gain: high with manageable risk.
67+
68+
### Option C: Deep Architecture Refactor
69+
- Shared memory + binary graph pipeline + renderer overhaul.
70+
71+
Expected gain: highest, but high risk and long timeline.
72+
73+
## 6) Comparison
74+
75+
| Dimension | Option A | Option B (Recommended) | Option C |
76+
|---|---|---|---|
77+
| Delivery speed | Fast | Medium | Slow |
78+
| Risk | Low | Medium | High |
79+
| Cold-start improvement | Medium | High | Very high |
80+
| Warm-start improvement | Low | Very high | Very high |
81+
| Multi-platform feasibility (v1) | High | High | Medium |
82+
83+
## 7) Chosen Direction
84+
85+
Choose **Option B**, delivered in phases with rollback switches.
86+
87+
Reason:
88+
- Strong performance upside without architectural disruption.
89+
- Explicitly supports runtime profile tuning per platform.
90+
- Suitable for a Windows-first pilot before broader rollout.
91+
92+
## 8) Execution Plan
93+
94+
### Phase 0: Instrumentation Baseline
95+
- Add startup timeline logs:
96+
- `T0 app_boot`
97+
- `T1 graph_preprocessed`
98+
- `T2 worker_init_sent`
99+
- `T3 first_tick_received`
100+
- `T4 first_interactive_render`
101+
- `T5 stable_layout`
102+
103+
### Phase 1: Windows Pilot v1 (low-risk)
104+
- Add runtime startup profile selection.
105+
- Add worker tick rate cap.
106+
- Add startup edge render delay.
107+
- Add startup link render cap (optional guard).
108+
109+
### Phase 2: Warm Start
110+
- Persist per-graph layout snapshot keyed by graph fingerprint.
111+
- Restore snapshot on startup and run low-alpha stabilization.
112+
113+
### Phase 3: Delta Transfer
114+
- Reduce transfer volume via delta-only tick payload or lower-frequency full payload.
115+
116+
## 9) Risk Points and Mitigation
117+
118+
1. Stale snapshot mismatch:
119+
- Mitigation: strict graph fingerprint validation + fallback to cold start.
120+
2. Over-throttling in low-end devices:
121+
- Mitigation: per-platform profile overrides and fast rollback.
122+
3. Rendering incompleteness perception when edges are delayed:
123+
- Mitigation: short delay window + status hint + progressive edge restore.
124+
125+
## 10) v1 Optimization Spec (Windows Pilot)
126+
127+
### Runtime Profile (pilot default)
128+
- Profile ID: `desktop_windows_pilot`
129+
- Worker tick cap: `24–30 FPS`
130+
- Edge render delay: `~400ms`
131+
- Startup partial edge cap window: `first 1500ms`
132+
133+
### Success Criteria
134+
- `TTI` improvement >= 30% vs baseline median.
135+
- `TFS` improvement >= 20% vs baseline median.
136+
- Startup 3s frame-drop reduction >= 30%.
137+
138+
### Rollback Gates
139+
- Any startup regression > 10% on P95.
140+
- Any reproducible interaction regression (focus/path mode/reader).
141+

0 commit comments

Comments
 (0)