@kirkchinese/dsh-citeciter 0.9.0-alpha.2 → 0.9.0-beta.1

package/README.md

@@ -1,188 +1,118 @@
 # CiteCiter
 
-[简体中文](README.zh.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
+[简体中文](README.zh.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [Changelog](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/CHANGELOG.md) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
-> **0.8.0 is deprecated.** On Linux, starting DSH through a symlink can prevent Topic creation or restoration with a missing `@deepseek-ai/dsh-agent-loop` error. For DSH 0.1.5-rc.1 / Desktop 2.0.9, upgrade to [0.8.2](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.8.2). For DSH 0.1.7, read the compatibility notice below first.
+![CiteCiter](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.9.0-beta.1/assets/hero/citeciter-hero.png)
 
-CiteCiter adds a source-aware workspace to DeepSeek Harness. Create independent Topics from conversations, tool results and documents for text, programming, image and learning tasks. New Topics use native DSH Sessions, permissions, models, attachments and message queues. The source conversation continues independently.
+**The AI finished the task. I still want to understand how it did it.**
 
-[![CiteCiter demonstration: learn while working](https://raw.githubusercontent.com/kirkchinese/CiteCiter/feat/dsh-latest-usability/assets/docs/video-cover.png)](https://www.bilibili.com/video/BV1tqeA65EJ8/)
+CiteCiter is a [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugin that helps you learn from your agent's real work. Select part of a conversation, a tool result or a document, ask about it in a separate Topic that keeps its source, use a blackboard to see how the pieces relate, then return to your work. The main conversation is never modified.
 
-[Watch on Bilibili](https://www.bilibili.com/video/BV1tqeA65EJ8/). The video shows a released version; this branch's wheel routing and alpha migration are described below.
+[![CiteCiter demo](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.9.0-beta.1/assets/docs/video-cover.png)](https://www.bilibili.com/video/BV1tqeA65EJ8/)
 
-![Native Citer workspace and manual submission diagram](https://raw.githubusercontent.com/kirkchinese/CiteCiter/feat/dsh-latest-usability/assets/docs/native-workspace.svg)
+[Watch the demo on Bilibili](https://www.bilibili.com/video/BV1tqeA65EJ8/) (recorded with an earlier version; the interface has changed slightly).
 
-This is a 0.8 workspace diagram, not a screenshot, with the optional learning route explicitly enabled. This branch routes references as follows; model work still starts only after manual submission.
+## Installation
 
-```mermaid
-flowchart LR
-  S[Actual selection] --> W[Wheel action]
-  W --> F[Free question]
-  W --> N[Other built-ins]
-  W --> C[Custom destination]
-  F --> A{Unarchived same-source Topic selected?}
-  A -->|Yes| D[Append to existing draft]
-  A -->|No| T[Create Topic draft]
-  N --> T
-  C --> D
-  C --> T
-  D --> E[Edit references, question and model]
-  T --> E
-  E --> M[Manual send]
-```
-
-## Version and installation
+CiteCiter needs DSH and a working model. The plugin declares exact host versions, so choose the CiteCiter release that matches your DSH:
 
-This is **0.9.0-alpha.2, the default prerelease on npm latest / next**, targeting Web DSH `0.1.7-rc.2` and the same DSH bundled with [DSH Desktop 2.0.15](https://github.com/anywhere-labs/dsh-desktop/releases/tag/v2.0.15). Separate Host/Client compile checks against DSH `0.1.5-rc.2` remain; they do not establish functional acceptance of the latest Desktop. The older **0.8.2** package remains available only for DSH `0.1.5-rc.1` / Desktop `2.0.9`. Node.js must satisfy `^22.19.0 || >=24.0.0`. Linux acceptance is excluded from this round.
+| DSH version | CiteCiter version |
+| --- | --- |
+| `0.2.0-rc.2` (including the official Desktop), `0.2.1-alpha.1`, `0.2.1-alpha.2` | `0.9.0-beta.1` |
+| `0.1.7-rc.2` | `0.9.0-alpha.3` |
+| `0.1.5-rc.1` | `0.8.2` |
+| `0.1.2-rc.1` | `0.6.0` |
 
-**Do not use 0.8.2 with DSH 0.1.7.** Its exact peer ranges fail the compatibility gate; forcing installation then fails Typert activation because `create()` factories are missing. See [Issue #9](https://github.com/kirkchinese/CiteCiter/issues/9). This release supports the RC2 gate and Host/Remote factories without `allow-version`. Install this prerelease instead of forcing the old package through a compatibility exemption.
+**Official Desktop:** install the npm package `@kirkchinese/dsh-citeciter` from the Plugins page, or enter `https://github.com/kirkchinese/CiteCiter.git` in its Git field, then restart when prompted.
 
-| Version | Status | Main differences |
-| --- | --- | --- |
-| 0.9.0-alpha.2 | Default prerelease; npm latest / next | Prerelease-aware update checks; no repeat update prompt for the same version |
-| 0.9.0-alpha.1 | Earlier prerelease | Dual-host adapters, durable drafts, PTC tool display, reference routing and learning-route policy |
-| 0.8.2 | Older hosts | Explicit source horizons and continuation; native first-answer question suggestions |
-| 0.8.1 | Published | Fix Topic startup through Linux/macOS launcher symlinks |
-| 0.8.0 | Deprecated; upgrade to 0.8.2 | Linux launcher symlinks can prevent Topics from opening |
-| 0.7.0-beta.3 | Previous development candidate | Private read-only Topics, selection wheel, manual five-stage learning |
-| 0.6.0 | Published | DSH 0.1.2-rc.1 / Desktop 2.0.5 baseline |
+**CLI and Web:**
 
-For DSH 0.1.7, install this prerelease:
-
-```powershell
-npm install -g @deepseek-ai/dsh@0.1.7-rc.2
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.9.0-alpha.2
-dsh web
+```sh
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.9.0-beta.1
 ```
 
-Both `latest` and `next` select 0.9.0-alpha.2; it remains a prerelease. For DSH 0.1.5-rc.1 / Desktop 2.0.9, explicitly install 0.8.2. Older built-in update checks may reject prerelease versions; use the installation command above to upgrade. For DSH 0.1.2-rc.1 / Desktop 2.0.5, keep using @kirkchinese/dsh-citeciter@0.6.0. If npm blocks native dependency installation scripts, follow its output to allow the named dependencies and reinstall. Do not disable script restrictions globally.
-
-In 0.8.0, launching DSH through a Linux/macOS symlink can prevent Topics from opening with a missing dsh-agent-loop error. Version 0.8.1 resolves the real CLI entry before loading host modules and retains Desktop's app.asar anchor. Native Linux Node regression passed; macOS has not been tested.
+You can also install a release tag straight from the repository, which contains the built plugin, so nothing is built at install time:
 
-Build and install this branch locally:
-
-```powershell
-npm install -g @deepseek-ai/dsh@0.1.7-rc.2
-pnpm install --frozen-lockfile
-pnpm typecheck
-pnpm typecheck:desktop
-pnpm build
-pnpm --dir packages/citeciter pack --pack-destination E:/project/CiteCiter/.refs/artifacts
-dsh plugin --profile web add E:/project/CiteCiter/.refs/artifacts/kirkchinese-dsh-citeciter-0.9.0-alpha.2.tgz
+```sh
+dsh plugin --profile web add "git+https://github.com/kirkchinese/CiteCiter.git#v0.9.0-beta.1"
 ```
 
-Desktop bundles its own DSH. Version 0.8.2 retains the accepted Desktop 2.0.9 baseline. This release targets Desktop 2.0.15: run `dsh plugin add @kirkchinese/dsh-citeciter@0.9.0-alpha.2` in its managed terminal. Updating the global CLI does not update Desktop's embedded runtime. Restart the relevant host after installation. Do not run Web and Desktop writers against the same DSH home simultaneously.
-
-Known host limitation: Windows read-only PowerShell can reject the host encoding initialization under ConstrainedLanguage, and some Chinese output can be garbled. Citer retains the original errors without raising permissions or hiding output; DSH must fix the executor. This prerelease makes no native acceptance claim for Linux/macOS or the separate Desktop NEXT shell.
-
-## Source reading and suggested questions
-
-`read_source_session` returns byte-bounded pages. `sourceMaxSeq` is the readable snapshot horizon; the legacy `availableThroughSeq` is request-bounded and does not indicate source exhaustion. When `hasMore` is true, pass `nextFromSeq` as the next `fromSeq` and omit `throughSeq`. `truncated` only marks a byte-budget stop within the range. Empty pages, filtered events and oversized placeholders do not prove missing evidence. Observer reads currently committed events; Exact Fork reads only the inherited prefix.
-
-Native Topics offer three suggested questions after the first answer by default; disable them in CiteCiter settings. The prompt omits suggestions when the current request excludes them, asks for only a result, or imposes a strict format or length limit. Clicking a question only fills the draft and still requires manual submission. Source instructions and question suggestions are separate prompt modules; source contents remain gated by submitted attachments.
-
-## Drafts and references
-
-1. Select text in the source conversation, hold the right mouse button, point at a wheel action and release. Tool results, the document reader and native file previews provide additional entry points.
-2. Free question adds the selection to the selected unarchived Topic; it creates a Topic when none is selected or the selected Topic is archived. Other built-in actions create Topics by default, and custom actions choose their destination. Append only within the current source, retaining the draft, model and permissions. Source addresses and excerpts are removable attachments. The plus button selects actual files or images; it does not manufacture references.
-3. Review the question, references, permissions and model, then click Send or press Enter. Shift + Enter inserts a newline; Enter during IME composition does not submit.
-
-Creating Topics, choosing wheel actions, changing models and quoting boards do not call a model. Wheel actions go directly to the Citer composer, where the user edits the question, references and model before sending. Custom actions targeting an existing Topic append their prompt after the current draft. Submitted prompts and references are recorded in the Topic's native log.
-
-Removing an unsent source attachment makes its reading tool reject access; new Topics do not silently inherit source history. Previously sent references remain in conversation history: removing a later draft copy does not retract them. Draft text, actual references and attachment bytes are stored in the owning Topic's `draft/` directory and restored after panel close, Topic switches, reload and restart. Restoration never sends a message. Model, reasoning and permission choices continue to use host-persisted state. Background polling in another window does not replace the last-used Topic; navigation restoration follows explicit actions.
-
-Drafts do not enter model logs or grant source access. Only host-confirmed submission contents are cleared; edits made during submission survive. Rejected sends retain the draft. Lost responses display a pending state for explicit reconciliation or retry. Concurrent save conflicts preserve local input and ask which version to keep. Choosing the local draft restores attachment bytes still held by this window if another window removed them. Missing or damaged attachments surface errors. Permanent Topic deletion includes its draft. Older Desktop refuses writes to newer session formats; continue in the newer Web host instead of manually downgrading logs.
-
-## Permissions, input and queue
+Restart DSH and refresh the page after installing or upgrading. Do not use `dsh plugin allow-version` to force a plugin that does not match your host version. Do not run two host processes on the same DSH home.
 
-Model menus support arrow keys, Home/End and Enter. Submenu changes keep focus inside the menu; the model button retains focus and blocks repeated actions while saving.
+## Start from one question
 
-New Topics start **read-only**, even when their source has full access. The input's permission menu selects native DSH read-only, workspace-write or full-access mode. Modification requires an explicit user mode choice or changed new-Topic default. DSH approval, sandbox and tool policies remain active.
+Say your agent changed some code and you wonder: "Why does this async save affect typing?"
 
-Input controls are attachments, permission mode, model/reasoning and Send. Choose the model first, then one of its supported reasoning levels. Images and generic files use native DSH attachment services, with upload state and retry. Select files from the attachment menu, paste images into the input, or drop files onto the Citer panel. The drop invitation names the receiving Topic; release adds attachments only to that Topic. Drops are unavailable without a current Topic, and files dropped into Citer are not copied into the source draft. Mixed image and text paste retains both. Sent files show a download icon and filename; click to save the original attachment. Click a historical image to preview it inside the host. Escape, the backdrop or the close button dismisses the preview and restores focus to the image. User messages omit the role label. Host rejection shows its cause and retains the draft; an accepted message is cleared even if the subsequent status read fails.
+1. Select the relevant text in the conversation, a tool result or a document, hold the right mouse button to open the wheel, and choose 自由提问 (free question) or 解释这段 (explain this).
+2. Citer opens a draft with the source address and the excerpt as removable attachments. Write your question, choose a model, and send it yourself.
+3. Keep asking about the material; when it helps, have the model draw the flow on the blackboard or summarize learning cards.
+4. Go back to the task and check your understanding against the code, a tool result or a small experiment.
 
-While a reply runs, Enter and Send follow DSH's busy-send preference; Ctrl + Enter temporarily uses the other delivery mode. Queued messages run after the current turn; steering is admitted at its next step. The composer toggle overrides the current Topic without changing the host default. Pending rows can be removed or changed to steering. Stop ends the response and preserves existing output; pending work follows DSH's queue rules.
+Creating a Topic or choosing a wheel action only prepares a draft; the model runs only after you send. Explanations and boards can still be wrong; they help you understand and check, not replace evidence.
 
-New Topics use standard programming tools under DSH permissions. Existing records retain their conversation and permissions when migrated into the source directory. Migration verifies every event; records that cannot be verified stay in their original store with an error report. Permissions are not expanded automatically.
+## Features
 
-DSH tool approvals, clarification questions and plan confirmations appear in their owning Topic, with decisions handled by the native host interaction service. Approval cards retain the tool name, reason and related parameters for inspection.
+| You want to | CiteCiter provides |
+| --- | --- |
+| Understand an answer, code or tool result | A separate Topic with a source citation; follow-ups never touch the main conversation |
+| See relationships and processes | A blackboard with Markdown, formulas, tables, SVG, images and sandboxed HTML; vision models can inspect the rendered board and fix it |
+| Keep what you learned | Learning cards you can export and revise, with prose and code examples shown separately |
+| Discuss real files | File and image attachments, a `.txt` / `.md` document reader, and a "CiteCiter 学习" entry in native file previews |
+| Act on what you understood | DSH models, tools, approvals, permissions, queueing and steering; new Topics are read-only by default |
+| Pick up where you left off | Drafts (text, references, attachments) and unsubmitted question answers are saved and restored after switching, refreshing or restarting, never sent automatically |
 
-Model-provided reasoning appears in an expandable Thinking row. While reasoning is streaming before the answer, the row shows Thinking in progress. Collapsed rows retain a one-line preview; expanding displays the full Markdown. Models that return no reasoning do not produce an empty row.
+## Using CiteCiter
 
-After the host accepts a manual submission, the transcript follows the latest message. Model output alone preserves the user's position while reading earlier messages.
+**Wheel and citations.** After selecting text, hold the right mouse button to open the eight-slot wheel, move to an action and release. A short right click lets you click a slot, Shift + right click keeps the browser menu, the arrow keys, digits 1–8 and Enter also select, and Esc cancels. 自由提问 adds the selection to the selected, unarchived Topic, or creates one if none is available; other actions create a new Topic by default. Slots, prompts, the default model and where the panel opens are all configurable in Settings.
 
-## Learning, boards and images
+**Composer.** The composer offers attachments, permission mode, model and reasoning effort, and Send. Enter sends, Shift + Enter adds a line, and Enter never sends during IME composition. While a reply is generating, Enter follows DSH's queue/steer preference and Ctrl + Enter uses the other one. Add files from the attachment menu, paste images, or drop files onto the Citer panel.
 
-Learning route is off by default. While off, the current prompt prevents old messages or todo items from reviving a teaching route; a single explanation or board request does not enable it. Ordinary coding plans remain available. When enabled, a submitted question asks the model to select and maintain a plan through DSH `todo_write`, using underlying logic, qualitative analysis, quantitative board work, concept connections and summary cards as needed. The user's scope, length, tool constraints and card count take precedence; the route does not expand the request into one task per stage.
+**Drafts.** Drafts save silently in the background. Edits to the same Topic from several windows merge automatically; where they overlap, the window you are typing in wins. After a successful send, only what was sent is cleared, and anything written meanwhile is kept.
 
-The board appears once, in the host conversation's blackboard tab. It supports text, Markdown, math, tables, SVG, images and isolated HTML. Quoting adds a draft attachment; math renders as math rather than raw object fields. Read, export and revise cards in Citer's Cards view. Examples explicitly use text or code: text renders as Markdown; code uses the native code block with its language, line breaks, indentation and copy button. Exports include code fences, and older cards remain readable.
+**Learning route and cards.** The learning route is off by default; when on, the model plans its explanation with DSH todos. You can ask for learning cards at any time; the model checks conclusions, conditions and calculations first, but self-checking does not guarantee correctness. Active recall is off by default; when on, cards show their self-test question first.
 
-`blackboard_view` returns a browser-rendered PNG to an image-capable model, allowing it to inspect clipping, labels, arrows and layout before updating the board. The image contains only the board, not the conversation or window layout. A separate capture worker renders the requested Topic and board revision offscreen at 1000×680 when another Topic is selected, the Citer panel is closed, or a narrow layout hides the board. Keep the DSH Web or Desktop page connected. SVG colors are preserved; Markdown code uses backgrounds suited to the dark board. Sandboxed HTML iframes cannot be captured; use SVG for inspectable diagrams.
+**Images.** Image generation and viewing tools come from host plugins such as [Codex Connect](https://github.com/franksong2702/dsh-codex-connect), enabled separately in each profile.
 
-Compatible host plugins can provide `codex_connect_image_generate` and `view_image` to Topics. Citer does not manage their accounts. The current upstream [dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect) `0.1.0-alpha.4.52` supports DSH RC1/RC2 without local patches or version exceptions. Image capabilities are off by default: open Settings → Built-in plugins → Codex Connect → Capabilities, enable GPT Image generation, and save. Web and Desktop have separate profiles; configure each profile separately. Installation alone does not enable the tools. `view_image` has its own Enable view_image tool switch; enabling image generation does not enable it. Generation, uploaded-image editing and display are tracked in the [current acceptance record](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-27-connect-450.md); previous versions do not establish current acceptance.
+## Permissions and data
 
-Before saving cards, the model is instructed to check definitions, conditions, derivations, numbers and contradictions, then correct or mark unverified claims. Self-review does not ensure factual accuracy; acceptance found and corrected a model error. See the [validation record](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-12-native-real-model.md). Active recall is optional and off by default. There is no spaced repetition, reminder or streak system.
+New Topics are **read-only** by default, even when the source session has more permissions. A Topic can change the workspace only after you choose another permission mode in the composer or change the default for new Topics in Settings; DSH approvals and sandboxing still apply.
 
-## Topics and layout
+Topics appear only in the Citer list, never in DSH's session list. Double-click a title or press F2 to rename it; an archived Topic returns to the list when you send to it again. Permanent deletion asks for the full Session ID and removes only that Topic's records, drafts and attachments.
 
-The list icon opens searchable Topics for the current source; ＋ creates a blank Topic. Double-click the title or press F2 to rename; Enter/blur saves and Escape cancels. Archive hides a Topic while preserving its records, and the archive list restores it. Submitting a new message in an archived Topic returns it to the active list after host admission; rejected submissions preserve the archive state and draft. Permanent deletion requires the full Session ID and removes only Citer-owned Topic files after releasing its runtime. Symlinks and paths outside the owned directory are rejected. Source Sessions are never deleted.
-
-Wide windows keep source and Citer side by side, with a resizable divider. Drag the title area away to float; release at the right window edge to dock. Opening native file details temporarily hides Citer when both panes cannot fit. Closing details restores the same Topic, draft and model. Explicitly selecting Citer or a file-selection action opens the compact Citer page; its top-left Back button restores the prior view. Without details, narrow screens use this page directly rather than placing Citer below the source. Closing restores host space and preserves Desktop captions.
-
-Surfaces use translucent backgrounds, blur and short transitions, respecting host themes and reduced-motion settings. A dedicated adapter owns layout changes; unknown host structures do not receive an intrusive full-screen fallback.
-
-## Storage and migration
-
-Topics appear only in Citer navigation. DSH does not recursively discover nested Topic logs. Citer owns live membership and navigation; native send services can address a loaded Topic by identity.
+CiteCiter stores its data in each source session's directory:
 
 ```text
 .dsh/sessions/<workspace>/<sourceSession>/
-├── session.v4.jsonl[.zstd]       DSH-owned source
+├── session.v4.jsonl[.zstd]   main session managed by DSH (never modified by Citer)
 └── citeciter/
-    ├── owner.json              Verified source ownership
+    ├── owner.json            directory ownership
     ├── <topicNumber>/
-    │   ├── topic.json          Title, archive state, model and source
-    │   ├── draft/              Unsent text, references and attachment bytes
-    │   └── sessions/<workspace>/<citerSession>/session.v4.jsonl
-    └── migration-backups/      Verified original copies
+    │   ├── topic.json        Topic information
+    │   ├── draft/            unsent text, references and attachments
+    │   ├── question-drafts/  unsubmitted question answers
+    │   └── sessions/         the Topic's own session log
+    └── deleted/              deletion records (identity only, no content)
 ```
 
-Citer owns creation, archive, restore and deletion. Archiving preserves the full log. Deletion leaves other Topics, the source and migration backups intact. Migration reads and writes through public DSH persistence APIs, compares the header and every event before switching the index, and retains originals. Moving verified old copies out of the main list requires an explicitly confirmed scope.
-
-Alpha uses v4 logs. DSH reads and migrates older v3 logs; Citer does not rewrite event sequences or `seedLength`. Sources with historical logs remain addressable through their physical source directory.
-
-## Documents and native preview
-
-While Citer is open, use the top-right … → Document reading action. The standalone reader launcher remains available when Citer is closed and no longer covers its composer.
-
-Click 📖 to import `.txt`, `.md` or `.markdown`. The reader preserves the full document, displays at most 500 KiB of UTF-8 text per page and accepts up to 2,000,000 characters. Paging clears the previous selection but keeps the question. Preparing a draft collapses the reader. The document address and excerpt are separate removable attachments.
-
-Document tools return the full UTF-16 length and actual read range. Search results expose the valid endpoint; reads distinguish the requested cap, returned endpoint and remaining content. Continue with nextFromOffset and omit throughOffset when the end is unknown. Invalid ranges report explicit bounds instead of silently clamping them.
-
-When the optional documentPreviews service is present, select “CiteCiter 学习” in native file preview. The host reads the file; Citer provides selectable source text, pagination and references. Creating a Topic stores a complete snapshot, unaffected by later file changes. Each snapshot is limited to 8 MiB / 2,000,000 characters and requires a source Session address.
-
-This branch compiles against public subpackage types `0.1.7-rc.2`; the preview service remains optional. Without it, conversation actions and the independent reader remain usable. The learning viewer does not provide PDF text extraction, Word parsing or OCR. Selections from different documents can join one Topic; reads identify documents by their submitted attachment addresses.
-
-## Wheel settings
-
-Configure the trigger, default model and eight slots in Settings → CiteCiter. Defaults are Ask, Explain, Find errors, Translate, Quantitative board, Summary cards and two empty slots. Each slot has a prompt, input hint, draft destination, content mode and default placement. Save slot edits explicitly.
-
-A short right-click leaves a clickable wheel; Shift + right-click preserves the native menu. Arrow keys, digits 1–8 and Enter select actions. Center, empty slots, outside release, Escape, source changes or wheel blur cancel. There is no preliminary question dialog; the Citer composer owns the draft.
+Topics created before 0.8 are migrated into this layout at startup; their original logs are kept.
 
-## Sibling project
+## Known issues
 
-CiteCiter and [Claude2DSH](https://github.com/kirkchinese/claude2dsh), by the same author, serve one workflow: moving knowledge between agent tools and then reusing it.
+- On Windows, PowerShell in read-only mode may report a language-mode error or print garbled Chinese. This is a limitation of the DSH executor inside the read-only sandbox; CiteCiter does not loosen permissions to work around it.
+- After the official Desktop restarts, other browser tabs still connected to the old backend may go blank; refreshing restores them. This also happens with CiteCiter disabled.
+- Using different DSH versions one after another at the same browser address can leave the host's own draft data in an incompatible format so the main conversation does not render; use a different address or port per version.
+- The plugin is mainly tested on Windows; Linux and macOS have not been systematically tested, and reports are welcome.
 
-- **Claude2DSH** — migrates Claude Code conversations, skills, subagents, slash commands, memory and MCP servers into DeepSeek Harness as native resumable sessions and assets, and exports back. It brings the past context in; CiteCiter keeps what you conclude from it traceable.
+## Why CiteCiter
 
-Both follow the same rules: public extension points only, nothing written into a foreign tool's directory without explicit authorization, and a real-profile acceptance run before every release. If you are reorganizing past sessions, importing first makes citing them much easier.
+Practice usually produces two things: a result and a skill. We form judgment by trying, making mistakes, comparing approaches and verifying. AI can take over more and more of the execution, but it does not automatically hand the matching understanding to its user, so finishing a task and growing as a person can come apart.
 
-## Development and acceptance
+CiteCiter turns real AI work into material you can cite, question and check. Start from the question in front of you, understand the principle, look at the evidence, and continue with a better understanding. Even when an agent does the work, people still need to set goals, understand the key conditions, judge whether a result applies, and take over when something goes wrong.
 
-[Contributing](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/CONTRIBUTING.md) · [Alpha changes](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/releases/v0.9.0-alpha.2.md) · [Current acceptance status](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-27-connect-450.md) · [0.8.2 fix notes](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/releases/v0.8.2.md)
+## Feedback
 
-Host and Client compile separately. Native session adaptation, source reading, index storage, attachments, queue, board capture, learning plans and UI controls are separate modules. The DSH Agent Loop is unchanged. The full host input component has no supported cross-session embedding interface; Citer reuses public ConversationController / SessionFace behavior and does not automatically inherit every third-party composer extension.
+Bring a task where "the agent finished, but I still can't explain it" to the [issue tracker](https://github.com/kirkchinese/CiteCiter/issues). Include your DSH and plugin versions and whether you got stuck installing, citing and asking, or understanding the answer. Remove keys and private content before pasting material.
 
-Artificial model providers, test directories and temporary acceptance scripts have been removed from the current branch, with Git history preserved. CI checks dependencies, types, build and packaging. Functional acceptance uses real models, real source branches and actual UI; the validation record states coverage and unfinished work.
+See [CONTRIBUTING.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/CONTRIBUTING.md) for development and [docs/product.zh.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/docs/product.zh.md) (Chinese) for the product rules. [Claude2DSH](https://github.com/kirkchinese/claude2dsh), by the same author, migrates sessions and assets between Claude Code and DSH.
 
 MIT License.

package/README.zh.md

@@ -1,188 +1,118 @@
 # CiteCiter
 
-[English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
+[English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [更新记录](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/CHANGELOG.md) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-> **0.8.0 已弃用。** Linux 通过符号链接启动 DSH 时，可能无法创建或恢复 Topic，报找不到 `@deepseek-ai/dsh-agent-loop`。使用 DSH 0.1.5-rc.1 / Desktop 2.0.9 时，请升级到 [0.8.2](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.8.2)；DSH 0.1.7 请先阅读下方兼容说明。
+![CiteCiter](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.9.0-beta.1/assets/hero/citeciter-hero.png)
 
-CiteCiter 为 DeepSeek Harness 提供带来源引用的独立工作区。可从主对话、工具结果和文档建立 Topic，处理文字、编程、图像和学习任务。新 Topic 使用 DSH 原生会话、权限、模型、附件与消息队列，来源对话继续独立工作。
+**AI 已经完成了任务，我还想弄明白它是怎么做的。**
 
-[![CiteCiter 演示视频：边做边学](https://raw.githubusercontent.com/kirkchinese/CiteCiter/feat/dsh-latest-usability/assets/docs/video-cover.png)](https://www.bilibili.com/video/BV1tqeA65EJ8/)
+CiteCiter 是 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 的插件，帮助你从 Agent 的真实工作中学习。选中对话、工具结果或文档中的一段内容，在保留来源的独立 Topic 里追问，用小黑板理解关键关系，再回到原来的工作。主对话不会被改动。
 
-[在 B 站观看演示](https://www.bilibili.com/video/BV1tqeA65EJ8/)。视频展示已发布版本；本分支的轮盘分流和 alpha 适配见下文。
+[![CiteCiter 演示](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.9.0-beta.1/assets/docs/video-cover.png)](https://www.bilibili.com/video/BV1tqeA65EJ8/)
 
-![Citer 原生工作区与手动发送流程示意](https://raw.githubusercontent.com/kirkchinese/CiteCiter/feat/dsh-latest-usability/assets/docs/native-workspace.svg)
+[在 B 站观看演示](https://www.bilibili.com/video/BV1tqeA65EJ8/)（早期版本录制，界面与当前版本略有不同）。
 
-上图为 0.8 工作区示意，非运行截图，其中学习路线处于手动开启状态。本分支的引用流程如下；模型仍在用户发送后才开始回答。
+## 安装
 
-```mermaid
-flowchart LR
-  S[实际选文] --> W[轮盘动作]
-  W --> F[自由提问]
-  W --> N[其他内置动作]
-  W --> C[自定义目标]
-  F --> A{已选中同源未归档 Topic?}
-  A -->|是| D[追加到已有草稿]
-  A -->|否| T[新建 Topic 草稿]
-  N --> T
-  C --> D
-  C --> T
-  D --> E[编辑引用、问题和模型]
-  T --> E
-  E --> M[手动发送]
-```
-
-## 版本与安装
+CiteCiter 需要 DSH 和一个可用的模型。插件声明了精确的宿主版本，请按 DSH 版本选择对应的 CiteCiter：
 
-本版为 **0.9.0-alpha.2 默认安装的预发布版（npm latest / next）**，适配 Web DSH `0.1.7-rc.2` 和 [DSH Desktop 2.0.15](https://github.com/anywhere-labs/dsh-desktop/releases/tag/v2.0.15) 内置的同版 DSH。保留 DSH `0.1.5-rc.2` 的独立 Host/Client 编译检查；旧版编译通过不代表最新 Desktop 功能通过。Web 与 Desktop 的真实模型验收范围见文末记录；不将旧 SDK 编译结果视为实机功能验证。旧版 **0.8.2** 仅保留给旧宿主，兼容基线为 DSH `0.1.5-rc.1` / Desktop `2.0.9`。Node.js 要求 `^22.19.0 || >=24.0.0`。本轮不验收 Linux。
+| DSH 版本 | CiteCiter 版本 |
+| --- | --- |
+| `0.2.0-rc.2`（含官方桌面版）、`0.2.1-alpha.1`、`0.2.1-alpha.2` | `0.9.0-beta.1` |
+| `0.1.7-rc.2` | `0.9.0-alpha.3` |
+| `0.1.5-rc.1` | `0.8.2` |
+| `0.1.2-rc.1` | `0.6.0` |
 
-**DSH 0.1.7 不能使用 0.8.2。** 旧版的精确 peer 范围不匹配；强制安装后还会因 Typert 缺少 `create()` 工厂而启动失败，见 [Issue #9](https://github.com/kirkchinese/CiteCiter/issues/9)。本版已适配 RC2 的版本检查及 Host/Remote 工厂接口，无需 `allow-version`。请安装本预发布版，不要将旧版强行加入兼容例外。
+**官方桌面版：** 在插件页安装 npm 包 `@kirkchinese/dsh-citeciter`，或在 Git 地址一栏填写 `https://github.com/kirkchinese/CiteCiter.git`，然后按提示重启。
 
-| 版本 | 状态 | 主要差异 |
-| --- | --- | --- |
-| 0.9.0-alpha.2 | 默认预发布，npm latest / next | 更新检查支持预发布版本；相同版本不再重复提示升级 |
-| 0.9.0-alpha.1 | 早期预发布 | 双宿主适配、持久草稿、PTC 工具展示、引用追加与学习路线约束 |
-| 0.8.2 | 旧宿主版本 | 明确来源读取上界与续读位置，恢复原生 Topic 首答建议追问 |
-| 0.8.1 | 已发布 | 修复 Linux/macOS 符号链接启动时无法打开 Topic |
-| 0.8.0 | 已弃用，请升级 0.8.2 | Linux 符号链接启动错误会阻止 Topic 打开 |
-| 0.7.0-beta.3 | 前一开发候选版 | 私有只读 Topic、选文轮盘、手动五阶段学习 |
-| 0.6.0 | 已发布 | DSH 0.1.2-rc.1 / Desktop 2.0.5 基线 |
+**命令行与 Web：**
 
-DSH 0.1.7 用户安装本预发布版：
-
-```powershell
-npm install -g @deepseek-ai/dsh@0.1.7-rc.2
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.9.0-alpha.2
-dsh web
+```sh
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.9.0-beta.1
 ```
 
-`latest` 和 `next` 均指向 0.9.0-alpha.2；版本号仍为预发布。DSH 0.1.5-rc.1 / Desktop 2.0.9 用户须显式安装 0.8.2。旧版内置更新检查可能无法识别预发布版本，请使用上面的安装命令升级。旧宿主 DSH 0.1.2-rc.1 / Desktop 2.0.5 应继续使用 @kirkchinese/dsh-citeciter@0.6.0。如 npm 提示本地原生依赖的安装脚本被阻止，按 npm 输出对明确列出的依赖放行后重装。不要通过全局关闭脚本限制解决。
-
-0.8.0 在 Linux/macOS 通过符号链接启动 DSH 时，可能无法打开 Topic，报找不到 dsh-agent-loop。0.8.1 先解析 CLI 入口真实路径再加载宿主模块，保留 Desktop 的 app.asar 路径。Linux 原生 Node 回归已通过，macOS 尚未实测。
+也可以从仓库安装某个发布标签，仓库内已包含构建好的插件，安装时无需构建：
 
-本地构建并安装此分支：
-
-```powershell
-npm install -g @deepseek-ai/dsh@0.1.7-rc.2
-pnpm install --frozen-lockfile
-pnpm typecheck
-pnpm typecheck:desktop
-pnpm build
-pnpm --dir packages/citeciter pack --pack-destination E:/project/CiteCiter/.refs/artifacts
-dsh plugin --profile web add E:/project/CiteCiter/.refs/artifacts/kirkchinese-dsh-citeciter-0.9.0-alpha.2.tgz
+```sh
+dsh plugin --profile web add "git+https://github.com/kirkchinese/CiteCiter.git#v0.9.0-beta.1"
 ```
 
-Desktop 使用自己的内置 DSH。0.8.2 对应已验收的 Desktop 2.0.9 基线；本版针对 Desktop 2.0.15，在其管理终端执行 `dsh plugin add @kirkchinese/dsh-citeciter@0.9.0-alpha.2`。全局 CLI 更新不会更新 Desktop 内置运行时。安装后重启相应宿主。同一 DSH home 不要同时运行 Web 和 Desktop 写入进程。
-
-已知宿主限制：Windows 只读 PowerShell 的编码初始化可能被受限语言模式拒绝，部分中文输出可能乱码。Citer 保留原始错误，不提高权限或隐藏输出；此问题等待 DSH 修复。本次预发布不包含 Linux/macOS 或 Desktop NEXT 外壳的实机验收声明。
-
-## 来源读取与建议追问
-
-`read_source_session` 按字节预算分页。`sourceMaxSeq` 是本次快照的可读上界；`availableThroughSeq` 是旧版请求上界标记，不能用它判断来源结束。`hasMore` 为 true 时，以 `nextFromSeq` 作为下一次 `fromSeq`，省略 `throughSeq` 继续读取。`truncated` 只表示当前范围因字节预算停止；空页、过滤事件及超大内容占位不代表来源不存在。Observer 每次读取当前已提交事件，Exact Fork 只读取继承前缀。
-
-原生 Topic 的首答默认提供三条建议追问，可在 CiteCiter 设置中关闭。用户本次要求不附建议、只给结果或严格限定格式与篇幅时，提示词要求省略追问。点击建议只填入草稿，手动发送后才调用模型。来源说明和建议追问由独立提示词模块提供；来源内容继续按已发送附件读取。
-
-## 草稿与引用
-
-1. 在主对话选中文字，按住右键打开八槽轮盘，移向动作后松开。也可从工具结果、文档阅读器或原生文件预览创建 Topic。
-2. “自由提问”把选文加入当前选中的未归档 Topic；未选中或当前 Topic 已归档时新建。其他内置动作默认新建，自定义动作可选择目标。只在当前来源会话内追加，保留已有草稿、模型和权限。来源地址与选文显示为可移除附件；加号仅选择实际图片或文件，不生成引用。
-3. 检查问题、引用、权限和模型，点击发送或按 Enter。Shift + Enter 换行；输入法组词期间 Enter 不发送。
-
-创建 Topic、选择轮盘动作、切换模型、引用板书均不调用模型。轮盘动作直接进入 Citer 输入框，在同一处编辑问题、引用和模型，再手动发送。自定义动作追加到已有 Topic 时，其提示词追加在已有草稿后。模式提示词和发送时的引用写入 Topic 原生日志。
-
-未发送的来源附件被删除后，来源读取工具会拒绝读取该来源；新 Topic 不隐式复制来源历史。已经发送的附件属于历史消息，删除后续草稿中的副本不会撤回历史上下文。草稿的文字、真实引用和附件内容保存在所属 Topic 的 `draft/` 目录，关闭面板、切换 Topic、刷新和重启后恢复；恢复本身不发送消息。模型、思考强度和权限以宿主保存的状态为准。后台窗口的轮询不改写上次使用的 Topic；导航恢复按主动操作记录。
-
-草稿不写入模型日志，也不授予来源读取权限。宿主确认接收后，只清除本次提交内容，发送期间新增的编辑保留。发送失败保留草稿；响应丢失时显示待核对状态，用户核对或明确重试后才继续。并发保存冲突保留本地输入并提示选择版本；明确保留本窗口时，会重新保存被另一窗口移除、但本窗口仍持有的附件；缺失或损坏附件明确报错。永久删除 Topic 同时删除其草稿。旧 Desktop 遇到较新的会话日志格式时拒绝写入，须回到新版 Web 继续，不手工降级日志。
-
-## 权限、输入与队列
+安装或升级后重启 DSH 并刷新页面。不要用 `dsh plugin allow-version` 强行加载与宿主版本不匹配的插件。同一个 DSH 主目录不要同时运行两个宿主进程。
 
-模型菜单支持方向键、Home/End 与 Enter。切换子菜单后焦点留在菜单内，保存期间模型按钮保留焦点并阻止重复操作。
+## 从一个疑问开始
 
-新 Topic 默认 **只读**，即使来源会话具有完全权限。输入框的权限菜单使用 DSH 的只读、工作区内修改、完全权限模式。只有用户主动选择模式或更改新 Topic 默认值后，才允许相应修改。DSH 审批、沙箱和工具限制继续生效；插件不绕过权限服务。
+例如，Agent 修改了程序，你想知道"为什么这段异步保存逻辑会影响输入？"
 
-输入框从左到右为附件、权限模式、模型与思考强度、发送。模型菜单先选模型，再选该模型支持的思考强度。图片和普通文件通过 DSH 原生附件服务发送，文件显示上传状态，失败可重试。可从附件菜单选择文件，在输入框粘贴图片，或拖入 Citer 面板。拖放提示显示接收的 Topic，松开只向该 Topic 添加附件；没有可用 Topic 时不接收。主对话不会收到拖入 Citer 的副本。混合粘贴时同时保留图片与文字。已发送文件显示下载图标与文件名，点击保存原附件。点击历史图片在宿主内预览；按 Esc、点击遮罩或关闭按钮返回，键盘焦点恢复到原图片。用户消息不显示角色标签。宿主拒收时显示原因并保留草稿；宿主已接收的消息不会因后续状态读取失败而重新留在输入框。
+1. 在主对话、工具结果或文档中选中相关内容，按住右键打开轮盘，选择"自由提问"或"解释这段"。
+2. Citer 打开草稿，来源地址和选文作为可移除的附件。写下问题、选择模型，再手动发送。
+3. 围绕这段材料继续追问；需要时让模型在小黑板上画出流程，或整理成学习卡。
+4. 回到原任务，用代码、工具结果或一次小实验检查自己的理解。
 
-回答运行时，Enter 和发送按钮跟随 DSH 设置中的“繁忙时的发送行为”；Ctrl + Enter 临时使用另一种方式。排队在当前轮结束后处理，插话由 DSH 在当前轮的下一步接收。输入区的切换按钮只覆盖当前 Topic，不改写宿主默认值。队列显示待处理内容，可移除或转为插话。停止结束当前回答并保留已生成内容；待处理队列继续遵循 DSH 规则。
+创建 Topic 或选择轮盘动作只会准备草稿，模型只在你手动发送后运行。解释和板书仍可能出错；它们帮助你理解和检查，不代替事实证据。
 
-新 Topic 可使用标准编程工具，操作范围由 DSH 权限决定。旧版记录迁入来源目录后仍保留原有对话和权限。迁移会逐条核验日志；无法核验的记录保留原存储并报告，不自动扩大权限。
+## 功能
 
-DSH 工具审批、补充问题和计划确认显示在对应 Topic 中，决定交回宿主原生交互处理。审批卡保留工具名称、理由及关联参数供查看。
+| 你想做什么 | CiteCiter 提供什么 |
+| --- | --- |
+| 理解一段回答、代码或工具结果 | 带来源引用的独立 Topic，追问不会写入主对话 |
+| 看懂关系与过程 | 支持 Markdown、公式、表格、SVG、图片和隔离 HTML 的小黑板；支持视觉的模型可以查看渲染后的板书并自行修正 |
+| 留下可回看的理解 | 可导出、可修订的学习卡，文字与代码示例分开展示 |
+| 围绕真实文件讨论 | 文件与图片附件、`.txt` / `.md` 文档阅读器、原生文件预览中的"CiteCiter 学习"入口 |
+| 从理解继续动手 | 复用 DSH 的模型、工具、审批、权限、排队和插话；新 Topic 默认只读 |
+| 暂停后继续 | 草稿（文字、引用、附件）和未提交的问答自动保存，切换、刷新或重启后恢复，不会自动发送 |
 
-模型返回的思考内容显示为可展开的“思考”行；生成思考而尚无正文时显示“思考中”。折叠状态保留一行预览，展开后显示完整 Markdown。未返回思考内容的模型不显示空行。
+## 使用说明
 
-手动发送被宿主接收后，消息区跳到最新内容。仅模型继续输出时，保留用户向上阅读的位置。
+**轮盘与引用。** 选中文字后按住右键打开八格轮盘，移向动作后松开；短按右键可点击选择，Shift + 右键保留浏览器菜单，方向键、数字 1–8 和 Enter 也可选择，Esc 取消。"自由提问"把选文加入当前选中的未归档 Topic，没有可用 Topic 时新建；其他动作默认新建。轮盘的八个槽位、提示词、默认模型和打开位置都可以在设置中修改。
 
-## 学习、板书与图片
+**输入。** 输入框依次提供附件、权限模式、模型与思考强度、发送。Enter 发送，Shift + Enter 换行，输入法组词时 Enter 不会发送。生成过程中 Enter 跟随 DSH 的排队／插话设置，Ctrl + Enter 临时使用另一种方式。可以从附件菜单选择文件、粘贴图片，或把文件拖到 Citer 面板上。
 
-“学习路线”默认关闭。关闭时，当前提示词明确禁止从旧消息或旧待办恢复教学路线；单次讲解或板书不等于开启路线，也不禁用编程任务的普通计划。开启后，用户发送问题时要求模型通过 DSH `todo_write` 自行选择、排列和更新学习计划。可选方式包括底层逻辑、定性分析、定量板书、概念关联和总结卡片，按内容取舍。用户指定的范围、篇幅、工具限制和卡片数量优先，不按阶段扩充任务。
+**草稿。** 草稿在后台静默保存。多个窗口编辑同一个 Topic 时，各自的修改会自动合并；同一处有冲突时，以正在输入的窗口为准。发送成功后只清除已发送的部分，发送期间新写的内容会保留。
 
-小黑板统一显示在主区“小黑板”标签。支持文本、Markdown、公式、表格、SVG、图片和隔离 HTML。板书引用进入草稿附件，公式渲染为数学内容，不显示原始对象字段。学习卡在 Citer 的“学习卡”视图查看、导出和修订。示例分为文字与代码：文字按 Markdown 展示，代码使用原生代码块，保留语言、换行、缩进及复制按钮。导出包含代码围栏，旧卡片继续兼容。
+**学习路线与学习卡。** 学习路线默认关闭；开启后，模型会根据问题用 DSH 待办安排讲解步骤。学习卡可以随时单独请求，生成前模型会核对结论、条件和计算，但自查不能保证正确。主动回忆默认关闭，开启后学习卡先显示自测问题。
 
-`blackboard_view` 把浏览器真实渲染的 PNG 返回给支持视觉输入的模型。模型可检查遮挡、标签、箭头和布局后继续修改板书。截图仅包含板书，不包含主对话或窗口布局；切换 Topic、关闭 Citer 面板或窄屏隐藏板书后，独立截图模块仍按请求中的 Topic 和版本使用相同组件进行 1000×680 离屏渲染。需保持 DSH Web 或 Desktop 页面连接。SVG 保留原始颜色，Markdown 代码使用适合深色板书的背景。沙箱 HTML iframe 暂不支持截图，需改用 SVG 才能进行此视觉检查。
+**图像。** 生成和查看图片的工具由 [Codex Connect](https://github.com/franksong2702/dsh-codex-connect) 等宿主插件提供，需要在对应的 Profile 中单独开启。
 
-宿主中的兼容插件可向 Topic 提供 `codex_connect_image_generate` 和 `view_image`，Citer 不代替其账户配置。当前使用上游 [dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect) `0.1.0-alpha.4.52`，同时支持 DSH RC1/RC2，不需要本地补丁或版本例外。图像能力默认关闭：在设置 → 内置插件 → Codex Connect → 能力中启用「GPT Image 图片生成」并保存。Web 与 Desktop 分别使用自己的 Profile，需要分别配置；安装插件本身不会启用工具。`view_image` 有独立的「启用 view_image 工具」开关；图片生成开关不会同时启用它。图像生成、上传图编辑和结果显示以[当前联调记录](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-27-connect-450.md)为准，旧版本结果不替代当前验收。
+## 权限与数据
 
-请求总结卡片时，模型先核对定义、条件、推导、数值及前后矛盾，再保存完整卡片组；无法核实的内容应标明或省略。自查不能保证知识正确，验收中已发现并纠正模型错误，见[验收记录](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-12-native-real-model.md)。主动回忆默认关闭，可在卡片中开启；不提供间隔复习、提醒或打卡。
+新 Topic 默认**只读**，即使来源会话拥有更高权限。只有你在输入框中选择其他权限模式，或在设置里修改新 Topic 的默认权限后，Topic 才能修改工作区；DSH 的审批和沙箱规则照常生效。
 
-## Topic 与布局
+Topic 只出现在 Citer 的列表里，不会出现在 DSH 的会话列表中。双击标题或按 F2 重命名；归档的 Topic 在你再次发送消息后自动恢复。永久删除需要输入完整的 Session ID，只删除这个 Topic 自己的记录、草稿和附件。
 
-点击列表图标浏览、搜索并切换当前来源的 Topic；＋建立空 Topic。双击标题或按 F2 重命名，Enter/失焦保存，Esc 取消。归档用于隐藏并保留记录，可从归档列表恢复。在归档 Topic 中手动发送新消息后，Topic 自动回到活动列表；发送被宿主拒绝时保留归档状态和草稿。永久删除要求输入完整 Session ID，只删除 Citer 自己维护的 Topic 目录；删除前停止并释放该 Topic，拒绝符号链接及越界路径。主 Session 不删除。
-
-宽窗口并排显示来源和 Citer，可拖动分隔线调整比例。拖动标题栏离开侧边后变为悬浮窗；拖回窗口右缘释放后停靠。空间不足时打开原生文件详情，Citer 暂时收起；关闭详情后恢复同一 Topic、草稿和模型。主动点击 Citer 入口或从文件选文时，可切回 Citer 独立页面，左上角返回键释放原界面。没有详情时，窄屏直接使用此独立页面，不把学习栏放到下方。关闭面板恢复宿主空间；Desktop 标题栏保留。
-
-菜单和面板使用半透明背景、背景模糊与短动效，支持宿主主题和系统减少动态效果设置。布局适配集中在独立模块中，未知宿主结构不会强制覆盖主界面。
-
-## 会话存储与迁移
-
-Citer 的 Topic 只出现在 Citer 列表。DSH 的会话磁盘索引不递归扫描 Topic 子目录；插件独立维护实时成员和导航，原生发送服务按身份访问当前 Topic。
+CiteCiter 的数据保存在每个来源会话的目录中：
 
 ```text
-.dsh/sessions/<工作区>/<主Session>/
-├── session.v4.jsonl[.zstd]       主会话，由 DSH 管理
+.dsh/sessions/<workspace>/<sourceSession>/
+├── session.v4.jsonl[.zstd]   DSH 管理的主会话（Citer 不会改动）
 └── citeciter/
-    ├── owner.json              来源与目录归属
-    ├── <Topic编号>/
-    │   ├── topic.json          标题、归档状态、模型和来源
-    │   ├── draft/              未发送文字、引用及附件字节
-    │   └── sessions/<工作区>/<CiterSession>/session.v4.jsonl
-    └── migration-backups/      已核验旧副本的备份
+    ├── owner.json            目录归属
+    ├── <topicNumber>/
+    │   ├── topic.json        Topic 信息
+    │   ├── draft/            未发送的文字、引用和附件
+    │   ├── question-drafts/  未提交的问答
+    │   └── sessions/         Topic 自己的会话日志
+    └── deleted/              删除记录（只含身份，不含内容）
 ```
 
-新建、归档、恢复和删除均由 Citer 管理。归档保留全文；删除不影响其他 Topic、主 Session 或迁移备份。迁移使用 DSH 公开持久化接口读取和写入，核验头部和全部事件后才切换索引；旧副本保留，清除主列表重复入口时需明确确认移动范围。
-
-alpha 的当前格式为 v4。旧 v3 文件由 DSH 读取及迁移，Citer 不直接改写事件序号或 `seedLength`。仅存在历史日志时仍按来源实体目录定位 Citer 数据。
-
-## 文档与原生预览
-
-Citer 打开时，从右上角“…” → “文档阅读”进入阅读器；关闭 Citer 后保留独立读书入口，避免悬浮按钮遮挡输入区。
-
-点击 📖 导入 `.txt`、`.md`、`.markdown`。阅读器保存全文，每页最多 500 KiB UTF-8 文本，导入最多 2,000,000 字符。翻页清除旧选区、保留问题；选文并准备草稿后自动收起阅读器。文档地址和选文分别作为待发送附件，可独立删除。
-
-文档工具返回 UTF-16 总长度与实际读取区间。搜索结果提供可用终点；读取结果区分请求终点、实际终点和后续内容，续读使用 nextFromOffset。未知终点可省略 throughOffset；越界错误给出具体合法范围，不静默截断。
-
-安装了可选 documentPreviews 服务时，在原生文件预览中选择“CiteCiter 学习”。宿主读取文件，Citer 提供可选取的源文本、分页与引用；创建 Topic 时保存完整快照，文件之后的变化不会改写该快照。单个快照最多 8 MiB / 2,000,000 字符，必须携带来源 Session 地址。
-
-本分支按子包 `0.1.7-rc.2` 的公开类型编译，服务仍为可选。缺少服务时，对话轮盘与独立阅读器仍可用。学习查看方式不提供 PDF 文本层、Word 解析或 OCR。不同文档可追加到同一 Topic；模型按已发送的文档地址选择读取对象。
-
-## 轮盘设置
-
-在“设置 → CiteCiter”选择触发键、默认模型和八个槽位。默认槽位为自由提问、解释这段、找错误、翻译、定量板书、总结卡片、两个空槽；每槽可设置提示词、输入提示、引用目标、内容方式及默认位置。槽位更改需点击保存。
-
-右键短按保留可点击轮盘，Shift + 右键使用原生菜单；可用方向键、数字 1–8 和 Enter 选择。中心、空槽、轮盘外、Esc、来源切换或轮盘失焦取消动作。没有额外的补充问题弹窗；草稿由 Citer 输入框统一管理。
+0.8 之前版本创建的 Topic 会在启动时自动迁移到这个目录，原始日志保留不动。
 
-## 兄弟项目
+## 已知问题
 
-CiteCiter 与同作者的 [Claude2DSH](https://github.com/kirkchinese/claude2dsh) 面向同一类工作流：在多个 agent 工具之间迁移并复用知识。
+- Windows 上，只读模式下的 PowerShell 可能报语言模式错误或输出中文乱码。这是 DSH 执行器在只读沙箱中的限制，CiteCiter 不会为此放宽权限。
+- 官方桌面版重启后，仍连接着旧后台的其他浏览器标签页可能白屏，刷新即可恢复；停用 CiteCiter 时同样会出现。
+- 在同一个浏览器地址上先后使用不同版本的 DSH，宿主自己保存的草稿格式可能不兼容，导致主对话无法显示；不同版本请使用不同的地址或端口。
+- 插件主要在 Windows 上测试；Linux 与 macOS 未经系统测试，遇到问题欢迎反馈。
 
-- **Claude2DSH** —— 把 Claude Code 的会话、技能、子 agent、斜杠命令、记忆与 MCP 服务器迁移为 DSH 原生可续聊会话与资产，并支持反向导出。它负责「把过去的上下文搬进来」，CiteCiter 负责「让搬进来之后的答案可追溯」。
+## 为什么做 CiteCiter
 
-两者遵循同一套约定：只使用公开扩展点、未经显式授权不写入外部工具目录、发布前跑真实 profile 验收。如果你正在整理历史会话，先迁入再引用会顺手很多。
+实践通常同时产生两样东西：成果和能力。我们通过尝试、犯错、比较方案和验证，逐渐形成判断。AI 可以接手越来越多的执行，却不会自动把相应的理解交给使用者，任务完成与人的成长可能因此分离。
 
-## 开发与验收
+CiteCiter 尝试把真实的 AI 工作过程变成可引用、可追问、可检验的学习材料。从眼前的一个疑问出发，理解原理、查看证据，再带着新的认识继续工作。即使把执行交给 Agent，人仍需要提出目标、理解关键条件、判断结果是否适用，并在出现异常时接管。
 
-[开发规范](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/CONTRIBUTING.zh.md) · [alpha 变更说明](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/releases/v0.9.0-alpha.2.md) · [本轮验收状态](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/validation/2026-09-27-connect-450.md) · [0.8.2 修复说明](https://github.com/kirkchinese/CiteCiter/blob/feat/dsh-latest-usability/docs/releases/v0.8.2.md)
+## 反馈
 
-Host 和 Client 分别编译。原生会话适配、来源读取、索引存储、附件、发送队列、板书截图、学习计划和 UI 控件独立实现；不修改 DSH Agent Loop。完整宿主输入组件尚无跨会话嵌入接口，Citer 通过公开 ConversationController / SessionFace 复用行为，不能自动继承所有第三方输入区扩展。
+欢迎带着"Agent 已经完成了，但我还讲不清"的任务来[反馈](https://github.com/kirkchinese/CiteCiter/issues)。请写明 DSH 和插件版本，以及卡在安装、引用追问还是理解回答。贴材料前请移除密钥和私人内容。
 
-当前分支已移除人工模型提供者、测试目录与临时验收脚本，保留 Git 历史。CI 进行锁文件、类型、构建和打包检查。功能验收使用真实模型、真实来源分支及实际 UI，覆盖情况与未完成项以验收记录为准。
+开发说明见 [CONTRIBUTING.zh.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/CONTRIBUTING.zh.md)，产品规则见 [docs/product.zh.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.1/docs/product.zh.md)。同作者的 [Claude2DSH](https://github.com/kirkchinese/claude2dsh) 用于在 Claude Code 与 DSH 之间迁移会话和资产。
 
 MIT License.