Local Document Ingest

SKILL.md

---
name: local_document_ingest
description: Ingest desktop-uploaded local files into the Research KB. Use for local folder scan tasks where OpenClaw must read backend shared-file paths, understand each changed file, create a type-specific entity wiki page for every readable file, archive originals under source_files, update related pages, synthesize concept/resource pages, maintain links/catalog/index metadata, and return backend task JSON.
---

# 本地文件入库知识库编译

## 核心职责

把桌面端本地文件夹扫描上传的文件，编译成团队知识库中的可追踪、可复用、可链接的 Markdown 知识页面。

桌面端负责扫描用户选择的本地文件夹、计算 hash、识别新增/修改/移动/删除，并且只上传内容新增或内容修改的文件。完全无内容变化时桌面端只向后端上报空扫描结果，用于更新扫描时间和 source_snapshots，不创建本 skill 任务。后端负责把上传文件保存到 OpenClaw 可读取的共享目录，记录资料源状态，并构造任务 payload。OpenClaw 负责真正的知识库编译：读取原文件、理解内容、判断资料类型、为每个可读取文件生成或更新一个对应类型的实体页、归档原文件、更新相关已有页面、按需要创建或更新跨文件概念页和资源页、维护内部链接、维护 `catalog.json` 和 `index.md`，最后写出后端可读的结果 JSON。

知识库不是网盘，也不是原文摘要仓库。每个文件实体页都应回答：这个文件是什么资料、核心内容是什么、它对团队有什么价值、哪些结论可复用、哪些内容不确定、它和知识库里已有项目/论文/实验/会议/概念/资源有什么关系，以及这些判断能追溯到哪些原始证据。

本 skill 的重点不是机械多产页面，而是把新增资料放进已有知识图谱。OpenClaw 在写 `pages.json` 前必须先私下做一次“知识图谱规划”：先确定每个可读文件的实体页，再判断是否需要更新已有 `overview/`、`projects/`、`concepts/`、`resources/` 或其他相关页面。概念页、资源页、overview 页都不是配额；没有证据时不要硬建，但如果它们能显著改善导航、跨文件综合、复用或可追踪关系，就应该更新。

## 硬性规则

- 只处理本次 payload 中 `source.items[]` 明确列出的文件。`items[].itemKey` 是文件条目身份，`items[].sha256` 是内容 hash；同一路径内容修改会复用原 `itemKey` 并更新当前 `sha256`，同内容不同路径文件可能共享 `sha256`，但必须有不同 `itemKey`。
- 只从 `items[].storagePath` 或 `items[].archived_path` 读取文件内容。
- 不要遍历 `sharedDir/uploads` 来推断本次文件；同一天可能发生多次上传。
- 不要访问、暴露或写入用户电脑上的完整本地绝对路径；只使用 `original_path` 或 `metadata.relativePath` 这类相对路径作为来源线索。
- `source.items[]` 里的每个可读取文件都必须生成或更新一个对应类型的实体 wiki 页，不能因为文件低价值、只是支撑已有主题、属于同一批资料包，就只归档而不建实体页。
- 完全不可读、损坏、hash 校验失败、格式暂时无法处理的文件可以不生成实体页，但必须写入 `skippedSources[]`，说明原因，并尽量保留 source trace。
- 跨文件概念页、资源页、项目页、综述页或 overview 页是实体页之外的关系层，不能替代文件实体页。
- 移动、重命名、删除只代表资料源元数据变化；如果后端没有把它们放入 `source.items[]`，本 skill 不重新编译正文。
- 不要使用旧目录 `summaries/`、`imports/` 作为主要写入位置。
- 不要写入真实密钥、token、隐私路径、大段原文复制或未经证据支持的推断。

## 输入约定

任务 payload 通常包含：

