适用版本：1.23.0　|　最后核对：2026-10-15

Agent 自动化引擎已整体内嵌于 Rust（src-tauri/src/commands/agent/），无外部进程、无需 Python 环境。 历史：v1.0 曾以 Python FastAPI + LangGraph 子进程实现（端口 9877），v1.1 迁移为 Rust 原生引擎，agent/、src-tauri/src/python/ 已删除。

TimeWrite 的 AI 能力分两条路径：

Agent 引擎与主进程同进程运行：Skill Prompt 组装 → 云端模型 ReAct 推理 → 工具调用直接经 repository 层读写 SQLite，全程无 HTTP 回调、无端口、无子进程生命周期管理。数据库写操作的唯一入口始终在 Rust，单进程模型天然规避多进程并发写锁。

┌────────────────────────────────────────────────────────────┐
│  WebView 前端（React 19）                                    │
│  components/agent/：useAgent / AgentMemoryPanel /          │
│    AgentMessageBubble / types                               │
└───────────────────────────┬────────────────────────────────┘
                            │ Tauri IPC（invoke / event）
┌───────────────────────────┴────────────────────────────────┐
│  Rust Core（Tauri v2）—— Agent 引擎 commands/agent/         │
│  skills.rs     IPC 命令层（execute/cancel + 记忆 CRUD）         │
│  engine.rs    SSE 流式 ReAct 循环 + 任务取消 + L2 模式分发     │
│  sse_parser.rs 纯函数 SSE 解析器（next_line / parse_sse /       │
│                flush_remaining_line，无 AppHandle 依赖）       │
│  pipeline.rs  L2 流水线执行器（固定步骤序列，阶段六）          │
│  profiles.rs  L1 画像注册表（提示词/工具/预算/执行模式）        │
│  prompts.rs   动态场景提示组装 + Token 估算                    │
│  tools.rs     L0 工具注册表 —— 8 个数据库工具                  │
│  memory.rs    memories 表存取 + 规则提取 + 检索                │
│     │                                                        │
│     ├── repository/（chapter / world_card / book 仓库）      │
│     └── SQLite（time_write.db，含 memories 表）              │
└─────────────────────────────────────────────────────────────┘

数据流方向：

前端 useAgent.executeSkill()
  → invoke('execute_agent_skill', { skill, bookId, message, aiConfig, requestId, ... })
  → skills.rs → engine.rs（先由 book_id 反查 book_type，合成「领域 × 能力」有效画像）
       ├─ 按 L2 执行模式分发（见 §3.3）
       │    ├─ ReAct     → 单个 react_loop（现状默认）
       │    └─ Pipeline  → pipeline.rs 按步骤跑多个「收窄工具/轮数」的 react_loop
       ├─ prompts.rs 组装 System Prompt（基准提示 + 场景提示 + 记忆段）
       ├─ reqwest POST {endpoint}/chat/completions（OpenAI 兼容 SSE，默认 DeepSeek）
       ├─ 模型返回 tool_calls → tools.rs execute_tool → repository → SQLite
       └─ 流式增量 → emit('agent-stream-chunk', { event, data, requestId })
  → 前端 listen() 按 requestId 过滤 → RAF 缓冲 → 更新消息 UI
  → 结束后异步 memory::extract_and_save 沉淀记忆

8 个子模块 + 1 个 mod.rs = 9 个文件：

v1.1 起原 get_agent_status / start_agent / stop_agent（启停外部 Python 进程）已随迁移移除； Agent 常驻 Rust 主进程，无启停状态机。

上下文裁剪常量：MAX_HISTORY_ITEMS=10、MAX_HISTORY_CHARS=2000、MAX_TOOL_RESULT_CHARS=30000、MAX_ITERATIONS=15。

