dsh-plugin-manager-companion 0.1.0

package/dist/fix.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 分级修复：把诊断给出的 fix descriptor 变成实际动作。
+ *
+ * 归属：A 类·重写（旧仓库的 fixIssue/fixAll 在 index.ts 里，且直接写 patch 文件）。
+ * 官方复用：pluginManager.setPluginEnabled（行级启停）、installBundle（装包）、
+ *   saveManifest + withFileLock（声明改写）。
+ * 前提检查：旧仓库有 A/B/C 三级修复，其中"删重复行"直接改 cordis.patch.yml。
+ *   前提已变：官方现在拥有组合的写权，而它**没有**删行能力。我们不再自己写那个文件，
+ *   改为如实回 needs-manual —— 见 applyFix 的 JSDoc。
+ */
+import type { Context } from "@deepseek-ai/cordis";
+/**
+ * 一次修复的执行结果。
+ *
+ * `needs-manual` 不是失败：它是"这条修复没有官方通道，我们拒绝自己动手写 profile 组合"，
+ * 并把精确到行的操作步骤交回用户。与"执行失败"分开报，用户才知道该做什么。
+ */
+export interface FixOutcome {
+    readonly ok: boolean;
+    readonly action: string;
+    readonly target?: string;
+    /** executed = 已执行；needs-manual = 需用户手工；failed = 执行失败。 */
+    readonly status: "executed" | "needs-manual" | "failed";
+    readonly output: string;
+}
+/** applyFix 的依赖（由入口注入，避免 fix.ts 反向依赖 index.ts）。 */
+export interface FixDependencies {
+    readonly ctx: Context;
+    readonly environmentName: () => string | null;
+    /** 受质量门保护的安装（官方 add 通道）；由入口提供（它需要 config 与官方 Remote 编排）。 */
+    readonly install: (spec: string) => Promise<{
+        readonly ok: boolean;
+        readonly output: string;
+    }>;
+    /**
+     * 修复安装（官方 install 通道）：把 profile **已声明**的依赖真正装进 node_modules。
+     *
+     * @param target - 包名（用于文案；官方 install 按 package.json 全量收敛）。
+     * @returns 结果。
+     */
+    readonly repair: (target: string) => Promise<{
+        readonly ok: boolean;
+        readonly output: string;
+    }>;
+}
+/**
+ * 执行一条诊断给出的修复。
+ *
+ * 三条路，按"官方有没有现成通道"划分：
+ *   1. 行级启停 → 官方 setPluginEnabled（enable-row / disable-row）
+ *   2. 装包 → 入口提供的通道：install-provider 走受质量门保护的 add，
+ *      install-dependency 走官方 install（声明已在、只是没装，add 必被 already-installed 拒绝）
+ *   3. 删重复官方包拷贝 → 官方 withFileLock + 官方 saveManifest（remove-official-copy）
+ *
+ * @param action - 修复动作（诊断给出的闭集取值）。
+ * @param target - 动作目标，语义随 action 不同。
+ * @param deps - 依赖。
+ * @returns 执行结果。
+ */
+export declare function applyFix(action: string, target: string | undefined, deps: FixDependencies): Promise<FixOutcome>;

package/dist/fix.js

