happy-notes#

iflow 知识库助手。支持： knowledge-base（知识库管理与文件管理）、 reports（内容生成）、 search（联网搜索并导入知识库）。分享功能见下方「分享功能」章节。

Setup#

Security note: Credentials are only sent as HTTP headers to the configured API endpoint and never to any other domain.

1. 获取 API Key：访问 API Key 管理页面 申请
2. 存储凭证（二选一）：

bash

# 方式 A — 配置文件（推荐，Linux/Mac）
mkdir -p ~/.config/happy-notes && echo "your_api_key" > ~/.config/happy-notes/api-key

# 方式 B — 环境变量
export IFLOW_API_KEY="your_api_key"

powershell

# Windows PowerShell 用户：
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\happy-notes"
"your_api_key" | Out-File -FilePath "$env:USERPROFILE\.config\happy-notes\api-key" -Encoding utf8 -NoNewline
# 或设置环境变量：$env:IFLOW_API_KEY = "your_api_key"

Windows 用户注意：必须先创建 happy-notes 目录再写入 api-key 文件。如遇配置问题，请访问 API Key 管理页面 获取帮助。

Agent 按优先级尝试：环境变量 → 配置文件。Pipeline 脚本内部自动读取凭证，无需手动初始化。

快速决策树#

收到用户请求后， 按顺序判断：

text

1. 用户只是问问题/查信息？ → 不走 Pipeline，Agent 自行回答
2. 操作主体是什么？
   a. 知识库本身（列表/创建/删除/改名/详情） → pipeline_kb.py
   b. 知识库中的文件（列表/重命名/删除/详情/重试） → pipeline_file_management.py
   c. 需要新建库 + 上传文件/URL → P1 (pipeline_create_kb_and_generate.py)
   d. 向已有库追加内容（文件/URL/文本） → P3 (pipeline_import_and_generate.py)
   e. 在已有库中搜索内容 → 核心目的是生成? P2 : P4
   f. 联网搜索外部网页/论文 → P6 (pipeline_web_search.py)
   g. 直接对已有库生成报告/PPT → pipeline_generate.py
   h. 查看生成进度 → pipeline_check_status.py
   i. 分享知识库 → pipeline_share.py

快速决策表#

⚡ 多步骤任务优先用 Pipeline 脚本。Pipeline 已封装凭证读取、参数串联、解析轮询、错误处理，一条命令完成整个流程。仅 Pipeline 不覆盖的单步操作才直接调 API（见下方「直接调 API 参考」）。

收到用户请求后，按此表选择执行方式：

用户意图执行方式关键参数建库 + 上传 + 生成"建个知识库，传几篇论文，生成报告"Pipeline 1 pipeline_create_kb_and_generate.py``--name --files --urls --output-type --query"建个知识库存一下这些文件"（不生成）Pipeline 1--name --files --no-generate追加内容 + 生成"把这个链接/文件加到XX知识库，然后生成总结"Pipeline 3 pipeline_import_and_generate.py``--kb + --files/ --urls/ --text --output-type --query"帮我把这段内容存到知识库"Pipeline 3--kb --text --text-title --rename --no-generate搜索 + 生成"在XX知识库里搜一下关于YY的，生成报告"Pipeline 2 pipeline_search_and_generate.py``--kb --search --mode semantic --output-type --query"搜一下知识库里有没有关于XX的文件"Pipeline 2--kb --search --mode file --search-only语义检索（深度内容匹配）"知识库里有没有关于XX的内容"Pipeline 4 pipeline_semantic_search.py``--kb --query"找到相关内容后生成报告"Pipeline 4--kb --query --generate --output-type"检索后分享知识库"Pipeline 4--kb --query --share文件管理"看看知识库里有哪些文件"Pipeline 5 pipeline_file_management.py list``--kb"把这个文件改个名"Pipeline 5 rename``--kb --file --new-name"删掉这个文件"Pipeline 5 delete``--kb --file --force"把那几个测试文件都删了"Pipeline 5 batch-delete``--kb --files --force联网搜索 + 导入 + 生成（搜索结果存入知识库）"帮我搜一下关于XX的网页，整理成报告"Pipeline 6 pipeline_web_search.py``--kb --query --source WEB --output-type"搜一下XX的学术论文，生成综述"Pipeline 6--kb --query --source SCHOLAR --output-type"深度研究一下XX"Pipeline 6--kb --query --type DEEP_RESEARCH"搜一下XX的论文存到知识库"（不生成）Pipeline 6--kb --query --no-generate"搜一下XX看看有什么"（只看结果）Pipeline 6--kb --query --search-only（⚠️ 仍需知识库）快速搜索（不涉及知识库）"XX是什么" / "帮我查一下XX" / "最近有什么关于XX的新闻"不走 Pipeline，Agent 使用自身搜索能力直接回答—知识库管理查看/创建/删除知识库pipeline_kb.py list/ create/ delete``--name / --kb --force修改知识库名称/描述pipeline_kb.py update``--kb --name --description查看知识库详情pipeline_kb.py info``--kb文件管理补充查看文件详情pipeline_file_management.py info``--kb --file重试解析失败的文件pipeline_file_management.py retry``--kb --file内容生成（单独生成，不含搜索/导入）"帮我做个PPT" / "生成一份报告"pipeline_generate.py``--kb --output-type --query --preset"查看生成进度" / "做好了吗"pipeline_check_status.py``--kb [--creation-id]搜索管理停止正在进行的搜索pipeline_web_search.py --stop``--kb --stop删除搜索记录pipeline_web_search.py --delete-search``--kb --delete-search分享"把知识库分享给同事"pipeline_share.py``--kb**其他（极少数 Pipeline 未覆盖的操作）**修改知识库高级设置等查阅 references/api.md仅作为最后手段

