@kirkchinese/dsh-citeciter 0.5.0 → 0.8.0

package/README.md

@@ -1,107 +1,126 @@
-# `@kirkchinese/dsh-citeciter`
+# CiteCiter
 
-Investigate any line in a DSH response—without stopping the Agent or changing the source Session. CiteCiter provides verifiable, source-bound, read-only side investigations for interactive DSH.
+[简体中文](README.zh.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
-![Select a DSH response and continue investigating in a private CiteCiter Topic](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
+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.
 
-*Select, right-click, and investigate beside the source while the main Agent keeps working.*
+![Native Citer workspace and manual submission diagram](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.0/assets/docs/native-workspace.svg)
 
-[简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
+This is an interaction diagram, not a screenshot. Selection actions prepare drafts; model work begins only after the user sends.
 
-## Highlights
+## Version and installation
 
-- **Exact source binding.** CiteCiter rechecks the visible selection against the committed response before creating a Topic.
-- **No need to wait.** A committed intermediate model call can be investigated while the surrounding Agent turn continues, including its reasoning or a selection spanning reasoning and answer text.
-- **Durable investigations.** Private Topics support natural follow-up questions and reopen after a refresh or restart.
-- **Evidence with no write access.** CiteCiter can inspect committed source events and search or read project files, but cannot change the source Session or workspace.
-- **Inspectable work.** Questions, answers, source reads, and project-file checks remain together in the investigation panel.
-- **Presenter Topics.** A read-only teacher can build a durable formula, diagram, table, or animation board through atomic tool commits while it explains.
-- **Side-by-side workflow.** The conversation concedes space whenever the panel and a usable conversation fit; tighter layouts fall back to an overlay.
-- **Web update notices.** CiteCiter checks npm's stable version and offers a copyable upgrade command without granting the browser package-management access.
+Current version: **0.8.0**. Baseline: DSH `0.1.5-rc.1`, [DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) `2.0.9`, Node.js `^22.19.0 || >=24.0.0`. Windows acceptance uses Node 24.19.0. DSH next, alpha and TUI are separate targets.
 
-## Use
+| Version | Status | Main differences |
+| --- | --- | --- |
+| 0.8.0 | Current version | Native Sessions, manual drafts, DSH permissions, attachments, queue and AI learning plans |
+| 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 |
 
-1. Select answer or reasoning inside a committed assistant model call. When reasoning is collapsed, begin the selection on its disclosure row; the row represents the complete model call. The surrounding Agent turn may still be running.
-2. Right-click the selection, enter your first question, and choose `开始提问` or `开始讲解`.
-3. CiteCiter creates a new Topic in the investigation panel.
-4. Continue asking questions there, or reopen an earlier Topic from CiteCiter's Topic rail.
-5. Change the Topic model, reasoning effort, title, archive state, or panel width without changing the source Session.
+Update the host CLI and install the published package:
 
-## Install v0.5.0
+```powershell
+npm install -g @deepseek-ai/dsh@latest
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.0
+dsh web
+```
 
-CiteCiter 0.5.0 requires Node.js `^22.19.0 || >=24.0.0` and DSH `>=0.1.1-rc.1 <0.1.1-rc.3`.
+This installs 0.8.0. 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.
 
-For DSH Web:
+Build and install this branch locally:
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
-dsh plugin --profile web list --depth 0
+```powershell
+pnpm install --frozen-lockfile
+pnpm typecheck
+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.8.0.tgz
 ```
 
-Confirm that the list shows `@kirkchinese/dsh-citeciter@0.5.0`, then restart DSH Web and refresh the page.
+Desktop bundles its own DSH. Update the Desktop application, then run `dsh plugin add <absolute package path>` 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.
+
+## 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. Citer opens an independent draft. Source conversation/document addresses and selected excerpts appear as removable attachments. Document chips show the filename; expand them to inspect the original path and snapshot address. Click × to remove a reference; the attachment menu can add sources and excerpts again.
+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. Actions that need a question first show an input and model choice. Other actions fill a preset question and still require manual Send. Submitted mode prompts and reference contents 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. Drafts survive panel close/reopen, Topic switches and window blur; browser reload or client exit does not retain unsent drafts or local attachments.
+
+## Permissions, input and queue
+
+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.
+
+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. 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.
 
-CiteCiter 0.5.0 is Web-only.
-Upgrading from v0.3 does not migrate or rewrite existing Topics, settings, or source Sessions.
-Users remaining on DSH `0.1.0-rc.7` should keep CiteCiter 0.3.2.
+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.
 
-## Context modes
+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.
 
-Observer is the default. It creates an independent Topic and reads committed source evidence on demand, including while the source turn is still running.
+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.
 
-Exact Fork is an advanced mode for a source turn that has already ended. `exact-when-available` uses Exact Fork when a stable boundary exists and otherwise falls back to Observer.
+## Learning, boards and images
 
-## Presenter board
+Learning route is off by default. When enabled, a submitted question asks the model to select and maintain a plan through DSH `todo_write`. It may use underlying logic, qualitative analysis, quantitative board work, concept connections and summary cards as needed; users do not click through stages individually.
 
-Presenter Topics use the standard Agent loop plus a scoped `blackboard_apply` tool. A board batch becomes visible only after its paired tool result succeeds; a failed or interrupted batch leaves the previous board intact. Refresh and restart project the final board from the private Topic Session rather than storing a second mutable copy.
+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.
 
-## Web update notices
+`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. When the tab is closed or the narrow layout hides the board, the same component renders offscreen at 1000×680. Keep Citer open during capture. SVG colors are preserved; Markdown code uses backgrounds suited to the dark board. Sandboxed HTML iframes cannot be captured; use SVG for inspectable diagrams.
 
-The Web client checks npm's `latest` stable version without blocking startup. A newer version appears in a persistent upper-right card with `更新`, `下次一定`, and `不再提示`: the first action copies the standard Web Profile install command, the second hides that version for the current tab session, and the third disables future checks until the CiteCiter settings page enables them again. CiteCiter never runs the install command; execute it in a terminal and restart DSH Web.
+When [dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect) and its image tools are enabled in the host, new Topics can use `codex_connect_image_generate` and `view_image`. Citer does not require the connector or manage its account setup. Real generation and viewing have been exercised with connector `0.1.0-alpha.4.34`.
 
-The first release containing the checker still needs one manual upgrade because an older installed build cannot run code it does not contain. Custom Web Profiles must replace `web` in the copied command. Check the newer release's DSH requirement before installing; the notice compares package versions and does not assert host compatibility. Desktop updates are outside this feature.
+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](../../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.
+
+## Topics and layout
+
+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. 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. When space is insufficient, Citer occupies the main content area with a Back button at the top left. Back restores the source. It never moves below the source on narrow screens. Closing restores host space; native details and Desktop captions remain available.
+
+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.
+
+```text
+.dsh/sessions/<workspace>/<sourceSession>/
+├── session.v3.jsonl[.zstd]       DSH-owned source
+└── citeciter/
+    ├── owner.json              Verified source ownership
+    ├── <topicNumber>/
+    │   ├── topic.json          Title, archive state, model and source
+    │   └── sessions/<workspace>/<citerSession>/session.v3.jsonl
+    └── migration-backups/      Verified original copies
+```
 
-## Host developer API
+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.
 
-0.5.0 provides the v1 Host service `ctx.citeciterRuntime` (`create`, `ask`, `get`, `list`, and `delete`) and the `citeciter/topic-created`, `citeciter/topic-updated`, and `citeciter/topic-deleted` events. Browser entry registration, presets, and a separate client face remain planned for M4/M5, so frontend extension APIs are not stable yet.
+## Documents and native preview
 
-## Supported hosts
+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.
 
-| Host | CiteCiter version | Notes |
-|---|---|---|
-| DSH Web `0.1.1-rc.1` and `0.1.1-rc.2` | `0.5.0` | Fresh-profile Linux package, assembled browser smokes, and a real DeepSeek provider run passed |
-| [DSH Desktop 2.0.2](https://github.com/anywhere-labs/deepseek-harness-desktop) with bundled DSH `0.1.1-rc.2` | Future target | Packaged Desktop installers have not been accepted yet |
-| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) development shell with DSH `0.1.1-rc.1` | `0.4.0` only | Historical Linux source-shell record |
-| DSH Web `0.1.0-rc.7` | `0.3.2` | Previous stable line |
-| DSH TUI | — | Not supported yet |
+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.
 
-The demo is only a workflow illustration. It is not packaged-Desktop acceptance evidence.
+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.
 
-## Limitations
+The preview's public type baseline is resolved subpackage `0.1.5-rc.2`; the top-level DSH version does not establish service availability. Without it, conversation actions and the independent reader remain usable. The learning viewer does not provide PDF text extraction, Word parsing or OCR.
 
-- A selection must include at least one committed assistant model call. User-only ranges, tool-only ranges, and still-streaming fragments cannot anchor a Citation. A committed model call's reasoning disclosure row may represent that complete call.
-- Renderer-generated KaTeX layout and footnote numbers cannot be cited directly because they lack stable source coordinates.
-- Exact Fork cannot start from an open source turn.
-- Source-file access depends on the running DSH filesystem service and remains read-only.
-- Read Frog translated selections are only a compatibility fallback for DSH rc.1/rc.2 and only activate when the full private marker set is present.
-- DSH still has no public right-dock extension point. When side-by-side layout fits, CiteCiter temporarily adjusts the layout; every new DSH version needs that path retested.
-- Topics are Host-durable. When Desktop restarts on a different loopback port, CiteCiter falls back to the most recently updated Topic because browser local storage is origin-scoped; configure a fixed Desktop port to restore the exact last-viewed Topic.
-- Permanent Topic deletion is owner maintenance over CiteCiter's fixed private JSONL root because DSH rc.2 has no Session deletion API. One active CiteCiter process must own a DSH home; sharing that home between live processes is unsupported.
-- CiteCiter 0.5.0 is Web-only; packaged Desktop support is still pending.
-- There is currently no TUI interaction adapter.
-- DSH is prerelease software; later DSH API versions may require a CiteCiter update.
+## Wheel settings
 
-## Community
+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, optional question step, content mode and default placement. Save slot edits explicitly.
 
-Questions, workflow ideas, and compatibility reports are welcome in the DSH-Citeciter QQ group (`1108040435`).
+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. The question dialog survives app blur and closes only on explicit dismissal or source change.
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="360" alt="QR code for the DSH-Citeciter QQ group 1108040435">
-</p>
+## Development and acceptance
 
-## Contributing
+[Contributing](../../CONTRIBUTING.md) · [0.8 release notes](../../docs/releases/v0.8.0.md) · [Real-model acceptance](../../docs/validation/2026-09-12-native-real-model.md)
 
-Issues and pull requests are welcome. Before submitting code, read the [contribution guide](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.md).
+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.
 
-## License
+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.
 
-MIT © CiteCiter contributors
+MIT License.

package/README.zh.md

@@ -1,107 +1,128 @@
-# `@kirkchinese/dsh-citeciter`
+# CiteCiter
 
-对 DSH 回复里的某一句追到底，不打断主 Agent，也不改变来源 Session。CiteCiter 为交互式 DSH 提供可核查、与来源精确绑定、只读的旁路调查。
+[English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-![选中 DSH 回答后在 CiteCiter 私有 Topic 中继续调查](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
+CiteCiter 为 DeepSeek Harness 提供带来源引用的独立工作区。可从主对话、工具结果和文档建立 Topic，处理文字、编程、图像和学习任务。新 Topic 使用 DSH 原生会话、权限、模型、附件与消息队列，来源对话继续独立工作。
 
-*划选、右键、就地调查；主 Agent 继续工作。*
+![Citer 原生工作区与手动发送流程示意](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.0/assets/docs/native-workspace.svg)
 
-[English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
+上图为交互示意，非运行截图。选文动作只准备草稿；模型在用户发送后开始回答。
 
-## 核心能力
+## 版本与安装
 
-- **精确绑定来源。** 创建 Topic 前，CiteCiter 会把可见选区与已经提交的回答重新核对。
-- **不用等待主任务。** 一次中间模型调用提交后即可开始调查，外层 Agent 轮次可以继续运行；思考内容和跨越“思考+回答”的选区也可以使用。
-- **调查可以持续。** 私有 Topic 支持自然续问，刷新或重启后仍能重新打开。
-- **有证据、无写权限。** CiteCiter 能检查来源中已提交的事件，也能搜索和阅读项目文件，但不能改变来源 Session 或工作区。
-- **过程可检查。** 问题、回答、来源读取和项目文件核查都留在调查面板中。
-- **讲解 Topic。** 只读老师可以在讲解时通过原子工具提交构建持久的公式、图形、表格或动画黑板。
-- **并排工作流。** 面板和可用主对话能同时容纳时，主对话会自动让出空间；更紧的布局才回退为覆盖模式。
-- **Web 更新提醒。** CiteCiter 检查 npm 中的稳定版本，并提供可复制的升级命令，无需给浏览器包管理权限。
+当前版本为 **0.8.0**。兼容基线为 DSH `0.1.5-rc.1`、[DSH Desktop](https://github.com/anywhere-labs/dsh-desktop) `2.0.9`；Node.js `^22.19.0 || >=24.0.0`。本轮 Windows 验收使用 Node 24.19.0。DSH 的 next、alpha 和 TUI 属于其他目标。
 
-## 使用
+| 版本 | 状态 | 主要差异 |
+| --- | --- | --- |
+| 0.8.0 | 当前版本 | 原生会话、手动草稿、DSH 权限、原生附件与队列、AI 学习计划 |
+| 0.7.0-beta.3 | 前一开发候选版 | 私有只读 Topic、选文轮盘、手动五阶段学习 |
+| 0.6.0 | 已发布 | DSH 0.1.2-rc.1 / Desktop 2.0.5 基线 |
 
-1. 在一次已经提交的助手模型调用中选择回答或思考内容；思考正文未展开时，可以从折叠行开始选择，该行代表该次完整模型调用。外层 Agent 轮次可以仍在运行。
-2. 右键选区，输入第一个问题，然后点击“开始提问”或“开始讲解”。
-3. CiteCiter 在调查面板中创建一个新 Topic。
-4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
-5. 独立调整模型、思考强度、标题、归档状态和面板宽度，不改变来源 Session。
+更新主机 CLI，然后安装已发布包：
 
-## 安装 v0.5.0
+```powershell
+npm install -g @deepseek-ai/dsh@latest
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.0
+dsh web
+```
 
-CiteCiter 0.5.0 需要 Node.js `^22.19.0 || >=24.0.0` 与 DSH `>=0.1.1-rc.1 <0.1.1-rc.3`。
+此命令安装 0.8.0。旧宿主 DSH 0.1.2-rc.1 / Desktop 2.0.5 应继续使用 @kirkchinese/dsh-citeciter@0.6.0。如 npm 提示本地原生依赖的安装脚本被阻止，按 npm 输出对明确列出的依赖放行后重装。不要通过全局关闭脚本限制解决。
 
-DSH Web 使用：
+本地构建并安装此分支：
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
-dsh plugin --profile web list --depth 0
+```powershell
+pnpm install --frozen-lockfile
+pnpm typecheck
+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.8.0.tgz
 ```
 
-请确认列表显示 `@kirkchinese/dsh-citeciter@0.5.0`，然后重启 DSH Web 并刷新页面。
+Desktop 使用自己的内置 DSH。更新 Desktop 应用后，在其管理终端执行 `dsh plugin add <安装包绝对路径>`；全局 CLI 更新不会更新 Desktop 内置运行时。安装后重启相应宿主。同一 DSH home 不要同时运行 Web 和 Desktop 写入进程。
+
+## 草稿与引用
+
+1. 在主对话选中文字，按住右键打开八槽轮盘，移向动作后松开。也可从工具结果、文档阅读器或原生文件预览创建 Topic。
+2. Citer 打开独立草稿。来源对话地址、来源文档地址及选中文段显示为附件。文档附件显示文件名，展开查看原始路径和快照地址。点击 × 移除；附件菜单可重新添加来源或选文。
+3. 检查问题、引用、权限和模型，点击发送或按 Enter。Shift + Enter 换行；输入法组词期间 Enter 不发送。
+
+创建 Topic、选择轮盘动作、切换模型、引用板书均不调用模型。需要补充问题的轮盘动作先打开输入框和模型选择；无需补充的动作填入预设问题，仍需手动发送。模式提示词和发送时的引用内容写入当前 Topic 的原生日志。
+
+未发送的来源附件被删除后，来源读取工具会拒绝读取该来源；新 Topic 不隐式复制来源历史。已经发送的附件属于历史消息，删除后续草稿中的副本不会撤回历史上下文。草稿在关闭/重开学习栏、切换 Topic 和窗口失焦时保留；刷新或退出客户端不保留未发送草稿和本地附件。
+
+## 权限、输入与队列
+
+新 Topic 默认 **只读**，即使来源会话具有完全权限。输入框的权限菜单使用 DSH 的只读、工作区内修改、完全权限模式。只有用户主动选择模式或更改新 Topic 默认值后，才允许相应修改。DSH 审批、沙箱和工具限制继续生效；插件不绕过权限服务。
+
+输入框从左到右为附件、权限模式、模型与思考强度、发送。模型菜单先选模型，再选该模型支持的思考强度。图片和普通文件通过 DSH 原生附件服务发送，文件显示上传状态，失败可重试。可从附件菜单选择文件，在输入框粘贴图片，或拖入 Citer 面板。拖放提示显示接收的 Topic，松开只向该 Topic 添加附件；没有可用 Topic 时不接收。主对话不会收到拖入 Citer 的副本。混合粘贴时同时保留图片与文字。已发送文件显示下载图标与文件名，点击保存原附件；用户消息不显示角色标签。宿主拒收时显示原因并保留草稿；宿主已接收的消息不会因后续状态读取失败而重新留在输入框。
+
+回答运行时，Enter 和发送按钮跟随 DSH 设置中的“繁忙时的发送行为”；Ctrl + Enter 临时使用另一种方式。排队在当前轮结束后处理，插话由 DSH 在当前轮的下一步接收。输入区的切换按钮只覆盖当前 Topic，不改写宿主默认值。队列显示待处理内容，可移除或转为插话。停止结束当前回答并保留已生成内容；待处理队列继续遵循 DSH 规则。
 
-CiteCiter 0.5.0 只提供 Web 安装路径。
-从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。
-仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
+新 Topic 可使用标准编程工具，操作范围由 DSH 权限决定。旧版记录迁入来源目录后仍保留原有对话和权限。迁移会逐条核验日志；无法核验的记录保留原存储并报告，不自动扩大权限。
 
-## 上下文模式
+DSH 工具审批、补充问题和计划确认显示在对应 Topic 中，决定交回宿主原生交互处理。审批卡保留工具名称、理由及关联参数供查看。
 
-Observer 是默认模式。它创建独立 Topic，并按需读取已经提交的来源证据；来源轮次仍在运行时也可以使用。
+模型返回的思考内容显示为可展开的“思考”行；生成思考而尚无正文时显示“思考中”。折叠状态保留一行预览，展开后显示完整 Markdown。未返回思考内容的模型不显示空行。
 
-Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
+## 学习、板书与图片
 
-## 讲解黑板
+“学习路线”默认关闭。开启后，用户发送问题时要求模型通过 DSH `todo_write` 自行选择、排列和更新学习计划。可用方式包括底层逻辑、定性分析、定量板书、概念关联和总结卡片；模型按内容取舍，无需逐个点击阶段。
 
-讲解 Topic 使用标准 Agent loop 和 scoped `blackboard_apply` 工具。黑板批次只在配对工具结果成功后显示；失败或中断批次保留此前画面。刷新和重启从私有 Topic Session 投影最终黑板，不存储第二份可变副本。
+小黑板统一显示在主区“小黑板”标签。支持文本、Markdown、公式、表格、SVG、图片和隔离 HTML。板书引用进入草稿附件，公式渲染为数学内容，不显示原始对象字段。学习卡在 Citer 的“学习卡”视图查看、导出和修订。
 
-## Web 更新提醒
+`blackboard_view` 把浏览器真实渲染的 PNG 返回给支持视觉输入的模型。模型可检查遮挡、标签、箭头和布局后继续修改板书。截图仅包含板书，不包含主对话或窗口布局；标签关闭或窄屏隐藏板书时，使用相同组件按 1000×680 离屏渲染。需保持 Citer 打开。SVG 保留原始颜色，Markdown 代码使用适合深色板书的背景。沙箱 HTML iframe 暂不支持截图，需改用 SVG 才能进行此视觉检查。
 
-Web 客户端在不阻塞启动的情况下检查 npm `latest` 稳定版本。发现新版本后，右上角持久卡片提供 `更新`、`下次一定` 和 `不再提示`：第一个操作复制标准 Web Profile 安装命令，第二个操作在当前标签页会话内隐藏该版本，第三个操作关闭后续检查，直到在 CiteCiter 设置页重新开启。CiteCiter 不会执行安装命令；请在终端执行并重启 DSH Web。
+如果宿主已安装并启用 [dsh-codex-connect](https://github.com/franksong2702/dsh-codex-connect) 的图片工具，新 Topic 可直接使用 `codex_connect_image_generate` 和 `view_image`；Citer 不要求该插件，也不代替其账户配置。本轮已验证连接插件 `0.1.0-alpha.4.34` 生成并查看真实图片。
 
-首次包含检查器的版本仍需手动升级一次，因为已经安装的旧构建无法运行尚未包含的代码。使用自定义 Web Profile 时需替换复制命令中的 `web`。安装前请核对新版对 DSH 的要求；提醒只比较包版本，不声明宿主兼容性。此功能不包含 Desktop 更新。
+请求总结卡片时，模型先核对定义、条件、推导、数值及前后矛盾，再保存完整卡片组；无法核实的内容应标明或省略。自查不能保证知识正确，验收中已发现并纠正模型错误，见[验收记录](../../docs/validation/2026-09-12-native-real-model.md)。主动回忆默认关闭，可在卡片中开启；不提供间隔复习、提醒或打卡。
+
+## Topic 与布局
+
+点击列表图标浏览、搜索并切换当前来源的 Topic；＋建立空 Topic。双击标题或按 F2 重命名，Enter/失焦保存，Esc 取消。归档用于隐藏并保留记录，可从归档列表恢复。永久删除要求输入完整 Session ID，只删除 Citer 自己维护的 Topic 目录；删除前停止并释放该 Topic，拒绝符号链接及越界路径。主 Session 不删除。
+
+宽窗口并排显示来源和 Citer，可拖动分隔线调整比例。拖动标题栏离开侧边后变为悬浮窗；拖回窗口右缘释放后停靠。空间不足时，Citer 占据主内容区并显示左上角返回键；返回后释放主对话。窄屏不把学习栏放到下方。关闭面板后恢复宿主空间；原生详情面板和 Desktop 标题栏保留。
+
+菜单和面板使用半透明背景、背景模糊与短动效，支持宿主主题和系统减少动态效果设置。布局适配集中在独立模块中，未知宿主结构不会强制覆盖主界面。
+
+## 会话存储与迁移
+
+Citer 的 Topic 只出现在 Citer 列表。DSH 的会话磁盘索引不递归扫描 Topic 子目录；插件独立维护实时成员和导航，原生发送服务按身份访问当前 Topic。
+
+```text
+.dsh/sessions/<工作区>/<主Session>/
+├── session.v3.jsonl[.zstd]       主会话，由 DSH 管理
+└── citeciter/
+    ├── owner.json              来源与目录归属
+    ├── <Topic编号>/
+    │   ├── topic.json          标题、归档状态、模型和来源
+    │   └── sessions/<工作区>/<CiterSession>/session.v3.jsonl
+    └── migration-backups/      已核验旧副本的备份
+```
 
-## Host 开发接口
+新建、归档、恢复和删除均由 Citer 管理。归档保留全文；删除不影响其他 Topic、主 Session 或迁移备份。迁移使用 DSH 公开持久化接口读取和写入，核验头部和全部事件后才切换索引；旧副本保留，清除主列表重复入口时需明确确认移动范围。
 
-0.5.0 提供 Host 侧 v1 服务 `ctx.citeciterRuntime`（`create`、`ask`、`get`、`list`、`delete`）和 `citeciter/topic-created`、`citeciter/topic-updated`、`citeciter/topic-deleted` 事件。浏览器入口注册、preset 和独立客户端 face 仍在 M4/M5 计划内，因此前端扩展接口尚未稳定。
+## 文档与原生预览
 
-## 支持范围
+Citer 打开时，从右上角“…” → “文档阅读”进入阅读器；关闭 Citer 后保留独立读书入口，避免悬浮按钮遮挡输入区。
 
-| 宿主 | CiteCiter 版本 | 说明 |
-|---|---|---|
-| DSH Web `0.1.1-rc.1` 与 `0.1.1-rc.2` | `0.5.0` | 全新 profile Linux 包、组装浏览器冒烟与真实 DeepSeek 提供方验收通过 |
-| [DSH Desktop 2.0.2](https://github.com/anywhere-labs/deepseek-harness-desktop)（内置 DSH `0.1.1-rc.2`） | 后续目标 | 正式 Desktop 安装包仍未验收 |
-| [dataelement DSH Desktop](https://github.com/dataelement/dsh-desktop) 源码开发壳（内置 DSH `0.1.1-rc.1`） | 仅 `0.4.0` | 历史上的 Linux 源码壳记录 |
-| DSH Web `0.1.0-rc.7` | `0.3.2` | 旧版稳定线 |
-| DSH TUI | — | 暂不支持 |
+点击 📖 导入 `.txt`、`.md`、`.markdown`。阅读器保存全文，每页最多 500 KiB UTF-8 文本，导入最多 2,000,000 字符。翻页清除旧选区、保留问题；选文并准备草稿后自动收起阅读器。文档地址和选文分别作为待发送附件，可独立删除。
 
-动图只是流程演示，不代表 Desktop 安装包验收结果。
+安装了可选 documentPreviews 服务时，在原生文件预览中选择“CiteCiter 学习”。宿主读取文件，Citer 提供可选取的源文本、分页与引用；创建 Topic 时保存完整快照，文件之后的变化不会改写该快照。单个快照最多 8 MiB / 2,000,000 字符，必须携带来源 Session 地址。
 
-## 已知限制
+该服务的公开类型基线为解析后的子包 `0.1.5-rc.2`；仅查看 DSH 顶层版本不足以判断能力。缺少服务时，对话轮盘与独立阅读器仍可用。学习查看方式不提供 PDF 文本层、Word 解析或 OCR。
 
-- 选区中必须至少包含一个已经提交的助手模型调用；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。已提交模型调用的思考折叠行可以代表该次完整调用。
-- 渲染器生成的 KaTeX 排版和脚注编号没有稳定原文坐标，不能直接引用。
-- Exact Fork 不能从仍在运行的来源轮次开始。
-- 来源文件访问依赖当前 DSH 文件系统服务，并始终保持只读。
-- Read Frog 翻译选区只是 DSH rc.1/rc.2 的兼容补丁，只有完整私有标记都在时才会启用。
-- DSH 还没有公开的右侧 dock 扩展点。能并排显示时，CiteCiter 会临时调整布局；换到新的 DSH 版本后需要重新确认这一块。
-- Topic 由 Host 持久保存。Desktop 重启到不同 loopback 端口时，浏览器 localStorage 会因 origin 改变而失去精确指针，CiteCiter 将回退到最近更新的 Topic；需要精确恢复“上次查看”时应配置固定 Desktop 端口。
-- DSH rc.2 没有 Session 删除 API，因此 Topic 永久删除是对 CiteCiter 固定私有 JSONL 根目录执行的所有者维护。一个 DSH home 只能由一个活动 CiteCiter 进程占用，不支持多个活动进程共享。
-- CiteCiter 0.5.0 只提供 Web 安装路径；Desktop 的正式安装包还没跟上。
-- 当前没有 TUI 交互适配器。
-- DSH 仍处于预发布阶段，后续 API 版本可能要求同步更新 CiteCiter。
+## 轮盘设置
 
-## 交流与反馈
+在“设置 → CiteCiter”选择触发键、默认模型和八个槽位。默认槽位为自由提问、解释这段、找错误、翻译、定量板书、总结卡片、两个空槽；每槽可设置提示词、是否先补充问题、内容方式及默认位置。槽位更改需点击保存。
 
-欢迎加入 DSH-Citeciter QQ 群（群号 `1108040435`），交流使用方式、功能想法和兼容性问题。
+右键短按保留可点击轮盘，Shift + 右键使用原生菜单；可用方向键、数字 1–8 和 Enter 选择。中心、空槽、轮盘外、Esc、来源切换或轮盘失焦取消动作。补充问题输入框在应用失焦时保留，主动关闭或切换来源才取消。
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="360" alt="DSH-Citeciter QQ 群 1108040435 二维码">
-</p>
+## 开发与验收
 
-## 参与贡献
+[开发规范](../../CONTRIBUTING.zh.md) · [0.8 版本说明](../../docs/releases/v0.8.0.md) · [真实模型验收](../../docs/validation/2026-09-12-native-real-model.md)
 
-欢迎提交 Issue 和 Pull Request。提交代码前请阅读[贡献文档](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.zh.md)。
+Host 和 Client 分别编译。原生会话适配、来源读取、索引存储、附件、发送队列、板书截图、学习计划和 UI 控件独立实现；不修改 DSH Agent Loop。完整宿主输入组件尚无跨会话嵌入接口，Citer 通过公开 ConversationController / SessionFace 复用行为，不能自动继承所有第三方输入区扩展。
 
-## 许可证
+当前分支已移除人工模型提供者、测试目录与临时验收脚本，保留 Git 历史。CI 进行锁文件、类型、构建和打包检查。功能验收使用真实模型、真实来源分支及实际 UI，覆盖情况与未完成项以验收记录为准。
 
-MIT © CiteCiter contributors
+MIT License.