dingtalk-dws-mcp 1.0.1 → 1.1.0

package/README.md

@@ -2,20 +2,32 @@
 
 源码包。用户能力与接入见 [`mcp/dingtalk-dws-mcp/GUIDE.md`](../../../mcp/dingtalk-dws-mcp/GUIDE.md)。
 
-Agent：`instructions` / tool `description` / `prompts`。长期巡检：`dingtalk_patrol_setup` 备料 → 传装到主机 → 停。
+Agent：`instructions` / tool `description` / `prompts` / **Resources（`guides/*.md`）**。长期巡检：`dingtalk_patrol_setup` 备料 → 传装到主机 → 停。
+
+本目录为唯一工程根：
+
+```text
+packages/mcp/dingtalk-dws-mcp/
+  src/                 # MCP server（含 patrol-setup；build 时从 lib 同步 notify-delivery）
+  lib/notify-delivery/ # L0 投递（仓内唯一源；不单独发 npm）
+  host-patrol/         # 主机巡检 CLI 源码（pack:deploy 用；不进 MCP npm tarball）
+  guides/              # MCP Resources
+```
+
+部署产物仍使用 `deploy/linux-x64/runtime/patrol/`（与 `install.sh` 路径约定一致）；勿与源码目录 `host-patrol/`、`src/patrol-setup/` 混淆。
 
 ## 构建
 
 ```bash
-cd packages/lib/notify-delivery && npm install && npm run build
-cd ../../mcp/dingtalk-dws-mcp && npm install && npm run build
-npm run pack:deploy
+cd packages/mcp/dingtalk-dws-mcp
+npm install && npm run build
+npm run pack:deploy   # 可选：生成 deploy/linux-x64 巡检包（仅 monorepo）
 ```
 
-`pack:deploy` 生成 `deploy/linux-x64/`（瘦身 patrol + 默认便携 Node `bin/node`，禁 devDeps）。  
-可选：`DINGTALK_PATROL_INCLUDE_NODE=0`、`DINGTALK_PATROL_NODE_URL`、`DINGTALK_PATROL_INCLUDE_DWS=0`（默认尝试打入 linux ELF dws；Windows 打包机需 `DINGTALK_PATROL_DWS_PATH` 指向 ELF）。  
-`dingtalk_patrol_setup` 只写 staging（含本机已验证投递凭据）；传装用 host-execution 或 SSH，目标机跑 `install.sh`。可选 `deploy.sh` 为直连 SSH helper。  
+`npm publish` 的 `files` 仅含 `dist/src` + `guides` + README/LICENSE；**不会**把 `host-patrol/`、`lib/`、`deploy/` 打进 registry。
+
+`pack:deploy` **仅 monorepo**（需要 `host-patrol/`、`lib/`、`scripts/`）。npx/registry 没有这些目录；`patrol_bundle.available=false` 属预期。默认不打便携 Node；空气间隙设 `DINGTALK_PATROL_INCLUDE_NODE=1`。可选 `DINGTALK_PATROL_NODE_URL`、`DINGTALK_PATROL_INCLUDE_DWS=0`。Windows 可从 `dingtalk-workspace-cli` 抽出 linux ELF `dws`（或设 `DINGTALK_PATROL_DWS_PATH`）。传装跟 `copy_plan`；可选 `deploy.sh` 为直连 SSH helper。  
 
-配置示例（npx）：[`mcp/dingtalk-dws-mcp/mcp.example.json`](../../../mcp/dingtalk-dws-mcp/mcp.example.json)。npm：`dingtalk-dws-mcp@1.0.0`。
+配置示例（npx）：[`mcp/dingtalk-dws-mcp/mcp.example.json`](../../../mcp/dingtalk-dws-mcp/mcp.example.json)。npm：`dingtalk-dws-mcp@1.1.0`。
 
 规格（开发者）：[RFC-0007](../../../docs/rfc/RFC-0007-dingtalk-dws-mcp.md)、[RFC-0008](../../../docs/rfc/RFC-0008-dingtalk-notify-patrol.md)。