--query 参数含义速查（⚠️ 不同 Pipeline 含义不同，传错会导致生成质量差或搜索失败）#

Pipeline--query 含义创作要求参数默认生成P1—--query（创作要求）是 → --no-generate 关闭P2—--query（创作要求），搜索词用 --search是 → --search-only 关闭P3—--query（创作要求）是（有新内容时） → --no-generate 关闭P4--query（ 检索关键词）--gen-query（创作要求）否 → --generate 开启P6--query（ 搜索关键词）--creation-query（创作要求）是 → --no-generate 关闭P-Gen—--query（创作要求）始终生成

⚠️ 易错点：

• P4：搜索词用 --query，创作要求用 --gen-query。千万不要把创作要求塞进 --query，否则搜索结果会偏离。
• P6：搜索词用 --query，创作要求用 --creation-query。不传 --creation-query 时脚本会自动生成默认 prompt。
• P2：搜索词用 --search（不是 --query）， --query 是创作要求。不要混淆。

记忆规则：P4 和 P6 的 --query 是搜索/检索词（因为搜索是它们的核心功能），创作要求用独立参数名。其他 Pipeline 的 --query 就是创作要求。 P4 是唯一默认不生成的 Pipeline，需要 --generate 显式开启。

Pipeline 2 搜索模式选择#

P2 有两种搜索模式，必须根据用户意图选择：

用户意图--mode原因搜 内容/主题（"关于XX的"）semantic语义匹配内容片段，精准但较慢搜 特定文件（"找一下叫XX的文件"）file按文件名+摘要匹配，快速但粒度粗

默认是 file 模式。用户说"搜一下关于XX的"时，必须显式加 --mode semantic。

Pipeline 2 vs Pipeline 4 如何选？#

一句话判断：P2 = 核心目的是 生成（搜索是选素材的手段）；P4 = 核心目的是 看检索结果（生成/分享是可选附加）。

场景用哪个原因搜索后要 生成 内容Pipeline 2专为"搜索→生成"设计，支持 file/semantic 两种模式纯检索，只看结果不生成Pipeline 4返回详细片段和来源文件检索后要 分享 知识库Pipeline 4内置 --share 参数检索后 可能 生成（可选）Pipeline 4用 --generate 可选触发生成

Pipeline 2/4 vs Pipeline 6 vs Agent 自身搜索 如何选？#

