从需求拆解到上线：多AI协作Agent工作流自建Linkly AI链接工具

从需求拆解到上线：用多AI协作Agent工作流自建了一个"Linkly AI"链接工具

前阵子一直泡在各种AI Agent工作流里，突然冒出个念头：与其天天用别人的SaaS链接工具，不如自己拿AI全流程搭一个"Linkly AI"出来——一个能AI生成品牌链接、自动分组归类、还带基础访问分析的轻量级自托管服务。整个过程不写一行Prompt之外的代码，全靠AI Agent协作完成需求拆解、系统设计、代码生成、测试修补。这篇文章把从零到一的完整路径记录下来，包括Agent之间怎么分工、每一步让哪个模型负责什么、踩过的坑和最后的质量控制手段，希望对也在折腾AI编程和多模型协作的朋友有点参考价值。

1. "Linkly AI"到底是个什么：产品定位与核心需求拆解

先说清楚Linkly AI这个项目要解决的问题。市面上的链接缩短工具其实不少，但普遍有两个痛点：第一，绝大部分是纯工具型产品，生成出来的短链又丑又没辨识度，用户根本不知道点开链接会跳到哪；第二，管理后台基本就是把URL塞进数据库，没有任何智能整理能力。Linkly AI想做的，就是把"链接管理"这件事从机械操作变成"AI帮你规划、生成、归类"，并让链接本身可读、可信、可管理。

• 核心需求一：AI生成语义化别名。给它一个原始长链接，它自动读取页面标题和内容摘要，生成一个人类能直接读懂的自定义别名，比如linkly.ai/deep-dive-llm-cost，而不是linkly.ai/x7k2q。
• 核心需求二：自动分类打标签。根据目标网页的内容特征自动识别所属类别，比如技术、电商、教育、娱乐，并分配标签。
• 核心需求三：智能描述生成。在分享场景里，链接本身之外还需要一句推荐语，AI根据网页内容生成简短的分享描述。
• 核心需求四：基础行为分析。记录点击次数、来源渠道、设备类型，让用户看到链接的传播表现。

这四个需求听起来每个都不难，但组合在一起，就决定了整个项目的技术选型方向：需要一个网页内容抓取模块、一个LLM接口层、一个短链生成与跳转服务、一个事件埋点存储，再加一个前端仪表盘。这已经是完整全栈应用的体量了。

接下来的问题是：谁来做这件事？我已经不打算自己一个人闷头写完所有代码，也不打算机械地让AI"写一段登录"“写一段路由”这样零散地干活。我想试的是：把AI当成一个完整的研发团队，有产品经理、架构师、前端工程师、后端工程师、测试工程师，各自用不同的模型或不同的Prompt角色，协同完成一个项目。"Linkly AI"就是这个多AI协作工作流的第一个真实试验田。

2. 多AI协作的最初设计：角色定义与任务拆分思路

真正动手之前，最大的问题是"多AI协作到底怎么协作"。不是开几个ChatGPT窗口来回复制粘贴，那只是人肉调度。我需要的是一套可执行的协作协议——明确任务边界、交接物格式、质量验收标准。这一步是整个项目中我花时间最长、也受益最大的一环。

2.1 四个Agent角色的明确分工

我最终把团队拆成了四个角色，每个角色有独立的Prompt模板和输出格式要求：

这里的核心经验是：不要让一个Agent同时干所有事。我见过很多人让同一个模型既做架构设计又写具体代码，结果就是前半段想得很宏大，后半段实现跟不上。把架构决策和编码实现拆到不同角色，即便底层是同一个模型，只要Prompt上下文不同，产生的结果质量也有明显差异。

2.2 任务交接的标准化格式

Agent之间协作最怕的就是"口口相传"导致信息衰减。所有角色之间的交接物必须是一份标准化的Task Spec文档，包含：目标描述、输入数据、输出产物、验收标准、风险约束。比如Product Agent给Architect Agent的交接物，不会是一段"我想做个链接工具"这样模糊的对话，而是一份结构化的PRD要点表。

• 目标描述：生成短链接时，AI需要根据页面内容自动产出语义化别名、分类标签、分享描述。
• 输入数据：用户提交的目标长URL。
• 输出产物：系统设计方案、数据库表结构、外部接口清单。
• 验收标准：短链接可访问、别名可读、分类准确率不低于80%、分析面板数据延迟低于5秒。
• 风险约束：最低成本运行，优先选择免费额度内的方案，不引入重型基础设施。

