mirror of
https://github.com/CherryHQ/cherry-studio.git
synced 2026-07-05 13:47:59 +08:00
c514dcc049
packages/shared was never a real pnpm workspace package (no package.json); it was referenced only through the @shared TypeScript path alias. Relocate it under src/ via git mv (143 files, detected as pure renames).
Repoint the @shared alias and include globs to src/shared across electron.vite.config.ts, tsconfig.{json,node,web}.json and vitest.config.ts; update scripts/check-custom-exts.ts, scripts/update-languages.ts, the eslint.config.mjs generated-file globs, the data-classify generator output targets, .github/CODEOWNERS path rules, and CLAUDE.md/docs/source-comment references.
The @shared alias name is unchanged, so all 1403 @shared/* import sites resolve without modification. Verified with typecheck:node, typecheck:web and the full test suite (700 files, 9739 tests passing).
4.3 KiB
4.3 KiB
Knowledge UI V2 重构约束
本文档只记录 Knowledge V2 UI 重构的硬约束，用于统一组件结构、数据边界和协作方式。
它不定义任何未确认的视觉稿、交互稿或页面细节。
1. 组件结构设计约束
- Knowledge V2 UI 实现统一使用 Tailwind CSS +
@cherrystudio/ui（cherry-ui）。 - Knowledge V2 UI 优先复用
@cherrystudio/ui已有的 primitive / composite 组件，不在业务页面中直接实现一套新的基础 UI。 - 对按钮、输入框、下拉、文本域、弹层、标签页、滚动容器等基础交互，优先使用 cherry-ui 组件，不直接使用原生组件作为业务实现方案。
- 如果 cherry-ui 暂时缺少所需能力，优先补齐
@cherrystudio/ui或先回到设计 / 组件层确认，不接受在 Knowledge V2 UI 中直接回退到原生基础组件的临时方案。 - UI 文件结构设计优先遵循
vercel-composition-patterns。 - Knowledge V2 UI 优先采用 composition-first 的组织方式，优先考虑 compound components、清晰的 slot / children 组合，以及必要时的 provider + context 接口。
- 避免在单一组件中通过大量布尔 props 或模式开关堆叠分支逻辑。
- 同一类 UI 变体优先使用显式变体组件或独立子组件，而不是继续扩展
isXxx、showXxx、variant === ...这类隐式分支。 - 状态组装与展示职责分离：容器层负责组装数据和行为，展示层只消费清晰、稳定的接口。
2. Hook 使用约束
- Knowledge V2 UI 的 hooks 统一切换到
useKnowledge.v2。 - 新 UI 不再继续依赖现有
useKnowledge的旧实现，也不再围绕旧 knowledge 数据流做结构设计。 - 旧 hook 仅作为迁移参考，不再作为 V2 UI 的扩展基础。
3. 数据来源与字段边界约束
- Knowledge V2 UI 的数据模型与字段边界以
src/main/data/db/schemas/knowledge.ts为准。 - Knowledge V2 UI 的 renderer 侧领域类型统一复用
src/shared/data/types/knowledge.ts，不再在页面目录重复定义 knowledge base 主数据类型。 - 知识库与知识项相关 UI，应围绕
knowledge_base与knowledge_item的 SQLite 结构来设计和实现。 - 不再使用原先 Redux knowledge 数据作为事实来源。
- 任何旧实现中存在、但不在
knowledge.ts中稳定定义的字段，不应继续作为 V2 UI 的设计前提。 itemCount、知识库级status等列表展示字段属于基于knowledge_item的派生聚合结果，不属于knowledge_base主数据。- 当前语义下，“删除分组”只删除 group 本身，不删除分组下的 knowledge base。
- 分组删除后，关联的 knowledge base 应回到 ungrouped；在产品语义重新确认前，不得把“删除分组”实现或文案扩展为“同时删除该分组下所有 base”。
当前暂留问题：创建 / 重建知识库时的 dimensions
- 当前 renderer 创建知识库、重建迁移失败知识库时仍暂时硬编码
dimensions。 - 后续应改为从选中的 embedding model 或上游模型能力解析出维度，避免 renderer 侧继续维护固定值。
- 在该上游能力明确前，RAG 配置面板中的 embedding model 与 dimensions 只做只读展示，不允许在 renderer 中直接修改。
4. UI 确认约束
- 一切未确认的 UI 不得自行添加。
- 任何新增布局、视觉元素、交互入口、状态展示、批量操作或信息区块，在没有确认 UI 稿前都不进入 V2 范围。
- 如果实现过程中遇到 UI 稿缺口，应先回到设计确认，再继续落地。
- 当前文档只定义重构边界，不代表具体页面方案已经确认。
5. UI 稿勘查约束
- ui参考稿 https://pecan-stool-05054889.figma.site/
- 当 Knowledge V2 UI 的参考稿来自网页或 Figma Site 时，优先使用
.agents/skills/knowledge-v2-ui/SKILL.md。 - 该 skill 用于通过
opencli打开页面、进入侧边栏知识库标签、提取已确认的 UI 结构，并将结果整理为可实现的界面拆分说明。 - 对网页 UI 稿的分析结论，应只基于页面中实际可见、可验证的元素，不得补全未确认的视觉或交互细节。
- 如果页面中存在同名节点、结构歧义或未暴露的交互入口，应先记录歧义并回到 UI 确认，而不是自行推断。