@@ -0,0 +1,168 @@
+/**
+ * 分级修复：把诊断给出的 fix descriptor 变成实际动作。
+ *
+ * 归属：A 类·重写（旧仓库的 fixIssue/fixAll 在 index.ts 里，且直接写 patch 文件）。
+ * 官方复用：pluginManager.setPluginEnabled（行级启停）、installBundle（装包）、
+ *   saveManifest + withFileLock（声明改写）。
+ * 前提检查：旧仓库有 A/B/C 三级修复，其中"删重复行"直接改 cordis.patch.yml。
+ *   前提已变：官方现在拥有组合的写权，而它**没有**删行能力。我们不再自己写那个文件，
+ *   改为如实回 needs-manual —— 见 applyFix 的 JSDoc。
+ */
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { environmentDir } from "./paths.js";
+import { requireManager } from "./official.js";
+/**
+ * 需要用户手工处理的两条：它们都要求改 cordis.patch.yml 的**结构**（删行）。
+ *
+ * 官方只有行级 setPluginEnabled（改某一行的 disabled），没有删行能力。我们自己写
+ * 这个文件会引入"两个写者并发改同一份组合"——那正是本仓库要消除的事故形态。
+ */
+const MANUAL_ACTIONS = new Set(["remove-duplicate-row", "remove-row"]);
+/**
+ * 装包类动作分两条通道，**不能合并**：
+ *
+ *   - install-provider：某个插件 import 了一个没被声明的包 → 要 `add` 它。
+ *   - install-dependency：package.json **已经声明**了，但 node_modules 里没有 → 要修复安装。
+ *
+ * 为什么 install-dependency 不能走 `add`：官方 inspect 把「已声明」当作「已安装」
+ * （already-installed 是官方 PluginInspectProblem 闭集里的取值），于是 `add` 必然被拒绝，
+ * 输出「拒绝安装：already-installed」——与诊断结论直接矛盾，用户点多少次都不会成功
+ * （write-auditor 真机验证发现，见 docs/private/write-path-audit.md §3·P3）。
+ * 官方 `dsh plugin --profile X install` 是把参数转发给 pnpm 的官方通道，修复安装用它。
+ */
+const ADD_ACTIONS = new Set(["install-provider"]);
+/** 修复安装类动作：声明齐全但 node_modules 缺失，走官方 install 通道。 */
+const REPAIR_ACTIONS = new Set(["install-dependency"]);
+/**
+ * 执行一条诊断给出的修复。
+ *
+ * 三条路，按"官方有没有现成通道"划分：
+ *   1. 行级启停 → 官方 setPluginEnabled（enable-row / disable-row）
+ *   2. 装包 → 入口提供的通道：install-provider 走受质量门保护的 add，
+ *      install-dependency 走官方 install（声明已在、只是没装，add 必被 already-installed 拒绝）
+ *   3. 删重复官方包拷贝 → 官方 withFileLock + 官方 saveManifest（remove-official-copy）
+ *
+ * @param action - 修复动作（诊断给出的闭集取值）。
+ * @param target - 动作目标，语义随 action 不同。
+ * @param deps - 依赖。
+ * @returns 执行结果。
+ */
+export async function applyFix(action, target, deps) {
+    if (MANUAL_ACTIONS.has(action))
+        return manualOutcome(action, target);
+    if (ADD_ACTIONS.has(action) || REPAIR_ACTIONS.has(action)) {
+        if (target === undefined) {
+            return failed(action, ADD_ACTIONS.has(action) ? "缺少 target（要安装的 spec）" : "缺少 target（包名）");
+        }
+        const result = ADD_ACTIONS.has(action) ? await deps.install(target) : await deps.repair(target);
+        return {
+            ok: result.ok, action, target,
+            status: result.ok ? "executed" : "failed", output: result.output,
+        };
+    }
+    try {
+        switch (action) {
+            case "enable-row":
+            case "disable-row": {
+                if (target === undefined)
+                    return failed(action, "缺少 target（loader 行 id）");
+                const manager = requireManager(deps.ctx);
+                const enabled = action === "enable-row";
+                const change = await manager.setPluginEnabled(target, enabled);
+                if (change.application === "failed") {
+                    const code = change.error?.code ?? "unknown";
+                    const detail = change.error?.diagnostic ?? "";
+                    return failed(action, "执行失败：" + code + (detail === "" ? "" : " —— " + detail));
+                }
+                return {
+                    ok: true, action, target, status: "executed",
+                    output: "已" + (enabled ? "启用" : "禁用") + " " + target + restartNote(change.application),
+                };
+            }
+            case "remove-official-copy":
+                if (target === undefined)
+                    return failed(action, "缺少 target（包名）");
+                return await removeOfficialCopy(target, deps);
+            default:
+                return { ok: false, action, status: "failed", output: "未知修复动作：" + action };
+        }
+    }
+    catch (error) {
+        return failed(action, error instanceof Error ? error.message : String(error), target);
+    }
+}
+/** 应用结果里"要不要重启"的补充说明。 */
+function restartNote(application) {
+    if (application === "restart-required")
+        return "（需要重启环境才能生效）";
+    if (application === "overridden")
+        return "（改动已保存，但被更高层覆盖，当前不生效）";
+    return "";
+}
+/** 构造一条 needs-manual 结果。 */
+function manualOutcome(action, target) {
+    const id = target ?? "（未知目标）";
+    return {
+        ok: false, action, ...(target === undefined ? {} : { target }), status: "needs-manual",
+        output: [
+            "这条修复要改 cordis.patch.yml 的结构，我们没有自己动手写这个文件。",
+            "",
+            "要修的是：" + action + "，目标 " + id,
+            "请在诊断报告里展开这条问题的证据 —— 它给了 cordis.patch.yml 的具体行号；",
+            "删掉多余那几行后保存即可，下一次启动生效。",
+            "",
+            "如果环境已经起不来：用 dsh --profile <name> --patch <空补丁.yml> 先拉起来，",
+            "或者交给 agent 用官方 plugin_manager 工具处理。",
+        ].join("\n"),
+    };
+}
+/** 构造一条 failed 结果。 */
+function failed(action, output, target) {
+    return { ok: false, action, ...(target === undefined ? {} : { target }), status: "failed", output };
+}
+/**
+ * 删掉 profile 里重复的官方包拷贝，并把声明从 dependencies 挪到 peerDependencies。
+ *
+ * 为什么安全：重复拷贝才是模块身份分裂的根因（profile 里出现第二份官方包，loader 的
+ * 最近优先解析会劫持官方行）。删掉后该包由共享 fallback 目录提供，与其它官方包共用一份。
+ *
+ * 两个写操作都在官方通道上：目录删除是普通文件系统操作（不是配置文件）；声明改写用
+ * 官方 saveManifest，并取官方同款的文件锁（与 pluginManager 的写用同一把），因此不会
+ * 与官方并发写 package.json 打架。
+ *
+ * @param packageName - 重复的官方包名。
+ * @param deps - 依赖。
+ * @returns 执行结果。
+ */
+async function removeOfficialCopy(packageName, deps) {
+    const envName = deps.environmentName();
+    if (envName === null)
+        return failed("remove-official-copy", "无法确定当前环境", packageName);
+    const dir = environmentDir(envName);
+    const copy = join(dir, "node_modules", ...packageName.split("/"));
+    const removed = [];
+    if (existsSync(copy)) {
+        await rm(copy, { recursive: true, force: true });
+        removed.push(copy);
+    }
+    const { withFileLock } = await import("@deepseek-ai/dsh-atomic-write");
+    const { readProfileManifest } = await import("@deepseek-ai/dsh-app-boot");
+    const { saveManifest } = await import("@deepseek-ai/dsh-plugin-manager/operations");
+    await withFileLock(join(dir, "package.json"), async () => {
+        const manifest = readProfileManifest("dsh", dir);
+        const dependencies = { ...(manifest.dependencies ?? {}) };
+        if (!Object.hasOwn(dependencies, packageName))
+            return;
+        delete dependencies[packageName];
+        const peers = { ...(manifest["peerDependencies"] ?? {}) };
+        peers[packageName] = peers[packageName] ?? "*";
+        await saveManifest(dir, { ...manifest, dependencies, peerDependencies: peers });
+    });
+    const declared = removed.length === 0 ? "未发现重复拷贝（可能已被清理）" : "已删除 " + removed[0];
+    return {
+        ok: true, action: "remove-official-copy", target: packageName, status: "executed",
+        output: declared + "；声明已从 dependencies 移到 peerDependencies。重启环境后由共享目录提供同一份官方包。",
+    };
+}

