# Vibe Coding 实践分享：用 AI 构建本地写作 Agent 的架构设计与技术选型

## 引言

各位开发者好。我是一名内容创作者，也是 Vibe Coding 的实践者。最近完成了一个名为**墨参（MoShen）**的开源项目——一个本地优先的个人写作 Agent，面向长篇小说创作者。

项目已开源：[GitHub - M1r0er/moshen](https://github.com/M1r0er/moshen)

今天在此分享，一方面是记录 Vibe Coding 的实践过程与技术选型思路，另一方面也恳请各位有经验的开发者帮忙审视代码，指出不足之处。作为一个非专业开发者主导的项目，我知道在架构、安全和工程实践上一定有改进空间。

---

## 一、项目定位与设计哲学

### 1.1 问题域

长篇小说创作面临一个核心挑战：几十万字的设定、伏笔、人物关系需要跨章节甚至跨卷保持一致。作者自身很难在写作时同时回忆和管理所有这些信息。

现有 AI 写作工具大多采用"一键生成"模式，但这种方式存在根本性矛盾：

- 模型在海量平均语料上训练，输出趋向"最平均"表达，人物与桥段趋向套路
- 长篇依赖几十万字前后一致的设定，纯生成难以长期维持
- 写作主导权交出后，作者对作品的判断力与个人风格一并丢失

### 1.2 核心理念

墨参的核心理念是：**将 AI 放在编辑的位置，而非代笔的位置**。

具体而言，Agent 与传统助手的区别在于主动性：

| 行为 | 墨参的做法 |
|---|---|
| 保存即巡检 | 每次保存章节，一次调用同时产出伏笔检测和角色观察 |
| 主动干预 | 发现逻辑漏洞、设定矛盾时按三级主动提出 |
| 自主长任务 | 星图分析、拆书蒸馏、AI 审稿等自主跑完整流程 |
| 自主上下文组装 | 审稿只送设定树+人物档案+大纲+待审正文，不重复烧 token |
| 自主落盘 | 报告写进 reports/ 并同步知识库，失败带回原因供重试 |

但 Agent 的行为边界明确限定在：**整理、核对、质疑、记录**。正文只有作者手动保存时才写入磁盘。

### 1.3 系统合同

项目设有一份不可被用户配置或写作模板覆盖的系统合同，规定以下约束：

1. **作者事实优先**：作者明确写入的设定、大纲、角色与正文是事实来源，AI 推断不得覆盖
2. **来源可辨**：区分"作者已确认的事实"与"AI 推断/建议的内容"
3. **输出诚实**：不谎称已执行操作
4. **不泄漏系统提示**
5. **结构化输出**：被要求返回 JSON 时只输出合法 JSON

---

## 二、功能架构

墨参共 10 个功能页面，涵盖创作全流程：

### 2.1 创作核心

**对话页**支持流式输出，输入意图经路由器分配到不同职能模型。对话中模型可通过标记协议直接写入设定/大纲/知识库，或提出待确认提案（作者点选后才落地）。发现问题时触发三级干预：

- L1 建议：温和推荐
- L2 质询：指出问题要求解释
- L3 否决：明确阻止严重后果

**写作页**提供富文本编辑器与自动保存，核心特性包括正文角色条目自动标蓝联动、AI 审稿（设定一致性/人物OOC/逻辑因果/节奏/文风/伏笔）、保存后自动巡检、章节创作流程门禁（规划→草稿→审稿→修稿→定稿，状态只向前推进）。

### 2.2 设定管理

**角色页**实现角色 = 档案 + 阶段节点 + 事件连线 + AI观察收件箱的结构。AI 分阶段解析按正文拆分角色成长阶段，保存时自动提取的提及与新别名进入收件箱待作者逐条采纳或忽略。

**星图页**从稿件抽取六类实体（角色/世界/势力/地点/事件/道具）及关系，3D 可视化，重新分析采用增量更新（AI 只提交变更补丁，不整份重写）。

**伏笔台账**记录埋设与回收，按状态排序，保存章节时自动检测。

### 2.3 辅助功能

设定页（多级目录树/筛选/搜索/AI优化/导出多格式）、大纲页（节点连线式）、爽爆点库（使用次数统计/审美疲劳提示）、知识库、灵感文件夹、文件诊断（文风诊断/逻辑检查/冲突值计算/拆书蒸馏）。

---

## 三、技术架构与选型

### 3.1 整体架构

```
┌─────────────────────────────────────┐
│           Electron 主进程             │
│  (窗口管理 + Python 子进程生命周期)    │
├──────────────┬──────────────────────┤
│  preload.js   │   Python FastAPI     │
│  (进程桥接)    │   (uvicorn 后端服务)  │
├──────────────┼──────────────────────┤
│              │  ┌─────┐ ┌────────┐  │
│  Vue 3 前端   │  │core │ │engines │  │
│  + three.js  │  ├─────┤ ├────────┤  │
│  (单文件HTML)  │  │know-│ │analysis│  │
│              │  │ledge│ │        │  │
│              │  ├─────┤ ├────────┤  │
│              │  │route│ │prompts │  │
│              │  └─────┘ └────────┘  │
└──────────────┴──────────────────────┘
         │                    │
    ~/.moshen/.env      工作区目录（JSON/MD/HTML）
    (API Key 配置)      (项目数据，纯文件存储)
```

### 3.2 技术栈

| 层级 | 选型 | 选型理由 |
|---|---|---|
| 桌面框架 | Electron 33 + electron-builder | 跨平台桌面打包，前端可复用 Web 技术栈 |
| 后端 | Python 3.10+ / FastAPI / uvicorn | 异步支持好，生态丰富，PyInstaller 可打包 |
| 前端 | Vue 3（单文件）+ three.js | 响应式开发，three.js 实现 3D 关系图 |
| 模型接口 | OpenAI 兼容协议 | 兼容 DeepSeek/Claude/GPT/Qwen/Ollama 等 |
| 存储 | 工作区纯文件 | 本地优先，无数据库依赖，可移植 |

### 3.3 后端分层

后端采用清晰的四层架构：

**核心层（core/）**：配置管理、LLM 调用封装、上下文管理、安全 IO、会话租约、文件解析

**引擎层（engines/）**：对话编排、意图路由、主动干预评估

**知识层（knowledge/）**：项目知识库、创作流程状态机、角色库、爽爆点库、拆书引擎

**分析层（analysis/）**：星图分析器、伏笔分析器、角色分阶段解析、文风档案

**路由层（routes/）**：14 个路由模块，对接前端的 10 个页面

### 3.4 四层上下文管理

```python
class ContextManager:
    """四层上下文组装器（请求级，不跨请求共享）"""
    
    def __init__(self, core_layer="", memory_layer="", working_layer=""):
        self._core_layer = core_layer      # 墨参人格 + 系统合同
        self._memory_layer = memory_layer   # 项目知识库摘要
        self._working_layer = working_layer # 当前焦点 + 检索结果
        self._history = []                  # 对话历史
```

设计要点：

- **system 消息只包含跨轮次稳定的内容**（核心层 + 记忆层），便于 LLM 复用上下文缓存
- **请求级实例化**：每次请求创建新的 ContextManager，不跨请求共享可变状态，避免并发串台
- **上下文按预算与优先级注入**：被截断或省略的部分会显式告知模型与用户，不做静默丢弃

### 3.5 原子写与并发安全

```python
def atomic_write_text(path, content, encoding="utf-8"):
    """原子写入：同目录临时文件 + fsync + os.replace"""
    target = Path(path)
    target.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp = tempfile.mkstemp(
        dir=str(target.parent), prefix=".tmp_", suffix=target.suffix or ".tmp"
    )
    try:
        with os.fdopen(fd, "w", encoding=encoding, newline="") as f:
            f.write(content)
            f.flush()
            os.fsync(f.fileno())
        os.replace(tmp, target)
    except BaseException:
        try:
            os.unlink(tmp)
        except OSError:
            pass
        raise
```

读改写串行化使用进程内可重入锁（`threading.RLock`），单用户桌面应用场景下一个全局写锁即可消除竞态。JSON 存储的读改写序列通过 `update_json` 方法封装为原子操作。

### 3.6 会话租约机制

```python
@app.middleware("http")
async def enforce_session_lease(request, call_next):
    if request.method in _MUTATING_METHODS:
        path = request.url.path
        if path.startswith("/api/") and not path.startswith(_SESSION_EXEMPT_PREFIXES):
            lease = request.headers.get("X-Moshen-Lease")
            if get_session_registry().is_stale(lease):
                return JSONResponse(
                    {"detail": "项目会话已过期"},
                    status_code=409,
                )
    return await call_next(request)
```

项目被重新打开后，旧窗口的租约失效，其写操作被拒绝，避免过期上下文污染新会话。未携带租约的请求保持放行，兼容尚未接入的调用路径。

### 3.7 多模型职能分配

```
TEXT_MASTER        → 文学分析、文风诊断
STRUCTURE_ANALYST  → 结构分析、逻辑检查、干预评估
KNOWLEDGE_BUILDER  → 拆书、知识提取
DIALOGUE_PARTNER   → 日常对话、创意讨论
NOVEL_ANALYZER     → 星图实体与关系抽取
IMAGE_GENERATOR    → 人物肖像
```

降级链：未单独指定的职能自动回退到默认渠道。auto 模式结合输入长度与意图，在同一渠道的多个模型间选择。

### 3.8 安全措施

| 措施 | 实现 |
|---|---|
| 本机访问限制 | 中间件校验 Host，仅允许 127.0.0.1/localhost/::1 |
| API Key 保护 | 密钥不回传前端，一律掩码返回，留空即保持不变 |
| 原子写 | 临时文件 + fsync + os.replace |
| 读改写串行化 | 进程内可重入写锁 |
| 会话租约 | 旧窗口写操作被 409 拒绝 |
| 来源标注 | 设定/大纲/伏笔记录带 author/ai 标注，AI 不覆盖手工内容 |
| 写入分两类 | 标记触发直接写入 vs 待确认提案需手动确认 |

---

## 四、数据与隐私

| 数据类型 | 存储位置 |
|---|---|
| 项目资料 | 工作区目录（JSON / Markdown / HTML） |
| 模型配置与 API Key | ~/.moshen/.env |
| 偏好设置 | ~/.moshen/workspace.json |

核心原则：

- 不提供模型额度，不托管稿件
- 请求发往用户自己配置的服务商
- 所有数据存于本机，无云端依赖
- 对话中的写入分两类：直接写入仅限设定/大纲/知识库，其余内容走待确认提案

---

## 五、已知限制

| 限制 | 说明 |
|---|---|
| 不生成正文 | 不提供一键成书 |
| 质量依赖模型 | 星图分析、文风诊断等结论需作者复核 |
| 肖像功能 | 需兼容 /images/generations 接口 |
| 界面语言 | 简体中文 + English（英文尚不完整） |
| 代码签名 | 未签名，Windows 可能提示 |
| 平台 | 仅 Windows 构建 |

---

## 六、诚邀各位开发者审视

作为一个 Vibe Coding 产物，项目在以下方面仍需改进，恳请各位指正：

1. **功能完整性**：是否有缺失的关键功能？
2. **安全审计**：本机访问限制、API Key 保护、原子写等措施是否充分？
3. **架构合理性**：四层上下文、多模型路由、增量更新等设计是否有更优方案？
4. **并发安全**：写锁策略在哪些场景下可能不足？
5. **工程实践**：测试覆盖、错误处理、代码组织等方面的问题
6. **用户体验**：交互流程设计是否合理

项目地址：[https://github.com/M1r0er/moshen](https://github.com/M1r0er/moshen)

MIT 协议，欢迎 Issue 与 PR，也欢迎在评论区交流技术细节。每一条反馈我都会认真对待。

---

## 结语

这个项目试图回答一个问题：如果把 AI 放在编辑而非代笔的位置上，能不能既利用模型的能力（核对矛盾、追踪伏笔、诊断文风），又保留作者的创作主导权？

Vibe Coding 让不懂代码的人也能尝试回答这个问题。但做出能用和做出好用之间的差距，需要社区的力量来弥合。

如果这个方向有价值，或者有什么想法，欢迎交流。

---

*项目持续迭代中，觉得有价值的话 Star 一下就是对作者最好的鼓励。*


各位开发者好。我是一名内容创作者，也是 Vibe Coding 的实践者。最近完成了一个名为墨参（MoShen）的开源项目——一个本地优先的个人写作 Agent，面向长篇小说创作者。

Vibe Coding 实践分享：用 AI 构建本地写作 Agent 的架构设计与技术选型

人工智能

编程语言

架构设计

墨参（MoShen）开源写作Agent：本地优先、AI辅助长篇小说创作，采用VibeCoding实践。核心将AI定位为编辑而非代笔，通过主动干预、原子写、四层上下文管理，实现设定一致性检查、伏笔追踪、角色分析等功能。技术栈含Electron、FastAPI、Vue3，支持多模型路由与安全本机运行。

文件存储

安全审计

代码解释

中间件

数据库

路由器

DeepSeek

Windows

GitHub

Python

路由

Agent

JSON

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Vibe Coding 实践分享：用 AI 构建本地写作 Agent 的架构设计与技术选型-腾讯云开发者社区-腾讯云

Vibe Coding 实践分享：用 AI 构建本地写作 Agent 的架构设计与技术选型

Vibe Coding 实践分享：用 AI 构建本地写作 Agent 的架构设计与技术选型

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