2.3 协作顺序与反馈闭环

整个协作流程是一个环：Product Agent先产出PRD，Architect Agent基于PRD产出架构，Engineer Agent基于架构写代码，QA Agent审查代码后把问题清单传回Engineer Agent修补。其中关键的一点是QA Agent不是最后才进入，而是在Engineer Agent每交付一个模块后就要跑一轮快速检查，形成小步快跑的迭代回路。

这个设计本质上把人类团队里的"日常站会同步"变成了机器之间的"结构化消息传递"，效率提升是其次，最重要的是每一轮迭代都有据可查。我现在回看整个开发日志，每一个设计决策都有当时的上下文记录，这在传统开发里几乎很难做到。

3. 系统设计落地：技术选型与核心数据模型

架构设计的阶段，Architect Agent产出的方案基本定下了整个系统的骨架。技术栈选择上，我给自己提了两个硬约束：一是成本尽可能低，个人项目不烧钱；二是部署足够简单，最好一个Docker Compose就能跑起来。

3.1 为什么选Python + FastAPI再加一个SQLite

后端选了Python和FastAPI，没有上Django。理由很简单：Linkly AI的核心逻辑是轻量API加少量数据库操作，不涉及复杂的权限体系和管理后台，FastAPI天生适合这种场景，而且自带OpenAPI文档，对联调和后续QA审查都方便。

数据库选了SQLite而不是PostgreSQL。我知道很多人看到"链接分析"就会默认要上PG，但对于个人自托管、日均几百到几千次点击的场景，SQLite完全够用。真要到了需要横向扩展那天，SQLAlchemy的抽象层可以平滑迁移，不需要重写业务代码。我在这类小项目上的原则一直是：不为想象中的高并发预先买单。

前端部分没有单独拆出Node服务，而是用Jinja2模板加少量HTMX完成了仪表盘页面。这个选择可能有点反主流，但效果很好：没有前后端分离的跨域问题，不需要额外维护前端构建链，AI生成的模板直接套上就能用，页面交互也不差。对AI编程来说，"技术栈越少、约束越少，生成质量越高"这个规律非常明显。

3.2 数据模型设计思路

表结构的设计是Architect Agent产出的最有价值的部分之一。一共四张表，每张表承担一个清晰的职责：

generation_jobs这张表是很多人做AI应用时容易忽略的。AI调用天然具有不确定性和相对较高的耗时，必须用一张任务表来记录每次生成的输入、输出、Token消耗和状态。这样既可以监控成本，也能让"生成失败重试""前端轮询状态"这类逻辑变得非常干净。

这里我要特别强调alias唯一约束的设计。语义化别名因为有AI生成这层前置，比纯随机短码更容易冲突。所以在表结构里对alias加了唯一索引，并且生成逻辑里加入了冲突检查：如果AI生成的别名已存在，则在尾部追加短随机后缀，而不是简单报错让用户换一个。

3.3 API契约与核心接口清单

接口设计遵循最小可用原则，总共六个核心接口，覆盖了链接管理的完整闭环：

• POST /api/link：提交长URL，触发AI生成任务，返回任务ID。
• GET /api/link/{task_id}：轮询查询任务状态，拿到最终的链接信息或错误信息。
• GET /{alias}：短链接跳转接口，记录点击事件后302重定向到目标地址。
• GET /api/links：列表查询，支持分类和标签筛选。
• GET /api/links/{id}/metrics：单个链接的访问分析数据。
• DELETE /api/links/{id}：删除链接，同步清理事件表数据。

前两个接口是异步设计，不是同步等待AI生成完再返回。这是因为LLM调用通常需要几秒到十几秒，如果做成同步阻塞，浏览器请求很容易超时，用户体验非常差。用"提交任务+轮询结果"的模式，配合generation_jobs表的状态流转，整个生成过程变得更健壮。

注意：链接跳转设计为302临时重定向，不是301永久重定向。301会被浏览器和搜索引擎缓存，后期如果你想改目标地址或者暂停某个链接，缓存会让你很被动。用302每次都走服务端，才能保证点击统计不丢失。

4. 核心实现细节：AI生成链路里的每一步都在干什么