- `taskId`: 后端任务 ID。
- `payloadFile`: 后端写出的 payload JSON 文件路径。
- `resultFile`: OpenClaw 最终必须写入的结果 JSON 文件路径。
- `skill`: `local_document_ingest`。
- `trigger`: 通常是 `local_desktop_upload`。
- `source.id`、`source.name`、`source.type`: 资料源信息；`source.type` 必须是 `local_folder`。
- `source.config.folderName`: 本地文件夹展示名；不要把完整本机路径写入知识页。
- `source.items[]`: 本次内容新增或内容修改的文件列表；移动、重命名、删除不应进入此数组。
- `items[].itemKey`: 文件条目身份，用于区分同内容但不同路径/不同来源的文件；同一路径内容修改沿用原 `itemKey`，OpenClaw 生成页面时必须用它写入 `sourceItemKeys`。`itemKey` 不等同于 `sha256`。
- `items[].title` 或 `items[].fileName`: 文件名或相对路径提示。
- `items[].original_path` 或 `items[].metadata.relativePath`: 用户选定文件夹内的相对路径。
- `items[].storagePath` 或 `items[].archived_path`: 后端共享目录中 OpenClaw 可读取的文件路径。
- `items[].sha256`: 文件内容 hash，用于内容校验和追踪；不能单独作为文件身份，因为同内容不同路径文件会共享该值。
- `items[].metadata.uploadBatchId`: 上传批次 ID，仅作为追踪元数据。
- `items[].metadata.mimeType`、`items[].size`、`items[].metadata.localMtimeMs`: 文件元数据。
- `team.kbRepo`: 目标团队知识库仓库。
- `platform.giteaUrl`、`platform.giteaOwner`、`platform.sharedDir`: 平台上下文。

环境变量可能包括 `GITEA_URL`、`GITEA_BOT_TOKEN`、`GITEA_BOT_USERNAME`、`GITEA_ORG`、`TEAM_KB_REPO`、`OPENCLAW_SHARED_DIR`。

正常情况下，完全无内容变化的空扫描由后端直接收口，不会创建 `local_document_ingest` 任务。如果因为兼容旧 payload 或人工重试导致 `source.items[]` 为空，返回成功结果并在 `skippedSources[]` 中说明没有内容变化文件，不创建或更新页面。

## 执行流程

1. 校验任务。
   - 确认 `source.type == "local_folder"`。
   - 只从 `source.items[]` 建立本次处理清单。
   - 确认每个文件有可读的 `storagePath` 或 `archived_path`。
   - 能校验 hash 时重新计算 `sha256`；不一致时跳过该文件并报告。

2. 读取并解析原文件。
   - 按文件格式提取正文、章节、表格、图片说明、幻灯片结构、表格工作表、代码片段、元数据和嵌入引用。
   - 对图片、音视频、压缩包、扫描件或难解析文件，只提取可靠信息，并标明解析限制。
   - 保留证据位置：页码、章节、幻灯片、sheet、行列、时间戳、相对路径、hash。

3. 为每个文件判断资料类型。
   - 资料类型由内容意图决定，不只看扩展名和文件名。
   - 每个可读取文件必须选择一个主类型，并生成或更新一个实体页。
   - 一个文件可以额外触发相关已有页更新，也可以支撑概念页或资源页。
   - 多个文件属于同一资料包时，也要分别生成每个文件的实体页，再通过链接和关系页把它们组织起来。

4. 归档原文件。
   - 每个已处理文件都应归档到 `source_files/local_folder/` 下。
   - 推荐路径：`source_files/local_folder/<sourceId>/<date>-<slug>-<hash8>-<item8>.<ext>`，其中 `item8` 来自文件条目身份短码，用来避免同名同内容文件归档路径碰撞。
   - 能保存原始字节时保存原始文件。
   - 无法保存原始字节时，在 `source_files/local_folder/<sourceId>/` 下创建来源登记 Markdown，记录共享路径、hash、大小、mime type、相对路径、上传批次、解析状态和归档失败原因。
   - 知识页优先引用归档后的 `source_files/...` 路径，不把临时共享上传路径作为主要来源路径。

5. 生成或更新文件实体页。
   - 每个文件一个实体页，路径放在该文件主类型对应目录。
   - 实体页不是简单摘要，而是按该资料类型的核心章节进行分析编译。
   - 如果能确定是同一资料对象的新版本、同一论文、同一会议或同一实验的实体页已经存在，应更新已有实体页，而不是机械新建重复页；但同内容不同路径文件仍要保留各自的文件条目来源。
   - 实体页的 `sources[]` 至少包含该文件的 source trace。

6. 更新关系层页面。
   - 先做关系规划，再写页面正文：本批资料新增了哪些实体？它们连接到哪些已有页面？哪些稳定概念、具体资源或 overview 导航需要新建或更新？
   - 如果文件内容与已有项目、论文、综述、实验、会议、技术方案、笔记、概念或资源有关，更新相关已有页。
   - 如果多个文件共同支撑某个稳定抽象知识，创建或更新概念页。
   - 如果多个文件提到同一个可复用对象，创建或更新资源页。
   - 如果一批文件共同构成一个项目包、实验包、会议包、调研包，或能补充某个团队级主题、研究方向、资料地图、项目导航，应更新 `overview/` 或相关主题页；但 overview 不能替代文件实体页。
   - 如果已有 overview/项目/概念/资源页面已经表达同一知识节点，应优先更新已有页并补充新证据，而不是重复建页。

