mirror of
https://github.com/tiddly-gittly/TidGi-Desktop.git
synced 2025-12-06 02:30:47 -08:00
Feat/Native AI Agent (#640)
* refactor: only use message id * feat: stream update, but react don't react on it dny * feat: start stop * feat: basic resoponse handlers * feat: load handler config schema * chore: upgrade to "moduleResolution": "bundler" * fix: prompt concat * feat: rjfs with mui * fix: mui v7 upgrade * fix: field editor tabs * feat: Description field is i18n key, use i18nAlly extension to see it on VSCode. And use react-i18next to translate it on frontend. * refactor: extract some shared components * refactor: remove @mui/lab * feat: faster editor * feat: beautify editor * refactor: better style * fix: fullscreen style * fix: array sort * fix: editor not saved * fix: broken array * chore: upgrade mui deps * Update type.d.ts * feat: upgrade and install react dev tools * refactor: simplify the code * refactor: simplify the code * refactor: simplify ai generated garbage code * fix: translated label * feat: translate enum and conditional show field based on enum * feat: click to open source * fix: ai generated garbage code to solve id and index problem * refactor: simplify * refactor: shorten * test: add jest * chore: node-linker=hoisted as electron forge suggested * test: e2e * fix: test failed on ci * test: faster by disable some typecheck * fix: ci * fix: ci * refactor: remove unused * fix: use macos and take screenshot in ci * docs: (cherry picked from commitb1a9706264) * fix: ci crash due to no dugite binary, due to NODE_ENV=test not set * Update test.yml * fix: ci * Update release.yml * docs: test * refactor: move folders and lint * refactor: organize pages to reduce level * refactor: merge page service and workspace service to allow drag & drop of pages * Update ipc-syncadaptor.ts * Update browserViewMetaData.ts * fix: view.webContents.loadURL won't reload on new electron version * fix: try to disable annoying useless disabling pasting "feature" https://github.com/electron/electron/issues/40995 * fix: initial page * feat: allow sort add icon * test: use vitest instead * refactor: use emotion instead * fix: all ts error after migrate to vitest and emotion * fix: Component selectors can only be used in conjunction with @emotion/babel-plugin, the swc Emotion plugin, or another Emotion-aware compiler transform. fix by not using this usage * fix: too many open files * test: add basic main page test * refactor: split workspace type to make it more specific * test: support mock react lazy import component by re-export them * test: sidebar * refactor: move mock to global * test: testing library fix * test: new wiki form * docs: test with vitest * lint: fix * docs: pronounication & remove toc as gh build in * feat: tools and rag * feat: prompt for build-in tools * fix: i18n * fix: tool using * test: fix * refactor: Auto-create default wiki workspace if none exists (handled in backend) * fix: create wiki workspace so it is on first one * refactor: remove some useless feature * refactor: use plugin instead of handler * chore: make concatPrompt async iterator * feat: show progress on frontend * fix: errors * fix: ConfigError: Config (unnamed): Key "overrides": This appears to be in eslintrc format rather than flat config format. * Update package.json * feat: allow windows to hide titlebar * fix: logger error when ctrl+c on mac * lint * refactor: use plugin everywhere * refactor: move more logic to plugin * refactor: run tool in plugin, simplify abstraction * refactor: remove ai generated duplicate * refactor * refactor: less plugins * test: simplify wiki search test * test: remove any * fix: not streaming, tool order wrong * test: plugin system and streaming * refactor: remove useless auto reply plugin * fix: hide duration expired tool calling message, so long tool result only show to ai once * fix: $ props should lower cased * test: support run as electron so can use sqlite3 compiled bin for electron * docs: better electron as node run and doc * test: restore to use threads instead of fock. Seems this also works for inmemory database * test: fix frontend ui test * lint: ai content * test: fix coverage * test: Refactor test mocks to dedicated __mocks__ directory Moved common test mocks from setup-vitest.ts into separate files under src/__tests__/__mocks__ for better organization and maintainability. Updated documentation to reflect the new structure. Removed fileMock.js and updated setup-vitest.ts to import and use the new centralized mocks. * Update ErrorDuringStart.md * Update messageManagementPlugin.test.ts * test: Fix Electron test process cleanup and update test config Update test:unit script to use cross-env for ELECTRON_RUN_AS_NODE, ensuring child processes inherit the variable and preventing resource leaks. Remove manual process.env setting from vitest.config.ts and add documentation on handling related errors in Testing.md. Also, add 'hanging-process' reporter to Vitest config for improved diagnostics. * fix: warning in test * Create AgentInstanceWorkflow.md * fix: duration bug * fix: ai not response for tool result * test: Add agent workflow feature and step definitions Introduces a new Cucumber feature for agent workflow, including multi-round conversation and tool usage. Adds agent-specific step definitions for message input and chat history validation. Refactors application step definitions for improved selector handling and element interaction. Updates test scripts in package.json to include a preparation step for e2e tests. * Update application.ts * test: Add mock OpenAI server and tests Introduces a MockOpenAIServer for simulating OpenAI chat completions, including tool call and tool result responses. Adds corresponding tests and updates vitest config to include tests in the features directory. * test: simplify steps * test: Add separate test userData and wiki folders Introduces 'userData-test' and 'wiki-test' folders for test environments, updating appPaths, fileNames, and paths constants to distinguish between development and test modes. This helps prevent conflicts when running test and development instances simultaneously. * Update eslint.config.mjs @typescript-eslint/no-unnecessary-condition': 'off' * test: Add data-testid attributes for test automation Added data-testid attributes to form inputs and buttons in ExternalAPI components to improve test automation reliability. Updated feature files and step definitions to use these selectors, refined window switching logic, and improved timing for UI interactions. Also exposed isElectronDevelopment and added isMainWindowPage utility for window identification. * test: fix wront page type by ai written garbage code * Update application.ts * Update Testing.md * fix: no log during e2e test, and error creating wiki blocks other init steps * test: click agent workspace button, and refactor mock server * test: mock streamable openai api * rename * chore: try esbuild loader, renderer build too slow * chore: organize webpack * chore: ignore service code from hot reload * Update Testing.md * test: use full agentinstance in test * chore: webpack error * Update Testing.md * chore: remove useless spectron * test: EsbuildPlugin's `define` doesn't work, it won't set env properly. * test: e2e mock openai * lint: disable @typescript-eslint/require-await * test: Add quick access to create default agent tab Introduces a 'Create Default Agent' quick access button in the Agent New Tab page, with localization support. Adds utility to close all tabs and create a default agent tab for fallback scenarios, improves test selectors for tab and close actions, and refactors agent chat tab creation logic for consistency and testability. * feat: remove unuse favorite * feat: Add wiki operation and workspaces list plugins Introduces wikiOperationPlugin and workspacesListPlugin for agent instance prompt and response handling. Updates plugin registry, test coverage, and default agent configuration to support wiki workspace listing and wiki note operations (create, update, delete) via tool calls. Refactors wikiSearchPlugin to delegate workspace list injection to workspacesListPlugin. * Refactor plugin schema system for dynamic registration Introduces a dynamic plugin schema registry, allowing plugins to register their parameter schemas and metadata at runtime. Refactors prompt concat schema generation to use dynamically registered plugin schemas, removes static plugin schema definitions, and updates all plugin files to export their parameter schemas. Adds new modelContextProtocolPlugin and schemaRegistry modules, and updates plugin initialization to register schemas and metadata. This enables extensibility and type safety for plugin configuration and validation. * refactor: move PromptConfigForm to inside PromptPreviewDialog * test: frontent render tool usage info * test: split file * test: fix error * test: wiki operation * test: remove log and clean up test deps * Update i18next-electron-fs-backend.ts * fix: wikiOperationInServer not called due to no message * test: fix * test: Refactor agent feature setup and improve mock server URL handling Moved AI provider and model configuration to a shared setup scenario in agent.feature to avoid redundant steps in each test. Enhanced application.ts to use a fallback localhost URL for MOCK_SERVER_URL when the mock server is not available, improving test reliability. * Remove retry logic from basicPromptConcatHandler Eliminated retryCount and maxRetries from basicPromptConcatHandler, simplifying the control flow and removing the retry limit for LLM calls. Logging and yield logic were updated to reflect the removal of retries. * Update agent.feature * test: agent and default wiki * test: refactor wiki cleanup * Update agent.feature * Refactor AI settings setup and add preference feature Moved AI provider and model configuration steps from agent.feature to a new preference.feature file for better separation of concerns. Updated step definitions in agent.ts to improve robustness when reading and writing settings files, including type usage and directory checks. * test: try debug can't stop bug * Update Testing.md * fix: cancel agent not update cancel button * refactor: update Frontend use `void window.service.native.log` to log to file. * test: log from renderer test * feat: add default embedding model config and victor search service and search preference panel * test: default embedding form and * test: default agent * refator: unused tool listing methods * Refactor test database setup for integration tests Centralizes in-memory SQLite test database initialization and cleanup in shared utilities for all integration tests. Updates agentDefinition and messageManagementPlugin tests to use the shared test database, improving reliability and reducing code duplication. * fix: app path wrong in unit test * feat: externalAPIDebug * test: embedding service and let db use real in memory one * test: provide at least one tab for close tab test * fix: victor db not loaded in new connection * test: disable hot reload * Update DeveloperTools.tsx * feat: tool message & wiki tool schema * feat: pref to open db * chore: skip ExternalsPlugin on dev * fix: APIs doesn't accept 'tool' role, and it won't return anything when API calls * fix: docs and remove ai fake fix * refactor: get agent list don't need to have message * Update basicPromptConcatHandler.failure.test.ts * Update basicPromptConcatHandler.test.ts * fix: role wrong cause e2e failed * test: allow e2e create .db file to check * feat: create new agent * feat: getAgentDefinitionTemplatesFromWikis * fix: Prevent update non-active (hiding) wiki workspace, so it won't pop up to cover other active agent workspace * fix: Ensure the config change is fully persisted before proceeding * test: Don't bring up window when running e2e test, otherwise it will annoy the developer who is doing other things. * feat: Edit existing agent definition workflow * Update StyledArrayContainer.tsx * test: prevent mock server hang * Refactor UI step definitions into separate file Moved UI-related Cucumber step definitions from application.ts to a new ui.ts file for better separation of concerns and maintainability. application.ts now only contains application-specific logic. * lint: ai auto fix * Clean up feature files and improve test coverage Removed unnecessary blank lines and improved formatting in feature files for better readability. Updated tsconfig to use 'bundler' module resolution. Enhanced EditAgentDefinitionContent test to mock and verify console.error output. Added type annotation for IAgentDefinitionService in basicPromptConcatHandler.failure.test.ts for improved type safety. * test: simplify message text match * feat: transcription and image generation model config * fix: style props error * chore: remove unused file * chore: try to imporove dev start speed but no sig improvment Replaces 'pnpm start' with 'pnpm start:init' for initial setup and documents slow startup in development. Adds a debug Webpack script, disables polling in renderer file watching, and only enables CircularDependencyPlugin in production/CI for faster dev builds. WebpackBar now only shows when DEBUG includes 'electron-forge:*'. ForkTsCheckerWebpackPlugin is now configured for async checks with memory limits and test file exclusion. Updates documentation to reflect these changes. * docs: why not vite * refactor: basic vite usage, but wiki worker is not running and view is not showing * refactor: remove lazy inject so vite works and wiki worker works, wiki in browser view can loads * Replace electron-squirrel-startup with inline implementation Added a custom Squirrel event handler in src/helpers/squirrelStartup.ts to handle Windows install/update/uninstall events, replacing the electron-squirrel-startup package. This avoids ESM/CommonJS compatibility issues and simplifies event handling in src/main.ts. * refactor: vite build and test * fix: e2e still use dev wiki folder * fix: provide env * chore: "tiddlywiki": "5.3.7" * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix: missing i18n * test: Module did not self-register: '/home/runner/work/TidGi-Desktop/TidGi-Desktop/node_modules/better-sqlite3/build/Release/better_sqlite3.node'. * feat: i18n * feat: zh-Hant i18n * Update test.yml * feat: zh-Hans in test * test: i18n * refactor: ts forge config * lint: fix * chore: update wiki * Update pnpm-lock.yaml * chore: update github action versions * Update wiki * fix: pnpm then node * fix: Multiple versions of pnpm specified * Update test.yml * fix: Failed to take screenshot: page.screenshot: Target page, context or browser has been closed * chore: CodeQL Action major versions v1 and v2 have been deprecated. * chore: parallel codeql * Update test.yml * fix: i18n test not passing * test: step screenshot in each folder * fix: can't unzip, may due to file path * test: increase timeout in CI * docs: more log about wiki creation, and add log to criticial path * Refactor: logging for structured and consistent output Replaces string-based logger messages with structured logging throughout the codebase, providing function names, error messages, and relevant context as objects. This improves log readability, enables better filtering and searching, and standardizes error and debug reporting across services. * chore: debug wiki copy * fix: wiki submodule not cloned * Revert "test: increase timeout in CI" This reverts commiteff8583a01. * test: reduce wait time, because most check already will wait for a while * test: batch some e2e steps to reduce screenshot count * Update index.ts * chore: remove webpack files, use vite plugins --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
lin onetwo
GitHub
parent
a39023627d
commit
fa9751e5ea
533 changed files with 53202 additions and 11006 deletions
171
docs/features/AgentInstanceWorkflow.md
Normal file
171
docs/features/AgentInstanceWorkflow.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
# AgentInstance and the plugin-based workflow
|
||||
|
||||
This document explains how an agentInstance invokes a handler and how logic is composed via plugins to enable strategy-like processing. It covers message persistence, streaming updates, tool calling, and second-round handoff.
|
||||
|
||||
## Overview
|
||||
|
||||
- Entry: `IAgentInstanceService.sendMsgToAgent` receives user input.
|
||||
- Orchestrator: `basicPromptConcatHandler` drives prompt concatenation, AI calls, and plugin hooks.
|
||||
- Plugins: `createHooksWithPlugins` attaches plugins to unified hooks with shared context, enabling decoupled, replaceable strategies.
|
||||
- Data: message model `AgentInstanceMessage`, status model `AgentInstanceLatestStatus`.
|
||||
|
||||
### Handler selection and registration
|
||||
|
||||
- Source of handlerID: prefer the instance’s handlerID, fallback to the agent definition’s handlerID (see `src/pages/Agent/store/agentChatStore/actions/agentActions.ts#getHandlerId` and the preferences hook `useHandlerConfigManagement.ts`).
|
||||
- Backend registration: in `AgentInstanceService.initialize()`, `registerBuiltinHandlers()` registers `basicPromptConcatHandler` under the ID `basicPromptConcatHandler`; `initializePluginSystem()` registers built-in plugins.
|
||||
- Runtime selection: inside `sendMsgToAgent()`, the handler is fetched from `this.agentHandlers` by agentDef.handlerID and started as an async generator `const generator = handler(handlerContext)`, then iterated with `for await (const result of generator)`.
|
||||
|
||||
Related code:
|
||||
|
||||
- [index.ts](../../src/services/agentInstance/index.ts): `initialize()`, `registerBuiltinHandlers()`, `sendMsgToAgent()`
|
||||
- [basicPromptConcatHandler.ts](../../src/services/agentInstance/buildInAgentHandlers/basicPromptConcatHandler.ts)
|
||||
|
||||
## Sequence
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant User as User
|
||||
participant AISvc as IAgentInstanceService
|
||||
participant Handler as basicPromptConcatHandler
|
||||
participant Hooks as Plugins(Hooks)
|
||||
participant API as External API
|
||||
|
||||
User->>AISvc: sendMsgToAgent(text,file)
|
||||
AISvc-->>Handler: append to agent.messages
|
||||
Handler->>Hooks: userMessageReceived
|
||||
Hooks-->>AISvc: saveUserMessage / debounceUpdateMessage
|
||||
Handler->>Hooks: agentStatusChanged(working)
|
||||
loop generation and streaming updates
|
||||
Handler->>AISvc: concatPrompt(handlerConfig, messages)
|
||||
AISvc-->>Handler: flatPrompts
|
||||
Handler->>API: generateFromAI(flatPrompts)
|
||||
API-->>Handler: update(content)
|
||||
Handler->>Hooks: responseUpdate(update)
|
||||
Hooks-->>AISvc: debounceUpdateMessage
|
||||
end
|
||||
API-->>Handler: done(final content)
|
||||
Handler->>Hooks: responseComplete(done)
|
||||
alt plugin requests next round
|
||||
Hooks-->>Handler: actions.yieldNextRoundTo = self
|
||||
Handler->>Handler: append messages and continue flow
|
||||
else return to user
|
||||
Handler-->>AISvc: completed(final)
|
||||
end
|
||||
```
|
||||
|
||||
## Key design points
|
||||
|
||||
### 1. Event-driven strategy composition
|
||||
|
||||
– `createHooksWithPlugins` exposes unified hooks: `processPrompts`, `userMessageReceived`, `agentStatusChanged`, `responseUpdate`, `responseComplete`, `toolExecuted`.
|
||||
– Plugins subscribe as needed and compose different strategies without changing the main flow.
|
||||
|
||||
Plugin registration and wiring:
|
||||
|
||||
- At app init, `initializePluginSystem()` registers built-in plugins to a global registry.
|
||||
- For each round, `createHooksWithPlugins(handlerConfig)` creates a fresh hooks instance and attaches plugins per config.
|
||||
- `responseConcat()` and `promptConcat` also look up `builtInPlugins` and run plugin logic (e.g., `postProcess`) with a dedicated context.
|
||||
|
||||
Stateless plugins requirement:
|
||||
|
||||
- Plugins must be stateless. Do not persist cross-round or cross-session state inside closures.
|
||||
- All state must travel through `context` (e.g., `handlerContext.agent.messages`, `metadata`).
|
||||
- Plugins may be registered to multiple hooks across conversations and then discarded; internal mutable state risks races and contamination.
|
||||
|
||||
### 2. Messages as the source of truth
|
||||
|
||||
– User, assistant, and tool result messages are all `AgentInstanceMessage`.
|
||||
– `duration` limits how many subsequent rounds include a message in context.
|
||||
– UI and persistence coordinate via `saveUserMessage` and `debounceUpdateMessage`.
|
||||
|
||||
Persistence and UI updates:
|
||||
|
||||
– User messages: `messageManagementPlugin.userMessageReceived` persists via `IAgentInstanceService.saveUserMessage`, pushes into `handlerContext.agent.messages`, and calls `debounceUpdateMessage` to notify UI.
|
||||
– Streaming updates: `responseUpdate` maintains an in-progress assistant message (`metadata.isComplete=false`) with debounced UI updates.
|
||||
– Finalization: `responseComplete` persists the final assistant message and updates UI once more.
|
||||
– Tool results: `toolExecuted` persists messages with `metadata.isToolResult` and sets `metadata.isPersisted` to avoid duplicates.
|
||||
|
||||
### 3. Second-round handoff and control
|
||||
|
||||
– Plugins may set `actions.yieldNextRoundTo = 'self'` in `responseComplete` to trigger another LLM round immediately.
|
||||
– The handler stops after reaching retry limits and returns the final result.
|
||||
|
||||
concatPrompt and prompt delivery:
|
||||
|
||||
– `AgentInstanceService.concatPrompt` exposes an observable stream for prompt assembly. The handler uses `getFinalPromptResult` to obtain final prompts before calling the external API.
|
||||
|
||||
## Example plugins
|
||||
|
||||
### messageManagementPlugin
|
||||
|
||||
Responsibilities:
|
||||
|
||||
– Persist user messages in `userMessageReceived` and sync UI.
|
||||
– Manage streaming assistant message in `responseUpdate`; persist final content in `responseComplete`.
|
||||
– Update status in `agentStatusChanged`.
|
||||
– Persist tool results in `toolExecuted` and mark as persisted.
|
||||
|
||||
Notes:
|
||||
|
||||
– Update `handlerContext.agent.messages` in place for immediate UI rendering.
|
||||
– Use debounced updates to reduce re-renders.
|
||||
– Mark streaming messages with `metadata.isComplete`.
|
||||
|
||||
### wikiSearchPlugin
|
||||
|
||||
Responsibilities:
|
||||
|
||||
– Inject available wiki workspaces and tool list in `processPrompts`.
|
||||
– On `responseComplete`, detect tool calls, execute, produce `isToolResult` message with `duration=1`.
|
||||
– Set `actions.yieldNextRoundTo = 'self'` to continue immediately with tool outputs.
|
||||
|
||||
Notes:
|
||||
|
||||
– Validate parameters with zod.
|
||||
– Use messages as the carrier for tool I/O.
|
||||
– Set `duration=1` for tool-call assistant messages to economize context.
|
||||
|
||||
Tool calling details:
|
||||
|
||||
– Parse: detect tool-call patterns via `matchToolCalling` in `responseComplete`.
|
||||
– Validate & execute: validate with zod, then `executeWikiSearchTool` uses workspace and wiki services to fetch results.
|
||||
– History: create an `isToolResult` message (`role: 'user'`, `duration=1`) for the next round; report via `hooks.toolExecuted.promise(...)` so messageManagementPlugin persists and notifies UI.
|
||||
– Loop: set `actions.yieldNextRoundTo='self'` to continue another round using tool outputs.
|
||||
|
||||
## Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User input] --> B[sendMsgToAgent]
|
||||
B --> C[Message enqueued to agent.messages]
|
||||
C --> D[userMessageReceived persist + UI]
|
||||
D --> E[agentStatusChanged = working]
|
||||
E --> F[concatPrompt generate prompts]
|
||||
F --> G[generateFromAI streaming]
|
||||
G --> H[responseUpdate update UI]
|
||||
H --> I{responseComplete}
|
||||
I -->|tool call| J[Execute tool and write tool result message]
|
||||
J --> K[actions.yieldNextRoundTo=self]
|
||||
K --> F
|
||||
I -->|plain reply| L[Complete and return to UI]
|
||||
```
|
||||
|
||||
## Related code
|
||||
|
||||
- [basicPromptConcatHandler.ts](../../src/services/agentInstance/buildInAgentHandlers/basicPromptConcatHandler.ts)
|
||||
- [messageManagementPlugin.ts](../../src/services/agentInstance/plugins/messageManagementPlugin.ts)
|
||||
- [wikiSearchPlugin.ts](../../src/services/agentInstance/plugins/wikiSearchPlugin.ts)
|
||||
- [interface.ts](../../src/services/agentInstance/interface.ts)
|
||||
|
||||
## Benefits
|
||||
|
||||
– Loose coupling: the main flow stays unchanged while capabilities are pluggable.
|
||||
– Testability: plugins can be unit-tested and integration-tested with the handler.
|
||||
– Evolvability: new capabilities land as new plugins and hook subscriptions.
|
||||
|
||||
## Notes
|
||||
|
||||
– Avoid double persistence; use `metadata` flags for dedup.
|
||||
– Ensure idempotency and robust error handling; prefer UI updates over persistence when degrading.
|
||||
– Control retry limits and exit conditions to avoid infinite loops.
|
||||
|
|
@ -59,25 +59,25 @@ async function loadFileContentHandler(request: Request) {
|
|||
}
|
||||
}
|
||||
|
||||
try {
|
||||
try {
|
||||
/**
|
||||
* This function is called for every view, but seems register on two different view will throw error, so we check if it's already registered.
|
||||
*/
|
||||
if (!view.webContents.session.protocol.isProtocolHandled('filefix')) {
|
||||
/**
|
||||
* This function is called for every view, but seems register on two different view will throw error, so we check if it's already registered.
|
||||
* Electron's bug, file protocol is not handle-able, won't get any callback. But things like `filea://` `filefix` works.
|
||||
*/
|
||||
if (!view.webContents.session.protocol.isProtocolHandled('filefix')) {
|
||||
/**
|
||||
* Electron's bug, file protocol is not handle-able, won't get any callback. But things like `filea://` `filefix` works.
|
||||
*/
|
||||
view.webContents.session.protocol.handle('filefix', loadFileContentHandler);
|
||||
}
|
||||
/**
|
||||
* Alternative `open://` protocol for a backup if `file://` doesn't work for some reason.
|
||||
*/
|
||||
if (!view.webContents.session.protocol.isProtocolHandled('open')) {
|
||||
view.webContents.session.protocol.handle('open', loadFileContentHandler);
|
||||
}
|
||||
} catch (error) {
|
||||
logger.error(`Failed to register protocol: ${(error as Error).message}`, { function: 'handleViewFileContentLoading' });
|
||||
view.webContents.session.protocol.handle('filefix', loadFileContentHandler);
|
||||
}
|
||||
/**
|
||||
* Alternative `open://` protocol for a backup if `file://` doesn't work for some reason.
|
||||
*/
|
||||
if (!view.webContents.session.protocol.isProtocolHandled('open')) {
|
||||
view.webContents.session.protocol.handle('open', loadFileContentHandler);
|
||||
}
|
||||
} catch (error) {
|
||||
logger.error(`Failed to register protocol: ${(error as Error).message}`, { function: 'handleViewFileContentLoading' });
|
||||
}
|
||||
```
|
||||
|
||||
#### `protocol.handle('file')`
|
||||
|
|
@ -85,37 +85,37 @@ async function loadFileContentHandler(request: Request) {
|
|||
`protocol.handle('file'`'s handler won't receive anything.
|
||||
|
||||
```ts
|
||||
public async handleFileProtocol(request: GlobalRequest): Promise<GlobalResponse> {
|
||||
logger.info('handleFileProtocol() getting url', { url: request.url });
|
||||
const { pathname } = new URL(request.url);
|
||||
logger.info('handleFileProtocol() handle file:// or open:// This url will open file in-wiki', { pathname });
|
||||
let fileExists = fs.existsSync(pathname);
|
||||
logger.info(`This file (decodeURI) ${fileExists ? '' : 'not '}exists`, { pathname });
|
||||
if (fileExists) {
|
||||
return await net.fetch(pathname);
|
||||
}
|
||||
logger.info(`try find file relative to workspace folder`);
|
||||
const workspace = await this.workspaceService.getActiveWorkspace();
|
||||
if (workspace === undefined) {
|
||||
logger.error(`No active workspace, abort. Try loading pathname as-is.`, { pathname });
|
||||
return await net.fetch(pathname);
|
||||
}
|
||||
const filePathInWorkspaceFolder = path.resolve(workspace.wikiFolderLocation, pathname);
|
||||
fileExists = fs.existsSync(filePathInWorkspaceFolder);
|
||||
logger.info(`This file ${fileExists ? '' : 'not '}exists in workspace folder.`, { filePathInWorkspaceFolder });
|
||||
if (fileExists) {
|
||||
return await net.fetch(filePathInWorkspaceFolder);
|
||||
}
|
||||
logger.info(`try find file relative to TidGi App folder`);
|
||||
// on production, __dirname will be in .webpack/main
|
||||
const inTidGiAppAbsoluteFilePath = path.join(app.getAppPath(), '.webpack', 'renderer', pathname);
|
||||
fileExists = fs.existsSync(inTidGiAppAbsoluteFilePath);
|
||||
if (fileExists) {
|
||||
return await net.fetch(inTidGiAppAbsoluteFilePath);
|
||||
}
|
||||
logger.warn(`This url can't be loaded in-wiki. Try loading url as-is.`, { url: request.url });
|
||||
return await net.fetch(request.url);
|
||||
public async handleFileProtocol(request: GlobalRequest): Promise<GlobalResponse> {
|
||||
logger.info('handleFileProtocol() getting url', { url: request.url });
|
||||
const { pathname } = new URL(request.url);
|
||||
logger.info('handleFileProtocol() handle file:// or open:// This url will open file in-wiki', { pathname });
|
||||
let fileExists = fs.existsSync(pathname);
|
||||
logger.info(`This file (decodeURI) ${fileExists ? '' : 'not '}exists`, { pathname });
|
||||
if (fileExists) {
|
||||
return await net.fetch(pathname);
|
||||
}
|
||||
logger.info(`try find file relative to workspace folder`);
|
||||
const workspace = await this.workspaceService.getActiveWorkspace();
|
||||
if (workspace === undefined) {
|
||||
logger.error(`No active workspace, abort. Try loading pathname as-is.`, { pathname });
|
||||
return await net.fetch(pathname);
|
||||
}
|
||||
const filePathInWorkspaceFolder = path.resolve(workspace.wikiFolderLocation, pathname);
|
||||
fileExists = fs.existsSync(filePathInWorkspaceFolder);
|
||||
logger.info(`This file ${fileExists ? '' : 'not '}exists in workspace folder.`, { filePathInWorkspaceFolder });
|
||||
if (fileExists) {
|
||||
return await net.fetch(filePathInWorkspaceFolder);
|
||||
}
|
||||
logger.info(`try find file relative to TidGi App folder`);
|
||||
// on production, __dirname will be in .webpack/main
|
||||
const inTidGiAppAbsoluteFilePath = path.join(app.getAppPath(), '.webpack', 'renderer', pathname);
|
||||
fileExists = fs.existsSync(inTidGiAppAbsoluteFilePath);
|
||||
if (fileExists) {
|
||||
return await net.fetch(inTidGiAppAbsoluteFilePath);
|
||||
}
|
||||
logger.warn(`This url can't be loaded in-wiki. Try loading url as-is.`, { url: request.url });
|
||||
return await net.fetch(request.url);
|
||||
}
|
||||
```
|
||||
|
||||
if
|
||||
|
|
@ -125,4 +125,4 @@ await app.whenReady();
|
|||
protocol.handle('file', nativeService.handleFileProtocol.bind(nativeService));
|
||||
```
|
||||
|
||||
works. But currently it is not.
|
||||
works. But currently it is not.
|
||||
|
|
|
|||
443
docs/features/WikiWorkspaceCreation.md
Normal file
443
docs/features/WikiWorkspaceCreation.md
Normal file
|
|
@ -0,0 +1,443 @@
|
|||
# Wiki Workspace Creation
|
||||
|
||||
## Overview
|
||||
|
||||
Wiki workspaces are the core concept in TidGi, representing individual TiddlyWiki instances with associated configuration, Git repositories, and UI views. This document explains how wiki workspaces are created in two scenarios:
|
||||
|
||||
1. **Automatic creation** when the application starts with no existing workspaces
|
||||
2. **Manual creation** through the frontend UI
|
||||
|
||||
## Automatic Workspace Creation
|
||||
|
||||
### Startup Flow
|
||||
|
||||
When TidGi launches without any existing workspaces, it automatically creates a default wiki workspace. This logic is implemented in the initialization chain:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Main as main.ts
|
||||
participant Common as commonInit()
|
||||
participant WikiGit as WikiGitWorkspaceService
|
||||
participant Workspace as WorkspaceService
|
||||
participant View as WorkspaceViewService
|
||||
|
||||
Main->>Common: app.on('ready')
|
||||
Common->>Common: await app.whenReady()
|
||||
Common->>Common: Initialize database & services
|
||||
Common->>WikiGit: wikiGitWorkspaceService.initialize()
|
||||
WikiGit->>Workspace: getWorkspacesAsList()
|
||||
Workspace-->>WikiGit: workspaces[]
|
||||
|
||||
alt No wiki workspaces exist
|
||||
WikiGit->>WikiGit: Create default config
|
||||
WikiGit->>WikiGit: copyWikiTemplate()
|
||||
WikiGit->>WikiGit: initWikiGitTransaction()
|
||||
WikiGit->>Workspace: create(defaultConfig)
|
||||
WikiGit->>WikiGit: initWikiGit()
|
||||
end
|
||||
|
||||
Common->>Workspace: initializeDefaultPageWorkspaces()
|
||||
Common->>View: initializeAllWorkspaceView()
|
||||
```
|
||||
|
||||
### Implementation Details
|
||||
|
||||
#### 1. Entry Point (main.ts)
|
||||
|
||||
The initialization starts in `src/main.ts` in the `commonInit()` function:
|
||||
|
||||
```typescript
|
||||
const commonInit = async (): Promise<void> => {
|
||||
await app.whenReady();
|
||||
await initDevelopmentExtension();
|
||||
|
||||
// Initialize database FIRST - all other services depend on it
|
||||
await databaseService.initializeForApp();
|
||||
|
||||
// ... other initializations ...
|
||||
|
||||
// Auto-create default wiki workspace if none exists
|
||||
await wikiGitWorkspaceService.initialize();
|
||||
|
||||
// Create default page workspaces before initializing all workspace views
|
||||
await workspaceService.initializeDefaultPageWorkspaces();
|
||||
|
||||
// Perform wiki startup and git sync for each workspace
|
||||
await workspaceViewService.initializeAllWorkspaceView();
|
||||
};
|
||||
```
|
||||
|
||||
#### 2. WikiGitWorkspaceService.initialize()
|
||||
|
||||
Located in `src/services/wikiGitWorkspace/index.ts`, this method checks if any wiki workspaces exist and creates a default one if needed:
|
||||
|
||||
```typescript
|
||||
public async initialize(): Promise<void> {
|
||||
const workspaceService = container.get<IWorkspaceService>(serviceIdentifier.Workspace);
|
||||
const workspaces = await workspaceService.getWorkspacesAsList();
|
||||
const wikiWorkspaces = workspaces.filter(w => isWikiWorkspace(w) && !w.isSubWiki);
|
||||
|
||||
// Exit if any wiki workspaces already exist
|
||||
if (wikiWorkspaces.length > 0) return;
|
||||
|
||||
// Construct minimal default config with required fields
|
||||
const defaultConfig: INewWikiWorkspaceConfig = {
|
||||
order: 0,
|
||||
wikiFolderLocation: DEFAULT_FIRST_WIKI_PATH,
|
||||
storageService: SupportedStorageServices.local,
|
||||
name: 'wiki',
|
||||
port: 5212,
|
||||
isSubWiki: false,
|
||||
backupOnInterval: true,
|
||||
readOnlyMode: false,
|
||||
tokenAuth: false,
|
||||
tagName: null,
|
||||
mainWikiToLink: null,
|
||||
mainWikiID: null,
|
||||
excludedPlugins: [],
|
||||
enableHTTPAPI: false,
|
||||
lastNodeJSArgv: [],
|
||||
homeUrl: '',
|
||||
gitUrl: null,
|
||||
};
|
||||
|
||||
try {
|
||||
// Copy the wiki template first
|
||||
const wikiService = container.get<IWikiService>(serviceIdentifier.Wiki);
|
||||
await wikiService.copyWikiTemplate(DEFAULT_FIRST_WIKI_FOLDER_PATH, 'wiki');
|
||||
|
||||
// Create the workspace
|
||||
await this.initWikiGitTransaction(defaultConfig);
|
||||
} catch (error) {
|
||||
logger.error(error.message, error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Wiki Template and Git Initialization
|
||||
|
||||
The `initWikiGitTransaction` method handles the complete workspace creation:
|
||||
|
||||
1. **Create workspace record**: Calls `workspaceService.create(newWorkspaceConfig)` to persist workspace configuration
|
||||
2. **Copy wiki template**: Uses `wikiService.copyWikiTemplate()` to copy base TiddlyWiki files
|
||||
3. **Initialize Git repository**: If not already initialized, calls `gitService.initWikiGit()`
|
||||
4. **Rollback on failure**: If any step fails, removes the created workspace and wiki folder
|
||||
|
||||
```typescript
|
||||
public initWikiGitTransaction = async (
|
||||
newWorkspaceConfig: INewWikiWorkspaceConfig,
|
||||
userInfo?: IGitUserInfos
|
||||
): Promise<IWorkspace | undefined> => {
|
||||
const workspaceService = container.get<IWorkspaceService>(serviceIdentifier.Workspace);
|
||||
const newWorkspace = await workspaceService.create(newWorkspaceConfig);
|
||||
|
||||
try {
|
||||
// ... Git initialization logic ...
|
||||
|
||||
if (await hasGit(wikiFolderLocation)) {
|
||||
logger.warn('Skip git init because it already has a git setup.');
|
||||
} else {
|
||||
const gitService = container.get<IGitService>(serviceIdentifier.Git);
|
||||
await gitService.initWikiGit(wikiFolderLocation, isSyncedWiki, !isSubWiki, gitUrl, userInfo);
|
||||
}
|
||||
|
||||
return newWorkspace;
|
||||
} catch (error) {
|
||||
// Rollback: remove workspace and wiki folder
|
||||
await workspaceService.remove(workspaceID);
|
||||
await wikiService.removeWiki(wikiFolderLocation);
|
||||
throw new InitWikiGitError(error.message);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
#### 4. View Initialization
|
||||
|
||||
After workspace creation, `workspaceViewService.initializeAllWorkspaceView()` starts each wiki:
|
||||
|
||||
1. **Check wiki validity**: Verifies the wiki folder contains valid TiddlyWiki files
|
||||
2. **Start wiki server**: Launches the TiddlyWiki Node.js server
|
||||
3. **Create browser view**: Creates an Electron WebContentsView to display the wiki
|
||||
4. **Load initial URL**: Navigates the view to the wiki's home URL
|
||||
|
||||
## Manual Workspace Creation
|
||||
|
||||
### User Interface Flow
|
||||
|
||||
Users can create new workspaces through the "Add Workspace" window:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[User clicks Add Workspace] --> B[Open AddWorkspace window]
|
||||
B --> C{Creation Method}
|
||||
|
||||
C -->|Create New| D[useNewWiki hook]
|
||||
C -->|Clone Existing| E[useCloneWiki hook]
|
||||
C -->|Open Existing| F[useOpenWiki hook]
|
||||
|
||||
D --> G[Fill form: name, folder, port]
|
||||
E --> H[Fill form: git URL, credentials]
|
||||
F --> I[Select existing wiki folder]
|
||||
|
||||
G --> J[Submit form]
|
||||
H --> J
|
||||
I --> J
|
||||
|
||||
J --> K[callWikiInitialization]
|
||||
K --> L[wikiGitWorkspace.initWikiGitTransaction]
|
||||
L --> M[workspaceView.initializeWorkspaceView]
|
||||
M --> N[workspaceView.setActiveWorkspaceView]
|
||||
N --> O[Close AddWorkspace window]
|
||||
```
|
||||
|
||||
### Frontend Components
|
||||
|
||||
#### 1. Form State Management (useForm.ts)
|
||||
|
||||
Located in `src/pages/AddWorkspace/useForm.ts`, manages workspace creation form state:
|
||||
|
||||
```typescript
|
||||
export function useWikiWorkspaceForm(options?: { fromExisted: boolean }) {
|
||||
const [wikiFolderName, wikiFolderNameSetter] = useState('tiddlywiki');
|
||||
const [parentFolderLocation, parentFolderLocationSetter] = useState('');
|
||||
const [wikiPort, wikiPortSetter] = useState(5212);
|
||||
const [storageProvider, storageProviderSetter] = useState<SupportedStorageServices>(
|
||||
SupportedStorageServices.local
|
||||
);
|
||||
|
||||
// Initialize default folder path
|
||||
useEffect(() => {
|
||||
(async function getDefaultExistedWikiFolderPathEffect() {
|
||||
const desktopPath = await window.service.context.get('DEFAULT_WIKI_FOLDER');
|
||||
parentFolderLocationSetter(desktopPath);
|
||||
})();
|
||||
}, []);
|
||||
|
||||
// ... rest of form state ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Creation Hooks
|
||||
|
||||
Three main hooks handle different creation methods:
|
||||
|
||||
##### useNewWiki (useNewWiki.ts)
|
||||
|
||||
Creates a new wiki from template:
|
||||
|
||||
```typescript
|
||||
export function useNewWiki(
|
||||
isCreateMainWorkspace: boolean,
|
||||
isCreateSub: boolean,
|
||||
form: IWikiWorkspaceForm,
|
||||
wikiCreationMessageSetter: (m: string) => void,
|
||||
// ...
|
||||
): () => Promise<void> {
|
||||
const onSubmit = useCallback(async () => {
|
||||
wikiCreationMessageSetter(t('AddWorkspace.Processing'));
|
||||
|
||||
try {
|
||||
const newWorkspaceConfig = workspaceConfigFromForm(form, isCreateMainWorkspace, true);
|
||||
|
||||
// Create wiki folder and files
|
||||
if (isCreateMainWorkspace) {
|
||||
await window.service.wiki.copyWikiTemplate(
|
||||
form.parentFolderLocation,
|
||||
form.wikiFolderName
|
||||
);
|
||||
} else {
|
||||
await window.service.wiki.copySubWikiTemplate(/* ... */);
|
||||
}
|
||||
|
||||
// Initialize workspace and Git
|
||||
await callWikiInitialization(newWorkspaceConfig, wikiCreationMessageSetter, t, gitUserInfo, {
|
||||
from: WikiCreationMethod.Create
|
||||
});
|
||||
} catch (error) {
|
||||
wikiCreationMessageSetter(error.message);
|
||||
hasErrorSetter(true);
|
||||
}
|
||||
}, [/* dependencies */]);
|
||||
|
||||
return onSubmit;
|
||||
}
|
||||
```
|
||||
|
||||
##### useCloneWiki (useCloneWiki.ts)
|
||||
|
||||
Clones an existing wiki from a Git repository:
|
||||
|
||||
```typescript
|
||||
export function useCloneWiki(/* ... */): () => Promise<void> {
|
||||
const onSubmit = useCallback(async () => {
|
||||
wikiCreationMessageSetter(t('AddWorkspace.Processing'));
|
||||
|
||||
try {
|
||||
const newWorkspaceConfig = workspaceConfigFromForm(form, isCreateMainWorkspace, true);
|
||||
|
||||
// Clone from Git repository
|
||||
if (isCreateMainWorkspace) {
|
||||
await window.service.wiki.cloneWiki(
|
||||
form.parentFolderLocation,
|
||||
form.wikiFolderName,
|
||||
form.gitRepoUrl,
|
||||
form.gitUserInfo!
|
||||
);
|
||||
} else {
|
||||
await window.service.wiki.cloneSubWiki(/* ... */);
|
||||
}
|
||||
|
||||
// Initialize workspace
|
||||
await callWikiInitialization(newWorkspaceConfig, wikiCreationMessageSetter, t, gitUserInfo, {
|
||||
from: WikiCreationMethod.Clone
|
||||
});
|
||||
} catch (error) {
|
||||
wikiCreationMessageSetter(error.message);
|
||||
hasErrorSetter(true);
|
||||
}
|
||||
}, [/* dependencies */]);
|
||||
|
||||
return onSubmit;
|
||||
}
|
||||
```
|
||||
|
||||
##### useOpenWiki (useOpenWiki.ts)
|
||||
|
||||
Opens an existing wiki folder:
|
||||
|
||||
```typescript
|
||||
export function useOpenWiki(/* ... */): () => Promise<void> {
|
||||
const onSubmit = useCallback(async () => {
|
||||
wikiCreationMessageSetter(t('AddWorkspace.Processing'));
|
||||
|
||||
try {
|
||||
const newWorkspaceConfig = workspaceConfigFromForm(form, isCreateMainWorkspace, false);
|
||||
|
||||
// No need to copy template or clone, wiki folder already exists
|
||||
// Just initialize workspace and start wiki
|
||||
await callWikiInitialization(newWorkspaceConfig, wikiCreationMessageSetter, t, gitUserInfo, {
|
||||
from: WikiCreationMethod.Open
|
||||
});
|
||||
} catch (error) {
|
||||
wikiCreationMessageSetter(error.message);
|
||||
hasErrorSetter(true);
|
||||
}
|
||||
}, [/* dependencies */]);
|
||||
|
||||
return onSubmit;
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Common Initialization (callWikiInitialization)
|
||||
|
||||
Located in `src/pages/AddWorkspace/useCallWikiInitialization.ts`, this function performs the final workspace initialization steps:
|
||||
|
||||
```typescript
|
||||
export async function callWikiInitialization(
|
||||
newWorkspaceConfig: INewWorkspaceConfig,
|
||||
wikiCreationMessageSetter: (m: string) => void,
|
||||
t: TFunction<'translation'>,
|
||||
gitUserInfo: IGitUserInfos | undefined,
|
||||
configs: ICallWikiInitConfig,
|
||||
): Promise<void> {
|
||||
// Step 1: Initialize workspace and Git
|
||||
wikiCreationMessageSetter(t('Log.InitializeWikiGit'));
|
||||
const newWorkspace = await window.service.wikiGitWorkspace.initWikiGitTransaction(
|
||||
newWorkspaceConfig,
|
||||
gitUserInfo
|
||||
);
|
||||
|
||||
if (newWorkspace === undefined) {
|
||||
throw new Error('newWorkspace is undefined');
|
||||
}
|
||||
|
||||
// Step 2: Initialize workspace view (starts wiki server, creates browser view)
|
||||
wikiCreationMessageSetter(t('Log.InitializeWorkspaceView'));
|
||||
await window.service.workspaceView.initializeWorkspaceView(newWorkspace, {
|
||||
isNew: true,
|
||||
from: configs.from
|
||||
});
|
||||
|
||||
// Step 3: Activate the new workspace
|
||||
wikiCreationMessageSetter(t('Log.InitializeWorkspaceViewDone'));
|
||||
await window.service.workspaceView.setActiveWorkspaceView(newWorkspace.id);
|
||||
|
||||
// Step 4: Close Add Workspace window (if not disabled)
|
||||
if (!configs.notClose) {
|
||||
await window.service.window.close(WindowNames.addWorkspace);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Workspace Creation Validation
|
||||
|
||||
### Wiki Folder Validation
|
||||
|
||||
The `checkWikiExist` method in WikiService validates that a folder contains a valid TiddlyWiki:
|
||||
|
||||
1. **Check folder exists**: Verifies the wiki folder path exists
|
||||
2. **Check tiddlywiki.info**: For main wikis, requires `tiddlywiki.info` file
|
||||
3. **Check plugin files**: Verifies required TiddlyWiki core files exist
|
||||
4. **Show error dialog**: If validation fails and `showDialog: true`, prompts user to remove invalid workspace
|
||||
|
||||
The error message in the CI logs shows this validation:
|
||||
|
||||
```log
|
||||
无法找到之前还在该处的工作区知识库文件夹！该目录不是一个知识库文件夹
|
||||
```
|
||||
|
||||
This occurs when `initWikiGit` completes but wiki template files are not yet created, causing `initializeAllWorkspaceView` to fail validation.
|
||||
|
||||
## Related Code
|
||||
|
||||
### Backend Services
|
||||
|
||||
- [main.ts](../../src/main.ts): Application initialization entry point
|
||||
- [wikiGitWorkspace/index.ts](../../src/services/wikiGitWorkspace/index.ts): `initialize()`, `initWikiGitTransaction()`
|
||||
- [workspacesView/index.ts](../../src/services/workspacesView/index.ts): `initializeAllWorkspaceView()`, `initializeWorkspaceView()`
|
||||
- [wiki/index.ts](../../src/services/wiki/index.ts): `copyWikiTemplate()`, `checkWikiExist()`
|
||||
- [git/index.ts](../../src/services/git/index.ts): `initWikiGit()`
|
||||
|
||||
### Frontend UI Components
|
||||
|
||||
- [AddWorkspace/useForm.ts](../../src/pages/AddWorkspace/useForm.ts): Form state management
|
||||
- [AddWorkspace/useNewWiki.ts](../../src/pages/AddWorkspace/useNewWiki.ts): Create new wiki
|
||||
- [AddWorkspace/useCloneWiki.ts](../../src/pages/AddWorkspace/useCloneWiki.ts): Clone from Git
|
||||
- [AddWorkspace/useOpenWiki.ts](../../src/pages/AddWorkspace/useOpenWiki.ts): Open existing wiki
|
||||
- [AddWorkspace/useCallWikiInitialization.ts](../../src/pages/AddWorkspace/useCallWikiInitialization.ts): Common initialization logic
|
||||
|
||||
## Common Issues
|
||||
|
||||
### 1. Wiki Validation Failure
|
||||
|
||||
**Symptom**: Error message "该目录不是一个知识库文件夹" during initialization
|
||||
|
||||
**Cause**: Wiki template files not fully created before validation runs
|
||||
|
||||
**Solution**: Ensure `copyWikiTemplate()` completes before calling `initWikiGitTransaction()`
|
||||
|
||||
### 2. Git Initialization Timeout
|
||||
|
||||
**Symptom**: Workspace creation hangs during Git initialization
|
||||
|
||||
**Cause**: Git operations taking too long in CI or slow network conditions
|
||||
|
||||
**Solution**: Implement timeout protection in `initWikiGit()` or skip Git init for local-only wikis
|
||||
|
||||
### 3. Worker Not Starting
|
||||
|
||||
**Symptom**: Wiki operations timeout after workspace creation
|
||||
|
||||
**Cause**: Worker initialization fails if wiki folder validation fails
|
||||
|
||||
**Solution**: Ensure wiki folder passes validation before starting worker
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Atomic Operations**: Use transactions (`initWikiGitTransaction`) to rollback on failure
|
||||
2. **Validation First**: Always validate wiki folders before starting services
|
||||
3. **Progress Feedback**: Use `wikiCreationMessageSetter` to show user progress
|
||||
4. **Error Handling**: Catch and display user-friendly error messages
|
||||
5. **Default Values**: Provide sensible defaults for optional configuration
|
||||
6. **Cleanup on Failure**: Always remove partially created workspaces on error
|
||||
Loading…
Add table
Add a link
Reference in a new issue