# CiteCiter
[English](README.md) · [npm](https://www.npmjs.com/package/@kirkchinese/dsh-citeciter) · [更新记录](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.7/CHANGELOG.md) · [问题反馈](https://github.com/kirkchinese/CiteCiter/issues)
**AI 已经完成了任务，我还想弄明白它是怎么做的。**
CiteCiter 是 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 的插件，帮助你从 Agent 的真实工作中学习。选中对话、工具结果或文档中的一段内容，在保留来源的独立 Topic 里追问，用小黑板理解关键关系，再回到原来的工作。主对话不会被改动。
[](https://www.bilibili.com/video/BV1tqeA65EJ8/)
[在 B 站观看演示](https://www.bilibili.com/video/BV1tqeA65EJ8/)（早期版本录制，界面与当前版本略有不同）。
## 安装
CiteCiter 需要 DSH 和一个可用的模型。插件声明了一个 DSH 版本范围，同一条版本线上的后续发布不需要等 CiteCiter 更新；超出范围时 DSH 会拒绝加载，请按 DSH 版本选择对应的 CiteCiter：
| DSH 版本 | CiteCiter 版本 |
| --- | --- |
| `0.2.0-rc.2` 及以上、`0.2.2` 之前（含官方桌面版，以及 `0.2.1` 的各个 alpha、rc 和正式版） | `0.9.0-beta.7` |
| `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` |
**官方桌面版：** 在插件页安装 npm 包 `@kirkchinese/dsh-citeciter`，或在 Git 地址一栏填写 `https://github.com/kirkchinese/CiteCiter.git`，然后按提示重启。
**命令行与 Web：**
```sh
dsh plugin --profile web add @kirkchinese/dsh-citeciter@0.9.0-beta.7
```
也可以从仓库安装某个发布标签，仓库内已包含构建好的插件，安装时无需构建：
```sh
dsh plugin --profile web add "git+https://github.com/kirkchinese/CiteCiter.git#v0.9.0-beta.7"
```
安装或升级后重启 DSH 并刷新页面。不要用 `dsh plugin allow-version` 强行加载与宿主版本不匹配的插件。同一个 DSH 主目录不要同时运行两个宿主进程。
## 从一个疑问开始
例如，Agent 修改了程序，你想知道"为什么这段异步保存逻辑会影响输入？"
1. 在主对话、工具结果或文档中选中相关内容，旁边会出现 Citer 工具条。
2. 点"解释"直接得到讲解；或者点"提问"，来源和选文会作为可移除的附件放进输入框，写下自己的问题后发送。
3. 围绕这段材料继续追问；需要时让模型在小黑板上画出流程，或整理成学习卡。
4. 回到原任务，用代码、工具结果或一次小实验检查自己的理解。
新建 Topic 或选择"提问"只会准备草稿；"解释""翻译"这类预设动作在你点选时发送，也可以在设置里改成先放进输入框。解释和板书仍可能出错；它们帮助你理解和检查，不代替事实证据。
## 功能
| 你想做什么 | CiteCiter 提供什么 |
| --- | --- |
| 理解一段回答、代码或工具结果 | 带来源引用的独立 Topic，追问不会写入主对话 |
| 看懂关系与过程 | 支持 Markdown、公式、表格、SVG、图片和隔离 HTML 的小黑板；支持视觉的模型可以查看渲染后的板书并自行修正；板书还能编排动画，元素按关键帧、路径或公式运动，可以播放、暂停、拖动进度和按步骤跳转 |
| 留下可回看的理解 | 可导出、可修订的学习卡，文字与代码示例分开展示 |
| 围绕真实文件讨论 | 文件与图片附件；在右侧栏阅读导入的 Markdown / 文本文档和工作区文件，选中即可提问，引用带行号并能回到原文 |
| 从理解继续动手 | 复用 DSH 的模型、工具、审批、权限、排队和插话；新 Topic 默认只读 |
| 暂停后继续 | 草稿（文字、引用、附件）和未提交的问答自动保存，切换、刷新或重启后恢复，不会自动发送 |
## 使用说明
**工具条与动作。** 在主对话的助手回答、你自己的消息、工具结果或文档中选中文字后，旁边出现工具条：第一个动作（默认是"问 Citer"）之后是"引用"，再往后是其余前三个动作，剩下的动作和"在新 Topic 中提问"在"⋯"里。"引用"把选中的句子作为一个引用胶囊放进主对话的输入框，和 `@文件` 的样子一样，已有的文字和附件都保留；发送时主 Agent 收到这段原文和它出自谁（它的回复、你的消息或工具结果），就知道你接下来的话针对哪一句，适合和它讨论或反驳。DSH `0.2.1-rc.2` 起，已发送的消息里也显示为引用胶囊。动作默认加入当前打开的 Topic，没有或已归档时新建。在 Citer 自己的回答里选中文字也会出现工具条，动作在这个 Topic 中继续，"引用"会把选段加到这个 Topic 的输入框。"问 Citer"打开输入框让你写问题；"解释""找错误""翻译"等预设动作直接发送，不会改动输入框里已有的草稿。动作的名称、提示词和顺序都可以在设置中修改。喜欢手势的话，可以在设置中开启轮盘：选中文字后按住右键（或设定的键）移向动作，松开即执行。
**右侧栏。** Citer 是 DSH 右侧栏里的一个标签页，可以从侧栏的指引页、桌宠或工具条打开，和文件、终端、其他插件的标签并排、分屏、悬浮或全屏，关闭标签即收起。更喜欢以前那种独立面板的话，在设置 → Citer → 面板中打开"不使用 DSH 右侧栏"。界面语言跟随 DSH 的语言设置（中文或英文），默认动作的名称和提示词也随之切换，你改过的动作保持原样。Topic 在输入框下方显示自己的用量：token 数、缓存命中率和上下文占用。
**文档。** 在 Citer 的空状态点"打开文档"，或在 Topic 列表的"文档"页导入 `.md` / `.txt` 文件，文档会在右侧栏的标签页里打开：Markdown 正常排版（标题、列表、代码块、公式），文本和代码带行号，长文档边滚动边显示。选中文字就会出现同样的工具条，"问 Citer""解释""引用"都可以用。从文档提问的 Topic 在引用下方显示"文档名 · 第 N 行"，点"打开原文"回到那一段并短暂高亮。工作区里的文件用 DSH 自己的文件预览打开，在视图菜单中选"Citer 阅读"即可同样选文提问，提问时会把文件快照存入 Citer 的文档。文档列表在 Topic 列表的"文档"页，可以搜索和删除；删除只移除文档本身，相关 Topic 的对话保留。不使用 DSH 右侧栏时，文档在 Citer 面板的页签里打开。
**桌宠。** Citer 收起时，她会扒在窗口边缘探头；鼠标靠近时站起来，点一下就打开 Citer。可以把她拖到左边或右边的任意高度，位置会被记住。收起期间有回答完成，或有问题在等你回答时，她旁边会出现一个小圆点。
**输入。** 输入框依次提供附件、权限模式、模型与思考强度、发送。Enter 发送，Shift + Enter 换行，输入法组词时 Enter 不会发送。生成过程中 Enter 跟随 DSH 的排队／插话设置，Ctrl + Enter 临时使用另一种方式。可以从附件菜单选择文件、粘贴图片，或把文件拖到 Citer 面板上。
**草稿。** 草稿在后台静默保存。多个窗口编辑同一个 Topic 时，各自的修改会自动合并；同一处有冲突时，以正在输入的窗口为准。发送成功后只清除已发送的部分，发送期间新写的内容会保留。
**来源与代码库。** 每个 Topic 都知道自己属于哪个主对话，即使没有引用任何内容，Citer 也能随时读取它（只能读这个主对话）。看到的是带位置标记的对话记录：用户与助手的消息、工具调用和结果；过长的工具输出先缩短，需要时再读全文。在设置中开启"自动附上来源摘录"后，每轮开头会附上来源最近的新内容，默认关闭。"代码库变化感知"在每轮开头列出上一轮以来 git 工作区（含未提交的改动）改了哪些文件，Citer 需要时再用工具读取逐行改动；也可以在设置中改为直接附上 diff，或者关闭。这些内容都记录在 Topic 里，像 DSH 主对话一样显示为可展开的上下文行，展开即是模型收到的原文；它们不会写入你的仓库。运行环境、时间等其他上下文和 DSH 一样默认不列出，可以在 Topic 菜单中选择"显示全部上下文"查看。Topic 中的工具调用也使用 DSH 的样式：读取文件带行号，编辑显示为 diff，命令显示输出和退出码。
**学习路线与学习卡。** 学习路线默认关闭，可以在 Topic 菜单（⋯）中开启；开启后，模型会根据问题用 DSH 待办安排讲解步骤。学习卡可以随时单独请求，生成前模型会核对结论、条件和计算，但自查不能保证正确。主动回忆默认关闭，开启后学习卡先显示自测问题。
**Codex Connect。** CiteCiter 适配了社区插件 [Codex Connect](https://github.com/franksong2702/dsh-codex-connect)（`dsh-codex-connect`）。在同一个 Profile 中安装并开启它之后，Topic 可以使用它接入的 ChatGPT / Codex 模型和 GPT Image 图片工具，生成的图片直接显示在工具卡下方。图片工具需要在 Codex Connect 的设置中单独开启；它的安装、登录和支持的 DSH 版本请见该插件的说明。
## 权限与数据
新 Topic 默认**只读**，即使来源会话拥有更高权限。只有你在输入框中选择其他权限模式，或在设置里修改新 Topic 的默认权限后，Topic 才能修改工作区；DSH 的审批和沙箱规则照常生效。
Topic 只出现在 Citer 的列表里，不会出现在 DSH 的会话列表中。新 Topic 先以引用摘录或问题为标题，第一次回答时由 DSH 的标题服务生成摘要标题；双击标题、按 F2 或在 Topic 菜单中重命名，重命名后不再自动修改；归档的 Topic 在你再次发送消息后自动恢复。永久删除需要输入完整的 Session ID，只删除这个 Topic 自己的记录、草稿、附件和代码库快照。
新 Topic 使用设置中"新 Topic 的模型"，未设置时沿用来源对话输入框里当前选择的模型。如果这个模型在当前 DSH 中不可用（例如设置是在另一台机器上配置的），Topic 照常创建，引用和草稿都保留，Citer 会提示你在模型菜单中换一个可用的模型，不会自动换模型或发送。
CiteCiter 的数据保存在每个来源会话的目录中：
```text
.dsh/sessions///
├── session.v4.jsonl[.zstd] DSH 管理的主会话（Citer 不会改动）
└── citeciter/
├── owner.json 目录归属
├── /
│ ├── topic.json Topic 信息
│ ├── draft/ 未发送的文字、引用和附件
│ ├── question-drafts/ 未提交的问答
│ ├── workspace/ 代码库变化感知的快照（独立的 git 对象）
│ └── sessions/ Topic 自己的会话日志
└── deleted/ 删除记录（只含身份，不含内容）
```
0.8 之前版本创建的 Topic 会在启动时自动迁移到这个目录，原始日志保留不动。
## 已知问题
- Windows 上，只读模式下的 PowerShell 可能报语言模式错误或输出中文乱码。这是 DSH 执行器在只读沙箱中的限制，CiteCiter 不会为此放宽权限。
- 官方桌面版重启后，仍连接着旧后台的其他浏览器标签页可能白屏，刷新即可恢复；停用 CiteCiter 时同样会出现。
- 在同一个浏览器地址上先后使用不同版本的 DSH，宿主自己保存的草稿格式可能不兼容，导致主对话无法显示；不同版本请使用不同的地址或端口。
- 插件主要在 Windows 上测试；Linux 与 macOS 未经系统测试，遇到问题欢迎反馈。
## 为什么做 CiteCiter
实践通常同时产生两样东西：成果和能力。我们通过尝试、犯错、比较方案和验证，逐渐形成判断。AI 可以接手越来越多的执行，却不会自动把相应的理解交给使用者，任务完成与人的成长可能因此分离。
CiteCiter 尝试把真实的 AI 工作过程变成可引用、可追问、可检验的学习材料。从眼前的一个疑问出发，理解原理、查看证据，再带着新的认识继续工作。即使把执行交给 Agent，人仍需要提出目标、理解关键条件、判断结果是否适用，并在出现异常时接管。
## 反馈
欢迎带着"Agent 已经完成了，但我还讲不清"的任务来[反馈](https://github.com/kirkchinese/CiteCiter/issues)。请写明 DSH 和插件版本，以及卡在安装、引用追问还是理解回答。贴材料前请移除密钥和私人内容。
开发说明见 [CONTRIBUTING.zh.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.7/CONTRIBUTING.zh.md)，产品规则见 [docs/product.zh.md](https://github.com/kirkchinese/CiteCiter/blob/v0.9.0-beta.7/docs/product.zh.md)。同作者的 [Claude2DSH](https://github.com/kirkchinese/claude2dsh) 用于在 Claude Code 与 DSH 之间迁移会话和资产。
MIT License.