happy-notes

iflow 知识库助手(iflow知识库),支持知识库管理、文件上传/URL导入、内容生成、联网搜索并导入知识库。 当用户提到知识库、资料库、收藏文章、保存链接、上传文件、导入网页、 生成报告、生成PPT、生成播客、生成思维导图、生成视频、分享知识库、 查看生成进度、搜论文并整理、查文献并生成报告、深度研究、搜索网页并存到知识库时,使用此 skill。 即使用户没有明确说"知识库"或"报告",只要

SKILL.md

GitHub

Cleanup Review

python scripts/_reset_state.py is an optional cleanup helper for the happy-notes skill. It may recursively remove /tmp/_skill_work, /tmp/skill_scratch. Show the exact paths first, explain whether they are skill-private temporary paths or user state, and run the cleanup only after the user confirms.

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. 存储凭证(二选一):
# 方式 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"
# 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 脚本内部自动读取凭证,无需手动初始化。

快速决策树

收到用户请求后,按顺序判断:

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 应提前告知限制,建议拆分后分批导入同一知识库。

操作前置依赖链

⚠️ 必须严格遵守:

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

轮询策略

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

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

Pipeline 脚本

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

Pipeline 脚本 用途 关键参数
P1 pipeline_create_kb_and_generate.py 建库+上传+生成 --name --files --urls --output-type
P2 pipeline_search_and_generate.py 搜索+生成 --kb --search --mode --output-type
P3 pipeline_import_and_generate.py 追加+生成 --kb --files/--urls/--text --output-type --create-if-missing
P4 pipeline_semantic_search.py 语义检索+生成/分享 --kb --query --generate --share
P5 pipeline_file_management.py 文件管理 --kb + list/rename/delete/batch-delete/info/retry
P6 pipeline_web_search.py 联网搜索+导入+生成 --kb --query --source --type --stop --delete-search
P-Gen pipeline_generate.py 直接生成(已有知识库) --kb --output-type --query --preset
P-KB pipeline_kb.py 知识库管理 list/create/delete/update/info
P-Check pipeline_check_status.py 查看生成进度 --kb --creation-id
P-Share pipeline_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 才代表真正完成。

操作指南

分享功能

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

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

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

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

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

展示(Agent 用实际输出替换):

知识库「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:

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: 格式不支持)
  • 格式化展示:
    你的知识库:
    1. **AI 论文集** — 5 个文件
    2. **竞品分析** — 12 个文件
    3. **技术方案** — 3 个文件
    

API 参考

⚠️ 禁止直接用 curl/iflow_api 拼 HTTP 请求。所有 20 个 API 端点均已有 Pipeline 脚本覆盖,必须通过 Pipeline 脚本执行操作。

Pipeline 脚本已封装凭证读取、参数校验、解析轮询、错误重试,一条命令完成整个流程。直接拼 HTTP 请求容易出错(参数格式错、缺少轮询、无重试),且不利于用户理解操作进度。

如需了解 API 底层细节(仅供理解原理,不应直接调用),参见 references/api.md。