[RFC] add_resource 支持本地目录导入

[qin-ctx]

背景

add_resource 不支持本地目录，传入目录路径报错 [Errno 21] Is a directory（#80）。

以下是我个人的初步想法，欢迎大家修改和提出建议。

整体架构

add_resource("/path/to/dir")
       │
       ▼
┌──────────────────────────┐
│ UnifiedResourceProcessor │  ← path.is_dir() 检测
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│    DirectoryParser        │
│                          │
│  ┌────────────────────┐  │
│  │ 阶段一：预扫描校验  │  │  ← os.walk() 遍历，分类所有文件
│  │                    │  │     unsupported 非空 → 报错终止
│  └────────┬───────────┘  │
│           │ 校验通过      │
│  ┌────────▼───────────┐  │
│  │ 阶段二：解析路由    │  │
│  │                    │  │
│  │  rich_file ──→ 对应 Parser（PDFParser / MarkdownParser / ...）
│  │  text_file ──→ 编码检测 + 直接上传（共享 upload_utils）
│  │                    │  │
│  └────────┬───────────┘  │
│           │              │
│  ParseResult(temp_dir)   │
└──────────┬───────────────┘
           │
           ▼
┌──────────────────────────┐
│ TreeBuilder               │  ← finalize_from_temp()
│ 移动到 AGFS + 入队语义生成 │     现有流程，无需改动
└──────────────────────────┘

核心设计

为什么分两阶段

目录可能包含上百个文件，如果边解析边发现不支持的格式，已解析的工作就浪费了。
因此采用先校验后解析：阶段一快速遍历确认所有文件可处理，阶段二才开始实际解析。

阶段一：校验逻辑

遍历目录树，对每个文件做如下判定（按优先级）：

文件 → 在 IGNORE_DIRS 下？ → 跳过（.git, node_modules 等）
     → 点文件/符号链接/空文件？ → 跳过
     → ParserRegistry 有对应 Parser？ → 标记为 rich_file
     → ext ∈ CODE_EXTENSIONS ∪ ADDITIONAL_TEXT_EXTENSIONS？ → 标记为 text_file
     → 否 → unsupported

unsupported 非空 → 抛出异常，附带完整的不支持文件列表。
全部通过 → 进入阶段二。

阶段二：解析路由

校验通过后，创建 VikingFS 临时目录 viking://temp/{uuid}/{dir_name}/。

• rich_file：调用对应 Parser，每个 Parser 返回自己的 temp_dir_path，
  将其内容移动到主临时目录的对应相对路径下。
• text_file：直接上传到 VikingFS 对应路径，复用 CodeRepositoryParser 的编码检测逻辑。

最终返回 ParseResult(temp_dir_path=temp_uri)，
由现有 TreeBuilder.finalize_from_temp() 完成后续流程（移动到 AGFS + 入队语义生成）。

入口改动

UnifiedResourceProcessor.process() 和 ParserRegistry.parse() 中
path.exists() 后增加 path.is_dir() 判断，路由到 DirectoryParser。

与 CodeRepositoryParser 的复用

从 CodeRepositoryParser._upload_directory() 提取编码检测+上传逻辑为共享工具函数，
DirectoryParser 和 CodeRepositoryParser 共同调用。

---

完整示例

输入目录：

~/ai_research/
├── README.md
├── papers/
│   ├── transformer.pdf
│   └── attention.pdf
├── notes/
│   ├── summary.md
│   └── diagrams/
│       └── arch.png
├── src/
│   ├── model.py
│   ├── train.py
│   └── config.yaml
├── .git/
└── node_modules/

阶段一：预扫描校验

.git/              → IGNORE_DIRS → 跳过
node_modules/      → IGNORE_DIRS → 跳过
README.md          → ParserRegistry → MarkdownParser → rich_file ✓
papers/transformer.pdf → ParserRegistry → PDFParser  → rich_file ✓
papers/attention.pdf   → ParserRegistry → PDFParser  → rich_file ✓
notes/summary.md       → ParserRegistry → MarkdownParser → rich_file ✓
notes/diagrams/arch.png → ParserRegistry → ImageParser → rich_file ✓
src/model.py       → CODE_EXTENSIONS → text_file ✓
src/train.py       → CODE_EXTENSIONS → text_file ✓
src/config.yaml    → ADDITIONAL_TEXT_EXTENSIONS → text_file ✓
unsupported: []    → 校验通过 ✅

阶段二：解析路由

创建 viking://temp/{uuid}/ai_research/

rich_file 处理:
  README.md              → MarkdownParser.parse()  → 移动到 {root}/README/
  papers/transformer.pdf → PDFParser.parse()       → 移动到 {root}/papers/transformer/
  papers/attention.pdf   → PDFParser.parse()       → 移动到 {root}/papers/attention/
  notes/summary.md       → MarkdownParser.parse()  → 移动到 {root}/notes/summary/
  notes/diagrams/arch.png → ImageParser.parse()    → 移动到 {root}/notes/diagrams/arch/

text_file 处理:
  src/model.py    → 编码检测 + 上传到 {root}/src/model.py
  src/train.py    → 编码检测 + 上传到 {root}/src/train.py
  src/config.yaml → 编码检测 + 上传到 {root}/src/config.yaml

