@minidoll/agentkit-dsh-plugin 0.0.0-stage → 0.1.0

package/dist/inject.d.ts

@@ -0,0 +1,74 @@
+/** 注入内容的硬上限（字节）。超过就截断 —— 注入不是"越多越好"。 */
+export declare const MAX_CONTEXT_BYTES = 900;
+/** 内容块（照抄 `dsh-llm` 的 TextBlock）。 */
+interface TextBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * 构造一条合法的 UserMessage。
+ *
+ * `createUserMessage` 拿得到就用它（id 由官方生成，最保险）；
+ * 拿不到时**照抄契约**手工构造 —— 形状必须与 `dsh-llm` 的
+ * `MessageBase`/`UserMessage`/`TextBlock` 完全一致。
+ */
+export interface UserMessageLike {
+    role: 'user';
+    id: string;
+    content: TextBlock[];
+    source: {
+        kind: 'user';
+    };
+}
+/**
+ * 断言"这真的是一个可以被宿主接受的 UserMessage"。
+ *
+ * 事故就是没做这一步。断言失败 → 调用方**不注入**（不是抛给宿主）。
+ */
+export declare function assertUserMessage(value: unknown): value is UserMessageLike;
+/** 项目级注入开关文件（跟随仓库走，不需要每次设环境变量）。 */
+export declare const INJECT_CONFIG_REL = ".agent/inject.json";
+/**
+ * 这次调用是否该注入（**默认关**）。
+ *
+ * 两级开关，任一为真即开：
+ * 1. `.agent/inject.json` 的 `{"enabled": true}` —— 项目自己决定（推荐）
+ * 2. `AGENTKIT_CONTEXT_INJECT=1` —— 环境变量（临时试验用）
+ *
+ * 默认关的理由：这是 2026-10-25 事故区，未经真实会话验证的注入不默认生效。
+ */
+export declare function injectEnabled(root?: string): boolean;
+/** 诊断：注入成功/失败/跳过都留痕（排在插件 trace 里）。 */
+export interface InjectionTrace {
+    (line: string): void;
+}
+export interface BuildHintInput {
+    /** 工作区根（已由根解析确定）。 */
+    root: string;
+    /** 本次动作涉及的文件（workspace 相对或绝对）。 */
+    filePath?: string;
+    /** 本次动作涉及的其它候选路径（用于从命令里提取的项目内文件）。 */
+    extraPaths?: readonly string[];
+}
+/** 生成注入文本；没有可注入内容时返回 null（**不注入空内容**）。 */
+export declare function buildInjectText(input: BuildHintInput): string | null;
+export interface InjectResult {
+    ok: boolean;
+    /** 为什么没注入（ok=false 时给出原因，便于诊断）。 */
+    reason?: string;
+    /** 构造好的 UserMessage[]（ok=true 时非空）——直接放进 additionalContexts。 */
+    messages?: UserMessageLike[];
+}
+/**
+ * 构造要放进 `PostToolDecision.additionalContexts` 的数组。
+ *
+ * **这是唯一对外入口** —— 所有校验、工厂/兜底选择、上限都在这里收口。
+ */
+export declare function buildAdditionalContexts(input: {
+    root: string;
+    filePath?: string;
+    extraPaths?: readonly string[];
+    sessionId?: string | null;
+    trace?: InjectionTrace;
+}): Promise<InjectResult>;
+export {};

package/dist/inject.js