场景用哪个原因搜索 知识库内 已有内容Pipeline 2/4内部语义检索联网搜索 新的网页/论文，需要 存储/整理/生成****Pipeline 6外部搜索，结果导入知识库需要 深度研究报告****Pipeline 6 ( DEEP_RESEARCH)多轮搜索生成研究报告搜 学术论文 并整理Pipeline 6 ( --source SCHOLAR)搜索 arxiv 等学术库只想 快速了解 某个问题，不需要存储Agent 自身搜索（不走 Pipeline）用户只要答案，不涉及知识库

易混淆场景#

用户表达正确路由为什么"写篇博客"type= MARKDOWN, query 描述博客风格博客 = Markdown 报告"帮我总结一下" / "对比分析"type= PDF, query 传达要求总结/分析 = 报告"帮我记一下这些内容"Pipeline 3 --text文本导入，非 URL 导入"记一下今天吃饭50元"Pipeline 3 --text --create-if-missing短文本记录，自动匹配或创建知识库"今天买了本书花了30"Pipeline 3 --text --create-if-missing隐含记账意图，无需用户指定知识库"把这篇文章存到知识库"URL 导入（Pipeline 3 --urls）操作对象是链接，不是文本"找一下知识库里叫xxx的文件"Pipeline 2 --mode file按文件名（+摘要）匹配"搜一下知识库里关于XX的，生成报告"Pipeline 2 --mode semantic按内容语义匹配，核心目的是生成"知识库里有没有关于XX的内容"Pipeline 4语义检索内容片段"这篇论文讲了什么关于XX"Pipeline 4 --content-ids限定文件的语义检索"做个PPT"（未指定风格）type= PPT， 先询问风格Agent 应主动问：「PPT 有商务和卡通两种风格，您想用哪种？默认商务。」"做个卡通风格的PPT"type= PPT, preset= "卡通"PPT 风格参数"把文章存进去然后帮我写份报告"Pipeline 3多步任务用 Pipeline"搜一下XX的论文"Pipeline 6 (联网搜索)搜外部论文并整理，不是知识库内搜索"知识库里搜一下XX"Pipeline 2/4已有内容搜索"深度研究一下XX"Pipeline 6 ( DEEP_RESEARCH)多轮联网搜索 + 生成研究报告"深度研究一下XX的论文"Pipeline 6 ( DEEP_RESEARCH + --source SCHOLAR)深度研究 + 学术论文源"XX是什么" / "帮我查一下XX"Agent 自身搜索，不走 Pipeline用户只想要答案，不涉及知识库存储或生成"最近有什么关于XX的新闻"Agent 自身搜索，不走 Pipeline快速查询，无需导入知识库

核心判断规则#

• 用户只是 提问/查询信息，不涉及存储、导入或生成 → 不走 Pipeline，Agent 用自身搜索能力直接回答
• 操作对象是 知识库本身或其中的文件（增删改查、上传、导入）→ knowledge-base
• 操作对象是 基于知识库内容的产出物（报告、PPT、播客、思维导图、视频）→ reports
• 操作对象是 外部网页或学术论文，且需要 导入知识库或生成产出物 → Pipeline 6（联网搜索→导入→生成）
• 多步骤任务 → 优先 Pipeline 脚本

搜索分流关键判断：用户说"搜一下"时，看是否涉及知识库操作（存储、整理、生成报告等）。涉及 → Pipeline 6；不涉及 → Agent 自行搜索回答。

Agent 常见错误（⚠️ 必须避免）#

错误模式正确做法每个文件/URL 分别调用 Pipeline 1 创建知识库 → 产生 N 个空知识库一次请求只创建一个知识库，所有文件通过 --files "a.pdf,b.pdf" 逗号分隔一次传入不检查知识库是否已存在就创建新的先用 --kb "名称" 查询是否已有同名知识库，有则改用 Pipeline 3 追加submitted 状态告诉用户"已生成完成"submitted 仅表示任务进入队列，只有 success 才是真正完成对生成任务循环轮询状态提交后告知用户预计时间，用户主动问时才查一次用 curl/ iflow_api 直接拼 HTTP 请求调 API（如 creationList、 shareNotebook 等）必须使用 Pipeline 脚本。Pipeline 已封装凭证、参数校验、轮询、错误重试。直接调 API 容易出错且不稳定。所有 20 个 API 端点均已有 Pipeline 覆盖，不存在"需要直接调 API"的场景Pipeline 输出有 failedCount 但 Agent 不告知用户检查 Pipeline 输出 JSON 中的 failedCount/ failedItems/ importFailedCount 字段， 如有失败必须告知用户（如"3 个文件已导入，1 个失败：bad.exe 格式不支持"）

