Skip to content

Commit 8e3fa74

Browse files
committed
docs(desktop): align onboarding implementation doc with current behavior (anomalyco#180)
- prepare-runtime scripts sync downgraded to non-fatal warning - configure-memory skip persists enabled=false with credential retention - ontology-setup adds source selection (official / custom GitHub URL) - memory-config replaced advanced toggle with real LLM/Embedding form and probe flow - done step uses in-process transition instead of relaunch - IPC channel relaunch replaced with transition-to-workbench, probe adds Runtime/Memory
1 parent 01e759b commit 8e3fa74

1 file changed

Lines changed: 37 additions & 22 deletions

File tree

‎docs/DESKTOP-ONBOARDING.md‎

Lines changed: 37 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,9 @@
6161
|---------|------|-------------|-------------|
6262
| ontology 未准备 | 步骤 6 尚未成功 | `SETUP_ONTOLOGY_NOT_PREPARED` | 返回步骤 6,完成 ontology 准备后重试 |
6363
| settings 写入失败 | ontology 配置缺失、目标不可写或磁盘满 | `SETUP_RUNTIME_PREPARE_FAILED` | 保留步骤 7,展示 settings 诊断与重试按钮 |
64-
| scripts 同步失败 | ontology scripts 缺失或链接/复制失败 | `SETUP_RUNTIME_PREPARE_FAILED` | 保留步骤 7,展示缺失脚本与重试按钮 |
64+
| scripts 同步失败 | ontology scripts 缺失或链接/复制失败 | warning(非阻断) | 保留步骤 7,展示缺失脚本为警告,允许继续 |
6565
| 能力物化失败 | agents/skills/commands/rules/plugins/prompts 任一源缺失或目标不可写 | `SETUP_RUNTIME_PREPARE_FAILED` | 保留步骤 7,展示失败能力与重试按钮 |
66-
| 成功 | 三类全局运行时动作全部 ready | `created` / `reused` | 展示 settings、scripts、能力摘要,用户主动继续 |
66+
| 成功 | settings 与能力物化全部 ready | `created` / `reused` | 展示 settings、scripts(含警告)、能力摘要,用户主动继续 |
6767

6868
### 1.6 initialize-space(步骤 8)
6969

@@ -81,9 +81,11 @@
8181

8282
| 错误类型 | 原因 | machine 返回 | Desktop 响应 |
8383
|---------|------|-------------|-------------|
84+
| 配置不完整 | 启用记忆但缺少 LLM endpoint/key 或 Embedding endpoint/model | `SETUP_MEMORY_CONFIG_INCOMPLETE` | 保留步骤 9,展示缺失字段与重试按钮,不写入半成品配置 |
8485
| 文件写入失败 | 无写权限或磁盘满 | `ok: false` | 展示"配置保存失败,请检查磁盘空间和权限后重试" + 重试按钮 |
85-
| enabled 未传 | Desktop 漏传必填字段 `enabled` | `ok: false` | 实现层错误——Desktop 的 `onboardingExecuteStep` 必须确保 `enabled: true/false` |
86-
| 用户跳过 | 点击"跳过"或只勾选 `enabled` | 仅传 `{ enabled: true }`(不传可选 LLM/Embedding 字段) | 标记步骤为 `skipped`,进入步骤 10 |
86+
| enabled 未传 | Desktop 漏传必填字段 `enabled` | `ok: false` | 实现层错误——Desktop 的 `onboardingExecuteStep` 须确保 `enabled: true/false` |
87+
| 用户暂不启用 | 点击"暂不启用长期记忆" | `enabled: false`,持久化两个记忆开关为 `false` | 标记步骤为 `skipped`,已有模型凭证保留,进入步骤 10 |
88+
| 保存成功 | 配置完整且验证通过 | `created` / `updated` / `reused` | 复检并展示全局作用域、启用状态、endpoint/model、密钥状态与 env path |
8789

8890
### 1.8 star(步骤 10)
8991

@@ -200,13 +202,17 @@ interface AiProviderProps extends StepProps {
200202
```typescript
201203
interface OntologySetupProps extends StepProps {
202204
// 组件内部状态:
203-
// - mode: "fork" | "clone"
205+
// - sourceType: "official" | "custom" 本体来源(官方默认源或自定义 GitHub URL)
206+
// - customUrl: string 自定义来源时填写的 GitHub URL
207+
// - mode: "fork" | "clone" 获取模式
204208
// - hasGithubAuth: boolean
205209
// - existingMode: "fork" | "clone" | null
206210
//
207211
// 有有效 GitHub 认证且无既有本体时默认 Fork,否则默认 Clone。
208-
// 用户只选择本体模式。成功提交:
209-
// onComplete({ stepId: "ontology-setup", input: { mode } })。
212+
// 用户选择本体来源与获取模式。自定义 URL 适用于 fork 或 clone。
213+
// 已安装 ontology 保持当前来源与拓扑,不允许切换模式。
214+
// 成功提交:
215+
// onComplete({ stepId: "ontology-setup", input: { mode, source } })。
210216
// machine result 中 availableTypes 仅展示准备结果,类型选择由步骤 8 所有。
211217
}
212218
```
@@ -245,17 +251,24 @@ interface CreateSpaceProps extends StepProps {
245251
```typescript
246252
interface MemoryConfigProps extends StepProps {
247253
// 组件内部状态:
248-
// - enabled: boolean 是否启用记忆
249-
// - llmEndpoint: string 自定义 LLM 端点(enabled=true 时可选)
250-
// - llmKey: string 自定义 LLM Key(enabled=true 时可选)
251-
// - llmModel: string 自定义 LLM Model(enabled=true 时可选)
252-
// - embeddingEndpoint: string 自定义 Embedding 端点(enabled=true 时可选)
253-
// - embeddingKey: string 自定义 Embedding Key(enabled=true 时可选)
254-
// - embeddingModel: string 自定义 Embedding Model(enabled=true 时可选)
255-
// - showAdvanced: boolean 是否展开高级配置
256-
// - showSkip: true 此步骤可跳过
254+
// - enabled: boolean 是否启用记忆
255+
// - probeState: "unconfigured" | "disabled" | "ready"
256+
// - llmEndpoint: string LLM 端点
257+
// - llmKey: string LLM Key(空表示保留已有密钥)
258+
// - llmModel: string LLM Model
259+
// - embeddingEndpoint: string Embedding 端点
260+
// - embeddingKey: string Embedding Key(空表示保留已有密钥)
261+
// - embeddingModel: string Embedding Model
262+
// - embeddingSameAsLlm: boolean Embedding 复用同一 endpoint 与 key
263+
// - showSkip: true 此步骤可跳过
257264
//
258-
// 默认只展示 enabled checkbox。enabled=true 时展开高级选项。
265+
// 进入步骤时先只读探测已有配置。probe 完成 after展示表单。
266+
// unconfigured → 默认启用,展示 LLM 与 Embedding 两段真实配置表单。
267+
// ready → 回填 endpoint/model,密钥显示"已保存",空密钥输入表示保留。
268+
// disabled → 开关关闭,展示关闭影响与重新启用入口。
269+
// 选择"Embedding 使用同一服务" → endpoint 与 key 复用 LLM 值,只单独填写 Embedding model。
270+
// 启用记忆时最终生效配置须满足 LLM endpoint/key 与 Embedding endpoint/model。
271+
// "暂不启用长期记忆" → 调用 configure-memory(enabled=false) 后以 skipped 语义推进。
259272
// 完成后调用 onComplete({ stepId: "memory-config",
260273
// input: { enabled, ...optionalLLMFields } })。
261274
}
@@ -280,11 +293,13 @@ interface StarGuideProps extends StepProps {
280293
interface DoneViewProps {
281294
state: OnboardingState; // 完整的 onboarding 状态
282295
nonFatalFailures: StepError[]; // 非致命步骤的失败信息(须展示给用户)
283-
onRelaunch: () => void; // 触发 relaunch
296+
onEnterWorkbench: () => void; // 触发进程内转换进入 Workbench
284297
}
285298
```
286299

287-
`onboardingComplete()` 在写入完成态前调用 machine `inspect`。只有 `verdict === "healthy"` 才允许 relaunch。门禁失败返回结构化错误,Renderer 保留在 done 页面并展示缺失维度。
300+
`onboardingComplete()` 在写入完成态前调用 machine `inspect`。只有 `verdict === "healthy"` 才允许进入 Workbench。门禁失败返回结构化错误,Renderer 保留在 done 页面并展示缺失维度。
301+
302+
进程内转换在当前进程内启动 sidecar 并将窗口切换到 Workbench,不重启进程。转换失败时提供"重试启动 / 重新配置"入口。
288303

289304
---
290305

@@ -299,7 +314,7 @@ interface OnboardingIpcDeps {
299314
readOnboardingState: () => OnboardingState; // 读 onboarding.json
300315
writeOnboardingState: (state: Partial<OnboardingState>) => void; // 写 onboarding.json(原子替换)
301316
broadcastProgress: (stepId: string, status: StepStatus) => void; // 通知 renderer 进度
302-
relaunchApp: () => void; // 重启应用
317+
transitionToWorkbench: () => Promise<{ status: "ok" } | { status: "error"; message: string }>; // 进程内转换
303318
downloadFile: (url: string, dest: string) => Promise<boolean>; // 下载 CLI binary
304319
checkSystem: () => SystemCheckResult; // 本地系统检查
305320
}
@@ -315,9 +330,9 @@ Machine client 将 capability success envelope 的 `data` 解释为 `SetupOperat
315330
|---------|------|------|
316331
| `onboarding:read-state` | Renderer → Main | 读取当前 onboarding.json |
317332
| `onboarding:execute-step` | Renderer → Main | 执行一个步骤(调 machine 或本地操作) |
318-
| `onboarding:probe` | Renderer → Main | 只读探测 GitHub、Provider 或 setup 环境,不改变步骤状态 |
333+
| `onboarding:probe` | Renderer → Main | 只读探测 GitHub、Provider、Runtime、Memory 或 setup 环境,不改变步骤状态 |
319334
| `onboarding:progress` | Main → Renderer | 推送步骤执行进度(broadcastProgress) |
320-
| `onboarding:relaunch` | Renderer → Main | 完成 onboarding 后重启 |
335+
| `onboarding:transition-to-workbench` | Renderer → Main | 完成后进程内转换进入 Workbench |
321336
| `onboarding:get-system-info` | Renderer → Main | 获取系统信息(步骤 1) |
322337

323338
---

0 commit comments

Comments
 (0)