7. 维护链接、catalog 和 index。
   - 正文中的内部链接使用 `[[path-without-md|显示标题]]`。
   - `relatedConcepts` 用于概念页，`relatedResources` 用于资源页，`relatedCodePages` 用于代码页，`relatedPages` 用于 overview/项目/论文/综述/会议/实验/技术文档/笔记等普通 Wiki 页面之间的关联。
   - 页面正文里也要写有解释意义的 wikilink，不能只依赖 frontmatter/catalog 字段。
   - 新建或更新页面后，维护 `catalog.json`。
   - 重要入口或导航变化应更新 `index.md` 或相关 overview 页面。

8. 写出结果。
   - 将最终结果 JSON 写入 `resultFile`。
   - 最终回复只能是 JSON，不要额外输出解释性文字。

## 脚本闭环

本 skill 必须使用自带 Python 脚本完成确定性动作。OpenClaw 不应直接跳过脚本手写 Gitea，也不应直接扫描 `sharedDir/uploads`。

标准流程：

```bash
python3 scripts/run_task.py prepare --input <payload.json> --context-output <context.json>
# OpenClaw 阅读 <context.json>，生成 <pages.json>
python3 scripts/run_task.py validate-pages --input <payload.json> --context <context.json> --pages <pages.json>
python3 scripts/run_task.py apply --input <payload.json> --context <context.json> --pages <pages.json>
```

`prepare` 负责：

- 读取 payload，只建立 `source.items[]` 中本次内容新增/修改文件的处理清单。
- 校验 `source.type`、共享文件是否存在、sha256 是否和 payload 一致。
- 抽取文本预览、Office XML 文本、zip 清单、文件元数据和弱类型提示。
- 读取 `catalog.json`、`index.md` 和少量相关页面卡片，输出给 OpenClaw 的 `<context.json>`。
- 对缺失、不可读或 hash 不一致的文件写入 `skippedSources[]`。

OpenClaw 负责阅读 `<context.json>` 后生成 `<pages.json>`。知识图谱规划只在内部思考中完成，不要把规划文字当作最终回复，也不要停在规划阶段。`pages.json` 必须是纯 JSON 对象，不允许包含 Markdown、注释、尾随逗号或解释性文字，至少包含：

```json
{
  "pages": [
    {
      "path": "papers/example.md",
      "title": "论文：Example",
      "type": "paper",
      "kbType": "wiki",
      "sourceItemKeys": ["<inputItems[].itemKey>"],
      "content": "Markdown 正文，不带 frontmatter",
      "keywords": [],
      "projectIds": ["general"],
      "relatedConcepts": ["concepts/example.md"],
      "relatedResources": ["resources/example.md"],
      "relatedPages": ["overview/example.md"]
    }
  ],
  "skippedSources": [],
  "errors": [],
  "snapshot": {}
}
```

`pages[].sourceItemKeys` 是硬性字段，必须引用 `inputItems[].itemKey`，不要用 `sha256` 代替。每个可读 `inputItems[]` 必须至少出现在一个实体页中，实体页目录只包括 `projects/`、`papers/`、`surveys/`、`code/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`；`overview/`、`concepts/`、`resources/` 不能替代实体页。`pages[].path` 只能写入 `projects/`、`papers/`、`surveys/`、`code/`、`meetings/`、`experiments/`、`tech-notes/`、`notes/`、`concepts/`、`resources/` 或必要的 `overview/` 页面，不能写入 `qa/` 或 `source_files/`。

`validate-pages` 负责：

- 在写入知识库前校验 `<pages.json>`，不触碰 Gitea。
- 拦截 JSON 语法错误、路径越界、缺少 `sourceItemKeys`、漏掉可读文件实体页、写入 `qa/` 等问题。
- 如果验证失败，OpenClaw 必须修正 `<pages.json>` 并重新验证；验证通过后才能运行 `apply`。

`apply` 负责：