最终 VikingFS 结构

viking://resources/ai_research/
├── README/                          ← MD 按章节展开
│   ├── introduction.md
│   └── usage.md
├── papers/
│   ├── transformer/                 ← PDF 按章节展开
│   │   ├── abstract.md
│   │   ├── method.md
│   │   └── experiments.md
│   └── attention/
│       ├── abstract.md
│       └── mechanism.md
├── notes/
│   ├── summary/                     ← MD 按章节展开
│   │   └── ...
│   └── diagrams/
│       └── arch/                    ← ImageParser VLM 描述
│           └── description.md
└── src/
    ├── model.py                     ← 原样保留
    ├── train.py
    └── config.yaml

目录间的组织关系（papers/、notes/、src/）与原始目录一致，
单个文档（如 transformer.pdf）被 Parser 展开为子目录。

---

开放讨论 🗣️

1. 不支持格式的处理策略

当前想法：存在不支持的文件直接报错。

• A) 严格报错：有不支持的文件就报错，用户必须清理后重试
• B) 跳过 + 警告：跳过不支持的文件，继续解析，返回 warnings
• C) 可配置：增加 strict 参数让用户选择

2. 与 CodeRepositoryParser 的关系

• A) 独立 DirectoryParser：新建 Parser，共享上传工具
• B) 扩展 CodeRepositoryParser：在其 parse() 中增加本地目录分支

3. 混合资源类型目录的语义聚合

现有的 SemanticProcessor 在生成目录级别的 abstract/overview 时，
处理的都是纯代码目录或纯文档目录，子文件的摘要风格和粒度是一致的。

引入目录导入后，同一目录下可能混合存在设计文档（PDF）、技术笔记（MD）、
架构图（PNG）、源代码（PY）等，各文件提取出的摘要差异很大。
当这些不同风格的子文件摘要需要合并成该目录的 abstract/overview 时，
现有的聚合逻辑是否需要调整？

例如：~/project/ 下同时有 design.pdf（摘要偏架构描述）和
src/main.py（摘要偏代码结构），生成 project/ 的目录级 overview 时，
应该如何融合这两种不同性质的摘要？

4. 自定义过滤规则

当前想法只有固定的 IGNORE_DIRS / IGNORE_EXTENSIONS 过滤。
是否需要支持用户自定义选择导入哪些文件？

• A) 不支持：仅使用内置过滤规则
• B) include/exclude 参数：如 add_resource("/dir", include="*.pdf,*.md", exclude="drafts/")
• C) glob 通配符：如 add_resource("/dir", glob="docs/**/*.pdf")
• D) .vikingignore 文件：类似 .gitignore，在目录下放置配置文件声明忽略规则

5. 大目录限制

当前无目录级别限制。是否需要总文件数或总大小上限？

---

任务拆解（初步）

#	任务	描述
T1	目录预扫描校验模块	遍历目录树、文件分类（rich/text/unsupported）、格式校验、异常报告，含校验逻辑的单元测试
T2	共享上传工具	从 CodeRepositoryParser 提取编码检测+文本文件上传为独立工具函数，含上传和编码转换的单元测试
T3	rich_file 解析编排	对 rich_file 调用对应 Parser，将各 Parser 的 temp 输出移动到主临时目录的正确相对路径，含路径映射和多 Parser 协调的测试
T4	DirectoryParser 组装 + 入口路由	将 T1/T2/T3 组装为 DirectoryParser，添加 is_dir() 路由和注册，含端到端集成测试
T5	混合目录语义聚合适配	调研/适配 SemanticProcessor 对混合类型目录的 abstract/overview 生成，含混合类型目录的语义生成测试

T1、T2、T3、T5 可以并行开发，T4 负责最终组装。

---

协作者

目前已报名的协作者：

• @qin-ctx
• @shaoeric
• @ze-mu-zhou

欢迎更多人参与讨论和贡献！

[ze-mu-zhou]

1.C可配置，默认 跳过 + 警告 会好一点
目录导入场景下，用户的核心需求应该是尽可能多地导入可处理的内容，不应该因为个别不支持的文件而中断整个流程
2.A独立 DirectoryParser
因为CodeRepositoryParser 的设计目标是代码仓库
而DirectoryParser 的设计目标是通用目录，两者的预扫描逻辑、Parser 路由、语义聚合策略都不同
3.暂时还没有成熟的想法，先观察其他任务的进展再讨论
4.B，以参数方式实现起来简单一些，先把常见的场景覆盖了，后续可以根据社区要求扩展成.vikingignore
5.我觉得是必须的，建议实现为用户可配置的参数，设置一个相对保守的默认上限
当用户传入的目录超过限制时，不直接拒绝，而是通过warning提示用户当前目录的规模，并要求用户显式确认是否继续
这样既能防止误传超大目录导致系统过载，又不会阻碍有真实大目录需求的用户

[ze-mu-zhou]

此外，我想要认领一下T2的任务

[shaoeric]

我先认领下T1的，最后T4中端到端的测试和验收测试工作我也会同步跟进

[shaoeric]

T1: #102
T2: #87

我继续认领 T3

[MaojiaSheng]

服务模式下有一个 BUG
#168