架构定了之后，真正的活就来了。整个系统里最有含金量、也最值得展开讲的就是AI生成链路。这个模块承担了需求里三个核心功能：语义化别名生成、自动分类打标签、分享描述生成。它不是简单调一次LLM接口就完事，而是拆成了三个子任务的组合流水线。

4.1 页面内容抓取：绕过超时和反爬的关键处理

生成AI元数据的前提是拿到目标网页的内容。这一步看似简单，却是整个链路第一个容易翻车的地方。直接用requests.get去抓，会遇到三个大坑：响应超时、内容空白、被对方站点拦截。

• 超时处理：设置五秒连接和十秒读取超时，超过则自动降级用URL本身生成元数据。降级方案兜底，保证用户请求永远有响应。
• User-Agent伪装：很多站点对默认的Python-UA直接拒绝服务，统一设置成Chrome浏览器的UA字符串。
• 内容提取：命中HTML后，优先读og:title和og:description这两个OpenGraph标签，比正文解析更稳定。没有则退回到<title>和<meta name="description">。

我实测下来，用OpenGraph标签配合meta描述解析，绝大多数主流网站都能在几秒内拿到高质量的内容摘要。正文抽取那套复杂的算法（比如Readability）在这个场景里反而太过笨重——我们只需要给LLM足够的文字来判断主题和生成描述，并不需要读全篇文章。

4.2 三段式Prompt设计与一次调用的融合输出

关于"到底调用多少次LLM"，我踩过一次明显的弯路。最初设计是三次独立调用：一次生成别名、一次生成分类、一次生成描述。效果确实每项都更精细，但问题也很突出——三次调用头尾加起来耗时十几秒，Token消耗大三倍，而且中间任何一次失败都会让整个任务失败。

优化后的方案是：一次LLM调用，完成三个独立字段的生成。通过设计结构化输出的Prompt，让模型一次性返回JSON格式的alias、category、tags、description四个字段。实测耗时降到了单次调用的水平，分类准确率和描述质量几乎没下降。这里的关键是用好few-shot示例，而不是简单地在Prompt里写"请返回JSON"。

4.3 语义化别名的生成策略：可读性优先于唯一性

语义化别名是Linkly AI最核心的差异化功能。Prompt里对alias生成规则有几条硬性约束：6到30个字符，只能包含小写字母和连字符，优先提取页面标题里的核心名词短语，不使用停用词和泛词。比如一篇关于"Transformer模型推理成本优化"的文章，AI应该生成transformer-inference-cost而不是article-20240615。

这里有一个绕不开的问题：AI生成的alias天然有冲突概率。我的处理方案是三层递进：第一层直接把AI生成的alias插入数据库，撞了唯一索引就进入第二层；第二层在alias尾部追加两个随机数字或简短字母，像transformer-inference-cost-42；第三层如果再次冲突，就追加四位随机哈希，保证一定唯一。这样做的好处是，大部分链接能保住可读性，只有极端冲突时才牺牲一点可读性。

4.4 分类打标签的规则与模型约束

分类体系在架构阶段就固定好了，一共八个类别：Technology、Business、Education、Health、Entertainment、News、Shopping、Other。Prompt里给了每个类别的定义和三个示例URL，让模型先判断再填label。Tags则开放生成，但限制三到五个，且必须是语义明确的名词短语。

实测中一个有意思的现象是：如果不对模型强调"只能输出指定的类别字符串"，它经常会发挥出体系之外的分类，比如自定义出"Finance""Lifestyle"，导致前端筛选列表失控。后来在few-shot示例里专门加了一个反面示例，标注"Not allowed: Lifestyle. Correct: Entertainment"，准确率立刻上来了。这类经验告诉我们：给AI定边界，靠的不是口号，而是带对比的示例。

4.5 流式状态更新与失败重试机制

在generation_jobs表的支持下，我实现了六大状态流转：pending → fetching → generating → saving → completed，任何一步失败都会落为failed并记录error_message。前端轮询接口时，会根据状态显示不同的进度提示，比如"正在读取页面内容""AI正在分析主题""正在保存链接"。

失败重试的逻辑只针对generating阶段，最多重试两次，中间加三秒退避。如果连续失败，任务最终置为failed，并触发降级方案：直接用纯随机短码创建基础链接，把AI能力部分全部跳过。这样保证用户永远能拿到一个可用的短链接，只是没有那些智能元数据。