- 校验 `<pages.json>`，拦截缺少 `sourceItemKeys`、漏掉可读文件实体页、路径越界、写入 `qa/` 等情况。
- 把被处理的源文件归档到 `source_files/local_folder/<sourceId>/...`，归档文件名包含内容 hash 短码和文件条目身份短码；无法原样归档时写来源登记 Markdown。
- 为页面补齐 frontmatter、source trace、归档路径、hash、sourceStatus。
- 写入/更新 Markdown 页面、`catalog.json` 和 `index.md`。
- 把后端需要的统一结果 JSON 写入 `resultFile`，结果必须包含布尔型 `success`；`sourceItems[]` 写回后端用于资料项状态统计。

## 知识库目录

主要目录如下：

- `overview/`: 团队级地图、主题导航、资料包总览。
- `projects/`: 团队研究/工程项目实体页和项目主页，记录项目目标、范围、里程碑、进展、决策、风险、相关资料和知识链接；不是代码资料目录。
- `papers/`: 论文实体页。
- `surveys/`: 综述、调研、技术/行业调查实体页。
- `code/`: 本地代码资料、代码包、局部源码、仓库说明、实现说明和架构分析实体页。
- `meetings/`: 会议纪要、讨论记录、决议和行动项实体页。
- `experiments/`: 实验记录、评测结果、运行分析实体页。
- `tech-notes/`: 技术文档、操作指南、API/配置/排障文档实体页。
- `notes/`: 个人或团队笔记实体页。
- `concepts/`: 跨文件、跨项目可复用的抽象概念页。
- `resources/`: 数据集、模型、工具、库、仓库、API、网站、论文、benchmark 等具体资源页。
- `source_files/`: 原文件归档和来源登记。

本 skill 不创建或更新 `qa/` 页面；`qa/` 属于查询/问答沉淀链路。

## 资料类型判断

判断资料类型时综合以下证据：标题、文件名、相对路径、章节结构、摘要、参考文献、表格、图注、命令/API、实验设置、会议议程、代码结构、正文意图和已有 catalog 关系。

常见主类型：

- 论文：包含研究问题、方法、实验、结果、引用等论文结构。
- 综述/调研：覆盖一个领域、方向、技术栈、竞品、案例或文献集合，并有分类、比较、趋势、风险信息。
- 项目资料：立项说明、需求规格、研究计划、项目方案、阶段总结、路线图、任务拆解、项目复盘等非代码资料。
- 代码资料：README、设计文档、源码包、架构说明、实现说明、运行说明、测试线索、依赖配置。
- 技术文档：安装部署、API、命令、配置、操作流程、排障、示例。
- 实验：假设、变量、环境、数据、模型、指标、结果、异常、结论、下一步。
- 会议：时间、参与者、议程、讨论、决议、行动项、风险、开放问题。
- 笔记：想法、备忘、阅读记录、草稿、碎片证据、不确定结论。
- 概念资料：主要解释方法、机制、框架、算法、模型、指标、评估概念、架构范式或研究问题。
- 资源资料：主要介绍数据集、模型、工具、库、仓库、API、网站、论文、benchmark、平台、模板等具体对象。

混合资料也必须选一个主类型生成实体页，并在实体页中说明次要内容；必要时再更新概念页、资源页或其他相关页。

## 页面生成规则

每个可读取文件都必须对应一个实体页：

- 论文文件写入 `papers/<slug>.md`。
- 综述/调研文件写入 `surveys/<slug>.md`。
- 项目资料写入 `projects/<slug>.md`。
- 代码资料写入 `code/<slug>.md`。
- 技术文档写入 `tech-notes/<slug>.md`。
- 实验资料写入 `experiments/<slug>.md`。
- 会议资料写入 `meetings/<slug>.md`。
- 笔记资料写入 `notes/<slug>.md`。
- 概念说明类或资源说明类文件也必须先写入上述实体目录中最贴近的一类；`concepts/`、`resources/`、`overview/` 只能作为关系层或导航层，不能替代文件实体页。

实体页命名应稳定、可读、可避免冲突。推荐 slug 由标题或文件名生成，并在必要时追加 hash 短码。不要因为多个文件属于同一主题而省略文件实体页。对于一组相关文件，可以额外创建主题/项目/overview 页，并让各实体页互相链接。

## 页面元数据要求

每个生成或更新的 Markdown 知识页必须包含 frontmatter，至少包括：

```yaml
id: stable-page-id
title: readable title
type: paper|survey|project|code|tech-note|experiment|meeting|note|concept|resource|overview
kbType: wiki|project|concept|resource|source
tags: []
keywords: []
projectIds: []
createdAt: ISO-8601
updatedAt: ISO-8601
generatedBy: openclaw:local_document_ingest
contentHash: sha256-of-page-body
sourceStatus: active|outdated|deleted|mixed
sources:
  - sourceId: 1
    sourceType: local_folder
    platform: desktop
    title: source title
    fileName: original file name
    originalPath: relative/path/in/local/folder
    archivedPath: source_files/local_folder/...
    sha256: file hash
    status: active
    ingestedAt: ISO-8601
```

