donfaquir · Jul 6, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 3, 2026 · Jul 3, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.7.4] - 2026-07-06
+
+### Added
+- 后端心跳事件（`llm:heartbeat`），agent loop 迭代及工具执行期间每 10 秒发送
+- 前端 watchdog 定时器，30 秒无事件自动恢复 streaming 状态
+- 事件缓冲队列：前置事件未到时缓冲后续事件，前置满足后自动冲刷
+- 记忆提案卡片展示完整 content 字段（之前仅显示推荐原因）
+
+### Changed
+- Planning 模式从 Phase A/B 两阶段简化为单次 agent loop 执行
+- AiConversationPanel 拆分：提取 ToolCallItem、MessageBubble 组件和 useAgentEventHandlers hook（-31%）
+
+### Fixed
+- 事件处理器幂等化：tool-call-start / skill-spawn / tool-call-done 防重复
+- context-guard 使用消息计数替代索引，避免快照漂移
+- 工具审批等待时间不再计入工具超时
+
 ## [0.7.3] - 2026-07-01
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,42 @@
+# KnowForge Project Guidelines
+
+## Build & Test
+
+```bash
+# Frontend type check
+npx tsc --noEmit
+
+# Backend tests
+cargo test --manifest-path src-tauri/Cargo.toml
+
+# Dev server
+npm run dev
+```
+
+## Architecture: File Size Limits
+
+Single-file components and modules must not grow unboundedly. Hard limits (lines):
+
+| Threshold | Action |
+|-----------|--------|
+| > 800     | Consider extracting hooks or sub-components |
+| > 1200    | Must extract before adding new logic |
+| > 1800    | Treat as a bug — refactor before any other work |
+
+Current large files that must NOT grow further without extraction:
+
+- `src/App.tsx` (1921) — route/layout only; new features go in dedicated components
+- `src/components/AiConversationPanel.tsx` (1758) — recently refactored; new event handlers → `useAgentEventHandlers`, new rendering → `MessageBubble` or new sub-component, new UI state → dedicated hook
+- `src/components/AiLlmSettingsModal.tsx` (1680) — extract section components for new settings
+- `src/hooks/useOpenDocs.ts` (1140) — extract sub-hooks for new doc operations
+- `src-tauri/src/lib.rs` (1828) — Tauri command hub; new commands register here but implementation goes in domain modules
+- `src-tauri/src/llm/agent_loop.rs` (1581) — core loop; new tool handling → tool modules, new context logic → context_guard
+
+### Where to put new code
+
+- New Tauri event listener → `src/hooks/useAgentEventHandlers.ts`
+- New message rendering logic → `src/components/MessageBubble.tsx` or a new `src/components/<Name>.tsx`
+- New tool call display → `src/components/ToolCallItem.tsx`
+- New React hook → `src/hooks/use<Name>.ts`
+- New Rust tool → `src-tauri/src/tools/built_in/<name>.rs`
+- New LLM feature → `src-tauri/src/llm/<name>.rs`, not inline in `agent_loop.rs`
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "knowforge",
   "private": true,
-  "version": "0.7.3",
+  "version": "0.7.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

