@kirkchinese/dsh-citeciter 0.5.0 → 0.6.0

package/README.md

@@ -1,107 +1,99 @@
-# `@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.
+**A learning and investigation companion for DeepSeek Harness Web and Desktop.**
 
-![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)
+Select a committed response and explore it in a private Topic while the main task continues. Ask follow-ups, change models, or let the presenter explain with formulas, diagrams, tables and animations.
 
-*Select, right-click, and investigate beside the source while the main Agent keeps working.*
+[简体中文](README.zh.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
 
-[简体中文](README.zh.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [Issues](https://github.com/kirkchinese/CiteCiter/issues)
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/hero/citeciter-hero.png" width="100%" alt="Explore selected AI output in private CiteCiter Topics"></p>
 
-## Highlights
+## Install and compatibility
 
-- **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.
+CiteCiter **0.6.0** targets DSH `0.1.2-rc.1` and [DSH Desktop 2.0.5](https://github.com/anywhere-labs/dsh-desktop/releases/tag/v2.0.5). Node.js must satisfy `^22.19.0 || >=24.0.0`; Windows validation uses Node 24.19.0. DSH alpha and Desktop master are separate targets.
 
-## Use
+| Environment | Installation target | Status |
+| --- | --- | --- |
+| DSH Web 0.1.2-rc.1 | `web` profile | Windows runtime and UI verified |
+| DSH Desktop 2.0.5 | Current Desktop profile, default `desktop` | Targeted; see release notes for mode-specific checks |
+| DSH 0.1.1-rc.1 / rc.2 | Older environment | Keep CiteCiter 0.5.0 |
+| DSH alpha, TUI | — | Unsupported |
+| Linux / macOS | Same package | Not tested in this migration |
 
-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.
+Install or upgrade the Web plugin:
 
-## Install v0.5.0
+```powershell
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.6.0
+dsh plugin --profile web list --depth 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`.
+Confirm version 0.6.0, restart the owning host and refresh the page. Alternatively, download the `.tgz` from the [GitHub Release](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.6.0) and replace the package name with the tarball's absolute path. See Contributing for a local workspace installation.
 
-For DSH Web:
+For Desktop, confirm its selected profile and data directory, then install using the **same DSH_HOME**:
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
-dsh plugin --profile web list --depth 0
+```powershell
+dsh plugin --profile desktop add @kirkchinese/dsh-citeciter@0.6.0
+dsh plugin --profile desktop list --depth 0
 ```
 
-Confirm that the list shows `@kirkchinese/dsh-citeciter@0.5.0`, then restart DSH Web and refresh the page.
+Replace `desktop` if a custom profile is selected; set `$env:DSH_HOME` in PowerShell if it uses a custom home. Restart Desktop. Updating the global npm CLI does not replace Desktop's embedded runtime.
 
-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.
+If npm 12 blocks the native dependency scripts listed by this DSH release, allow them for this installation:
 
-## Context modes
-
-Observer is the default. It creates an independent Topic and reads committed source evidence on demand, including while the source turn is still running.
+```powershell
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1 --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty,@google/genai,protobufjs
+```
 
-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.
+This addresses native installation. An old plugin importing the removed `effectiveSandboxMode` export requires a plugin upgrade; reinstalling the host alone does not fix it.
 
-## Presenter board
+## Use
 
-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.
+1. Select committed assistant answer or reasoning text, right-click, enter a question, and choose “开始提问” or “开始讲解”.
+2. Continue in the learning panel, change model/reasoning effort, and manage Topic titles, archives and deletion.
+3. Use `+ 新 Topic` for a free question or presentation. A new source session needs its first message before the Topic can reuse its model route.
+4. Presenter boards appear in the main workspace's “小黑板” tab. Board citations append to the current question draft.
+5. Tool results, terminal output, diffs and the text/Markdown Reader also provide Topic entry points.
 
-## Web update notices
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif" width="100%" alt="Select AI output and continue in a CiteCiter Topic"></p>
 
-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.
+This older recording demonstrates the citation workflow; host layout and controls differ in 0.6.
 
-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.
+## Keep the source conversation visible
 
-## Host developer API
+- Wide windows allocate a separate learning column and retain native details.
+- Saved panel proportions range from 28% to 55%. Actual width is capped to leave at least 480 CSS pixels for conversation, then returns to the preference when space permits.
+- Narrow or zoomed windows place the learning panel in a bottom row, with the conversation visible above it.
+- Closing restores host layout. Unrecognized frames show a compact compatibility message.
 
-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.
+Content uses public DSH slots, conversation projections and snapshot hooks. This release has no public right-dock sizing service, so a small maintained host adapter allocates space. Revalidate it after host upgrades.
 
-## Supported hosts
+## Topics and data
 
-| 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 |
+Observer discussions use private logs and read source events or project files as needed. Exact Fork inherits context from a completed source turn. File tools remain read-only and Topics never append to the source Session. Uncommitted streaming text has no stable citation position; Exact Fork requires a completed source turn.
 
-The demo is only a workflow illustration. It is not packaged-Desktop acceptance evidence.
+Atomic `blackboard_apply` commits support formulas, Markdown, tables, safe SVG, isolated HTML animations and embedded images. Topics support follow-ups, model changes, archive/restore and permanent deletion with a Session ID confirmation.
 
-## Limitations
+Indexes live under `$DSH_HOME/citeciter/workspaces/`; logs under `$DSH_HOME/citeciter/sessions/`. Without the variable the home is usually `.dsh` in the user directory. Back up the complete home before upgrading. Version 0.6 uses the new runtime API without bulk-rewriting old logs. DSH's version-0 physical JSONL still uses `seedLength`; preserve and diagnose unknown events rather than deleting fields.
 
-- 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.
+Only one active CiteCiter host may own a home. Concurrent Web and Desktop instances need different homes. Update notices copy a command without installing anything; Desktop commands target the current profile.
 
-## Community
+## Development
 
-Questions, workflow ideas, and compatibility reports are welcome in the DSH-Citeciter QQ group (`1108040435`).
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm test:snapshot
+```
 
-<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>
+The real application snapshot uses a temporary profile and keyless model for Observer, Exact Fork, source reads, boards and source-log isolation. Host `ctx.citeciterRuntime` exposes `create`, `ask`, `get`, `list`, `delete` and Topic change events. Public frontend entry registration and preset extension APIs remain unfinished. See [Contributing](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.md) and the [0.6.0 release note](https://github.com/kirkchinese/CiteCiter/blob/main/docs/releases/v0.6.0.md).
 
-## Contributing
+## Community and license
 
-Issues and pull requests are welcome. Before submitting code, read the [contribution guide](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.md).
+DSH-Citeciter QQ group: `1108040435`.
 
-## License
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="280" alt="DSH-Citeciter QQ group QR code"></p>
 
-MIT © CiteCiter contributors
+[MIT License](https://github.com/kirkchinese/CiteCiter/blob/main/LICENSE)

package/README.zh.md

@@ -1,107 +1,99 @@
-# `@kirkchinese/dsh-citeciter`
+# CiteCiter
 
-对 DSH 回复里的某一句追到底，不打断主 Agent，也不改变来源 Session。CiteCiter 为交互式 DSH 提供可核查、与来源精确绑定、只读的旁路调查。
+**为 DeepSeek Harness Web 与 Desktop 打造的 AI 输出学习、检查与纠偏插件。**
 
-![选中 DSH 回答后在 CiteCiter 私有 Topic 中继续调查](https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif)
+选中一段已提交的回答，在旁边创建独立 Topic，反复追问、切换模型，或让 AI 用公式、图形、表格和动画逐步讲解。主任务继续运行，学习记录保存在独立日志中。
 
-*划选、右键、就地调查；主 Agent 继续工作。*
+[English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
-[English](README.md) · [GitHub](https://github.com/kirkchinese/CiteCiter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/hero/citeciter-hero.png" width="100%" alt="CiteCiter 将选中的 AI 回答展开为独立 Topic"></p>
 
-## 核心能力
+## 0.6.0 安装与兼容
 
-- **精确绑定来源。** 创建 Topic 前，CiteCiter 会把可见选区与已经提交的回答重新核对。
-- **不用等待主任务。** 一次中间模型调用提交后即可开始调查，外层 Agent 轮次可以继续运行；思考内容和跨越“思考+回答”的选区也可以使用。
-- **调查可以持续。** 私有 Topic 支持自然续问，刷新或重启后仍能重新打开。
-- **有证据、无写权限。** CiteCiter 能检查来源中已提交的事件，也能搜索和阅读项目文件，但不能改变来源 Session 或工作区。
-- **过程可检查。** 问题、回答、来源读取和项目文件核查都留在调查面板中。
-- **讲解 Topic。** 只读老师可以在讲解时通过原子工具提交构建持久的公式、图形、表格或动画黑板。
-- **并排工作流。** 面板和可用主对话能同时容纳时，主对话会自动让出空间；更紧的布局才回退为覆盖模式。
-- **Web 更新提醒。** CiteCiter 检查 npm 中的稳定版本，并提供可复制的升级命令，无需给浏览器包管理权限。
+CiteCiter **0.6.0** 的安装基线是 DSH `0.1.2-rc.1`，Desktop 对应 [DSH Desktop 2.0.5](https://github.com/anywhere-labs/dsh-desktop/releases/tag/v2.0.5)。Node.js 要求 `^22.19.0 || >=24.0.0`；Windows 实测使用 Node 24.19.0。DSH alpha 与 Desktop master 不在此兼容承诺中。
 
-## 使用
+| 环境 | 安装目标 | 状态 |
+| --- | --- | --- |
+| DSH Web 0.1.2-rc.1 | `web` profile | Windows 实际运行与 UI 验证 |
+| DSH Desktop 2.0.5 | Desktop 当前 profile，默认 `desktop` | 适配目标，分模式验证见 release 文档 |
+| DSH 0.1.1-rc.1 / rc.2 | 旧环境 | 保留 CiteCiter 0.5.0 |
+| DSH alpha、TUI | — | 未支持 |
+| Linux / macOS | 相同包 | 本轮未运行平台验证 |
 
-1. 在一次已经提交的助手模型调用中选择回答或思考内容；思考正文未展开时，可以从折叠行开始选择，该行代表该次完整模型调用。外层 Agent 轮次可以仍在运行。
-2. 右键选区，输入第一个问题，然后点击“开始提问”或“开始讲解”。
-3. CiteCiter 在调查面板中创建一个新 Topic。
-4. 在 Topic 中继续追问，或从 CiteCiter 的 Topic 栏恢复旧讨论。
-5. 独立调整模型、思考强度、标题、归档状态和面板宽度，不改变来源 Session。
+安装或升级 Web 插件：
 
-## 安装 v0.5.0
+```powershell
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.6.0
+dsh plugin --profile web list --depth 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.6.0 后重启相应宿主并刷新页面。也可从 [GitHub Release](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.6.0) 下载 `.tgz`，将安装命令中的包名替换为 tarball 的绝对路径。源码开发使用贡献指南中的本地工作区安装流程。
 
-DSH Web 使用：
+Desktop 中先确认当前 profile 名称和数据目录，使用**相同的 DSH_HOME**安装：
 
-```sh
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.5.0
-dsh plugin --profile web list --depth 0
+```powershell
+dsh plugin --profile desktop add @kirkchinese/dsh-citeciter@0.6.0
+dsh plugin --profile desktop list --depth 0
 ```
 
-请确认列表显示 `@kirkchinese/dsh-citeciter@0.5.0`，然后重启 DSH Web 并刷新页面。
+若 Desktop 选择了自定义 profile，把 `desktop` 换成该名称；若使用自定义 home，先在当前 PowerShell 中设置 `$env:DSH_HOME`。重启 Desktop。全局 npm 更新只影响 CLI，Desktop 内置的 DSH 随桌面应用更新。
 
-CiteCiter 0.5.0 只提供 Web 安装路径。
-从 v0.3 升级不会迁移或重写现有 Topic、设置或来源 Session。
-仍在 DSH `0.1.0-rc.7` 上运行的用户应继续使用 CiteCiter 0.3.2。
+npm 12 若提示安装脚本被拦截，按此次依赖列表一次性放行并重装；不必改变全局永久策略：
 
-## 上下文模式
-
-Observer 是默认模式。它创建独立 Topic，并按需读取已经提交的来源证据；来源轮次仍在运行时也可以使用。
+```powershell
+npm install -g @deepseek-ai/dsh@0.1.2-rc.1 --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty,@google/genai,protobufjs
+```
 
-Exact Fork 是面向已结束来源轮次的高级模式。`exact-when-available` 在存在稳定边界时使用 Exact Fork，否则回退到 Observer。
+这解决原生依赖安装问题；旧插件引用已移除的 `effectiveSandboxMode` 则需要升级插件，单独重装宿主不会修复。
 
-## 讲解黑板
+## 开始使用
 
-讲解 Topic 使用标准 Agent loop 和 scoped `blackboard_apply` 工具。黑板批次只在配对工具结果成功后显示；失败或中断批次保留此前画面。刷新和重启从私有 Topic Session 投影最终黑板，不存储第二份可变副本。
+1. 选中已提交的助手回答或思考内容，右键输入问题，选择“开始提问”或“开始讲解”。
+2. 在右侧学习栏继续追问、切换模型和思考强度，或管理 Topic 标题、归档和删除。
+3. 使用 `+ 新 Topic` 创建自由问答或讲解。新的主会话需先发送消息，让 Topic 取得当前模型配置。
+4. 讲解内容位于主工作区“小黑板”标签；“引用到提问”会追加到现有草稿。
+5. 也可从工具结果、终端结果、差异片段及文本/Markdown Reader 创建 Topic。
 
-## Web 更新提醒
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/demo/citeciter-0.4.0.gif" width="100%" alt="选中 AI 回答并在 CiteCiter 中继续追问"></p>
 
-Web 客户端在不阻塞启动的情况下检查 npm `latest` 稳定版本。发现新版本后，右上角持久卡片提供 `更新`、`下次一定` 和 `不再提示`：第一个操作复制标准 Web Profile 安装命令，第二个操作在当前标签页会话内隐藏该版本，第三个操作关闭后续检查，直到在 CiteCiter 设置页重新开启。CiteCiter 不会执行安装命令；请在终端执行并重启 DSH Web。
+上图演示引用流程，录制于旧版；0.6 的宿主布局和控件可能不同。
 
-首次包含检查器的版本仍需手动升级一次，因为已经安装的旧构建无法运行尚未包含的代码。使用自定义 Web Profile 时需替换复制命令中的 `web`。安装前请核对新版对 DSH 的要求；提醒只比较包版本，不声明宿主兼容性。此功能不包含 Desktop 更新。
+## 并排学习，不遮挡主对话
 
-## Host 开发接口
+- 宽屏为学习栏分配独立列，保留主对话和原生详情栏。
+- 保存的面板比例为 28%–55%。空间不足时限制实际宽度，为主对话保留至少 480 CSS 像素；扩大窗口后恢复偏好比例。
+- 窄窗口或缩放后无法容纳两列时，学习栏移至下方，主对话仍在上方可见。
+- 关闭学习栏后恢复宿主布局。无法识别的宿主仅显示兼容提示。
 
-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 计划内，因此前端扩展接口尚未稳定。
+内容通过 DSH 公开 slots、会话投影和快照 hooks 接入。当前宿主没有公开的右侧 dock 尺寸接口，因此尺寸分配使用集中维护的宿主布局适配器，升级宿主后需重新验收。
 
-## 支持范围
+## Topic 与数据
 
-| 宿主 | 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 | — | 暂不支持 |
+Observer 在私有日志中讨论，按需读取来源事件和项目文件；Exact Fork 继承已结束来源轮次的上下文。文件工具保持只读，Topic 不向主 Session 追加事件。未提交的流式文字没有稳定引用坐标；Exact Fork 需等待来源轮次结束。
 
-动图只是流程演示，不代表 Desktop 安装包验收结果。
+Presenter 的 `blackboard_apply` 原子提交支持公式、Markdown、表格、安全 SVG、隔离 HTML 动画和内嵌图片。Topic 可继续追问、切换模型、归档、恢复及带 Session ID 确认的永久删除。
 
-## 已知限制
+Topic 索引在 `$DSH_HOME/citeciter/workspaces/`，日志在 `$DSH_HOME/citeciter/sessions/`；未设置变量时通常为用户目录下的 `.dsh`。升级前备份整个 home。0.6 使用新版会话 API；没有批量重写旧日志。DSH 版本 0 JSONL 的物理 `seedLength` 仍由宿主读取，遇到未知事件应保留原件并诊断，不能删字段绕过。
 
-- 选区中必须至少包含一个已经提交的助手模型调用；纯用户消息、纯工具行和仍在流式输出的片段不能作为引用锚点。已提交模型调用的思考折叠行可以代表该次完整调用。
-- 渲染器生成的 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。
+一个 home 只能由一个活动 CiteCiter 宿主使用。Web 与 Desktop 同时运行时使用不同 home；不要让两者并发写入同一私有存储。更新提醒只复制命令，不自动安装；Desktop 命令使用当前 profile。
 
-## 交流与反馈
+## 开发
 
-欢迎加入 DSH-Citeciter QQ 群（群号 `1108040435`），交流使用方式、功能想法和兼容性问题。
+```sh
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm test:snapshot
+```
 
-<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>
+实际应用快照使用临时 profile 与无密钥模型，覆盖 Observer、Exact Fork、来源读取、板书和来源日志不变性。Host API `ctx.citeciterRuntime` 提供 `create`、`ask`、`get`、`list`、`delete` 及 Topic 变化事件。前端入口注册 API 和 preset 扩展仍未稳定。开发流程见 [贡献指南](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.zh.md)，公开变更见 [0.6.0 发布说明](https://github.com/kirkchinese/CiteCiter/blob/main/docs/releases/v0.6.0.md)。
 
-## 参与贡献
+## 社区与许可证
 
-欢迎提交 Issue 和 Pull Request。提交代码前请阅读[贡献文档](https://github.com/kirkchinese/CiteCiter/blob/main/CONTRIBUTING.zh.md)。
+DSH-Citeciter QQ 群：`1108040435`。
 
-## 许可证
+<p align="center"><img src="https://raw.githubusercontent.com/kirkchinese/CiteCiter/main/assets/community/qq-group.jpg" width="280" alt="DSH-Citeciter QQ 群二维码"></p>
 
-MIT © CiteCiter contributors
+[MIT License](https://github.com/kirkchinese/CiteCiter/blob/main/LICENSE)