dsh-assist-chat 0.1.0 → 0.1.1

package/README.md

@@ -2,60 +2,84 @@
 
 English | [中文](README.zh.md)
 
-Side chat for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+**Side chat for DeepSeek Harness.** Ask a follow-up without derailing what you are working on.
 
-A right-dock seat that **branches the conversation you are in**: it carries the main thread history up to the moment you open it, so "that error above" and "the file we just edited" already make sense — then continues on its own branch without rewriting, interrupting, or derailing the main transcript.
+Opens a second conversation in the right dock that **already knows everything the main thread knows** — your current task, the error you just hit, the file you just edited. Ask your question there, get your answer, and the main thread stays exactly as it was.
 
-The panel does not reimplement chat. It mounts the product own Conversation surface, so streaming, markdown, tool cards, approvals, Stop and the composer behave exactly like the main conversation.
+## The problem it solves
 
-Inspired by the side chat in ZCode (`zai-org/ZCode`): same shape — a tab in the right side pane backed by a real, parallel child conversation. Not a modal, and it never takes over the main area.
+You are mid-task. Something occurs to you that is not part of the task:
 
-## Why
+- "what does this error actually mean?"
+- "would this approach even work?"
+- "what is that function supposed to do?"
 
-You are mid-task and want to ask something tangential: a design question, a sanity check, "what does this error actually mean". Opening a new conversation loses the context; typing in the main thread derails it and rewrites the transcript you were about to hand off.
+You have three options today, and two of them are bad:
 
-A side chat is the third option. It forks the current conversation, so it knows what the main thread knows, and it runs beside it.
+| Option | Knows your context | Keeps your main thread clean |
+| --- | --- | --- |
+| Open a new conversation | ❌ You re-explain everything from scratch | ✅ |
+| Just ask in the main thread | ✅ | ❌ The question and answer get written into the transcript you were about to hand off, and the agent gets derailed |
+| **Side chat** | ✅ It forks the conversation | ✅ Nothing you say reaches the main thread |
 