错误处理#

错误码场景Agent 应对方式40010深度研究并发限制（同时只能运行 1 个）告知用户「您有一个深度研究任务正在进行中，请等待完成后再发起新的深度研究」。 不要重试，建议用户稍后再试，或改用 FAST_SEARCH 快速搜索500（搜索/创作）搜索和创作接口限流（合计 20 次/分钟）Pipeline 脚本内部已自动重试。如果仍然失败，告知用户「请求过于频繁，请稍后再试」40004文件尚在解析中就提交了生成任务告知用户「文件正在解析中」，等待解析完成后再提交生成任务

文件上传限制#

限制项上限说明单文件大小20MB超过需先压缩或拆分PDF 页数500 页超过需先拆分为多个文件再分批上传

用户上传大文件/长 PDF 时，Agent 应提前告知限制，建议拆分后分批导入同一知识库。

操作前置依赖链#

⚠️ 必须严格遵守：

text

创建知识库 → 导入文件 → 文件解析完成(status=success) → 生成产出

1. 没有知识库就不能导入文件：必须先有 collectionId，才能调用文件上传/导入接口
2. 文件未解析完成就不能生成产出：必须确认 status=success，否则返回错误码 40004
3. 多步任务必须逐步确认：用户说"导入这篇文章然后生成报告"时，必须先完成导入并确认解析完成，再提交生成任务， 不能并行提交

轮询策略#

操作类型策略说明文件解析Pipeline 内部自动轮询（5s 间隔）Agent 无需干预，告知用户"正在处理"即可内容生成（提交后）不轮询，立即返回告知用户预计时间，等用户问"做好了吗"时再查内容生成（用户询问）单次查询 creationList查一次告知状态，不要循环轮询联网搜索Pipeline 内部自动轮询Agent 向用户展示进度即可

关键原则：搜索 + 创作接口共享 20 次/分钟 限额。内容生成任务有排队机制，高峰期耗时更长。Agent 绝不循环轮询 生成状态，提交后立即返回，用户询问时查一次。

Pipeline 脚本#

每个 Pipeline 的完整参数说明、输出 JSON 格式和使用示例见 references/pipelines.md。

Pipeline脚本用途关键参数P1pipeline_create_kb_and_generate.py建库+上传+生成--name --files --urls --output-typeP2pipeline_search_and_generate.py搜索+生成--kb --search --mode --output-typeP3pipeline_import_and_generate.py追加+生成--kb --files/ --urls/ --text --output-type --create-if-missingP4pipeline_semantic_search.py语义检索+生成/分享--kb --query --generate --shareP5pipeline_file_management.py文件管理--kb + list/ rename/ delete/ batch-delete/ info/ retryP6pipeline_web_search.py联网搜索+导入+生成--kb --query --source --type --stop --delete-searchP-Genpipeline_generate.py直接生成（已有知识库）--kb --output-type --query --presetP-KBpipeline_kb.py知识库管理list/ create/ delete/ update/ infoP-Checkpipeline_check_status.py查看生成进度--kb --creation-idP-Sharepipeline_share.py分享知识库--kb

通用说明：

• 知识库定位：所有 Pipeline 支持 --kb（名称模糊匹配）和 --kb-id（ID 精确指定）
• 输出格式：结构化 JSON 到 stdout，进度日志到 stderr
• 参数串联：Pipeline 1 返回的 collectionId 可传给其他 Pipeline 的 --kb-id
• 参数校验：所有 Pipeline 在调用 API 前校验 --output-type、 --preset、文件路径和 URL 格式，无效参数直接报错
• 删除确认：Pipeline 5 删除操作默认需交互确认，Agent 调用时 必须加 --force
• 列表上限： pipeline_kb.py list 最多返回 100 个知识库， pipeline_file_management.py list 最多返回 100 个文件。超出时建议用 --keyword/ --file 按关键词过滤

创作状态术语（⚠️ 严格区分）#

