Tazhiyou
桌面 AI 智能体 · 知识增强系统
一盏清茶,一份匠心。
以茶道精神雕琢代码,以分层架构承载智能。
项目概览
静心、专注、精益求精
关于 Tazhiyou
桌面智能体Tazhiyou 是一款知识增强型桌面 AI 智能体,采用 分层 + 模块化 + 依赖注入 的复合架构。 在保证模块化的同时,通过统一接口规范与横切关注点(日志、错误、DI)确保可维护性与可扩展性。
集成知识管理、文档生成、文件智能分类、PC 控制等功能模块,通过本地 LLM 推理保障数据隐私。 如茶之沉淀,代码亦需静心雕琢——每一个模块都是一次修行,每一次重构都是一场悟道。
ServiceLocator 三生命周期 + 线程安全
9 类 ErrorCategory + guard<T> + RAII 上报
10 模块实现 IModule,ModuleManager 统一调度
展示/业务/数据/基础设施 4 层解耦
分层架构
四层复合架构,职责分明
表现层 · 业务层 · 数据层 · 基础设施层
表现层 · Presentation
views/*IModule / QWidget 视图,负责用户交互、主题与数据绑定。
业务层 · Business
models/*IService 业务服务,承载领域逻辑与流程编排,无 UI 依赖,可被多模块复用。
数据层 · Data
models/*/RepositoryIRepository<T> 仓储模式,隔离存储实现,支持分页、排序、过滤的统一查询。
基础设施层 · Infrastructure
core/*Core.h / Logger / AuditLog / Win32 封装,承载所有横切关注点。
横切关注点
所有层均通过统一的横切组件协同工作,确保关注点分离:
安全加固与预防性编程
纵深防御 · 白名单校验 · 异常全覆盖
输入验证 · 路径穿越 · 命令注入 · XSS · 加密 · 日志
输入白名单校验
SecurityValidator 集中校验路径/文件名/标识符/URL,按路径分量精确拒绝 "..",拒绝 Windows 保留名,fail-closed 白名单策略。
路径穿越防护
ZipReader 按分量精确拒绝 ".." 防 Zip Slip;FileOperations::rename 校验 newName 防分隔符注入;isWithinBase 规范化前缀校验。
命令注入防护
PowerShell 调用前单引号转义 (' → '');compress/extract 入口新增输入合法性校验,双层防御 CWE-78。
XSS 输出编码
HTML 特殊字符严格编码 5 字符全集 (& < > " '),与 OWASP 一致,统一替换此前各转换器 3~4 字符不一致实现。
AES-256 加密存储
AES-256-CBC + PKCS7,密钥由用户口令经 PBKDF2-HMAC-SHA256 (100000 轮) 派生,随机 IV,密钥不落盘,Windows CNG/BCrypt。
异常处理全覆盖
关键函数 100% 经 guard<T> 守护,捕获异常转 Result<T>;ErrorScope RAII 析构自动上报;9 类 ErrorCategory 细化分类。
边界检查与可观测性
统一边界检查入口 (checkIndex/checkRange) 防越界;StructuredLogger 12 分类 5 级别结构化日志 + traceId 关联;PerfTracer RAII 纳秒级计时,metricsUpdated 信号实时推送性能仪表盘:
核心组件
统一契约,各司其职
IModule
功能模块接口功能模块统一契约,由 ModuleManager 管理生命周期。定义 meta / initialize / createView / shutdown / executeCommand 等方法。
IService
业务服务接口业务逻辑层统一抽象,无 UI 依赖,可被多个模块复用。一个 IModule 可组合多个 IService。
IRepository<T>
数据访问接口仓储模式数据层接口,隔离存储实现。支持 save / findById / find / remove / count,配合 QueryOptions 实现分页查询。
ServiceLocator
依赖注入容器类型安全的 DI 容器,支持 Singleton / Transient / Instance 三种生命周期。基于 QReadWriteLock 保证线程安全。
ErrorHandler
错误处理九类错误分类 + 统一异常转换。提供 guard<T>() 守护执行、ErrorScope RAII 作用域、errorOccurred 信号供 UI 通知。
StructuredLogger
结构化日志12 个 LogCategory + Builder 模式 + PerfTracer 纳秒级性能追踪。支持分类过滤、关联追踪、度量统计与历史查询。
功能模块
模块化设计,各具匠心
文件管理模块
智能分类/搜索/整理/预览,树形+预览面板双栏布局
系统监控模块
CPU/内存/磁盘/网络仪表盘 + QChart 折线图 + 进程管理
AI 助手模块
多轮对话 + Agent 循环(5 轮防死循环)+ 技能系统 + tool_call
知识增强模块
维基百科爬取/TF-IDF 向量化/LRU 缓存/长文本生成
PC 控制模块
窗口管理/输入模拟/电源控制/AIAPM 性能监控
文件转换模块
DOCX/EPUB/MOBI/图像 → PDF 批量转换 + 拖放 + 进度信号
系统工具箱模块
注册表清理/磁盘碎片/软件卸载/内存优化(懒加载+异步+备份)
文档管理模块
Office 解析/LLM 文档生成/思维导图(write_document 工具)
网页可视化编辑器
WYSIWYG 编辑 + 6 模板 + 响应式预览 + 版本快照差异
设置模块
通用/模块优先级/权限/AES-256 安全/工作流 6 分页
数据流转约定
- ▸单向数据流:View → Service → Repository → 存储,返回 Result<T> 逆流而上
- ▸不可跨层:View 不直接访问 Repository;Service 不直接操作 QWidget
- ▸异步边界:耗时操作用 QtConcurrent::run + 信号回主线程
- ▸所有权:Repository 实体归 Service;Service 归 ServiceLocator;View 归父容器
代码实证
真实源码片段,匠心可见
摘自 src/core/arch/ 与 src/models/knowledge/
ServiceLocator · 依赖注入容器
三种生命周期 + 类型擦除 + QReadWriteLock 线程安全
template <typename Interface> void registerSingleton(std::function<std::shared_ptr<Interface>()> factory) { ServiceExtractor extractor = makeExtractor<Interface>(); registerEntry(typeid(Interface), Lifetime::Singleton, [factory]() -> std::shared_ptr<void> { return std::static_pointer_cast<void>(factory()); }, extractor); } // 实际注册示例(AppController.cpp:436) ServiceLocator::instance().registerSingleton<UsageStatsService>( []() { return std::make_shared<UsageStatsService>(); });
ErrorHandler · guard<T>() 守护执行
异常转 Result<T> + 9 类错误分类 + RAII 自动上报
template <typename T> Result<T> guard(const std::function<T()>& fn, ErrorCategory category, const QString& context = {}) { try { return { ResultCode::Ok, {}, fn() }; } catch (const std::exception& e) { report(category, ResultCode::Failed, QString::fromLocal8Bit(e.what()), context); return { ResultCode::Failed, QString::fromLocal8Bit(e.what()) }; } catch (...) { report(category, ResultCode::Failed, QStringLiteral("未知异常"), context); return { ResultCode::Failed, QStringLiteral("未知异常") }; } }
KnowledgeMemoryOptimizer · LRU 缓存
双向链表 + 哈希索引 + GlobalMemoryStatusEx 动态预算
const KnowledgeEntry* loadEntry(qint64 id) { ++m_totalAccess; auto it = m_index.find(id); if (it != m_index.end()) { // 命中缓存: 移到头部 const int idx = it.value(); if (idx > 0) { CacheNode node = m_lruList.takeAt(idx); m_lruList.prepend(node); m_index.clear(); for (int i = 0; i < m_lruList.size(); ++i) m_index.insert(m_lruList[i].id, i); } ++m_cacheHits; return &m_lruList.first().entry; } // 未命中: 从磁盘加载, 插入头部, 超预算淘汰尾部 auto r = m_store->get(id); if (!r.ok()) return nullptr; m_lruList.prepend({ id, r.data }); if (m_usedBytes > m_budgetBytes) unloadCold(); return &m_lruList.first().entry; }
KnowledgeVectorizer · TF-IDF 向量化
中文 2 字滑窗 bigram + 平滑 IDF + 倒排索引加速
QStringList tokenize(const QString& text) const { QStringList tokens; for (const QString& seg : segments) { if (seg.contains(/* 中文字符 */)) { for (int i = 0; i + 1 < seg.length(); ++i) { // 中文: 2 字滑窗 const QChar c1 = seg.at(i), c2 = seg.at(i + 1); if (c1.unicode() >= 0x4e00 && c1.unicode() <= 0x9fff) tokens.append(QString(c1) + c2); } } } return tokens; } void rebuildIdf() { const double N = static_cast<double>(qMax(1, m_docCount)); for (auto it = m_docFreq.begin(); it != m_docFreq.end(); ++it) { const double df = static_cast<double>(it.value()); const double idf = std::log((N + 1.0) / (df + 1.0)) + 1.0; // 平滑 IDF m_idf.insert(it.key(), idf); } }
DocumentAgent · 60s 超时保护
QEventLoop + QTimer::singleShot 限制 LLM 调用
static constexpr int kLlmTimeoutMs = 60000; // LLM 调用超时 60s QString callLlm(const QString& systemPrompt, const QString& userPrompt) { QList<ChatMessage> messages; /* System + User 消息构建 */ QEventLoop loop; Result<QString> result; ModelManager::instance().chat(messages, [&result, &loop](const Result<QString>& r) { result = r; loop.quit(); }); // 超时保护: 60s 后强制退出 QTimer::singleShot(kLlmTimeoutMs, &loop, &QEventLoop::quit); loop.exec(); if (!result.ok()) { TAZ_LOG_WARNING("DocumentAgent: LLM 调用失败: %1", result.message); return {}; } return result.data; }
FileManagementModule · QtConcurrent 异步
QFutureWatcher + QtConcurrent::run 避免 UI 阻塞
auto* watcher = new QFutureWatcher<ClassifyResult>(this); connect(watcher, &QFutureWatcher<ClassifyResult>::finished, this, [this, watcher]() { auto r = watcher->result(); if (r.ok()) { m_statusLabel->setText(QStringLiteral("已按维度分类: %1 组") .arg(r.data.size())); } watcher->deleteLater(); }); watcher->setFuture(QtConcurrent::run([root, classifyBy]() { FileClassifier fc; return fc.classify(root, classifyBy, false); }));
技术栈
精选工具,铸就品质
语言与构建
框架
存储与网络
AI 能力
架构模式
平台与系统集成
链接 10 个系统库:psapi · pdh · wbemuuid · powrprof · crypt32 · bcrypt · winmm · shlwapi · shell32 · winhttp
工程亮点
细节之处见匠心
类型安全的依赖注入
ServiceLocator 使用 ServiceExtractor 类型擦除,通过 if constexpr 编译期检查 is_convertible_v,避免 dynamic_pointer_cast 误用。QReadWriteLock 保障注册写锁、解析读锁的线程安全。
九类标准化错误处理
ErrorHandler 提供 Network/Database/FileSystem/Permission/Validation/System/AI/Configuration/Unknown 九大分类,配合 guard<T>() 守护执行与 ErrorScope RAII 自动上报,Win32 系统错误自动提取。
纳秒级结构化日志
StructuredLogger 提供 12 个 LogCategory、Builder 模式链式字段、PerfTracer RAII 自动测量耗时。支持 newTraceId 关联追踪、enableCategory 动态静音、recordMetric 度量统计与 entryLogged 信号实时推送 UI。
知识增强本地推理
知识管理模块实现向量化检索 + 倒排索引筛选 + LRU 缓存优化。LongTextGenerator 支持滑动窗口上下文管理、分段落生成与连贯性评分,本地 LLM 推理保障数据隐私,60 秒超时保护。
好的代码如同好茶,需要时间的沉淀与匠心的打磨。
"