@dsh-plugin/dsh-force-read-skill 0.0.0-stage → 0.1.0-dev.42788551751

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+<div align="center">
 
-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 Force Read Skill
+
+**Require a DeepSeek Harness model to read a skill before using other tools.**
+
+English | [简体中文](README.zh_CN.md)
+
+</div>
+
+[![CI](https://github.com/dsh-plugins/dsh-force-read-skill/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/dsh-plugins/dsh-force-read-skill/actions/workflows/npm-publish.yml)
+[![npm](https://img.shields.io/npm/v/@dsh-plugin/dsh-force-read-skill)](https://www.npmjs.com/package/@dsh-plugin/dsh-force-read-skill)
+
+## Install
+
+Install dsh-loader 2.0 and the plugin in the same Web profile.
+
+```sh
+dsh plugin --profile web add "@dsh-plugin/dsh-loader@next"
+dsh plugin --profile web add "@dsh-plugin/dsh-force-read-skill"
+```
+
+Edit and save the configuration on the plugin details page. Saved changes take effect immediately.
+
+| Setting | Default | Behavior |
+| --- | --- | --- |
+| Require skill reading (`enabled`) | Enabled | Reject other tool calls until the model reads an eligible skill. |
+| Required skills (`requiredSkills`) | Empty list | An empty list accepts any skill. Otherwise, the model must read one skill from the list. |
+
+A successful read applies to the current session, including resumed sessions, until the next successful context compaction. A `/skill-name` invocation that injects eligible skill instructions also satisfies the requirement.
+
+The `skill` tool is exempt. Programmatic Tool Calling (PTC) presets can read through `run_code` and receive the instructions in the next model request. Other tool calls in the same batch still undergo the check.
+
+Rejected calls return **You must read those skills that you should read.**
+
+## Build and test
+
+```sh
+npm ci
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```

package/README.zh_CN.md

@@ -0,0 +1,44 @@
+<div align="center">
+
+# DSH Force Read Skill
+
+**要求 DeepSeek Harness 模型先读取 SKILL，再使用其他工具。**
+
+[English](README.md) | 简体中文
+
+</div>
+
+[![持续集成](https://github.com/dsh-plugins/dsh-force-read-skill/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/dsh-plugins/dsh-force-read-skill/actions/workflows/npm-publish.yml)
+[![npm 版本](https://img.shields.io/npm/v/@dsh-plugin/dsh-force-read-skill)](https://www.npmjs.com/package/@dsh-plugin/dsh-force-read-skill)
+
+## 安装
+
+在同一个 Web 配置档案中安装 dsh-loader 2.0 和本插件。
+
+```sh
+dsh plugin --profile web add "@dsh-plugin/dsh-loader@next"
+dsh plugin --profile web add "@dsh-plugin/dsh-force-read-skill"
+```
+
+在插件详情页修改配置，保存后立即生效。
+
+| 配置项 | 默认值 | 行为 |
+| --- | --- | --- |
+| 强制阅读 SKILL（`enabled`） | 开启 | 模型成功读取符合要求的 SKILL 后，才可调用其他工具。 |
+| 指定 SKILL（`requiredSkills`） | 空列表 | 留空时可读取任意 SKILL。填写后，读取列表中的任意一个即可。 |
+
+成功读取后，当前会话放行至下一次成功的上下文压缩。恢复会话时沿用该会话的记录。通过 `/技能名` 注入符合要求的技能正文也可满足要求。
+
+插件豁免 `skill`。程序化工具调用（Programmatic Tool Calling，PTC）预设可通过 `run_code` 读取 SKILL，正文会随下一步请求发送给模型。同一批次内的其他工具调用仍需通过检查。
+
+未满足要求时，工具返回 **You must read those skills that you should read.**
+
+## 构建与测试
+
+```sh
+npm ci
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-force-read-skill
+      name: '@dsh-plugin/dsh-force-read-skill'

package/lib/history.d.ts

@@ -0,0 +1,49 @@
+export interface ContentBlock {
+    readonly type: string;
+    readonly text?: string;
+}
+interface ToolResultBlock extends ContentBlock {
+    readonly isError?: boolean;
+}
+type SessionEvent = {
+    readonly type: 'step/end';
+} | {
+    readonly type: 'compaction/end';
+    readonly data: {
+        readonly error?: string;
+    };
+} | {
+    readonly type: 'tool/call';
+    readonly data: {
+        readonly name: string;
+        readonly arguments: string;
+    };
+} | {
+    readonly type: 'tool/result';
+    readonly sourceEventSeqs?: readonly number[];
+    readonly data: {
+        readonly message: {
+            readonly role: string;
+            readonly isError?: boolean;
+            readonly content: readonly ToolResultBlock[];
+        };
+    };
+} | {
+    readonly type: 'user/message';
+    readonly data: {
+        readonly source: {
+            readonly kind: string;
+            readonly form?: string;
+        };
+        readonly content: readonly ContentBlock[];
+    };
+};
+export interface SessionHistory {
+    readonly events?: readonly SessionEvent[];
+    snapshotEvents?(): readonly SessionEvent[];
+}
+/** 从完整的技能正文提取宿主渲染的名称。 */
+export declare function readSkillName(content: readonly ContentBlock[]): string | undefined;
+/** 查找最近一次成功压缩后已交付给模型的技能读取结果。 */
+export declare function hasReadSkill(session: SessionHistory, requiredSkills: readonly string[]): boolean;
+export {};

package/lib/history.js

@@ -0,0 +1,60 @@
+const skillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** 从完整的技能正文提取宿主渲染的名称。 */
+export function readSkillName(content) {
+    for (const block of content) {
+        if (block.type !== 'text' || !block.text?.trimEnd().endsWith('</skill_content>')) {
+            continue;
+        }
+        const name = /^<skill_content name="([^"]+)">\r?\n/.exec(block.text)?.[1];
+        if (name !== undefined && skillNamePattern.test(name)) {
+            return name;
+        }
+    }
+    return undefined;
+}
+/** 查找最近一次成功压缩后已交付给模型的技能读取结果。 */
+export function hasReadSkill(session, requiredSkills) {
+    const events = session.snapshotEvents?.() ?? session.events ?? [];
+    let previousStep = false;
+    for (let index = events.length - 1; index >= 0; index--) {
+        const event = events[index];
+        if (event.type === 'compaction/end' && event.data.error === undefined) {
+            return false;
+        }
+        if (event.type === 'step/end') {
+            previousStep = true;
+            continue;
+        }
+        let name;
+        if (event.type === 'user/message' && event.data.source.kind === 'skill-invocation'
+            && event.data.source.form === 'instructions') {
+            name = readSkillName(event.data.content);
+        }
+        else if (previousStep && event.type === 'tool/result') {
+            const callSeq = event.sourceEventSeqs?.[0];
+            const call = callSeq === undefined ? undefined : events[callSeq];
+            if (call?.type !== 'tool/call' || call.data.name !== 'skill') {
+                continue;
+            }
+            const message = event.data.message;
+            const result = message.role === 'tool' ? message : message.content[0];
+            if (result?.isError !== false) {
+                continue;
+            }
+            // DSH 可能将长正文写入溢出文件。成功结果确认读取，原始调用保留技能名称。
+            try {
+                const args = JSON.parse(call.data.arguments);
+                if (typeof args?.name === 'string' && skillNamePattern.test(args.name)) {
+                    name = args.name;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+        if (name !== undefined && (requiredSkills.length === 0 || requiredSkills.includes(name))) {
+            return true;
+        }
+    }
+    return false;
+}

package/lib/index.d.ts

@@ -0,0 +1,43 @@
+import type { CordisContext, HostAPI } from '@dsh-plugin/dsh-loader';
+import { type ContentBlock, type SessionHistory } from './history.js';
+export declare const name = "@dsh-plugin/dsh-force-read-skill";
+export declare const inject: string[];
+interface Execution {
+    readonly name: string;
+    readonly agent?: {
+        readonly session: SessionHistory;
+    };
+    readonly parent?: object;
+}
+interface Result {
+    readonly isError: boolean;
+    readonly content: readonly ContentBlock[];
+}
+type PreDecision = {
+    readonly kind: 'allow' | 'cancel';
+} | {
+    readonly kind: 'ask';
+    readonly reason?: string;
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+};
+type PostDecision = {
+    readonly kind: 'accept';
+    readonly content?: readonly ContentBlock[];
+    readonly value?: unknown;
+    readonly additionalContexts?: readonly unknown[];
+} | {
+    readonly kind: 'block';
+    readonly feedback: readonly ContentBlock[];
+};
+interface PluginContext extends CordisContext {
+    readonly dshLoader: HostAPI;
+    on(event: 'tools/pre-execute', listener: (exec: Execution, next: () => Promise<PreDecision>) => Promise<PreDecision>, options?: {
+        prepend?: boolean;
+    }): () => void;
+    on(event: 'tools/post-execute', listener: (exec: Execution, result: Result, next: () => Promise<PostDecision>) => Promise<PostDecision>): () => void;
+}
+/** 注册阅读要求，并在工具请求进入权限检查前执行校验。 */
+export declare function apply(ctx: PluginContext): Promise<void>;
+export {};

package/lib/index.js

@@ -0,0 +1,68 @@
+import { defineConfig } from '@dsh-plugin/dsh-loader/config';
+import { hasReadSkill, readSkillName } from './history.js';
+export const name = '@dsh-plugin/dsh-force-read-skill';
+export const inject = ['dshLoader', 'tools'];
+const id = 'dsh-force-read-skill';
+const denialReason = 'You must read those skills that you should read.';
+/** 注册阅读要求，并在工具请求进入权限检查前执行校验。 */
+export async function apply(ctx) {
+    const loader = ctx.dshLoader;
+    const preferences = await loader.config.register(ctx, defineConfig({
+        id,
+        packageName: name,
+        title: '强制阅读 SKILL',
+        fields: [
+            { type: 'boolean', key: 'enabled', label: '强制阅读 SKILL', default: true },
+            {
+                type: 'array',
+                key: 'requiredSkills',
+                label: '指定 SKILL',
+                description: '读取其中任意一个即可。留空时可读取任意 SKILL。',
+                default: [],
+                item: { type: 'text', label: 'SKILL 名称', pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$' },
+            },
+        ],
+    }));
+    const check = (exec) => {
+        const { enabled, requiredSkills } = preferences.get().value;
+        if (!enabled || !exec.agent || exec.name === 'skill' || exec.name === 'run_code') {
+            return undefined;
+        }
+        if (hasReadSkill(exec.agent.session, requiredSkills)) {
+            return undefined;
+        }
+        return denialReason;
+    };
+    // 先于权限询问拒绝调用，并在宿主的最终检查中再次执行同一规则。
+    ctx.effect(() => ctx.on('tools/pre-execute', async (exec, next) => {
+        const reason = check(exec);
+        return reason === undefined ? next() : { kind: 'deny', reason };
+    }, { prepend: true }), `${id}:check`);
+    const tools = loader.services.get('tools');
+    ctx.effect(() => tools.guard(check), `${id}:guard`);
+    ctx.effect(() => ctx.on('tools/post-execute', async (exec, result, next) => {
+        if (!exec.agent || !exec.parent || exec.name !== 'skill' || result.isError) {
+            return next();
+        }
+        const { enabled, requiredSkills } = preferences.get().value;
+        if (!enabled) {
+            return next();
+        }
+        const decision = await next();
+        if (decision.kind !== 'accept' || Object.hasOwn(decision, 'value')) {
+            return decision;
+        }
+        const content = decision.content ?? result.content;
+        const skill = readSkillName(content);
+        if (skill === undefined || (requiredSkills.length !== 0 && !requiredSkills.includes(skill))
+            || hasReadSkill(exec.agent.session, requiredSkills)) {
+            return decision;
+        }
+        // PTC 的子调用结果只交给程序。附加正文后，模型可在下一步直接读取。
+        const instructions = loader.llm.createUserMessage({
+            source: { kind: 'skill-invocation', name: skill, form: 'instructions' },
+            content,
+        });
+        return { ...decision, additionalContexts: [...decision.additionalContexts ?? [], instructions] };
+    }), `${id}:deliver-ptc-skill`);
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@dsh-plugin/dsh-force-read-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.42788551751",
+  "description": "要求 DeepSeek Harness 模型先读取 SKILL，再执行其他工具。",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-plugins/dsh-force-read-skill.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.zh_CN.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=24.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@dsh-plugin/dsh-loader": "^2.0.0-dev.42783642741"
+  },
+  "devDependencies": {
+    "@dsh-plugin/dsh-loader": "2.0.0-dev.42783642741",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  }
+}