实体页的 `sources[]` 必须包含其对应原文件。相关页、概念页、资源页的 `sources[]` 应包含支撑该页结论的所有文件来源。用户可见 Markdown 中不要写完整本地绝对路径。

## 各类型实体页核心章节

以下章节不是死板模板，而是每种资料必须回答的核心问题。章节标题可以根据文件内容微调，但不能丢掉该类型最有价值的信息。缺少证据时写“来源未提及”或“无法从当前资料确认”。

### 论文实体页：`papers/<slug>.md`

目标：帮助团队判断论文研究什么、贡献是什么、方法是否可复用、实验是否可信、对当前项目有什么启发。

核心章节：

1. `## 一句话结论`：用 1-3 句话说明研究问题、方法和最重要结论。
2. `## 研究问题与背景`：问题定义、研究动机、已有方法不足、适用场景。
3. `## 核心贡献`：区分作者明确声称的贡献和 OpenClaw 基于内容归纳的贡献。
4. `## 方法与机制`：模型、算法、系统流程、关键模块、重要假设。
5. `## 实验设计与证据`：数据集、基线、指标、设置、消融、定性证据。
6. `## 结果与解释`：主要结果说明了什么，不能说明什么。
7. `## 局限与不确定性`：作者承认的局限、评估缺口、复现风险、外部有效性。
8. `## 可复用结论与团队启发`：可迁移的方法、评估方式、工程实现、研究问题。
9. `## 关联概念与资源`：链接相关概念、数据集、benchmark、工具、模型、项目或其他论文。
10. `## 来源与证据索引`：归档文件、hash、页码、章节、图表线索。

### 综述/调研实体页：`surveys/<slug>.md`

目标：把宽范围信息整理成分类框架、趋势判断、风险地图和团队后续行动依据。

核心章节：

1. `## 调研范围与核心问题`：覆盖领域、时间范围、对象边界、要回答的问题。
2. `## 分类框架`：技术路线、方法家族、应用场景、评价维度、产业层级或成熟度分层。
3. `## 关键发现`：按主题总结稳定结论，避免只罗列材料。
4. `## 代表性方法/系统/论文/案例`：用表格说明对象、核心思想、优点、限制、适用场景。
5. `## 趋势与变化`：方向演进、近期热点、范式变化和可能原因。
6. `## 风险、争议与约束`：证据冲突、评估缺口、工程风险、安全/合规/伦理问题。
7. `## 信息缺口`：还缺哪些资料、实验、案例或权威来源。
8. `## 团队启发与后续行动`：项目选择、实验计划、阅读优先级、论文写作或技术选型建议。
9. `## 来源与证据索引`：文件、章节、链接、hash、归档路径。

### 项目资料实体页：`projects/<slug>.md`

目标：记录团队真实研究项目或工程项目的项目级知识。`projects/` 不是代码资料目录，而是项目主页/项目实体层，用来把论文、实验、会议、技术文档、代码页、概念页和资源页组织到同一个项目脉络下。

适合写入 `projects/` 的本地文件包括：立项说明、需求规格、研究计划、项目方案、阶段总结、路线图、任务拆解、项目复盘、项目背景材料等。代码仓库、源码包、实现说明、架构分析、运行测试说明应写入 `code/`。

核心章节：

1. `## 项目定位`：项目要解决的科研/工程问题、目标用户、团队语境、项目边界。
2. `## 目标与成功标准`：预期产出、验收标准、阶段目标、不可做事项。
3. `## 背景与动机`：项目为什么重要，来自哪些需求、研究问题或外部条件。
4. `## 范围与关键任务`：任务拆解、工作包、里程碑、依赖关系。
5. `## 当前进展与决策`：已完成内容、关键决策、决策理由、影响范围。
6. `## 关联资料与知识页`：链接相关论文、综述、实验、会议、技术文档、代码页、概念页、资源页。
7. `## 风险与开放问题`：资源、时间、技术、数据、协作、合规、质量风险，以及未解决问题。
8. `## 下一步行动`：后续任务、负责人、优先级、需要补充的证据。
9. `## 来源与证据索引`：项目文件、相对路径、hash、归档路径、扫描时间。