5. Engineer Agent实战：从空目录到可用代码的生成过程

架构文档就位后，真正的代码生成环节开始了。我用的是Cline加上DeepSeek-V3和Claude模型混合跑，让Agent按模块依次产出代码。整个过程中最关键的发现是：给AI一个清晰的目录结构和模块边界，它写出来的代码几乎不用大改；反之如果让它自由发挥，代码质量和风格会迅速失控。

5.1 项目结构与模块边界

工程开始前，Architect Agent产出了一个非常具体的目录规划：

linkly-ai/ ├── app/ │ ├── main.py # FastAPI入口与路由注册 │ ├── models.py # ORM数据模型 │ ├── schemas.py # Pydantic请求响应模型 │ ├── services/ │ │ ├── fetcher.py # 页面内容抓取 │ │ ├── generator.py # LLM生成链路 │ │ ├── alias.py # 别名冲突处理 │ │ └── metrics.py # 点击统计聚合 │ ├── routers/ │ │ ├── link_api.py # /api/link相关接口 │ │ ├── metrics_api.py # /api/links/{id}/metrics接口 │ │ └── redirect.py # /{alias}跳转接口 │ └── templates/ │ ├── index.html # 仪表盘主页面 │ └── link_detail.html # 单链接详情页 ├── tests/ │ ├── test_api.py │ ├── test_alias.py │ └── test_generator.py ├── docker-compose.yml ├── Dockerfile └── requirements.txt

实际证明，只要把目录结构和职责边界在任务说明里写清楚，Agent在生成代码时几乎不会出现"跨层调用"或者"职责混乱"的问题。它在每个模块里只做该模块的事，fetcher不碰数据库，generator不写路由逻辑。这是因为上下文的边界本身就能约束模型的输出范围，就像给到一个明确岗位的人，他自然知道自己该干什么。

5.2 抓重点：让Agent先生成核心业务，再补外围

我让Engineer Agent按"核心链路优先，外围功能后补"的顺序生成代码。第一步只写fetcher.py、generator.py、alias.py三个核心服务，配合最简单的路由把生成链路跑通；第二步才补metrics.py和跳转埋点；第三步才做前端模板和仪表盘。

这种顺序的核心价值在于：AI生成的代码在最核心的链路上会搭配最多的测试反馈，而外围代码即使有瑕疵也不会拖累核心功能。等到所有基础功能跑通后，再回头用QA审查来修补外围问题，成本低得多。

5.3 一次令人印象深刻的Agent自纠错过程

在生成alias.py时，Agent第一版代码里对唯一约束的处理是"捕获IntegrityError后重新生成一个别名"。这个逻辑本身没问题，但细看有一个bug：重试的时候用的是同一个随机种子，执行数据库插入之前没有清空ORM session。第一次冲突后session处于过期状态，第二次插入依然报同样的错。

有趣的是，这个bug不是人发现的，是QA Agent在做代码审查时发现的。它的审查报告里写了一行："Potential issue: retry logic does not rollback the session before re-inserting; will hit stale session errors." 工程师Agent收到这条审查意见后，自动修复了代码，在重试前增加session.rollback()调用。这是整个项目里第一个完全由AI自己发现并修复的bug，那一刻我还是挺惊讶的。

5.4 代码生成的常见质量问题和Prompt修正

连续几轮生成之后，我总结出AI写代码最容易反复出现的三个问题，也整理出了对应的Prompt修正策略：

还有一个经验是：同一次会话里连续生成的代码，质量会随着对话长度逐渐下降。我的做法是每个模块新开会话，把目录约定和系统全局说明放在System Prompt里，然后用一次完整的需求描述触发生成。模块之间靠文件系统接力，不靠同一会话的上下文记忆。

6. QA Agent的价值：代码审查发现了哪些人类会忽略的问题

整个项目里，QA Agent发挥的作用超出了我的预期，不是因为它能替代测试工程师，而是因为它以一种完全机械化的视角去审查代码，人类的固有思维盲区在它身上不存在。它会像强迫症一样逐行检查，找出那些我大概率看一眼就放过的隐患。

6.1 跳转接口的开放重定向漏洞

