GinerYard/dsh-chords

dsh-chords · Chords（和弦）

DeepSeek Harness 插件：代码与自然语言的和弦；CHORDS = Code Harness, Online Reference for DeepSeek.

一个 DeepSeek Harness 插件：代码与自然语言之间的和弦 —— CHORDS = Code Harness, Online Reference for DeepSeek.

版本 Version: 0.3.3 | 兼容 Compatible with: DeepSeek Harness 0.1.0-rc.6

功能特性 / Features

- 双栏卡片：左侧代码（语法高亮 + 行号），右侧分块伪代码（通俗易懂的自然语言）
双栏卡片：左侧代码（语法高亮 + 行号），右侧分块伪代码（真正的自然语言，绝不出现 if/for/new 等关键字）
- 三色确定性标签：🔵 明确（用户要求）/ 🟡 推测（上下文推导）/ ⚪ 默认（惯例填充）
确定性标签：🔵 明确 / 🟡 推测 / ⚪ 默认
- 锚点高亮：悬停解释块 → 对应代码行整行琥珀色高亮；点击任一侧 → 对侧滚动居中
锚点高亮：悬停伪代码块即可点亮对应的代码行；点击任一侧即可将对侧滚动居中
- 原地编辑：✎ 修改（块级精修）/ ✎ 改算法（整体重设计）；后台 LLM 完成，对话完全零污染
原地编辑：块级精修与整卡重设计均在后台运行 —— 对话保持零污染
- 版本历史：◀ ▶ 浏览任意历史版本；基于任意版本修改都追加为最新版本；每卡上限 20 版
版本历史：用 ◀ ▶ 浏览任意历史版本；基于任意版本的修改始终追加为最新版本；每卡上限 20 版
- 重命名：点击标题即可改名；改名链保证旧标题查询依然命中、刷新后依然生效
重命名：点击标题即可改名；改名链保证旧标题在刷新后依然可被解析命中
- Agent 集成：后台修改自动进入运行时上下文；chords_current / chords_list / chords_history 供 agent 查询任意版本
Agent 集成：后台修改会自动进入运行时上下文；三个查询工具让 agent 可读取任意版本
- 持久化：文档、历史、改名链落盘，重启存活；TTL 自动老化；会话销毁即清理
持久化：文档、历史与改名链在重启后依然存活；TTL 自动老化；会话销毁时清理
- 自动国际化：非中文系统自动切换英文界面
自动国际化：非中文系统自动切换为英文界面
- 分层模型路由：按代码长度自动选择模型档位与思考级别（见下文）
分层模型路由：模型档位与思考级别随代码长度自动选择（见下文）

环境要求 / Requirements

- DeepSeek Harness 已安装（dsh 命令可用，web profile 可启动），版本 0.1.0-rc.6 或 API 兼容
DeepSeek Harness 已安装（dsh 命令可用，web profile 可启动），版本 0.1.0-rc.6 或 API 兼容
- 模型路由可用（默认 deepseek-official；其他厂商需对应适配器已安装）
模型路由可用（默认 deepseek-official；其他厂商需安装对应适配器）

安装 / Installation

1. 复制插件目录 / Copy the plugin directory

将包内的 dsh-chords 文件夹复制到 DSH 的共享 node_modules：
Copy-Item -Recurse ./dsh-chords "$env:DSH_HOME\profiles\node_modules\"
或在目标机器上走 pnpm：
dsh plugin --profile web add

2. 注册插件 / Register the plugin

编辑 $env:DSH_HOME\profiles\web\cordis.patch.yml，把 [] 替换为：

- insert:
- id: chords
name: dsh-chords
可选配置见下文「模型路由与配置」

3. 重启 / Restart

dsh web --port 8080

刷新浏览器页面。让 agent 生成一段代码，应出现双栏卡片。
刷新浏览器。让 agent 写一些代码——双栏卡片应该会出现。

使用教程 / Tutorial

1. 生成卡片 / Create a card

在对话里让 agent 写代码。agent 会自动调用 chords，
代码以双栏卡片呈现，且不会在正文重复粘贴。
在对话中让 agent 写代码（例如用 Python 写一个归并排序）。agent 会自动调用
chords：代码以双栏卡片呈现，且不会在消息中重复。

2. 阅读卡片 / Reading the card