package/dist/guard.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 插件安装守卫：拦住 agent 走"裸命令"改插件状态，并把正确走法写进拒绝原因。
+ *
+ * 归属：A 类·重写（拦 agent 工具调用 + 注册常驻提示段；旧 src/guard.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/guard.ts（194 行：按 shell 段判定、
+ *   positional 词提取处理 --profile X 与 --profile=X 两种写法、npm 变体覆盖、
+ *   动词词边界避免误伤 install-assets 这类脚本名、denial reason 直接给正确命令）。
+ * 官方复用：官方 plugin_manager agent 工具（boot/plugin-manager/src/tools.ts，动作枚举
+ *   list_plugins / list_bundles / set_plugin / set_bundle / install_bundle / remove_bundle）
+ *   是**当前环境**写操作的正确入口；ctx.tools.guard 是官方提供的单调守卫注册点
+ *   （返回 string 即拒绝，没有 allow 结果，所以监听顺序无法把拒绝翻回放行）；
+ *   ctx.systemPrompt.section 是官方提示段注册点。
+ * 前提检查：旧实现引导到它自建的 plugin_install / plugin_uninstall / plugin_toggle
+ *   工具——那些工具在本仓库被**删除**了（用户决定："agent 工具只留 plugin_search +
+ *   健康检查，其余交还官方"）。所以这里的引导目标必须换成官方 plugin_manager；
+ *   引导到一个不存在的工具会让模型反复重试（比不拦更糟）。
+ *
+ * 范围与边界（如实声明，不夸大）：
+ *   - 守卫只作用于**本进程内的 agent 工具调用**（bash / run_code）。用户在终端
+ *     手工执行的裸命令拦不住，也不该拦——那是用户自己的机器。
+ *   - 守卫是单调拒绝：它不能给别的守卫已拒绝的调用"放行"，只能加一道拒绝。
+ *   - 我们自己的 CLI（dshpmc）走的正是官方 runPluginCommand，与官方 plugin_manager
+ *     同一条 pnpm 通道，因此不被拦；DshPmc 自身也不在拦截词表里。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** 一条工具执行的只读视图（结构式；不 import 官方内部类型，避免 peer 版本漂移）。 */
+export interface GuardedExecution {
+    /** 工具名（'bash' / 'run_code' / 其它）。 */
+    readonly name: string;
+    /** 解析后的入参：bash 用 command，run_code 用 code。 */
+    readonly arguments?: unknown;
+}
+/** 官方 CLI 的 plugin 子命令只读动词（显式列出，避免"不在写词表里就算只读"的默认放行）。 */
+export declare const PLUGIN_READ_VERBS: Set<string>;
+/**
+ * 从一条命令段里取出"位置词"：去掉全局 flag 与其取值。
+ *
+ * 两种写法都要处理：--profile web（空格分隔，值是下一个词）与 --profile=web
+ * （内联）。解析器允许全局 flag 出现在任意位置，所以 flag 在子命令之前也要能
+ * 认出子命令——早先只匹配"子命令紧邻"的写法会漏掉 flag-first 的同一个变更。
+ *
+ * 取值槽只在下一个词自己不是子命令 plugin 时才吃掉它，否则 flag-first 的写法
+ * 会把 plugin 当成 --profile 的值丢掉。
+ *
+ * @param segment - 一条命令段（已按 ; | & 换行切开）。
+ * @returns 位置词序列。
+ */
+export declare function positionalWords(segment: string): string[];
+/**
+ * 一条命令段是否用官方 CLI 改了插件状态。
+ *
+ * 形如：dsh [--profile X] plugin <写动词> …（任意 flag 顺序）。只读动词（list /
+ * status / help / dump-config）放行：那不是变更，拦住它只会让模型无法诊断。
+ *
+ * @param segment - 一条命令段。
+ * @returns 是否是官方 CLI 的插件变更。
+ */
+export declare function isDshPluginMutation(segment: string): boolean;
+/**
+ * 一条命令段是否用包管理器改了 DSH 环境里的依赖。
+ *
+ * 两个条件同时成立才算：出现包管理器 + 写动词，且同一段里出现环境目录标记
+ * （profiles/、.dsh、DSH_HOME）。只在项目目录里跑 pnpm add 是正常开发行为，
+ * 拦它属于误伤。
+ *
+ * 动词用词边界判定：npm run install-assets 不是变更（脚本名以 install- 开头），
+ * 早先的 \binstall\b 会把它误判成变更。
+ *
+ * @param segment - 一条命令段。
+ * @returns 是否是对环境目录的包管理器变更。
+ */
+export declare function isProfilePackageMutation(segment: string): boolean;
+/**
+ * 整条命令是否属于被拦的裸变更。
+ *
+ * 逐段判定（; 换行 & | 切开）：只读调用出现在另一段里不能豁免真正的变更，
+ * 环境目录标记出现在另一段里也不能牵连一条无关的包管理器命令。
+ *
+ * @param command - 完整的命令行或 run_code 源码。
+ * @returns 是否应拒绝。
+ */
+export declare function isRawPluginMutation(command: string): boolean;
+/**
+ * 拒绝原因：必须**可直接执行**。
+ *
+ * 只写"不要这么做"会让模型换个说法再试；写清"改用 X 的 Y 动作"才能一次纠正。
+ * 引导目标是官方 plugin_manager 工具（当前环境）与我们自己的 dshpmc CLI
+ * （跨环境 + 质量门 + 技能/预设直装），两者都是官方 pnpm 通道，不是自建写路径。
+ */
+export declare const DENIAL_REASON: string;
+/**
+ * 常驻提示段：在模型尝试裸命令之前就把规则说清楚。
+ *
+ * order 300 落在官方 SECTION_ORDERS 的 PERSONA_PREFIX(0) 与 PLAN_POLICY(500) 之间：
+ * 属于"操作约束"，要排在策略文本之前。旧实现用了同一个位置。
+ */
+export declare const PLUGIN_RULE_SECTION: {
+    name: string;
+    order: number;
+    text: string;
+};
+/**
+ * 创建守卫函数（每次装配一个实例）。
+ * @returns 守卫：命中裸变更时返回拒绝原因，否则 undefined。
+ */
+export declare function createPluginGuard(): (execution: GuardedExecution) => string | undefined;
+/**
+ * 把守卫注册到 tools 服务。
+ *
+ * tools 服务缺失时返回 null 而不是抛错：插件必须能在任何宿主上加载，
+ * 没有工具注册表的宿主里"没有守卫"是事实，由调用方决定要不要记账。
+ *
+ * @param ctx - host 上下文。
+ * @returns 注销函数；tools 服务不可用时 null。
+ */
+export declare function registerPluginGuard(ctx: Context): (() => void) | null;
+/**
+ * 注册常驻提示段。
+ *
+ * @param ctx - host 上下文。
+ * @returns 注销函数；systemPrompt 服务不可用时 null。
+ */
+export declare function registerPluginRulePrompt(ctx: Context): (() => void) | null;
+/**
+ * 同时注册守卫与提示段（装配入口用一次调用表达两件事）。
+ *
+ * @param ctx - host 上下文。
+ * @returns 两个注销函数；服务缺失时对应项为 null。
+ */
+export declare function registerGuard(ctx: Context): {
+    readonly guard: (() => void) | null;
+    readonly prompt: (() => void) | null;
+};