QA Agent审查GET /{alias}跳转接口时，提出了一条安全风险：如果links表里没有任何记录，我们的代码会把{alias}参数直接拼到目标URL上进行302跳转。这意味着任何访问者都能构造一个恶意链接，利用我们的域名完成开放重定向攻击。比如linkly.ai/goto?url=https://evil.com这样。修复方案也简单：所有跳转目标必须先从数据库查询得到，不能让参数直接决定跳转地址。

这个漏洞如果不认真审查，真的很容易漏。因为跳转接口的全部逻辑就几行代码，正常思路下很难想到"查不到alias时我还能干嘛"，而"查不到时param里还有用户可控内容"这个念头不会主动出现。QA Agent的价值恰好在它没有假设，只有穷举。

6.2 缺失的速率限制与滥用防护

QA Agent在第二轮审查中明确提出：POST /api/link接口没有速率限制，真实部署后会被脚本刷爆，每个请求都会触发昂贵的LLM调用，成本和资源都会被打爆。这个提醒让我意识到，"AI应用比普通CRUD应用更需要成本防护"这条铁律。普通接口被刷最坏是数据库变慢，而AI接口被刷意味着Token费用直线往上冲。

修复方案是在接口层加了个简单的内存滑动窗口限流：同一IP每分钟最多提交5次链接生成请求。虽然分布式环境下这个方案有局限，但对个人部署单实例的场景已经足够。

6.3 空值处理和极端输入覆盖

QA Agent给出的第三类重要意见集中在输入校验上：提交空URL、URL不含协议头、内容抓取完全失败、LLM返回了非法JSON、别名生成为空值，这些场景在开发时很容易被忽略，但在真实环境中几乎必然出现。它的做法是生成了一整套边界测试用例，覆盖这些极端场景，并让Engineer Agent逐条修复。

6.4 Automated测试的实际覆盖效果

经过两轮审查和修复，tests/目录下最终有27个测试用例。覆盖率不敢说特别高，但核心链路上的关键节点都有覆盖。我手动模拟了几个最常见的使用场景：提交正常URL、提交404页面URL、连续快速提交多个URL、访问不存在的短链接、删除正在被访问的链接，全部通过了测试。

这个阶段的直接收获是：整个项目从"看起来差不多了"到"真的敢放到公网跑"，靠的不是信心，是一份份测试报告。

7. 多AI协作里最实用的Prompt工程：三个角色模板公开

写完整个项目，最值得沉淀下来的就是三个角色Prompt模板。我直接把它们分享出来，这几个模板是纯文本的，你可以根据项目改完就能直接在Cline或自己组的Agent环境里跑。

7.1 Product Agent模板（需求拆解方向）

你是产品经理Agent。用户会给你一个模糊的项目想法或功能描述。 你的任务是： 1. 用不超过五句话解释这个项目解决的核心问题。 2. 分解出最多八个核心用户故事，每个故事用"作为...我想要...以便..."格式表达。 3. 为每个用户故事定义至少两条可测试的验收标准。 4. 标注哪些需求属于MVP必做，哪些属于后续迭代。 5. 输出格式必须为结构化Markdown，所有内容不得包含具体技术实现方案。

这套Prompt的精髓在于加了"不得包含具体技术实现方案"这条约束。产品Agent一旦开始考虑技术实现，就会不自觉地带入方案偏见。把技术和产品分离，是保证后续架构决策不被过早锁死的关键。

7.2 Architect Agent模板（技术设计方向）

你是系统架构师Agent。你会收到产品经理的输出，必须解读为可执行的系统设计。 你的任务是： 1. 确定技术栈，只允许选择成熟且社区活跃的方案，每个选择必须给出理由。 2. 设计数据模型，表名和字段需命名规范，关键表必须标注唯一约束与索引。 3. 定义核心API契约，包括请求响应结构和错误码规范。 4. 识别系统中最容易失败的两个环节，并主动设计兜底方案。 5. 输出格式必须包含：架构概览、数据模型、API清单、部署方案、风险清单五部分。

这条Prompt里最有价值的是第4条"设计兜底方案"。它强迫架构师在动手设计时就考虑"如果这一步挂了怎么办"，而不是等项目上线出了问题再打补丁。

7.3 Engineer Agent模板（编码实现方向）

