dsh-js-tools 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# dsh-js-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH（DeepSeek Harness）通用测量工具插件。给 DSH 会话里的模型装上"精确测量"能力：字数统计与数学表达式求值，专治判分/评测 rubric 里的目测问题。
+
+**适配版本：DSH `0.2.1-alpha.3`**（依赖 `@deepseek-ai/dsh-tools` 同版本对齐）
+
+## 工具清单
+
+### 1. `text_stats` — 精确字数统计
+
+统计一段文本的精确字数，**不要目测**。判分中涉及「字数上限/下限」「篇幅」「长度」类 Rubric 时，模型会先调用本工具拿到精确数字再下结论。
+
+返回字段：
+
+| 字段 | 说明 |
+|---|---|
+| `characters` | 字符数（含空白） |
+| `bytes` | UTF-8 字节数 |
+| `lines` | 行数 |
+| `nonEmptyLines` | 非空行数 |
+| `words` | 单词数（按空白切分） |
+| `cjkCharacters` | 汉字数（CJK 统一表意文字） |
+| `whitespace` | 空白字符数 |
+| `nonAsciiCharacters` | 非 ASCII 字符数 |
+| `estimatedTokens` | 估算 token 数（CJK 0.6/字符，其他 0.25/字符） |
+
+超大文本（>10 万字符）请先分段再逐段调用。
+
+### 2. `evaluate_expression` — 安全表达式求值
+
+计算数学表达式，返回数值结果。支持四则运算、括号、幂(`^`)、百分号(`%`)。判分中涉及数字计算、比例换算、金额/权重计算的 Rubric 精确判定。
+
+示例：`3 * 4 + 2`、`(85 + 90) / 2`、`7 * 30`、`1200 * 0.2`
+
+安全设计：输入白名单过滤（仅数字/运算符/括号/小数点），禁止任何标识符，防注入。
+
+## 安装
+
+```bash
+# 在 DSH profile 目录下
+dsh plugin --profile xeval add -w dsh-js-tools
+```
+
+安装后可用 `dsh plugin --profile xeval dump-config` 确认插件进入依赖树。
+
+## 使用
+
+插件通过 `ctx.tools.register` 注册工具，DSH 会话内模型可自动调用。判分/评测场景建议在 prompt 中追加工具提示段，声明可用工具及"字数类/数值类 rubric 必须调用工具精确实测、禁止目测"的约束，模型才会主动调用。
+
+```text
+可用工具：
+- text_stats：精确统计文本字数（字符/行/词/CJK/token），涉及字数类 Rubric 必须先调用再判定，禁止目测。
+- evaluate_expression：计算数学表达式，涉及数值计算类 Rubric 必须先调用再判定。
+```
+
+## 验证
+
+已在 $OMB（OneMillion-Bench）判分链路实测通过：
+- q_293 字数 rubric（超 2000 字扣分）：模型调用 `text_stats` 实测 **2836 字符（CJK 2287）** 后精确判定，不再目测
+- 无字数/数值类 rubric 的题目，模型按需判断不调用工具，正常判分
+
+## 为什么自写
+
+社区同类插件存在兼容性问题：
+- `dsh-text-stats`：`cannot set property "textStats" without provide`（缺 provide 声明）
+- `dsh-plugin-calculator`：依赖旧版 `@deepseek-ai/dsh-tools@0.1.1-rc.2`，与 DSH 0.2.1-alpha.3 不兼容
+
+本插件按 DSH 0.2.1-alpha.3 的 `defineTool` API 编写，版本对齐。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: judge-tools
+      name: dsh-js-tools

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "dsh-js-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DSH (DeepSeek Harness) 通用测量工具插件：text_stats 精确字数统计 + evaluate_expression 安全表达式求值，适配 DSH 0.2.1-alpha.3",
+  "main": "src/index.js",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "judge",
+    "eval",
+    "text-stats",
+    "calculator",
+    "字数统计",
+    "判分"
+  ],
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,173 @@
+// dsh-judge-tools: $OMB 判分工具插件（适配 DSH 0.2.1-alpha.3）
+// 注册两个工具：text_stats（字数统计）+ evaluate_expression（表达式求值）
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+export const name = "judge-tools";
+export const inject = ["tools"];
+
+/** CJK 判定（用于 token 估算） */
+function isCjk(codePoint) {
+  return (
+    (codePoint >= 0x3400 && codePoint <= 0x4dbf) ||
+    (codePoint >= 0x4e00 && codePoint <= 0x9fff) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff)
+  );
+}
+
+function codePointLength(text) {
+  let n = 0;
+  for (const _ of text) n += 1;
+  return n;
+}
+
+/** 估算 token：CJK 0.6/字符，其他 0.25/字符 */
+function estimateTokens(text) {
+  let tokens = 0;
+  for (const ch of text) {
+    tokens += isCjk(ch.codePointAt(0)) ? 0.6 : 0.25;
+  }
+  return Math.ceil(tokens);
+}
+
+function computeStats(text) {
+  const chars = [...text].length;
+  const bytes = Buffer.byteLength(text, "utf8");
+  const lines = text.length === 0 ? 0 : text.split(/\r?\n/).length;
+  const nonEmptyLines = text.split(/\r?\n/).filter((l) => l.trim().length > 0).length;
+  const words = text.trim() ? text.trim().split(/\s+/).length : 0;
+  let cjk = 0;
+  let whitespace = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0);
+    if (/\s/.test(ch)) whitespace += 1;
+    else if (isCjk(cp)) cjk += 1;
+  }
+  const nonAscii = chars - [...text].filter((ch) => ch.codePointAt(0) < 0x80).length;
+  return {
+    characters: chars,
+    bytes,
+    lines,
+    nonEmptyLines,
+    words,
+    cjkCharacters: cjk,
+    whitespace,
+    nonAsciiCharacters: nonAscii,
+    estimatedTokens: estimateTokens(text),
+  };
+}
+
+/** 安全表达式求值：只允许数字/运算符/括号/小数点，禁止任何标识符 */
+function safeEval(expr) {
+  const cleaned = String(expr).trim();
+  if (!cleaned) throw new Error("表达式不能为空");
+  // 严格白名单：数字、四则、幂、括号、小数点、百分号、空格、逗号(千分位)
+  if (!/^[\d\s+\-*/().,%^]+$/.test(cleaned)) {
+    throw new Error(`表达式含非法字符（仅允许数字/四则/括号/幂/百分号）: ${cleaned.slice(0, 40)}`);
+  }
+  // 防御：不允许连续运算符开头等明显非法形态
+  if (/[+\-*/^]{2,}/.test(cleaned.replace(/--/g, ""))) {
+    // 幂与负号可能冲突，宽松处理；交给 Function 兜底
+  }
+  // 用 Function 构造执行（输入已白名单过滤，无标识符可达）
+  // eslint-disable-next-line no-new-func
+  const fn = new Function(`"use strict"; return (${cleaned});`);
+  const value = fn();
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`计算结果非法: ${value}`);
+  }
+  return value;
+}
+
+function renderNumber(v) {
+  // 保留最多 10 位有效数字，去掉浮点尾巴
+  const rounded = Math.abs(v) >= 1e15 || (Math.abs(v) < 1e-9 && v !== 0)
+    ? v.toExponential(6)
+    : String(Math.round(v * 1e10) / 1e10);
+  return rounded;
+}
+
+export function apply(ctx) {
+  ctx.on("ready", () => {
+    ctx.logger.info("[judge-tools] plugin ready");
+  });
+
+  ctx.tools.register(defineTool({
+    name: "text_stats",
+    description:
+      "统计一段文本的精确字数：字符数（含/不含空白）、字节数、行数、单词数、CJK 汉字数、估算 token 数。" +
+      "用于判分中涉及「字数上限/下限」「篇幅」「长度」类 Rubric 的精确判定——不要目测，先调用本工具拿到精确数字再下结论。" +
+      "超大文本（>10万字符）请先分段再逐段调用。",
+    parameters: {
+      text: {
+        type: "string",
+        required: true,
+        description: "要统计的文本内容（原样传入，不要截断）",
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          characters: { type: "integer" },
+          bytes: { type: "integer" },
+          lines: { type: "integer" },
+          nonEmptyLines: { type: "integer" },
+          words: { type: "integer" },
+          cjkCharacters: { type: "integer" },
+          whitespace: { type: "integer" },
+          nonAsciiCharacters: { type: "integer" },
+          estimatedTokens: { type: "integer" },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: "text",
+          text: `字符 ${value.characters}（CJK ${value.cjkCharacters}）/ 行 ${value.lines} / 词 ${value.words} / 估算 ${value.estimatedTokens} token`,
+        },
+      ],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const text = String(args.text ?? "");
+      if (text.length === 0) throw new Error("text_stats: `text` 不能为空");
+      return computeStats(text);
+    },
+    presentCall: (args) => ({ card: "generic", title: "字数统计", kind: "other", rawInput: args }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: "evaluate_expression",
+    description:
+      "计算数学表达式，返回数值结果。支持四则运算、括号、幂(^)、百分号(%)。" +
+      "用于判分中涉及数字计算、比例换算、金额/权重计算的 Rubric 精确判定。" +
+      "例：'3 * 4 + 2'、'(85 + 90) / 2'、'7 * 30'、'1200 * 0.2'。",
+    parameters: {
+      expression: {
+        type: "string",
+        required: true,
+        description: "数学表达式（只支持数字、+ - * / ( ) ^ % 和空格）",
+      },
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          expression: { type: "string" },
+          result: { type: "string" },
+        },
+      },
+      render: (_args, value) => [
+        { type: "text", text: `${value.expression} = ${value.result}` },
+      ],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const expr = String(args.expression ?? "");
+      const value = safeEval(expr);
+      return { expression: expr, result: renderNumber(value) };
+    },
+    presentCall: (args) => ({ card: "generic", title: "表达式计算", kind: "other", rawInput: args }),
+  }));
+}