跳转到主要内容

Tazhiyou

桌面 AI 智能体 · 知识增强系统

一盏清茶,一份匠心。
以茶道精神雕琢代码,以分层架构承载智能。

项目概览

静心、专注、精益求精

关于 Tazhiyou

桌面智能体

Tazhiyou 是一款知识增强型桌面 AI 智能体,采用 分层 + 模块化 + 依赖注入 的复合架构。 在保证模块化的同时,通过统一接口规范与横切关注点(日志、错误、DI)确保可维护性与可扩展性。

集成知识管理、文档生成、文件智能分类、PC 控制等功能模块,通过本地 LLM 推理保障数据隐私。 如茶之沉淀,代码亦需静心雕琢——每一个模块都是一次修行,每一次重构都是一场悟道。

0
C++ 源文件
0
功能模块
0
Qt6 模块
0
分层架构
依赖注入

ServiceLocator 三生命周期 + 线程安全

错误治理

9 类 ErrorCategory + guard<T> + RAII 上报

统一模块接口

10 模块实现 IModule,ModuleManager 统一调度

分层架构

展示/业务/数据/基础设施 4 层解耦

C++17 Qt 6.8.1 CMake SQLite 本地 LLM Win32 API

分层架构

四层复合架构,职责分明

表现层 · 业务层 · 数据层 · 基础设施层

表现层 · Presentation

views/*

IModule / QWidget 视图,负责用户交互、主题与数据绑定。

IModule QWidget ThemeManager

业务层 · Business

models/*

IService 业务服务,承载领域逻辑与流程编排,无 UI 依赖,可被多模块复用。

IService 领域逻辑 流程编排

数据层 · Data

models/*/Repository

IRepository<T> 仓储模式,隔离存储实现,支持分页、排序、过滤的统一查询。

IRepository<T> SQLite QueryOptions

基础设施层 · Infrastructure

core/*

Core.h / Logger / AuditLog / Win32 封装,承载所有横切关注点。

Core.h Logger AuditLog Win32

横切关注点

所有层均通过统一的横切组件协同工作,确保关注点分离:

ServiceLocator — 依赖注入容器
ErrorHandler — 标准化错误处理
StructuredLogger — 结构化日志
AuditLog — 操作审计

安全加固与预防性编程

纵深防御 · 白名单校验 · 异常全覆盖

输入验证 · 路径穿越 · 命令注入 · XSS · 加密 · 日志

输入白名单校验

SecurityValidator 集中校验路径/文件名/标识符/URL,按路径分量精确拒绝 "..",拒绝 Windows 保留名,fail-closed 白名单策略。

SecurityValidator CWE-20

路径穿越防护

ZipReader 按分量精确拒绝 ".." 防 Zip Slip;FileOperations::rename 校验 newName 防分隔符注入;isWithinBase 规范化前缀校验。

CWE-22 Zip Slip

命令注入防护

PowerShell 调用前单引号转义 (' → '');compress/extract 入口新增输入合法性校验,双层防御 CWE-78。

CWE-78 escapeForPowerShell

XSS 输出编码

HTML 特殊字符严格编码 5 字符全集 (& < > " '),与 OWASP 一致,统一替换此前各转换器 3~4 字符不一致实现。

CWE-79 OWASP

AES-256 加密存储

AES-256-CBC + PKCS7,密钥由用户口令经 PBKDF2-HMAC-SHA256 (100000 轮) 派生,随机 IV,密钥不落盘,Windows CNG/BCrypt。

AES-256 PBKDF2

异常处理全覆盖

关键函数 100% 经 guard<T> 守护,捕获异常转 Result<T>;ErrorScope RAII 析构自动上报;9 类 ErrorCategory 细化分类。

guard<T> RAII

边界检查与可观测性

统一边界检查入口 (checkIndex/checkRange) 防越界;StructuredLogger 12 分类 5 级别结构化日志 + traceId 关联;PerfTracer RAII 纳秒级计时,metricsUpdated 信号实时推送性能仪表盘:

SecurityValidator — 边界检查统一入口
StructuredLogger — 12 分类结构化日志
PerfTracer — 纳秒级性能追踪
AuditLog — SQLite 操作审计

核心组件

统一契约,各司其职

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 线程安全

src/core/arch/ServiceLocator.h
C++
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 自动上报

src/core/arch/ErrorHandler.h
C++
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 动态预算

src/models/knowledge/KnowledgeMemoryOptimizer.cpp
C++
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 + 倒排索引加速

src/models/knowledge/KnowledgeVectorizer.cpp
C++
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 调用

src/models/docmgmt/DocumentAgent.cpp
C++
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 阻塞

src/views/filemgmt/FileManagementModule.cpp
C++
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);
}));

技术栈

精选工具,铸就品质

语言与构建

C++17 CMake VS 2022 x64

框架

Qt 6.8.1 QtSql QtConcurrent

存储与网络

SQLite QNetworkAccessManager

AI 能力

本地 LLM 向量化检索 意图解析

架构模式

依赖注入 仓储模式 模块化

平台与系统集成

Windows 10+ Win32 API WMI CNG 加密

链接 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 秒超时保护。

"

好的代码如同好茶,需要时间的沉淀与匠心的打磨。

"
回到主页