你是高级工程师Agent。你会收到系统设计文档，需要按模块生成完整可运行的代码。 全局约束： 1. 严格遵循目录结构和模块边界，禁止跨模块引用内部实现。 2. 捕获已知异常，未知异常交给统一异常处理器，禁止裸except。 3. 每个文件禁止超过300行，超过则主动拆分。 4. 核心业务逻辑必须有相应的单元测试。 5. 不写冗余注释，只对关键算法和易错点作说明。 6. 使用异步IO处理外部HTTP调用和数据库操作。 7. 代码必须在Python 3.11环境可运行。

命令Engineer Agent按模块逐个生成，如果一个模块太大就让它自己拆分子模块。每次只让它交付一个文件或一个目录，避免一次生成过多导致质量下降。

7.4 QA Agent模板（审查方向）

你是资深测试工程师Agent。你会收到代码文件和对应的设计文档。 你的任务是逐行审查代码，必须报告： 1. 安全漏洞：包括注入、开放重定向、SSRF、越权访问、敏感信息泄露。 2. 边界条件问题：空值、极端输入、并发冲突、外部服务超时。 3. 代码质量问题：冗余逻辑、过度抽象、可读性问题。 4. 缺失的测试用例：指出哪些关键路径没有覆盖。 5. 每个问题必须标注严重程度（Critical/Major/Minor）和修复建议。 输出格式为问题清单表格，按严重程度排序。

个人经验是，QA Agent的审查意见不要让它直接改代码，而是把问题清单传回给Engineer Agent去修。这样职责边界清晰，问题修复的代码质量也更有保障。

8. 联调、部署与真实落地中的意外情况

开发接近尾声时，最大的考验来了：从本地环境搬到真实服务器上，联调各种外部依赖。这个过程暴露了不少开发环境没出现过的问题。

8.1 外部网站抓取的现实难度

本地开发时我用的测试URL都是固定的几个站点，一切顺利。一上生产环境，各式各样的真实URL涌进来，问题立刻出现：有站点会在三秒内不返回内容就直接挂断，有站点返回的HTML是JS渲染后的空壳，还有站点对非浏览器UA返回403。fetcher.py在本地测试时已经很健壮，但真实场景还是让超时重试策略做出了好几次调整。

最终把抓取策略改成三层：先试OpenGraph标签，失败则用meta描述，再失败则降级用URL自身路径生成元数据。页面正文全文解析被彻底放弃了，因为对LLM分类和描述生成来说，标题加描述的信息量已经足够。这个决策让抓取的成功率从不到七成提升到了九成以上。

8.2 HTTP与HTTPS的跳转兼容问题

另一个真实部署中才暴露的问题：服务器前面挂了Nginx并配置了HTTPS证书，但FastAPI应用本身跑在HTTP端口上。使用完整链接生成跳转地址时，如果代码里写死http://，那么最终分享出去的短链接就会以HTTP形式出现，浏览器会显示安全警告，非常影响可信度。

修复方案是让代码在生成跳转URL时优先读取X-Forwarded-Proto请求头，拿不到再回退到http。这个细节本地环境完全测不出来，只有真正部署在反代后面才会遇到。同理，用户提交的目标URL如果不是以http://或https://开头，抓取代码要自动补上https://，否则requests会直接报错。

8.3 容器部署与资源占用

Docker Compose部署时，我原本想着一个轻量应用撑死占用两三百MB内存。实际跑起来才发现LLM请求是同步IO操作，如果并发请求多，内存峰值会跳得很快。最终把Worker数量从默认的4个降到2个，并设置了--timeout 120的Gunicorn参数，避免请求处理中超时被强制杀掉。

SQLite单连接在小并发下反而比连接池更稳，因为SQLite本身对多写者不友好，一个连接通过锁机制保证写操作串行化，数据一致性更好。这一点和MySQL、PG的并发模型完全不同。

8.4 内容安全与水印策略

真实部署前，我还对AI生成内容加了一道安全过滤。开篇提到的"无禁词无审核"类搜索词我完全避开，不做也不碰。Linkly AI只处理合法、合规的常规链接，并且对生成结果做了一层基础校验：如果目标页面被明确判定为违法违规站点，拒绝生成链接。这一条不能省，因为链接工具天然会被滥用，主动加安全阀是必须的成本。

9. 成本账与性能数据：多AI协作到底值不值

整个项目从需求拆解到上线，总共耗时大约三天半的业余时间。这里有成本账可以算一算，给纠结"AI开发到底值不值"的人做一个参考。

9.1 Token消耗与实际花费

