dsh-agent-persona 0.1.8 → 0.2.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_EN.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # dsh-agent-persona
2
2
 
3
- Different system-prompt personas for different **workspaces** and different **sessions**.
3
+ Different system prompt personas for different **workspaces** and **sessions**.
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/dsh-agent-persona)](https://www.npmjs.com/package/dsh-agent-persona)
6
6
  [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
@@ -8,280 +8,186 @@ Different system-prompt personas for different **workspaces** and different **se
8
8
 
9
9
  [中文](./README.md)
10
10
 
11
- Note: the settings UI is in Chinese. The code, docs and this file are English.
12
-
13
- ## What it does
14
-
15
- A DSH deployment usually runs several jobs at once — frontend work, docs, alert triage, code review — and each
16
- wants its own identity, tone and constraints. This plugin hands each of them its own persona, injected as a
17
- **section of the system prompt**:
18
-
19
- - **Many personas, each with its own reach.** One persona can apply to several workspace directories and several
20
- sessions; a match is `exact`, `prefix`, `contains` or `regex`.
21
- - **More specific wins.** A session-id rule beats a workspace rule, and `exact` beats `prefix`/`contains`/`regex`;
22
- only equal specificity falls back to list order.
23
- - **An explicit default persona.** Mark one persona as the default and it takes every session nothing else claimed
24
- — at most one at a time. With none marked, those sessions keep DSH's own system prompt.
25
- - **A place belongs to one persona.** Pointing a workspace or session at a new persona takes it away from whoever
26
- held it, and the save reports whose claim moved.
27
- - **Append or replace.** Keep DSH's identity line and put the persona after it, or drop that line and use only the
28
- persona.
29
- - **Empty text means "no persona here"** — add a rule for a place and leave the body empty to switch it off there.
30
- - **An edit applies to the next message.** No restart: the body is re-read per assembly by file stamp.
31
- - **Tools cannot write the persona file.** The body becomes part of the system prompt, so the host registers a
32
- global `tools.guard` that refuses every call pointing at the persona store — file tools by the paths in their
33
- arguments, shell commands by mentioning the store together with a write feature — while read-only commands pass.
34
- - **A store that cannot be read is never lost quietly.** When the file exists but cannot be used, the page says
35
- what happened and why, and the first save copies the original to `personas.json.bak-<timestamp>` before touching
36
- it. If that copy fails, the write fails with it.
37
- - **Import / export.** Export writes a JSON file (and copies it to the clipboard); import takes a chosen file or a
38
- pasted document, **previews as you type** every persona with its size and reach, and creates them **disabled**
39
- and appended at the end, never taking over the default slot.
40
-
41
- Three surfaces, three jobs:
42
-
43
- | Surface | Where | What for |
44
- |---|---|---|
45
- | **Settings page** | Settings → Agent 人设 | Create, edit, delete, duplicate and reorder personas; write the body, preview Markdown, let AI rework it. Beside the title: the **GitHub and npm links** and the **version of the copy actually installed** (its tooltip says whether this copy came from npm or from a local checkout) |
46
- | **Session view** | the **人设** tab on a conversation | Which persona this session matched and why, the **system prompt it actually sent** (rendered and source), and the same management UI inline |
47
- | **Sidebar card** | the right bar of `dsh-better-sidebar` | Puts that same view into the sidebar (needs that plugin installed) |
48
-
49
- All three preference switches (`编辑后自动保存` / `在对话页显示「人设」标签` / `注册到 dsh-better-sidebar`) live on the
50
- **Settings → Agent 人设** page, which none of them can hide: switching the conversation tab or the sidebar card
51
- off and returning there is how you turn them back on. This plugin adds nothing to **Settings → General**.
52
-
53
- ## Why it outranks AGENTS.md
11
+ ## What it solves
54
12
 
55
- DSH turns workspace instructions (`AGENTS.md` and friends) into a **user-role** message, and that message's own
56
- intro says *"They do not override system, developer, or direct user instructions."* This plugin writes a
57
- **system-prompt section** instead (section name `agent-persona`, order 1, right after the identity line).
13
+ One DSH install usually runs several kinds of work at once. While you're writing frontend code, you want the agent to give you the edit and skip the pleasantries. While you're writing docs, you want structure first. In a session where you're watching alerts, you want it to confirm before touching anything. Stuffing all of that into `AGENTS.md` doesn't work well — workspace instructions arrive as a user message, and the model is free to treat them as advice.
58
14
 
59
- That ordering is the framework's, not something the plugin claims — which is also why editing files inside the
60
- workspace cannot touch this layer.
15
+ This plugin writes a persona as **a section of the system prompt** (section name `agent-persona`, right after DSH's built-in identity line) and dispatches it by workspace path or session id. One location belongs to at most one persona, and the more specific rule wins. After you save, the next message uses the new persona.
61
16
 
62
17
  ## Install
63
18
 
64
- **Tested against DSH `0.1.5-rc.1` (the author's development environment), `0.1.5-rc.2`, `0.2.0-rc.2` and
65
- the current `0.2.1-rc.2`.** That is what `package.json`'s `dsh.compatibility` declares — it means "we ran on
66
- these", not a promise of compatibility work for older or newer releases; please verify on yours.
67
-
68
- The sidebar card additionally needs **`dsh-better-sidebar`**: without it the `注册到 dsh-better-sidebar` switch is not
69
- shown at all (there is nothing to register into), and everything else works as usual.
19
+ Requires DSH `0.2.0-rc.2` or newer; this release is tested on `0.2.2-rc.1` (full list below). Install it into the profile you use, either from a plugin market such as dshmarket or from the CLI:
70
20
 
71
21
  ```bash
72
22
  dsh plugin --profile web add dsh-agent-persona
73
23
  ```
74
24
 
75
- Then **restart `dsh web` once**: profile bundles are read at startup, and that is where the plugin row lives.
25
+ Then **restart `dsh web` once**. Profile bundles are read at startup, and the plugin registers itself from there.
76
26
 
77
- After the restart:
27
+ After the restart the settings sidebar has an **Agent 人设** page, and `~/.dsh/dsh-agent-persona/state.json` contains a load heartbeat saying which file was loaded, where personas are stored, and how many there are.
78
28
 
79
- - the **Agent 人设** entry in settings;
80
- - `cat ~/.dsh/dsh-agent-persona/state.json` — the load heartbeat: which module was loaded, how many personas,
81
- where the store is.
29
+ Upgrade or remove with `dsh plugin --profile web update|remove dsh-agent-persona`, then restart again. Your persona file is not deleted or overwritten. There are also local install scripts: `bash scripts/install.sh` on Unix, `scripts/install.ps1` on Windows.
82
30
 
83
- Local install scripts live in `scripts/install.sh` and `scripts/install.ps1`.
31
+ ## Three-minute setup
84
32
 
85
- Upgrading and removing (`dsh plugin …` runs the profile's package manager for you):
33
+ ![Creating a persona and adding a target](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/settings-list.gif)
86
34
 
87
- ```bash
88
- dsh plugin --profile web update dsh-agent-persona # upgrade within the declared range
89
- dsh plugin --profile web add dsh-agent-persona@latest # jump to the newest major
90
- dsh plugin --profile web remove dsh-agent-persona # uninstall
91
- ```
35
+ Open **Settings → Agent 人设**, click **新建人设** (new persona), and add locations one row at a time under **适用范围** (scope): pick **workspace directory** or **a specific session**, then choose the target from the dropdown. The list comes from DSH's own workspaces and sessions, and sessions show their title and "a few minutes ago" — no session id to copy. For prefix, contains, or regex matching, choose **自己输入…** (type it yourself).
92
36
 
93
- **Restart `dsh web` once** after an upgrade or a removal. Your persona file is neither deleted nor
94
- overwritten — uninstalling only removes the plugin.
37
+ Write the body, turn the persona on, save. Two things worth knowing up front:
95
38
 
96
- ## Using it
39
+ - New personas start **disabled**, so creating one never changes an existing session;
40
+ - A location can only belong to one persona. Assign a workspace to a new persona and the previous owner loses it; the save message tells you who it was taken from.
97
41
 
98
- ![persona list](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/settings-list.gif)
42
+ ## Where it shows up
99
43
 
100
- **New persona** → add rows under reach, pick a workspace or a session → write the body → switch it on → save.
44
+ | Surface | Location | What it's for |
45
+ |---|---|---|
46
+ | **Settings page** | Settings → Agent 人设 | Create, edit, delete, duplicate, reorder personas; write the body, preview Markdown, let AI rewrite a draft. GitHub/npm links and the installed version sit next to the title |
47
+ | **Session tab** | **人设** tab at the top of a conversation | See which persona matched, the system prompt actually sent, and manage personas in place |
48
+ | **Sidebar card** | dsh-better-sidebar's right sidebar | Mounts the same 人设 page in the sidebar (requires that plugin) |
49
+ | **Plugin detail** | Web GUI → Plugins → dsh-agent-persona | Six preference switches, plugin icon, and display name |
101
50
 
102
- - A **new persona starts disabled**, so adding one changes nothing until you say so.
103
- - Reach is a list of rows. Each row picks a kind (**workspace directory** or **a session**) and then the target
104
- from a dropdown; switching a row's kind clears its value.
105
- - The dropdowns come from DSH's own workspace and session lists — sessions carry their **title**, working
106
- directory and "minutes ago", so you do not need to know a session id.
107
- - Boundaries like prefixes and regexes are available through **type it yourself…**.
108
- - A persona with **no rows applies nowhere** (it is a draft) unless it is marked as the default.
51
+ ### Plugin detail configuration
109
52
 
110
- An expanded card — name, state, the default switch, injection mode, the reach rules, the body and the footer:
53
+ ![The Interface and features block on the plugin detail page](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/plugin-detail-config.gif)
111
54
 
112
- ![expanded card](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/settings-editor.gif)
55
+ The plugin detail page has a new **界面与功能** (Interface and features) block. Its subtitle reads: decides where this plugin shows up in DSH and what protection the editor gets; persona content is still edited under Settings → Agent 人设, and once the settings entry is hidden this page is the way back. All six switches live here, and the same group stays on the settings page — both write the same `prefs`, so changing either side updates the other. Each switch saves as you flip it; there is no save button.
113
56
 
114
- ### Version history (opt-in)
57
+ Turning off **在设置左栏显示「Agent 人设」** only hides the page from the settings navigation. The plugin detail page remains, so you can keep editing and turn the entry back on at any time. In the plugin list the display name is **Agent 人设** in Chinese and **Agent Persona** in English; the description comes from `locale/`, and the icon is `icon.svg` at the package root (it does not follow the theme color).
115
58
 
116
- Turn on **Save persona version history** in Settings and every save records the text change as a diff in
117
- `personas.history.json`. The version-history button in the editor toolbar opens the comparison:
59
+ ![Plugin detail header: the Agent Persona icon, v0.2.0, and the Chinese description](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/plugin-detail-icon.png)
118
60
 
119
- ![version history demo](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/versions.gif)
61
+ ## Personas: list and editor
120
62
 
121
- - **Text only**: name, enabled flag and targets are not versioned.
122
- - **Diffs, not snapshots**: equal runs are stored as line counts; only changed lines keep their text.
123
- - **Restore**: pick any version and restore it; the restore itself is recorded, so it can be undone too.
124
- - **Chained replay**: the first text is the base snapshot, later versions replay on top of it; past 200
125
- versions the oldest are folded into the base. A content hash per record makes a hand-edited history fail
126
- loudly instead of restoring different text.
127
- - Turning the switch off stops recording; existing history stays readable and restorable.
63
+ Personas are ordered top to bottom by priority. Each card shows its enabled state, fallback flag, the workspaces and sessions it applies to, body length, and rule count. The `⋯` menu has move up, move down, duplicate, and delete. A collapsed persona with **no locations at all** says "未设置位置:不生效,该会话仍用 DSH 自带的 prompt" — it's a draft, not a fallback. To use it as a fallback, turn on **默认人设** on the card; only one persona can be the fallback at a time.
128
64
 
129
- ### Reading what a session actually said
65
+ ![Expanding and editing a persona](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/settings-editor.gif)
130
66
 
131
- The button next to the session dropdown opens a **read-only** transcript: your inputs on the right, the agent's
132
- replies on the left.
67
+ Expanding a card lets you change the name, fallback flag, injection mode, and body. The body has a Markdown preview and can be rewritten by the model currently configured in DSH. The AI only produces a suggestion: it enters the editor only after you click **采用** or **追加**, and only a save writes it to disk. Import/export lives on the same page: export produces a JSON file (and copies it to the clipboard); import accepts a file or pasted text, previews each persona's word and rule counts as you type, and writes everything as "new and disabled", so it never replaces your fallback.
133
68
 
134
- - **Only what you actually typed.** Workspace instructions (`AGENTS.md`), runtime context snapshots, skill
135
- directory notes — anything the harness or another plugin injected as a user-role message — are left out, with a
136
- single line at the top saying how many were hidden.
137
- - Long messages are clipped; **展开全文** re-reads just that one and replaces that bubble, and **收起全文** puts the
138
- short text back.
139
- - **跳到最新** shows only the last user input and everything after it.
69
+ ## Version history (opt-in)
140
70
 
141
- ### The 人设 tab on a conversation
71
+ ![Version history: open a version, compare, restore](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/versions.gif)
142
72
 
143
- ![session view](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/view-persona.gif)
73
+ With **保存人设版本历史** on, every body save appends a diff to `personas.history.json`. The **版本历史** button at the bottom of the editor opens the compare window:
144
74
 
145
- **人设 / 提示词 / 管理**:
75
+ - **Body only**: renaming, enabling, or changing scope does not create a version;
76
+ - **Diffs, not snapshots**: unchanged lines are stored as counts, only changed lines keep their text;
77
+ - **Restore and delete**: any version can be restored, and restores themselves are recorded, so a bad restore can be undone. Deleting a version recomputes later diffs against the new predecessor, so the chain stays intact;
78
+ - **Dedupe**: if the first 16 hex characters of the body's sha256 match the latest version, no new version is added — covers undo, re-save after restore, and re-importing the same body;
79
+ - Turning the switch off only stops recording; existing history stays readable and restorable.
146
80
 
147
- - **人设** — which persona matched, **which of its rules matched**, the body as Markdown, its own state markers
148
- (in use / disabled, whether it is the default, its injection mode), and an inline editor (name, default switch,
149
- injection mode, body). Editing shows 未保存 · 点击保存 in the card header.
150
- - **提示词** — the prompt this session **actually sent**, with rendered/source views, copy and refresh. With no
151
- persona matched it shows DSH's own prompt verbatim.
152
- - **管理** — the same cards as the settings page, in place.
81
+ ## The 人设 tab in a session
153
82
 
154
- ### The five preferences
83
+ ![Session view: persona, prompt, manage](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/view-persona.gif)
155
84
 
156
- | Switch | Default | Meaning | Takes effect |
157
- |---|---|---|---|
158
- | 编辑后自动保存 | off | Save the editor about a second after typing stops | Immediately; rule rows (workspace/session) deliberately do **not** autosave, so a half-made choice is never stored |
159
- | 在对话页显示「人设」标签 | on | Register the conversation view or not | Immediately (registered/unregistered at runtime) |
160
- | 注册到 dsh-better-sidebar | on | Register the card with the sidebar plugin | Immediately; **not shown at all when that plugin is absent** |
161
- | 禁止模型改写人设文件 | on | Refuse the model's file and shell tools any write to or removal of the persona store (reads still work); with it off the model can edit it directly | Immediately, on the next tool call |
162
- | 保存人设版本历史 | off | Record every text change as a diff in `personas.history.json`, so any version can be compared and restored | Immediately, on the next save |
85
+ Select a session and the top of the view has **人设 / 提示词 / 管理** (persona / prompt / manage):
163
86
 
164
- Preferences live in the persona file's `prefs` field — not in the browser — so they share the data's scope. The
165
- browser keeps only a mirror, used to decide at load whether to register the views.
87
+ - **人设**: which persona matched, which rules matched, the rendered body, and an inline editor;
88
+ - **提示词**: the system prompt **actually sent** for this session, with rendered/source toggle, copy, and refresh;
89
+ - **管理**: the same cards as the settings page, for creating, enabling, editing, reordering, duplicating, and deleting in place.
166
90
 
167
- ## Injection mode: append or replace
91
+ Next to it is a read-only conversation log: it shows only what you actually typed, and plugin-injected content that looks like a user message is collapsed into a one-line notice. Long messages can be expanded individually, and you can jump to the latest one.
168
92
 
169
- | Mode | Effect |
170
- |---|---|
171
- | **Append** (default) | DSH's own identity sentence stays; the persona follows it |
172
- | **Replace** | DSH's identity sentence and the deployment's own persona line are dropped; only this persona remains |
93
+ ## Sidebar card
173
94
 
174
- Replace only touches what the deployment itself wrote. If an Agent preset shadows that section in its own scope,
175
- the plugin leaves it alone — someone else's identity wins.
95
+ ![The Agent 人设 card in dsh-better-sidebar: persona/prompt/manage tabs, refresh button, and the matched persona body](https://raw.githubusercontent.com/Awoodwhale/dsh-agent-persona/main/docs/images/sidebar-card.png)
176
96
 
177
- ## How matching works
97
+ With **dsh-better-sidebar** installed, the same 人设 page can be mounted in the right sidebar. If that plugin is absent, the **注册到 dsh-better-sidebar** switch is not shown, and everything else keeps working.
178
98
 
179
- On every assembly:
99
+ ## The six switches
180
100
 
181
- 1. disabled personas are skipped;
182
- 2. any matching row makes a persona a candidate, compared by specificity (session id 3 vs workspace 1; exact beats
183
- prefix/contains/regex);
184
- 3. equal specificity falls back to list order (`⋯` → move up/down);
185
- 4. a persona with **no rows does not take part** (draft), unless it is the marked default;
186
- 5. nothing matched → use the default persona if one is marked, otherwise inject nothing;
187
- 6. a winner whose body is empty injects nothing — that is how you say "no persona here".
101
+ | Switch | Default | Effect | Where to change | When it applies |
102
+ |---|---|---|---|---|
103
+ | 在设置左栏显示「Agent 人设」 | On | Whether the page appears in the settings sidebar; when off, reach it via Plugins → dsh-agent-persona | Settings page or plugin detail | Immediately |
104
+ | 在对话页显示「人设」标签 | On | Whether the 人设 tab is registered on the conversation page | Settings page or plugin detail | Immediately (registered/unregistered at runtime) |
105
+ | 注册到 dsh-better-sidebar | On | Whether the 人设 page is registered in the right sidebar; hidden when that plugin is not installed | Settings page or plugin detail | Immediately |
106
+ | 编辑后自动保存 | Off | Auto-save the editor about one second after you stop typing | Settings page or plugin detail | Immediately; not while switching scope rows, to avoid saving a half-made selection |
107
+ | 保存人设版本历史 | Off | Record a restorable diff on every body save | Settings page or plugin detail | Immediately; turning it off stops new versions, old history stays viewable |
108
+ | 禁止模型改写人设文件 | On | Reject tool calls that would write to the persona store (reads and greps are unaffected) | Settings page or plugin detail | On the next tool call |
188
109
 
189
- Only `exact` normalises paths (`/a/project/` equals `/a/project`); `prefix`, `contains` and `regex` compare the
190
- string you typed. Empty values, a broken regex, or a missing field on the session simply do not match — never an
191
- error.
110
+ Preferences live in the `prefs` field of the persona file, not in the browser, so they share the data's visibility. The browser keeps a mirror only to decide whether to register a view at load time.
192
111
 
193
- ## Files and configuration
112
+ ## Matching and priority
194
113
 
195
- ```
196
- ~/.dsh/dsh-agent-persona/
197
- ├── personas.json # personas + preferences, mode 600, written atomically
198
- ├── personas.history.json # version history (only while the switch is on)
199
- └── state.json # load heartbeat, rewritten on every load
200
- ```
114
+ When the system prompt is assembled:
201
115
 
202
- The body may use `{{model}}` and `{{cwd}}`; other `{{...}}` are de-braced (an unregistered variable would make the
203
- whole assembly throw, so it is guarded here).
116
+ 1. Disabled personas are skipped;
117
+ 2. Any matching row makes a persona a candidate. Candidates are compared by specificity: session id (3 points) > workspace (1 point), and exact > prefix/contains/regex;
118
+ 3. Ties go to the persona higher in the list;
119
+ 4. A persona with no locations does not participate (draft state) unless it is marked as fallback;
120
+ 5. If nothing matches, the fallback is used when set; otherwise nothing is injected;
121
+ 6. If the winning persona's body is empty, that means "no persona here" and nothing is injected.
204
122
 
205
- Configuration (a Schemastery schema, validated at load — a wrong type **fails the load** instead of being ignored):
123
+ Of the four match types, only `完全一致` (exact) normalizes paths (`/a/project/` and `/a/project` are the same); prefix, contains, and regex compare your string as written. Empty values, invalid regexes, and missing session fields simply don't match — they don't raise errors. Details in [docs/architecture.md](./docs/architecture.md).
206
124
 
207
- | Config | Default | Meaning |
208
- |---|---|---|
209
- | `storePath` | `''` | Where personas live; empty means `$DSH_HOME/dsh-agent-persona/personas.json` |
210
- | `tuneProvider` | `''` | Provider for the AI-tuning button; empty means DSH's current model |
211
- | `tuneModel` | `''` | Model id for the same |
125
+ ### Injection: append or replace
126
+
127
+ | Mode | Effect |
128
+ |---|---|
129
+ | **Append** (default) | Keep DSH's built-in identity line and append the persona after it |
130
+ | **Replace** | Drop DSH's built-in identity line and the deployment's own persona section; use only this persona |
131
+
132
+ **Replace** only touches the section the deployment writes. If an agent preset defines a persona in its own scope, the plugin does not override it — that identity prompt wins.
133
+
134
+ The body supports `{{model}}` and `{{cwd}}`, substituted with current values at render time. Other `{{...}}` placeholders are removed rather than failing the whole assembly.
212
135
 
213
- ### One store per profile (optional)
136
+ ## Data and security
214
137
 
215
- The store is **global by default** (`$DSH_HOME/dsh-agent-persona/personas.json`, the same convention other plugins
216
- use for their state), so profiles on one machine share one set of personas. To separate a profile, override the
217
- path in **that profile's** `cordis.patch.yml` (override the field — do **not** insert another row):
138
+ ```
139
+ ~/.dsh/dsh-agent-persona/
140
+ ├── personas.json # personas + preferences, mode 600, atomic writes
141
+ ├── personas.history.json # version history (created when the switch is on)
142
+ └── state.json # load heartbeat, rewritten on every load
143
+ ```
144
+
145
+ By default there is **one global store**, shared by every profile on the machine. To give a profile its own store, override `storePath` in its `cordis.patch.yml`:
218
146
 
219
147
  ```yaml
220
- # ~/.dsh/profiles/<profile>/cordis.patch.yml
221
148
  - id: agent-persona
222
149
  config:
223
150
  storePath: /Users/you/.dsh/profiles/<profile>/personas.json
224
151
  ```
225
152
 
226
- `DSH_HOME` isolates everything at once (sessions, other plugins' state). The path in force is always on the
227
- Agent 人设 page (`保存在 …`), so it is never a mystery which file you are editing.
228
-
229
- ## Honest notes
230
-
231
- - **A persona is a behavioural constraint, not a security boundary.** It shapes what the model says; it does not
232
- stop tools.
233
- - Tamper protection is decided by **capability, not by tool name**: a global `tools.guard` asks whether this call
234
- would write a protected file — the paths in its arguments (resolved through `~` and relative paths), redirect
235
- targets and writing commands in a shell line (delete, move, in-place edit, interpreter `-c`), and the targets
236
- named by `*** Update File:` markers in a patch body. Protected: `personas.json`, its history file, and their
237
- backup and temp copies.
238
- - It is still a behavioural measure, and the bypass surface is stated plainly: on `danger-full-access` you can
239
- edit the plugin or the profile patch; a path assembled at runtime inside a script, `$VAR` expansion, or an
240
- alias/function wrapper is invisible to a static read. Harder options live at the machine level: `chflags uchg
241
- <store>` (run `chflags nouchg` before editing it yourself), or a restricted sandbox with the store owned by
242
- another user.
243
- - The decision is per **tool call**: a line that both reads and writes has its writing half refused; the reading
244
- half is not implicated.
245
- - Only the **first** match is used — no concatenation. Matching is a linear scan; dozens of rules are fine,
246
- hundreds want a redesign.
247
- - Install once per profile: two rows with the same id in one process make the composition fail.
248
- - **Test boundary**: the suite is unit tests plus source audits (236 host assertions, 187 client assertions, and a
249
- generated-artifact drift check; the numbers are counted by the suites themselves, so they cannot fall behind
250
- the files). It does not drive a browser — UI behaviour is checked by hand today.
153
+ The active path is always shown in the meta line of the Agent 人设 page (`保存在 …`). Other options are `tuneProvider` / `tuneModel`; leave them empty to use the model configured in DSH.
251
154
 
252
- ## Development
155
+ One honest caveat: **a persona is a behavioral instruction, not a security boundary**. It shapes how the model talks; it does not stop it from using tools. The plugin registers a global `tools.guard` that uses capabilities to decide whether a call could write `personas.json`, its history, or a backup copy — paths in arguments, shell redirect targets and write-like commands, and targets inside patch bodies all count. On a local `danger-full-access` setup it can still be bypassed: modified plugin code, runtime-assembled paths, `$VAR` expansion, and alias wrappers are invisible to static checks. For something stronger, work at the machine level — e.g. `chflags uchg <persona file>` — or run DSH in a restricted sandbox.
253
156
 
254
- Sources are TypeScript; `lib/` is build output (not in git, built by `prepare` before `npm publish`):
157
+ If the file exists but cannot be read, the page says why, and backs the original up as `personas.json.bak-<timestamp>` before the first save. If the backup fails, nothing is written.
255
158
 
256
- ```
257
- src/index.ts host half: store, matching, the system-prompt section, the remote service
258
- src/client.ts client half: settings page + session view + sidebar card (bundled to lib/client.js)
259
- src/endpoints.ts single source for the remote surface (generates src/remote.ts and src/typert.ts)
260
- scripts/ the generator and install scripts
261
- test/ unit tests and source audits
262
- docs/ architecture, development notes, design decisions
263
- ```
159
+ ## Compatibility
160
+
161
+ The current `dsh.compatibility` in `package.json` declares these versions, and `engines.dsh` pins the same range `>=0.2.0-rc.2 <0.3.0`:
162
+
163
+ | DSH version | Notes |
164
+ |---|---|
165
+ | `0.2.0-rc.2` | Earliest supported version |
166
+ | `0.2.1-rc.2` | Tested |
167
+ | `0.2.2-rc.1` | Tested; current release target |
168
+
169
+ The table means "we ran it on these versions", not a compatibility promise for older or newer ones.
170
+
171
+ ## Straight talk
172
+
173
+ - **Only the first match wins**; personas are not concatenated. Matching is a linear scan — fine for dozens of rules, but hundreds need a redesign.
174
+ - Install it once per profile. Two rows with the same id in one process prevent the composition from starting.
175
+ - Workspace paths in rules are compared as strings. Don't rely on case or symlink equivalence (`完全一致` normalizes paths; the other three do not).
176
+ - The test suite covers unit tests and source audits; UI behavior is verified in a real browser.
177
+ - Persona files are plaintext. Don't put secrets in the body.
178
+
179
+ ## Development
180
+
181
+ The source is TypeScript; `lib/` is build output (not committed). `src/index.ts` is the host half (storage, matching, the system-prompt section, remote services), `src/client.ts` is the client half (settings page, session view, sidebar card), and `src/endpoints.ts` is the single source for remote methods. Layout details are in [docs/architecture.md](./docs/architecture.md).
264
182
 
265
183
  ```bash
266
184
  npm install
267
185
  npm run build # generate:remote → tsc → esbuild (writes lib/)
268
- npm run typecheck # both tsconfigs, no errors
269
- npm test # 236 + 187 assertions plus the generated-artifact drift check
270
- dsh --profile web --dump-config | grep -c 'id: agent-persona' # composition self-check, expects 1
186
+ npm run typecheck # two tsconfigs
187
+ npm test # unit tests + source audits + generated-artifact drift check
271
188
  ```
272
189
 
273
- How edits take effect:
274
-
275
- - **`src/**` always needs `npm run build`** — `lib/` is output.
276
- - Changing the **content** of the client artifact: the client recomposes, so **refresh the page**; do not rename
277
- the file.
278
- - Changing the **content** of the host artifact: ESM caches modules by URL, so it does **not** reload — restart
279
- `dsh web`.
280
- - Changes to `dsh.bundle.patch` or the profile's `bundles`: restart.
281
- - Never hand-edit the generated `src/remote.ts` / `src/typert.ts`: edit `src/endpoints.ts` and run
282
- `npm run generate:remote`; `npm test` fails if they drift.
283
-
284
- More in [docs/development.md](./docs/development.md) and [docs/architecture.md](./docs/architecture.md).
190
+ How to see code changes live and how to wire up development are in [docs/development.md](./docs/development.md).
285
191
 
286
192
  ## License
287
193
 
package/icon.svg ADDED
@@ -0,0 +1,17 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48" role="img" aria-label="Agent Persona">
2
+ <defs>
3
+ <linearGradient id="persona-card" x1="0" y1="0" x2="1" y2="1">
4
+ <stop offset="0" stop-color="#4f8cff"/>
5
+ <stop offset="1" stop-color="#7c5cff"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <!-- A persona is a card you can hand to a workspace: the back card is the pool, the front card is
9
+ the one this workspace gets. The prompt badge on the front card is the system prompt it sends. -->
10
+ <rect x="5" y="11" width="25" height="29" rx="8" fill="#7c5cff" opacity="0.32"/>
11
+ <rect x="13" y="6" width="29" height="33" rx="9" fill="url(#persona-card)"/>
12
+ <circle cx="27.5" cy="17.5" r="4.3" fill="#ffffff"/>
13
+ <path d="M20.4 26.8c0-3.7 3.2-6.1 7.1-6.1s7.1 2.4 7.1 6.1" fill="#ffffff"/>
14
+ <rect x="21" y="29.5" width="18" height="9.5" rx="3.2" fill="#0d1a33" opacity="0.82"/>
15
+ <path d="M25 32.5l2.8 2.4-2.8 2.4" fill="none" stroke="#ffffff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
16
+ <path d="M30.6 37.3h4.4" fill="none" stroke="#ffffff" stroke-width="2.2" stroke-linecap="round"/>
17
+ </svg>