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 参考」）。

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

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

⚠️ 易错点：

• 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/4 vs Pipeline 6 vs Agent 自身搜索 如何选？

易混淆场景

核心判断规则

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

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

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

错误处理

文件上传限制

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

操作前置依赖链

⚠️ 必须严格遵守：

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

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

轮询策略

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

Pipeline 脚本

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

通用说明：

• 知识库定位：所有 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 按关键词过滤

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

绝对禁止：在 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。