feat(desktop): embed BoosAPI Desktop client as a subproject
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
This commit is contained in:
boos
@@ -0,0 +1,127 @@
|
||||
---
|
||||
description: 按症状定位 markstream-vue 的 CSS 顺序、peer 依赖、SSR、自定义标签与流式性能问题。
|
||||
---
|
||||
|
||||
# 按症状排查
|
||||
|
||||
当你知道“哪里不对”，但还不确定问题到底是 CSS 顺序、peer 依赖、SSR 边界、自定义标签接法，还是渲染器选择不当时，就先从这页开始。
|
||||
|
||||
如果你已经明确知道是哪一层出了问题，也可以直接跳到每个分支下面链接过去的深度页面。
|
||||
|
||||
## 先按你看到的现象分流
|
||||
|
||||
| 你看到的问题 | 先看这里 | 然后看 |
|
||||
| --- | --- | --- |
|
||||
| 样式错乱、间距不对、Tailwind 抢样式 | [样式错乱？先做这几件事](/zh/guide/troubleshooting#css-looks-wrong-start-here) | [Tailwind 集成与样式顺序](/zh/guide/tailwind) |
|
||||
| `<thinking>` 这类可信标签被当成原生 HTML | [文档站与 VitePress 集成](/zh/guide/vitepress-docs-integration) 或 [自定义标签与高级组件](/zh/guide/custom-components) | [API 参考](/zh/guide/api) |
|
||||
| `window is not defined` 或浏览器专属依赖在 SSR 崩掉 | [排查问题](/zh/guide/troubleshooting) | [Nuxt SSR](/zh/nuxt-ssr) |
|
||||
| Mermaid、KaTeX、Monaco、D2 没有渲染出来 | [安装](/zh/guide/installation) | [渲染器与节点组件](/zh/guide/components) |
|
||||
| 聊天输出卡、频繁重解析、长内容越来越慢 | [AI 聊天与流式输出](/zh/guide/ai-chat-streaming) | [性能](/zh/guide/performance) |
|
||||
| 内置节点形态不适合业务 | [覆盖内置组件](/zh/guide/component-overrides) | [渲染器与节点组件](/zh/guide/components) |
|
||||
|
||||
## 1. 样式看起来不对
|
||||
|
||||
常见现象：
|
||||
|
||||
- 段落、表格、列表间距很奇怪
|
||||
- 代码块、图片、引用像是没吃到样式
|
||||
- Tailwind / UnoCSS 把渲染器样式盖掉了
|
||||
|
||||
按这个顺序检查：
|
||||
|
||||
1. reset 是否在 `markstream-vue/index.css` 之前导入
|
||||
2. 用了 Tailwind / UnoCSS 时，CSS 是否放在 `@layer components`
|
||||
3. 如果启用了数学公式，是否导入了 `katex/dist/katex.min.css`
|
||||
4. 如果渲染器嵌在大系统里，是否用 `custom-id` 做了作用域隔离
|
||||
|
||||
先从 CSS 清单开始： [排查问题](/zh/guide/troubleshooting#css-looks-wrong-start-here)
|
||||
|
||||
## 2. 自定义标签或自定义组件没有生效
|
||||
|
||||
常见现象：
|
||||
|
||||
- `<thinking>` 被原样输出成 HTML
|
||||
- 自定义 Vue 组件一直没有渲染
|
||||
- 某个页面能用，换个地方就失效
|
||||
|
||||
按这个顺序检查：
|
||||
|
||||
1. 标签是否加入了 `custom-html-tags`
|
||||
2. 是否用 `setCustomComponents(customId, mapping)` 注册了映射
|
||||
3. 页面渲染时是否传了匹配的 `custom-id`
|
||||
4. 如果你在 VitePress 里，注册逻辑是否放在 `enhanceApp`
|
||||
|
||||
最适合继续看的路径：
|
||||
|
||||
- 文档站 / 主题场景： [文档站与 VitePress 集成](/zh/guide/vitepress-docs-integration)
|
||||
- 应用内自定义标签： [自定义标签与高级组件](/zh/guide/custom-components)
|
||||
|
||||
## 3. SSR 报错或浏览器专属依赖崩掉
|
||||
|
||||
常见现象：
|
||||
|
||||
- `window is not defined`
|
||||
- Mermaid / Monaco 本地能跑，但 SSR 环境报错
|
||||
- 服务端和客户端 hydration 对不上
|
||||
|
||||
按这个顺序检查：
|
||||
|
||||
1. 先确认出问题的 peer 是否本来就只能在浏览器里运行
|
||||
2. 把这部分初始化放到 client-only 边界之后
|
||||
3. 让基础 `MarkdownRender` 仍然走服务端安全路径
|
||||
|
||||
最适合继续看的路径：
|
||||
|
||||
- 通用检查项： [排查问题](/zh/guide/troubleshooting)
|
||||
- Nuxt 专用规则： [Nuxt SSR](/zh/nuxt-ssr)
|
||||
|
||||
## 4. 重型能力没有渲染出来
|
||||
|
||||
常见现象：
|
||||
|
||||
- Mermaid fence 只显示源码
|
||||
- 数学公式是空白
|
||||
- Monaco 代码块是空的
|
||||
- D2 退回成原始文本
|
||||
|
||||
这类问题多数不是 parser 出错，而是下面几类原因：
|
||||
|
||||
- peer 依赖没装
|
||||
- 必需 CSS 没导，尤其是 KaTeX
|
||||
- SSR 或 worker 边界处理不对
|
||||
|
||||
先从 [安装](/zh/guide/installation) 开始，再去 [渲染器与节点组件](/zh/guide/components) 对照各组件的注意事项。
|
||||
|
||||
## 5. 流式输出或聊天界面越来越慢
|
||||
|
||||
常见现象：
|
||||
|
||||
- 每来一个 token 页面就明显抖动
|
||||
- 长聊天记录越来越重
|
||||
- 每次更新都在整篇重解析 Markdown
|
||||
|
||||
这类问题通常不是“调个样式”能解决的，而是接法需要调整：
|
||||
|
||||
- 把解析移到 `MarkdownRender` 外部
|
||||
- 改用 `nodes` + `final`
|
||||
- 重型 peers 按需启用，不要默认全开
|
||||
|
||||
最适合继续看的路径： [AI 聊天与流式输出](/zh/guide/ai-chat-streaming)，再配合 [性能](/zh/guide/performance)
|
||||
|
||||
## 6. 还是拿不准？
|
||||
|
||||
如果你还无法判断是哪一层的问题：
|
||||
|
||||
1. 先在 playground 里用最小 Markdown 示例复现
|
||||
2. 暂时去掉可选 peers，把问题缩小
|
||||
3. 对照最接近的场景页：
|
||||
`文档站与 VitePress 集成`、`AI 聊天与流式输出`、`使用与流式渲染`
|
||||
|
||||
如果最后看起来确实像 bug，再准备这些信息：
|
||||
|
||||
- 最小 Markdown 示例
|
||||
- 框架 / 运行时信息
|
||||
- 是否用了 Tailwind、UnoCSS、SSR
|
||||
- 当前安装了哪些可选 peers
|
||||
|
||||
然后再使用 [排查问题](/zh/guide/troubleshooting) 里的测试页或 issue 链接。
|
||||
Reference in New Issue
Block a user