@linkdesk/plugin-docs 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/README.md +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
- package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
- package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
- package/docs/zh/plugin.schema.json +687 -0
- package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
- package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
- package/package.json +20 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# 04 — Data Pipeline Command Conventions
|
|
2
|
+
|
|
3
|
+
> **Type: shell-level** — reference document defining the command ID format convention | 2026-07-26. **Settle this before writing any protocol/card plugin.** Command ID format, argument conventions, return format — once fixed they can't be changed casually; changing them is an API break.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Pipeline model
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Slider card drag
|
|
11
|
+
→ protocol.encode(value)
|
|
12
|
+
→ terminal.sendBytes(bytes)
|
|
13
|
+
→ MCU receives → computes → sends back
|
|
14
|
+
→ terminal.receiveData(raw)
|
|
15
|
+
→ protocol.parse(raw)
|
|
16
|
+
→ waveform card updates
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Three roles: **data source** (terminal/serial/network) → **protocol** (encode/decode) → **card** (UI widget).
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Command ID format
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
<pluginId>.<action>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
| Role | Command | Example |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| Data source | `<pluginId>.sendBytes` | `terminal.sendBytes` |
|
|
32
|
+
| Data source | `<pluginId>.onData` (event) | `terminal.onData` |
|
|
33
|
+
| Protocol | `<pluginId>.encode` | `bracket.encode` |
|
|
34
|
+
| Protocol | `<pluginId>.parse` | `bracket.parse` |
|
|
35
|
+
| Protocol | `<pluginId>.decode` | `modbus.decode` |
|
|
36
|
+
|
|
37
|
+
**Rules:**
|
|
38
|
+
- Prefix = plugin ID (the `id` field in `plugin.json`)
|
|
39
|
+
- Action name = a verb (`sendBytes` / `encode` / `parse` / `decode`)
|
|
40
|
+
- A data source is not named `send` — too vague. Byte-level push is `sendBytes`
|
|
41
|
+
- `onData` is an event (Emitter), not a command — it goes through CoreEvents rather than the CommandRegistry. It is listed here only for naming consistency
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## Argument formats
|
|
46
|
+
|
|
47
|
+
### sendBytes — a data source sends bytes
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
// request
|
|
51
|
+
{
|
|
52
|
+
channel: number, // channel / serial port number
|
|
53
|
+
bytes: number[], // raw bytes to send
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// response
|
|
57
|
+
{
|
|
58
|
+
success: boolean,
|
|
59
|
+
error?: string, // failure reason (e.g. "port closed")
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### encode — protocol encoding (value → bytes)
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
// request
|
|
67
|
+
{
|
|
68
|
+
channel: number,
|
|
69
|
+
value: number, // application-layer value (e.g. slider 0-100)
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// response
|
|
73
|
+
{
|
|
74
|
+
success: boolean,
|
|
75
|
+
bytes?: number[], // the encoded bytes
|
|
76
|
+
error?: string,
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### parse / decode — protocol parsing (bytes → value)
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
// request
|
|
84
|
+
{
|
|
85
|
+
channel: number,
|
|
86
|
+
bytes: number[], // raw bytes
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// response
|
|
90
|
+
{
|
|
91
|
+
success: boolean,
|
|
92
|
+
value?: number, // the parsed application-layer value
|
|
93
|
+
fields?: Record<string, unknown>, // structured fields (e.g. { temp: 25.3, humidity: 60 })
|
|
94
|
+
error?: string,
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Card update — extended form
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
// request
|
|
102
|
+
{
|
|
103
|
+
cardId: string, // card instance ID
|
|
104
|
+
fields: Record<string, unknown>, // field → value mapping
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// response
|
|
108
|
+
{
|
|
109
|
+
success: boolean,
|
|
110
|
+
error?: string,
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Result format — one unified envelope
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
interface PipelineResult {
|
|
120
|
+
success: boolean;
|
|
121
|
+
error?: string; // human-readable and short — good for a toast
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**Rules:**
|
|
126
|
+
- All pipeline commands return `PipelineResult` or a subtype of it
|
|
127
|
+
- When `success = false`, `error` is required
|
|
128
|
+
- `error` is a short human-readable string — not a stack trace, not a code
|
|
129
|
+
- The concrete data fields (`bytes` / `value` / `fields`) are only guaranteed to exist when `success = true`
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## How to register
|
|
134
|
+
|
|
135
|
+
Plugins declare them in `contributes.commands`:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"contributes": {
|
|
140
|
+
"commands": [
|
|
141
|
+
{ "id": "bracket.encode", "title": "Bracket Protocol: Encode" },
|
|
142
|
+
{ "id": "bracket.parse", "title": "Bracket Protocol: Parse" }
|
|
143
|
+
]
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Callers use `executeCommand`:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
const result = await executeCommand("bracket.encode", {
|
|
152
|
+
channel: 1,
|
|
153
|
+
value: 75,
|
|
154
|
+
}) as PipelineResult & { bytes?: number[] };
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## Why settle it now
|
|
160
|
+
|
|
161
|
+
| Not settled | Settled |
|
|
162
|
+
|---|---|
|
|
163
|
+
| AI A writes `terminal.send`, AI B writes `serial.pushBytes` — they don't connect | Every data source is named `sendBytes` — the pipeline connects automatically |
|
|
164
|
+
| Everyone invents their own return format — `{ ok }` vs `{ success }` vs throw | One unified envelope — callers don't have to guess |
|
|
165
|
+
| A card doesn't know whether the protocol returns `value` or `fields` | The convention is explicit — an AI reading this document knows how to consume it |
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Not registered as core commands
|
|
170
|
+
|
|
171
|
+
These commands are **not registered in `coreCommands.ts`** — the core doesn't know that protocols/terminals/cards exist. They are registered by their respective plugins and discover each other through the CommandRegistry. The core only provides the CommandRegistry table.
|
|
172
|
+
|
|
173
|
+
> **← 07 index:** `00-readme.md`
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Multi-Repo Development and the Local Workspace
|
|
2
|
+
|
|
3
|
+
> 2026-09-14 · **Answers three questions: where should my plugin project live? What should the repo be called? How do I change the display name?**
|
|
4
|
+
> Every item comes with its "why" — this document's readers include future AIs, and if it only says "how", they will rewrite it in the next session according to their own understanding. The authoritative text for naming rules (character sets and mutability of the id / version / distribution artifact name) → [16-naming-conventions](16-naming-conventions.md); this document does not duplicate it.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. Local directory convention — collect projects into a container, grouped by ownership
|
|
9
|
+
|
|
10
|
+
**Recommended layout**: collect all plugin projects into **one container directory** (suggested: `E:\linkdesk-plugins\`), split internally into two folders by **ownership**:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
E:\linkdesk-plugins\
|
|
14
|
+
├─ official\ ← your own plugins (the 18 official ones + later new plugins)
|
|
15
|
+
│ ├─ file-tree\
|
|
16
|
+
│ └─ settings\
|
|
17
|
+
└─ third-party\ ← other people's plugins (cloned to study / fork)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**Why by ownership and not by function**: ownership is stable (a plugin never goes from official to third-party), whereas functional categories get redrawn again and again as plugins are added; and the marketplace catalog's `category` is already doing functional classification, so classifying a second time locally is duplicated work.
|
|
21
|
+
|
|
22
|
+
**Why collect them into a container**: without it they sprawl flat (`E:\linkdesk-build+scratch\` currently holds two of them), you can't find them, backups miss them, and an inbound AI doesn't know where to look.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 2. 🔴 The container directory itself must never be a repo
|
|
27
|
+
|
|
28
|
+
`E:\linkdesk-plugins\` should **never be `git init`-ed**. This isn't fastidiousness — once the container is made into a repository, three bad things happen automatically:
|
|
29
|
+
|
|
30
|
+
1. **Each plugin's `.git` becomes a nested repo**, and the parent repo records them as gitlinks — **it breaks silently and is extremely hard to spot** (whoever clones the container gets empty directories).
|
|
31
|
+
2. **The scaffold's rule is inverted into a disaster**: `create-linkdesk-plugin` checks "already inside a git repo → don't init", so once the container is a repo, **no new plugin creates its own repo** — they all become subdirectories of the container, producing exactly the monorepo you wanted to avoid.
|
|
32
|
+
3. The triggers are impossible to defend against completely: the IDE's "initialize repository" prompt, running `git init` at the wrong level, or `git add .` from a parent directory can all trip it.
|
|
33
|
+
|
|
34
|
+
**Guardrail**: put a note in the container (`README.md` or `DO-NOT-INIT-A-REPO-HERE.txt`) — it's not only for the author himself, but also for AIs that come in later and read the directory.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 3. Repository names are completely free (D5/N2)
|
|
39
|
+
|
|
40
|
+
**Repository names are not forced to carry any prefix; third parties have zero constraints.** This has been settled by the maintainer: naming your own plugin (repo) is a legitimate right of the author and can't be dictated.
|
|
41
|
+
|
|
42
|
+
- **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (N3 pending the user's sign-off; once signed off, the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — maintained in that one place only); third parties may do as they please.
|
|
43
|
+
- **The cost of renaming a repo**: published catalog entries have `owner/repo` embedded in `downloadUrl` / `readmeUrl`, so **renaming breaks the download and README links of already-published plugins** (the source itself is unaffected). Republishing one new entry after the rename heals it, but old version entries still point at the old links — **if you can avoid changing it, don't; if you must, do it early.**
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 4. Identity vs. display name vs. repository name (D5)
|
|
48
|
+
|
|
49
|
+
Three "names" that have nothing to do with one another; conflating them is the root of every naming problem:
|
|
50
|
+
|
|
51
|
+
| | What it is | Can it change |
|
|
52
|
+
|:--|:--|:--|
|
|
53
|
+
| **Plugin identity** (`plugin.json`'s id) | Install directory name, uninstall tombstone, the **unique key** for update reconciliation | 🔴 **Immutable once published** |
|
|
54
|
+
| **Display name** (`plugin.json`'s `name`) | What people see in the UI and on marketplace cards | ✅ **Change freely** (bump and republish when done) |
|
|
55
|
+
| **Repository name** | The project repo on GitHub | ✅ Free (costs as per the previous section) |
|
|
56
|
+
|
|
57
|
+
Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptools`: identity = `publisher.name`, immutable; `displayName` = freely changeable; repository name unrelated to identity) → full measurement and reasoning → [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md); the author-facing rule text → [16-naming-conventions](16-naming-conventions.md).
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 5. The local directory location is unrelated to plugin identity (the single most important item in this document)
|
|
62
|
+
|
|
63
|
+
**Where you clone a plugin project and what the directory is called have no effect on plugin identity** — a plugin repo is self-contained, and the shell only recognizes the Release URL and the catalog; it **does not recognize local paths at all**. ⇒ The local directory structure can be rearranged at any time, with zero risk.
|
|
64
|
+
|
|
65
|
+
Live evidence: the source repos of the two plugins `hello-linkdesk` and `first-run-setup` sit flat outside the container and still build, publish, get listed, and install/uninstall normally in the installed app. All 18 official plugins are the same way today (each in its own independent repo).
|
|
66
|
+
|
|
67
|
+
✅ **So "renaming a directory" is already safe today**: plugin identity = the top-level `pluginId` field (which must be declared explicitly and cannot be changed after publication), **and it has nothing to do with the directory name**.
|
|
68
|
+
|
|
69
|
+
> ⚠️ **Don't read that backwards**: the dangerous act is **changing `pluginId`** (= swapping in a different plugin; users who had it installed see no updates and their data appears lost, and most of the consequences raise no error), not renaming the directory. See [16-naming-conventions](16-naming-conventions.md).
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 6. Four names on the release path must not be hand-edited
|
|
74
|
+
|
|
75
|
+
They participate in install adjudication and update reconciliation; **hand-editing them means identity drift or a broken update chain**:
|
|
76
|
+
|
|
77
|
+
| Name | Why hand-editing is forbidden |
|
|
78
|
+
|:--|:--|
|
|
79
|
+
| `<id>.linkdesk-plugin` (distribution artifact name) | Zip install adjudication looks the plugin id back up from the base name |
|
|
80
|
+
| `v<version>` (Release tag) | The update check finds the version by tag |
|
|
81
|
+
| The version format `^\d+\.\d+\.\d+$` | The schema outright rejects pre-release suffixes and other irregular shapes |
|
|
82
|
+
| Plugin id | Identity is immutable (§4) |
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
> **← Index:** [00-readme](00-readme.md) · **Related:** [16-naming-conventions](16-naming-conventions.md) · [09-plugin-directory-layout §The relationship between source location and distribution artifacts](09-plugin-directory-layout.md)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Naming Conventions — Seven Names, One Identity
|
|
2
|
+
|
|
3
|
+
> 2026-09-14 · **Reader = plugin author.** After reading, you can answer four questions: **how do I choose an id? can it be changed? how do I change the display name? what should the repo be called?**
|
|
4
|
+
> The decision rationale (N1-N6) and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — this document is the author-facing landing point, and of the two there is **only one place to maintain**: change the rule here first and point back; don't create a second copy.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 1. Seven names in one table
|
|
9
|
+
|
|
10
|
+
| Name | Where the source of truth is | Who uses it | Can it change |
|
|
11
|
+
|:--|:--|:--|:--|
|
|
12
|
+
| **Plugin identity id** | `plugin.json` (declare `pluginId` explicitly; when undeclared, the **temporary** fallback = the project directory name — the fallback is not recommended; explicit declaration is the right way) | Install directory, uninstall records, update reconciliation, catalog deduplication | 🔴 **Immutable once published** |
|
|
13
|
+
| **Display name** `name` | `plugin.json` | UI, marketplace cards | ✅ Change freely (bump and republish when done) |
|
|
14
|
+
| **Version** | `plugin.json`'s `version` | Update comparison, Release tag, catalog | Must change on every release |
|
|
15
|
+
| **Distribution artifact name** | `<id>.linkdesk-plugin` (generated automatically by the SDK) | Zip install adjudication, Release assets | Follows the id; **must not be hand-edited** |
|
|
16
|
+
| **Release tag** | `v<version>` (tagged automatically by publish) | Update check | Follows the version; **must not be hand-tagged** |
|
|
17
|
+
| **GitHub repository name** | No rule | `downloadUrl` / `readmeUrl` / the details page's "Repository" | ✅ Free (rename cost in §4) |
|
|
18
|
+
| **Local directory name** | No rule | Only the build tooling | ✅ Free (⚠️ current red line in §5) |
|
|
19
|
+
|
|
20
|
+
**Conflating them is the single root cause of naming problems**: identity is the account machines reconcile against, the display name is what humans read, and the repo name and directory name are merely the project's address — the three are unrelated, and changing one should not drag the others along.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 2. Four character-set/format constraints (enforced mechanically; a mistake is rejected on the spot)
|
|
25
|
+
|
|
26
|
+
| Constraint | Rule | Source |
|
|
27
|
+
|:--|:--|:--|
|
|
28
|
+
| Plugin id | `^[A-Za-z0-9][A-Za-z0-9._-]*$` (first character must be a letter or digit) | `@linkdesk/plugin-sdk`'s `SAFE_PLUGIN_ID` (validate) |
|
|
29
|
+
| Version | `^\d+\.\d+\.\d+$` — **no `-beta` pre-release suffix or the like** (the schema rejects it outright; there is currently no syntax for expressing a pre-release, and that's the status quo, not an oversight) | `plugin.schema.json` |
|
|
30
|
+
| View container ID | `^[a-z][a-z0-9-]*$` | schema / [03-contributes-spec](03-contributes-spec.md) |
|
|
31
|
+
| Distribution artifact base name | = plugin id | SDK `assetNameForId` |
|
|
32
|
+
|
|
33
|
+
**Ids are best lowercase-with-hyphens** (e.g. `file-tree`) — the rule allows uppercase and dots, but lowercase-with-hyphens is the least trouble, and every official plugin does it.
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 3. Three questions answered directly
|
|
38
|
+
|
|
39
|
+
- **How do I choose an id?** Character set per the table above; **immutable once published** — it = install directory name + uninstall record key + update reconciliation key, so swapping the id is swapping in a different plugin (old data appears lost, the update chain breaks silently). **Write `"pluginId"` explicitly in `plugin.json`**; don't rely on the directory-name fallback.
|
|
40
|
+
- **Can I change the id?** No. If you want a different name, change the display name.
|
|
41
|
+
- **How do I change the display name?** `plugin.json`'s `name` can be changed freely; when done, **bump the version and republish** (an installed user's copy is frozen per version, so others won't see the new name otherwise).
|
|
42
|
+
- **What should the repo be called?** Completely free; no prefix is enforced. Official plugins are recommended to uniformly use `linkdesk-plugin-<id>` (the convention text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md), maintained only there once settled); third parties may do as they please.
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 4. The cost of renaming a repo
|
|
47
|
+
|
|
48
|
+
Published catalog entries have `owner/repo` embedded in `downloadUrl` / `readmeUrl` — **renaming breaks the download and README links of old versions** (the source is unaffected). Republishing one new entry heals it, but old version entries still point at the old links. **If you can avoid changing it, don't; if you must, do it early.**
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 5. The local directory name is unrelated to plugin identity
|
|
53
|
+
|
|
54
|
+
**Plugin id = the top-level `pluginId` field** (must be declared explicitly; immutable after publication), **not the directory name**. ⇒ The local project directory name can be **changed freely**; identity is unaffected.
|
|
55
|
+
|
|
56
|
+
Conversely, **changing `pluginId` is the dangerous act — it is equivalent to swapping in a different plugin**: two install directories coexist, uninstall records don't match, two catalog entries appear, the update chain breaks silently, plugin data appears lost — **all five consequences raise no error**. If you really want to change the id, that amounts to publishing a new plugin (see [15-multi-repo-and-local-workspace §5](15-multi-repo-and-local-workspace.md)).
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 6. The version number — four places, one source
|
|
61
|
+
|
|
62
|
+
The version number has **four landing points that must share one source**; changing one means changing all four:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
① Version number in the CHANGELOG.md section heading ## v<version>
|
|
66
|
+
② plugin.json.version ← the only source of truth (required at the schema level)
|
|
67
|
+
③ The catalog entry's versions[].version ← written automatically by publish
|
|
68
|
+
④ package.json.version ← must equal ②
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- The existing rules for ①②③ (section-heading parsing, honest blanks, reverse order) → [09-plugin-directory-layout §CHANGELOG.md format conventions](09-plugin-directory-layout.md).
|
|
72
|
+
- ④ is the fourth anchor: in an independent repo, `package.json` is **the first thing a newcomer (and an AI) sees when opening the repo** — with two version numbers coexisting and disagreeing, someone is bound to bump the wrong one; and both `publish` and the content-fingerprint gate read ② ⇒ **editing the wrong one = silently ineffective**.
|
|
73
|
+
- When to bump (MAJOR/MINOR/PATCH criteria) → `.claude/skills/version-bump/SKILL.md` — that is the sole authority; this document doesn't establish a second set.
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
> **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
# 17 — Region Map: Where Can Your Plugin Appear?
|
|
2
|
+
|
|
3
|
+
> **This page answers one question:** which **part of the window** should your plugin appear in? How is that part **declared**, and **what can it hold**?
|
|
4
|
+
> If you know the words "Icon Bar / Sidebar / Main Area" but not which declaration each one maps to — read this page first, then [13-Development Guide](13-development-guide.md).
|
|
5
|
+
|
|
6
|
+
| | |
|
|
7
|
+
|---|---|
|
|
8
|
+
| Audience | Authors (human, or the author's AI) who want to know "where does the thing I'm building belong" |
|
|
9
|
+
| Form | **A map** — take in the whole picture first, then look up the declaration snippet region by region |
|
|
10
|
+
| Not | A field dictionary (→ [06-plugin.json Spec](06-plugin-json-spec.md)) · the full syntax of every contribution point (→ [03-Contributes Spec](03-contributes-spec.md)) · container API details (→ [08-ViewContainer API](08-view-container-api.md)) |
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. All Regions in One Picture
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
18
|
+
│ ① Title Bar [logo] LinkDesk [buttons…] ─ □ × │ ← contributes.titleBar
|
|
19
|
+
├──────┬───────────────────────────┬──────────────────────────────────┤
|
|
20
|
+
│ │ ③ Sidebar title [◀] │ ④ Tab Bar [Terminal][📊] [+] │
|
|
21
|
+
│ ⑤ ├───────────────────────────┼──────────────────────────────────┤
|
|
22
|
+
│ Icon │ │ │
|
|
23
|
+
│ Bar │ ③ Sidebar │ ⑥ Main Area (tab content) │
|
|
24
|
+
│ │ container → view │ (when split, each pane has │
|
|
25
|
+
│ 42px │ (multiple sections) │ its own Tab Bar) │
|
|
26
|
+
│ │ │ │
|
|
27
|
+
├──────┴───────────────────────────┴──────────────────────────────────┤
|
|
28
|
+
│ Bottom Panel (Ctrl+J) [Output][Todo] [actions] │ ← location: "panel"
|
|
29
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
30
|
+
│ ⑦ Status Bar ● COM3 connected │ TX:1,234 │ 中:EN ☀ 🔔(3) │ ← top-level statusBar[]
|
|
31
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
32
|
+
|
|
33
|
+
Overlays (context menu / dialog / quick pick / floating panel) are painted on top — they belong to no region
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**This page is the authority on region names** (`docs/总体设计/V3-部件命名规范.md` is the canon for the same set of names): Title Bar · Icon Bar · Sidebar · Tab Bar · Main Area · Bottom Panel · Status Bar · Overlay.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 2. Region Cheatsheet
|
|
41
|
+
|
|
42
|
+
| Region | How you get in (declaration) | What goes there | How the user sees it |
|
|
43
|
+
|:--|:--|:--|:--|
|
|
44
|
+
| **⑤ Icon Bar** | `appearsIn.iconBar` (`"top"` / `"bottom"`) **plus** either an `entry` or a **sidebar** container | One icon button | The icon shows up in the 42px vertical strip on the far left; clicking it toggles the sidebar container |
|
|
45
|
+
| **③ Sidebar** | `location: "sidebar"` under `contributes.viewsContainers` (the default) + views attached via `contributes.views` | Collapsible sections (one per view) | Switch to it by clicking the Icon Bar; several plugins can add views to the same container |
|
|
46
|
+
| **⑥ Main Area** | `entry` + `appearsIn.tabBar: true` | The content of one tab | Click the icon in the Icon Bar, or pick it from the `[+]` new-tab menu; multiple instances, splittable |
|
|
47
|
+
| **Bottom Panel** | `location: "panel"` under `contributes.viewsContainers` + views | Several panel views switched by the Tab Bar | `Ctrl+J` expands it; focus it in code with `window.linkdesk.panel.reveal(viewId)` |
|
|
48
|
+
| **⑦ Status Bar** | A top-level `statusBar: [...]` array (**not** `contributes.statusBar`) | A line of text / icons / clickable entries | Usually at the bottom; `align` decides left or right |
|
|
49
|
+
| **① Title Bar** | `contributes.titleBar.right[]` / `.left[]` | Icon buttons or text-only buttons | The right side of the window's top row |
|
|
50
|
+
| **Overlay** | `contributes.floatingPanel` (declares one of your existing views as "openable in a Floating Panel") | One of your existing views | Right-click a tab → "Open in Floating Panel" |
|
|
51
|
+
| **View action area** | `contributes.views[].titleActions[]` | Three kinds of small controls: `icon` / `dropdown` / `split` | Right side of a sidebar section's collapsible header, or right side of a panel's Tab Bar |
|
|
52
|
+
|
|
53
|
+
### Two Places You Can't Get Into
|
|
54
|
+
|
|
55
|
+
| Where you might want to put it | What actually happens |
|
|
56
|
+
|:--|:--|
|
|
57
|
+
| **Right side bar** (`location: "auxiliarybar"`) | ⚠️ **The shell isn't wired up for it today** — declaring it renders nothing; it's a dormant region. Third parties that want a side bar should use `"sidebar"` |
|
|
58
|
+
| **Top Bar** (the old TopBar) | Removed in an early version. The name `contributes.titleBar` survived, but its slots land in the **① Title Bar**, not the old "Top Bar" |
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 3. Three Things People Mix Up Most
|
|
63
|
+
|
|
64
|
+
### ① Icon Bar ≠ tab: two plugin shapes
|
|
65
|
+
|
|
66
|
+
A plugin has **two paths** to being seen. Don't mix them up:
|
|
67
|
+
|
|
68
|
+
| Shape | What it needs | Result |
|
|
69
|
+
|:--|:--|:--|
|
|
70
|
+
| **Has an `entry`** | `entry` + `appearsIn.iconBar` | An icon plus openable-as-a-tab (the classic shape) |
|
|
71
|
+
| **entryless** (sidebar-only) | **No `entry`**; just a sidebar container + `appearsIn.iconBar` | An icon and a sidebar only, **never a tab** |
|
|
72
|
+
|
|
73
|
+
> **entryless is the recommended path for sidebar-only plugins** — no need to write an empty `src/index.tsx` just to earn an icon.
|
|
74
|
+
> Conversely: `appearsIn.tabBar: true` **requires** an `entry` (tabs are rendered by the entry component).
|
|
75
|
+
|
|
76
|
+
**Three cases where you don't get an icon** (none of them are bugs — they're by design):
|
|
77
|
+
- You don't declare `appearsIn.iconBar` (**opt-in** — no declaration, no icon)
|
|
78
|
+
- Data plugins (language packs / themes / icon themes, anything without a sidebar container)
|
|
79
|
+
- You have only panel / auxiliarybar containers — the Icon Bar means "open a sidebar container", and the Bottom Panel doesn't count
|
|
80
|
+
|
|
81
|
+
### ② Sidebar container ≠ tab
|
|
82
|
+
|
|
83
|
+
The sidebar holds two layers, **container → view**: the container is a "channel" (switched by clicking the Icon Bar), and the views are the individual **collapsible sections** inside it.
|
|
84
|
+
**Other plugins can add views to your container, and your plugin can add views to theirs** — the container's owner neither knows nor cares.
|
|
85
|
+
|
|
86
|
+
```jsonc
|
|
87
|
+
// Adding a section to someone else's container: write only contributes.views, not viewsContainers
|
|
88
|
+
{ "contributes": { "views": { "explorer": [ { "id": "timeline", "title": "TIMELINE", "render": "src/views/TimelineView.tsx", "order": 100 } ] } } }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### ③ Don't wrap your view component in `SidebarSection` yourself
|
|
92
|
+
|
|
93
|
+
When the shell renders with `PoolSectionStack` it **automatically** wraps your component in a collapsible header. Just return the **content**; wrap it yourself and you get a double header.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 4. Minimal Declaration Snippet for Each Region
|
|
98
|
+
|
|
99
|
+
### ⑤ Icon Bar + ⑥ Main Area (classic tab plugin)
|
|
100
|
+
|
|
101
|
+
```jsonc
|
|
102
|
+
{
|
|
103
|
+
"pluginId": "my-plugin",
|
|
104
|
+
"name": "My Plugin",
|
|
105
|
+
"icon": "resources/icon.svg",
|
|
106
|
+
"entry": "src/index.tsx",
|
|
107
|
+
"appearsIn": { "iconBar": "top", "tabBar": true }
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
// src/index.tsx — the entry component: the shell injects props as { isActive, tabId?, sourceId? }
|
|
113
|
+
export default function MyView({ isActive }: { isActive: boolean }) {
|
|
114
|
+
return <div>Hello LinkDesk</div>;
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### ③ Sidebar
|
|
119
|
+
|
|
120
|
+
```jsonc
|
|
121
|
+
{
|
|
122
|
+
"appearsIn": { "iconBar": "top" },
|
|
123
|
+
"contributes": {
|
|
124
|
+
"viewsContainers": { "my-sidebar": { "title": "My Tools", "location": "sidebar", "order": 100 } },
|
|
125
|
+
"views": { "my-sidebar": [ { "id": "main", "title": "", "render": "src/views/MainView.tsx", "order": 0 } ] }
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Bottom Panel
|
|
131
|
+
|
|
132
|
+
```jsonc
|
|
133
|
+
{
|
|
134
|
+
"contributes": {
|
|
135
|
+
"viewsContainers": { "my-panel": { "title": "My Panel", "location": "panel" } },
|
|
136
|
+
"views": { "my-panel": [ { "id": "output", "title": "Output", "render": "src/views/OutputView.tsx", "order": 0 } ] }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
await window.linkdesk.panel.reveal("output"); // Focus the "output" view in the Bottom Panel (not in a panel container → no-op, no error)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### ⑦ Status Bar
|
|
146
|
+
|
|
147
|
+
```jsonc
|
|
148
|
+
{
|
|
149
|
+
"statusBar": [
|
|
150
|
+
{ "id": "units", "label": "mm", "align": "right" },
|
|
151
|
+
{ "id": "zoom", "label": "100%", "align": "right", "onClick": "my-plugin.zoomFit" }
|
|
152
|
+
]
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
The React component for a Status Bar entry is auto-discovered along three paths: `statusBar.tsx` / `src/statusBar.tsx` / `src/components/statusBar.tsx`.
|
|
157
|
+
|
|
158
|
+
### ① Title Bar buttons
|
|
159
|
+
|
|
160
|
+
```jsonc
|
|
161
|
+
{
|
|
162
|
+
"contributes": {
|
|
163
|
+
"titleBar": { "right": [ { "command": "my-plugin.refresh", "icon": "codicon-refresh", "when": "my-plugin.busy" } ] }
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### View action area (sidebar section / right side of the panel Tab Bar)
|
|
169
|
+
|
|
170
|
+
```jsonc
|
|
171
|
+
{
|
|
172
|
+
"contributes": {
|
|
173
|
+
"views": {
|
|
174
|
+
"my-sidebar": [
|
|
175
|
+
{
|
|
176
|
+
"id": "main", "title": "My Tools", "render": "src/views/MainView.tsx",
|
|
177
|
+
"titleActions": [ { "type": "icon", "id": "reload", "command": "my-plugin.reload", "icon": "codicon-refresh", "title": "Reload" } ]
|
|
178
|
+
}
|
|
179
|
+
]
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The `command` in `titleActions` is registered by your own view component (`window.linkdesk.commands.registerCommand`); **for purely programmatic commands like these, prefer `when: "false"`** so they don't flood the Command Palette.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## 5. The Props Contract for Components
|
|
190
|
+
|
|
191
|
+
No matter which region you land in, **your content component receives the same set of props**:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
type PluginViewProps = { isActive: boolean; tabId?: string; sourceId?: string };
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| prop | Meaning | Usage |
|
|
198
|
+
|:--|:--|:--|
|
|
199
|
+
| `isActive` | Whether the containing tab/view is currently focused | **Use it only to gate side effects that should run while focused** (polling, autosave) — under keep-alive every tab stays mounted, so blanking the whole content block with `isActive` is a bug |
|
|
200
|
+
| `tabId` | This tab's id | Tells apart multiple instances of the same plugin |
|
|
201
|
+
| `sourceId` | Context data (file path / session id, etc.) | Editor-style plugins use it to know which file the user opened |
|
|
202
|
+
|
|
203
|
+
**View** components in the Sidebar / Panel have the same signature (you may declare only the props you actually use).
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 6. How Regions Talk to Each Other
|
|
208
|
+
|
|
209
|
+
Picking a region only settles "where you live". **Cross-region wiring** like "sidebar selection → Main Area switches → Status Bar updates" is a different page:
|
|
210
|
+
→ [18-Cross-Region Wiring](18-cross-region-wiring.md).
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 7. Related Reading
|
|
215
|
+
|
|
216
|
+
| What you want to do | Read this |
|
|
217
|
+
|:--|:--|
|
|
218
|
+
| Every field of the view container API (`viewsContainers` / `views` / `titleActions`, three forms) | [08-ViewContainer API](08-view-container-api.md) |
|
|
219
|
+
| The full syntax and examples for every contribution point | [03-Contributes Spec](03-contributes-spec.md) |
|
|
220
|
+
| What each field means / its type / its default | [06-plugin.json Spec](06-plugin-json-spec.md) · `plugin.schema.json` |
|
|
221
|
+
| How regions connect to one another | [18-Cross-Region Wiring](18-cross-region-wiring.md) |
|
|
222
|
+
| Writing a plugin for the first time | [13-Development Guide](13-development-guide.md) |
|
|
223
|
+
| The full documentation index | [00-README](00-readme.md) |
|
|
224
|
+
|
|
225
|
+
> Temporary negative-control line.
|