来源：halo-kb/知识库架构设计.md → ### C.4 批量导入本地 Markdown 的可行路径（原文 1430 字符）

C.4 批量导入本地 Markdown 的可行路径

已核实的结论：导入是可行的，但有明确边界。

排序	路径	端点/命令	状态
① 推荐	minidocs-cli 命令行批量导入	minidocs doc import <kb> --files a.md,b.md [--parent <docName>]，前置 minidocs auth login --url <站点> --auth-type bearer --token <PAT>	已验证（commands.md + npm 上存在 minidocs-cli@2026.9.9，bin minidocs，Node >= 22）
② 可行	Console API 直调	POST /apis/console.api.minidocs.halo.run/v1alpha1/knowledgebases/{name}/docs/import（multipart）	端点已验证；multipart 表单字段名未确认
③ 可行但有风险	标准 CRUD 直写扩展资源	POST /apis/minidocs.halo.run/v1alpha1/knowledgebasedocs	端点已验证；只写 raw 而不写 content（HTML）是否导致阅读页空白，未确认——content 由插件前端编辑器生成
④ 不可行	把本地 Markdown 目录打包成 ZIP 导入	/knowledgebases/import	已验证的否定结论：README 明确"导入知识库仅支持本插件导出的 ZIP 包"，自制目录（无 config.json）会被忽略
⑤ 兜底	后台手工粘贴	插件自带 Markdown 编辑器	必然可行，无需验证

必需的前置条件（缺一即不可行）：

1. KnowledgeBase 必须先存在——CLI/API 导入都要求目标知识库已有 slug 或 metadata.name；
2. 导入的文档默认是 draft（草稿），需要额外执行发布（CLI doc publish，或 API POST .../{docName}/publish），否则前台看不到；
3. CLI 需要 Halo 的 PAT（个人令牌）——请在 Halo 控制台「个人中心 → 个人令牌」创建，不要把令牌写进任何文件或本报告。

建议的落地顺序：先手工在后台建好 C.2 的分组节点（00~99 及二级分组）→ 记录每个节点的 metadata.name → 用 minidocs-cli 按 --parent 批量导入正文 → 批量 publish → 抽查 3~5 篇确认树形与渲染正确。

---

来源：halo-kb/知识库架构设计.md → ### C.5 上架前的三个冲突检查（与本实例直接相关）（原文 1011 字符）

C.5 上架前的三个冲突检查（与本实例直接相关）

1. ✅ 主题模板冲突：本实例安全。插件作者指出：主题若自带 doc.html / docs.html（为 Halo 官方文档插件适配的），会覆盖插件内置前台模板，症状是前台报「资源不存在」（issue #3 评论）。我已核对 Ethereal 1.2.4 的 27 个模板清单：archives / bangumis / categories / category / equipments / error-404 / fragments-post-list / friends / gateway_fragments-layout / index / layout / links / moment / moments / page / photo / photos / portfolio-detail / portfolio / post / schedule-calendar-card / schedule-calendar / skills / tag / tags / timeline / wishes——不含 doc.html 与 docs.html，不会覆盖。
2. ⚠️ 路由冲突：需保持 plugin-docsme 禁用。MiniDocs 与 Halo 付费文档插件（docsme）**都占用 /docs/*（issue #1 评论）。本实例已装 plugin-docsme 但处于禁用状态——安装 MiniDocs 后必须保持其禁用**。
3. ⚠️ 已知限制：issue #5「希望为每个目录设置折叠开关」仍 open、功能未实现——即目录树的折叠行为不可配置。
4. ℹ️ 兼容性仅由 requires >= 2.26.0 声明支撑，未见到针对 2.26.1 的专项测试声明（未确认）。

---

---

来源：halo-kb/minidocs-落地记录.md → ## 8. 未确认项与遗留（原文 1563 字符）

8. 未确认项与遗留

8.1 【未确认】

#	项	说明
1	真实浏览器里的视觉效果	全程只用 curl 校验状态码与 HTML 片段（已确认 HTML 内含真实节点标题与正文），没有在浏览器/无痕窗口中目视确认布局、目录折叠、代码高亮是否正常。建议人工用无痕窗口访问 /docs/view/tech-docs 复核一次
2	只写 raw 不写 content 是否会空白	设计稿 C.4 标注的未确认项。本次 raw 与 content 两个都写，因此规避了该风险，但没有单独构造"只写 raw"的场景去验证它。该问题仍然未确认
3	无正文的分组节点在前台如何呈现	已确认实体模型没有目录标记（§3.4）、分组节点靠 children 体现；但"点进一个没有正文的节点会显示成什么样"未在浏览器确认
4	分享链接	shareEnabled / shareToken / sharePassword / shareExpiresAt 与 /docs/share/{shareToken} 路由完全没用到、没验证
5	ZIP 导入导出	/knowledgebases/export、/import、/import/preview 只从字节码确认了路径，未实际调用
6	Halo 2.26.1 的专项兼容性	兼容性只由 requires: ">=2.26.0" 声明支撑，作者未见针对 2.26.1 的测试声明
7	删知识库是否级联删文档	见 §4.3
8	源码 null 兜底逻辑是否真为"开启"	设计稿 C.3 提到的文档内部矛盾；本次显式写入 true，未构造 null 场景验证

8.2 本次没有做（超出任务范围，留给后续）

项	出处
建第二个知识库「私有笔记」(private-notes)	设计稿 C.2 的知识库划分建议里提到 2 个，本次任务只要求「技术文档库」
把 38 个节点的正文填进去	本次只建结构；正文需按设计稿 D 节的模板逐篇写
菜单项「文档」→ /docs	设计稿 E.① 第 7 步
启用 minidocs-cli 做批量导入	设计稿 C.4 的路径①
触碰主题设置、docsme、其他插件设置	硬约束禁止，全程未动

8.3 硬约束遵守情况

约束	状态
只操作 MiniDocs 相关资源与它自己的设置	✅ 全程只碰 halo-plugin-minidocs-configmap、tech-docs 知识库、其下 38 个文档
不动其他插件设置 / 主题配置	✅ 未发出任何相关请求
不启用 docsme	✅ 实测其 phase=DISABLED，脚本把它当反向断言守
不重启容器或服务	✅ 未执行任何重启；allowAnonymousRead 修改后立即生效，无需重启
不写任务根目录之外的文件	✅ 全部落在 H:\Works\halo-kb\ 下
报告中不出现真实 token	✅ 全部用 <TOKEN> 占位；脚本从环境变量读、不打印不落盘