@acryldev/plugin-context 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/docs/README.md +160 -0
- package/docs/delivery/local-live.md +113 -0
- package/docs/delivery/marketplace.md +16 -0
- package/docs/docs.json +2836 -0
- package/docs/extending/agent-preset.md +37 -0
- package/docs/extending/chat-command.md +28 -0
- package/docs/extending/client-slot.md +135 -0
- package/docs/extending/config-schema.md +7 -0
- package/docs/extending/cordis-core.md +63 -0
- package/docs/extending/desktop-app.md +53 -0
- package/docs/extending/desktop-main.md +25 -0
- package/docs/extending/event-hook.md +14 -0
- package/docs/extending/host-route.md +33 -0
- package/docs/extending/llm-adapter.md +38 -0
- package/docs/extending/packaging.md +53 -0
- package/docs/extending/prompt-contribution.md +9 -0
- package/docs/extending/service.md +13 -0
- package/docs/extending/skill-provider.md +9 -0
- package/docs/extending/state-and-persistence.md +71 -0
- package/docs/extending/three-role-capability.md +33 -0
- package/docs/extending/tool-plugin.md +24 -0
- package/docs/extending/tui-command.md +8 -0
- package/docs/extending/tui-components.md +61 -0
- package/docs/extending/ui-branding.md +43 -0
- package/docs/extending/ui-components.md +56 -0
- package/docs/extending/ui-customization.md +41 -0
- package/docs/extending/ui-library.md +66 -0
- package/docs/extending/ui-theme.md +55 -0
- package/docs/extending/workspace-tab.md +50 -0
- package/docs/maps/events.md +108 -0
- package/docs/maps/mount-points.md +154 -0
- package/docs/maps/slot-contracts.md +3376 -0
- package/docs/maps/taxonomy.md +306 -0
- package/docs/maps/theme-tokens.md +115 -0
- package/docs/maps/ui-components.md +26 -0
- package/docs/reference/cookbook/adding-a-package.md +174 -0
- package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
- package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
- package/docs/reference/cookbook/adding-a-tool.md +103 -0
- package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
- package/docs/reference/cookbook/extension-cookbook.md +134 -0
- package/docs/reference/cordis-api/context.md +366 -0
- package/docs/reference/cordis-api/events.md +209 -0
- package/docs/reference/cordis-api/fiber.md +377 -0
- package/docs/reference/cordis-api/inherited.md +40 -0
- package/docs/reference/cordis-api/registry.md +154 -0
- package/docs/reference/cordis-api/service.md +104 -0
- package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
- package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
- package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
- package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
- package/docs/reference/harness/agent-lifecycle.md +93 -0
- package/docs/reference/harness/architecture.md +168 -0
- package/docs/reference/harness/capability-seams.md +675 -0
- package/docs/reference/harness/config-catalog.md +4523 -0
- package/docs/reference/harness/cordis-primer.md +47 -0
- package/docs/reference/harness/defensive-patterns.md +35 -0
- package/docs/reference/harness/event-producer-consumer.md +111 -0
- package/docs/reference/harness/glossary.md +47 -0
- package/docs/reference/harness/tool-catalog.md +2721 -0
- package/docs/reference/harness/tool-execution-pipeline.md +67 -0
- package/docs/reference/subsystems/README.md +75 -0
- package/docs/reference/subsystems/agent-team.md +233 -0
- package/docs/reference/subsystems/approval.md +172 -0
- package/docs/reference/subsystems/attachment.md +363 -0
- package/docs/reference/subsystems/boot.md +324 -0
- package/docs/reference/subsystems/browser-use.md +69 -0
- package/docs/reference/subsystems/client-modules.md +186 -0
- package/docs/reference/subsystems/client-resources.md +94 -0
- package/docs/reference/subsystems/commands.md +225 -0
- package/docs/reference/subsystems/compaction.md +286 -0
- package/docs/reference/subsystems/computer-use.md +58 -0
- package/docs/reference/subsystems/conversation.md +287 -0
- package/docs/reference/subsystems/core.md +1107 -0
- package/docs/reference/subsystems/credentials.md +497 -0
- package/docs/reference/subsystems/deliverables.md +180 -0
- package/docs/reference/subsystems/extensions.md +386 -0
- package/docs/reference/subsystems/feedback.md +402 -0
- package/docs/reference/subsystems/filesystem.md +532 -0
- package/docs/reference/subsystems/goal.md +315 -0
- package/docs/reference/subsystems/invariants.md +90 -0
- package/docs/reference/subsystems/jobs.md +501 -0
- package/docs/reference/subsystems/llm-streaming.md +1131 -0
- package/docs/reference/subsystems/lsp.md +204 -0
- package/docs/reference/subsystems/mcp.md +141 -0
- package/docs/reference/subsystems/office-to-pdf.md +89 -0
- package/docs/reference/subsystems/otel.md +46 -0
- package/docs/reference/subsystems/permission-presets.md +169 -0
- package/docs/reference/subsystems/persistence.md +418 -0
- package/docs/reference/subsystems/plan.md +89 -0
- package/docs/reference/subsystems/product-telemetry.md +81 -0
- package/docs/reference/subsystems/ptc-runtime.md +234 -0
- package/docs/reference/subsystems/sandbox.md +223 -0
- package/docs/reference/subsystems/schedule.md +545 -0
- package/docs/reference/subsystems/scope.md +61 -0
- package/docs/reference/subsystems/session-projection.md +358 -0
- package/docs/reference/subsystems/session-query.md +511 -0
- package/docs/reference/subsystems/session-reference.md +226 -0
- package/docs/reference/subsystems/session-telemetry.md +214 -0
- package/docs/reference/subsystems/session-title.md +206 -0
- package/docs/reference/subsystems/session.md +1300 -0
- package/docs/reference/subsystems/settings.md +157 -0
- package/docs/reference/subsystems/shell.md +316 -0
- package/docs/reference/subsystems/sidebar-right.md +160 -0
- package/docs/reference/subsystems/skills.md +354 -0
- package/docs/reference/subsystems/slots.md +201 -0
- package/docs/reference/subsystems/spill.md +126 -0
- package/docs/reference/subsystems/ssh.md +137 -0
- package/docs/reference/subsystems/storage.md +262 -0
- package/docs/reference/subsystems/subagent.md +762 -0
- package/docs/reference/subsystems/subprocess.md +323 -0
- package/docs/reference/subsystems/system-prompt.md +226 -0
- package/docs/reference/subsystems/terminal.md +186 -0
- package/docs/reference/subsystems/todo.md +34 -0
- package/docs/reference/subsystems/token-meter.md +108 -0
- package/docs/reference/subsystems/tools.md +749 -0
- package/docs/reference/subsystems/typert.md +489 -0
- package/docs/reference/subsystems/user-questions.md +309 -0
- package/docs/reference/subsystems/voice-input.md +166 -0
- package/docs/reference/subsystems/web-client.md +102 -0
- package/docs/reference/subsystems/web-server.md +228 -0
- package/docs/reference/subsystems/web.md +208 -0
- package/docs/reference/subsystems/webhook.md +72 -0
- package/docs/reference/subsystems/workflow.md +280 -0
- package/docs/reference/subsystems/workspace.md +661 -0
- package/docs/start-here/blueprints.md +33 -0
- package/docs/start-here/this-runtime.md +84 -0
- package/docs/start-here/troubleshooting.md +29 -0
- package/docs/start-here/trust-and-safety.md +39 -0
- package/docs/start-here/verify-before-done.md +46 -0
- package/example-plugins/README.md +45 -0
- package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
- package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
- package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
- package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
- package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
- package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
- package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/chat-command-basic/index.js +26 -0
- package/example-plugins/packages/chat-command-basic/package.json +25 -0
- package/example-plugins/packages/client-chat-message-action/client.js +46 -0
- package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-chat-message-action/index.js +9 -0
- package/example-plugins/packages/client-chat-message-action/package.json +31 -0
- package/example-plugins/packages/client-slot-header-action/client.js +57 -0
- package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-header-action/index.js +13 -0
- package/example-plugins/packages/client-slot-header-action/package.json +31 -0
- package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
- package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
- package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
- package/example-plugins/packages/client-theme-override/client.js +52 -0
- package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-theme-override/index.js +9 -0
- package/example-plugins/packages/client-theme-override/package.json +30 -0
- package/example-plugins/packages/client-tool-view/client.js +47 -0
- package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-tool-view/index.js +24 -0
- package/example-plugins/packages/client-tool-view/package.json +34 -0
- package/example-plugins/packages/client-ui-components/client.js +77 -0
- package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-components/index.js +9 -0
- package/example-plugins/packages/client-ui-components/package.json +31 -0
- package/example-plugins/packages/client-ui-library/client.js +715 -0
- package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-ui-library/index.js +9 -0
- package/example-plugins/packages/client-ui-library/package.json +37 -0
- package/example-plugins/packages/client-workspace-tab/client.js +72 -0
- package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
- package/example-plugins/packages/client-workspace-tab/index.js +9 -0
- package/example-plugins/packages/client-workspace-tab/package.json +30 -0
- package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/config-schema-basic/index.js +19 -0
- package/example-plugins/packages/config-schema-basic/package.json +25 -0
- package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
- package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
- package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
- package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/event-hook-basic/index.js +17 -0
- package/example-plugins/packages/event-hook-basic/package.json +22 -0
- package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
- package/example-plugins/packages/generated-capability-template/index.js +16 -0
- package/example-plugins/packages/generated-capability-template/package.json +42 -0
- package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/host-route-basic/index.js +20 -0
- package/example-plugins/packages/host-route-basic/package.json +29 -0
- package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
- package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
- package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
- package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
- package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
- package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
- package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
- package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
- package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
- package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
- package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
- package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
- package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
- package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
- package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
- package/example-plugins/packages/service-provider-greeter/index.js +22 -0
- package/example-plugins/packages/service-provider-greeter/package.json +25 -0
- package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/settings-section-basic/index.js +34 -0
- package/example-plugins/packages/settings-section-basic/package.json +26 -0
- package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/skill-provider-basic/index.js +31 -0
- package/example-plugins/packages/skill-provider-basic/package.json +22 -0
- package/example-plugins/packages/state-host-store/client.js +57 -0
- package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-host-store/index.js +90 -0
- package/example-plugins/packages/state-host-store/package.json +31 -0
- package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
- package/example-plugins/packages/state-workspace-file/index.js +52 -0
- package/example-plugins/packages/state-workspace-file/package.json +25 -0
- package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-basic/index.js +25 -0
- package/example-plugins/packages/tool-basic/package.json +25 -0
- package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
- package/example-plugins/packages/tool-policy-hook/index.js +28 -0
- package/example-plugins/packages/tool-policy-hook/package.json +25 -0
- package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-command-basic/index.js +24 -0
- package/example-plugins/packages/tui-command-basic/package.json +22 -0
- package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
- package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
- package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
- package/example-plugins/packages/tui-ui-library/index.js +73 -0
- package/example-plugins/packages/tui-ui-library/package.json +29 -0
- package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
- package/example-plugins/packages/web-page-branding/index.js +31 -0
- package/example-plugins/packages/web-page-branding/package.json +22 -0
- package/example-plugins/scenarios.json +11 -0
- package/index.js +384 -0
- package/lib/blend-apply.js +107 -0
- package/lib/blend-capture.js +249 -0
- package/lib/blend-ledger.js +76 -0
- package/lib/contract.js +5 -0
- package/lib/install.js +516 -0
- package/lib/lookup.js +67 -0
- package/lib/manifest.js +56 -0
- package/lib/pack-root.js +22 -0
- package/lib/provenance.js +110 -0
- package/lib/publish.js +64 -0
- package/lib/reconcile.js +83 -0
- package/lib/router.js +55 -0
- package/lib/scopes.js +82 -0
- package/lib/skills.js +54 -0
- package/lib/stage.js +157 -0
- package/lib/verify.js +77 -0
- package/package.json +56 -3
- package/scripts/lib/indexes.mjs +45 -0
- package/scripts/lib/manifest.mjs +127 -0
- package/scripts/lib/maps.mjs +482 -0
- package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
- package/skills/acryl-add-ui/SKILL.md +18 -0
- package/skills/acryl-build-plugin/SKILL.md +21 -0
- package/skills/acryl-change-plugin/SKILL.md +16 -0
- package/skills/acryl-desktop-shell/SKILL.md +12 -0
- package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
- package/skills/acryl-fix-plugin/SKILL.md +12 -0
- package/skills/acryl-improve-ui/SKILL.md +10 -0
- package/skills/acryl-remove-plugin/SKILL.md +11 -0
- package/skills/acryl-restyle-ui/SKILL.md +14 -0
- package/skills/acryl-share-plugin/SKILL.md +23 -0
- package/skills/acryl-tui-ui/SKILL.md +12 -0
- package/README.md +0 -3
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
<!-- Synced from acryl:docs/cordisplugins/development-canvas-plugin.md @ 7968b4ff5d. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Development Canvas as a standalone Cordis plugin
|
|
4
|
+
|
|
5
|
+
Development Canvas follows the same law as the rest of ACRYL: **everything is a
|
|
6
|
+
plugin**. It is not a Desktop subpath, a Desktop child plugin, or unconditional
|
|
7
|
+
logic inside the Electron bootstrap.
|
|
8
|
+
|
|
9
|
+
**Provenance note**: the package has since been extracted out of this
|
|
10
|
+
workspace entirely (`acryldev/acryl-development-canvas` on GitHub, published
|
|
11
|
+
to npm) and is no longer a pnpm workspace member here - Desktop no longer
|
|
12
|
+
force-loads it by default. It is a Market-install-only plugin, same as any
|
|
13
|
+
third-party bundle. The design and Fiber-ownership description below still
|
|
14
|
+
holds; the `pnpm --filter acryl-development-canvas` commands referenced
|
|
15
|
+
further down only work from a checkout of that separate repo.
|
|
16
|
+
|
|
17
|
+
## Package and composition
|
|
18
|
+
|
|
19
|
+
Canvas owns the independent `acryl-development-canvas` PNPM workspace and
|
|
20
|
+
package. Its bundle patch contributes one stable Loader row:
|
|
21
|
+
|
|
22
|
+
```yaml
|
|
23
|
+
- id: acryl-development-canvas
|
|
24
|
+
name: acryl-development-canvas
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The package root is the Host plugin. The package also declares `dsh.client` and
|
|
28
|
+
exports `./client`, so the DSH Client module graph derives the browser plugin
|
|
29
|
+
from the same enabled Loader entry.
|
|
30
|
+
|
|
31
|
+
A profile patch can disable the whole capability without editing either
|
|
32
|
+
package:
|
|
33
|
+
|
|
34
|
+
```yaml
|
|
35
|
+
- id: acryl-development-canvas
|
|
36
|
+
disabled: true
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Host Fiber
|
|
40
|
+
|
|
41
|
+
`acryl-development-canvas/src/index.ts` hard-injects `webServer`. One
|
|
42
|
+
`ctx.effect()` owns the private PTY registry and all same-origin routes.
|
|
43
|
+
|
|
44
|
+
Activation is transactional. If any route registration fails, every earlier
|
|
45
|
+
registration is removed before the error escapes. Normal disposal removes
|
|
46
|
+
routes first and then awaits all PTY processes and subscriptions reaching
|
|
47
|
+
quiescence.
|
|
48
|
+
|
|
49
|
+
The PTY registry stays an internal module rather than becoming a Service. No
|
|
50
|
+
neighboring plugin consumes it, so exposing it would create a shallow,
|
|
51
|
+
hypothetical seam.
|
|
52
|
+
|
|
53
|
+
## Client Fiber and Desktop seam
|
|
54
|
+
|
|
55
|
+
Desktop owns only the advanced frame. That frame declares the single/root
|
|
56
|
+
`desktop.main` slot and contributes the upstream conversation at priority 100.
|
|
57
|
+
|
|
58
|
+
The independent Canvas Client plugin uses:
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
export const inject = ['slots']
|
|
62
|
+
|
|
63
|
+
ctx.slots.inject('desktop.main', () => {
|
|
64
|
+
// register Canvas at priority 0
|
|
65
|
+
// return cleanup for the slot, styles, and PTY client owner
|
|
66
|
+
})
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Canvas therefore wins while its Client Fiber and the slot declaration are both
|
|
70
|
+
live. Removing Canvas unregisters its priority-0 entry, and the Desktop
|
|
71
|
+
conversation fallback becomes visible automatically. There is no status route,
|
|
72
|
+
polling timer, global presence store, or React import from Desktop to Canvas.
|
|
73
|
+
|
|
74
|
+
The declaration effect owns a `CanvasPtyClient`. It tracks every Host session
|
|
75
|
+
opened by that Client activation. Disposal closes all tracked sessions and also
|
|
76
|
+
closes a late session whose asynchronous start settles during teardown.
|
|
77
|
+
|
|
78
|
+
## Current functional scope
|
|
79
|
+
|
|
80
|
+
One active tab fills the main content area. `+` opens terminal/agent, file, or
|
|
81
|
+
browser tabs. Terminal and agent tabs use `node-pty` with xterm.js rendering,
|
|
82
|
+
byte input, ANSI/alternate-screen support, and resize propagation.
|
|
83
|
+
|
|
84
|
+
The hardcoded coding-agent command list remains transitional transport R&D. It
|
|
85
|
+
must not become room identity, relay, resume, or orchestration. Those concerns
|
|
86
|
+
will use the later `acrAgentControl` capability.
|
|
87
|
+
|
|
88
|
+
File tabs remain an in-memory editor. Browser tabs remain sandboxed HTTP(S)
|
|
89
|
+
iframes. Neither limitation belongs in the Desktop shell.
|
|
90
|
+
|
|
91
|
+
## Lifecycle verification
|
|
92
|
+
|
|
93
|
+
The standalone package tests cover:
|
|
94
|
+
|
|
95
|
+
- Host plugin name and `inject` contract;
|
|
96
|
+
- rollback after partial route activation;
|
|
97
|
+
- route and process cleanup;
|
|
98
|
+
- real TTY allocation, byte input, and resize;
|
|
99
|
+
- Client-owned session cleanup, including late start settlement;
|
|
100
|
+
- Canvas priority replacing and then restoring the conversation fallback;
|
|
101
|
+
- tab state behavior.
|
|
102
|
+
|
|
103
|
+
Run:
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
corepack pnpm --filter acryl-development-canvas run check
|
|
107
|
+
corepack pnpm --filter acryl-desktop run verify:loader
|
|
108
|
+
corepack pnpm --filter acryl-desktop run verify:profile
|
|
109
|
+
```
|
|
@@ -0,0 +1,517 @@
|
|
|
1
|
+
<!-- Synced from acryl:docs/cordisplugins/hello-world-plugin-guide.md @ 043fa47bf8. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
|
|
2
|
+
|
|
3
|
+
# Hello World: a Cordis plugin for this DSH Desktop repository
|
|
4
|
+
|
|
5
|
+
> **Status:** R&D learning fixture and coding-agent onboarding material. This
|
|
6
|
+
> is not an ACRYL product feature or milestone.
|
|
7
|
+
|
|
8
|
+
This guide is the smallest practical path from one JavaScript module to a
|
|
9
|
+
profile-installed DSH plugin. It targets the versions pinned by this checkout:
|
|
10
|
+
DSH Desktop `2.0.2` and `@deepseek-ai/cordis` `4.0.1` (see the
|
|
11
|
+
[Desktop package manifest](../../acryl-desktop/package.json)). The pinned
|
|
12
|
+
DeepSeek Harness source is the authority when an ecosystem tutorial disagrees
|
|
13
|
+
with this guide.
|
|
14
|
+
|
|
15
|
+
That distinction matters: Harness vendors and locally hardens Cordis, and
|
|
16
|
+
renames its packages into the `@deepseek-ai/*` scope. Do not mechanically copy
|
|
17
|
+
examples that import `cordis`, import `@cordisjs/*`, or use an older `ctx.use`
|
|
18
|
+
API. The fork provenance and local modifications are recorded in the pinned
|
|
19
|
+
[vendor manifest](../../deepseek-harness/vendor/README.md); this checkout is at
|
|
20
|
+
[Harness source commit `b150a551b8d4`](https://github.com/deepseek-ai/deepseek-harness/tree/b150a551b8d465e31e418e1b2eaf5e79bbb7d28e).
|
|
21
|
+
|
|
22
|
+
## The model in one minute
|
|
23
|
+
|
|
24
|
+
A **plugin** is a lifecycle-managed module. In the common module form it
|
|
25
|
+
exports `apply(ctx, config?)`; the Loader calls `apply` when the plugin's hard
|
|
26
|
+
dependencies are available. A **bundle** is the installable npm package that
|
|
27
|
+
ships one configuration patch which inserts that plugin into a DSH
|
|
28
|
+
composition. A **profile** is the user's runnable, ordered list of bundles plus
|
|
29
|
+
its own final patch.
|
|
30
|
+
|
|
31
|
+
For an ordinary installable third-party plugin, these are separate things:
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
profile
|
|
35
|
+
-> lists bundle package in dsh.profile.bundles
|
|
36
|
+
-> bundle declares dsh.bundle.patch
|
|
37
|
+
-> cordis.patch.yml inserts a Loader row
|
|
38
|
+
-> Loader imports the plugin module
|
|
39
|
+
-> Cordis calls apply(ctx)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Desktop uses the same bundle and Loader contracts, but its launcher inserts the
|
|
43
|
+
Desktop-owned layer into each generation instead of persisting that package in
|
|
44
|
+
the user's bundle list. The three registration paths below must not be mixed.
|
|
45
|
+
|
|
46
|
+
## Path 1: one-off source overlay for learning
|
|
47
|
+
|
|
48
|
+
The [current official first-plugin tutorial](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)
|
|
49
|
+
creates a TypeScript source module and a separate overlay file:
|
|
50
|
+
|
|
51
|
+
```yaml
|
|
52
|
+
# scratch-plugin/cordis.yml
|
|
53
|
+
- insert:
|
|
54
|
+
- id: hello-world
|
|
55
|
+
name: '/absolute/path/to/acryl/scratch-plugin/src/my-plugin.ts'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
From the pinned `deepseek-harness/` source workspace, the tutorial launches the
|
|
59
|
+
Web profile with:
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
corepack pnpm dsh web --patch /absolute/path/to/acryl/scratch-plugin/cordis.yml
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
This is an ephemeral development overlay. It does not create a package, does
|
|
66
|
+
not add a dependency to a profile, and does not edit
|
|
67
|
+
`dsh.profile.bundles`. The module path must be absolute: the patch file's
|
|
68
|
+
location does not change the profile directory from which Loader module names
|
|
69
|
+
resolve. The pinned source says the same in the
|
|
70
|
+
[first Harness plugin walkthrough](../../deepseek-harness/docs/user/develop/basic/index.md).
|
|
71
|
+
|
|
72
|
+
Use this path to prove `apply(ctx)` runs. Use Path 2 when the plugin should be
|
|
73
|
+
installed, removed, updated, or shared.
|
|
74
|
+
|
|
75
|
+
## Path 2: ordinary third-party bundle and profile registration
|
|
76
|
+
|
|
77
|
+
Use plain ESM JavaScript for the first exercise. It avoids a build step and
|
|
78
|
+
makes the actual runtime contract visible.
|
|
79
|
+
|
|
80
|
+
```text
|
|
81
|
+
dsh-hello-world/
|
|
82
|
+
├── package.json
|
|
83
|
+
├── index.js
|
|
84
|
+
└── cordis.patch.yml
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`package.json`:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"name": "dsh-hello-world",
|
|
92
|
+
"version": "0.1.0",
|
|
93
|
+
"private": true,
|
|
94
|
+
"type": "module",
|
|
95
|
+
"main": "./index.js",
|
|
96
|
+
"exports": "./index.js",
|
|
97
|
+
"files": ["index.js", "cordis.patch.yml"],
|
|
98
|
+
"dsh": {
|
|
99
|
+
"bundle": {
|
|
100
|
+
"patch": "./cordis.patch.yml"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`index.js`:
|
|
107
|
+
|
|
108
|
+
```js
|
|
109
|
+
export const name = 'hello-world'
|
|
110
|
+
|
|
111
|
+
export function apply(ctx) {
|
|
112
|
+
ctx.logger.info('[hello-world] Hello from Cordis!')
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
`cordis.patch.yml`:
|
|
117
|
+
|
|
118
|
+
```yaml
|
|
119
|
+
- insert:
|
|
120
|
+
- id: hello-world
|
|
121
|
+
name: dsh-hello-world
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
That is a complete Host plugin bundle. `name` in `index.js` is optional
|
|
125
|
+
diagnostic metadata. The row's `name` is the package specifier that the Loader
|
|
126
|
+
imports. Keep the row `id` stable and distinctive so later patches and HMR can
|
|
127
|
+
identify it. The exact three-file shape is also the one taught by the pinned
|
|
128
|
+
[DSH publishing tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md).
|
|
129
|
+
|
|
130
|
+
Do not omit `dsh.bundle.patch`. A package without that declaration can be
|
|
131
|
+
installed as a plain dependency, but `dsh plugin` will not add it as an active
|
|
132
|
+
profile layer. Also ship the referenced patch in `files`; a manifest that
|
|
133
|
+
points at a file excluded from the tarball is not a usable bundle.
|
|
134
|
+
|
|
135
|
+
### Run it in the current Desktop setup
|
|
136
|
+
|
|
137
|
+
The outer repository is a Yarn 4 workspace; the pinned
|
|
138
|
+
`deepseek-harness/` checkout remains its own pnpm workspace. From the repository
|
|
139
|
+
root, prepare the supported toolchains and build Desktop with the root scripts:
|
|
140
|
+
|
|
141
|
+
```sh
|
|
142
|
+
corepack pnpm install --frozen-lockfile
|
|
143
|
+
corepack pnpm upstream:install
|
|
144
|
+
corepack pnpm upstream:build
|
|
145
|
+
corepack pnpm build
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Start the graphical application only when you intend to open it:
|
|
149
|
+
|
|
150
|
+
```sh
|
|
151
|
+
corepack pnpm dev
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
In DSH Desktop, choose **Open DSH Terminal**. That terminal supplies the pinned
|
|
155
|
+
`dsh`, `pnpm`, and Node shims and defaults bare plugin commands to the active
|
|
156
|
+
profile. From the directory containing `dsh-hello-world/`, run:
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
dsh plugin add ./dsh-hello-world
|
|
160
|
+
dsh --dump-config
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The dump should contain the `dsh-hello-world` layer and the `hello-world` row.
|
|
164
|
+
Restart Desktop after adding, removing, or updating a bundle; bundle membership
|
|
165
|
+
is fixed for a running generation. Then inspect the Desktop log for
|
|
166
|
+
`[hello-world] Hello from Cordis!`. Remove the exercise with:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
dsh plugin remove dsh-hello-world
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
An explicit profile is equivalent when using an ordinary DSH terminal:
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
dsh plugin --profile desktop add ./dsh-hello-world
|
|
176
|
+
dsh --profile desktop --dump-config
|
|
177
|
+
dsh plugin --profile desktop remove dsh-hello-world
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
The product command deliberately forwards package work to pnpm in the selected
|
|
181
|
+
profile and reconciles `dsh.profile.bundles`; do not replace it with `pnpm add`
|
|
182
|
+
in the outer PNPM workspace. Relative `file:`/`link:` paths are anchored to the
|
|
183
|
+
directory in which `dsh plugin` was invoked. The implementation is documented
|
|
184
|
+
in the pinned [CLI reference](../../deepseek-harness/apps/cli/reference/README.md)
|
|
185
|
+
and [plugin command source](../../deepseek-harness/apps/cli/src/plugin.ts).
|
|
186
|
+
|
|
187
|
+
For a headless repository confidence check, run the existing complete profile
|
|
188
|
+
Loader smoke (it uses a real profile-local third-party package fixture and does
|
|
189
|
+
not open Electron):
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
corepack pnpm --filter acryl-desktop run build
|
|
193
|
+
corepack pnpm --filter acryl-desktop run verify:profile
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
That smoke validates the current Desktop composition and public Host services;
|
|
197
|
+
it does not replace a focused test for the behavior of your own plugin. See the
|
|
198
|
+
[fixture](../../acryl-desktop/tests/fixtures/desktop-host-services-smoke-plugin/index.js)
|
|
199
|
+
and [smoke runner](../../acryl-desktop/scripts/verify-profile-boot.mjs).
|
|
200
|
+
|
|
201
|
+
## Path 3: ACRYL Desktop's built-in registration
|
|
202
|
+
|
|
203
|
+
This repository's Desktop shell is not discovered through a special Electron
|
|
204
|
+
plugin registry. It is registered through normal DSH package and Cordis
|
|
205
|
+
surfaces:
|
|
206
|
+
|
|
207
|
+
1. The package export `acryl-desktop` maps to `lib/index.js`, whose source
|
|
208
|
+
is [src/index.ts](../../acryl-desktop/src/index.ts) and exports the Host
|
|
209
|
+
plugin's `name`, `inject`, schema, and `apply(ctx, config)`.
|
|
210
|
+
2. The package manifest declares
|
|
211
|
+
`"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` and ships the
|
|
212
|
+
patch; see [package.json](../../acryl-desktop/package.json).
|
|
213
|
+
3. [cordis.patch.yml](../../acryl-desktop/cordis.patch.yml) inserts the
|
|
214
|
+
`desktop-shell` row with `name: acryl-desktop`, plus the Desktop-owned
|
|
215
|
+
Hello World, terminal, development-canvas, diagnostics, notification, pnpm,
|
|
216
|
+
profile, and update rows through exported package subpaths. The learning
|
|
217
|
+
proof is implemented by
|
|
218
|
+
[src/hello-world.ts](../../acryl-desktop/src/hello-world.ts), exported
|
|
219
|
+
as `acryl-desktop/hello-world`, and registered under the stable
|
|
220
|
+
`desktop-hello-world` row.
|
|
221
|
+
4. During profile preparation, the launcher reads that patch and inserts it
|
|
222
|
+
immediately after `@deepseek-ai/dsh-web-app`; it does not persist the
|
|
223
|
+
Desktop package into the selected profile's bundle list. See the exact
|
|
224
|
+
composition in [profile.ts](../../acryl-desktop/src/profile.ts).
|
|
225
|
+
|
|
226
|
+
The Host row is part of both compatibility and advanced generations. The
|
|
227
|
+
package also declares an ordinary Web Client face exported at `./client`.
|
|
228
|
+
Its [Client entry](../../acryl-desktop/src/client/index.ts) registers the
|
|
229
|
+
shared Desktop contributions in both modes and mounts the Desktop-owned layout
|
|
230
|
+
and root presentation only when `environment.mode === 'advanced'`. Thus mode
|
|
231
|
+
changes presentation composition, not the Cordis plugin contract.
|
|
232
|
+
|
|
233
|
+
Electron changes the **launch path**: it selects a profile, provides
|
|
234
|
+
generation-scoped native services, boots the Host root, and loads the ordinary
|
|
235
|
+
loopback Web surface in a sandboxed BrowserWindow. It does not change how a
|
|
236
|
+
plugin declares `apply`, config, `inject`, services, effects, package exports,
|
|
237
|
+
or Loader rows. Third-party Host plugins and Web Client modules therefore keep
|
|
238
|
+
using standard DSH contracts in both modes. The repository
|
|
239
|
+
[Desktop architecture](../architecture.md) and
|
|
240
|
+
[package architecture](../../acryl-desktop/README.md) own this boundary.
|
|
241
|
+
|
|
242
|
+
### Compatibility requirements for a future ACRYL rename
|
|
243
|
+
|
|
244
|
+
A future product/package rename should treat the DSH composition format as a
|
|
245
|
+
compatibility contract, not as branding to rewrite freely. Retain:
|
|
246
|
+
|
|
247
|
+
- the `dsh.bundle.patch` manifest shape and a shipped patch file;
|
|
248
|
+
- loadable package exports for every module specifier named by patch rows;
|
|
249
|
+
- coherent `dsh.client` metadata and a loadable `./client` export for the
|
|
250
|
+
browser face;
|
|
251
|
+
- stable Loader row ids, because user and home patches address those ids;
|
|
252
|
+
- `dsh.profile.bundles`, profile-local dependencies, layer order, and ordinary
|
|
253
|
+
`dsh plugin` reconciliation semantics;
|
|
254
|
+
- migration or compatibility aliases for persisted old package names and patch
|
|
255
|
+
module specifiers if the npm identity changes;
|
|
256
|
+
- compatibility exports for the public `profile-service` and `pnpm` contract
|
|
257
|
+
paths while third-party consumers migrate.
|
|
258
|
+
|
|
259
|
+
In other words, ACRYL may rename the application and its package, but an existing
|
|
260
|
+
profile must still resolve its recorded bundle identities and every exported
|
|
261
|
+
specifier referenced by the effective patch-or be migrated explicitly before
|
|
262
|
+
boot. Do not invent an ACRYL-only plugin manifest. The pinned
|
|
263
|
+
[profile implementation](../../deepseek-harness/packages/boot/app-boot/src/profile.ts),
|
|
264
|
+
[plugin command](../../deepseek-harness/apps/cli/src/plugin.ts), and
|
|
265
|
+
[publishing tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md)
|
|
266
|
+
define the compatibility surface to preserve.
|
|
267
|
+
|
|
268
|
+
## Lifecycle rule: every effect must reverse
|
|
269
|
+
|
|
270
|
+
The Hello World module acquires no external resource, so it needs no disposer.
|
|
271
|
+
As soon as a plugin starts a timer, watcher, socket, subprocess, external
|
|
272
|
+
subscription, or native registration, acquire it inside `ctx.effect()` and
|
|
273
|
+
return its cleanup:
|
|
274
|
+
|
|
275
|
+
```js
|
|
276
|
+
export const name = 'hello-heartbeat'
|
|
277
|
+
|
|
278
|
+
export function apply(ctx) {
|
|
279
|
+
ctx.effect(() => {
|
|
280
|
+
const timer = setInterval(() => {
|
|
281
|
+
ctx.logger.info('[hello-heartbeat] still active')
|
|
282
|
+
}, 5_000)
|
|
283
|
+
|
|
284
|
+
return () => clearInterval(timer)
|
|
285
|
+
}, 'hello-world heartbeat')
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Cordis-owned registrations such as `ctx.on(...)`, child plugins created with
|
|
290
|
+
`ctx.plugin(...)`, and services are already effects. Raw platform resources are
|
|
291
|
+
not. A plugin can unload during HMR, a patch edit, generation shutdown, or loss
|
|
292
|
+
of a required service; cleanup must work in every case. If teardown operations
|
|
293
|
+
must be ordered, keep them in one async disposer and await them in sequence,
|
|
294
|
+
because separate async disposers may run concurrently. The pinned
|
|
295
|
+
[lifecycle tutorial](../../deepseek-harness/docs/cordis-tutorial/02-lifecycle-and-effects.md)
|
|
296
|
+
defines these semantics.
|
|
297
|
+
|
|
298
|
+
## Services and `inject` are different concepts
|
|
299
|
+
|
|
300
|
+
A **service** is a named callable capability supplied by a provider. `inject`
|
|
301
|
+
is a consumer's declaration that one or more services are hard dependencies.
|
|
302
|
+
It is not a startup-order hint.
|
|
303
|
+
|
|
304
|
+
```js
|
|
305
|
+
// Consumer plugin
|
|
306
|
+
export const name = 'hello-consumer'
|
|
307
|
+
export const inject = ['greeter']
|
|
308
|
+
|
|
309
|
+
export function apply(ctx) {
|
|
310
|
+
ctx.logger.info(ctx.greeter.greet('ACRYL'))
|
|
311
|
+
}
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Cordis keeps this consumer `PENDING` until a provider registers `greeter`.
|
|
315
|
+
Inside `apply`, `ctx.greeter` is therefore available. If the provider later
|
|
316
|
+
unloads, Cordis unloads the consumer and reverses its effects; if the service
|
|
317
|
+
returns, the consumer activates again. Loader row order does not provide this
|
|
318
|
+
guarantee-service availability does. For a capability the plugin can live
|
|
319
|
+
without, omit it from `inject` and probe it at the use site:
|
|
320
|
+
|
|
321
|
+
```js
|
|
322
|
+
export function apply(ctx) {
|
|
323
|
+
const metrics = ctx.get('metrics')
|
|
324
|
+
metrics?.record('hello_world_loaded', 1)
|
|
325
|
+
}
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Use a service when another plugin needs to invoke a stable capability. Use an
|
|
329
|
+
event when other plugins only need to observe or intercept something without a
|
|
330
|
+
direct capability call. Prefer a `Service` subclass when publishing a typed,
|
|
331
|
+
callable API; declaration merging supplies TypeScript safety, while the runtime
|
|
332
|
+
service registration supplies the capability. The complete provider/consumer
|
|
333
|
+
pattern is in the pinned [services tutorial](../../deepseek-harness/docs/cordis-tutorial/03-services.md).
|
|
334
|
+
|
|
335
|
+
Do not access `ctx.someService` without declaring it as a hard injection.
|
|
336
|
+
Cordis's guard may reject undeclared service access. Conversely, do not add an
|
|
337
|
+
optional service to `inject` merely to avoid an `undefined` check: doing so can
|
|
338
|
+
turn an otherwise healthy plugin into a permanently pending one.
|
|
339
|
+
|
|
340
|
+
## Optional typed configuration
|
|
341
|
+
|
|
342
|
+
The zero-config Hello World is the right first plugin. When deployments need a
|
|
343
|
+
tunable greeting, export a TypeScript `Config` type and a same-named
|
|
344
|
+
Schemastery schema; Cordis validates the row config and fills schema defaults
|
|
345
|
+
before `apply` runs:
|
|
346
|
+
|
|
347
|
+
```ts
|
|
348
|
+
import type { Context } from '@deepseek-ai/cordis'
|
|
349
|
+
import Schema from '@deepseek-ai/schemastery'
|
|
350
|
+
|
|
351
|
+
export interface Config {
|
|
352
|
+
greeting: string
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
export const Config: Schema<Config> = Schema.object({
|
|
356
|
+
greeting: Schema.string().default('Hello from Cordis!'),
|
|
357
|
+
})
|
|
358
|
+
|
|
359
|
+
export function apply(ctx: Context, config: Config): void {
|
|
360
|
+
ctx.logger.info(`[hello-world] ${config.greeting}`)
|
|
361
|
+
}
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
```yaml
|
|
365
|
+
- insert:
|
|
366
|
+
- id: hello-world
|
|
367
|
+
name: dsh-hello-world
|
|
368
|
+
config:
|
|
369
|
+
greeting: Hello from ACRYL!
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Do not export a plain object under `Config`; Cordis expects a Standard
|
|
373
|
+
Schema-compatible schema. A TypeScript package must publish built JavaScript
|
|
374
|
+
and declarations. A Git install fetches source, so its `prepare` build requires
|
|
375
|
+
an explicit pnpm `allowBuilds` grant; an npm release or built tarball avoids
|
|
376
|
+
that install-time build. See the pinned
|
|
377
|
+
[configuration guide](../../deepseek-harness/docs/user/develop/basic/config.md)
|
|
378
|
+
and [publishing guide](../../deepseek-harness/docs/user/develop/basic/publish.md).
|
|
379
|
+
|
|
380
|
+
## `cordis.patch.yml`, bundles, and profile layers
|
|
381
|
+
|
|
382
|
+
For an installed plugin, `cordis.patch.yml` belongs to the **bundle** and the
|
|
383
|
+
bundle's `package.json` points to it through `dsh.bundle.patch`. `dsh plugin`
|
|
384
|
+
then adds the package to the selected profile's ordered
|
|
385
|
+
`dsh.profile.bundles`. The effective DSH configuration applies:
|
|
386
|
+
|
|
387
|
+
1. bundle patches in profile order;
|
|
388
|
+
2. the profile's own `cordis.patch.yml`;
|
|
389
|
+
3. `$DSH_HOME/cordis.patch.yml`;
|
|
390
|
+
4. explicit `--patch` overlays in command-line order.
|
|
391
|
+
|
|
392
|
+
Later layers win per Loader row. A patch replaces a row's complete `config`
|
|
393
|
+
value rather than deep-merging it, so an override must restate every config key
|
|
394
|
+
that row still needs. In this Desktop, the launcher prepares the chosen Web
|
|
395
|
+
profile, keeps third-party bundle order, inserts the Desktop layer into the
|
|
396
|
+
generation, and boots from an empty include root; the exact implementation is
|
|
397
|
+
in [profile.ts](../../acryl-desktop/src/profile.ts).
|
|
398
|
+
|
|
399
|
+
## Failure diagnostics
|
|
400
|
+
|
|
401
|
+
### The plugin prints nothing
|
|
402
|
+
|
|
403
|
+
First run `dsh --dump-config` for the active profile.
|
|
404
|
+
|
|
405
|
+
- No bundle layer: verify `package.json` contains a valid `dsh.bundle.patch`,
|
|
406
|
+
the patch is shipped, and the package appears in the profile's
|
|
407
|
+
`dsh.profile.bundles`. Install through `dsh plugin`, not raw root PNPM.
|
|
408
|
+
- Layer exists but row is absent: check the YAML patch shape and row `id`.
|
|
409
|
+
- Row exists but module is unresolved: check the exact package/path spelling
|
|
410
|
+
and package exports. A resolution error can occur before a console logger is
|
|
411
|
+
observing startup, so “no message” is not proof the module loaded.
|
|
412
|
+
- Row is disabled: inspect later profile, home, and `--patch` layers.
|
|
413
|
+
- Bundle was just added/removed/updated: restart the profile generation.
|
|
414
|
+
|
|
415
|
+
### The fiber is `PENDING`
|
|
416
|
+
|
|
417
|
+
`PENDING` is a valid lifecycle state: at least one hard injected service is not
|
|
418
|
+
available yet. It is not fixed by moving the row earlier in YAML. Compare every
|
|
419
|
+
name in `inject` with an actual provider in the same service realm. Remove an
|
|
420
|
+
injection only if the capability is truly optional; otherwise mount the correct
|
|
421
|
+
provider. A pending fiber does not keep Node alive, so an otherwise empty
|
|
422
|
+
headless composition can exit successfully without running `apply`.
|
|
423
|
+
|
|
424
|
+
For a focused diagnosis, temporarily add a diagnostic plugin that enumerates
|
|
425
|
+
`ctx.registry`, checks `fiber.state === FiberState.PENDING`, and prints the
|
|
426
|
+
fiber names. The pinned
|
|
427
|
+
[composition/HMR tutorial](../../deepseek-harness/docs/cordis-tutorial/06-composition-and-hmr.md)
|
|
428
|
+
contains a runnable diagnostic. In an agent profile that explicitly composes
|
|
429
|
+
the optional Cordis inspection toolset, use its advertised read-only inspect
|
|
430
|
+
providers; do not assume those tools exist in every shipped profile.
|
|
431
|
+
|
|
432
|
+
### The fiber is `FAILED`
|
|
433
|
+
|
|
434
|
+
`apply` threw, configuration validation failed, a service name collided, or
|
|
435
|
+
the composed rows are invalid. Read the first cause, not only the later
|
|
436
|
+
dependent `PENDING` symptoms. Common causes are a plain-object `Config`, an
|
|
437
|
+
undeclared `ctx.service` access, duplicate Loader row ids, or two providers
|
|
438
|
+
publishing the same non-isolated service name. Desktop rejects duplicate row
|
|
439
|
+
ids before boot; choose a package-qualified id rather than overwriting another
|
|
440
|
+
plugin accidentally.
|
|
441
|
+
|
|
442
|
+
### It works once, then duplicates behavior after reload
|
|
443
|
+
|
|
444
|
+
The plugin created process/page state outside `apply`, or acquired an external
|
|
445
|
+
resource without an effect disposer. Move acquisition into `ctx.effect()` and
|
|
446
|
+
make cleanup idempotent. Never retain a Desktop service, BrowserWindow, timer,
|
|
447
|
+
or subprocess handle across a generation restart.
|
|
448
|
+
|
|
449
|
+
### It works in Desktop but not ordinary DSH-or the reverse
|
|
450
|
+
|
|
451
|
+
The only supported third-party Desktop Host services are `desktopProfiles` and
|
|
452
|
+
`desktopPnpm`, exported by `acryl-desktop/profile-service` and
|
|
453
|
+
`acryl-desktop/pnpm`. A Desktop-only plugin may hard-inject them. A plugin
|
|
454
|
+
that must also run under ordinary DSH should detect `desktopProfiles` with
|
|
455
|
+
`ctx.get(...)` and mount its Desktop adapter inside a nested
|
|
456
|
+
`ctx.inject(['desktopPnpm'], ...)`, while retaining an ordinary DSH fallback.
|
|
457
|
+
Do not infer the Desktop profile from argv, settings, a URL, or `$DSH_HOME`.
|
|
458
|
+
The exact supported boundary and teardown semantics are in the
|
|
459
|
+
[Desktop plugin-service contract](../../acryl-desktop/docs/plugin-services.md)
|
|
460
|
+
and the repository's [plugin-development note](../plugin-development.md).
|
|
461
|
+
|
|
462
|
+
## Current contracts versus proposals
|
|
463
|
+
|
|
464
|
+
Safe dependencies for a plugin in this checkout are:
|
|
465
|
+
|
|
466
|
+
- the pinned `@deepseek-ai/cordis` plugin, lifecycle, service, injection,
|
|
467
|
+
event, and Loader contracts;
|
|
468
|
+
- DSH package contracts documented by the pinned source;
|
|
469
|
+
- normal `dsh.bundle`, profile, and patch semantics;
|
|
470
|
+
- for Desktop-specific Host code, only `desktopProfiles` and `desktopPnpm` as
|
|
471
|
+
documented above;
|
|
472
|
+
- for browser UI, ordinary DSH Host routes/RPC plus Web Client metadata,
|
|
473
|
+
services, and slots-not Electron APIs or a new renderer IPC system.
|
|
474
|
+
|
|
475
|
+
Do **not** code against the proposed Community Fabric manifest, Host Descriptor,
|
|
476
|
+
capability negotiation, unified event vocabulary, compatibility badge, effect
|
|
477
|
+
ledger, or conformance API. Community Fabric is currently a documentation-only
|
|
478
|
+
RFC with no runtime, SDK, or released schema in this workspace; working plugins
|
|
479
|
+
still use existing DSH/Cordis APIs. See its explicit
|
|
480
|
+
[status statement](../../dsh-community-fabric/README.md).
|
|
481
|
+
|
|
482
|
+
The Community Market is a real Desktop component, but catalog membership is
|
|
483
|
+
discovery metadata-not proof of safety or compatibility. Its current boundary
|
|
484
|
+
and the reviewed dshfind/1024Store adapters are documented in the
|
|
485
|
+
[Market README](../../cordis-plugin-market/README.md). The public
|
|
486
|
+
[dshfind repository](https://github.com/hikariming/dshfind) describes a catalog
|
|
487
|
+
generated from the `dsh-plugin` GitHub topic, while
|
|
488
|
+
[DSH 1024Store](https://github.com/imsai-sh/awesome-deepseek-harness-plugins)
|
|
489
|
+
checks basic repository structure such as `package.json`, `dsh.bundle`, and the
|
|
490
|
+
declared patch path. Its own contribution contract explicitly describes this
|
|
491
|
+
as static validation rather than runtime or security validation
|
|
492
|
+
([catalog contribution rules](https://github.com/imsai-sh/awesome-deepseek-harness-plugins/blob/90e3f5852663daa116ca310518eb8c01dec56151/CONTRIBUTING.md)).
|
|
493
|
+
Use [dshfind.com](https://dshfind.com/en) and
|
|
494
|
+
[deepseek1024.com](https://deepseek1024.com) to discover candidates, then
|
|
495
|
+
inspect the candidate's source, exact version, lifecycle scripts, bundle
|
|
496
|
+
manifest, patch, dependencies, and compatibility before installing it.
|
|
497
|
+
Directory inclusion is neither a security audit nor a replacement for the
|
|
498
|
+
pinned DSH contracts. In particular, dshfind learning material currently
|
|
499
|
+
contains examples from a different Cordis/API snapshot; treat it as conceptual
|
|
500
|
+
secondary reading and translate every technical detail back to the pinned DSH
|
|
501
|
+
source.
|
|
502
|
+
|
|
503
|
+
## Primary references used
|
|
504
|
+
|
|
505
|
+
- [Current official first-plugin tutorial](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)
|
|
506
|
+
- [Pinned first Harness plugin](../../deepseek-harness/docs/user/develop/basic/index.md)
|
|
507
|
+
- [Pinned package-and-profile tutorial](../../deepseek-harness/docs/user/develop/basic/publish.md)
|
|
508
|
+
- [Pinned Cordis first-plugin tutorial](../../deepseek-harness/docs/cordis-tutorial/01-first-plugin.md)
|
|
509
|
+
- [Pinned lifecycle/effects tutorial](../../deepseek-harness/docs/cordis-tutorial/02-lifecycle-and-effects.md)
|
|
510
|
+
- [Pinned services tutorial](../../deepseek-harness/docs/cordis-tutorial/03-services.md)
|
|
511
|
+
- [Pinned Loader implementation notes](../../deepseek-harness/vendor/loader/README.md)
|
|
512
|
+
- [Repository Cordis architecture specification](../cordis/cordis_spec.md)
|
|
513
|
+
- [Desktop public plugin services](../../acryl-desktop/docs/plugin-services.md)
|
|
514
|
+
|
|
515
|
+
Repository discovery for this guide used direct source reads because the
|
|
516
|
+
codebase knowledge graph was unavailable. No file under the pinned
|
|
517
|
+
`deepseek-harness/` checkout was modified.
|