Pipeline 输出的 creationStatus含义Agent 应告知用户submitted生成任务已提交到队列， 尚未完成「生成任务已提交，预计需要 10-30 分钟，您可以稍后问我"做好了吗"来查看进度」pending排队等待处理「任务排队中，请耐心等待」processing正在生成中「正在生成中，请稍候…」success真正完成，内容可查看「已生成完成！」failed生成失败「生成失败：[具体原因]。建议检查源文件后重试」

绝对禁止：在 submitted 或 processing 阶段使用"已完成""已生成"等措辞。只有 success 才代表真正完成。

操作指南#

分享功能#

用户可以将知识库分享给他人。分享包含以下内容的 只读快照：

• 知识库中的 全部文件
• 已生成的 产出物

分享权限： 被分享者只能 查看，不能编辑知识库内容，也不能基于该知识库再次生成新的产出物。

shell

# 使用 Pipeline 脚本（推荐）
python3 scripts/pipeline_share.py --kb "AI 论文集"

脚本会自动查找知识库、调用分享 API、拼接分享链接并输出。

展示（Agent 用实际输出替换）：

text

知识库「AI 论文集」的分享链接已生成：
https://iflow.cn/inotebook/share?shareId=xxx

被分享者可查看知识库中的所有文件和已生成的内容（只读，不可编辑或再生成）。

如需"检索 + 分享"组合操作，可用 Pipeline 4： pipeline_semantic_search.py --kb "..." --query "..." --share

内容检索#

两种检索方式：

• 语义检索（ searchChunk）：按语义匹配内容片段，精准但较慢（同步接口，几秒到几十秒）
• 文件级匹配（ pageQueryContents）：API 的 fileName 参数只按文件名匹配；Pipeline 2 的 file 模式会拉取全量文件列表后在客户端同时匹配 fileName 和 summary，快速但粒度粗

直接调 API 的用法见 knowledge-base/SKILL.md。

文本导入#

用户粘贴纯文本内容要存入知识库时， 优先使用 Pipeline 3：

shell

python3 scripts/pipeline_import_and_generate.py \
  --kb "知识库名称" --text "用户粘贴的内容" \
  --text-title "文件标题" --rename --no-generate

Pipeline 内部会自动创建临时 .md 文件 → 上传 → 清理 → 重命名。后端不提供独立的文本创建接口，必须通过文件上传实现。手动实现方式见 knowledge-base/SKILL.md。

智能知识库匹配#

当用户没有明确指定目标知识库时，Agent 需智能推断。完整匹配逻辑（默认配置检查 → 语义匹配 → 置信度处理 → 命名规则）见 references/kb-matching.md。

核心流程：检查默认配置 → 列出知识库按语义匹配 → 高置信度直接用 / 中等确认 / 无匹配建议创建。Pipeline 3 --create-if-missing 可在知识库不存在时自动创建。

用户体验#

• 隐藏内部 ID：展示中使用知识库名称、文件标题，ID 仅用于 API 调用

  • 正确： 已导入到知识库「AI 论文集」
  • 错误： 已导入到知识库 c7e804b0-82f1-4617-b720-bebfac16b8d1

• 精简进度：不暴露内部操作细节，只报告用户关心的信息

  • 上传文件： 正在导入 attention.pdf… → 已导入到「AI 论文集」
  • 创作生成： 正在生成内容… → 内容已生成

• 批量操作：汇总结果，如 3 个文件已导入，1 个失败（bad.exe: 格式不支持）

• 格式化展示： text

  你的知识库：
  

1. AI 论文集 — 5 个文件
2. 竞品分析 — 12 个文件
3. 技术方案 — 3 个文件

## API 参考

> **⚠️ 禁止直接用 `curl`/ `iflow_api` 拼 HTTP 请求。所有 20 个 API 端点均已有 Pipeline 脚本覆盖，必须通过 Pipeline 脚本执行操作。**
>
> Pipeline 脚本已封装凭证读取、参数校验、解析轮询、错误重试，一条命令完成整个流程。直接拼 HTTP 请求容易出错（参数格式错、缺少轮询、无重试），且不利于用户理解操作进度。
>
> 如需了解 API 底层细节（仅供理解原理，不应直接调用），参见 `references/api.md`。