package/dist/src/notify/bind.d.ts

@@ -1,7 +1,22 @@
 import type { AppConfig, RouteName, RouteType, TargetCandidate } from "../types.js";
+/** Persisted bind record. Both fields required. */
+export type BoundTarget = {
+    id: string;
+    name: string;
+};
+/** Unified route view for doctor / list_routes / send. Bound iff name != null. */
+export type RouteBindingView = {
+    name: string | null;
+    id: string | null;
+};
 export declare function candidateRef(candidate: TargetCandidate): string;
-export declare function readTargets(config: AppConfig): Record<string, string>;
-export declare function writeTarget(config: AppConfig, route: RouteName, targetId: string): void;
+/** Read valid bindings only. Bare strings / partial objects are invalid → omitted (unbound). No migration. */
+export declare function readBoundTargets(config: AppConfig): Partial<Record<RouteName, BoundTarget>>;
+export declare function readBoundTarget(config: AppConfig, route: RouteName): BoundTarget | null;
+export declare function writeTarget(config: AppConfig, route: RouteName, target: BoundTarget): void;
 export declare function resolveRouteTarget(config: AppConfig, route: RouteName): string;
+export declare function describeRouteBinding(config: AppConfig, route: RouteName): RouteBindingView;
+export declare function describeRoutesMap(config: AppConfig, routes: readonly RouteName[]): Record<string, RouteBindingView>;
 export declare function routeType(route: RouteName): RouteType;
+/** Internal: bound iff display name is present (same rule as API surfaces). */
 export declare function isRouteConfigured(config: AppConfig, route: RouteName): boolean;

package/dist/src/notify/bind.js

@@ -5,21 +5,47 @@ import { DingtalkDwsError } from "../errors.js";
 export function candidateRef(candidate) {
     return `candidate_${createHash("sha256").update(`${candidate.type}\n${candidate.target_id}`).digest("hex")}`;
 }
-export function readTargets(config) {
+function parseBoundTarget(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const record = raw;
+    const id = typeof record.id === "string" ? record.id.trim() : "";
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    if (!id || !name)
+        return null;
+    return { id, name };
+}
+/** Read valid bindings only. Bare strings / partial objects are invalid → omitted (unbound). No migration. */
+export function readBoundTargets(config) {
     try {
         const parsed = JSON.parse(fs.readFileSync(config.targetsPath, "utf8"));
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
-            return parsed;
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const out = {};
+        for (const route of ["notify_group", "notify_user"]) {
+            const bound = parseBoundTarget(parsed[route]);
+            if (bound)
+                out[route] = bound;
+        }
+        return out;
     }
     catch {
-        // first bind
+        return {};
     }
-    return {};
 }
-export function writeTarget(config, route, targetId) {
+export function readBoundTarget(config, route) {
+    return readBoundTargets(config)[route] ?? null;
+}
+export function writeTarget(config, route, target) {
+    const id = target.id.trim();
+    const name = target.name.trim();
+    if (!id || !name) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "bind requires non-empty id and name");
+    }
     fs.mkdirSync(path.dirname(config.targetsPath), { recursive: true, mode: 0o700 });
-    const targets = readTargets(config);
-    targets[route] = targetId;
+    // Rewrite from valid bindings only — invalid on-disk slots are dropped, not upgraded.
+    const targets = readBoundTargets(config);
+    targets[route] = { id, name };
     fs.writeFileSync(config.targetsPath, `${JSON.stringify(targets, null, 2)}\n`, { mode: 0o600 });
 }
 export function resolveRouteTarget(config, route) {
@@ -29,16 +55,32 @@ export function resolveRouteTarget(config, route) {
         }
         return "webhook";
     }
-    const target = readTargets(config)[route];
+    const target = readBoundTarget(config, route);
     if (!target)
         throw new DingtalkDwsError("INVALID_ARGUMENT", `Route ${route} has no bound target`);