### 代码资料实体页：`code/<slug>.md`

目标：说明代码资料、代码包、局部源码或实现说明为什么存在、如何工作、成熟度如何、哪里可复用或需要改造。完整 Git 仓库优先交给 `gitea_repo_ingest`；本 skill 处理本地上传的代码文档、压缩包、局部源码、README、架构说明、运行测试线索等。

核心章节：

1. `## 代码资料定位`：资料对应的系统、模块或代码包，解决的问题、输入输出、边界。
2. `## 核心能力与使用场景`：能力、场景输入、输出、价值。
3. `## 架构与目录结构`：组件、模块、目录职责、关键文件，不机械罗列文件树。
4. `## 核心模块`：表格列出模块、职责、入口、依赖、数据流和证据路径。
5. `## 数据、接口与协议`：API、CLI、事件、数据库表、文件格式、schema、消息协议。
6. `## 依赖、配置与环境`：运行时、依赖、环境变量、权限、外部服务；敏感信息脱敏。
7. `## 运行、测试与部署线索`：只写来源中有证据支持的命令和步骤。
8. `## 成熟度与风险`：可运行性、测试、异常处理、安全、性能、维护性。
9. `## 修改建议与阅读路线`：后续工程动作和推荐阅读顺序。
10. `## 来源与证据索引`：归档文件、hash、相对路径、扫描时间。
### 技术文档实体页：`tech-notes/<slug>.md`

目标：把操作说明、接口说明、部署文档或技术方案整理成可执行、可排障、可复用的团队知识。

核心章节：

1. `## 用途与适用场景`：解决什么问题，适合谁在什么条件下使用。
2. `## 前置条件`：账号、权限、环境、版本、输入资源、假设。
3. `## 关键概念`：理解该文档必须知道的对象、术语和机制。
4. `## 操作流程或实现方案`：主流程、分支、结果。
5. `## 命令、API 与配置`：命令、参数、接口、字段、配置项、敏感项归属。
6. `## 示例与验证方式`：可复现实例、预期输出、检查点、验收标准。
7. `## 排障与常见错误`：失败模式、原因、日志位置、处理办法。
8. `## 风险与限制`：兼容性、安全、性能、数据一致性、维护风险。
9. `## 来源与证据索引`：来源章节、文件 hash、归档路径。

### 实验实体页：`experiments/<slug>.md`

目标：保留科研过程中“为什么做、怎么做、结果怎样、下一步是什么”的证据链。

核心章节：

1. `## 实验目的与假设`：要验证的问题、预期现象、成功标准。
2. `## 变量与对照`：自变量、因变量、控制变量、基线、对照组。
3. `## 环境与配置`：硬件、软件、模型、数据、版本、随机种子、参数。
4. `## 数据与方法`：数据来源、预处理、实验步骤、评价指标。
5. `## 结果`：关键结果、图表含义、观察现象。
6. `## 异常与偏差`：失败、异常值、日志、环境差异和可能原因。
7. `## 结论`：哪些假设被支持、哪些没有证据、哪些需要复验。
8. `## 下一步`：补充实验、参数调整、数据补充、代码修改建议。
9. `## 来源与证据索引`：实验文件、结果表格/图片/日志、hash、归档路径。

### 会议实体页：`meetings/<slug>.md`

目标：把组会、导师反馈、讨论纪要或聊天整理成决策、行动项、风险和开放问题。

核心章节：

1. `## 会议信息`：时间、参与者、主题、来源文件；缺失则标注。
2. `## 议程与背景`：会议围绕什么问题展开，关联哪些项目或资料。
3. `## 关键讨论`：按主题整理观点、证据、分歧和上下文。
4. `## 决议`：已经达成的决定、理由和影响范围。
5. `## 行动项`：任务、负责人、截止时间、依赖、状态；缺失则写未提及。
6. `## 风险与阻塞`：项目风险、资源缺口、技术难点和待协调事项。
7. `## 开放问题`：未解决问题和需要补充的证据。
8. `## 关联页面`：链接相关项目、实验、论文、技术方案或概念。
9. `## 来源与证据索引`：会议纪要、转写、附件、hash、归档路径。

### 笔记实体页：`notes/<slug>.md`

目标：从碎片化记录中提炼背景、想法、证据、不确定性和可执行下一步。

核心章节：