run_skill()
  ├─ register_cancel_token()（全局取消令牌：标志 + Notify）
  ├─ 由 book_id 反查 book_type → profiles::merge(能力, 领域) → EffectiveProfile
  │    （领域/能力各有兜底：未知领域 → novel，未知能力 → writing；预算另有区分）
  ├─ 组装 System Prompt
  │    ├─ compose_system_prompt(eff, msg)   # 领域基准 + 能力基准 + 两类 hints（各 ≤3 条）
  │    └─ memory_prompt(book, skill, msg)   # 注入相关记忆段（≤600 tokens）
  ├─ 清理历史消息（剥离 reasoning_content）
  ├─ 按 EffectiveProfile.runtime 分发（见 §3.3）
  ├─ react_loop(..., ctx: ReactCtx)（ReAct）／ run_pipeline()（Pipeline）
  │    ├─ POST /chat/completions（tools = build_tools_schema(本次可见工具名)）
  │    ├─ **HTTP 错误诊断**：`classify_http_error` 对 DNS / 连接拒绝 / 超时 / TLS / 上游 5xx 等模式匹配返回中文诊断提示
  │    ├─ **SSE 解析**：`sse_parser.rs` 纯函数——`next_line` 逐行取出 → `parse_sse_data` 解析 JSON 返回 `LineParse { done, deltas }` → 对每个 delta 调 `emit_event("chunk", ...)` 推送；流结束时 `flush_remaining_line` 处理残留
  │    ├─ 有工具调用 → tools::execute_tool() → 追加 tool 消息 → 继续循环
  │    └─ 无工具调用 → 文本流结束
  ├─ emit('agent-stream-chunk', { event: 'done', ... })
  └─ 异步 extract_and_save()（记忆沉淀，不阻塞响应）

轮数上限不再是固定 15：取 EffectiveProfile.max_rounds（writing 5 / analysis 10 / research 20 / polish 3）。未知能力回退 MAX_ITERATIONS=15，不沿用 writing 的 5 轮。

流式事件协议（agent-stream-chunk，负载 AgentStreamEvent { event, data, requestId }）：

超时与取消：SSE 单行读取超时 60s、总超时 600s。取消采用 CancelToken（原子标志 + tokio::Notify）：cancel_current_task() 置位并 notify_waiters()，引擎在 SSE 流读取与 HTTP 发送两个阻塞点通过 tokio::select! 与取消通知竞争——即时中断，无需等待 60s 行超时或下一个 chunk；被放弃的流读取随即 drop、底层连接关闭，服务端感知后停止生成，任务以 cancelled 事件收尾（取消路径不再补发 done）。

run_skill_inner 组装完 System Prompt 后，按 EffectiveProfile.runtime 分发：

• 合并规则：领域优先、能力次之。流程形状由「处理什么作品」决定，故领域声明的模式优先于能力声明。
• 步骤隔离：Step { name, instruction, tools, max_rounds } 之间不共享消息历史。每步只看到「公共 System Prompt + 本步指令 + 用户消息 + 前序步骤产物」，上下文长度始终可控。
• 失败语义（部分成功，不自动重试）：单步失败即停，已完成步骤的产物保留，最终文本给出 x/y 结构化进度。刻意不做自动重试——create_note_card 有副作用且不可重入，盲重试会造成重复卡片。
• 文本一致性：步骤头 / 空输出占位 / 分隔换行由同一批函数生成，流式推送与最终渲染共用，故前端累积到的文本与 IPC 返回值逐字一致。流水线仍只推 chunk 事件，不新增事件类型。

SingleShot（单轮直出）是 ADR-005 规划的第三种模式，未实现——其唯一消费方「AI 工具箱迁移」标为可选且需先对齐网络重试能力，见 实施计划阶段六。

记忆持久化于主数据库 time_write.db 的 memories 表（v1.1 起由 Python 期独立 agent_memory.db 迁入）：

CREATE TABLE memories (
    id               INTEGER PRIMARY KEY AUTOINCREMENT,
    book_id          TEXT NOT NULL,
    skill_type       TEXT NOT NULL,      -- writing / analysis / research / polish
    memory_type      TEXT NOT NULL,      -- preference / decision / lesson
    content          TEXT NOT NULL,
    keywords         TEXT NOT NULL DEFAULT '',
    relevance_score  REAL NOT NULL DEFAULT 1.0,
    created_at       TEXT NOT NULL DEFAULT (datetime('now','localtime')),
    updated_at       TEXT NOT NULL DEFAULT (datetime('now','localtime')),
    last_hit_at      TEXT                -- 最近一次检索命中注入时间（NULL = 从未命中）
);
-- 索引：idx_memories_book_skill (book_id, skill_type) / idx_memories_type (memory_type)

extract_and_save 基于关键词规则在对话结束后自动提取，不消耗额外模型调用：