package/dist/guard.js

@@ -0,0 +1,232 @@
+/**
+ * 插件安装守卫：拦住 agent 走"裸命令"改插件状态，并把正确走法写进拒绝原因。
+ *
+ * 归属：A 类·重写（拦 agent 工具调用 + 注册常驻提示段；旧 src/guard.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/guard.ts（194 行：按 shell 段判定、
+ *   positional 词提取处理 --profile X 与 --profile=X 两种写法、npm 变体覆盖、
+ *   动词词边界避免误伤 install-assets 这类脚本名、denial reason 直接给正确命令）。
+ * 官方复用：官方 plugin_manager agent 工具（boot/plugin-manager/src/tools.ts，动作枚举
+ *   list_plugins / list_bundles / set_plugin / set_bundle / install_bundle / remove_bundle）
+ *   是**当前环境**写操作的正确入口；ctx.tools.guard 是官方提供的单调守卫注册点
+ *   （返回 string 即拒绝，没有 allow 结果，所以监听顺序无法把拒绝翻回放行）；
+ *   ctx.systemPrompt.section 是官方提示段注册点。
+ * 前提检查：旧实现引导到它自建的 plugin_install / plugin_uninstall / plugin_toggle
+ *   工具——那些工具在本仓库被**删除**了（用户决定："agent 工具只留 plugin_search +
+ *   健康检查，其余交还官方"）。所以这里的引导目标必须换成官方 plugin_manager；
+ *   引导到一个不存在的工具会让模型反复重试（比不拦更糟）。
+ *
+ * 范围与边界（如实声明，不夸大）：
+ *   - 守卫只作用于**本进程内的 agent 工具调用**（bash / run_code）。用户在终端
+ *     手工执行的裸命令拦不住，也不该拦——那是用户自己的机器。
+ *   - 守卫是单调拒绝：它不能给别的守卫已拒绝的调用"放行"，只能加一道拒绝。
+ *   - 我们自己的 CLI（dshpmc）走的正是官方 runPluginCommand，与官方 plugin_manager
+ *     同一条 pnpm 通道，因此不被拦；DshPmc 自身也不在拦截词表里。
+ */
+/** 官方 CLI 的 plugin 子命令写动词。 */
+const PLUGIN_WRITE_VERBS = new Set(['add', 'install', 'remove', 'rm', 'update', 'upgrade', 'uninstall', 'delete']);
+/** 官方 CLI 的 plugin 子命令只读动词（显式列出，避免"不在写词表里就算只读"的默认放行）。 */
+export const PLUGIN_READ_VERBS = new Set(['list', 'status', 'help', 'dump-config', 'view', 'ls']);
+/** 包管理器变更动词（npm/yarn/bun/pnpm 家族）。 */
+const PM_WRITE_VERBS = new Set(['add', 'install', 'i', 'remove', 'rm', 'uninstall', 'update', 'upgrade', 'link']);
+/** 出现在命令里即视为"目标是 DSH 环境"的标记。 */
+const PROFILE_DIR_MARKER = /profiles[\\/]|\.dsh|DSH_HOME/i;
+/**
+ * 从一条命令段里取出"位置词"：去掉全局 flag 与其取值。
+ *
+ * 两种写法都要处理：--profile web（空格分隔，值是下一个词）与 --profile=web
+ * （内联）。解析器允许全局 flag 出现在任意位置，所以 flag 在子命令之前也要能
+ * 认出子命令——早先只匹配"子命令紧邻"的写法会漏掉 flag-first 的同一个变更。
+ *
+ * 取值槽只在下一个词自己不是子命令 plugin 时才吃掉它，否则 flag-first 的写法
+ * 会把 plugin 当成 --profile 的值丢掉。
+ *
+ * @param segment - 一条命令段（已按 ; | & 换行切开）。
+ * @returns 位置词序列。
+ */
+export function positionalWords(segment) {
+    // 命令行词：shell 标点（引号、括号、反引号、=、逗号）与空白同样分词，
+    // 因此嵌在引号里或 run_code 表达式里的同一个命令仍然能被认出来。
+    const tokens = segment.match(/[A-Za-z0-9_@.\/~-]+/g) ?? [];
+    const out = [];
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.startsWith('-')) {
+            if (token.includes('='))
+                continue;
+            const next = tokens[index + 1];
+            if (next !== undefined && !next.startsWith('-') && next !== 'plugin')
+                index += 1;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+/** 一个位置词是否指 dsh 可执行文件（裸名或任意路径结尾）。 */
+function isDshWord(word) {
+    return word.split('/').pop() === 'dsh';
+}
+/**
+ * 一条命令段是否用官方 CLI 改了插件状态。
+ *
+ * 形如：dsh [--profile X] plugin <写动词> …（任意 flag 顺序）。只读动词（list /
+ * status / help / dump-config）放行：那不是变更，拦住它只会让模型无法诊断。
+ *
+ * @param segment - 一条命令段。
+ * @returns 是否是官方 CLI 的插件变更。
+ */
+export function isDshPluginMutation(segment) {
+    const words = positionalWords(segment);
+    for (let index = 0; index < words.length - 1; index += 1) {
+        if (!isDshWord(words[index]) || words[index + 1] !== 'plugin')
+            continue;
+        const verbs = words.slice(index + 2);
+        if (verbs.some(verb => PLUGIN_WRITE_VERBS.has(verb)))
+            return true;
+        // 只读动词（含无动词的裸 'dsh plugin'）→ 不算变更。
+        if (verbs.some(verb => PLUGIN_READ_VERBS.has(verb)))
+            return false;
+        return false;
+    }
+    return false;
+}
+/**
+ * 一条命令段是否用包管理器改了 DSH 环境里的依赖。
+ *
+ * 两个条件同时成立才算：出现包管理器 + 写动词，且同一段里出现环境目录标记
+ * （profiles/、.dsh、DSH_HOME）。只在项目目录里跑 pnpm add 是正常开发行为，
+ * 拦它属于误伤。
+ *
+ * 动词用词边界判定：npm run install-assets 不是变更（脚本名以 install- 开头），
+ * 早先的 \binstall\b 会把它误判成变更。
+ *
+ * @param segment - 一条命令段。
+ * @returns 是否是对环境目录的包管理器变更。
+ */
+export function isProfilePackageMutation(segment) {
+    if (!/\b(?:pnpm|npm|yarn|bun)\b/.test(segment))
+        return false;
+    if (!PROFILE_DIR_MARKER.test(segment))
+        return false;
+    const words = positionalWords(segment);
+    for (let index = 0; index < words.length; index += 1) {
+        const word = words[index];
+        if (word === 'pnpm' || word === 'npm' || word === 'yarn' || word === 'bun') {
+            const verbs = words.slice(index + 1);
+            if (verbs.some(verb => PM_WRITE_VERBS.has(verb)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 整条命令是否属于被拦的裸变更。
+ *
+ * 逐段判定（; 换行 & | 切开）：只读调用出现在另一段里不能豁免真正的变更，
+ * 环境目录标记出现在另一段里也不能牵连一条无关的包管理器命令。
+ *
+ * @param command - 完整的命令行或 run_code 源码。
+ * @returns 是否应拒绝。
+ */
+export function isRawPluginMutation(command) {
+    for (const segment of command.split(/[;\n&|]+/)) {
+        if (isDshPluginMutation(segment))
+            return true;
+        if (isProfilePackageMutation(segment))
+            return true;
+    }
+    return false;
+}
+/** 从一次工具执行里取出命令行文本；非 bash/run_code 返回 null。 */
+function commandText(execution) {
+    if (execution.name !== 'bash' && execution.name !== 'run_code')
+        return null;
+    const args = execution.arguments;
+    if (typeof args?.command === 'string')
+        return args.command;
+    if (typeof args?.code === 'string')
+        return args.code;
+    return null;
+}
+/**
+ * 拒绝原因：必须**可直接执行**。
+ *
+ * 只写"不要这么做"会让模型换个说法再试；写清"改用 X 的 Y 动作"才能一次纠正。
+ * 引导目标是官方 plugin_manager 工具（当前环境）与我们自己的 dshpmc CLI
+ * （跨环境 + 质量门 + 技能/预设直装），两者都是官方 pnpm 通道，不是自建写路径。
+ */
+export const DENIAL_REASON = 'Blocked: raw plugin mutations bypass the protected flow. Use the plugin_manager tool instead: '
+    + 'plugin_manager { action: "list_plugins" } to find an entry id, then '
+    + 'action: "set_plugin" | "set_bundle" (with target + enabled) to enable/disable, '
+    + 'action: "install_bundle" (target: package spec) to install, or '
+    + 'action: "remove_bundle" (target: package name) to uninstall — those actions require '
+    + 'danger-full-access permission or an approval, and the user must confirm the change. '
+    + 'For a quality-gated install, cross-environment management, or skill/agent-preset installs, '
+    + 'run the companion CLI instead: dshpmc install <spec> --profile <name>, '
+    + 'dshpmc remove <name>, dshpmc update <name>, dshpmc uninstall-kind <owner/repo>. '
+    + 'Do not run bare "dsh plugin add/remove/update" or pnpm add/remove against a profile directory.';
+/**
+ * 常驻提示段：在模型尝试裸命令之前就把规则说清楚。
+ *
+ * order 300 落在官方 SECTION_ORDERS 的 PERSONA_PREFIX(0) 与 PLAN_POLICY(500) 之间：
+ * 属于"操作约束"，要排在策略文本之前。旧实现用了同一个位置。
+ */
+export const PLUGIN_RULE_SECTION = {
+    name: 'plugin-manager-companion:install-rule',
+    order: 300,
+    text: 'To install, remove, enable, disable, or update DSH plugins in the current profile, use the '
+        + 'plugin_manager tool (actions: list_plugins, list_bundles, set_plugin, set_bundle, install_bundle, '
+        + 'remove_bundle). It requires danger-full-access permission or approval. For a quality-gated install, '
+        + 'another profile, or skill / agent-preset installs, use the companion CLI: dshpmc install <spec>, '
+        + 'dshpmc remove <name>, dshpmc update <name>, dshpmc uninstall-kind <owner/repo>. '
+        + 'Never run bare "dsh plugin add/remove" or npm/yarn/bun/pnpm add/remove against a profile directory: '
+        + 'that path skips the quality gate and can leave the profile unable to boot.',
+};
+/**
+ * 创建守卫函数（每次装配一个实例）。
+ * @returns 守卫：命中裸变更时返回拒绝原因，否则 undefined。
+ */
+export function createPluginGuard() {
+    return (execution) => {
+        const command = commandText(execution);
+        if (command === null)
+            return undefined;
+        return isRawPluginMutation(command) ? DENIAL_REASON : undefined;
+    };
+}
+/**
+ * 把守卫注册到 tools 服务。
+ *
+ * tools 服务缺失时返回 null 而不是抛错：插件必须能在任何宿主上加载，
+ * 没有工具注册表的宿主里"没有守卫"是事实，由调用方决定要不要记账。
+ *
+ * @param ctx - host 上下文。
+ * @returns 注销函数；tools 服务不可用时 null。
+ */
+export function registerPluginGuard(ctx) {
+    const tools = ctx.get('tools');
+    if (tools === undefined || typeof tools.guard !== 'function')
+        return null;
+    return tools.guard(createPluginGuard());
+}
+/**
+ * 注册常驻提示段。
+ *
+ * @param ctx - host 上下文。
+ * @returns 注销函数；systemPrompt 服务不可用时 null。
+ */
+export function registerPluginRulePrompt(ctx) {
+    const systemPrompt = ctx.get('systemPrompt');
+    if (systemPrompt === undefined || typeof systemPrompt.section !== 'function')
+        return null;
+    return systemPrompt.section({ ...PLUGIN_RULE_SECTION });
+}
+/**
+ * 同时注册守卫与提示段（装配入口用一次调用表达两件事）。
+ *
+ * @param ctx - host 上下文。
+ * @returns 两个注销函数；服务缺失时对应项为 null。
+ */
+export function registerGuard(ctx) {
+    return { guard: registerPluginGuard(ctx), prompt: registerPluginRulePrompt(ctx) };
+}