知识分享 qianqianjie.top

Rust · Python · Flutter · AI Agent

把踩过的坑,
写成能复用的知识。

这里是我做过的一些项目,和关于 AI Agent 的实践笔记。 不追热点,只记录真正跑在生产环境里的东西。

12开源项目
08Agent 笔记
113Agent Skills
01

项目

从内网穿透到智能交通,每一个都来自真实需求。

P.01基础设施

rust_frp

Rust 实现的 frp 内网穿透工具。TCP / UDP / HTTP / HTTPS / QUIC / WebSocket 全传输,mTLS + AES-256-GCM,兼容原版 frp 配置。

Rust↗
P.02数据采集

tenders

招标公告自动采集平台:多站点爬取、Web 端筛选与关注、数据统计和提醒,长期运行在生产环境。

Python / Flask↗
P.03AI & Agent

team-skills

精选 AI Agent Skills 技能库,Trae 与 WorkBuddy 双智能体共享,覆盖开发、文档、运维等 113 个可复用流程。

Python↗
P.04端侧 AI

announcer-ocr

叫号屏 OCR 语音播报机:摄像头实时识别号码,TTS 语音提醒,systemd 常驻自启,生产环境长期稳定运行。

Rust↗
P.05桌面应用

PDF-DocVault

本地优先的 PDF 文档中心:PDF 操作、文档扫描、OCR 识别与归档管理,数据永不离开本机。

C / OCR↗
P.06企业应用

AR_Smart

企业应收账款管理系统:账款台账、账龄分析、数据可视化与定时催收提醒,Vue 3 + Flask。

Vue / Flask↗
P.07智能交通

ITS_Archives

智能交通建设档案系统:信号灯、电子警察、卡口等设备档案、质保与维修记录,前后端分离。

Vue / Flask↗
P.08企业应用

施工日志平台

Flutter 移动端填报 + Flask / Socket.IO 后端:水印拍照、日志审批、项目群聊,数据完全自主部署。

Flutter / Flask↗
P.09企业应用

procurement

企业级采购管理平台:采购计划创建、多级审批流程、PDF 导出,Flask + Bootstrap。

Python↗
P.10企业应用

labormanagement

劳动用工申请与审批管理系统:Flask + React 前后端分离,含验证码与登录频率限制。

React / Flask↗
P.11智能交通

traffic_volume

交通流量采集展示系统:流量数据采集、统计分析与可视化大屏。

C↗
P.12工具

QJ Scanner

文档扫描应用:文档数字化、图像增强与处理,面向日常纸质资料归档。

Python↗
在 GitHub 查看全部仓库↗
02

AI Agent 笔记

来自实际落地的经验,不是论文摘要。

N.01 Agent 的本质是一个循环

模型本身只会「说」,Agent 让它「做」。核心循环是:观察状态 → 规划下一步 → 调用工具 → 读取结果 → 判断是否结束。

工程上真正难的不是循环本身,而是三件事:状态如何表示、工具返回如何裁剪、什么时候停。没有明确停止条件的 Agent,最终都会变成烧 token 的 while(true)。

N.02 工具设计决定能力上限

同一个模型,工具 schema 写得好不好,任务成功率可能差一倍。几条经验:

  • 工具名用动词短语,参数少而必填项明确;
  • 错误信息要告诉模型「怎么改」,而不是抛一段 stack trace;
  • 写操作做成幂等,并提供 dry-run;
  • 权限边界放在服务端,不要只写在 prompt 里。
N.03 MCP:把工具接入标准化

MCP 把「模型 ↔ 工具」拆成 host / client / server 三层,工具、资源、提示词都可以被发现和调用。stdio 适合本地进程,HTTP / SSE 适合远端服务。

落地时要记住:每个 server 都是一个新的攻击面。工具白名单、参数校验、调用审计和超时,一个都不能少。

N.04 上下文工程比 prompt 更重要

上下文窗口不是越大越好:无关内容会稀释注意力,长上下文还贵。实用做法是分层——系统约束常驻、任务状态结构化、检索内容按需注入、历史定期压缩成摘要。

子 Agent 的价值往往不是「更聪明」,而是把大量中间过程隔离在另一个上下文里,主线程只拿到结论。

N.05 多 Agent 不是默认答案

多 Agent 适合可清晰分工、且子任务上下文相互独立的场景,比如并行调研、多视角审查。如果是强耦合的连续操作,拆开只会增加通信成本和状态不一致。

先问一句:单 Agent 加上好工具能不能做完?不能,再拆。

N.06 记忆要分层,更要有写入策略

工作记忆放当前任务,情节记忆存历史交互,语义记忆沉淀稳定事实。关键不在「存」,而在「什么时候写、写什么、什么时候忘」。

无脑全量记忆会把错误和过时信息一起固化下来,比不记更糟。

N.07 评测与可观测性

上线前至少准备 20–50 条真实任务回归集,记录任务成功率、工具调用成功率、平均步数、token 成本与延迟。

生产环境保留完整 trace(输入、工具参数、返回、耗时),否则出问题只能靠猜。小模型配好工具链,常常优于大模型配烂工具。

N.08 Skills:把流程变成资产

Prompt 是一次性的,Skill 是可版本化的流程资产:触发条件、步骤、脚本、检查清单都写在文件里,按需加载。

把重复三次以上的操作固化成 Skill,是 Agent 工程里性价比最高的投入。我的 team-skills 就是这么攒起来的。

03

关于

全栈开发者,写 Rust、Python 和 Flutter,做智能交通,也折腾 AI Agent。

喜欢把系统跑到生产环境里,而不是停在 demo。这个站点用来沉淀项目经验和 Agent 工程笔记,内容会持续更新。