-## Features
+A side chat is the third option done properly. It is the same idea as the side chat in [ZCode](https://github.com/zai-org/ZCode): a tab in the right dock, backed by a real, parallel conversation — not a modal, and it never takes over the main area.
 
-- **Branch, not blank slate** — every opening forks the main conversation as it is *right now*.
-- **Isolated by construction** — its own Session, its own agent, its own transcript. Nothing you say here lands in the main thread.
-- **Native chat surface** — messages, streaming, tool calls, code blocks, Stop, composer: all inherited, none reimplemented.
-- **Per-conversation** — a branch of conversation A never surfaces while you are looking at B.
-- **Tab lifecycle = branch lifecycle** — one branch while the tab is open (survives tab switches and dock collapse), retired when you close the tab.
-- **No catalog noise** — the branch row is hidden from the left session list while alive, and archived once you close it.
+## What it feels like
 
-## Install
+1. You are in a conversation with some history. A **Side chat** button sits in the session header.
+2. Click it. The right dock opens with a tab called **Side chat**, containing a copy of that conversation — every message from before is already there.
+3. Ask your question. It answers using the full context you already built up.
+4. Close the tab. Your main conversation never noticed a thing.
 
-### From the dsh market
+The panel is not a reimplementation of chat: it mounts the product own Conversation surface, so streaming, markdown, tool cards, approvals, Stop and the composer behave exactly like the main conversation.
 
-Search for `dsh-assist-chat` under **Plugins → Discover**, or add an index source and install from there.
+## Features
 
-### From npm
+- **A branch, not a blank slate** — every opening forks the main conversation as it is right now, so no re-explaining.
+- **Genuinely isolated** — its own Session, its own agent, its own transcript. Nothing leaks into the main thread.
+- **Native chat surface** — messages, streaming, tool calls, code blocks, Stop, composer: all inherited, none redrawn.
+- **One branch per conversation** — conversation A side chat never appears while you are looking at B.
+- **Tab lifecycle is branch lifecycle** — one branch while the tab is open (survives tab switches and dock collapse), retired when you close the tab.
+- **No clutter** — the branch is hidden from the left session list while alive, and archived once you close it.
+
+## Install
 
 ```sh
+# from npm (recommended)
 dsh plugin --profile desktop add dsh-assist-chat
-```
-
-### From a local checkout
 
-Point the profile at this directory:
+# or straight from the repository
+dsh plugin --profile desktop add github:sleep123937/dsh-assist-chat
 
-```sh
+# or point at a local checkout
 dsh plugin --profile desktop add link:/absolute/path/to/dsh-assist-chat
 ```
 
-Either way the package ships its own `cordis.patch.yml`, so the loader entry is inserted by the package itself. **Restart DeepSeek Harness afterwards.**
+Use `--profile web` instead of `--profile desktop` if you run the browser build. **Restart DeepSeek Harness afterwards** — the button appears in the session header.
+
+## FAQ
+
+**Why can I not find it in the left session list?**
+By design. The branch exists as a real Session (it has to, to have its own agent), but its catalog row is hidden while the tab is open, so your list stays clean. Close the tab and it is archived.
 
-## Usage
+**Does it see what I say in the main thread afterwards?**
+No. A fork is a snapshot: the branch knows the conversation up to the moment you opened it. If you want the newer context, close the tab and open a fresh one.
 
-1. Open a conversation that already has some history.
-2. Click **Side chat** in the session header (the same entry is on the right sidebar guide page).
-3. The dock opens with a branch of that conversation. Ask away.
-4. Close the tab when done. Opening it again later forks a fresh copy of whatever the main thread looks like by then.
+**Does anything I ask here pollute the main conversation?**
+No. Separate Session, separate transcript. The main thread is byte-for-byte unchanged.
+
+**Can I keep several open?**
+Yes — the dock supports tabs and split panes. Each branch is tied to the conversation it was forked from.
+
+**Why did my message disappear once?**
+If a branch gets archived while its tab is still open, DSH rejects its model steps silently. This plugin only archives on tab close, and attempts to restore a branch that is somehow still archived. If you ever see it, reopen the tab.
 
 ## How it works
 
+*This section is for people reading the source. You do not need it to use the plugin.*
+
+Registered pieces:
+
 | Piece | Registration |
 | --- | --- |
 | Tab type | `ctx.sidebarRightTabs.register({ id, kind: "assistchat", keepMounted: true, guide })` |
@@ -63,26 +87,19 @@ Either way the package ships its own `cordis.patch.yml`, so the loader entry is
 | Chat surface | `renderFactorySlot("conversation.content", { variant: "embedded", phase, hero }, { slots: { views: FixedChatView } })` |
 | Entry point | `conversation.session.header.actions` — a list seat; `.corner` is single and already taken |
 
-### Session lifecycle
-
-1. Resolve the conversation on screen: `ctx.get("uiWorkspace").mainReference.sessionId`.
-2. `ctx.get("sessions").fork({ sessionId, increaseTitle: true })` — the child inherits the full transcript. A blank parent falls back to `create({ workspaceId })`.
-3. `ctx.get("sessions").retain(id, { source, signal })` yields the SessionReference the provider needs.
-4. On unmount (tab closed): release the reference, then archive the branch.
-
-The parent id travels through the tab navigation params (`openTab(kind, { params: { parent } })`). The dock layout is stored per Session, so branch identity is keyed the same way.
+Branch lifecycle: resolve the conversation on screen (`uiWorkspace.mainReference.sessionId`) → `sessions.fork({ sessionId, increaseTitle: true })` → `sessions.retain(...)` → release and archive on unmount. The parent id rides the tab navigation params, so the dock keeps the branch bound to its own conversation.
 
 ### Two things that will bite you
 
 **Never archive a branch that is still in use.** DSH ships an `archived-session-gate` that rejects every `agent/pre-step` of an archived Session. Messages are accepted into the queue and then silently vanish, with no error at all. Archiving is only safe *after* the tab closes.
 
-**Which forces hiding to be presentation-only.** The left catalog renders one row per Session with a stable `data-row-key="session:<id>"`, so a plugin can mark the rows it minted and hide them with `display: none`. That keeps the Session fully writable. Trade-offs: the "expand N more" counter still counts hidden rows, and the trick is tied to the row-key convention.
+**Which forces hiding to be presentation-only.** The catalog renders one row per Session carrying `data-row-key="session:<id>"`, so the plugin marks the rows it minted and hides them with `display: none`. The Session stays fully writable. Trade-offs: the "expand N more" counter still counts hidden rows, and the trick is tied to that row-key convention.
 
 ## Compatibility
 
 - DeepSeek Harness `>= 0.2.0` (`engines.dsh`).
-- Client plugin API only — no host-side code, no patched DSH files.
-- A branch is visible in the catalog while its tab is open, and archived when the tab closes.
+- Client plugin API only: no host-side code, no patched DSH files.
+- Tested on 0.2.1-rc.3, desktop profile.
 
 ## Development
 
@@ -93,6 +110,16 @@ npm run check   # syntax only
 
 `test/smoke.cjs` runs the shipped Client module in a `vm` sandbox with a mock React and a mock Cordis context. No GUI needed.
 
+## Feedback
+
+Bugs, ideas and "this does not work on my machine" are all welcome:
+
+- [Report a bug](https://github.com/sleep123937/dsh-assist-chat/issues/new?template=bug_report.yml)
+- [Request a feature](https://github.com/sleep123937/dsh-assist-chat/issues/new?template=feature_request.yml)
+- [Browse existing issues](https://github.com/sleep123937/dsh-assist-chat/issues)
+
+Prefer email? Write to **zousleep@163.com**.
+
 ## License
 
 MIT

package/README.zh.md

@@ -91,6 +91,16 @@ npm run check   # 只查语法
 
 `test/smoke.cjs` 用 `vm` + mock React + mock Cordis context 跑真实的 Client 模块，不需要开 GUI。
 
+## 反馈
+
+遇到问题、有想法、或者「在我机器上跑不起来」，都欢迎：
+
+- [报告问题](https://github.com/sleep123937/dsh-assist-chat/issues/new?template=bug_report.yml)
+- [提个建议](https://github.com/sleep123937/dsh-assist-chat/issues/new?template=feature_request.yml)
+- [看看别人提了什么](https://github.com/sleep123937/dsh-assist-chat/issues)
+
+不想用 GitHub 也行，直接发邮件到 **zousleep@163.com**。
+
 ## 许可
 
 MIT

package/locale/en.json

@@ -1,4 +1,8 @@
 {
+  "meta": {
+    "title": "Side chat",
+    "description": "Branch the current conversation into the right dock. Ask a follow-up without derailing the main thread — the branch already knows everything the main conversation knows."
+  },
   "tab.title": "Side chat",
   "guide.title": "Side chat",
   "guide.description": "Open a side conversation isolated from the main thread",

package/locale/zh.json

@@ -1,4 +1,8 @@
 {
+  "meta": {
+    "title": "辅助对话",
+    "description": "在右侧栏开一条当前对话的分支。追问不会打断主线——分支已经知道主对话知道的一切。"
+  },
   "tab.title": "辅助对话",
   "guide.title": "辅助对话",
   "guide.description": "开一个与主对话隔离的旁支会话，随时追问而不打断主线",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-assist-chat",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Side chat for DeepSeek Harness: a right-dock seat that branches the current conversation, so you can ask follow-ups without derailing the main thread. 右侧栏辅助对话：从当前会话 fork 一条旁支，追问不打断主线。",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "author": "sleep123937 <1347351715@qq.com> (https://github.com/sleep123937)",
+  "author": "sleep123937 <zousleep@163.com> (https://github.com/sleep123937)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sleep123937/dsh-assist-chat.git"