如果把这个项目交给外包开发，同样功能没有三五千块做不下来。25美元换一个完整可运行的全栈应用，这个投入产出比已经不需要再讨论。但要注意的是，这个账必须建立在"AI Agent工作流已经跑通"的前提下。如果是从零开始摸索多AI协作，前期的Prompt调试和流程设计成本至少要再翻一倍。

9.2 各环节花费时间分布

我记录了自己的时间支出：搭建Agent协作框架花了8个小时，这是最大的单项成本；剩下的需求定义3小时、架构审查1小时、代码生成与调度4小时、测试修补3小时、部署排错2小时。

时间上最值得优化的是"需求定义"那3小时。如果一开始就能一次性把PRD写清楚，后续Agent产出和验证的效率会高很多。反过来说，AI协作模式下，架构设计的速度快得惊人，传统项目里需要在会议室吵两天的技术选型，Agent十几分钟内就能给出完整建议，人的工作变成了审查而不是创造。

9.3 索引与查询性能

部署上线后，我对核心路径做了下基础压测。在SQLite上，点击事件写入的QPS大约在200左右，别名查询的延迟稳定在10毫秒以内。对于个人自托管的使用场景，这个数据非常舒服。仪表盘上的聚合数据通过定时任务每五分钟从事件表汇总到link_metrics表，查询自身不卡慢，数据延迟也在可接受范围内。

10. 实测表现与局限：Linkly AI在真实使用中的强项和短板

任何项目都有它的适用边界。Linkly AI在真实跑了三周之后，优势和局限性都暴露得比较充分。

10.1 表现最亮眼的三个场景

• 大量技术文章分享：AI生成的语义化别名辨识度极高，比如给一篇讲图数据库的文章生成graph-db-practical-guide，分享到群里别人一眼就知道内容方向，点击率明显高于那些随机短链。
• 内容归类整理：我的个人收藏链接经过AI自动分类后，按标签筛选非常方便，省去了手动整理书签的时间。
• 分享描述生成：AI生成的推荐语可以直接复制到社交媒体，省了一件事先想着怎么介绍文章的脑力活。

10.2 目前在用的两个运营小技巧

我实际用下来发现，给AI生成结果加"二次编辑"功能是刚需——AI给的文章标题和描述虽然准确，但个人分享时总想加点自己的观点。所以我在链接详情页加了一个简单的编辑框，允许用户对Title、Description、Tags做修改。这个改动很小，但对使用体验的提升非常明显。

另一个小技巧是生成的description不要直接截断到OpenGraph的原始内容，让AI在原始描述的基础上重写一遍，加入"为什么值得看"的角度，点击率会好很多。

10.3 当前局限与改造空间

局限也是明显的：一是LLM调用延迟这个物理瓶颈无法绕过，最坏情况下一个链接生成要等十五秒左右；二是免费额度耗尽后要自己付费配置API Key，成本随使用量线性增长；三是SQLite在并发高的时候写锁会成为瓶颈，如果链接被大量投放，需要迁移到PostgreSQL。

还有一个值得改进的方向是链接失效检测。现在Linkly AI不会主动检查目标链接是否已经失效，用户访问一个死链没有任何提示。后续可以加一个后台异步任务，定期抓取所有已生成的链接，遇到404或DNS解析失败时标记状态，并在仪表盘上列出异常。这是链接管理工具普遍缺少的能力，如果做了会非常有价值。

11. 一套直接可用的部署方案：从零到公网可访问

写到这里，很多东西已经融进前面各个章节了，但我觉得还是值得把一套完整的、可以直接照抄的部署流程独立整理出来，方便你在看完之后就能自己动手跑一个Linkly AI。

11.1 环境依赖准备

需要准备的东西非常简单：一台能跑Docker的云服务器（1核1G最低配置就够了）、一个域名（可选但强烈建议）、一个OpenAI兼容的API Key。

环境依赖清单：

项目运行环境：Docker 20.10+ 和 Docker Compose 2.0+ API Key：任意OpenAI兼容接口的Key 域名解析：把域名A记录指向服务器IP

11.2 docker-compose.yml生产配置