-    return target;
+    return target.id;
+}
+export function describeRouteBinding(config, route) {
+    if (config.adapter === "webhook") {
+        if (route !== "notify_group" || !config.webhookUrl)
+            return { name: null, id: null };
+        return { name: "webhook", id: null };
+    }
+    const bound = readBoundTarget(config, route);
+    if (!bound)
+        return { name: null, id: null };
+    return { name: bound.name, id: bound.id };
+}
+export function describeRoutesMap(config, routes) {
+    const out = {};
+    for (const route of routes)
+        out[route] = describeRouteBinding(config, route);
+    return out;
 }
 export function routeType(route) {
     return route === "notify_group" ? "group" : "user";
 }
+/** Internal: bound iff display name is present (same rule as API surfaces). */
 export function isRouteConfigured(config, route) {
-    if (config.adapter === "webhook")
-        return route === "notify_group" && Boolean(config.webhookUrl);
-    return Boolean(readTargets(config)[route]);
+    return describeRouteBinding(config, route).name != null;
 }

package/dist/src/{patrol → patrol-setup}/setup.d.ts

@@ -1,11 +1,31 @@
 import type { AppConfig, RouteName } from "../types.js";
-/** Agent-filled args (not mcp.json forms). Delivery credentials come from MCP env → env.sh. */
+declare const DELIVER_POLICIES: readonly ["always", "on_status_change", "only_statuses"];
+type DeliverPolicyKind = (typeof DELIVER_POLICIES)[number];
+declare const TERMINATION_POLICIES: readonly ["none", "status_match", "manual"];
+type TerminationPolicyKind = (typeof TERMINATION_POLICIES)[number];
+export type PatrolSetupIntent = "always" | "long_monitor" | "stop_on_critical" | "on_event";
+export type PatrolSetupDeliver = {
+    policy?: DeliverPolicyKind;
+    statuses?: string[];
+};
+export type PatrolSetupTermination = {
+    policy?: TerminationPolicyKind;
+    status?: string;
+    on?: "first" | "until";
+    terminate_on_delivery_failure?: boolean;
+};
+/** Agent-filled args (not mcp.json forms). Delivery credentials come from MCP env -> env.sh. */
 export type PatrolSetupInput = {
     name: string;
     cron?: string;
     probe_command?: string;
     probe_script?: string;
     route?: RouteName;
+    /** Recipe alias for Agent. Explicit deliver/termination override the alias. */
+    intent?: PatrolSetupIntent;
+    watch_path?: string;
+    deliver?: PatrolSetupDeliver;
+    termination?: PatrolSetupTermination;
     /** Soft mode: allow missing bind/bundle (tests / preview). Always stages only. */
     dry_run?: boolean;
 };
