zn-ai/docs/Knowledge-Docs-Refactor-Plan.md

Knowledge 页面文档管理重构计划

1. 目标

本次重构不是继续扩展当前 Knowledge/index.tsx 里的“房型管理 / 事件管理”演示逻辑，也不是在旧页面里增加一个“文档 Tab”。

本次方案明确采用替换式重构：

1. 直接抛弃 Knowledge 现有功能
2. 直接删除 roomType / event 双业务模型
3. 直接把 Knowledge 页面改造成面向本地文档目录的管理页
4. 不做旧交互兼容，不保留旧状态，不做混合页过渡

产品需求：

1. 提供上传文件按钮
2. 上传文件保存到 zn-ai/docs 目录
3. 文件列表展示：
   • 文件名称
   • 文件大小
   • 修改日期
   • 文件类型
4. 每条文件支持删除
5. 视觉 UI 沿用当前 Knowledge 页和站内已有风格

一句话目标：

• 把 Knowledge 页面从“重业务 demo 页”直接替换成“本地 docs 目录文件管理页”。

2. 当前现状

2.1 渲染层现状

当前 src/pages/Knowledge/index.tsx 是一个单文件重页面，主要问题有：

1. 页面职责和产品目标不一致
   • 当前是 roomType / event 双 Tab
   • 上传行为只是 ImageManagerDialog 中的本地临时对象 URL
   • 没有真正写入主进程或磁盘
2. 页面状态过重
   • 房型列表、事件列表、图片管理、反馈提示都堆在一个文件里
3. 当前上传能力只是前端临时态
   • 使用 File + URL.createObjectURL
   • 刷新后数据丢失
   • 没有真正的文件列表 API

结论：

• 当前 Knowledge 页需要被整体替换，而不是增量补按钮。

2.2 主进程现状

当前主进程已经有本地 Host API 分发能力：

• electron/main.ts
• electron/api/router.ts

其中已有可复用的文件路由：

• electron/api/routes/files.ts

已有能力主要是：

1. /api/files/stage-buffer
   • 接收 base64
   • 写入 userData/openclaw-media/outbound
2. /api/files/stage-paths
   • 拷贝已有路径文件到暂存目录

这说明仓库已经接受“渲染层读文件 -> base64 -> Host API 落盘”的模式，Knowledge 重构可以沿用这条链路。

2.3 风格现状

当前 Knowledge 页可复用的视觉资产很明确：

1. 顶部大标题 + 副标题
2. 圆角胶囊按钮
3. 圆角卡片 / 表格容器
4. 浅色背景 + serif 标题
5. 轻量 feedback 提示条

所以 UI 不需要另起视觉体系，但只复用视觉语言，不复用旧业务结构。

2.4 迁移策略结论

这次不采用“兼容式迁移”，而采用“一刀切替换”：

1. /knowledge 路由保持不变
2. Knowledge/index.tsx 内部逻辑整体重写
3. 旧的 roomType / event / ImageManagerDialog 相关状态、组件、文案直接移除
4. 不保留旧功能入口
5. 不做旧数据迁移

3. 重构范围

3.1 渲染层范围

建议重构目标文件：

1. src/pages/Knowledge/index.tsx
   • 从单文件重业务页直接替换成 docs 文件管理页
2. src/pages/Knowledge/copy.ts
   • 新增文档管理相关文案
3. src/pages/Knowledge/types.ts
   • 删除旧 room/event 类型
   • 视情况改成 docs 列表类型，或直接移除