- 左侧代码：语法高亮、行号、整行可点
左栏：带语法高亮的代码和行号；每一整行都可点击
- 右侧每个解释块：块 id、行号徽章（如 L3-7）、确定性圆点、伪代码、复杂度徽章、理由
右栏各块：块 id、行号范围标签（如 L3-7）、确定性圆点、伪代码、复杂度徽章、理由
- 悬停解释块 → 对应代码行整行高亮；点击任一侧 → 对侧滚动居中
悬停某个块可高亮匹配的代码行；点击任一侧可将对侧滚动居中

3. 修改卡片/ Edit a card

- 块级精修：悬停解释块 → 点「✎ 修改」→ 改写该块伪代码 → 「提交修改」。只改这一块，其余保持不变
块级编辑：悬停某个块 → ✎ 修改 → 改写其伪代码 → 提交。只改这一块
- 整体重设计：点「✎ 改算法」→ 用自然语言描述新算法 → 「提交重设计」。允许自由重新分块
整体重设计：✎ 改算法 → 用自然语言描述新算法 → 提交重设计。允许重新分块
- 修改在后台由 LLM 完成，卡片原地更新（版本 +1、摘要提示），对话里不会出现任何消息
修改在后台由 LLM 完成；卡片原地更新（版本 +1、摘要提示）。对话中不会出现任何消息
- 进行中可「终止修改」；同一时间一张卡只允许一个在途修改
你可以终止进行中的修改；每张卡同一时间只允许一个在途修改

4. 版本历史 / Version history

- 卡片头部 ◀ v2/5 ▶ 浏览历史版本；「回到最新」返回
使用卡片头部的 ◀ v2/5 ▶ 浏览历史版本；回到最新可返回
- 从任意历史版本发起修改，结果都追加为最新版本（不分支、不覆盖历史）
从任意历史版本发起的修改，结果都追加为最新版本（不分支、不覆盖历史）
- 刷新/重启后历史依然完整（宿主持久化）
历史在刷新和重启后依然完整（宿主持久化）

5. 重命名 / Rename

点击卡片标题 → 输入新名 → 回车。改名后：旧标题查询依然命中、刷新后依然生效、后续修改继续合并到同一张卡。
点击卡片标题，输入新名称，按回车。重命名后：旧标题查询依然命中，
重命名在刷新后依然生效，后续修改继续合并到同一张卡。

6. 对话内修改与查询 / In-conversation edits and queries

- 直接在对话里说「把这段改成 XX」：agent 会先查最新版（chords_current）再修改，同标题合并成细条
把对话中的这句话改成 XX：agent 先读取最新版本，再把更新合并进同一张卡片
- 「这个卡片 v2 时长什么样？」：agent 用 chords_history 拉取任意历史版本
这张卡片在 v2 时是什么样子：agent 使用 chords_history 获取任意过往版本

模型路由与配置 / Model routing and configuration

后台修改按代码行数分三档（单次 LLM 调用完成代码 + 解释块）：
后台修改按代码行数分三档，每次修改使用一次 LLM 调用：

| 档位 Tier | 行数 Lines | 模型 Model | 思考 Reasoning | maxTokens | 超时 Timeout |
|---|---|---|---|---|---|
| 小 Small | ≤200 | 跟随对话模型 follow the session model | off | 8192 | 180s |
| 中 Medium | 201-500 | 强档模型 strong model | off | 16384 | 360s |
| 大 Large | >500 | 强档模型 strong model | high | 131072 | 900s |

全部参数可在 cordis.patch.yml 覆盖：
每个参数都可以在 cordis.patch.yml 中覆盖：

- insert:
- id: chords
name: dsh-chords
config:
followSessionModel: true     # 跟随会话默认模型（false 则用下方 provider/model）
provider: ""                 # 显式覆盖（空 = 跟随）
model: ""                    # 显式覆盖
strongModel: ""              # 中大档的强档模型（空 = 查厂商表）
smallLines: 200
largeLines: 500
effortSmall: "off"
effortLarge: "high"
maxTokens: 8192
maxTokensLarge: 16384
maxTokensHuge: 131072
timeoutMs: 180000
timeoutMsLarge: 360000
timeoutMsHuge: 900000
ttlDays: 14                  # 文档无更新超过该天数视为过期
providers:                   # 主流厂商的默认档/强档（模型名按部署实际调整）
deepseek-official: { default: deepseek-v4-flash, strong: deepseek-v4-pro }
openai: { default: gpt-4o-mini, strong: gpt-4o }
anthropic: { default: claude-sonnet-4, strong: claude-opus-4 }
moonshot: { default: moonshot-v1-8k, strong: moonshot-v1-128k }
"z-ai": { default: glm-4-flash, strong: glm-4-plus }
volcengine: { default: doubao-1-5-pro-32k, strong: doubao-1-5-pro-256k }
xai: { default: grok-3-mini, strong: grok-3 }
google: { default: gemini-2.0-flash, strong: gemini-2.5-pro }
minimax: { default: MiniMax-Text-01, strong: MiniMax-M1 }