@@ -21,7 +41,8 @@ export declare function readBundleInfo(env?: NodeJS.ProcessEnv): {
 };
 /**
  * Stage offline patrol materials only. Does not SSH/scp.
- * Agent copies bundle_root + staging_dir to the host (host-execution or SSH), then runs install.sh there.
+ * Prefer copy_plan.artifact (one .tgz). Two-dir copy is fallback when tar packing fails.
  */
 export declare function runPatrolSetup(config: AppConfig, input: PatrolSetupInput, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
 export declare function bundleFingerprintForDoctor(env?: NodeJS.ProcessEnv): Record<string, unknown>;
+export {};

package/dist/src/patrol-setup/setup.js

@@ -0,0 +1,386 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+import { DEFAULT_PATROL_MESSAGE_BODY, DEFAULT_PATROL_MESSAGE_TITLE, } from "../notify-delivery/index.js";
+import { DingtalkDwsError } from "../errors.js";
+import { isRouteConfigured, readBoundTarget } from "../notify/bind.js";
+import { mcpPackageRoot, readPackageVersion } from "../version.js";
+const OBSERVATION_STATUSES = ["ok", "warning", "critical", "unknown"];
+const DELIVER_POLICIES = ["always", "on_status_change", "only_statuses"];
+const TERMINATION_POLICIES = ["none", "status_match", "manual"];
+const DEFAULT_CRON = "*/15 * * * *";
+const DEFAULT_PROBE = `#!/usr/bin/env bash
+set -euo pipefail
+printf '%s\\n' '{"status":"ok","summary":"【进度】示例巡检正常\\n【监控】请替换为真实检查","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}'
+`;
+export function resolveBundleRoot(env = process.env) {
+    const override = env.DINGTALK_PATROL_BUNDLE_ROOT?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(mcpPackageRoot(), "deploy", "linux-x64");
+}
+export function readBundleInfo(env = process.env) {
+    const bundle_root = resolveBundleRoot(env);
+    const manifestPath = path.join(bundle_root, "manifest.json");
+    const ready = fs.existsSync(manifestPath) && fs.existsSync(path.join(bundle_root, "runtime", "patrol"));
+    if (!ready) {
+        return {
+            available: false,
+            bundle_root,
+            fingerprint: null,
+            server_version: null,
+            includes_node: false,
+            includes_dws: false,
+            message: `Patrol bundle missing at ${bundle_root}. ` +
+                `pack:deploy is monorepo-only (clone agent-compose, cd packages/mcp/dingtalk-dws-mcp, npm run pack:deploy). ` +
+                `npx installs do not include host-patrol/ or deploy artifacts.`,
+        };
+    }
+    try {
+        const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        return {
+            available: true,
+            bundle_root,
+            fingerprint: typeof m.fingerprint === "string" ? m.fingerprint : null,
+            server_version: typeof m.server_version === "string" ? m.server_version : null,
+            includes_node: Boolean(m.includes_node),
+            includes_dws: Boolean(m.includes_dws),
+            message: "bundle ready",
+        };
+    }
+    catch {
+        return {
+            available: false,
+            bundle_root,
+            fingerprint: null,
+            server_version: null,
+            includes_node: false,
+            includes_dws: false,
+            message: `Invalid manifest at ${manifestPath}`,
+        };
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function writeLf(filePath, content, mode) {
+    const body = content.replace(/\r\n/g, "\n");
+    if (mode === undefined)
+        fs.writeFileSync(filePath, body, "utf8");
+    else
+        fs.writeFileSync(filePath, body, { mode });
+}
+/** Sync local notify credentials (already verified by doctor) into target env.sh. Not user OAuth.
+ * Never copy laptop DINGTALK_DWS_COMMAND / config.dwsCommand — that path is Agent-host local
+ * (Windows .exe or Linux absolute) and is wrong on the patrol target. Target resolves `dws` via
+ * install runtime PATH (bundled linux ELF) or system dws. Optional target-only override:
+ * DINGTALK_PATROL_HOST_DWS (path that exists on the target machine).
+ */
+function writeEnvFile(filePath, config, env) {
+    const lines = ["# Generated by dingtalk_patrol_setup — delivery credentials for target host"];
+    const put = (key, value) => {
+        if (value)
+            lines.push(`export ${key}=${shellQuote(value)}`);
+    };
+    put("DINGTALK_CLIENT_ID", config.clientId ?? env.DINGTALK_CLIENT_ID);
+    put("DINGTALK_CLIENT_SECRET", config.clientSecret ?? env.DINGTALK_CLIENT_SECRET);
+    put("DINGTALK_ROBOT_CODE", config.robotCode ?? env.DINGTALK_ROBOT_CODE);
+    put("DINGTALK_WEBHOOK_URL", config.webhookUrl ?? env.DINGTALK_WEBHOOK_URL);
+    put("DINGTALK_WEBHOOK_SECRET", config.webhookSecret ?? env.DINGTALK_WEBHOOK_SECRET);
+    const hostDws = env.DINGTALK_PATROL_HOST_DWS?.trim();
+    if (hostDws)
+        put("DINGTALK_DWS_COMMAND", hostDws);
+    writeLf(filePath, `${lines.join("\n")}\n`, 0o600);
+}
+function pickRoute(config, preferred) {
+    if (config.adapter === "webhook")
+        return "notify_group";
+    if (preferred) {
+        if (!isRouteConfigured(config, preferred)) {
+            throw new DingtalkDwsError("INVALID_ARGUMENT", `Route ${preferred} is not bound`);
+        }
+        return preferred;
+    }
+    if (isRouteConfigured(config, "notify_group"))
+        return "notify_group";
+    if (isRouteConfigured(config, "notify_user"))
+        return "notify_user";
+    throw new DingtalkDwsError("INVALID_ARGUMENT", "Bind a notify target first (or use webhook)");
+}
+const INTENT_PRESETS = {
+    always: { deliver: { policy: "always" }, termination: { policy: "none" } },
+    long_monitor: {
+        deliver: { policy: "on_status_change", statuses: ["warning", "critical"] },
+        termination: { policy: "none" },
+    },
+    stop_on_critical: {
+        deliver: { policy: "always" },
+        termination: { policy: "status_match", status: "critical", on: "first" },
+    },
+    on_event: { deliver: { policy: "always" }, termination: { policy: "none" } },
+};
+function policiesFromIntent(intent) {
+    return INTENT_PRESETS[intent];
+}
+function resolvePolicies(input) {
+    const intent = input.intent ?? "always";
+    const preset = policiesFromIntent(intent);
+    return {
+        intent,
+        deliver: normalizeDeliver(input.deliver ?? preset.deliver),
+        termination: normalizeTermination(input.termination ?? preset.termination),
+    };
+}
+function writeJobArchive(options) {
+    const installSrc = path.join(options.bundleRoot, "install.sh");
+    if (!fs.existsSync(installSrc))
+        return null;
+    const packDir = fs.mkdtempSync(path.join(os.tmpdir(), "patrol-job-"));
+    try {
+        writeLf(path.join(packDir, "install.sh"), fs.readFileSync(installSrc, "utf8"), 0o755);
+        const manifest = path.join(options.bundleRoot, "manifest.json");
+        if (fs.existsSync(manifest))
+            fs.copyFileSync(manifest, path.join(packDir, "manifest.json"));
+        const runtime = path.join(options.bundleRoot, "runtime");
+        const includes_runtime = fs.existsSync(runtime);
+        if (includes_runtime)
+            fs.cpSync(runtime, path.join(packDir, "runtime"), { recursive: true });
+        fs.cpSync(options.stagingRoot, path.join(packDir, "staging"), { recursive: true });
+        fs.mkdirSync(path.dirname(options.outFile), { recursive: true });
+        if (fs.existsSync(options.outFile))
+            fs.unlinkSync(options.outFile);
+        const entries = ["install.sh", "staging"];
+        if (fs.existsSync(path.join(packDir, "manifest.json")))
+            entries.push("manifest.json");
+        if (includes_runtime)
+            entries.push("runtime");
+        const dest = options.outFile.replace(/\\/g, "/");
+        const cwd = packDir.replace(/\\/g, "/");
+        execFileSync("tar", ["-czf", dest, "-C", cwd, ...entries], { windowsHide: true });
+        return { bytes: fs.statSync(options.outFile).size, includes_runtime };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        fs.rmSync(packDir, { recursive: true, force: true });
+    }
+}
+function isObservationStatus(value) {
+    return OBSERVATION_STATUSES.includes(value);
+}
+function normalizeDeliver(input) {
+    const policy = input?.policy ?? "always";
+    if (!DELIVER_POLICIES.includes(policy)) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "deliver.policy must be always | on_status_change | only_statuses");
+    }
+    const statuses = (input?.statuses ?? []).filter((s) => typeof s === "string" && isObservationStatus(s));
+    if (input?.statuses && input.statuses.length !== statuses.length) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "deliver.statuses must be ok|warning|critical|unknown");
+    }
+    if (policy === "only_statuses" && statuses.length === 0) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "deliver.statuses is required when deliver.policy is only_statuses");
+    }
+    return statuses.length ? { policy, statuses } : { policy };
+}
+function normalizeTermination(input) {
+    const policy = input?.policy ?? "none";
+    if (!TERMINATION_POLICIES.includes(policy)) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "termination.policy must be none | status_match | manual");
+    }
+    if (policy !== "status_match") {
+        return { policy };
+    }
+    const status = input?.status;
+    if (!status || !isObservationStatus(status)) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "termination.status must be ok|warning|critical|unknown");
+    }
+    const on = input?.on === "until" ? "until" : "first";
+    return {
+        policy,
+        status,
+        on,
+        terminate_on_delivery_failure: input?.terminate_on_delivery_failure === true,
+    };
+}
+function yamlBlockDeliver(deliver) {
+    const lines = ["deliver:", `  policy: ${deliver.policy}`];
+    if (deliver.statuses?.length) {
+        lines.push(`  statuses: [${deliver.statuses.map((s) => JSON.stringify(s)).join(", ")}]`);
+    }
+    return lines.join("\n");
+}
+function yamlBlockTermination(termination) {
+    const lines = ["termination:", `  policy: ${termination.policy}`];
+    if (termination.policy === "status_match" && termination.status) {
+        lines.push(`  status: ${termination.status}`);
+        lines.push(`  on: ${termination.on ?? "first"}`);
+        if (termination.terminate_on_delivery_failure) {
+            lines.push("  terminate_on_delivery_failure: true");
+        }
+    }
+    return lines.join("\n");
+}
+function buildYaml(options) {
+    const delivery = [`  type: ${options.deliveryType}`];
+    if (options.target)
+        delivery.push(`  ${options.target.field}: ${JSON.stringify(options.target.id)}`);
+    const body = DEFAULT_PATROL_MESSAGE_BODY.split("\n").map((l) => `    ${l}`).join("\n");
+    const trigger = options.watchPath
+        ? `trigger:
+  type: event
+  watch:
+    path: ${JSON.stringify(options.watchPath)}`
+        : `cron: ${JSON.stringify(options.cron ?? "*/15 * * * *")}`;
+    return `name: ${options.name}
+${trigger}
+probe:
+  exec:
+    command: ${JSON.stringify(options.probeCommand)}
+    timeout_sec: 60
+delivery:
+${delivery.join("\n")}
+${yamlBlockDeliver(options.deliver)}
+${yamlBlockTermination(options.termination)}
+template:
+  title: ${JSON.stringify(DEFAULT_PATROL_MESSAGE_TITLE)}
+  body: |
+${body}
+`;
+}
+/**
+ * Stage offline patrol materials only. Does not SSH/scp.
+ * Prefer copy_plan.artifact (one .tgz). Two-dir copy is fallback when tar packing fails.
+ */
+export async function runPatrolSetup(config, input, env = process.env) {
+    const name = input.name.trim();
+    if (!name || name.includes("/") || name.includes("\\") || name.includes("..")) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "name must be a single path segment");
+    }
+    if (!config.adapter) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "Set DINGTALK_CLIENT_ID/SECRET or DINGTALK_WEBHOOK_URL in MCP env");
+    }
+    const { intent, deliver, termination } = resolvePolicies(input);
+    if (intent === "on_event" && !input.watch_path?.trim()) {
+        throw new DingtalkDwsError("INVALID_ARGUMENT", "watch_path is required for intent=on_event (host file or directory; EventTrigger uses fs.watch, not cron)");
+    }
+    const watchPath = intent === "on_event" ? input.watch_path.trim() : undefined;
+    const cron = watchPath ? undefined : (input.cron?.trim() || DEFAULT_CRON);
+    const bundle = readBundleInfo(env);
+    if (!bundle.available && !input.dry_run) {
+        throw new DingtalkDwsError("ADAPTER_UNAVAILABLE", bundle.message);
+    }
+    const route = pickRoute(config, input.route);
+    const deliveryType = config.adapter;
+    let target;
+    let targetName;
+    if (deliveryType === "dws") {
+        const bound = readBoundTarget(config, route);
+        if (!bound && !input.dry_run) {
+            throw new DingtalkDwsError("INVALID_ARGUMENT", `Bind ${route} before setup`);
+        }
+        if (bound) {
+            targetName = bound.name;
+            target = route === "notify_group"
+                ? { field: "open_conversation_id", id: bound.id }
+                : { field: "user_id", id: bound.id };
+        }
+    }
+    const stagingRoot = path.join(env.DINGTALK_PATROL_STAGING_DIR?.trim()
+        ? path.resolve(env.DINGTALK_PATROL_STAGING_DIR)
+        : path.join(os.tmpdir(), "dingtalk-patrol-staging"), name);
+    fs.mkdirSync(path.join(stagingRoot, "probes"), { recursive: true, mode: 0o700 });
+    const probeCommand = input.probe_command?.trim() || "./probes/example.sh";
+    const probeFile = path.join(stagingRoot, "probes", path.basename(probeCommand) === probeCommand ? "example.sh" : path.basename(probeCommand));
+    const script = input.probe_script ?? DEFAULT_PROBE;
+    writeLf(probeFile, script.endsWith("\n") ? script : `${script}\n`, 0o755);
+    const yamlPath = path.join(stagingRoot, "patrol.yaml");
+    const envPath = path.join(stagingRoot, "env.sh");
+    writeLf(yamlPath, buildYaml({
+        name,
+        cron,
+        watchPath,
+        probeCommand: probeCommand.includes("/") || probeCommand.includes("\\")
+            ? probeCommand
+            : `./probes/${path.basename(probeFile)}`,
+        deliveryType,
+        target,
+        deliver,
+        termination,
+    }));
+    writeEnvFile(envPath, config, env);
+    const artifactPath = path.join(path.dirname(stagingRoot), `${name}.tgz`);
+    const archive = bundle.available
+        ? writeJobArchive({ bundleRoot: bundle.bundle_root, stagingRoot, outFile: artifactPath })
+        : null;
+    const response = {
+        ok: true,
+        name,
+        cron,
+        route,
+        intent,
+        watch_path: watchPath,
+        trigger: watchPath ? { type: "event", watch: { path: watchPath } } : { type: "cron", cron },
+        deliver,
+        termination,
+        next_action: "install_on_host",
+        staging_dir: stagingRoot,
+        bundle_root: bundle.bundle_root,
+        bundle_fingerprint: bundle.fingerprint,
+        includes_node: bundle.includes_node,
+        includes_dws: bundle.includes_dws,
+        install_hint: archive
+            ? `Copy one file ${artifactPath} to the host, tar -xzf, then ./install.sh ./staging. LAN hosts: local SCP. Do not send RFC1918 IPs via ACCESS.`
+            : "Copy bundle_root and staging_dir to the host, then run install.sh <staging_on_host>",
+        copy_plan: archive
+            ? {
+                artifact: artifactPath,
+                bytes: archive.bytes,
+                includes_runtime: archive.includes_runtime,
+                remote_install: "tar -xzf <job.tgz> && ./install.sh ./staging",
+            }
+            : {
+                bundle_root: bundle.bundle_root,
+                staging_dir: stagingRoot,
+                remote_install: "install.sh <staging_on_host>",
+            },
+        server_version: readPackageVersion(),
+        paths: { yaml: yamlPath, env: envPath, probe: probeFile, artifact: archive ? artifactPath : undefined },
+    };
+    if (targetName)
+        response.target_name = targetName;
+    if (deliveryType === "dws" && bundle.available && !bundle.includes_dws) {
+        response.warning =
+            "bundle includes_dws=false: target needs system dws on PATH, or re-pack with linux ELF (DINGTALK_PATROL_DWS_PATH)";
+    }
+    const serialized = JSON.stringify(response);
+    for (const secret of [config.clientSecret, config.webhookSecret, env.DINGTALK_CLIENT_SECRET, env.DINGTALK_WEBHOOK_SECRET]) {
+        if (secret && serialized.includes(secret)) {
+            throw new DingtalkDwsError("INTERNAL_ERROR", "refusing to return secrets");
+        }
+    }
+    return response;
+}
+export function bundleFingerprintForDoctor(env = process.env) {
+    const info = readBundleInfo(env);
+    let next_action = null;
+    if (!info.available) {
+        next_action =
+            "Host patrol bundle missing. In this repo: npm run pack:deploy and set DINGTALK_PATROL_BUNDLE_ROOT. npx installs have no deploy artifacts — do not dry_run as a substitute for packing.";
+    }
+    else if (!info.includes_dws) {
+        next_action =
+            "Bundle has no linux dws ELF. Re-run pack:deploy on a machine with dingtalk-workspace-cli (or set DINGTALK_PATROL_DWS_PATH). Target otherwise needs system dws.";
+    }
+    return {
+        available: info.available,
+        fingerprint: info.fingerprint,
+        server_version: info.server_version ?? readPackageVersion(),
+        includes_node: info.includes_node,
+        includes_dws: info.includes_dws,
+        path: info.bundle_root,
+        message: info.message,
+        next_action,
+    };
+}