1. `## 背景`：笔记产生的上下文、关联项目或问题。
2. `## 核心想法`：可复用观点、假设、设计思路或问题定义。
3. `## 证据与依据`：支持这些想法的事实、引用或观察。
4. `## 不确定性`：尚未验证、证据不足或存在歧义的地方。
5. `## 关联知识`：链接相关页面、概念、资源、项目或实验。
6. `## 行动项`：后续阅读、实验、实现、讨论或整理动作。
7. `## 验证问题`：把模糊想法转成可验证的问题。
8. `## 来源与证据索引`：原始文件、相对路径、hash、归档路径。

### 概念关系页：`concepts/<slug>.md`

目标：沉淀稳定抽象知识节点，服务跨资料复用。适合方法、框架、机制、算法、模型、评价概念、架构范式、研究问题、理论术语、业务流程模式、数据处理范式。

`concepts/` 是实体页之外的关系层，不能替代任何文件实体页。如果某个上传文件本身就是概念说明，先为该文件生成 `notes/`、`tech-notes/`、`surveys/` 或 `projects/` 中最贴近的一类实体页；如果一个或多个文件共同支撑同一稳定概念，再创建或更新同一个概念页并记录多来源证据。

核心章节：

1. `## 定义与边界`：团队语境下的定义、适用范围、不适用范围、别名。
2. `## 为什么重要`：对团队项目、研究问题或工程实践的价值。
3. `## 机制或结构`：组成部分、变量、流程、公式或架构关系。
4. `## 在当前资料中的体现`：上传文件如何使用或解释该概念。
5. `## 证据片段`：短证据片段和来源索引，避免长引用。
6. `## 关联页面`：论文、综述、项目、实验、会议、资源。
7. `## 边界与易混淆点`：相近概念、常见误解、限制。
8. `## 未解决问题`：争议、缺口、待验证假设。
9. `## 来源与可追踪性`：每条关键结论来自哪些文件、章节、路径或 hash。

不要为普通文件名、临时变量、一次性小节标题、泛泛词语或没有来源证据的常识创建概念页。

### 资源关系页：`resources/<slug>.md`

目标：沉淀具体可复用对象，方便团队以后找到、评估和复用。适合数据集、模型、工具、库、仓库、API、网站、论文、benchmark、平台、模板、脚本、标准和外部系统。

`resources/` 是实体页之外的关系层，不能替代任何文件实体页。如果某个上传文件本身就是资源说明，先为该文件生成 `notes/`、`tech-notes/`、`code/`、`surveys/` 或 `projects/` 中最贴近的一类实体页；如果一个或多个文件共同提到同一可复用资源，再创建或更新同一个资源页并记录多来源证据。

核心章节：

1. `## 资源说明`：资源是什么、解决什么问题、资源类型。
2. `## 出现位置`：它在哪些上传文件和已有知识页中出现。
3. `## 使用方式`：安装、访问、调用、数据格式、许可、权限条件；没有证据则标注。
4. `## 与团队知识的关系`：相关项目、概念、实验、论文、综述。
5. `## 复用价值与限制`：成熟度、成本、风险、约束、不确定性。
6. `## 来源与可追踪性`：原始文件、链接、hash、归档路径、更新时间。

资源页应服务复用，不应变成下载清单或原文复制。

## 跨文件综合规则

多个上传文件相关时：

- 仍然为每个文件生成或更新自己的实体页。
- 如果它们属于同一论文包、会议包、实验包、项目文档包或调研包，可额外创建或更新一个包级 overview、项目页、实验总览页或调研页。
- 如果多个文件给出不同版本、结果或决策，应记录冲突，不要静默合并。
- 只有当时间信息来自文件内容或元数据且可信时，才用“最新资料覆盖旧资料”；否则标注时间顺序不确定。
- 用概念页连接重复出现的抽象知识，用资源页连接重复出现的具体对象。
- 相同相对路径前缀只能作为弱分组证据，内容证据优先。

## 链接规则

正文内部链接使用：

```markdown
[[papers/example-paper|论文：Example Paper]]
[[concepts/retrieval-augmented-generation|检索增强生成]]
[[resources/sqlite|SQLite]]
```

规则：

- 在第一次有解释价值的位置加链接，不必每次出现都链接。
- 链接目标使用不带 `.md` 的路径。
- 优先链接 catalog 中已有页面。
- 新建概念页或资源页后，要从相关文件实体页链接过去。
- 更新已有页时，保留仍然有效的旧链接；如果新证据推翻旧链接关系，要说明原因。
- 不要链接到不存在、未创建、未更新且 catalog 中也没有的页面。

## 目录索引维护