说明：插件只传 provider/model/reasoningEffort，各厂商的线缆参数由 DSH 适配器翻译；
reasoningEffort 目前支持 off / high / max。非 deepseek 厂商需要其适配器已安装。
说明：插件只传递 provider/model/reasoningEffort；线缆参数由各厂商的 DSH 适配器翻译
（reasoningEffort：off / high / max）。非 DeepSeek 厂商需要安装其适配器。

数据与隐私 / Data and privacy

- 插件数据（文档、版本历史、改名链、修改摘要）只落在本机：/storages/code_lens.json
所有插件数据（文档、版本历史、改名链、修改摘要）都保留在本机：/storages/code_lens.json
- 无更新超过 ttlDays（默认 14 天）自动过期；会话销毁即清理该会话全部数据
文档闲置超过 ttlDays（默认 14 天）会过期；销毁会话会清除其数据
- 代码内容本身不离开你配置的模型路由（与普通对话一致）
代码内容永远不会离开你配置的模型路由（与普通对话相同）

故障排查 / Troubleshooting

| 现象 Symptom | 处理 Fix |
|---|---|
| 修改失败并提示「后台修改失败：…」 | 按提示原因处理；多为模型输出非 JSON（自动重试一次）或超时 |
| 后台修改失败：… | 阅读原因；通常是模型回复非 JSON（自动重试一次）或超时 |
| 「未找到输入桥…」 | 远程通道降级失败；按提示粘贴到输入框即可（对话流程会接管） |
| 未找到输入桥… | 后台通道降级；按提示将请求粘贴到输入框 |
| 重启后数据丢失 | 检查启动日志是否出现 version-mismatch / memory-only；新版会自动弃置旧单元重建 |
| 重启后数据丢失 | 检查启动日志是否出现 version-mismatch / memory-only；当前版本会自愈 |
| 卡片渲染异常 | 单卡有独立错误边界，会把错误文字显示在卡片上；把原文反馈给作者 |
| 卡片渲染错误 | 每张卡片都有自己的错误边界并显示消息；请报告该问题 |

开发者 / 开发者

- 宿主集成契约（远程 API、数据模型、客户端算法）：见 REMOTE-API.md
宿主集成契约（远程 API、数据模型、客户端算法）：见 REMOTE-API.md
- 包结构：dsh-chords/package.json + lib/index.js（宿主半）+ lib/client.js（Web 客户端半）
包结构：dsh-chords/package.json + lib/index.js（宿主半）+ lib/client.js（Web 客户端半）
- 迁移安装指南：见 INSTALL.md
迁移安装指南：见 INSTALL.md
- 测试：test/ 内含 7 组 vitest 测试（38 个用例，纯函数级，无需启动 Harness、无需真模型）；在插件目录执行 npm i -D vitest 后运行 npm test
测试：test/ 内含 7 组 vitest 测试套件（38 个用例，纯函数级；无需启动 Harness，无需真实模型）。在插件目录内运行 npm i -D vitest，然后运行 npm test

变更历史 / 变更历史

- 0.3.3 bug修复
- 0.2.63 渲染微调
- 0.2.62 纯函数测试（38 用例）+ 测试用导出 + npm test 脚本
- 0.2.61 渲染修复
- 0.2.60 自动国际化（中/英）
- 0.2.59 后台修改改为单次合并 LLM 调用
- 0.2.58 三档模型路由
- 0.2.56 并发与存储原子性修复
- 0.2.54 串行注册队列
- 0.2.53 持久化自愈
- 0.2.51 版本历史宿主水合
- 0.2.45 重命名 + 改名链
- 0.2.44 版本导航 ◀ ▶
- 0.2.29 持久化存储域 + TTL + 会话销毁清理
- 0.2.22 后台修改通道
- 0.2.10 忙碌锁与终止
- 0.2.9 会话隔离
- 0.2.3 上下文回流 + chords_current
- 0.2.0 原地编辑
- 0.1.x 双栏卡片、三色确定性、锚点高亮

证书 / 许可证

MIT © 2026 GinerYard —— 全文见 LICENSE / MIT © 2026 GinerYard — 见 LICENSE 文件