放入资料
上传扫描 PDF，经 OCR、切块和向量化，进入知识库。
QUANMIN AGENT / INDEPENDENT PROJECT
让分散的工具，
一起把事做完。
从找到一份资料，到交付一份报表。
一个连接知识、文件与飞书的 Web Agent。
QUANMIN / WORKSPACE产品能力示意
PDF / 知识XLSX / 数据飞书 / 协作
一个任务，一起完成。理解 → 选择工具 → 执行 → 核验THE QUESTION BEHIND IT
工具已经很多。
我更关心，它们如何一起工作。
最初，我想给自己做一个 Personal Agent。后来，问题逐渐变得清楚：资料、数据和操作分散在不同平台，完成一件事仍需要人不断搬运上下文。Quanmin Agent 是我对这件事的一次实际探索。
04 实机案例Web 浏览器即入口TS 统一应用技术栈
WATCH THE PRODUCT / 真实产品，真实执行
01 知识库问答 / 01 OF 04
让一份 PDF，成为可追溯的回答。
录制于 2026 年 10 月。私人侧栏已裁去，过程经剪辑压缩，结果停留展示；预录视频不会发起模型请求。
用自然语言提问
Agent 根据任务选择知识库 Skill，通过工具查找相关内容。
带着依据回答
回答附上文档来源与 PDF 页码，可以回到原文核对。
阅读演示说明与结果
使用公开城市更新研究报告的扫描摘页，真实检索并引用来源。数字属于报告观点，未独立核实。文字层完整的文件不需要 OCR。
02 飞书文档与消息 / 02 OF 04
从几个数字，到一份飞书周报。
录制于 2026 年 10 月。私人侧栏已裁去，过程经剪辑压缩，结果停留展示；预录视频不会发起模型请求。
说清楚要做什么
给出模拟订单、销售额和退款数据，请 Agent 制作运营周报。
生成可协作的文档
计算环比与退款占比，整理摘要、指标表和下周行动建议。
把成果送到飞书
按指令分享给本人，再由机器人发送文档链接与摘要。
阅读演示说明与结果
真实创建飞书文档：订单与销售额环比均为 14.3%，退款占销售额 2.5%。录屏包含飞书文档实页及 Agent 的发送回执。机器人创建后，按后续指令授予本人查看权限，并发送一条私聊消息、回读核对；没有发给其他人。全部为模拟业务数据。
03 Excel 报表交付 / 03 OF 04
改一个数字，交付整张报表。
录制于 2026 年 10 月。私人侧栏已裁去，过程经剪辑压缩，结果停留展示；预录视频不会发起模型请求。
上传已有的 Excel
模拟电商周报包含多个产品、七天销售和多个指标，保留上传原件。
修改、重算、导出
销量从 31 改为 32，重算公式，生成新版 Excel 和完整表格图片。
预览、下载、发送
结果留在对话中可预览和下载，报表图片发送到本人飞书私聊。
阅读演示说明与结果
真实处理模拟工作簿，重算后全店周销量为 1,732，净销售额为 192,925 元。使用固定 spreadsheet Skill 与 CLI。发送时发生一次本地路径参数校验失败，修正为相对路径后成功，仅投递一条图片；成片保留最终说明。视频展示的是表格报表图片。
四个场景 / 演示结束
看过结果，再看背后的选择。
技术与架构 →认识构建它的人 ↗UNDER THE HOOD / 关键选择
把复杂性放在
真正需要它的地方。
应用层统一 TypeScript；复用 Agent 执行能力，把精力放在身份、工具接入与业务交付。点击路径，查看每层的职责。
01 / 交互入口
让产品通过浏览器抵达用户。
React + TypeScript 构建 Web 界面，Vite 负责构建。前后端共享流式事件类型，减少接口理解偏差。文件预览、执行反馈和成果下载都在同一段对话里。
复用 Pi，保留自己的产品层
此前搭建 LangChain Agent 时，我需要补齐会话与上下文管理。个人项目选择 Pi，复用执行循环、工具协议和会话压缩；产品账户、权限和外部工具仍由应用层负责。
取舍：减少重复建设，也需要关注运行时升级与会话格式兼容。一套 PostgreSQL，承接多种状态
业务数据由 PostgreSQL 持久化，pgvector 存储向量，pg-boss 承接任务队列。复用已有数据库，控制单机部署的组件数量。
取舍：简化运维；数据库备份、资源预算与任务恢复必须认真处理。轻量检索，适应实际资源
在 4 GB 内存服务器的约束下，没有部署整套 RAGFlow。文字提取与 LangChain 切块留在应用侧，按需调用百度 OCR 与百炼 Embedding，再用 pgvector 检索。
取舍：依赖外部服务的费用与可用性。当前为向量检索，混合检索与重排尚未上线。把可重复的动作固化下来
Skill 说明怎么完成任务，CLI 提供可复用操作。表格由 LibreOffice 重算与渲染，避免每轮从零编写临时代码；Langfuse 追踪模型与工具调用，辅助排查。
取舍：封装需要维护，但执行过程更容易复查和验证。DELIVERY IS MORE THAN A DEMO
不只看它答得好，也检查它能否交付。
知识问答核对来源与 PDF 页码；表格处理核对指定单元格、重算结果与可下载文件。演示使用模拟数据，验证执行链路，不等同于业务收益证明。
账户数据按用户隔离，外部系统使用对应授权。工具执行边界由程序约束；涉及发送与写入的任务，按用户指令范围执行。
任务状态与执行记录持久化，使用 Langfuse 排查调用。对可能产生重复副作用的中断任务，不盲目自动重放；静态站点发布保留上一版本以便回退。
运行基座Docker + Nginx原文件服务器持久磁盘调用追踪OpenTelemetry → Langfuse
HOW MY THINKING EVOLVED
框架会换，交付的标准不变。
从节点工作流开始
用 LangGraph 组织流程，逐步理解业务步骤与 Agent 自主执行各自适合的位置。
搭建自己的 Agent 平台
探索现成系统后，基于开发环境、集成与修改成本，选择 LangChain，并自行补齐上下文和持久化能力。
让核心轻一些，连接深一些
选择 Pi 与 TypeScript，把更多时间放在权限、业务工具和 Web 体验上，用真实链路检验每次选择。
BUILDING THE SYSTEM
从执行核心，到一个可用的 Web 产品。
01 / 应用与运行时分工
Pi 承接执行循环、原生工具与会话压缩语义；Node.js 承接 HTTP 和流式输出。账户、授权、持久化与业务入口放在产品层，避免把运行时当成完整的多用户产品。
前后端统一 TypeScript，共享事件类型。这个选择服务于 Web 交付与接口维护，而不是要求每个工具都使用同一种语言。
02 / 上下文不是无限堆积
此前搭建 Agent 时，我关注前缀稳定、结构化摘要和近期对话保留：压缩后仍要知道目标、已完成事项和剩余工作。当前选择复用 Pi 的会话能力，并将会话条目持久化到 PostgreSQL。
这减少了重新实现上下文机制的工作，也带来版本兼容责任：运行时升级时，需要验证历史会话能否恢复。
03 / 文件进入知识库的路径
PDF 优先提取文字层，Word 与 Markdown 直接解析；扫描页按需交给百度 OCR。随后通过 LangChain 文本切块，调用百炼 Embedding，并写入 pgvector。
只有处理完成的文件参与检索。切块保留来源与 PDF 物理页码，Agent 通过知识检索 Skill 与 CLI 查找内容，再组织带引用的回答。
04 / 先验证，再固化
表格方案先做 Spike，分别验证文件读写、公式重算和图片导出。ExcelJS 无法独立完成后两项，因此使用 LibreOffice 承接，再把稳定路径封装为 Skill 与 CLI。
验证落到实际链路：上传文件、修改数据、核对结果、生成文件并按指令交付。功能成功之外，还检查失败状态与可继续处理的路径。
当前边界
原文件保存在服务器持久磁盘，需要与数据库共同备份。现阶段采用单机部署与外部模型服务；混合检索、重排及更多业务连接是后续方向，不作为已交付能力。
ENGINEERING NOTES / 01
一次请求，如何成为一次可靠的执行。
聊天入口只是表面。请求背后，需要明确谁在操作、任务处于什么状态，以及结果应交付到哪里。
身份先于执行
Web 请求首先属于一个产品账户。用户、会话、文件和知识库按账户关联；服务端在查询与操作时检查归属。飞书身份通过应用标识和 open_id 关联，不能因为名字相同就合并账户。
登录与工具授权是两件事：登录解决“你是谁”，外部系统授权决定“你能做什么”。连接飞书后，也必须区分应用身份与用户身份，不能把开发者自己的权限默认借给所有访客。
排队与对话各自保存什么
PostgreSQL 保存产品消息、任务状态与执行记录；Pi 的会话条目也持久化到数据库，以便继续使用运行时原有的上下文语义。pg-boss 承接任务领取和生命周期，应用层管理用户并发与同会话串行。
模型命名属于辅助请求，与实际业务任务分开处理。浏览器断开也不意味着任务应当消失；重新打开页面时，产品需要根据持久状态恢复展示。实时流式体验和任务是否完成，是两个不同的问题。
工具调用与权限不混在一起
Agent 根据任务选择 Skill，读取使用方式，再通过 CLI 完成具体操作。这样可以把通用执行循环与业务能力分开：增加知识检索或表格操作，不需要为每种业务重写一套 Agent。
但 Skill 只是模型可读取的说明，不是安全边界。账户范围、可访问文件和执行隔离必须由程序约束。文档中的文本、评论和检索结果都是输入材料，不应获得改变权限的能力。
失败后，先判断有没有产生副作用
读取失败和发送结果未知，不能采用同一种重试策略。对于已经执行中的任务，进程中断可能发生在写入或发送之后；直接重新运行，可能造成重复消息或重复修改。
因此任务保留中断与未知状态，不盲目重放有副作用的动作。排障时同时查看业务状态、工具结果和调用追踪，再决定如何处理。当前方案面向单机部署，不能据此宣称多副本高可用。
ENGINEERING NOTES / 02
知识库的重点，是把来源留到最后。
文件能入库还不够。检索、阅读与引用之间，需要保留一条可以核对的路径。
解析：让不同文件走合适的路径
PDF 先尝试提取文字层；Word 和 Markdown 直接解析。文字不足或乱码的 PDF 页再使用 OCR，避免把本来可以直接读取的文档全部送去识别。OCR 使用百度云服务，向量化使用百炼 Embedding。
解析任务有文件大小、页数和文本长度限制。上传成功只表示文件已接收，不等于知识已经可用；界面需要展示处理状态，完成向量化后才允许检索。
切块：语义长度和来源精度一起考虑
LangChain 文本切块组件负责按段落和中文标点分割，并保留相邻内容重叠。PDF 的块不跨物理页，便于检索后返回明确的来源位置。
页码必须说明是哪一种：PDF 第几页不一定等于正文印刷页号。Word 和 Markdown 没有可靠页码时，不为它们编造页码；引用呈现文档名称与实际可定位的信息。
检索：匹配到内容，不等于答案已经成立
查询向量与 pgvector 中的内容向量进行匹配，返回相关片段。Agent 还需要阅读这些内容，判断是否足以回答问题；必要时继续检索或读取邻近内容。
目录查询和语义检索各有用途。列出已有文件应走目录能力，不能靠相似度猜测文件清单。当前实现是向量检索；关键词混合检索与重排有价值，但尚未作为已上线能力宣传。
成本：选择能在现有资源下运转的方案
本地开发机和服务器的内存都有限，因此没有部署完整 RAGFlow。应用侧承担解析、切块与状态管理，较重的 OCR 和 Embedding 通过外部服务完成，向量与业务数据共用 PostgreSQL。
这降低了本机资源需求，但引入网络延迟、外部服务可用性和调用成本。OCR 提交结果不明确时不能随意重交；原件、处理状态和外部任务编号都需要被认真管理。
ENGINEERING NOTES / 03
把工具接进来，也把结果交出去。
连接一个 API 只是起点。业务还需要上下文、权限、反馈和真实可用的交付物。
飞书评论：沿着原来的讨论完成工作
选中文档内容并 @Agent 后，事件先持久化，再快速确认接收，后台执行任务。这样避免让模型执行时间阻塞事件响应；重复通知通过事件与评论标识去重。
原讨论串提供任务上下文，处理结果回到同一讨论串。OK 用于表达已经接收，DONE 仅在任务完成并交付后标记。表情负责简洁反馈，实际任务状态仍以后台记录为准。
Excel：读写、计算与呈现是三种能力
调研时先验证现成库究竟能做什么。ExcelJS 可以读写工作簿，但不能独立承担完整的公式重算与表格图片导出，因此最终引入 LibreOffice，由后端调度完成重算与渲染。
稳定步骤封装为 CLI，再用 Skill 指导 Agent 使用。验收不是只检查文件是否生成，还要修改具体单元格，核对联动公式结果，并检查图片与新版工作簿。
文件：一轮结束，工作不应该丢失
上传原件与生成结果分开保存。用户下一轮继续修改时，Agent 应能接着使用本会话文件；用户也应能从消息中的附件卡片直接预览和下载，而不是猜测内部文件名。
当前采用服务器持久磁盘，提供用量与手动管理，不自动清理。磁盘足够使用不代表可以无限增长；配额、删除记录与备份是持续运营需要关注的部分。
部署与观察：验证对象必须是实际产品
Docker 封装运行环境，Nginx 承接入口；Langfuse 观察模型与工具调用，OpenTelemetry 提供打点。日志和追踪用于回答“执行到哪里、为什么失败”，不能替代用户验收。
验证按风险选择：简单页面调整看构建与浏览器效果；权限、队列、持久化等重要逻辑需要业务测试；外部服务则用真实文件、真实工具调用验证完整路径。上线后继续检查公开入口与资源加载。
下一页 / 关于我
了解技术之后，
认识构建它的人。
继续了解我 →THE BUILDER / QUANMIN
从业务现场出发，
把方法做成系统。
我关注 AI 数字化与 FDE 方向：和业务一起厘清问题，把方法论、数据和工具连接起来，再用实际交付验证它。
在此前的项目制工作中，我主导 Agent 平台的技术选型、搭建与集成，从工具、CLI 和 Skill，到前端展示和调试。业务方法论的提炼，与业务同事及负责人共同完成。
在这个个人项目中
我负责需求与产品判断、架构选择、交互与 UI 设计、推进及验收；借助 AI 协作完成代码实现、测试和部署。这里展示的，是这些选择最终运行起来的结果。
把人工取数与写报告，变成可交付的流程。
面对投流服务团队向客户交付周报的需求，搭建 Agent 平台，用 SQL 固定取数与指标口径，将业务报告结构沉淀到生成流程中。
部分项目的周报无需修改即可交付；其他项目由业务人员校验并调整分析内容。
来自本人项目经历描述，非统一口径的独立效果统计；不展示原公司数据。用自然语言交代规则，让执行有边界。
把指定时间、账户指标和条件动作组织为定时任务。调整账户前进行人机确认；已明确授权的动作按授权边界执行。
我的重点：把“帮我盯一下”转成可执行的任务，并把权限与确认放进流程。
此前工作项目能力，不代表当前个人产品已接入广告账户。把业务团队的方法论，交付成可运行能力。
与业务同事及负责人共同梳理诊断方法，我主导数据获取、流程组织、工具集成与输出呈现的工程化。验证多种交付形式后，按平台要求采用 Markdown。
通过合作平台审核，在内测版本上架并向商家开放。
基于本人参与经历；未确认后续公测状态，不披露客户与合作条款。WORKING WITH THE BUSINESS
我如何把业务描述，推进到交付。
先理解原来怎么做
以周报为例，先和业务同事梳理取数、指标口径、报告结构及客户需要的结论。SQL 固定计算口径，Agent 负责在这一基础上组织内容；分析是否适合客户，由业务验收。
方法论共同提炼，工程化由我推进
账户诊断 Skill 的方法来自与业务人员、负责人共同讨论。我主导数据拉取、工具与流程封装、结果呈现和平台适配。尝试飞书文档、HTML 与 Markdown 后，最终按平台条件选择 Markdown 交付。
用实际交付看效果
此前的周报项目中，部分报告无需改动即可交付，部分仍需修改分析。对我而言，这种业务反馈比“生成成功”更有意义；它决定了下一步该改提示、数据口径，还是整个流程。
把人的判断保留在关键位置
账户监测可以用自然语言交代时间、阈值和动作，但执行权限必须明确。需要确认的调整交给人决策，已授权的操作在边界内执行。自动化的便利不能取代责任划分。
为什么继续做个人项目
我希望有一个自己会持续使用的 Personal Agent，也希望用一个公开可观察的产品展示我的思考。当前先把知识、文件与飞书连接起来，未来再根据真实需求扩展，而不是先把所有系统都接一遍。
PROJECT STORY / 01
电商周报：从手工取数，到业务可以交付。
工作经历 · 投流服务团队面向客户的周期性交付
问题从业务流程里出现
团队需要向客户交付周报。原来的工作包括拉取数据、计算指标、按既有结构撰写报告，再由业务人员检查。取数与写报告都需要重复投入时间，而且最终输出必须符合客户熟悉的形式。
我的目标不是单纯让模型写一段分析，而是搭建能承接这条流程的 Agent 平台，让生成结果接近业务原本可以交付的报告。
我负责把方法落实到系统
在项目制分工下，我是平台建设的主要推进者：技术栈选择、Agent 核心、工具调用、CLI、Skill，以及前端展示和调试都由我主导。业务报告口径与方法，则需要和业务同事一起梳理。
通过 SQL 明确取数与计算逻辑，把报告结构组织到生成流程中。相对确定的指标交给明确规则，分析与表达交给 Agent，再由业务判断分析是否适合客户。
结果与仍然需要人的部分
实际验收中，部分项目拿到周报后可以不改动直接交付；另一些项目需要校验并调整部分分析内容。这些反馈说明流程已经能产生可用结果，也说明分析质量仍然需要结合业务场景判断。
这里不把个人观察换算成一个统一的准确率或节省工时。对我更重要的是：哪些内容能稳定复用，哪些内容仍需人判断，以及这些差异应该如何反馈到下一次迭代。
PROJECT STORY / 02
诊断 Skill：和业务共创，把能力工程化。
工作经历 · 账户诊断方法与平台交付
共同提炼，而不是一个人发明方法
这个项目与业务团队协作，也有负责人共同参与方法论梳理。我的角色是主要推进工程化的人：理解诊断思路，梳理需要哪些数据、从哪里取得、如何组织成可执行步骤。
业务经验不能只写成一段提示词。数据表、取数方式、判断依据和输出结构，都影响 Skill 最终能否被稳定调用。
围绕交付条件调整呈现
过程中探索了飞书文档、Markdown 和 HTML 等输出形式。不同呈现方式都可以承载诊断结果，但最终需要满足合作平台的使用与交付条件，因此选择 Markdown。
这次经历让我更重视“适合交付”的含义：界面丰富并不总是第一目标。能被平台接受、能让业务理解、能被后续复用，才是具体场景中的判断依据。
最终交付与职责边界
Skill 通过合作平台审核，在内测版本上架，并已向商家开放。之后是否进入公测，我没有足够信息确认，因此不把未知进展计入成果。
方法论来自共同协作，我主导数据获取、流程封装、工具集成与呈现适配。对外介绍时，我希望把这两部分都讲清楚：既说明个人承担的工作，也保留团队贡献。
PROJECT STORY / 03
账户监测：让自动化理解条件，也尊重授权。
工作经历 · 定时检查与账户操作
把口头要求变成明确任务
业务可以用自然语言交代：在某个时间检查指定账户，观察预算或指标，如果达到条件则采取相应动作。Agent 将这些要求组织为定时任务，再到指定时间读取数据与判断。
相比让人逐项配置规则，这种入口更接近业务的表达方式。但条件、账户范围与动作仍然需要明确，不能只因为输入是一句话，就省略执行约束。
确认机制是流程的一部分
对于需要人决定的调整，系统把情况交给人确认后再执行；对于事先已经明确授权的动作，则在授权范围内处理。人的确认不是每次机械重复，而是与动作风险和已有授权关联。
这段实践影响了我的个人产品：接入工具时，不仅考虑“能不能调用”，还要考虑“代表谁调用”“允许做到哪一步”和“发生异常后如何判断结果”。当前 Quanmin Agent 尚未接入广告账户。
MY PRACTICE / 04
我在个人产品里，继续验证这些判断。
Quanmin Agent · 从 Personal Agent 出发的独立实践
为什么选择 Web
我希望手机和电脑都能通过浏览器进入同一个工作空间，不必为了每个平台安装一个客户端。于是选择 Web 作为主要入口，并统一应用层的 TypeScript 技术栈，让前后端协作和维护更直接。
如果以后需要采集本机环境或完成浏览器无法承担的工作，客户端仍可能有价值。但它应该由具体需求推动，而不是先增加一种交付形态。
为什么从 LangChain 转向 Pi
此前使用过 LangGraph 节点工作流，也在工作项目中基于 LangChain 搭建 Agent。那段经历让我看到，会话、持久化和上下文管理需要大量细节工作，而这些并不是每个业务项目都值得从头实现。
个人项目选择 Pi，是因为它的核心较轻，并已有可复用的执行与会话机制。我仍使用 LangChain 的文本切块组件。选择框架是为了匹配工作边界，而不是要求所有能力来自同一个生态。
如何与 AI 协作
我负责提出目标、界定问题、判断方案、审阅体验并验收结果，借助 AI 推进代码、测试和部署。出现不确定性时，先做一个有明确问题的 Spike，再决定是否引入正式实现。
这个页面上的表格处理、OCR 与文档协作，都经历过具体尝试和修正。产品中附件预览、文件归档、执行反馈等细节，也来自实际使用时不断发现问题，再回到实现中调整。
我希望继续承担怎样的工作
我对 AI 数字化与 FDE 的兴趣，在于进入真实流程：和业务一起确认目标，连接已有数据与系统，交付能被使用的应用，并继续处理反馈。技术选型是其中一部分，沟通、验收和维护同样重要。
Quanmin Agent 是我可以公开展示的实践载体。它展示当前已经运行的知识库、文件处理和飞书协作，也保留未来连接更多业务的空间。财务、网店等连接仍是探索方向，不是已完成的产品能力。
A WORKING PRODUCT. AN ONGOING PRACTICE.
我的下一步，
是连接更多真实业务。
当前已连接知识库、文件处理与飞书。财务、网店与更多业务系统是后续探索方向，尚未接入。
回到四个实机案例 ↑已有授权？打开 Agent ↗演示无需登录。当前飞书登录受应用可用范围限制，暂不提供任意外部账号自助试用。
04 飞书文档内协作 / 04 OF 04
在飞书文档里，@它把图补上。
2026 年 10 月 28 日新建模拟周报并真实执行。连续采集操作过程，镜头经平滑缩放，执行等待加速，个人信息已遮挡；视频不会发起新的模型请求。
直接在文档里提出需求
选中原文，在局部评论中 @quanmin-agent，请它把渠道销售额做成图表。
用表情反馈任务状态
接下任务时标记 OK；读取数据、制作图表并核验，交付后标记 DONE。
写回原文档，回复原讨论串
在文末追加横向柱状图，保留原文与表格，并在评论中说明核验结果。
阅读演示说明与结果
全新文档《秋日生活馆｜渠道增长周报》使用虚构数据。内容直播 46.8、自然搜索 32.4、信息流投放 25.6、私域社群 16.2、其他渠道 7.6，单位均为万元，合计 128.6 万元。Agent 在本次任务中实际生成并插入图表图片，完成后返回原评论串。本功能需要文档访问权限和应用事件订阅，不代表任意外部飞书账号都可使用。