• 用户侧消息含「喜欢 / 偏好 / 习惯 / 希望…」→ preference
• 用户侧消息含「决定 / 选择 / 采用 / 打算…」→ decision
• 助手侧消息含「建议 / 注意 / 教训 / 提醒…」→ lesson
• 每条记忆截取最多 3 句；extract_keywords 用去停用词后的高频词生成 keywords

retrieve_memories(conn, book_id, skill_type, user_message, max_tokens, top_k)：

1. 候选集：先取「本书 + 本技能」精确匹配（≤50 条）；不足时回退整本书（≤30 条）
2. 打分：关键词交集越多分越高（score *= 1 + 0.3 × overlap），再乘类型权重
3. 裁剪：按 Token 预算（默认 600，DEFAULT_MAX_TOKENS）截取，top_k = 10

memory_prompt(...) 将检索结果格式化为可注入 System Prompt 的记忆段；命中为空则省略该段。

lib.rs setup 阶段检测旧 Python 期 agent_memory.db（开发模式 <cwd>/data/、打包模式 <app_data_dir>/），存在即调用 migrate_legacy_db() 一次性导入：

• 幂等：目标 memories 表已有数据则跳过；旧库无 memories 表也跳过
• 迁移失败仅记日志，不阻断应用启动

长期使用会积累大量低分/过期记忆拖慢检索，采用「容量上限 + 过期未命中」双清理策略（prune_memories）：

• 命中打点：retrieve_memories 选中注入的记忆即时更新 last_hit_at，作为过期判定依据
• 触发时机：extract_and_save 每次沉淀新记忆后随路清理本组；lib.rs 启动时 prune_all_memories 兜底清理存量（幂等，空库零开销）
• 清理失败仅记日志，不阻断记忆写入主流程

skill_base_prompt(skill) 返回对应技能 Prompt；未知 skill 回退 writing。

get_dynamic_prompt(skill, user_message) 采用 核心 Prompt + 场景提示 分离：

核心 Prompt（固定，前缀结构稳定，利于 KV Cache 命中）
   + 用户消息关键词匹配到的场景提示（最多 3 条，来自 dynamic_hints 表）
   = 最终 System Prompt

例如消息含「大纲」追加大纲生成指引，含「伏笔」追加伏笔分析指引。estimate_prompt_tokens 按 中文/1.5 + 其他/3.5 估算 Prompt Token。

8 个数据库工具收敛为 static TOOLS: &[ToolDef] 单一真相源（ADR-005 阶段一）：新增一个工具只需在数组里追加一项，不必再改「订阅 / schema / 分发」三处。数据源全部经 repository 层（chapter_repo / world_card_repo / book_repo）直接查询 SQLite。

通用工具（6 个）

领域工具（2 个，仅提炼类领域 breakdown / note 可见）

可见工具集 = 能力工具 ∪ 领域工具（能力在前、领域新增在后，保序去重）。各能力画像声明自己的子集：

未知能力回退 writing 工具集，但预算回退 15 轮 / 600s（不是 writing 的 5 轮 / 300s）。 拆书 / 学科笔记领域追加 list_book_chapters（若能力集尚无）+ split_chapter + create_note_card；小说 / 论文领域不追加任何工具。

• build_tools_schema(skill) 生成 OpenAI function calling 格式的 tools 数组随请求发送
• execute_tool(conn, name, args) 分发到各 tool_* 私有函数
• 返回内容统一裁剪（单工具结果上限 200,000 字符），循环内再按 MAX_TOOL_RESULT_CHARS（30,000）压缩后作为 tool 消息回填

要点：

• 状态恒为 running：Agent 无外部进程可启停，useAgent.status 固定 'running'，Header 状态栏显示「已连接 · 模型服务就绪」
• aiConfig 取自设置页对话配置，Agent 场景强制 reasoningEffort: 'max'
• AI 侧面板（AiSidePanel）与工具箱在 Agent 模式下同样复用 execute_agent_skill

约定例外：以上 Agent invoke 直接由组件发起（未封装进 tauri-bridge.ts）， 与「唯一 IPC 入口」约定不一致，见 架构总览 备注。

• Agent 使用指南 — 面向用户
• AI 模块架构 — AI 对话 / RAG（非 Agent）
• 架构总览 — 系统级双进程模型
• IPC 命令速查 — Agent 相关命令与事件
• ADR-002（Bridge 只读架构，已废弃） — v1.0 历史决策记录