doc: optimize and remove outdated docs #781
Conversation
- Remove 7 outdated/duplicate IPC documents that caused confusion - Create comprehensive IPC architecture guide (ipc-architecture-complete.md) - Update EventBus usage guide with best practices and optimization examples - Add specific optimization recommendations based on codebase analysis - Eliminate documentation inconsistencies and provide accurate current state 🤖 Generated with [Claude Code](https://claude.ai/code)
- Remove 17 fragmented documentation files covering MCP, knowledge systems, and implementation details - Create 3 comprehensive consolidated documents: - knowledge-presenter-complete.md: Complete knowledge management system documentation - mcp-architecture.md: Unified MCP system architecture and implementation - tool-calling-system.md: Comprehensive tool calling and MCP integration guide - Improve documentation discoverability and reduce maintenance overhead
WalkthroughThis PR largely reorganizes documentation: removes numerous design/feature docs, adds new comprehensive guides for IPC architecture, Tool Calling, MCP architecture, and Knowledge Presenter, rewrites EventBus usage with precise routing APIs, and updates an MCP link in the developer guide. No code changes are shown. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Renderer Tab as Renderer (Tab)
participant EventBus as Main EventBus
participant Window as BrowserWindow
participant TargetTab as Target Renderer (Tab)
User->>Renderer Tab: trigger presenter action
Renderer Tab->>EventBus: send(event, target=tabId)
Note over EventBus: Route via sendToTab / sendToActiveTab / broadcastToTabs
EventBus->>Window: resolve active tab (optional)
EventBus->>TargetTab: deliver event(payload)
TargetTab-->>EventBus: ack/handle
sequenceDiagram
autonumber
participant User as User
participant Thread as Thread/Agent Loop
participant LLM as LLM Provider
participant MCP as MCP Presenter
participant Server as MCP Server
participant Tool as Tool Impl
User->>Thread: ask with tools enabled
Thread->>LLM: messages + tool definitions
LLM-->>Thread: tool_call (stream or final)
Thread->>MCP: callTool(toolName,args)
MCP->>Server: execute(tool,args)
Server->>Tool: run(args)
Tool-->>Server: result
Server-->>MCP: tool result
MCP-->>Thread: ToolCallResult
Thread->>LLM: provide tool result (continue)
LLM-->>Thread: final assistant message
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
- Delete outdated multi-window-architecture.md (feature already implemented) - Delete outdated performance_analysis_report.md (issues resolved) - Fix broken reference in developer-guide.md
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
docs/ipc/eventbus-usage.md (1)
169-173: Contradiction: enum comment recommends ALL_WINDOWS despite “精确路由优先”.The comment “（默认，推荐）” directly conflicts with this guide’s core principle. Recommend removing “推荐” and clarifying that broadcasts are exceptional.
enum SendTarget { - ALL_WINDOWS = 'all_windows', // 广播到所有窗口（默认，推荐） + ALL_WINDOWS = 'all_windows', // 广播到所有窗口（仅用于真正的全局事件） DEFAULT_TAB = 'default_tab' // 发送到默认标签页（特殊场景） }Optionally document what “DEFAULT_TAB” means and how it’s determined.
docs/developer-guide.md (3)
85-89: Update outdated MCP link to the new tool-calling docThis still references function-call-and-mcp.md, which the PR removes/supersedes. Point to tool-calling-system.md and keep the two MCP presenter docs if they remain.
-- [Function Call and MCP](./function-call-and-mcp.md) +- [Tool Calling System](./tool-calling-system.md) - [MCP Presenter Architecture](./mcp-presenter-architecture.md) - [MCP Presenter Design](./mcp-presenter-design.md)
127-136: Remove drafting notes from the published guideThis section is meta (author notes) and shouldn’t ship in user-facing docs.
-This guide should provide a good starting point for developers. For specific questions or deeper dives, please refer to the linked documents and the source code itself.The content for `docs/developer-guide.md` has been drafted. It covers: - - Project Structure: Based on `ls()` output and `CONTRIBUTING.md`. - - Architecture Overview: Explaining Electron's main/renderer architecture, the tech stack (Vue.js, TypeScript), and linking to relevant documents in `docs/` that I identified earlier. - - API Documentation: Pointing to `shared/presenter.d.ts` and `src/preload/index.d.ts`. -- Model Context Protocol (MCP): Explaining its purpose based on `README.md` and linking to `docs/tool-calling-system.md` and other MCP-specific architectural documents. - - Development Setup: Linking to the relevant sections in `README.md` and `CONTRIBUTING.md`. - - Building the Application: Linking to the relevant section in `README.md`. - - Contribution Guidelines: Linking to `CONTRIBUTING.md`. - -The paths for links to `README.md` sections are constructed assuming the `developer-guide.md` is in the `docs/` directory. For `CONTRIBUTING.md`, I've used a relative link `./CONTRIBUTING.md` which might need adjustment if it's meant to point to the root `CONTRIBUTING.md` (then it should be `../CONTRIBUTING.md`). I will use `../CONTRIBUTING.md` and `../README.md` for files in the root directory, and `./filename.md` for files within the `docs/` directory itself. I've updated the draft to reflect this. - -I will now create the file. +This guide should provide a good starting point for developers. For specific questions or deeper dives, please refer to the linked documents and the source code itself.
56-63: Update developer-guide.md links to remove dead referencesdocs/developer-guide.md (lines 56–63) currently lists several documents that no longer exist in
docs/. Please remove or update these entries to avoid broken links:• Missing files:
- docs/multi-window-architecture.md
- docs/event-system-design.md
- docs/config-presenter-design.md
- docs/mcp-presenter-architecture.md
- docs/mcp-presenter-design.md
• Existing docs you may wish to reference instead:
After cleaning up, your snippet might look like:
The `docs/` directory contains several documents that provide deeper insights into specific architectural aspects: - [Config Presenter Architecture](./config-presenter-architecture.md) - [Tool Calling System](./tool-calling-system.md) - [MCP Architecture](./mcp-architecture.md) It's recommended to review these documents for a comprehensive understanding of the application's design.Please apply these changes to ensure all links point to existing files.
🧹 Nitpick comments (31)
docs/ipc/optimization-recommendations.md (3)
39-54: Type context and parameter sourcing are unclear in examples.Show how
tabIdis obtained to avoid copy-paste misuse. Cross-link to the IPC doc that explainswebContentsId → tabId.-class ThreadPresenter { - handleStreamResponse(tabId: number, data: StreamData) { +// 由 renderer 传入 webContentsId，或在主进程通过 event.sender.id 解析 +class ThreadPresenter { + handleStreamResponse(tabId: number, data: StreamData) { eventBus.sendToTab(tabId, 'stream:data', data) } }Add: “参见《IPC 架构完整指南》中的 getTabIdByWebContentsId() 获取 tabId。”
93-110: Make the success criteria and metrics explicit for Phase 3.Define concrete KPIs so teams know when optimization “works.”
-### 阶段3: 性能监控 -- [ ] 添加IPC调用统计 -- [ ] 对比优化前后的性能差异 -- [ ] 建立持续监控机制 +### 阶段3: 性能监控（KPI） +- [ ] 采集指标：每秒IPC事件数、每事件平均payload字节、事件处理耗时P50/P95 +- [ ] 目标：非相关窗口收到的事件数下降 ≥ 80%；总IPC字节/分钟下降 ≥ 30% +- [ ] 仪表化：在 EventBus 的 send*/broadcast* 处打点（仅 DEV/诊断构建） +- [ ] 建立告警：单事件>256KB或>100ms 的长尾If useful, I can supply a minimal telemetry shim.
118-124: Minor wording nit.“Tool执行结果”→“工具执行结果”，与全文中文风格一致。
-// 优化Tool执行结果通知 +// 优化工具执行结果通知docs/ipc/ipc-architecture-complete.md (4)
18-36: Avoid hard-coded source line numbers; they rot quickly.Replace “:32/:159/:465...” with symbol references or code links. This reduces maintenance churn as code moves.
-- 位置: `src/main/presenter/tabPresenter.ts:32` +- 位置: `src/main/presenter/tabPresenter.ts`（见 `webContentsToTabId` 与 `getTabIdByWebContentsId`）Apply similarly to the other “位置” bullets here.
399-408: Add a caution about logging sensitive payloads.IPC logs can inadvertently include PII or secrets; call this out explicitly and recommend redaction in debug builds.
-# 在开发环境中启用详细的IPC调用日志 +# 在开发环境中启用详细的IPC调用日志（注意勿打印敏感数据）
441-446: Overconfident “100% 完成” claims will age badly.Soften wording to reflect current status without guaranteeing permanence.
-1. **Tab上下文识别**: 100%完成 -2. **精确事件路由**: 100%完成 +1. **Tab上下文识别**: 已全面可用 +2. **精确事件路由**: 已全面可用Apply similarly to items 3–5.
11-11: Chinese grammar polish.“提供了强大的显式事件发送方法”→“提供了功能强大的显式事件发送方法”更自然。
-提供了强大的显式事件发送方法 +提供了功能强大的显式事件发送方法docs/knowledge-presenter-complete.md (5)
176-191: Confirm the storage engine (“DuckDB 向量数据库”) and persist location.If DuckDB is indeed used, document the on-disk path, retention policy, and migration strategy; if not, reword to a provider-agnostic phrase.
-- 基于 DuckDB 的向量数据库 +- 基于本地向量数据库（当前实现：DuckDB；在未来可能替换/扩展） +- 数据文件位置：<配置项/默认路径>；支持备份/迁移说明
70-85: API naming consistency: prefer “reprocessFile” over “reAddFile”.“reAddFile”语义不清。与任务名/事件名统一，“reprocessFile(fileId)”更直观。相应更新接口与事件名。
-+reAddFile(fileId) ++reprocessFile(fileId)Repeat for IKnowledgePresenter/KnowledgePresenter sections and examples.
86-101: Global serial queue may throttle throughput; consider per-store concurrency.Document that tasks are executed serially per store while allowing limited cross-store concurrency (e.g., N=2) to avoid UI stalls on large imports.
--taskQueue: KnowledgeTask[] -+taskQueue: KnowledgeTask[] // 全局视图 -+concurrency: number // 每个 store 的并发上限（建议 1），全局并发上限（建议 2）Add a short “为什么”说明与背压/取消策略。
117-118: Fix nested list indentation to satisfy MD007.The nested bullets under “初始化流程/职责”等需要两空格缩进。
- - 创建知识库存储目录。 - - 监听配置变更事件，动态管理知识库实例。 + - 创建知识库存储目录。 + - 监听配置变更事件，动态管理知识库实例。Apply to other affected lists as needed.
202-209: Add a caution about PII and path handling in local files.Note that filenames and extracted text may include sensitive data; recommend scrubbing previews and avoiding path leakage to renderer logs.
1. **创建知识库**: ... +⚠️ 隐私提示：文件名/路径/内容可能包含敏感信息，日志与 UI 展示需做脱敏处理。docs/mcp-architecture.md (3)
237-248: Add a language hint to this fenced block to fix MD040 and improve readability.This is an ASCII flow; mark it as text.
-``` +```text User Input → LLM → Tool Call → Permission Check → [Permission Required] ...--- `344-346`: **Document auth for SSE/HTTP transports.** Add a sentence about using `customHeaders.Authorization` and avoiding logging tokens. ```diff - - `McpClient` 精细化处理 `stdio` 进程的环境变量 (PATH, 代理, npm registry) + - `McpClient` 精细化处理 `stdio` 环境变量（PATH/代理/npm registry），SSE/HTTP 使用 `customHeaders.Authorization` 传递令牌；避免在日志中输出敏感头
76-85: “npm registry 速度测试” needs a failure fallback.If speed test fails or is blocked, specify a default registry and a retry policy to avoid startup stalls.
Add a short “错误处理”小节：默认使用本地 npm 配置或官方 registry，并退避重试。
docs/ipc/eventbus-usage.md (4)
351-361: Keyboard shortcut examples should target only the active tab/window.Broadcasting may trigger duplicate navigations across windows.
- // 缩放需要所有窗口响应 - eventBus.send('shortcut:zoom-in', SendTarget.ALL_WINDOWS) + // 缩放：仅当前窗口的活跃 Tab + eventBus.sendToActiveTab(currentWindowId, 'shortcut:zoom-in')And for
shortcut:go-settings/clean-chat-history, prefersendToActiveTabunless truly global.
79-106: Clarify serialization constraints and import source of SendTarget.Add one line telling readers to only send serializable payloads and where to import
SendTargetfrom.-#### `sendToRenderer(eventName, target, ...args)` +#### `sendToRenderer(eventName, target, ...args)` +> 注意：payload 必须可序列化（避免 class 实例/循环引用）。`SendTarget` 从 `@/main/eventbus` 导入。
117-129: Add a link to the IPC architecture doc for tabId/windowId acquisition.Helps readers map concepts to code.
### 决策流程图 +参见《IPC 架构完整指南》中关于 `webContentsId → tabId/windowId` 的获取与注入。I can add deep links if you prefer.
365-381: Great performance guidance; add a size guard.Warn against sending large payloads; add a 256KB example threshold.
function notifyAllTabs(data: any) { - eventBus.sendToRenderer('data:updated', SendTarget.ALL_WINDOWS, data) + if (JSON.stringify(data).length > 256 * 1024) console.warn('payload too large') + eventBus.sendToRenderer('data:updated', SendTarget.ALL_WINDOWS, data) }docs/developer-guide.md (5)
34-34: Fix incorrect relative link to CONTRIBUTING.mdThis link points to docs/CONTRIBUTING.md, but CONTRIBUTING.md is typically at repo root. Update to ../CONTRIBUTING.md as your own note in Lines 136–137 suggests.
Apply:
-For more details, refer to the "Project Structure" section in [CONTRIBUTING.md](./CONTRIBUTING.md). +For more details, refer to the "Project Structure" section in [CONTRIBUTING.md](../CONTRIBUTING.md).
51-51: Avoid speculative wording; fix casing for shadcn/ui“are likely used” is speculative. Also, the project is styled “shadcn/ui” (lowercase).
-**Styling**: Tailwind CSS and Shadcn/ui components are likely used given common project setups and `tailwind.config.js`, `components.json`. +**Styling**: Tailwind CSS and shadcn/ui components (see `tailwind.config.js`, `components.json`).
74-74: Minor formatting: add a space before the acronymConsistency/readability.
-## Model Context Protocol (MCP) +## Model Context Protocol (MCP)(Note: If Markdown renderer already collapses it correctly, you can skip this.)
100-101: Prefer relative links for internal docsThese two GitHub absolute links can be relative to keep docs portable across forks/branches.
-- The "[Development Guide](https://github.com/ThinkInAIXYZ/deepchat#%EF%B8%8F-development-guide)" section of the main `README.md` file. -- The "[Local Development Setup](https://github.com/ThinkInAIXYZ/deepchat/blob/main/CONTRIBUTING.md#local-development-setup)" section of `CONTRIBUTING.md`. +- The "[Development Guide](../README.md#%EF%B8%8F-development-guide)" section of the main `README.md` file. +- The "[Local Development Setup](../CONTRIBUTING.md#local-development-setup)" section of `CONTRIBUTING.md`.
48-52: Use exact package naming for clarity
- Confirmed that
electron.vite.config.tsexists at the repository root.- The official package on npm is named electron-vite, so using the exact lowercase, hyphenated form avoids confusion.
- **Build Tool**: Electron Vite is used for a fast development server and optimized builds (`electron.vite.config.ts`). + **Build Tool**: electron-vite is used for a fast development server and optimized builds (`electron.vite.config.ts`).docs/tool-calling-system.md (7)
430-447: Add language identifier to fenced code block (markdownlint MD040)Specify a language for this code block. It’s prose; use “text”.
-``` +```text 你是一个有用的AI助手。当需要时，你可以使用以下工具帮助回答问题: function getTime(offset_ms: number): number 描述: 获取当前时间偏移后的毫秒数时间戳 参数: - offset_ms: 时间偏移量(毫秒) 使用工具时，请使用以下格式: <function_call> { "name": "getTime", "arguments": { "offset_ms": -86400000 } } </function_call>--- `451-462`: **Add language identifier to fenced code block (markdownlint MD040)** Same as above; use “text”. ```diff -``` +```text 我需要获取昨天的日期。我将调用getTime函数获取昨天的时间戳。 <function_call> { "name": "getTime", "arguments": { "offset_ms": -86400000 } } </function_call>--- `481-485`: **Add language identifier to fenced code block (markdownlint MD040)** Use “text”. ```diff -``` +```text 函数结果: 1684713600000 根据获取的时间戳，昨天是5月22日。--- `1-12`: **Consider adding an English version or language tag in filename** This doc is Chinese while the Developer Guide is English. To keep docs navigable: - Either add an English sibling (docs/tool-calling-system.en.md) or - Suffix this file as tool-calling-system.zh.md and link appropriately. If you decide to add an English variant, I can help draft it or generate a skeleton based on this file. --- `282-343`: **Terminology and API drift disclaimer** OpenAI/Anthropic/Gemini function/tool calling formats evolve. Add a short disclaimer at the start of each provider section noting versions/date and linking to official docs. Example addition near each provider heading: ```diff -### OpenAI API +### OpenAI API +注：以下内容基于截至 2025-08 的公开文档与本项目实现，具体字段可能随官方版本更新而变化，请以官方文档为准。
549-574: Clarify supported transports and scopeYou list stdio, SSE, HTTP, InMemory. If WebSocket/gRPC are future work (not implemented), move them to the “未来扩展方向” section only to avoid overpromising.
-- 支持多种传输协议（stdio, SSE, HTTP, InMemory） +- 当前支持多种传输协议（例如：stdio、SSE、HTTP、InMemory）；更多协议（如 WebSocket、gRPC）参见“未来扩展方向”。
76-82: Clarify implementation path for callTool
To improve discoverability, update the doc snippet to reference the actual file path ofmcpClient.ts.• Location:
docs/tool-calling-system.mdaround line 79Suggested change:
-通过 `mcpClient.ts` 的 `callTool` 方法实现跨提供商的工具调用： +通过 `src/main/presenter/mcpPresenter/mcpClient.ts` 中的 `callTool` 方法实现跨提供商的工具调用：
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (32)
docs/EXPORT_IMPLEMENTATION.md(0 hunks)docs/builtin-knowledge-architecture.md(0 hunks)docs/builtin-knowledge-design.md(0 hunks)docs/builtin-knowledge.md(0 hunks)docs/conversation-search-mcp.md(0 hunks)docs/data-sync-feature.md(0 hunks)docs/deepchat_tool_use_document.md(0 hunks)docs/developer-guide.md(1 hunks)docs/dialog-presenter.md(0 hunks)docs/event-system-design.md(0 hunks)docs/filesystem-enhancements.md(0 hunks)docs/function-call-and-mcp.md(0 hunks)docs/ipc/eventbus-refactor-summary.md(0 hunks)docs/ipc/eventbus-usage.md(3 hunks)docs/ipc/ipc-architecture-complete.md(1 hunks)docs/ipc/ipc-optimization-phase1-summary.md(0 hunks)docs/ipc/ipc-tab-context-test.md(0 hunks)docs/ipc/multi-tab-ipc-analysis.md(0 hunks)docs/ipc/multi-tab-ipc-optimization-plan.md(0 hunks)docs/ipc/optimization-recommendations.md(1 hunks)docs/knowledge-presenter-complete.md(1 hunks)docs/mcp-architecture.md(1 hunks)docs/mcp-permission-implementation-guide.md(0 hunks)docs/mcp-permission-system-design.md(0 hunks)docs/mcp-presenter-architecture.md(0 hunks)docs/mcp-presenter-design.md(0 hunks)docs/mcp-session-recovery.md(0 hunks)docs/multi-window-architecture.md(0 hunks)docs/performance_analysis_report.md(0 hunks)docs/start.md(0 hunks)docs/tool-calling-system.md(1 hunks)docs/usePageCapture.example.md(0 hunks)
💤 Files with no reviewable changes (25)
- docs/event-system-design.md
- docs/ipc/multi-tab-ipc-analysis.md
- docs/dialog-presenter.md
- docs/usePageCapture.example.md
- docs/mcp-presenter-architecture.md
- docs/ipc/multi-tab-ipc-optimization-plan.md
- docs/function-call-and-mcp.md
- docs/start.md
- docs/ipc/eventbus-refactor-summary.md
- docs/multi-window-architecture.md
- docs/deepchat_tool_use_document.md
- docs/builtin-knowledge-architecture.md
- docs/builtin-knowledge.md
- docs/ipc/ipc-tab-context-test.md
- docs/mcp-permission-system-design.md
- docs/EXPORT_IMPLEMENTATION.md
- docs/mcp-presenter-design.md
- docs/ipc/ipc-optimization-phase1-summary.md
- docs/mcp-permission-implementation-guide.md
- docs/filesystem-enhancements.md
- docs/performance_analysis_report.md
- docs/builtin-knowledge-design.md
- docs/mcp-session-recovery.md
- docs/data-sync-feature.md
- docs/conversation-search-mcp.md
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-07-21T01:45:54.229Z
Learnt from: CR
PR: ThinkInAIXYZ/deepchat#0
File: .cursor/rules/electron-best-practices.mdc:0-0
Timestamp: 2025-07-21T01:45:54.229Z
Learning: Applies to src/{main,renderer}/**/*.ts : Implement proper inter-process communication (IPC) patterns
Applied to files:
docs/ipc/ipc-architecture-complete.md
📚 Learning: 2025-07-21T01:45:33.790Z
Learnt from: CR
PR: ThinkInAIXYZ/deepchat#0
File: CLAUDE.md:0-0
Timestamp: 2025-07-21T01:45:33.790Z
Learning: Applies to src/main/**/*.ts : Main to Renderer: Use EventBus to broadcast events via mainWindow.webContents.send()
Applied to files:
docs/ipc/eventbus-usage.md
📚 Learning: 2025-07-21T01:45:54.229Z
Learnt from: CR
PR: ThinkInAIXYZ/deepchat#0
File: .cursor/rules/electron-best-practices.mdc:0-0
Timestamp: 2025-07-21T01:45:54.229Z
Learning: Applies to src/main/eventbus.ts : eventbus.ts is primarily used for intercommunication between main processes and decouples modules with events
Applied to files:
docs/ipc/eventbus-usage.md
📚 Learning: 2025-07-21T01:45:54.229Z
Learnt from: CR
PR: ThinkInAIXYZ/deepchat#0
File: .cursor/rules/electron-best-practices.mdc:0-0
Timestamp: 2025-07-21T01:45:54.229Z
Learning: Applies to src/main/presenter/index.ts : The IPC messages from the main process to notify the view mainly rely on the EventBus index.ts to listen for events that need to be notified and then send them to the renderer through the mainWindow
Applied to files:
docs/ipc/eventbus-usage.md
📚 Learning: 2025-07-21T01:46:52.880Z
Learnt from: CR
PR: ThinkInAIXYZ/deepchat#0
File: .cursor/rules/llm-agent-loop.mdc:0-0
Timestamp: 2025-07-21T01:46:52.880Z
Learning: Applies to src/main/presenter/llmProviderPresenter/index.ts : The main Agent loop should send standardized `STREAM_EVENTS` (`RESPONSE`, `END`, `ERROR`) to the frontend via `eventBus`.
Applied to files:
docs/ipc/eventbus-usage.md
🪛 markdownlint-cli2 (0.17.2)
docs/tool-calling-system.md
430-430: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
451-451: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
481-481: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/knowledge-presenter-complete.md
117-117: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
118-118: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
docs/mcp-architecture.md
237-237: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/ipc/eventbus-usage.md
17-17: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
40-40: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
69-69: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
90-90: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
105-105: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
🪛 LanguageTool
docs/ipc/ipc-architecture-complete.md
[uncategorized] ~11-~11: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：强大"地"显
Context: ...程和渲染进程之间的精确事件传递。基于 EventEmitter 构建，提供了强大的显式事件发送方法和Tab级别的精确路由功能。 ### 已实现的核心功能 ✅ ...
(wb4)
[uncategorized] ~457-~457: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：好"地"调试
Context: ...性能监控**: 添加IPC调用统计和性能监控 3. 开发体验: 提供更好的调试工具 ## 🎉 结论 DeepChat的IPC架构已经非常成熟和完善，...
(wb4)
docs/knowledge-presenter-complete.md
[uncategorized] ~220-~220: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：常用"地"检索
Context: ...- 增量处理: 只处理新增或修改的文件 - 缓存机制: 缓存常用的检索结果 - 异步处理: 所有耗时操作都在后台执行 - 资源管理...
(wb4)
docs/mcp-architecture.md
[uncategorized] ~447-~447: 动词的修饰一般为‘形容词（副词）+地+动词’。您的意思是否是：新"地"连接
Context: ...用者知道需要重试 5. 重新调用: 上层调用者重新发起请求，此时会建立新的连接和 session 6. 持续错误检测: 如果重启后再次出现 ses...
(wb4)
🔇 Additional comments (4)
docs/ipc/optimization-recommendations.md (1)
5-5: Back up the “28 files” claim with a reproducible search command or list.Provide either an appendix listing the files or a grep command so readers can validate and track progress.
You can add a short “How to audit” snippet:
+### 审计方法 +```bash +grep -nr "SendTarget\.ALL_WINDOWS" src/ | sort -V +``` +```docs/ipc/ipc-architecture-complete.md (1)
74-86: Verify method signatures match the actual EventBus implementation.Particularly the parameter order for
sendToWindow(eventName, windowId, ...)andsend(...)vssendToRenderer(...). Misdocumented order will cause runtime bugs.Please run a quick check and update if needed. I can script-verify against src/main/eventbus.ts upon request.
docs/ipc/eventbus-usage.md (1)
283-299: Error routing example should avoid broadcasting and send normalized payloads.Align with best practices you advocate elsewhere.
-// ❌ 广播错误到所有Tab -handleError(error: Error) { - eventBus.sendToRenderer('error:occurred', SendTarget.ALL_WINDOWS, error) -} +// ❌ 避免广播错误 +handleError(tabId: number, error: unknown) { + const safe = { message: String((error as any)?.message ?? error), type: 'STREAM_ERROR' } + eventBus.sendToTab(tabId, 'error:display', safe) +}⛔ Skipped due to learnings
Learnt from: CR PR: ThinkInAIXYZ/deepchat#0 File: .cursor/rules/error-logging.mdc:0-0 Timestamp: 2025-07-21T01:46:19.702Z Learning: Applies to **/*.{ts,tsx} : 不要吞掉错误Learnt from: CR PR: ThinkInAIXYZ/deepchat#0 File: .cursor/rules/error-logging.mdc:0-0 Timestamp: 2025-07-21T01:46:19.702Z Learning: Applies to **/*.{ts,tsx} : 提供用户友好的错误信息Learnt from: CR PR: ThinkInAIXYZ/deepchat#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-21T01:45:33.790Z Learning: Applies to src/main/**/*.ts : Main to Renderer: Use EventBus to broadcast events via mainWindow.webContents.send()docs/developer-guide.md (1)
109-112: External link stability verified: Mac Release Guide reachableThe referenced wiki page returns HTTP 200, confirming that the Mac Release Guide URL remains valid after the docs reorganization. No updates to this link are required.
| // 优化Tool执行结果通知 | ||
| class McpPresenter { | ||
| async executeTool(tabId: number, toolName: string, args: any) { | ||
| try { | ||
| const result = await this.callTool(toolName, args) | ||
|
|
||
| // 只通知调用方Tab | ||
| eventBus.sendToTab(tabId, 'mcp:tool-result', { toolName, result }) | ||
|
|
||
| } catch (error) { | ||
| // 错误也只通知调用方 | ||
| eventBus.sendToTab(tabId, 'mcp:tool-error', { toolName, error }) | ||
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Do not send native Error objects across IPC; normalize first.
Electron serializes errors poorly and leaking stack traces across tabs is undesirable. Send a safe payload.
- eventBus.sendToTab(tabId, 'mcp:tool-error', { toolName, error })
+ eventBus.sendToTab(tabId, 'mcp:tool-error', {
+ toolName,
+ error: { message: String(error?.message ?? error), code: 'TOOL_ERROR' }
+ })Mirror the same pattern in the other examples that emit errors.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // 优化Tool执行结果通知 | |
| class McpPresenter { | |
| async executeTool(tabId: number, toolName: string, args: any) { | |
| try { | |
| const result = await this.callTool(toolName, args) | |
| // 只通知调用方Tab | |
| eventBus.sendToTab(tabId, 'mcp:tool-result', { toolName, result }) | |
| } catch (error) { | |
| // 错误也只通知调用方 | |
| eventBus.sendToTab(tabId, 'mcp:tool-error', { toolName, error }) | |
| } | |
| } | |
| } | |
| ``` | |
| // 优化Tool执行结果通知 | |
| class McpPresenter { | |
| async executeTool(tabId: number, toolName: string, args: any) { | |
| try { | |
| const result = await this.callTool(toolName, args) | |
| // 只通知调用方Tab | |
| eventBus.sendToTab(tabId, 'mcp:tool-result', { toolName, result }) | |
| } catch (error) { | |
| // 错误也只通知调用方 | |
| eventBus.sendToTab(tabId, 'mcp:tool-error', { | |
| toolName, | |
| error: { message: String(error?.message ?? error), code: 'TOOL_ERROR' } | |
| }) | |
| } | |
| } | |
| } |
🤖 Prompt for AI Agents
In docs/ipc/optimization-recommendations.md around lines 76 to 91, the code
sends native Error objects across IPC which is unsafe and poorly serialized;
replace the direct error with a normalized, JSON-serializable payload (e.g. {
name: error.name, message: error.message, code: error.code ?? null, context:
optionalSafeInfo }) and omit or redact the full stack to avoid leaking
internals; update the catch branch to build and send that safe object and apply
the same normalization pattern to any other examples in this document that emit
errors.
| ### 权限类型 | ||
|
|
||
| #### Read Permissions | ||
| 用于只读数据的工具： | ||
| - `list_directory` | ||
| - `read_file` | ||
| - `get_information` | ||
|
|
||
| #### Write Permissions | ||
| 用于修改数据的工具： | ||
| - `write_file` | ||
| - `create_directory` | ||
| - `delete_file` | ||
| - `execute_command` | ||
|
|
||
| #### All Permissions | ||
| 授予读写访问权限给服务器。 |
There was a problem hiding this comment.
Elevate security guidance around powerful tools (execute_command/delete_file).
Call out that such tools should be disabled by default, require per-server allowlists, and are session-scoped at minimum.
-#### Write Permissions
+#### Write Permissions（高风险，默认禁用）
...
-- `execute_command`
+- `execute_command`（仅在明确允许时启用，建议强制二次确认）Also note headers/tokens hygiene for SSE/HTTP transports in the “多协议支持/安全考虑” sections.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 权限类型 | |
| #### Read Permissions | |
| 用于只读数据的工具： | |
| - `list_directory` | |
| - `read_file` | |
| - `get_information` | |
| #### Write Permissions | |
| 用于修改数据的工具： | |
| - `write_file` | |
| - `create_directory` | |
| - `delete_file` | |
| - `execute_command` | |
| #### All Permissions | |
| 授予读写访问权限给服务器。 | |
| ### 权限类型 | |
| #### Read Permissions | |
| 用于只读数据的工具： | |
| - `list_directory` | |
| - `read_file` | |
| - `get_information` | |
| #### Write Permissions（高风险，默认禁用） | |
| 用于修改数据的工具： | |
| - `write_file` | |
| - `create_directory` | |
| - `delete_file` | |
| - `execute_command`（仅在明确允许时启用，建议强制二次确认） | |
| #### All Permissions | |
| 授予读写访问权限给服务器。 |
| 所有 LLM 提供商都转换为统一的 `LLMCoreStreamEvent` 事件： | ||
|
|
||
| ```typescript | ||
| { | ||
| type: 'tool_call_start' | 'tool_call_chunk' | 'tool_call_end' | 'content_chunk'; | ||
| tool_call_id?: string; | ||
| tool_call_name?: string; | ||
| tool_call_arguments_chunk?: string; | ||
| tool_call_arguments_complete?: string; | ||
| content?: string; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Check event interface parity with implementation
Ensure LLMCoreStreamEvent matches the actual emitted event shape (names, optional fields).
🏁 Script executed:
#!/bin/bash
# Verify the interface or type alias exists and matches fields
rg -nP --type=ts '\bLLMCoreStreamEvent\b' -C3
rg -nP --type=ts "type:\s*'tool_call_start'|'tool_call_chunk'|'tool_call_end'|'content_chunk'" -C2Length of output: 64121
Align documentation with the actual LLMCoreStreamEvent interface
The snippet in docs/tool-calling-system.md (lines 506–517) currently defines only:
{
type: 'tool_call_start' | 'tool_call_chunk' | 'tool_call_end' | 'content_chunk';
tool_call_id?: string;
tool_call_name?: string;
tool_call_arguments_chunk?: string;
tool_call_arguments_complete?: string;
content?: string;
}but the real LLMCoreStreamEvent in src/shared/presenter.d.ts exports:
export interface LLMCoreStreamEvent {
type:
| 'text'
| 'reasoning'
| 'tool_call_start'
| 'tool_call_chunk'
| 'tool_call_end'
| 'error'
| 'usage';
content?: string;
tool_call_id?: string;
tool_call_name?: string;
tool_call_arguments_chunk?: string;
tool_call_arguments_complete?: string;
// …plus other fields like stop_reason, error details, usage stats, etc.
}Key mismatches to fix:
- Replace the limited type union in the docs with the full set of event types (
'text' | 'reasoning' | 'tool_call_start' | 'tool_call_chunk' | 'tool_call_end' | 'error' | 'usage') as defined in src/shared/presenter.d.ts. - Remove or rename the unsupported
'content_chunk'type—use the actual'text'and (if needed)'reasoning'types instead. - Document any additional optional fields (e.g.
stop_reason, error/usage payloads) that the interface exposes.
Please update docs/tool-calling-system.md to exactly mirror the LLMCoreStreamEvent interface shape so that readers see an accurate, up-to-date event schema.
optimize and remove outdated docs
Summary by CodeRabbit