写入页面和 source file 后：

- 更新 `catalog.json`，记录 path、title、type、kbType、sourceIds、projectIds、keywords、relatedConcepts、relatedResources、relatedCodePages、relatedPages、contentHash、sourceStatus、updatedAt。
- 新增重要实体页、概念页、资源页或主题页时，更新 `index.md` 或相关 overview 页面，保证知识库脱离后端也可浏览。
- catalog 关系要和 frontmatter、正文链接保持一致。
- 新处理文件的 `sourceStatus` 为 `active`。如果后续后端传入删除或过期状态，应把受影响页面标为 `outdated`、`deleted` 或 `mixed`，不要直接删除历史知识。

## 写作与证据要求

- 优先综合分析，不要把页面写成 OCR 输出或原文摘要堆砌。
- 表格适合用于比较、模块列表、资源清单、行动项、实验结果、证据索引。
- 引用必须短而必要；大多数内容应转述和归纳。
- 区分来源明确陈述和 OpenClaw 推断。
- 不确定结论要标注“从资料结构推断”“需要进一步确认”或“当前资料未说明”。
- 失败实验、负面结果、局限、开放问题同样是有价值知识，应保留。
- 每个关键结论都应能追溯到 source hash、归档路径、页码/章节/路径等证据。

## 输出结果 JSON

必须把单个合法 JSON 对象写入 `resultFile`，最终回复也只能是 JSON。结构如下：

```json
{
  "success": true,
  "processedSources": [1],
  "createdPages": [
    {
      "path": "papers/example-paper.md",
      "title": "论文：Example Paper",
      "type": "paper",
      "kbType": "wiki",
      "sourceIds": [1],
      "keywords": ["RAG", "evaluation"],
      "contentHash": "sha256...",
      "sourceStatus": "active"
    }
  ],
  "updatedPages": [],
  "archivedFiles": [
    "source_files/local_folder/1/2026-07-07-example-paper-a1b2c3d4.pdf"
  ],
  "skippedSources": [],
  "sourceItems": [
    {
      "itemKey": "stable-file-item-key",
      "title": "example-paper.pdf",
      "sourceKind": "file",
      "status": "ingested|skipped",
      "sha256": "a1b2...",
      "originalPath": "relative/path/example-paper.pdf",
      "archivedPath": "source_files/local_folder/1/2026-07-07-example-paper-a1b2c3d4.pdf",
      "lastError": ""
    }
  ],
  "errors": [],
  "commitId": "",
  "snapshot": {
    "sourceId": 1,
    "uploadBatchId": "source-1_20260707T095114123Z_a1b2c3d4",
    "processedItemHashes": ["a1b2..."],
    "entityPageCount": 1,
    "relatedPageUpdateCount": 0,
    "conceptPageCount": 0,
    "resourcePageCount": 0,
    "archivedFiles": []
  }
}
```

失败或部分失败规则：

- 只有任务整体无法完成时才使用 `success=false`，例如 Gitea 写入失败、无法读取 payload、共享上传文件缺失且无法登记来源、权限不足。
- 单个文件不可读、无法解析、hash 不一致或格式不支持时，如果其他文件已成功处理，保持 `success=true`，并在 `skippedSources[]` 或 `errors[]` 说明。
- 如果本批次没有任何可读文件，但原文件已经成功归档并写入 `skippedSources[]` / `sourceItems[]`，可以返回 `success=true`；不要为了通过校验编造实体页。
- 错误原因必须具体：路径不可读、hash 不一致、格式不支持、解析失败、证据不足、Gitea 写入失败、权限问题。
- 不要在 JSON 之外返回自然语言说明。

## 完成前检查清单

结束前逐项确认：

- `source.items[]` 中每个可读取文件都有一个对应类型实体页。
- 无法生成实体页的文件已经写入 `skippedSources[]` 并说明原因。
- 每个已处理文件都归档到 `source_files/local_folder/`，或有来源登记说明无法原样归档的原因。
- 没有处理 payload 之外的文件。
- 实体页放在正确类型目录，且包含该类型核心章节。
- 相关已有页已按证据更新。
- 概念页和资源页只在有复用价值且有证据时创建或更新。
- 有关系的页面之间保留内部链接和关系元数据；普通页面关系写入 `relatedPages`，不要把 overview/项目/会议等普通页面硬塞进概念或资源字段。
- 页面中没有完整本地绝对路径、密钥或大段原文复制。
- `catalog.json`、`index.md`、frontmatter 和结果 JSON 一致。