4. 新增 src/pages/Knowledge/components/*
   • KnowledgeDocsToolbar.tsx
   • KnowledgeDocsTable.tsx
   • KnowledgeDocsEmpty.tsx
   • KnowledgeDocDeleteButton.tsx

3.2 主进程范围

建议新增 / 修改：

1. 新增 electron/utils/knowledge-docs.ts
   • docs 根目录解析
   • 文件列表读取
   • 上传写入
   • 删除
   • 文件名安全校验
2. 新增 electron/api/routes/knowledge.ts
   • 暴露 Knowledge 专用 Host API
3. 修改 electron/api/router.ts
   • 注册 handleKnowledgeRoutes

3.3 测试范围

建议新增：

1. tests/knowledge-docs-routes.test.ts
2. tests/knowledge-page.test.tsx

4. 推荐目标结构

4.1 页面 IA

重构后的 Knowledge 页面建议只有一层核心任务流：

1. 顶部标题区
   • Knowledge Management
   • 副标题
   • 刷新
   • 上传文件
2. 列表区
   • 文件总数卡片或摘要
   • 文档表格
3. 空态 / 错误态
4. 删除确认

明确删除：

1. roomType / event Tab
2. EventDialog
3. ImageManagerDialog
4. 事件图片本地临时态
5. 房型映射查询能力

4.2 前端组件拆分建议

推荐拆法：

1. KnowledgePage
   • 页面壳
   • 拉取列表
   • 调度上传 / 删除 / 刷新
2. KnowledgeDocsToolbar
   • 上传按钮
   • 刷新按钮
   • 简要统计
3. KnowledgeDocsTable
   • 表头
   • 行渲染
4. KnowledgeDocsEmpty
   • 空态
5. useKnowledgeCopy
   • 补齐新文案，不另起 i18n 体系

注意：

• 这里的组件拆分是为了替代旧页面，不是为了与旧功能并存。

4.3 主进程模块拆分建议

推荐拆法：

1. knowledge-docs.ts
   • getKnowledgeDocsDir()
   • listKnowledgeDocsFiles()
   • saveKnowledgeDocsFile()
   • deleteKnowledgeDocsFile()
2. routes/knowledge.ts
   • GET /api/knowledge/docs
   • POST /api/knowledge/docs
   • DELETE /api/knowledge/docs/:name

这样可以避免把 Knowledge 领域继续塞进通用 files.ts，后续如果增加“重命名 / 下载 / 打开目录”，也更好扩展。

5. 推荐数据契约

5.1 列表项结构

建议前端使用以下结构：

interface KnowledgeDocItem {
  name: string;
  size: number;
  modifiedAt: string;
  type: string;
}

字段解释：

1. name
   • 文件名，作为主键展示
2. size
   • 字节数，前端转成 KB / MB
3. modifiedAt
   • ISO 时间字符串
4. type
   • 优先用扩展名，例如 md / pdf / json
   • 无扩展名时回退为 unknown

5.2 Host API 设计

推荐 API：

GET /api/knowledge/docs

返回：

{
  success: true,
  files: KnowledgeDocItem[]
}

POST /api/knowledge/docs

请求体：

{
  fileName: string;
  base64: string;
  mimeType?: string;
}

返回：

{
  success: true,
  file: KnowledgeDocItem
}

DELETE /api/knowledge/docs/:name

返回：

{
  success: true
}

5.3 上传链路建议

推荐复用当前 chat store 已采用的模式：

1. 渲染层通过 input[type=file] 选中文件
2. FileReader.readAsDataURL
3. 取出 base64
4. 调用 POST /api/knowledge/docs
5. 主进程写入 zn-ai/docs
6. 刷新列表

原因：

1. 与现有 src/stores/chat.ts 的上传思路一致
2. 不依赖浏览器侧暴露绝对路径
3. 更适配现在的 hostapi:fetch JSON body 结构

6. 文件系统策略

6.1 目标目录

产品要求是写入 zn-ai/docs，建议在开发阶段明确采用仓库目录：

path.join(process.cwd(), 'docs')

注意：

1. 这满足当前本地开发诉求
2. 但在打包态里，app.getAppPath() 目录通常不适合作为可写目录

所以建议把这条约束写死在 Phase 0 决策里：

1. 当前版本按“开发工作区 docs 目录”实现
2. 若未来进入打包态，再增加 fallback：
   • userData/knowledge-docs

6.2 安全约束

主进程必须加的边界：

1. 禁止路径穿越
   • 只允许文件名，不允许相对路径
2. 删除时二次校验目标文件真实路径仍在 docs 根目录内
3. 文件名规范化
   • 去掉控制字符
   • 过滤危险分隔符
4. 默认不覆盖已有文件
   • 推荐同名自动追加后缀
   • 例如 foo.md -> foo-1.md

6.3 排序与展示规则

建议默认按 modifiedAt 倒序展示，让最新上传或最近修改的文件排最前。

7. 具体实施计划

Phase 0：替换边界冻结

目标：

• 先冻结“替换式重构”的边界，避免后续又回到兼容旧功能的路线。

产出：

1. 确定页面只保留“文档上传 + 列表 + 删除”
2. 确定 docs 目录路径策略
3. 确定列表项结构
4. 确定上传冲突策略
5. 确定旧 roomType/event 代码直接下线

完成标准：

• 渲染层、主进程、测试都基于同一套字段命名
• 不再保留任何旧业务能力的开发任务

Phase 1：主进程与文件能力

目标：

• 先让本地 docs 目录具备可读、可写、可删能力。

交付：

1. 新增 electron/utils/knowledge-docs.ts
2. 新增 electron/api/routes/knowledge.ts
3. 在 electron/api/router.ts 接入新路由
4. 支持：
   • list
   • upload
   • delete

完成标准：

• 不依赖前端 mock，即可从主进程拿到真实 docs 列表

Phase 2：渲染层替换

目标：

• 把 Knowledge/index.tsx 从 demo 页整体替换成文件管理页。

交付：

1. 删除旧的 room/event 双 Tab 结构与相关状态
2. 新增上传按钮与隐藏文件输入
3. 新增文件表格
4. 新增删除操作和确认
5. 保留当前视觉语言

完成标准：

• 页面刷新后仍能看到真实文件列表
• 上传与删除可以闭环

Phase 3：验证与收口

目标：

• 补齐最基本的回归保护。

交付：

1. 主进程 route / util 测试
2. 页面交互测试
3. 手动 smoke checklist

完成标准：

• 上传、刷新、删除、空态、异常态都可验证

8. sub-agent 数量估算

由于这次采用“直接抛弃旧功能”的替换式重构，复杂度比“兼容旧页面并逐步迁移”明显更低，sub-agent 编制也可以相应收缩。

8.1 最小编制：3 个 sub-agent

适合当前任务，也已经足够覆盖主链路：

1. 渲染层 owner
2. 主进程 / 文件系统 owner
3. 测试 / 联调 owner

推荐原因：

1. 已经没有旧功能兼容成本
2. 页面职责单一
3. API 面很小
4. 测试面可控

8.2 推荐编制：3 个 sub-agent

推荐采用：

1. Agent A：Knowledge 页面壳与视觉对齐
2. Agent B：主进程 docs 文件服务与 Host API
3. Agent C：测试、copy、前后端收口

结论：

• 对这次 Knowledge 替换式重构，推荐 3 个 sub-agent + 1 个主控 Codex。

8.3 峰值编制：4 个 sub-agent

仅在想压缩工期时启用：

1. Agent A：页面壳
2. Agent B：文件服务
3. Agent C：Host API 路由
4. Agent D：测试 / copy / 收口

不建议长期保持 4 个，因为当前任务已经不再需要兼容旧功能，继续加人收益很有限。

9. 推荐 sub-agent 分工

Agent A：渲染层 Owner

负责文件：

1. src/pages/Knowledge/index.tsx
2. src/pages/Knowledge/components/*

职责：

1. 页面布局重构
2. 上传按钮与刷新按钮
3. 文件表格与空态
4. 删除确认
5. 保持当前视觉风格

Agent B：主进程 docs 文件服务 Owner

负责文件：

1. electron/utils/knowledge-docs.ts
2. electron/api/routes/knowledge.ts
3. electron/api/router.ts

职责：

1. 解析 zn-ai/docs 路径
2. 列出文件元数据
3. 保存文件
4. 删除文件
5. 文件名安全与根目录校验
6. 暴露 list / upload / delete 的本地 Host API

Agent C：测试 / copy / 前后端收口 Owner

负责文件：

1. src/pages/Knowledge/copy.ts
2. 可选新增 src/lib/knowledge-docs-api.ts
3. tests/knowledge-docs-routes.test.ts
4. tests/knowledge-page.test.tsx
5. docs/* 中的 smoke checklist

职责：

1. 补齐文案
2. 连接 FileReader -> base64 -> hostApiFetch
3. 校验上传
4. 校验删除
5. 校验空态 / 错误态
6. 校验文件元数据展示
7. 保证前后端字段一致

10. 并行推进顺序

建议按下面顺序推进：

1. Agent B 先完成文件服务
2. 主控 Codex / Agent B 接上 Host API 契约
3. Agent A 在 API 稳定后整体替换页面
4. Agent C 最后补测试、copy 与回归

原因：

• 这次需求本质上是“主进程文件能力先行，渲染层消费其结果”，而且旧页面不再需要兼容。

11. 风险与决策点

1. zn-ai/docs 目录写入策略
   • 当前需求明确指向仓库目录
   • 打包态写入需要后续额外决策
2. 同名文件冲突
   • 建议先采用“自动追加后缀，不覆盖原文件”
3. 大文件上传
   • 走 base64 会增加体积
   • 本期只要满足常规文档文件即可
4. 页面是否保留旧房型 / 事件能力
   • 本计划已明确直接移除，不做混合页

12. 验收标准

重构完成后，至少满足：

1. Knowledge 页能从主进程读取 zn-ai/docs 真实文件
2. 用户可上传文件到 zn-ai/docs
3. 列表展示：
   • 文件名称
   • 文件大小
   • 修改日期
   • 文件类型
4. 用户可删除文件
5. 页面风格与当前 Knowledge 页一致
6. 页面刷新后状态不丢失
7. 主进程具备基本路径安全校验

13. 当前建议结论

这次任务不适合在现有 Knowledge/index.tsx 上继续堆条件分支，也不适合保留旧功能做过渡。

最合理的推进方式是：

1. 直接下线 Knowledge 现有房型 / 事件功能
2. 把 Knowledge 页面整体替换成单一职责的 docs 文件管理页
3. 新增专门的 knowledge-docs 主进程文件服务
4. 用本地 Host API 打通上传、列表、删除
5. 用 3 个 sub-agent 作为推荐编制推进开发

这样改动面最小、职责边界最清晰，也最符合当前仓库已经建立起来的本地 Host API 架构。