dsh-docstring-gen

DeepSeek Harness 插件：从传入的源码文本中解析函数 / 方法 / 类签名，生成文档注释脚手架，并统计哪些符号还缺文档。

纯文本工具：正则解析 + 注释/字符串遮蔽（masked scan），不读文件、不起子进程、不联网；同样的输入永远得到同样的输出。

安装

npx -y @deepseek-ai/dsh plugin --profile web add @qingshanjiluo/dsh-docstring-gen

工具

工具	参数	作用
doc_scaffold	code（必填）、style（jsdoc / python-docstring / rst / auto）、language（typescript / javascript / python / auto）	返回带注释的原文：每个尚无文档的函数 / 方法 / 类前（JS/TS）或签名后（Python 函数体首行）插入一段脚手架——摘要行 + 按签名推断出的每个参数一行（@param {类型} 名、Args:、:param 名: / :type / :rtype），已有 JSDoc 或 docstring 的符号保持原样。
doc_scan	code（必填）、language	返回未写文档的符号清单（名称、所属类、kind、1 基行号、签名、参数名）与总数统计。

两个工具都是纯函数（isConcurrencySafe），可并行调用。

示例（TypeScript）：

const toKey = (value: string): string => value.trim().toLowerCase()

doc_scaffold 产出：

/**
 * TODO: describe what `toKey` does.
 *
 * @param {string} value - TODO
 * @returns {string} TODO
 */

Python 的 docstring 会插入到函数体内部（缩进按实际函数体推断）：

def summarize(items, sep):
    """TODO: describe what `summarize` does.

    Args:
        items: TODO
        sep: TODO

    Returns:
        TODO
    """

配置

配置项	类型	默认值	说明
defaultStyle	string	"auto"	调用传 auto 时使用的文档风格；auto 按语言选择（Python → python-docstring，JS/TS → jsdoc）。
defaultLanguage	string	"auto"	调用传 auto 时使用的语言；auto 依据词法特征打分判定。
maxSymbols	number	200	单次调用最多处理的声明数，超出部分忽略并在 truncated / notes 中说明。

风格与语言不匹配时不会报错：会回退到该语言的原生约定，并在 notes 中说明原因。

解析边界（启发式）

• 注释、字符串、模板串、正则字面量内部出现的 “代码” 会被遮蔽，不会被当作声明。
• JS/TS 识别 function、class、类方法（含 static / async / get / set / 修饰符）、箭头函数常量与类字段（const f = (…) => …、onClick = (e) => {…}）、函数表达式赋值；if (x) {、for (…) { 等控制流关键字不会误报。
• Python 识别 def / async def / class，跳过 self / cls 与仅含 interface/类型声明的成员；*args / **kwargs 保留星号前缀。
• 嵌套关系按缩进推断：类内函数报为 method，其 parent 为类名。
• “已有文档” 的判定：JS/TS 看上一行是否为 /** … *\/ 块（允许中间夹装饰器），Python 看签名后首个非空行是否为字符串字面量。

开发

npm install --no-audit --no-fund
npx tsc --noEmit
npm run build          # 产出 lib/index.js 与 lib/index.d.ts
npx vitest run         # 导出面 + 每个工具的行为用例
node scripts/load-smoke.mjs

插件契约见 src/index.ts：export const name / export const inject = ['tools'] / export interface Config + export const Config（schemastery）/ export function apply(ctx, config)；解析与渲染分别在 src/parser.ts、src/render.ts。

License

MIT