package/dist/src/prompts.js

@@ -2,12 +2,10 @@ const NOTIFY_RECIPE = `One-shot DingTalk notify (user-selected recipe):
 1. dingtalk_doctor → follow next_action
 2. Managed: search → bind → dingtalk_send (route, title, content)
 3. Webhook: dingtalk_send with route=notify_group only`;
-const PATROL_RECIPE = `Host Patrol Runtime (user-selected recipe):
+const PATROL_RECIPE = `Host Job Runtime (RFC-0008; user-selected recipe):
 1. dingtalk_doctor (credentials in MCP env only)
-2. Managed: bind notify target if needed
-3. From conversation: host + what to check + how often → call dingtalk_patrol_setup once (stages materials + delivery credentials)
-4. Copy bundle_root + staging_dir to the host (host-execution if available, else SSH with user-provided IP/user/password or key), run install.sh on the host
-5. Stop — do not download Node on the laptop`;
+2. Managed: search → bind if needed. Search empty (next_action=ask_user): stop and ask the user; do not guess another name.
+3. dingtalk_patrol_setup once (intent from conversation; on_event needs watch_path). Follow copy_plan. Stop — no session loop or dingtalk_send.`;
 export function listPromptDefinitions(_surface) {
     return [
         {

package/dist/src/resources/guides.d.ts

@@ -0,0 +1,24 @@
+export type GuideMeta = {
+    slug: string;
+    uri: string;
+    title: string;
+    description: string;
+};
+export declare function listMcpGuideResources(): Array<{
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    annotations: {
+        audience: Array<"user" | "assistant">;
+        priority: number;
+    };
+}>;
+export declare function readMcpGuideResource(uri: string): {
+    contents: Array<{
+        uri: string;
+        mimeType: string;
+        text: string;
+    }>;
+};

package/dist/src/resources/guides.js

@@ -0,0 +1,36 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { mcpPackageRoot } from "../version.js";
+const GUIDES = [
+    {
+        slug: "doc-search",
+        uri: "dingtalk-dws://guides/doc-search",
+        title: "DingTalk cloud doc search",
+        description: "Agent overlay: drive search short path and stop-rules; prefer over upstream doc search recipes when they lag.",
+    },
+];
+function readMarkdown(slug) {
+    const filePath = path.join(mcpPackageRoot(), "guides", `${slug}.md`);
+    return fs.readFileSync(filePath, "utf8");
+}
+export function listMcpGuideResources() {
+    return GUIDES.map((g) => ({
+        uri: g.uri,
+        name: g.slug,
+        title: g.title,
+        description: g.description,
+        mimeType: "text/markdown",
+        annotations: { audience: ["assistant"], priority: 0.7 },
+    }));
+}
+export function readMcpGuideResource(uri) {
+    const guide = GUIDES.find((g) => g.uri === uri);
+    if (!guide) {
+        const err = new Error(`Resource not found: ${uri}`);
+        err.code = -32002;
+        throw err;
+    }
+    return {
+        contents: [{ uri, mimeType: "text/markdown", text: readMarkdown(guide.slug) }],
+    };
+}