1. 项目概述当AI Agent遇见飞书知识库最近在整理团队沉淀在飞书知识库里的文档看着那几百个节点、嵌套了七八层的目录树我头都大了。手动梳理光是想想就让人望而却步。这几乎是每个使用飞书进行知识管理的团队都会遇到的痛点文档越积越多结构越来越乱新成员入职想快速了解知识体系老员工想找个历史文档都得在迷宫般的目录里“捉迷藏”。就在我琢磨着是不是要写个脚本硬啃飞书API的时候一个组合方案进入了我的视野AI Agent lark-cli。简单来说就是让一个具备逻辑推理能力的AI智能体通过飞书官方的命令行工具自动去读取、分析并生成一份清晰的知识库目录结构图。这个想法让我眼前一亮因为它完美地结合了“自动化”与“智能化”。AI Agent负责理解复杂的文档层级关系和内容lark-cli则提供了稳定、官方的数据通道。经过一番折腾我不仅跑通了整个流程还把核心逻辑封装成了一个开箱即用的开源工具。这个项目解决的远不止是“生成一个目录”这么简单。它本质上是在解决知识资产的可视化与结构化难题。对于团队负责人它能一键生成知识全景图快速评估知识体系的完整性与合理性对于新人它是一份极佳的“寻宝地图”对于知识管理者它是定期进行知识库“体检”的自动化工具。整个过程你只需要一个飞书应用的权限和一句命令。2. 核心工具链选型与设计思路为什么是AI Agent和lark-cli这个组合这背后是一套针对“非结构化信息处理”场景的经典技术选型逻辑。我们需要一个能“思考”的组件来处理模糊的文档标题和潜在的归类逻辑同时需要一个“手和脚”来稳定、合规地获取数据。2.1 为什么是lark-cli首先看数据获取层。飞书开放平台提供了完善的REST API我们可以自己用Python的requests库去封装调用。但这意味着要自己处理认证App ID, App Secret、管理访问令牌、解析复杂的API响应体还要应对可能出现的速率限制和错误重试。对于一个旨在“一键完成”的工具来说这些底层细节过于繁琐且容易出错。lark-cli的出现解决了这个问题。它是飞书官方维护的命令行工具用Go语言编写本质上是对飞书Open API的一层封装。它的核心优势在于开箱即用的认证只需一次简单的lark-cli login后续所有命令都自动携带有效的访问令牌。简化的命令语法将复杂的HTTP API调用转化为直观的命令例如lark-cli drive list_file就能列出空间文件学习成本极低。稳定的输出输出格式如JSON稳定便于下游程序如我们的Python脚本解析。官方维护意味着更好的兼容性和长期支持跟随飞书API的迭代而更新。在我们的场景中lark-cli扮演了数据搬运工的角色。它的任务就是以最高效、最稳定的方式把知识库的原始节点树“搬”出来交给后面的AI Agent处理。2.2 为什么是AI Agent而不仅仅是LLM接下来是处理层。我们当然可以直接用一个大型语言模型LLM来解析lark-cli输出的JSON然后让它输出一个目录结构。但这样做的效果往往不尽如人意。原因在于知识库的整理是一个多步骤、有状态的推理过程。一个简单的LLM调用单次Prompt可能面临如下问题上下文长度限制一个大型知识库的节点列表JSON可能非常长会轻易超出模型的上下文窗口。缺乏深度分析单次Prompt难以让模型进行“迭代思考”比如先总结大类再归纳子类最后调整歧义文档的归属。任务分解困难任务“生成一个清晰的目录结构”本身是模糊的。什么是“清晰”是按业务部门分类还是按文档类型需求、设计、报告分类LLM需要引导。AI Agent架构正是为解决此类问题而生。一个典型的Agent包含几个核心部分规划器Planner将“生成目录”这个高层目标分解为“获取数据”、“解析节点”、“识别主题”、“归纳分类”、“生成格式”等一系列子任务。工具集Tools为Agent提供“动手能力”。在我们的项目里最核心的工具就是“执行lark-cli命令并获取结果”。Agent可以自主调用这个工具去获取它需要的数据。记忆Memory让Agent能记住之前分析过的节点信息、已经做出的分类决策从而保持整体结构的一致性避免前后矛盾。执行器Executor按照规划器的步骤协调工具和记忆一步步推进任务。我选择了Claude Code作为这个AI Agent的“大脑”。相比于通用的Chat模型Claude Code在代码理解和结构化输出方面表现更为出色它能更好地理解JSON数据结构并严格按照要求输出Markdown或文本格式的目录。更重要的是通过其提供的API和Session管理能力我们可以构建一个具有持久化对话状态的Agent实现多轮交互和复杂推理。注意这里有一个关键的实操心得。初期我尝试使用GPT模型配合简单的LangChain框架发现它在处理深层嵌套的JSON和维持分类标准一致性上容易“失忆”。切换到Claude Code并设计了一个“两步归纳法”的Agent工作流后后文会详述输出的结构质量有了显著提升。工具链的选型直接决定了最终效果的上限。2.3 整体架构设计基于以上分析整个项目的架构就清晰了用户输入知识库URL或Token ↓ lark-cli 工具层 ├── 认证 (login) ├── 遍历知识库节点 (drive list_file --folder_tokenxxx --recursive) └── 输出结构化JSON ↓ AI Agent 处理层 (以Claude Code为核心) ├── 接收并解析JSON数据 ├── 运行“知识库结构分析”Agent │ ├── 规划分解分析任务 │ ├── 执行调用记忆与工具进行多轮分析 │ └── 输出生成Markdown目录树 └── 格式化最终结果 ↓ 输出清晰的知识库目录结构图 (Markdown/Text/Tree格式)这个架构实现了关注点分离lark-cli负责所有与飞书API交互的脏活累活AI Agent专注于需要智能的文档分析与结构生成。两者通过标准的JSON格式进行数据交换耦合度低未来替换任何一部分比如换用其他LLM或更新lark-cli版本都相对容易。3. 环境准备与核心工具部署理论说完了我们开始动手。这一部分我会详细拆解从零开始搭建整个环境的每一步包括你可能遇到的坑和解决方案。3.1 飞书应用创建与权限配置一切始于飞书开放平台。没有合法的应用身份lark-cli无法访问你的知识库数据。登录与创建访问飞书开放平台创建一个新的“企业自建应用”。给应用起个名字比如“知识库结构分析助手”。获取凭证在应用的“凭证与基础信息”页面你会找到App ID和App Secret。这两个字符串相当于你的应用账号密码务必妥善保管后续lark-cli登录和直接调用API都会用到。配置权限这是最关键也是最容易出错的一步。在“权限管理”页面你需要为应用添加以下权限drive:drive云空间读取权限。这是访问知识库本质上是云文档空间的基石。drive:file:readonly文件只读权限。我们只需要读取文档信息和目录结构不需要修改所以只读权限最安全。drive:file:list_in_folder列出文件夹内文件权限。用于递归遍历目录。重要提示添加权限后必须点击“申请线上发布”或“版本管理与发布”提交审核企业自建应用通常管理员审批即可。仅仅保存权限设置应用是没有实际权限的很多人在这一步卡住发现调用API总是返回无权限错误原因就是忘了发布。启用机器人可选但推荐在“事件订阅”或“机器人”页面启用机器人能力。这样你可以获得一个webhook地址用于接收事件虽然本项目用不到但启用后应用会更完整。3.2 lark-cli的安装与认证lark-cli支持macOS、Linux和Windows。安装macOS最方便的是使用Homebrewbrew install lark-cli。Linux/Windows可以从飞书开放平台的GitHub Release页面下载对应系统的二进制包解压后放入系统PATH路径。认证 安装成功后在终端执行lark-cli login。它会提示你选择登录方式。对于企业自建应用我们选择“自建应用”。接着它会依次交互式地询问你的App ID、App Secret和“事件订阅验证令牌”。如果你没有启用机器人事件订阅令牌可以随意填写一个非空字符串如dummy_token但App ID和Secret必须准确。认证成功后凭证会默认保存在~/.lark/config文件中。后续所有命令都会自动使用这个凭证。验证安装 运行lark-cli drive list_file --folder_token00代表根目录。如果返回了你个人空间的文件列表或一个空列表而没有报权限错误说明lark-cli安装和认证成功。3.3 AI Agent环境搭建以Claude Code为例Claude Code是Anthropic公司推出的专注于代码任务的Claude模型版本可以通过其API进行调用。我们使用Python环境来构建Agent逻辑。Python环境建议使用Python 3.9。创建一个虚拟环境是良好的习惯python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows安装依赖库pip install anthropic # Claude官方SDK pip install requests # 用于可能的额外HTTP请求 pip install python-dotenv # 管理环境变量核心就是anthropic库它提供了与Claude API交互的最直接方式。获取Claude API Key前往Anthropic控制台创建一个API Key。这个Key是调用Claude模型的凭证需要付费但有免费的起步额度供试用。配置环境变量将API Key存储在环境变量中避免硬编码在代码里更安全。# 在项目根目录创建 .env 文件 echo ANTHROPIC_API_KEY你的sk-xxx密钥 .env在Python代码中使用python-dotenv来加载from dotenv import load_dotenv import os load_dotenv() api_key os.getenv(ANTHROPIC_API_KEY)至此飞书侧和AI侧的基础环境已经准备就绪。接下来我们将进入最核心的部分如何让lark-cli和AI Agent协同工作。4. 核心实现数据获取与智能分析的协同这一章我们将深入代码层面看如何将lark-cli的数据获取能力“嫁接”给AI Agent并设计一个有效的Agent工作流来生成高质量的目录结构。4.1 利用lark-cli递归获取知识库树知识库在飞书底层是通过folder_token和file_token来组织的。我们的首要任务是拿到整个知识库的完整节点列表。步骤一找到知识库的“根Token”每个飞书知识库都有一个唯一的标识。最简单的方法是在飞书客户端打开知识库从浏览器地址栏找到URL中的wiki或space后面的那串字符。更通用的方法是通过lark-cli列出你有权限的顶级空间lark-cli drive list_file --folder_token0 --typewiki在返回的JSON列表中找到对应知识库的条目其中的token字段就是我们的入口点假设为wikcnXxxxxxx。步骤二编写递归获取函数我们不能指望单次API调用就拿到所有嵌套文件。需要编写一个递归函数从根目录开始一层层地探索。import json import subprocess import time def get_space_tree(folder_token, indent0): 递归获取以 folder_token 为根的空间树结构。 返回一个包含‘type’(file/folder), ‘name’, ‘token’, ‘children’的字典列表。 # 使用lark-cli命令列出当前文件夹下的所有项 cmd [lark-cli, drive, list_file, --folder_token, folder_token, --page_size, 200] # 每页最大数量 try: result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) data json.loads(result.stdout) except subprocess.CalledProcessError as e: print(fError listing folder {folder_token}: {e.stderr}) return [] except json.JSONDecodeError: print(fFailed to parse JSON for {folder_token}) return [] items [] # 假设返回的数据在 data[data][files] 或类似路径下需根据实际输出调整 # 这里需要你根据 lark-cli 的实际输出格式进行解析 file_list data.get(data, {}).get(files, []) for item in file_list: node { name: item.get(name, Unnamed), token: item.get(token), type: item.get(type, unknown), # file 或 folder children: [] } # 如果是文件夹递归获取其子项 if node[type] folder and node[token]: # 添加一个延迟避免请求过快 time.sleep(0.1) node[children] get_space_tree(node[token], indent2) items.append(node) return items实操心得lark-cli drive list_file的输出格式需要仔细查看。飞书API可能会分页上述简单示例没有处理分页逻辑。在实际工具中必须添加循环处理has_more和page_token字段确保获取所有节点。这是第一个容易踩的坑。步骤三保存与简化数据递归获取的JSON树可能非常庞大且包含许多我们不需要的字段如创建时间、所有者等。在交给AI处理前最好做一次清洗和简化只保留name,type,token和嵌套的children这样可以显著减少Token消耗提高AI处理效率。def simplify_tree(node): 简化节点只保留核心信息 simplified {name: node[name], type: node[type]} if node[children]: simplified[children] [simplify_tree(child) for child in node[children]] return simplified最终我们得到一个精简的、纯结构的JSON数据它描述了知识库的“骨架”但不包含文档具体内容。4.2 构建AI Agent工作流现在我们有了数据骨架需要AI Agent为它“注入灵魂”即理解这些文件名背后的含义并归纳出逻辑结构。一个强大的Agent不是一次Prompt就能完成的我设计了一个两阶段工作流。阶段一结构分析与主题识别这个阶段Agent的任务是“阅读”整个简化后的JSON树理解现有的文件夹结构并识别出主要的主题或分类维度。 我们给Claude Code设计一个System Prompt和第一次任务请求import anthropic client anthropic.Anthropic(api_keyapi_key) system_prompt 你是一个资深的知识管理专家擅长分析文档结构并提炼逻辑脉络。你将收到一个飞书知识库的目录树JSON数据。你的任务是 1. 通览整个目录结构理解现有的一级、二级文件夹的命名和分组方式。 2. 识别出当前知识库隐含的几种主要分类维度例如按业务部门、按项目阶段、按文档类型、按功能模块等。 3. 分析现有结构是否存在混乱、命名不规范或归类不合理的地方。 请用清晰、有条理的语言输出你的分析报告。然后将简化后的JSON树作为用户消息发送。Claude Code会返回一份分析报告指出当前结构的优点和问题并建议几个可行的重组维度。阶段二基于建议生成优化后的目录树收到分析报告后我们启动第二阶段。这次我们要求Agent扮演一个“重构执行者”。second_system_prompt 基于上一轮的分析报告和原始数据你现在需要生成一个全新的、更清晰合理的知识库目录结构。 要求 1. 从你上一轮建议的维度中选择最合适的一个作为主分类逻辑。 2. 保留所有原始文档节点但可以对它们进行重新归类。 3. 如果遇到含义模糊的文件可以根据其文件名进行合理推断或将其放入“待分类”区域。 4. 输出格式为纯文本的树状结构使用缩进和特定符号如├──, └──表示层级。在节点后可用括号简要说明其原路径或你的推断理由。 请直接输出最终的目录树不要附加解释。我们将第一轮的分析报告和原始数据再次提供给Agent。这次它会输出一个重构后的、带智能注释的目录树。核心技巧在两轮交互之间将第一轮的输出分析报告作为第二轮的系统提示或上下文的一部分是构建有效Agent工作流的关键。这模拟了人类“先分析再决策”的思考过程让AI的产出质量远超单次Prompt。4.3 结果输出与格式化AI Agent生成的文本目录树已经很有用但我们还可以做得更好。我通常会将结果输出为三种格式以满足不同场景纯文本树直接用于快速预览或在终端查看。Markdown文档生成一个完整的Markdown文件标题层级清晰可以直接导入到新的知识库页面或分享。def convert_tree_to_markdown(tree_lines, output_pathknowledge_structure.md): with open(output_path, w, encodingutf-8) as f: f.write(# 知识库目录结构分析报告\n\n) f.write(## 优化后结构\n\n) for line in tree_lines: # 将缩进符号转换为Markdown的标题层级或列表 # 例如根据缩进深度决定是二级标题(##)还是列表项(-) f.write(line \n)可视化图表进阶使用graphviz或mermaid的文本语法生成可以渲染成结构图的代码。虽然博文禁止使用Mermaid图表但在你自己的工具中可以生成Mermaid代码块用户复制到支持Mermaid的Markdown编辑器如Typora、Obsidian中即可看到可视化图形。最终用户运行一条命令就能在本地得到一份knowledge_structure.md文件打开后一个清晰、智能、带注释的知识地图跃然纸上。5. 开源工具封装与使用指南为了让这个能力更方便地被大家使用我将上述所有逻辑封装成了一个开源命令行工具暂命名为lark-wiki-mapper。5.1 工具设计与核心参数这个工具的设计哲学是“简单至上”。它只有两个核心命令auth: 用于配置飞书应用凭证内部调用lark-cli login。map: 核心命令生成知识库结构图。安装与配置# 从GitHub克隆项目 git clone https://github.com/your-username/lark-wiki-mapper.git cd lark-wiki-mapper pip install -r requirements.txt # 配置凭证首次使用 python mapper.py auth --app_id YOUR_APP_ID --app_secret YOUR_APP_SECRET核心使用# 生成知识库结构图 python mapper.py map --wiki_token wikcnXxxxxxx --output_format markdown --output_file ./my_wiki_map.md参数详解--wiki_token: 目标知识库的Token。如果不知道工具也提供了--wiki_url参数可以从浏览器地址栏的URL中自动提取。--output_format: 输出格式可选text,markdown,mermaid。--output_file: 输出文件路径。--claude_model: 指定使用的Claude模型如claude-3-5-sonnet-20241022默认为最新版Sonnet。--max_tokens: 限制AI分析时的Token数量防止处理超大知识库时成本过高。5.2 高级功能与自定义提示词对于有进阶需求的用户工具提供了更多灵活性自定义Agent提示词在项目根目录下创建prompts/文件夹你可以放置自定义的analysis_prompt.txt和generation_prompt.txt。工具会优先使用你的提示词从而让Agent按照你特定的业务逻辑比如必须遵循公司内部的文档分类规范进行思考。增量分析与对比通过--cache参数工具可以保存上一次获取的原始JSON数据。下次运行时如果知识库Token未变它会直接使用缓存数据跳过耗时的lark-cli递归过程快速进行AI分析适合频繁迭代。结构对比报告结合Git你可以将不同时间点生成的结构图进行差异对比直观地看到知识库的演进情况哪些区域文档增长最快哪些区域长期空白。5.3 安全与成本考量数据安全所有操作都在本地完成。你的飞书文档内容不会被上传到除飞书服务器和AnthropicClaudeAPI以外的任何第三方。lark-cli只获取文件列表元数据不获取文档正文内容。AI Agent处理的仅仅是文件名和目录结构信息。API成本使用Claude API会产生费用。处理一个拥有500个节点的知识库大约需要消耗10K-30K的输入Token和2K-5K的输出Token成本在几美分到几十美分之间。工具内置了--dry-run参数可以预估本次操作可能消耗的Token数量帮助你控制成本。6. 常见问题与排查实录在实际开发和使用的过程中我遇到了不少坑。这里把典型问题和解决方案记录下来希望能帮你节省时间。6.1 lark-cli相关错误问题1执行lark-cli login成功但运行命令时报authentication failed或no permission。原因最常见的原因是应用的权限没有“发布”。在飞书开放平台后台权限配置完成后必须点击“申请发布”或“版本管理”进行提交并由管理员审核通过企业自建应用通常是自助审批。解决登录飞书开放平台进入你的应用确保所需权限drive:drive等的状态是“已获得”或“已生效”而不是“未申请”。问题2lark-cli drive list_file返回空列表或找不到知识库。原因--folder_token参数可能不对。0代表个人空间根目录而知识库通常位于“团队空间”或“知识库”这个特殊的容器下。解决先用lark-cli drive list_file --folder_token0 --typewiki列出所有知识库空间找到正确的token。或者直接使用知识库的URL我的开源工具内置了从URL提取Token的逻辑。问题3递归获取时速度慢或中途报错退出。原因可能是触发了飞书API的速率限制或者网络不稳定。解决增加延迟在递归函数的循环中每次请求后添加time.sleep(0.2)或更长的时间。处理分页确保你的代码正确处理了API响应的has_more和page_token字段遍历所有页面。异常捕获与重试用try...except包裹API调用并在遇到网络错误或5xx服务器错误时进行有限次数的重试。6.2 AI Agent分析效果不佳问题1生成的目录结构混乱分类不符合预期。原因提示词Prompt不够精确。AI不理解你所在团队的特定业务语境。解决使用工具的自定义提示词功能。在generation_prompt.txt中明确给出分类规则。例如“请严格按照‘产品-设计-开发-测试-运营’这个五阶段模型对文档进行分类。如果文件名包含‘PRD’、‘需求’则归入‘产品’包含‘UI’、‘原型’则归入‘设计’以此类推。”问题2处理大型知识库时AI返回错误或中断。原因输入给AI的JSON数据太大超出了模型上下文窗口Claude 3.5 Sonnet的上下文窗口很大但也不是无限的。解决数据简化确保在传给AI前已经用simplify_tree函数去除了所有非必要字段。分块处理对于超大型知识库可以按一级文件夹分块进行分析最后再让AI汇总。这需要更复杂的Agent流程设计。使用--max_tokens参数限制输入长度优先保证核心部分的处理。问题3AI对某些模糊文件名的推断完全错误。原因AI仅基于文件名猜测缺乏上下文。解决这是当前方法的局限性。在工具的输出中我会让AI将这些“低置信度”的文件归类到“待分类-模糊文档”节点下并附上原路径提醒人工复核。未来可以探索结合文档摘要需要更高权限来辅助判断但复杂度会大大增加。6.3 环境与依赖问题问题工具在Windows系统上运行异常特别是子进程调用lark-cli时。原因路径或环境变量问题。Windows下命令行环境与Unix系有差异。解决确保lark-cli的安装路径已添加到系统的PATH环境变量中。在Python代码中调用subprocess.run时可以尝试添加shellTrue参数但需注意安全风险。检查Python脚本的编码确保为UTF-8以正确处理中文文件名。这个项目从构思到实现最大的体会是将复杂的智能任务分解为“确定性的数据管道”和“非确定性的AI推理”两部分并用胶水代码将它们牢固地粘合起来是构建实用AI应用的有效范式。lark-cli提供了稳定可靠的数据管道Claude Code提供了强大的推理能力而我们的代码则定义了它们如何协作的规则。最终得到的不仅仅是一个工具更是一个可复用的模式你可以轻松地将这个模式应用到其他需要“自动化智能化”梳理信息的场景中去。 AI Agent与lark-cli自动化梳理飞书知识库目录结构实践
1. 项目概述当AI Agent遇见飞书知识库最近在整理团队沉淀在飞书知识库里的文档看着那几百个节点、嵌套了七八层的目录树我头都大了。手动梳理光是想想就让人望而却步。这几乎是每个使用飞书进行知识管理的团队都会遇到的痛点文档越积越多结构越来越乱新成员入职想快速了解知识体系老员工想找个历史文档都得在迷宫般的目录里“捉迷藏”。就在我琢磨着是不是要写个脚本硬啃飞书API的时候一个组合方案进入了我的视野AI Agent lark-cli。简单来说就是让一个具备逻辑推理能力的AI智能体通过飞书官方的命令行工具自动去读取、分析并生成一份清晰的知识库目录结构图。这个想法让我眼前一亮因为它完美地结合了“自动化”与“智能化”。AI Agent负责理解复杂的文档层级关系和内容lark-cli则提供了稳定、官方的数据通道。经过一番折腾我不仅跑通了整个流程还把核心逻辑封装成了一个开箱即用的开源工具。这个项目解决的远不止是“生成一个目录”这么简单。它本质上是在解决知识资产的可视化与结构化难题。对于团队负责人它能一键生成知识全景图快速评估知识体系的完整性与合理性对于新人它是一份极佳的“寻宝地图”对于知识管理者它是定期进行知识库“体检”的自动化工具。整个过程你只需要一个飞书应用的权限和一句命令。2. 核心工具链选型与设计思路为什么是AI Agent和lark-cli这个组合这背后是一套针对“非结构化信息处理”场景的经典技术选型逻辑。我们需要一个能“思考”的组件来处理模糊的文档标题和潜在的归类逻辑同时需要一个“手和脚”来稳定、合规地获取数据。2.1 为什么是lark-cli首先看数据获取层。飞书开放平台提供了完善的REST API我们可以自己用Python的requests库去封装调用。但这意味着要自己处理认证App ID, App Secret、管理访问令牌、解析复杂的API响应体还要应对可能出现的速率限制和错误重试。对于一个旨在“一键完成”的工具来说这些底层细节过于繁琐且容易出错。lark-cli的出现解决了这个问题。它是飞书官方维护的命令行工具用Go语言编写本质上是对飞书Open API的一层封装。它的核心优势在于开箱即用的认证只需一次简单的lark-cli login后续所有命令都自动携带有效的访问令牌。简化的命令语法将复杂的HTTP API调用转化为直观的命令例如lark-cli drive list_file就能列出空间文件学习成本极低。稳定的输出输出格式如JSON稳定便于下游程序如我们的Python脚本解析。官方维护意味着更好的兼容性和长期支持跟随飞书API的迭代而更新。在我们的场景中lark-cli扮演了数据搬运工的角色。它的任务就是以最高效、最稳定的方式把知识库的原始节点树“搬”出来交给后面的AI Agent处理。2.2 为什么是AI Agent而不仅仅是LLM接下来是处理层。我们当然可以直接用一个大型语言模型LLM来解析lark-cli输出的JSON然后让它输出一个目录结构。但这样做的效果往往不尽如人意。原因在于知识库的整理是一个多步骤、有状态的推理过程。一个简单的LLM调用单次Prompt可能面临如下问题上下文长度限制一个大型知识库的节点列表JSON可能非常长会轻易超出模型的上下文窗口。缺乏深度分析单次Prompt难以让模型进行“迭代思考”比如先总结大类再归纳子类最后调整歧义文档的归属。任务分解困难任务“生成一个清晰的目录结构”本身是模糊的。什么是“清晰”是按业务部门分类还是按文档类型需求、设计、报告分类LLM需要引导。AI Agent架构正是为解决此类问题而生。一个典型的Agent包含几个核心部分规划器Planner将“生成目录”这个高层目标分解为“获取数据”、“解析节点”、“识别主题”、“归纳分类”、“生成格式”等一系列子任务。工具集Tools为Agent提供“动手能力”。在我们的项目里最核心的工具就是“执行lark-cli命令并获取结果”。Agent可以自主调用这个工具去获取它需要的数据。记忆Memory让Agent能记住之前分析过的节点信息、已经做出的分类决策从而保持整体结构的一致性避免前后矛盾。执行器Executor按照规划器的步骤协调工具和记忆一步步推进任务。我选择了Claude Code作为这个AI Agent的“大脑”。相比于通用的Chat模型Claude Code在代码理解和结构化输出方面表现更为出色它能更好地理解JSON数据结构并严格按照要求输出Markdown或文本格式的目录。更重要的是通过其提供的API和Session管理能力我们可以构建一个具有持久化对话状态的Agent实现多轮交互和复杂推理。注意这里有一个关键的实操心得。初期我尝试使用GPT模型配合简单的LangChain框架发现它在处理深层嵌套的JSON和维持分类标准一致性上容易“失忆”。切换到Claude Code并设计了一个“两步归纳法”的Agent工作流后后文会详述输出的结构质量有了显著提升。工具链的选型直接决定了最终效果的上限。2.3 整体架构设计基于以上分析整个项目的架构就清晰了用户输入知识库URL或Token ↓ lark-cli 工具层 ├── 认证 (login) ├── 遍历知识库节点 (drive list_file --folder_tokenxxx --recursive) └── 输出结构化JSON ↓ AI Agent 处理层 (以Claude Code为核心) ├── 接收并解析JSON数据 ├── 运行“知识库结构分析”Agent │ ├── 规划分解分析任务 │ ├── 执行调用记忆与工具进行多轮分析 │ └── 输出生成Markdown目录树 └── 格式化最终结果 ↓ 输出清晰的知识库目录结构图 (Markdown/Text/Tree格式)这个架构实现了关注点分离lark-cli负责所有与飞书API交互的脏活累活AI Agent专注于需要智能的文档分析与结构生成。两者通过标准的JSON格式进行数据交换耦合度低未来替换任何一部分比如换用其他LLM或更新lark-cli版本都相对容易。3. 环境准备与核心工具部署理论说完了我们开始动手。这一部分我会详细拆解从零开始搭建整个环境的每一步包括你可能遇到的坑和解决方案。3.1 飞书应用创建与权限配置一切始于飞书开放平台。没有合法的应用身份lark-cli无法访问你的知识库数据。登录与创建访问飞书开放平台创建一个新的“企业自建应用”。给应用起个名字比如“知识库结构分析助手”。获取凭证在应用的“凭证与基础信息”页面你会找到App ID和App Secret。这两个字符串相当于你的应用账号密码务必妥善保管后续lark-cli登录和直接调用API都会用到。配置权限这是最关键也是最容易出错的一步。在“权限管理”页面你需要为应用添加以下权限drive:drive云空间读取权限。这是访问知识库本质上是云文档空间的基石。drive:file:readonly文件只读权限。我们只需要读取文档信息和目录结构不需要修改所以只读权限最安全。drive:file:list_in_folder列出文件夹内文件权限。用于递归遍历目录。重要提示添加权限后必须点击“申请线上发布”或“版本管理与发布”提交审核企业自建应用通常管理员审批即可。仅仅保存权限设置应用是没有实际权限的很多人在这一步卡住发现调用API总是返回无权限错误原因就是忘了发布。启用机器人可选但推荐在“事件订阅”或“机器人”页面启用机器人能力。这样你可以获得一个webhook地址用于接收事件虽然本项目用不到但启用后应用会更完整。3.2 lark-cli的安装与认证lark-cli支持macOS、Linux和Windows。安装macOS最方便的是使用Homebrewbrew install lark-cli。Linux/Windows可以从飞书开放平台的GitHub Release页面下载对应系统的二进制包解压后放入系统PATH路径。认证 安装成功后在终端执行lark-cli login。它会提示你选择登录方式。对于企业自建应用我们选择“自建应用”。接着它会依次交互式地询问你的App ID、App Secret和“事件订阅验证令牌”。如果你没有启用机器人事件订阅令牌可以随意填写一个非空字符串如dummy_token但App ID和Secret必须准确。认证成功后凭证会默认保存在~/.lark/config文件中。后续所有命令都会自动使用这个凭证。验证安装 运行lark-cli drive list_file --folder_token00代表根目录。如果返回了你个人空间的文件列表或一个空列表而没有报权限错误说明lark-cli安装和认证成功。3.3 AI Agent环境搭建以Claude Code为例Claude Code是Anthropic公司推出的专注于代码任务的Claude模型版本可以通过其API进行调用。我们使用Python环境来构建Agent逻辑。Python环境建议使用Python 3.9。创建一个虚拟环境是良好的习惯python -m venv venv source venv/bin/activate # Linux/macOS # venv\Scripts\activate # Windows安装依赖库pip install anthropic # Claude官方SDK pip install requests # 用于可能的额外HTTP请求 pip install python-dotenv # 管理环境变量核心就是anthropic库它提供了与Claude API交互的最直接方式。获取Claude API Key前往Anthropic控制台创建一个API Key。这个Key是调用Claude模型的凭证需要付费但有免费的起步额度供试用。配置环境变量将API Key存储在环境变量中避免硬编码在代码里更安全。# 在项目根目录创建 .env 文件 echo ANTHROPIC_API_KEY你的sk-xxx密钥 .env在Python代码中使用python-dotenv来加载from dotenv import load_dotenv import os load_dotenv() api_key os.getenv(ANTHROPIC_API_KEY)至此飞书侧和AI侧的基础环境已经准备就绪。接下来我们将进入最核心的部分如何让lark-cli和AI Agent协同工作。4. 核心实现数据获取与智能分析的协同这一章我们将深入代码层面看如何将lark-cli的数据获取能力“嫁接”给AI Agent并设计一个有效的Agent工作流来生成高质量的目录结构。4.1 利用lark-cli递归获取知识库树知识库在飞书底层是通过folder_token和file_token来组织的。我们的首要任务是拿到整个知识库的完整节点列表。步骤一找到知识库的“根Token”每个飞书知识库都有一个唯一的标识。最简单的方法是在飞书客户端打开知识库从浏览器地址栏找到URL中的wiki或space后面的那串字符。更通用的方法是通过lark-cli列出你有权限的顶级空间lark-cli drive list_file --folder_token0 --typewiki在返回的JSON列表中找到对应知识库的条目其中的token字段就是我们的入口点假设为wikcnXxxxxxx。步骤二编写递归获取函数我们不能指望单次API调用就拿到所有嵌套文件。需要编写一个递归函数从根目录开始一层层地探索。import json import subprocess import time def get_space_tree(folder_token, indent0): 递归获取以 folder_token 为根的空间树结构。 返回一个包含‘type’(file/folder), ‘name’, ‘token’, ‘children’的字典列表。 # 使用lark-cli命令列出当前文件夹下的所有项 cmd [lark-cli, drive, list_file, --folder_token, folder_token, --page_size, 200] # 每页最大数量 try: result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) data json.loads(result.stdout) except subprocess.CalledProcessError as e: print(fError listing folder {folder_token}: {e.stderr}) return [] except json.JSONDecodeError: print(fFailed to parse JSON for {folder_token}) return [] items [] # 假设返回的数据在 data[data][files] 或类似路径下需根据实际输出调整 # 这里需要你根据 lark-cli 的实际输出格式进行解析 file_list data.get(data, {}).get(files, []) for item in file_list: node { name: item.get(name, Unnamed), token: item.get(token), type: item.get(type, unknown), # file 或 folder children: [] } # 如果是文件夹递归获取其子项 if node[type] folder and node[token]: # 添加一个延迟避免请求过快 time.sleep(0.1) node[children] get_space_tree(node[token], indent2) items.append(node) return items实操心得lark-cli drive list_file的输出格式需要仔细查看。飞书API可能会分页上述简单示例没有处理分页逻辑。在实际工具中必须添加循环处理has_more和page_token字段确保获取所有节点。这是第一个容易踩的坑。步骤三保存与简化数据递归获取的JSON树可能非常庞大且包含许多我们不需要的字段如创建时间、所有者等。在交给AI处理前最好做一次清洗和简化只保留name,type,token和嵌套的children这样可以显著减少Token消耗提高AI处理效率。def simplify_tree(node): 简化节点只保留核心信息 simplified {name: node[name], type: node[type]} if node[children]: simplified[children] [simplify_tree(child) for child in node[children]] return simplified最终我们得到一个精简的、纯结构的JSON数据它描述了知识库的“骨架”但不包含文档具体内容。4.2 构建AI Agent工作流现在我们有了数据骨架需要AI Agent为它“注入灵魂”即理解这些文件名背后的含义并归纳出逻辑结构。一个强大的Agent不是一次Prompt就能完成的我设计了一个两阶段工作流。阶段一结构分析与主题识别这个阶段Agent的任务是“阅读”整个简化后的JSON树理解现有的文件夹结构并识别出主要的主题或分类维度。 我们给Claude Code设计一个System Prompt和第一次任务请求import anthropic client anthropic.Anthropic(api_keyapi_key) system_prompt 你是一个资深的知识管理专家擅长分析文档结构并提炼逻辑脉络。你将收到一个飞书知识库的目录树JSON数据。你的任务是 1. 通览整个目录结构理解现有的一级、二级文件夹的命名和分组方式。 2. 识别出当前知识库隐含的几种主要分类维度例如按业务部门、按项目阶段、按文档类型、按功能模块等。 3. 分析现有结构是否存在混乱、命名不规范或归类不合理的地方。 请用清晰、有条理的语言输出你的分析报告。然后将简化后的JSON树作为用户消息发送。Claude Code会返回一份分析报告指出当前结构的优点和问题并建议几个可行的重组维度。阶段二基于建议生成优化后的目录树收到分析报告后我们启动第二阶段。这次我们要求Agent扮演一个“重构执行者”。second_system_prompt 基于上一轮的分析报告和原始数据你现在需要生成一个全新的、更清晰合理的知识库目录结构。 要求 1. 从你上一轮建议的维度中选择最合适的一个作为主分类逻辑。 2. 保留所有原始文档节点但可以对它们进行重新归类。 3. 如果遇到含义模糊的文件可以根据其文件名进行合理推断或将其放入“待分类”区域。 4. 输出格式为纯文本的树状结构使用缩进和特定符号如├──, └──表示层级。在节点后可用括号简要说明其原路径或你的推断理由。 请直接输出最终的目录树不要附加解释。我们将第一轮的分析报告和原始数据再次提供给Agent。这次它会输出一个重构后的、带智能注释的目录树。核心技巧在两轮交互之间将第一轮的输出分析报告作为第二轮的系统提示或上下文的一部分是构建有效Agent工作流的关键。这模拟了人类“先分析再决策”的思考过程让AI的产出质量远超单次Prompt。4.3 结果输出与格式化AI Agent生成的文本目录树已经很有用但我们还可以做得更好。我通常会将结果输出为三种格式以满足不同场景纯文本树直接用于快速预览或在终端查看。Markdown文档生成一个完整的Markdown文件标题层级清晰可以直接导入到新的知识库页面或分享。def convert_tree_to_markdown(tree_lines, output_pathknowledge_structure.md): with open(output_path, w, encodingutf-8) as f: f.write(# 知识库目录结构分析报告\n\n) f.write(## 优化后结构\n\n) for line in tree_lines: # 将缩进符号转换为Markdown的标题层级或列表 # 例如根据缩进深度决定是二级标题(##)还是列表项(-) f.write(line \n)可视化图表进阶使用graphviz或mermaid的文本语法生成可以渲染成结构图的代码。虽然博文禁止使用Mermaid图表但在你自己的工具中可以生成Mermaid代码块用户复制到支持Mermaid的Markdown编辑器如Typora、Obsidian中即可看到可视化图形。最终用户运行一条命令就能在本地得到一份knowledge_structure.md文件打开后一个清晰、智能、带注释的知识地图跃然纸上。5. 开源工具封装与使用指南为了让这个能力更方便地被大家使用我将上述所有逻辑封装成了一个开源命令行工具暂命名为lark-wiki-mapper。5.1 工具设计与核心参数这个工具的设计哲学是“简单至上”。它只有两个核心命令auth: 用于配置飞书应用凭证内部调用lark-cli login。map: 核心命令生成知识库结构图。安装与配置# 从GitHub克隆项目 git clone https://github.com/your-username/lark-wiki-mapper.git cd lark-wiki-mapper pip install -r requirements.txt # 配置凭证首次使用 python mapper.py auth --app_id YOUR_APP_ID --app_secret YOUR_APP_SECRET核心使用# 生成知识库结构图 python mapper.py map --wiki_token wikcnXxxxxxx --output_format markdown --output_file ./my_wiki_map.md参数详解--wiki_token: 目标知识库的Token。如果不知道工具也提供了--wiki_url参数可以从浏览器地址栏的URL中自动提取。--output_format: 输出格式可选text,markdown,mermaid。--output_file: 输出文件路径。--claude_model: 指定使用的Claude模型如claude-3-5-sonnet-20241022默认为最新版Sonnet。--max_tokens: 限制AI分析时的Token数量防止处理超大知识库时成本过高。5.2 高级功能与自定义提示词对于有进阶需求的用户工具提供了更多灵活性自定义Agent提示词在项目根目录下创建prompts/文件夹你可以放置自定义的analysis_prompt.txt和generation_prompt.txt。工具会优先使用你的提示词从而让Agent按照你特定的业务逻辑比如必须遵循公司内部的文档分类规范进行思考。增量分析与对比通过--cache参数工具可以保存上一次获取的原始JSON数据。下次运行时如果知识库Token未变它会直接使用缓存数据跳过耗时的lark-cli递归过程快速进行AI分析适合频繁迭代。结构对比报告结合Git你可以将不同时间点生成的结构图进行差异对比直观地看到知识库的演进情况哪些区域文档增长最快哪些区域长期空白。5.3 安全与成本考量数据安全所有操作都在本地完成。你的飞书文档内容不会被上传到除飞书服务器和AnthropicClaudeAPI以外的任何第三方。lark-cli只获取文件列表元数据不获取文档正文内容。AI Agent处理的仅仅是文件名和目录结构信息。API成本使用Claude API会产生费用。处理一个拥有500个节点的知识库大约需要消耗10K-30K的输入Token和2K-5K的输出Token成本在几美分到几十美分之间。工具内置了--dry-run参数可以预估本次操作可能消耗的Token数量帮助你控制成本。6. 常见问题与排查实录在实际开发和使用的过程中我遇到了不少坑。这里把典型问题和解决方案记录下来希望能帮你节省时间。6.1 lark-cli相关错误问题1执行lark-cli login成功但运行命令时报authentication failed或no permission。原因最常见的原因是应用的权限没有“发布”。在飞书开放平台后台权限配置完成后必须点击“申请发布”或“版本管理”进行提交并由管理员审核通过企业自建应用通常是自助审批。解决登录飞书开放平台进入你的应用确保所需权限drive:drive等的状态是“已获得”或“已生效”而不是“未申请”。问题2lark-cli drive list_file返回空列表或找不到知识库。原因--folder_token参数可能不对。0代表个人空间根目录而知识库通常位于“团队空间”或“知识库”这个特殊的容器下。解决先用lark-cli drive list_file --folder_token0 --typewiki列出所有知识库空间找到正确的token。或者直接使用知识库的URL我的开源工具内置了从URL提取Token的逻辑。问题3递归获取时速度慢或中途报错退出。原因可能是触发了飞书API的速率限制或者网络不稳定。解决增加延迟在递归函数的循环中每次请求后添加time.sleep(0.2)或更长的时间。处理分页确保你的代码正确处理了API响应的has_more和page_token字段遍历所有页面。异常捕获与重试用try...except包裹API调用并在遇到网络错误或5xx服务器错误时进行有限次数的重试。6.2 AI Agent分析效果不佳问题1生成的目录结构混乱分类不符合预期。原因提示词Prompt不够精确。AI不理解你所在团队的特定业务语境。解决使用工具的自定义提示词功能。在generation_prompt.txt中明确给出分类规则。例如“请严格按照‘产品-设计-开发-测试-运营’这个五阶段模型对文档进行分类。如果文件名包含‘PRD’、‘需求’则归入‘产品’包含‘UI’、‘原型’则归入‘设计’以此类推。”问题2处理大型知识库时AI返回错误或中断。原因输入给AI的JSON数据太大超出了模型上下文窗口Claude 3.5 Sonnet的上下文窗口很大但也不是无限的。解决数据简化确保在传给AI前已经用simplify_tree函数去除了所有非必要字段。分块处理对于超大型知识库可以按一级文件夹分块进行分析最后再让AI汇总。这需要更复杂的Agent流程设计。使用--max_tokens参数限制输入长度优先保证核心部分的处理。问题3AI对某些模糊文件名的推断完全错误。原因AI仅基于文件名猜测缺乏上下文。解决这是当前方法的局限性。在工具的输出中我会让AI将这些“低置信度”的文件归类到“待分类-模糊文档”节点下并附上原路径提醒人工复核。未来可以探索结合文档摘要需要更高权限来辅助判断但复杂度会大大增加。6.3 环境与依赖问题问题工具在Windows系统上运行异常特别是子进程调用lark-cli时。原因路径或环境变量问题。Windows下命令行环境与Unix系有差异。解决确保lark-cli的安装路径已添加到系统的PATH环境变量中。在Python代码中调用subprocess.run时可以尝试添加shellTrue参数但需注意安全风险。检查Python脚本的编码确保为UTF-8以正确处理中文文件名。这个项目从构思到实现最大的体会是将复杂的智能任务分解为“确定性的数据管道”和“非确定性的AI推理”两部分并用胶水代码将它们牢固地粘合起来是构建实用AI应用的有效范式。lark-cli提供了稳定可靠的数据管道Claude Code提供了强大的推理能力而我们的代码则定义了它们如何协作的规则。最终得到的不仅仅是一个工具更是一个可复用的模式你可以轻松地将这个模式应用到其他需要“自动化智能化”梳理信息的场景中去。