diff --git a/plan/INDEX.md b/plan/INDEX.md
@@ -0,0 +1,76 @@
+# Plan Index
+
+> 总控表：所有待办 spec 的状态、优先级一览。
+> 最后更新：2026-07-06
+
+---
+
+## Active
+
+（暂无进行中的 spec）
+
+---
+
+## Backlog
+
+（暂无 backlog — 当前架构已稳定，不再主动优化已知内部问题）
+
+---
+
+## Done
+
+| Spec | 优先级 | 完成日期 | 说明 |
+|------|--------|----------|------|
+| graph 私密节点过滤 | P0 | 2026-06-30 | 图谱泄漏私密笔记信息 |
+| note.read symlink 修复 | P0 | 2026-06-30 | 符号链接逃逸漏洞 |
+| link 隐私覆盖确认 | P1 | 2026-06-30 | link.suggest_related 隐私过滤 |
+| [thought.read](_archive/202506-tool-gap/spec-thought-read.md) | P0 | 2026-07-01 | 想法全文读取工具 |
+| [网络瞬态重试](_archive/202506-agent-loop-enhance/spec-error-recovery.md) | P1 | 2026-07-01 | 指数退避 + cancel 感知重试 |
+| [目标稳定性](_archive/202507-backlog-cleanup/goal-stability/README.md) | P1 | 2026-07-01 | 目标提取钉住 + 漂移警告 |
+| [计划审批](_archive/202507-backlog-cleanup/spec-plan-approval.md) | P1 | 2026-07-02 | Phase A→B 审批门（后已合并为单阶段） |
+| [主动压缩](_archive/202507-backlog-cleanup/spec-proactive-compaction.md) | P2 | 2026-07-03 | 修复快照索引漂移 |
+| Planning 模式简化 | P1 | 2026-07-03 | Phase A/B 合并为单次执行 |
+| God Component 拆分 | P1 | 2026-07-03 | AiConversationPanel 2570→1758 行 |
+| [事件可靠性](_archive/fix-event-reliability/) | P1 | 2026-07-06 | 心跳 + watchdog + 幂等 + 缓冲队列 |
+| 动态预算 | P1 | 已落地 | max_tool_calls 25 + budget 耗尽优雅降级 |
+| Agent Memory v2 | P1 | 已落地 | MemoryManager + agent_memory.json + LLM 提取 |
+
+---
+
+## Closed (Won't Fix)
+
+以下问题经评估后决定不修复，原因见括号：
+
+- D-2 隐式状态机（watchdog + 幂等 + 缓冲已从事件层面解决状态不一致）
+- D-4 会话重连（桌面应用刷新概率极低，审批超时已兜底）
+- D-6 压缩层边界不清（功能正确，重构风险 > 收益）
+- D-7 Skill 隔离（vault 非敌对数据，资源消耗已有界）
+- D-8 参数过多（纯美观，不影响功能）
+- 消息优先级（128K context 下几乎不触发）
+- 搜索重排序（LLM 本身是更强的 reranker）
+- 深度研究 / 工作记忆 / 结构化追踪 / 会话回放 / 并行 Agent / 零配置搜索 / MCP / 子 Agent / 思考可视化（关闭理由见 2026-07-03 评审）
+
+---
+
+## Archive
+
+历史计划文档已移至 `_archive/`，保留完整 git 历史。包含：
+
+- `iter1/` — 初始 AI 能力建设（P0-P5 工具 + agent loop）
+- `iter1-ai-upgrade/` — ContextGuard + 计划审查等 spec
+- `unified-provider/` — 统一 Provider 重构
+- `llm-latency/` — LLM 响应延迟优化
+- `agent-memory/` — Agent 记忆系统（20 个 spec）
+- `context-management-redesign/` — 上下文管理重设计（Phase 1 已完成）
+- `search-agent/` — 搜索 Agent 升级分析
+- `tool-gap-analysis/` — 工具缺口分析
+- `iter2-agent-evolution/` — Agent 架构进化路线（Phase 1-4）
+- `web-search-evolution/` — Web 搜索竞品分析与路线
+- `202506-security-privacy-fix/` — 安全与隐私修复（3 spec，全部完成）
+- `202506-tool-gap/` — 工具缺口（thought.read 完成，其余 wontfix）
+- `202506-agent-loop-enhance/` — Agent Loop 增强（重试已完成，反思循环 P3 延后）
+- `202507-backlog-cleanup/` — 2026-07 Backlog 清理
+- `fix-event-reliability/` — 事件可靠性三层修复（2026-07-06 完成）
+- `refactor-god-component/` — God Component 拆分方案
+- `review-agent-loop-architecture.md` — Agent Loop 架构评审
+- `session-context-management-analysis.md` — 会话上下文管理分析
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "knowforge"
-version = "0.7.3"
+version = "0.7.4"
 description = "Knowforge desktop app"
 authors = ["caichangqing"]
 edition = "2024"

diff --git a/src-tauri/src/ai_conversations.rs b/src-tauri/src/ai_conversations.rs
@@ -122,6 +122,8 @@ struct PersistedMessageDisk {
     skill_id: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     skill_name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    tool_calls: Option<Value>,
 }
 
 /// 会话级「想法聚焦」上下文（磁盘与 LLM 字段对齐）
@@ -249,6 +251,8 @@ pub struct PersistedMessageOut {
     pub skill_id: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub skill_name: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tool_calls: Option<Value>,
 }
 
 #[derive(Debug, Clone, Serialize)]
@@ -299,6 +303,8 @@ pub struct PersistedMessageIn {
     pub skill_id: Option<String>,
     #[serde(default)]
     pub skill_name: Option<String>,
+    #[serde(default)]
+    pub tool_calls: Option<Value>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
@@ -358,6 +364,7 @@ fn validate_messages_for_save(msgs: &[PersistedMessageIn]) -> Result<Vec<Persist
             reply_context_sources: m.reply_context_sources.clone(),
             skill_id: m.skill_id.clone(),
             skill_name: m.skill_name.clone(),
+            tool_calls: m.tool_calls.clone(),
         });
     }
     Ok(out)
@@ -473,6 +480,7 @@ fn load_ai_conversation_for_subdir(root: &Path, subdir: &str, args: LoadAiConver
             reply_context_sources: m.reply_context_sources,
             skill_id: m.skill_id,
             skill_name: m.skill_name,
+            tool_calls: m.tool_calls,
         })
         .collect();
     Ok(ConversationBodyOut {
@@ -642,6 +650,7 @@ mod tests {
                         reply_context_sources: None,
                         skill_id: None,
                         skill_name: None,
+                        tool_calls: None,
                     },
                     PersistedMessageIn {
                         id: "a1".to_string(),
@@ -651,6 +660,7 @@ mod tests {
                         reply_context_sources: None,
                         skill_id: None,
                         skill_name: None,
+                        tool_calls: None,
                     },
                 ],
                 set_as_active: Some(true),
@@ -680,6 +690,7 @@ mod tests {
             reply_context_sources: None,
             skill_id: None,
             skill_name: None,
+            tool_calls: None,
         }];
         assert_eq!(compute_title_from_messages(&msgs), "New chat");
     }