# @goodandready/dsh-context-lens 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-context-lens/

版本：0\.1\.36
npm 元数据更新时间：2026-11-12T11:45:40.727Z
中文译文更新时间：2026-11-16T19:12:24.776Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-context-lens
原文对照：https://npmcn.com/package/%40goodandready/dsh-context-lens/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-context-lens#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-context-lens

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：101 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-tools ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-08-31T11:44:35.200Z
- 最新版本发布：2026-11-12T11:45:40.497Z
- 近 30 天下载量：6008（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

用于语义 AST 代码骨架化和测试/构建日志压缩的 DSH 插件

## 安装

```sh
npm install @goodandready/dsh-context-lens
```

也可以使用：`pnpm add @goodandready/dsh-context-lens`、`yarn add @goodandready/dsh-context-lens`、`bun add @goodandready/dsh-context-lens`

## README

# 📦 @goodandready/dsh-context-lens

### DeepSeek Harness 语义 AST 代码骨架提取与测试日志压缩插件

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-context-lens.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-context-lens) [![license](https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-context-lens/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-context-lens/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-context-lens/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-context-lens/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢本插件，请在 GitHub 上点亮 Star</strong> —— 这能让我了解插件对您有所帮助，并激励我持续维护和演进它。<br><br>🐛 <strong>如遇问题或有功能建议</strong>，欢迎使用任意语言提交 GitHub Issue —— 您的所有实用建议都将在后续版本中得到评估和实现。</td></tr></tbody></table>

* * *

## ⚡ 核心定位与职责划分

> **说明：**  
> 上下文预算控制、Token 计数、工具输出头尾截断 (`dsh-compaction-tool-result-pruner`) 以及大文件溢出落盘 (`dsh-spill-policy`, `dsh-token-meter`) 由 **DSH 核心引擎 (>= 0.1.5)** 原生负责。  
> **`dsh-context-lens`** 专注于核心不具备的能力 —— **语义压缩**：
> 
> 1.  **AST 代码骨架生成**：提取函数签名、接口、类型定义及文档注释，去除冗长实现体（支持 9+ 种语言）。
> 2.  **焦点路径机制**：正在编辑的文件保留全量内容，周边工作区文件生成骨架。
> 3.  **测试与构建日志压缩**：保留失败信息、错误栈及汇总结果，剔除冗余输出。

```mermaid
graph LR
    subgraph RawContext [原始输入]
        Code[📁 源代码] --> Lens[dsh-context-lens 语义引擎]
        Logs[📋 测试与构建日志] --> Lens
    end

    subgraph Lens [语义压缩处理]
        Lens --> Focus{路径焦点判断}
        Focus -->|聚焦文件| FullCode[保留完整代码]
        Focus -->|周边文件| AST[AST 骨架提取]
        Lens --> LogCompress[日志压缩: 错误/堆栈/汇总]
    end

    subgraph Output [优化后上下文]
        FullCode --> Agent[🤖 Agent 上下文]
        AST --> Agent
        LogCompress --> Agent
        Agent --> Core[⚙️ DSH 核心截断与溢出策略]
    end

    style RawContext fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style Lens fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style Output fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
```

* * *

## 🛠️ Agent 工具参考 (归并至 2 个工具)

所有工具完全符合 DeepSeek Harness 规范，`output.render` 统一返回 `ContentBlock[]` 数组。

| 工具名 | 操作模式 | 参数 | 描述 |
| --- | --- | --- | --- |
| `context_lens_code` | `action: "skeleton"` (默认) | `filePath?`, `code?`, `language?`, `maxDepth?`, `sessionId?` | 直接从 `filePath` 读取并生成 AST 骨架（无需预先读取完整文件，节省上下文），或基于传入的 `code` 处理。若处于焦点内则返回完整代码 |
| `context_lens_code` | `action: "focus"` | `paths: string[]`, `sessionId?` | 设置当前会话的焦点路径列表 |
| `context_lens_code` | `action: "get_focus"` | `sessionId?` | 获取当前会话的焦点状态 |
| `context_lens_code` | `action: "clear_focus"` | `sessionId?` | 清空当前会话的焦点路径 |
| `context_lens_log` | N/A | `text` _(或 `log`)_, `mode?`, `maxLines?`, `auto?`, `command?` | 压缩测试或构建日志，保留错误、堆栈及总结信息 |

* * *

## ⚙️ 配置项

在 DSH 设置中心 (`plugins.row.config` / `plugins.item`) 中配置：

| 配置项 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `compressionMode` | `string` | `'balanced'` | 日志压缩模式 (`raw`, `balanced`, `aggressive`) |
| `astSkeletonMaxDepth` | `number` | `3` | AST 骨架最大嵌套深度 |
| `autoCompressThreshold` | `number` | `4000` | 调用 `context_lens_log (auto: true)` 时自动压缩触发的字符阈值（设为 0 禁用） |

* * *

## 📄 授权协议

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-context-lens 是什么？

用于语义 AST 代码骨架化和测试/构建日志压缩的 DSH 插件

### 如何安装 @goodandready/dsh-context-lens？

在项目目录运行 npm install @goodandready/dsh-context-lens，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-tools（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-context-lens 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-context-lens 是否存在。

### @goodandready/dsh-context-lens 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-context-lens 可以商用吗？

@goodandready/dsh-context-lens 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-context-lens 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-context-lens 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,008 次，日均约 200 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-context-lens 还在维护吗？

最新版本 0\.1\.36 发布于 2026/11/12（4 天前）；至今共发布 36 个版本，其中过去 12 个月发布了 36 个；首次发布于 2026/08/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