version: "3.9" services: linkly: build: . container_name: linkly-ai restart: always ports: - "127.0.0.1:8000:8000" environment: - DATABASE_URL=sqlite:///data/linkly.db - OPENAI_API_KEY=${OPENAI_API_KEY} - OPENAI_BASE_URL=${OPENAI_BASE_URL} - MODEL_NAME=${MODEL_NAME:-deepseek-chat} volumes: - ./data:/app/data command: gunicorn app.main:app -w 2 -k uvicorn.workers.UvicornWorker --timeout 120 --bind 0.0.0.0:8000

注意：这里的端口映射绑在了127.0.0.1上，不是0.0.0.0。这样FastAPI服务只能本机访问，由Nginx做反代对外提供HTTPS。避免把应用端口直接暴露到公网，是多一层安全隔离，成本几乎为零。

11.3 Nginx反代配置

server { listen 80; server_name linkly.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name linkly.example.com; ssl_certificate /etc/nginx/ssl/linkly.crt; ssl_certificate_key /etc/nginx/ssl/linkly.key; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } client_max_body_size 2M; }

这个配置里最重要的是X-Forwarded-Proto的传递，前面说过，短链接跳转地址靠这个头判断协议类型。如果少了这行，生成的跳转链接会走HTTP。

11.4 上线前的安全检查和清单

正式上线前最后过一遍检查清单：API Key用环境变量注入，不写进代码仓库；数据库目录挂载到宿主机volume，容器重建不丢数据；Nginx只开放443端口，其他全部关闭；速率限制配置确认生效；日志轮转打开，避免磁盘被请求日志打满。

部署完成之后，打开首页提交一个URL，等十几秒看到生成成功的短链接和AI元数据时，那种"整个系统是我自己攒出来的"的感觉，确实比直接用现成工具要爽得多。

12. 踩坑总结与后续扩展思路

整个项目做下来，最大的体会就是：多AI协作开发不是把AI工具拼在一起就完事，核心在于设计一套清晰的协作协议，让每个AI角色在其职责边界内发挥，又通过标准化的交接物衔接起来。Linkly AI这个项目虽然规模不大，但完整跑通了这个模式，并且效果已经超出预期。

12.1 踩过的坑清单（按严重程度排序）

• 没有任务流水表的AI应用等于没有审计日志：LLM调用是黑盒，出了问题没有generation_jobs的日志，排查会非常痛苦。
• 让同一Agent既做设计又做编码：模型在长上下文里容易"忘本"，生成的代码逐渐偏离架构约束。
• 不做速率限制就上线AI接口：一条请求就能烧掉0.2美元Token的场景真实存在，自己用不觉得，被人刷一次就后悔莫及。
• 301重定向"灵活现"：一开始图省事用了301，调试时改目标地址老半天不生效，换成302才恢复正常。
• 忽略HTTPS协议头传递：本地测不出问题，上公网就翻车，这类环境差异是最恼人的。

12.2 值得尝试的后续扩展

从产品角度，有三个方向是我自己很想去做的。一是批量导入导出：从浏览器书签或其他链接工具导入一批URL，AI批量生成元数据，这个功能对重度用户很有吸引力。二是团队协作：支持多人共用一套Linkly AI，各自管理自己的链接分组，这需要引入简单的登录鉴权体系。三是链接失效监控：定时检测所有链接的存活状态，在仪表盘上标注出已失效的短链，降低用户触达死链的挫败感。

12.3 给也想自己折腾AI项目的人几句心里话

如果你也想用类似的方式做一个自己的AI应用，我的建议是先从一个足够小、需求足够具体的项目开始。Linkly AI是一个链接工具，需求边界非常清晰，这对AI协作来说是非常有利的起点——模块边界天然存在，职责划分不需要人花太多精力去设计。反过来，如果你的需求本身充满模糊地带，比如"做一个AI助手"，那再强的Agent工作流也帮不了你，因为没有人能说清楚它到底该干什么。

另一个建议是做好心理准备：AI能写代码不假，但它不能替你思考"这个需求到底是不是准确的"，不能替你判断"这个设计是否真的符合使用场景"，更不能替你承担"部署上线后服务挂了"的责任。AI把执行效率拉高了一个量级，但决策质量依然要人自己来保证。想清楚这一点，再用AI协作的方式去做项目，体验会顺畅非常多。

最后，如果你尝试了任何基于这套思路的改造，比如加了批量导入、换成了PostgreSQL后端、做了团队版登录体系，都欢迎带着踩坑记录来找我聊聊。这类经验只有真正上手跑过，才知道哪些设计值钱、哪些想法理想化。