@@ -0,0 +1,248 @@
+/**
+ * DSH 侧"按需上下文"注入（2026-10-30，见 docs/design/0016）。
+ *
+ * ## 事故教训（2026-10-25，4 个会话损坏）
+ *
+ * 往 `additionalContexts` 塞了**裸字符串**，而它的真实类型是 `UserMessage[]`：
+ *
+ *   interface MessageBase { id; content: ContentBlock[]; source: MessageSource }
+ *   interface UserMessage extends MessageBase { role: 'user' }
+ *   TextBlock = { type: 'text'; text: string }
+ *
+ * 宿主读 `message.id` / `message.kind` 时直接炸。**不是"注入危险"，是"形状错"。**
+ *
+ * ## 三条防线（缺一不可）
+ *
+ * 1. **优先用官方工厂**：`createUserMessage({content, source})`（`@deepseek-ai/dsh-llm`）
+ *    —— 但实测 profile 与全局 node_modules 都解析不到它（pnpm 传递依赖），
+ *    所以工厂拿不到时用**照抄契约的手工构造**（不是重写状态机，是复制 5 行）。
+ * 2. **注入前断言**：`role/content/source/id` 逐项检查；不合法就**不注入**。
+ * 3. **失败降级**：整个包 try/catch，任何异常都返回"不注入"，绝不打断工具调用。
+ *
+ * ## 内容纪律
+ *
+ * - 上限 900B（超了截断并标记）—— 注入即污染，这条比"多给点信息"重要
+ * - 同 session+文件只注入一次（否则每次编辑都刷同一段话）
+ * - 默认**关**（`AGENTKIT_CONTEXT_INJECT=1` 才开）：未经真实会话验证的注入不默认生效
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** 注入内容的硬上限（字节）。超过就截断 —— 注入不是"越多越好"。 */
+export const MAX_CONTEXT_BYTES = 900;
+/** 尝试加载官方工厂（结果缓存；拿不到就是 null，不重试）。 */
+let factoryLoader = null;
+async function loadFactory() {
+    factoryLoader ??= (async () => {
+        try {
+            // 用变量形式 import：tsc 不静态解析（该包在 profile 里不可达，
+            // 解析失败由 catch 兜住 → 退回手工构造）
+            const pkg = '@deepseek-ai/dsh-llm';
+            const mod = (await import(pkg));
+            return typeof mod.createUserMessage === 'function' ? mod.createUserMessage : null;
+        }
+        catch {
+            // 解析不到（pnpm 传递依赖/无依赖）→ 走手工兜底，**不让插件因此崩**
+            return null;
+        }
+    })();
+    return factoryLoader;
+}
+/** 手工构造（照抄契约）。只在这一处实现，便于审计。 */
+function handcraft(text) {
+    return {
+        role: 'user',
+        id: randomUUID(),
+        content: [{ type: 'text', text }],
+        source: { kind: 'user' },
+    };
+}
+/**
+ * 断言"这真的是一个可以被宿主接受的 UserMessage"。
+ *
+ * 事故就是没做这一步。断言失败 → 调用方**不注入**（不是抛给宿主）。
+ */
+export function assertUserMessage(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    if (m.role !== 'user')
+        return false;
+    if (typeof m.id !== 'string' || m.id === '')
+        return false;
+    const src = m.source;
+    if (src === undefined || src.kind !== 'user')
+        return false;
+    const content = m.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return false;
+    return content.every((b) => {
+        const blk = b;
+        return blk.type === 'text' && typeof blk.text === 'string' && blk.text.length > 0;
+    });
+}
+/** 项目级注入开关文件（跟随仓库走，不需要每次设环境变量）。 */
+export const INJECT_CONFIG_REL = '.agent/inject.json';
+/**
+ * 这次调用是否该注入（**默认关**）。
+ *
+ * 两级开关，任一为真即开：
+ * 1. `.agent/inject.json` 的 `{"enabled": true}` —— 项目自己决定（推荐）
+ * 2. `AGENTKIT_CONTEXT_INJECT=1` —— 环境变量（临时试验用）
+ *
+ * 默认关的理由：这是 2026-10-25 事故区，未经真实会话验证的注入不默认生效。
+ */
+export function injectEnabled(root) {
+    if (process.env.AGENTKIT_CONTEXT_INJECT === '1')
+        return true;
+    if (root === undefined || root === '')
+        return false;
+    try {
+        const f = join(root, INJECT_CONFIG_REL);
+        if (!existsSync(f))
+            return false;
+        const doc = JSON.parse(readFileSync(f, 'utf8'));
+        return doc.enabled === true;
+    }
+    catch {
+        // 配置坏了 = 不开（宁可少注入，不可乱注入）
+        return false;
+    }
+}
+/** 同一 session+文件只注入一次。 */
+const injected = new Set();
+/**
+ * 生成"按需上下文"文本（与 OpenCode 侧同一套规则，保持跨客户端一致）。
+ *
+ * 注意：这里**不依赖 @agentkit/core**（插件是独立发布物），规则表内联。
+ */
+const PATH_RULES = [
+    { pattern: /^contracts\//, hint: '契约变更：实现必须同步（AGENTS 铁律），并在交接单声明契约影响与证据级别 L1-L4' },
+    { pattern: /^docs\/rules\//, hint: '规则文档：改它等于改所有人的行为约束 —— 先确认与 protocol.yml / AGENTS.md 不冲突' },
+    { pattern: /^docs\/design\//, hint: '设计文档：需与 codemap 里的模块对应（M4 会校验"文档提到该模块"）' },
+    { pattern: /^\.agent\/decisions\/\d{4}-/, hint: 'ADR：accepted 的有约束力 —— 要推翻先写新 ADR 标 superseded，不要直接改旧结论' },
+    { pattern: /^AGENTS\.md$/, hint: 'AGENTS.md 是派生文件（由 protocol.yml 生成）—— 改它请改 protocol.yml 再 akit sync' },
+];
+/** 生成注入文本；没有可注入内容时返回 null（**不注入空内容**）。 */
+export function buildInjectText(input) {
+    const lines = [];
+    const rels = [];
+    if (input.filePath !== undefined && input.filePath !== '')
+        rels.push(input.filePath);
+    for (const p of input.extraPaths ?? [])
+        if (p !== '')
+            rels.push(p);
+    // 1) 路径规则（取第一条命中的，避免叠加成噪音）
+    for (const raw of rels) {
+        const rel = String(raw).replace(/\\/g, '/').replace(/^\.\//, '');
+        for (const rule of PATH_RULES) {
+            if (rule.pattern.test(rel)) {
+                lines.push(`- 纪律：${rule.hint}`);
+                break;
+            }
+        }
+        if (lines.length > 0)
+            break;
+    }
+    // 2) codemap：模块职责 + 设计文档
+    for (const raw of rels) {
+        const rel = String(raw).replace(/\\/g, '/').replace(/^\.\//, '');
+        try {
+            const cm = join(input.root, '.agent', 'codemap.json');
+            if (!existsSync(cm))
+                break;
+            const map = JSON.parse(readFileSync(cm, 'utf8'));
+            const mod = (map.modules ?? []).find((m) => String(m.path ?? '').replace(/^\.\//, '') === rel);
+            if (mod !== undefined) {
+                if (mod.purpose !== undefined && mod.purpose !== '')
+                    lines.push(`- 模块职责（codemap）：${mod.purpose}`);
+                if (mod.doc !== undefined && mod.doc !== '')
+                    lines.push(`- 设计文档：${mod.doc}`);
+                break;
+            }
+        }
+        catch {
+            /* codemap 读不出 ⇒ 不注入这部分 */
+        }
+    }
+    // 3) ADR：正文提到该文件主干的，只给标题与状态
+    for (const raw of rels) {
+        if (lines.length >= 4)
+            break;
+        const rel = String(raw).replace(/\\/g, '/');
+        const stem = rel.split('/').pop()?.replace(/\.(ts|mjs|java|kt|py|go|md)$/, '') ?? '';
+        if (stem.length < 3)
+            continue;
+        try {
+            const dir = join(input.root, '.agent', 'decisions');
+            if (!existsSync(dir))
+                continue;
+            for (const name of readdirSync(dir).sort()) {
+                if (!/^\d{4}-.*\.md$/.test(name))
+                    continue;
+                const body = readFileSync(join(dir, name), 'utf8');
+                if (!body.includes(stem) && !body.includes(rel))
+                    continue;
+                const title = /^#\s+(.+)$/m.exec(body)?.[1] ?? name;
+                const status = /-?\s*\*\*状态\*\*[:：]\s*(.+)/.exec(body)?.[1] ?? '';
+                lines.push(`- 相关决策：${name.replace(/\.md$/, '')} ${title}${status ? `（${status}）` : ''}`);
+                if (lines.length >= 4)
+                    break;
+            }
+        }
+        catch {
+            /* 读不出 ⇒ 不注入 */
+        }
+    }
+    if (lines.length === 0)
+        return null;
+    let text = ['<!-- agentkit: 按需上下文（只读，来自 codemap/ADR） -->', ...lines].join('\n');
+    if (text.length > MAX_CONTEXT_BYTES)
+        text = `${text.slice(0, MAX_CONTEXT_BYTES - 20)}\n…（已截断）`;
+    return text;
+}
+/**
+ * 构造要放进 `PostToolDecision.additionalContexts` 的数组。
+ *
+ * **这是唯一对外入口** —— 所有校验、工厂/兜底选择、上限都在这里收口。
+ */
+export async function buildAdditionalContexts(input) {
+    try {
+        if (!injectEnabled(input.root)) {
+            // 2026-10-30：**没做也要出声** —— 否则"开关关着"与"根本没走到这里"在日志上无法区分
+            input.trace?.('inject skipped: disabled (no .agent/inject.json / env)');
+            return { ok: false, reason: 'inject disabled (no .agent/inject.json / env)' };
+        }
+        const key = `${input.sessionId ?? ''}|${input.filePath ?? ''}`;
+        if (injected.has(key)) {
+            input.trace?.('inject skipped: already injected for this session+file');
+            return { ok: false, reason: 'already injected for this session+file' };
+        }
+        const text = buildInjectText({
+            root: input.root,
+            ...(input.filePath !== undefined ? { filePath: input.filePath } : {}),
+            ...(input.extraPaths !== undefined ? { extraPaths: input.extraPaths } : {}),
+        });
+        if (text === null) {
+            input.trace?.('inject skipped: nothing to inject for this path');
+            return { ok: false, reason: 'nothing to inject for this path' };
+        }
+        const factory = await loadFactory();
+        const msg = factory !== null
+            ? factory({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+            : handcraft(text);
+        if (!assertUserMessage(msg)) {
+            // 形状不合法 ⇒ **不注入**（而不是把坏形状交给宿主，那正是事故）
+            input.trace?.(`inject rejected: shape check failed (${factory !== null ? 'factory' : 'handcraft'})`);
+            return { ok: false, reason: 'shape check failed' };
+        }
+        injected.add(key);
+        input.trace?.(`inject ok: ${String(text.length)}B via ${factory !== null ? 'factory' : 'handcraft'}`);
+        return { ok: true, messages: [msg] };
+    }
+    catch (err) {
+        // 第三条防线：任何异常都不影响工具调用
+        input.trace?.(`inject skipped: ${err.message}`);
+        return { ok: false, reason: err.message };
+    }
+}

package/dist/install.d.ts

@@ -0,0 +1,81 @@
+export declare const ROW_ID = "project-hooks";
+export declare const ROW_NAME = "@minidoll/agentkit-dsh-plugin";
+export declare const STATE_DIR = ".agentkit-landing";
+export interface LandingPaths {
+    home: string;
+    profile: string;
+    patch: string;
+    stateDir: string;
+}
+export declare function landingPaths(home: string, profile: string): LandingPaths;
+export interface InstallOptions {
+    home: string;
+    profile: string;
+    /** 配置文件绝对路径（可选）：不传则插件用默认（项目内发现）。 */
+    configFile?: string;
+}
+/**
+ * 把插件**包本身**装进 profile（T-008 完整路径的第 1–2 步）：
+ *   1. 在 profile 目录执行 `pnpm add <tarball|spec>` —— 代码落到
+ *      <profile>/node_modules（DSH loader 就是从那里加载 bundle 的）
+ *   2. 把包名加进 package.json 的 `dsh.profile.bundles`（顺序在末尾追加）
+ *
+ * 第 3 步（写 patch 行）由 bundle 自带的 cordis.patch.yml 完成 —— 它的
+ * package.json 声明了 `dsh.bundle.patch`。只有需要 configFile 覆盖时我们才
+ * 额外写一行（避免重复条目）。
+ */
+export interface BundleInstallOptions {
+    home: string;
+    profile: string;
+    /** tarball 路径或 npm 规格。 */
+    from: string;
+    /** 测试用：跳过真实 pnpm（只验证 package.json 与 patch 的文件效果）。 */
+    skipPackageManager?: boolean;
+}
+export interface BundleInstallResult {
+    ok: boolean;
+    added: boolean;
+    alreadyInstalled: boolean;
+    error?: string;
+}
+export interface InstallResult {
+    ok: boolean;
+    changed: boolean;
+    path: string;
+    backup?: string;
+    reason?: string;
+}
+export declare function install(opts: InstallOptions): InstallResult;
+export declare function rollback(opts: {
+    home: string;
+    profile: string;
+}): InstallResult;
+export interface StatusResult {
+    ok: boolean;
+    installed: boolean;
+    path: string;
+    backups: string[];
+    configFile?: string;
+}
+export declare function status(opts: {
+    home: string;
+    profile: string;
+}): StatusResult;
+/** 第 1–2 步：装包 + 登记 bundle。幂等（已装则跳过）。 */
+export declare function installBundle(opts: BundleInstallOptions): BundleInstallResult;
+/**
+ * 完整回滚：撤 patch 条目 **+** 撤 bundle 注册（deps/bundles）+ 卸包。
+ *
+ * 教训（0.0.2 事故）：只恢复 patch 文件是不够的 —— bundle 仍在
+ * dsh.profile.bundles 里，重启后照样被组合。撤销必须覆盖**注册面**。
+ */
+export declare function rollbackBundle(opts: {
+    home: string;
+    profile: string;
+    skipPackageManager?: boolean;
+}): {
+    ok: boolean;
+    removed: boolean;
+    patchRollback: InstallResult;
+    error?: string;
+};

package/dist/install.js

@@ -0,0 +1,213 @@
+/**
+ * DSH 宿主侧的落地（install / rollback / status）。
+ *
+ * 这是 client-landing 分工里归本层的那部分：**宿主改动是显式部署动作**
+ * （agentkit RFC-004 §7.8：项目侧自包含，宿主侧可审计、可撤销）。
+ *
+ * 设计约束（与 agentkit 自己的 install 同源）：
+ *  - **幂等**：已有我们的条目就不再插（重复安装不该产生重复配置）
+ *  - **备份**：写入前把原文件复制到 .agentkit-landing/backup-<ts>.yml
+ *  - **可回滚**：rollback 恢复最近一次备份（或指定的）
+ *  - **审计**：每次动作写一条 JSON 到 .agentkit-landing/ledger.jsonl
+ *  - **不吞别人的配置**：只追加我们这一行，不改写既有条目
+ */
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const ROW_ID = 'project-hooks';
+export const ROW_NAME = '@minidoll/agentkit-dsh-plugin';
+export const STATE_DIR = '.agentkit-landing';
+export function landingPaths(home, profile) {
+    const patch = join(home, 'profiles', profile, 'cordis.patch.yml');
+    return { home, profile, patch, stateDir: join(home, 'profiles', profile, STATE_DIR) };
+}
+function rowPresent(patchText) {
+    // 简单而稳:按我们自己的 id 与 name 判断
+    return patchText.includes(`id: ${ROW_ID}`) || patchText.includes(ROW_NAME);
+}
+function renderRow(configFile) {
+    const lines = [`- id: ${ROW_ID}`, `  name: ${ROW_NAME}`];
+    if (configFile !== undefined) {
+        lines.push('  config:', `    configFile: ${configFile}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function audit(paths, action, detail) {
+    mkdirSync(paths.stateDir, { recursive: true });
+    const rec = { at: new Date().toISOString(), action, profile: paths.profile, ...detail };
+    appendFileSync(join(paths.stateDir, 'ledger.jsonl'), `${JSON.stringify(rec)}\n`, 'utf8');
+}
+export function install(opts) {
+    const paths = landingPaths(opts.home, opts.profile);
+    if (!existsSync(join(opts.home, 'profiles', opts.profile))) {
+        return { ok: false, changed: false, path: paths.patch, reason: `profile not found: ${opts.home}/profiles/${opts.profile}` };
+    }
+    if (!existsSync(paths.patch)) {
+        // 没有 patch 文件就创建 —— 它是 profile 的用户层，允许为空后追加
+        mkdirSync(paths.stateDir, { recursive: true });
+        writeFileSync(paths.patch, `${renderRow(opts.configFile)}`, 'utf8');
+        audit(paths, 'install', { backup: null, configFile: opts.configFile ?? null, created: true });
+        return { ok: true, changed: true, path: paths.patch, reason: 'created' };
+    }
+    const before = readFileSync(paths.patch, 'utf8');
+    if (rowPresent(before)) {
+        audit(paths, 'install-noop', { reason: 'already present' });
+        return { ok: true, changed: false, path: paths.patch, reason: 'already present' };
+    }
+    mkdirSync(paths.stateDir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backup = join(paths.stateDir, `backup-${stamp}.yml`);
+    copyFileSync(paths.patch, backup);
+    // 只**追加**我们的行,不改写既有条目(别人的 patch 不该被我们动)
+    const next = before.endsWith('\n') || before === '' ? `${before}${renderRow(opts.configFile)}` : `${before}\n${renderRow(opts.configFile)}`;
+    writeFileSync(paths.patch, next, 'utf8');
+    audit(paths, 'install', { backup, configFile: opts.configFile ?? null });
+    return { ok: true, changed: true, path: paths.patch, backup };
+}
+export function rollback(opts) {
+    const paths = landingPaths(opts.home, opts.profile);
+    if (!existsSync(paths.stateDir)) {
+        return { ok: false, changed: false, path: paths.patch, reason: 'no state directory — nothing to roll back' };
+    }
+    const backups = readdirSync(paths.stateDir)
+        .filter((f) => f.startsWith('backup-') && f.endsWith('.yml'))
+        .sort();
+    const last = backups.at(-1);
+    if (last === undefined) {
+        return { ok: false, changed: false, path: paths.patch, reason: 'no backup recorded' };
+    }
+    copyFileSync(join(paths.stateDir, last), paths.patch);
+    audit(paths, 'rollback', { restoredFrom: last });
+    return { ok: true, changed: true, path: paths.patch, backup: join(paths.stateDir, last) };
+}
+export function status(opts) {
+    const paths = landingPaths(opts.home, opts.profile);
+    if (!existsSync(paths.patch)) {
+        return { ok: true, installed: false, path: paths.patch, backups: [] };
+    }
+    const text = readFileSync(paths.patch, 'utf8');
+    const m = new RegExp(`configFile:\\s*(\\S+)`).exec(text);
+    const backups = existsSync(paths.stateDir)
+        ? readdirSync(paths.stateDir).filter((f) => f.startsWith('backup-')).sort()
+        : [];
+    return { ok: true, installed: rowPresent(text), path: paths.patch, backups, ...(m?.[1] !== undefined ? { configFile: m[1] } : {}) };
+}
+function readProfileJson(home, profile) {
+    const p = join(home, 'profiles', profile, 'package.json');
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** 第 1–2 步：装包 + 登记 bundle。幂等（已装则跳过）。 */
+export function installBundle(opts) {
+    const profileDir = join(opts.home, 'profiles', opts.profile);
+    if (!existsSync(join(opts.home, 'profiles', opts.profile))) {
+        return { ok: false, added: false, alreadyInstalled: false, error: `profile not found: ${profileDir}` };
+    }
+    const pkg = readProfileJson(opts.home, opts.profile);
+    if (pkg === null)
+        return { ok: false, added: false, alreadyInstalled: false, error: `cannot read ${join(profileDir, 'package.json')}` };
+    const deps = (pkg.dependencies ?? {});
+    const dsh = (pkg.dsh ?? {});
+    const bundles = dsh.profile?.bundles ?? [];
+    const installed = Object.keys(deps).some((k) => k === ROW_NAME) || bundles.includes(ROW_NAME);
+    if (installed)
+        return { ok: true, added: false, alreadyInstalled: true };
+    if (opts.skipPackageManager !== true) {
+        // 1. 真装：代码必须落到 node_modules,loader 才加载得到。
+        // pnpm 不一定是全局命令(常见于 nvm/pnpm 独立安装),按候选路径解析;
+        // 解析不到要给**可操作**的错误,而不是空 stderr。
+        const pm = resolvePnpm();
+        if (pm === null) {
+            return {
+                ok: false,
+                added: false,
+                alreadyInstalled: false,
+                error: 'pnpm not found (tried PATH, ~/.local/share/pnpm/pnpm, npx). ' +
+                    'Install pnpm, or rerun with --skip-pnpm and install the package into the profile by hand.',
+            };
+        }
+        const r = spawnSync(pm, ['add', opts.from], { cwd: profileDir, encoding: 'utf8', timeout: 180_000 });
+        if (r.status !== 0) {
+            const detail = [r.error?.message, r.stdout, r.stderr].filter((x) => typeof x === 'string').join('\n').trim();
+            return { ok: false, added: false, alreadyInstalled: false, error: `${pm} add failed (exit ${String(r.status)})\n${detail.slice(-600)}` };
+        }
+    }
+    // 2. 登记 bundle（顺序追加,与 plugin-manager 的行为一致）
+    const next = {
+        ...pkg,
+        dependencies: { ...deps, [ROW_NAME]: opts.skipPackageManager === true ? 'file:.' : opts.from },
+        dsh: { ...dsh, profile: { ...(dsh.profile ?? {}), bundles: [...bundles, ROW_NAME] } },
+    };
+    writeFileSync(join(profileDir, 'package.json'), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    audit(landingPaths(opts.home, opts.profile), 'install-bundle', { from: opts.from });
+    return { ok: true, added: true, alreadyInstalled: false };
+}
+/** pnpm 的可用路径：先 PATH，再常见的独立安装位置，再 npx。 */
+function resolvePnpm() {
+    const candidates = ['pnpm', join(homedirPath(), '.local/share/pnpm/pnpm')];
+    for (const c of candidates) {
+        const probe = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 15_000 });
+        if (probe.status === 0)
+            return c;
+    }
+    const viaNpx = spawnSync('npx', ['--no-install', 'pnpm', '--version'], { encoding: 'utf8', timeout: 20_000 });
+    if (viaNpx.status === 0)
+        return 'npx pnpm';
+    return null;
+}
+function homedirPath() {
+    try {
+        return homedir();
+    }
+    catch {
+        return process.env.HOME ?? '';
+    }
+}
+/**
+ * 完整回滚：撤 patch 条目 **+** 撤 bundle 注册（deps/bundles）+ 卸包。
+ *
+ * 教训（0.0.2 事故）：只恢复 patch 文件是不够的 —— bundle 仍在
+ * dsh.profile.bundles 里，重启后照样被组合。撤销必须覆盖**注册面**。
+ */
+export function rollbackBundle(opts) {
+    const patchRollback = rollback({ home: opts.home, profile: opts.profile });
+    const profileDir = join(opts.home, 'profiles', opts.profile);
+    const pkg = readProfileJson(opts.home, opts.profile);
+    if (pkg === null) {
+        return { ok: false, removed: false, patchRollback, error: `cannot read ${join(profileDir, 'package.json')}` };
+    }
+    const deps = (pkg.dependencies ?? {});
+    const dsh = (pkg.dsh ?? {});
+    const bundles = dsh.profile?.bundles ?? [];
+    const had = ROW_NAME in deps || bundles.includes(ROW_NAME);
+    if (!had) {
+        audit(landingPaths(opts.home, opts.profile), 'rollback-bundle-noop', { reason: 'not registered' });
+        return { ok: true, removed: false, patchRollback };
+    }
+    const nextDeps = { ...deps };
+    delete nextDeps[ROW_NAME];
+    const nextBundles = bundles.filter((b) => b !== ROW_NAME);
+    const next = { ...pkg, dependencies: nextDeps, dsh: { ...dsh, profile: { ...(dsh.profile ?? {}), bundles: nextBundles } } };
+    writeFileSync(join(profileDir, 'package.json'), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    if (opts.skipPackageManager !== true) {
+        const pm = resolvePnpm();
+        if (pm !== null) {
+            const r = spawnSync(pm, ['remove', ROW_NAME], { cwd: profileDir, encoding: 'utf8', timeout: 180_000 });
+            if (r.status !== 0) {
+                // 注册已撤,包没卸掉 —— 如实报出,不假装成功
+                const detail = [r.stdout, r.stderr].filter((x) => typeof x === 'string').join('\n').trim();
+                audit(landingPaths(opts.home, opts.profile), 'rollback-bundle-partial', { detail: detail.slice(-300) });
+                return { ok: false, removed: false, patchRollback, error: `package removal failed: ${detail.slice(-300)}` };
+            }
+        }
+    }
+    audit(landingPaths(opts.home, opts.profile), 'rollback-bundle', {});
+    return { ok: true, removed: true, patchRollback };
+}

package/dist/payload.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 钩子 payload 构造（纯函数）。
+ *
+ * 字段以 `dsh-plugin-hooks/lib/config.js` 的 buildPayload 为实证依据（它读的是
+ * DSH 自己的词汇表）；本项目与它的差异只在**配置发现位置**（项目内 vs 宿主）。
+ */
+export interface HookPayload {
+    event: string;
+    hookId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    sessionId: string | null;
+    cwd: string | null;
+}
+export declare function buildPayload(input: Omit<HookPayload, 'cwd'> & {
+    cwd?: string | null;
+}): HookPayload;
+/** payload 走 stdin：一行 JSON + 换行（与 DSH shell 服务的词汇表一致）。 */
+export declare function payloadStdin(payload: HookPayload): string;
+/**
+ * 环境变量。
+ *
+ * **必须显式带上 PATH**：harness 的执行器给命令的是**干净环境** ——
+ * `env: { ...ENV_OVERRIDES, ...spec.env, ...spec.dshEnv }`，**没有 process.env**。
+ * 于是 `node .agent/generated/dsh-hook-bridge.mjs Gx` 在里面找不到 node，
+ * 命令静默失败、不写台账 —— 这正是"真实 seam 有痕迹但台账不动"的根因
+ * （我自己的探针能跑通，是因为探针进程有 PATH）。
+ */
+export declare function hookEnv(cwd: string, hookId: string, sessionId: string | null): Record<string, string>;
+/**
+ * 找到能跑 `node` 的目录。
+ *
+ * `process.execPath` 在插件跑在 Node 里时就是 node 本身；但 DSH 桌面端
+ * 可能把它跑在 Electron 宿主里（execPath 是 dsh-desktop）—— 那样要另外探测。
+ * 顺序：execPath 目录（若含 node）→ PATH 里第一个含 node 的目录 → 常见安装位置。
+ */
+export declare function nodeBinDir(): string | null;