@kirkchinese/dsh-citeciter 0.8.0 → 0.8.2

package/README.md

@@ -2,19 +2,23 @@
 
 [简体中文](README.zh.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [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. Upgrade to [0.8.2](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.8.2).
+
 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.
 
-![Native Citer workspace and manual submission diagram](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.0/assets/docs/native-workspace.svg)
+![Native Citer workspace and manual submission diagram](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.1/assets/docs/native-workspace.svg)
 
 This is an interaction diagram, not a screenshot. Selection actions prepare drafts; model work begins only after the user sends.
 
 ## Version and installation
 
-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.
+Current version: **0.8.2**. 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.
 
 | Version | Status | Main differences |
 | --- | --- | --- |
-| 0.8.0 | Current version | Native Sessions, manual drafts, DSH permissions, attachments, queue and AI learning plans |
+| 0.8.2 | Stable | 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 |
 
@@ -22,11 +26,13 @@ Update the host CLI and install the published package:
 
 ```powershell
 npm install -g @deepseek-ai/dsh@latest
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.0
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.2
 dsh web
 ```
 
-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.
+This installs 0.8.2. 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.
 
 Build and install this branch locally:
 
@@ -35,10 +41,16 @@ 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
+dsh plugin --profile web add E:/project/CiteCiter/.refs/artifacts/kirkchinese-dsh-citeciter-0.8.2.tgz
 ```
 
-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.
+Desktop bundles its own DSH. Run `dsh plugin add @kirkchinese/dsh-citeciter@0.8.2` in its managed terminal to upgrade the plugin, or pass an absolute local package path. 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.
+
+## 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. 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
 
@@ -117,7 +129,7 @@ A short right-click leaves a clickable wheel; Shift + right-click preserves the
 
 ## Development and acceptance
 
-[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)
+[Contributing](../../CONTRIBUTING.md) · [0.8.2 fix notes](../../docs/releases/v0.8.2.md) · [Real-model acceptance](../../docs/validation/2026-09-14-source-read-guidance.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.
 

package/README.zh.md

@@ -2,19 +2,23 @@
 
 [English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
 
+> **0.8.0 已弃用。** Linux 通过符号链接启动 DSH 时，可能无法创建或恢复 Topic，报找不到 `@deepseek-ai/dsh-agent-loop`。请升级到 [0.8.2](https://github.com/kirkchinese/CiteCiter/releases/tag/v0.8.2)。
+
 CiteCiter 为 DeepSeek Harness 提供带来源引用的独立工作区。可从主对话、工具结果和文档建立 Topic，处理文字、编程、图像和学习任务。新 Topic 使用 DSH 原生会话、权限、模型、附件与消息队列，来源对话继续独立工作。
 
-![Citer 原生工作区与手动发送流程示意](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.0/assets/docs/native-workspace.svg)
+![Citer 原生工作区与手动发送流程示意](https://raw.githubusercontent.com/kirkchinese/CiteCiter/v0.8.1/assets/docs/native-workspace.svg)
 
 上图为交互示意，非运行截图。选文动作只准备草稿；模型在用户发送后开始回答。
 
 ## 版本与安装
 
-当前版本为 **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.2**。兼容基线为 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.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 基线 |
 
@@ -22,11 +26,13 @@ CiteCiter 为 DeepSeek Harness 提供带来源引用的独立工作区。可从
 
 ```powershell
 npm install -g @deepseek-ai/dsh@latest
-dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.0
+dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.8.2
 dsh web
 ```
 
-此命令安装 0.8.0。旧宿主 DSH 0.1.2-rc.1 / Desktop 2.0.5 应继续使用 @kirkchinese/dsh-citeciter@0.6.0。如 npm 提示本地原生依赖的安装脚本被阻止，按 npm 输出对明确列出的依赖放行后重装。不要通过全局关闭脚本限制解决。
+此命令安装 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 尚未实测。
 
 本地构建并安装此分支：
 
@@ -35,10 +41,16 @@ 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
+dsh plugin --profile web add E:/project/CiteCiter/.refs/artifacts/kirkchinese-dsh-citeciter-0.8.2.tgz
 ```
 
-Desktop 使用自己的内置 DSH。更新 Desktop 应用后，在其管理终端执行 `dsh plugin add <安装包绝对路径>`；全局 CLI 更新不会更新 Desktop 内置运行时。安装后重启相应宿主。同一 DSH home 不要同时运行 Web 和 Desktop 写入进程。
+Desktop 使用自己的内置 DSH。在其管理终端执行 `dsh plugin add @kirkchinese/dsh-citeciter@0.8.2` 升级插件，也可传入本地安装包绝对路径；全局 CLI 更新不会更新 Desktop 内置运行时。安装后重启相应宿主。同一 DSH home 不要同时运行 Web 和 Desktop 写入进程。
+
+## 来源读取与建议追问
+
+`read_source_session` 按字节预算分页。`sourceMaxSeq` 是本次快照的可读上界；`availableThroughSeq` 是旧版请求上界标记，不能用它判断来源结束。`hasMore` 为 true 时，以 `nextFromSeq` 作为下一次 `fromSeq`，省略 `throughSeq` 继续读取。`truncated` 只表示当前范围因字节预算停止；空页、过滤事件及超大内容占位不代表来源不存在。Observer 每次读取当前已提交事件，Exact Fork 只读取继承前缀。
+
+原生 Topic 的首答默认提供三条建议追问，可在 CiteCiter 设置中关闭。点击建议只填入草稿，手动发送后才调用模型。来源说明和建议追问由独立提示词模块提供；来源内容继续按已发送附件读取。
 
 ## 草稿与引用
 
@@ -119,7 +131,7 @@ Citer 打开时，从右上角“…” → “文档阅读”进入阅读器；
 
 ## 开发与验收
 
-[开发规范](../../CONTRIBUTING.zh.md) · [0.8 版本说明](../../docs/releases/v0.8.0.md) · [真实模型验收](../../docs/validation/2026-09-12-native-real-model.md)
+[开发规范](../../CONTRIBUTING.zh.md) · [0.8.2 修复说明](../../docs/releases/v0.8.2.md) · [真实模型验收](../../docs/validation/2026-09-14-source-read-guidance.md)
 
 Host 和 Client 分别编译。原生会话适配、来源读取、索引存储、附件、发送队列、板书截图、学习计划和 UI 控件独立实现；不修改 DSH Agent Loop。完整宿主输入组件尚无跨会话嵌入接口，Citer 通过公开 ConversationController / SessionFace 复用行为，不能自动继承所有第三方输入区扩展。
 

package/lib/client.js

@@ -5659,7 +5659,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			updatedAt: number().int().nonnegative(),
 			archivedAt: number().int().nonnegative().nullable(),
 			sourceAvailable: boolean(),
-			observedThroughSeq: number().int().nonnegative().nullable().optional()
+			/** Cursor from this Topic's last source read, never the source horizon or a permission boundary. */
+			observedThroughSeq: number().int().nonnegative().nullable().optional().describe("Last source-read scan cursor; not the source horizon or an access limit.")
 		};
 		object({
 			schemaVersion: literal(2),
@@ -5705,7 +5706,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			archived: boolean(),
 			running: boolean(),
 			sourceAvailable: boolean(),
-			observedThroughSeq: number().int().nonnegative().nullable(),
+			/** Cursor from this Topic's last source read, never the source horizon or a permission boundary. */
+			observedThroughSeq: number().int().nonnegative().nullable().describe("Last source-read scan cursor; not the source horizon or an access limit."),
 			modelConfig: modelConfigSchema
 		}).strict();
 		const messageAttachmentSchema = object({
@@ -39594,7 +39596,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 							}),
 							(0, react_jsx_runtime.jsxs)("label", {
 								className: CiteCiter_module_css_default.settingStack,
-								children: [(0, react_jsx_runtime.jsxs)("span", { children: [(0, react_jsx_runtime.jsx)("strong", { children: "自定义导师提示词" }), (0, react_jsx_runtime.jsx)("small", { children: "在内置场景规则后补充教学偏好；留空只使用内置提示词。修改对之后恢复/新建的 Topic 生效。" })] }), (0, react_jsx_runtime.jsx)("textarea", {
+								children: [(0, react_jsx_runtime.jsxs)("span", { children: [(0, react_jsx_runtime.jsx)("strong", { children: "自定义导师提示词" }), (0, react_jsx_runtime.jsx)("small", { children: "补充教学偏好；留空使用内置提示词。原生 Topic 从下次发送起生效；旧 Topic 恢复后生效。" })] }), (0, react_jsx_runtime.jsx)("textarea", {
 									className: CiteCiter_module_css_default.promptTextarea,
 									value: settings.tutorPrompt ?? "",
 									maxLength: 4e3,