dsh-industry-research 0.1.0

package/lib/index.js

@@ -0,0 +1,2080 @@
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { FileSystemSkillProvider } from "@deepseek-ai/dsh-skill-filesystem";
+import z from "@deepseek-ai/schemastery";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createHash } from "node:crypto";
+//#region src/config.ts
+/**
+* Config schema and resolution for `dsh-industry-research`. Every tunable is a
+* validated {@link Config} field changeable from cordis.yml; the resolution
+* step validates bounds so misconfiguration fails loud at mount. With
+* `enabled: false` the plugin registers nothing and stays inert.
+* @module dsh-industry-research/config
+*/
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	industryRoot: z.string().default("industry-research"),
+	fetchTimeoutMs: z.number().default(2e4),
+	timelineMaxEntries: z.number().default(500),
+	sourceAllowlist: z.array(z.string()).default([]),
+	sourceBlocklist: z.array(z.string()).default([]),
+	offline: z.boolean().default(false),
+	skillsDir: z.string(),
+	track: z.object({
+		maxResultsPerTopic: z.number().default(10),
+		maxFetchesPerCall: z.number().default(10)
+	}).default({
+		maxResultsPerTopic: 10,
+		maxFetchesPerCall: 10
+	}),
+	scan: z.object({
+		maxFileBytes: z.number().default(1048576),
+		maxFigureCandidates: z.number().default(100)
+	}).default({
+		maxFileBytes: 1048576,
+		maxFigureCandidates: 100
+	})
+});
+/** Throw unless `value` is a positive safe integer. */
+function assertPositiveInt(name, value) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer, got ${String(value)}`);
+}
+/** Throw unless every entry is a non-empty string. */
+function assertStringList(name, value) {
+	for (const entry of value) if (typeof entry !== "string" || entry.trim().length === 0) throw new TypeError(`${name} entries must be non-empty strings, got ${JSON.stringify(entry)}`);
+}
+/**
+* Validate raw values and fill explicit defaults. Invalid bounds throw here —
+* misconfiguration fails loud at mount even without the Schemastery loader.
+* @param config - raw (possibly partial) plugin config.
+* @returns the fully resolved config.
+*/
+function resolveConfig(config = {}) {
+	const industryRoot = config.industryRoot ?? "industry-research";
+	if (typeof industryRoot !== "string" || industryRoot.trim().length === 0) throw new TypeError("industryRoot must be a non-empty path");
+	const fetchTimeoutMs = config.fetchTimeoutMs ?? 2e4;
+	assertPositiveInt("fetchTimeoutMs", fetchTimeoutMs);
+	const timelineMaxEntries = config.timelineMaxEntries ?? 500;
+	assertPositiveInt("timelineMaxEntries", timelineMaxEntries);
+	const sourceAllowlist = config.sourceAllowlist ?? [];
+	assertStringList("sourceAllowlist", sourceAllowlist);
+	const sourceBlocklist = config.sourceBlocklist ?? [];
+	assertStringList("sourceBlocklist", sourceBlocklist);
+	const skillsDir = config.skillsDir;
+	if (skillsDir !== void 0 && (typeof skillsDir !== "string" || skillsDir.trim().length === 0)) throw new TypeError("skillsDir must be a non-empty path when set");
+	const maxResultsPerTopic = config.track?.maxResultsPerTopic ?? 10;
+	assertPositiveInt("track.maxResultsPerTopic", maxResultsPerTopic);
+	const maxFetchesPerCall = config.track?.maxFetchesPerCall ?? 10;
+	assertPositiveInt("track.maxFetchesPerCall", maxFetchesPerCall);
+	const maxFileBytes = config.scan?.maxFileBytes ?? 1048576;
+	assertPositiveInt("scan.maxFileBytes", maxFileBytes);
+	const maxFigureCandidates = config.scan?.maxFigureCandidates ?? 100;
+	assertPositiveInt("scan.maxFigureCandidates", maxFigureCandidates);
+	return {
+		enabled: config.enabled ?? true,
+		industryRoot,
+		fetchTimeoutMs,
+		timelineMaxEntries,
+		sourceAllowlist,
+		sourceBlocklist,
+		offline: config.offline ?? false,
+		skillsDir,
+		track: {
+			maxResultsPerTopic,
+			maxFetchesPerCall
+		},
+		scan: {
+			maxFileBytes,
+			maxFigureCandidates
+		}
+	};
+}
+//#endregion
+//#region src/chain.ts
+/**
+* The industry-chain structure model (`ChainMap`) and its validation. This is
+* a pure data module: no I/O, no clock. A metric is either a sourced value
+* (`value` + `sourceRef`, optionally `unit`/`asOf`) or an explicit gap slot
+* (no `value`), so an unsourced number is a validation error by construction
+* and a missing number is an honest, listable gap.
+* @module dsh-industry-research/chain
+*/
+/** Chain tiers, upstream → downstream. */
+const CHAIN_TIERS = [
+	"upstream",
+	"midstream",
+	"downstream"
+];
+/**
+* Validate a chain map. Pure: returns the list of problems (empty when the
+* map is well-formed). Rules: unique node ids, legal tiers, edges reference
+* existing nodes, and every metric carrying a `value` also carries a
+* `sourceRef` (gap slots without a value are always legal).
+* @param map - the candidate chain map.
+* @returns human-readable validation problems, in encounter order.
+*/
+function validateChainMap(map) {
+	const problems = [];
+	if (typeof map.industry !== "string" || map.industry.trim().length === 0) problems.push("chain.industry must be a non-empty name");
+	const ids = /* @__PURE__ */ new Set();
+	for (const node of map.nodes) {
+		if (typeof node.id !== "string" || node.id.trim().length === 0) {
+			problems.push(`node ${JSON.stringify(node.id)} has an empty id`);
+			continue;
+		}
+		if (ids.has(node.id)) problems.push(`duplicate node id "${node.id}"`);
+		ids.add(node.id);
+		if (typeof node.name !== "string" || node.name.trim().length === 0) problems.push(`node "${node.id}" has an empty name`);
+		if (!CHAIN_TIERS.includes(node.tier)) problems.push(`node "${node.id}" has an illegal tier ${JSON.stringify(node.tier)} (expected upstream|midstream|downstream)`);
+		for (const metric of node.metrics) {
+			if (typeof metric.key !== "string" || metric.key.trim().length === 0) {
+				problems.push(`node "${node.id}" has a metric with an empty key`);
+				continue;
+			}
+			if (metric.value !== void 0) {
+				if (typeof metric.value !== "number" || !Number.isFinite(metric.value)) problems.push(`node "${node.id}" metric "${metric.key}" carries a non-finite value`);
+				if (typeof metric.sourceRef !== "string" || metric.sourceRef.trim().length === 0) problems.push(`node "${node.id}" metric "${metric.key}" carries a value without a sourceRef — register the source or mark the slot 待补 (omit value)`);
+			}
+		}
+	}
+	for (const edge of map.edges) {
+		if (!ids.has(edge.from)) problems.push(`edge references unknown node "${edge.from}" (from)`);
+		if (!ids.has(edge.to)) problems.push(`edge references unknown node "${edge.to}" (to)`);
+	}
+	return problems;
+}
+/**
+* List the explicit gaps of a well-formed chain map: metric slots without a
+* value, nodes without any metric slot, and tiers with no node at all.
+* @param map - the chain map (already validated).
+* @returns human-readable gap lines, in encounter order.
+*/
+function chainGaps(map) {
+	const gaps = [];
+	const tiers = /* @__PURE__ */ new Set();
+	for (const node of map.nodes) {
+		tiers.add(node.tier);
+		if (node.metrics.length === 0) gaps.push(`节点「${node.name}」(${node.id}) 没有任何指标槽位`);
+		for (const metric of node.metrics) if (metric.value === void 0) gaps.push(`节点「${node.name}」(${node.id}) 的指标「${metric.key}」待补（无来源数值）`);
+	}
+	for (const tier of CHAIN_TIERS) if (!tiers.has(tier)) gaps.push(`产业链缺少 ${tier} 层节点`);
+	return gaps;
+}
+//#endregion
+//#region src/sources.ts
+/**
+* The per-industry source registry (`sources.json`). Every artifact a metric
+* or claim may cite — a user note, a supplied data file, a fetched page — is
+* registered here with a stable ref (`S1`, `S2`, …), its origin (workspace
+* path or URL), and a SHA-256 content hash, so reports can render a
+* source-traceability appendix and byte-level checks can replay.
+* @module dsh-industry-research/sources
+*/
+/** SHA-256 hex digest of a UTF-8 string. */
+function sha256Of(content) {
+	return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/**
+* Load a registry from disk, tolerating a missing file (empty registry).
+* A corrupt file fails loud — durable data must not be silently dropped.
+* @param path - absolute path of the registry JSON.
+* @returns the parsed registry, or a fresh one when the file does not exist.
+*/
+async function loadSources(path) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			next: 1,
+			items: []
+		};
+		throw error;
+	}
+	const parsed = JSON.parse(text);
+	if (typeof parsed.next !== "number" || !Array.isArray(parsed.items)) throw new Error(`sources registry at ${path} is malformed (expected { next, items[] })`);
+	return parsed;
+}
+/**
+* Persist a registry, creating the parent directory.
+* @param path - absolute path of the registry JSON.
+* @param registry - the registry to write.
+*/
+async function saveSources(path, registry) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(registry, null, 2)}\n`, "utf8");
+}
+/**
+* Register one source and return its ref. Re-registering the same origin
+* refreshes the hash/timestamp of the existing entry instead of duplicating
+* it, so refs stay stable across re-runs.
+* @param registry - the registry to mutate.
+* @param origin - workspace path or URL the content came from.
+* @param content - the verbatim content snapshot (hashed).
+* @param capturedAt - ISO-8601 registration time.
+* @param note - optional human note (e.g. page title).
+* @returns the stable ref of the entry.
+*/
+function registerSource(registry, origin, content, capturedAt, note) {
+	const sha256 = sha256Of(content);
+	const existing = registry.items.find((item) => item.origin === origin);
+	if (existing !== void 0) {
+		existing.sha256 = sha256;
+		existing.capturedAt = capturedAt;
+		if (note !== void 0) existing.note = note;
+		return existing.ref;
+	}
+	const ref = `S${registry.next}`;
+	registry.next += 1;
+	registry.items.push({
+		ref,
+		origin,
+		sha256,
+		capturedAt,
+		...note !== void 0 ? { note } : {}
+	});
+	return ref;
+}
+//#endregion
+//#region src/web.ts
+/**
+* Look up the optional web capability.
+* @param ctx - the plugin context.
+* @returns the web service surface, or undefined when no web seam is mounted.
+*/
+function lookupWeb(ctx) {
+	return ctx.get("web");
+}
+/**
+* Resolve the web capability or throw the actionable reason it cannot run:
+* `offline: true` (deployment choice) or no mounted web seam (mount guidance
+* naming the missing pieces). Used by tools whose work is impossible offline.
+* @param ctx - the plugin context.
+* @param config - the resolved plugin config.
+* @param tool - the calling tool name (for the error message).
+* @returns the web service surface.
+*/
+function requireWeb(ctx, config, tool) {
+	if (config.offline) throw new Error(`${tool} cannot run while config.offline is true — public-source tracking requires the web; set offline: false or work from local artifacts only`);
+	const web = lookupWeb(ctx);
+	if (web === void 0) throw new Error(`${tool} requires the ctx.web capability, which is not mounted in this profile — mount @deepseek-ai/dsh-web plus a search provider (e.g. @deepseek-ai/dsh-web-search-deepseek) and a fetch provider (e.g. @deepseek-ai/dsh-web-fetch-http); the official dsh-base bundle already composes them`);
+	return web;
+}
+/**
+* Combine the tool's caller signal with the configured per-request timeout.
+* @param signal - the tool execution signal (`exec.signal`).
+* @param timeoutMs - per-request timeout in milliseconds.
+* @returns a signal that fires on either cancellation or timeout.
+*/
+function requestSignal(signal, timeoutMs) {
+	return AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+}
+/**
+* Render a thrown web failure with its machine-routable code when one exists
+* (`WebError` carries a stable `code`; plain errors degrade to the message).
+* @param error - the thrown value.
+* @returns a single-line diagnostic.
+*/
+function webErrorMessage(error) {
+	if (error instanceof Error) {
+		const code = error.code;
+		if (typeof code === "string" && code.length > 0) return `${code}: ${error.message}`;
+		return error.message;
+	}
+	return String(error);
+}
+//#endregion
+//#region src/paths.ts
+/**
+* Workspace path resolution and containment for `dsh-industry-research`. All
+* artifacts live under `<cwd>/<industryRoot>/`; every name crossing a tool
+* argument boundary (industry, company, data file) is validated so a crafted
+* value cannot escape the workspace. Both sides of every containment check
+* are resolved before comparison (`path.resolve` returns backslashes on
+* Windows, and comparing against a forward-slash input would always fail).
+* @module dsh-industry-research/paths
+*/
+/** Windows device names that cannot serve as directory segments. */
+const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
+/** Windows-forbidden filename characters (control characters are checked by code point below). */
+const FORBIDDEN_CHARS = /[<>:"|?*]/u;
+/**
+* Validate one path segment (an industry or company directory name). CJK and
+* other Unicode letters are fine; separators, traversal, control characters,
+* leading/trailing dots/spaces, and Windows device names are rejected.
+* @param label - what the segment names (for the error message).
+* @param value - the raw user/model-supplied name.
+* @returns the trimmed, validated segment.
+*/
+function safeSegment(label, value) {
+	const segment = value.trim();
+	if (segment.length === 0) throw new Error(`${label} must be a non-empty name`);
+	if (segment.length > 80) throw new Error(`${label} must be at most 80 characters, got ${segment.length}`);
+	if (segment.includes("/") || segment.includes("\\")) throw new Error(`${label} must be a single path segment, got ${JSON.stringify(value)}`);
+	if (segment === "." || segment === ".." || segment.includes("..")) throw new Error(`${label} must not contain traversal, got ${JSON.stringify(value)}`);
+	if (FORBIDDEN_CHARS.test(segment)) throw new Error(`${label} must not contain Windows-reserved characters, got ${JSON.stringify(value)}`);
+	for (const char of segment) if ((char.codePointAt(0) ?? 0) < 32) throw new Error(`${label} must not contain control characters, got ${JSON.stringify(value)}`);
+	if (segment.startsWith(".") || segment.endsWith(".") || segment.endsWith(" ")) throw new Error(`${label} must not start with '.' or end with '.'/' ', got ${JSON.stringify(value)}`);
+	if (WINDOWS_RESERVED.test(segment)) throw new Error(`${label} must not be a Windows device name, got ${JSON.stringify(value)}`);
+	return segment;
+}
+/**
+* Resolve `root` against the workspace cwd and return the absolute root.
+* A relative `industryRoot` is workspace-relative; an absolute one is used
+* as-is (deployment choice).
+* @param cwd - absolute session workspace root.
+* @param industryRoot - configured root (relative or absolute).
+* @returns the absolute industry root.
+*/
+function resolveIndustryRoot(cwd, industryRoot) {
+	return isAbsolute(industryRoot) ? resolve(industryRoot) : resolve(cwd, industryRoot);
+}
+/**
+* Resolve a user-supplied workspace-relative file path and verify containment
+* inside the workspace. Absolute paths are accepted only when already inside
+* the workspace; everything escaping the cwd is rejected.
+* @param cwd - absolute session workspace root.
+* @param file - the raw path from a tool argument.
+* @returns the absolute, containment-verified path.
+*/
+function resolveWorkspaceFile(cwd, file) {
+	const base = resolve(cwd);
+	const target = isAbsolute(file) ? resolve(file) : resolve(base, file);
+	if (target !== base && !target.startsWith(base + sep)) throw new Error(`path escapes the session workspace: ${JSON.stringify(file)}`);
+	return target;
+}
+/**
+* Resolve one named directory below a root and verify containment (defense in
+* depth after {@link safeSegment}).
+* @param root - absolute parent root.
+* @param segment - an already validated segment.
+* @returns the absolute, containment-verified directory path.
+*/
+function resolveContained(root, segment) {
+	const base = resolve(root);
+	const target = resolve(base, segment);
+	if (!target.startsWith(base + sep)) throw new Error(`segment escapes its root: ${JSON.stringify(segment)}`);
+	return target;
+}
+//#endregion
+//#region src/toolkit.ts
+/**
+* Shared helpers for the four research tools: workspace resolution from the
+* calling agent's session and per-industry directory layout. The layout is:
+*
+* ```
+* <cwd>/<industryRoot>/<industry>/chain.json      industry_map
+* <cwd>/<industryRoot>/<industry>/timeline.jsonl  industry_track
+* <cwd>/<industryRoot>/<industry>/sources.json    source registry
+* <cwd>/<industryRoot>/<industry>/notes/          seed notes
+* <cwd>/<industryRoot>/<industry>/reports/<ts>/   industry_report
+* <cwd>/<industryRoot>/companies/<slug>/card.*    company_scan
+* ```
+* @module dsh-industry-research/toolkit
+*/
+/**
+* Resolve the session workspace the calling agent operates in. The tools are
+* workspace-bound by design; without an agent-owned session cwd there is no
+* honest place to persist artifacts, so this fails loud.
+* @param exec - the tool execution context.
+* @returns the absolute workspace root.
+*/
+function workspaceOf(exec) {
+	const cwd = exec.agent?.session.header.cwd;
+	if (cwd === void 0 || cwd.trim().length === 0) throw new Error("this tool requires an agent-owned session workspace (session.header.cwd is unset)");
+	return cwd;
+}
+/**
+* Resolve and validate the directory of one industry under the configured
+* root. The industry name is validated as a single safe path segment.
+* @param config - resolved plugin config.
+* @param cwd - absolute workspace root.
+* @param industry - the raw industry argument.
+* @returns `{ root, dir, name }` — absolute industry root, absolute industry directory, and the validated segment.
+*/
+function industryDirOf(config, cwd, industry) {
+	const name = safeSegment("industry", industry);
+	const root = resolveIndustryRoot(cwd, config.industryRoot);
+	return {
+		root,
+		dir: resolveContained(root, name),
+		name
+	};
+}
+/**
+* Resolve and validate the directory of one company card under the shared
+* companies root.
+* @param config - resolved plugin config.
+* @param cwd - absolute workspace root.
+* @param company - the raw company name argument.
+* @returns `{ root, dir, slug }` — absolute industry root, absolute company directory, and the validated slug.
+*/
+function companyDirOf(config, cwd, company) {
+	const slug = safeSegment("company", company);
+	const root = resolveIndustryRoot(cwd, config.industryRoot);
+	return {
+		root,
+		dir: join(root, "companies", slug),
+		slug
+	};
+}
+/** The `chain.json` path of an industry directory. */
+function chainPathOf(dir) {
+	return join(dir, "chain.json");
+}
+/** The `timeline.jsonl` path of an industry directory. */
+function timelinePathOf(dir) {
+	return join(dir, "timeline.jsonl");
+}
+/** The `sources.json` path of an industry directory. */
+function sourcesPathOf(dir) {
+	return join(dir, "sources.json");
+}
+/** The `notes/` directory of an industry directory. */
+function notesDirOf(dir) {
+	return join(dir, "notes");
+}
+/** The `reports/` directory of an industry directory. */
+function reportsDirOf(dir) {
+	return join(dir, "reports");
+}
+//#endregion
+//#region src/tools/map.ts
+/**
+* The `industry_map` tool: build or update one industry's chain map. The
+* model authors the ChainMap (guided by the industry-research-method skill);
+* the tool validates it (dangling edges, unsourced numbers, illegal tiers),
+* persists `chain.json`, registers seed/web material as citable sources, and
+* lists the explicit gap slots. Called without a `chain` argument it returns
+* the current map plus the registered sources, so the model can iterate.
+* @module dsh-industry-research/tools/map
+*/
+/** The ChainMap parameter schema (semantic checks live in {@link validateChainMap}). */
+const CHAIN_PARAMETER = {
+	type: "object",
+	properties: {
+		industry: {
+			type: "string",
+			required: true,
+			description: "行业显示名"
+		},
+		nodes: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						required: true,
+						description: "节点 id（边引用用，如 upstream-1）"
+					},
+					name: {
+						type: "string",
+						required: true,
+						description: "节点显示名（如 高粱种植）"
+					},
+					tier: {
+						type: "string",
+						enum: [
+							"upstream",
+							"midstream",
+							"downstream"
+						],
+						required: true
+					},
+					metrics: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							properties: {
+								key: {
+									type: "string",
+									required: true,
+									description: "指标名（如 市场规模）"
+								},
+								value: {
+									type: "number",
+									description: "数值；缺省即待补槽位"
+								},
+								unit: {
+									type: "string",
+									description: "单位（如 亿元、%）"
+								},
+								asOf: {
+									type: "string",
+									description: "数值截止日期（ISO-8601）"
+								},
+								sourceRef: {
+									type: "string",
+									description: "来源引用：sources.json 的 ref（如 S1）、URL 或工作区路径；有 value 时必填"
+								}
+							},
+							additionalProperties: false
+						},
+						description: "指标槽位：有 value 必须带 sourceRef；无 value 即显式待补"
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		edges: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				properties: {
+					from: {
+						type: "string",
+						required: true,
+						description: "源节点 id"
+					},
+					to: {
+						type: "string",
+						required: true,
+						description: "目标节点 id"
+					},
+					note: {
+						type: "string",
+						description: "关系说明（如 原料供应）"
+					}
+				},
+				additionalProperties: false
+			}
+		}
+	},
+	additionalProperties: false,
+	description: "模型撰写的产业链结构图；语义校验（悬空边、无来源数值）由工具执行"
+};
+/**
+* Build the `industry_map` tool definition.
+* @param ctx - the plugin context (event emission + optional web lookup).
+* @param config - the resolved plugin config.
+* @returns the tool definition to register.
+*/
+function buildIndustryMapTool(ctx, config) {
+	return defineTool({
+		name: "industry_map",
+		description: "行业研究员的产业链建图工具：校验并落盘一份产业链结构图（上/中/下游节点 + 边 + 指标槽位），或在不带 chain 时返回当前图与已登记来源。每个有数值的指标必须带来源引用（sourceRef），缺数值的槽位即显式待补；禁止编造数据。仅供研究，不构成投资建议。",
+		parameters: {
+			industry: {
+				type: "string",
+				required: true,
+				description: "行业名（作为目录段，如「白酒」）"
+			},
+			seed: {
+				type: "string",
+				description: "自由文本笔记，写入该行业的 notes/ 并登记为来源"
+			},
+			seedFiles: {
+				type: "array",
+				items: { type: "string" },
+				description: "工作区内已有笔记/材料文件的相对路径列表，登记为来源"
+			},
+			web: {
+				type: "boolean",
+				description: "是否做 web 辅助检索（默认 true；config.offline 时自动跳过）"
+			},
+			chain: CHAIN_PARAMETER
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					industry: {
+						type: "string",
+						required: true
+					},
+					dir: {
+						type: "string",
+						required: true
+					},
+					chainPath: {
+						type: "string",
+						required: true
+					},
+					updated: {
+						type: "boolean",
+						required: true
+					},
+					chain: {
+						type: "json",
+						required: true
+					},
+					gaps: {
+						type: "array",
+						items: { type: "string" },
+						required: true
+					},
+					sources: {
+						type: "array",
+						items: { type: "json" },
+						required: true
+					},
+					seedRefs: {
+						type: "array",
+						items: { type: "string" },
+						required: true
+					},
+					webDigest: {
+						oneOf: [{
+							type: "array",
+							items: { type: "json" }
+						}, { type: "null" }],
+						required: true
+					},
+					webNote: {
+						oneOf: [{ type: "string" }, { type: "null" }],
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const current = value;
+				const lines = [`行业「${current.industry}」产业链图：${current.updated ? "已校验并写入" : "未更新（仅读取）"} ${current.chainPath}`, current.chain === null ? "当前无图：请撰写 chain 后再次调用。" : `节点 ${current.chain.nodes.length} / 边 ${current.chain.edges.length}；缺口 ${current.gaps.length} 项。`];
+				if (current.gaps.length > 0) lines.push(`缺口清单：${current.gaps.join("；")}`);
+				if (current.seedRefs.length > 0) lines.push(`本次登记来源：${current.seedRefs.join(", ")}（共 ${current.sources.length} 条，可用于 sourceRef）`);
+				if (current.webDigest !== null && current.webDigest.length > 0) lines.push(`web 辅助检索 ${current.webDigest.length} 条：${current.webDigest.map((source) => source.title ?? source.url).join("；")}`);
+				if (current.webNote !== null) lines.push(`web 辅助未执行：${current.webNote}`);
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: Math.max(3e4, config.fetchTimeoutMs * 3),
+		async execute(args, exec) {
+			const cwd = workspaceOf(exec);
+			const { dir, name } = industryDirOf(config, cwd, args.industry);
+			const sourcesPath = sourcesPathOf(dir);
+			const registry = await loadSources(sourcesPath);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const seedRefs = [];
+			if (args.seed !== void 0 && args.seed.trim().length > 0) {
+				const notesDir = notesDirOf(dir);
+				await mkdir(notesDir, { recursive: true });
+				const notePath = join(notesDir, `seed-${now.replaceAll(":", "-")}.md`);
+				const noteContent = `# 种子笔记（${now}）\n\n${args.seed.trim()}\n`;
+				await writeFile(notePath, noteContent, "utf8");
+				seedRefs.push(registerSource(registry, notePath, noteContent, now, "seed note"));
+			}
+			for (const file of args.seedFiles ?? []) {
+				const absolute = resolveWorkspaceFile(cwd, file);
+				const content = await readFile(absolute, "utf8");
+				seedRefs.push(registerSource(registry, absolute, content, now, "seed file"));
+			}
+			let webDigest = null;
+			let webNote = null;
+			if (args.web === false) webNote = "调用方指定 web: false";
+			else if (config.offline) webNote = "config.offline 为 true";
+			else {
+				const web = lookupWeb(ctx);
+				if (web === void 0) webNote = "ctx.web 未挂载（可选能力；不影响建图）";
+				else try {
+					const outcome = await web.search({
+						query: `${name} 产业链 上游 中游 下游 结构`,
+						maxResults: 5
+					}, requestSignal(exec.signal, config.fetchTimeoutMs));
+					webDigest = [...outcome.sources];
+					for (const source of outcome.sources) {
+						const digest = `${source.title ?? ""}\n${source.snippet ?? ""}`;
+						seedRefs.push(registerSource(registry, source.url, digest, now, source.title));
+					}
+				} catch (error) {
+					webNote = `web 检索失败：${webErrorMessage(error)}`;
+				}
+			}
+			if (seedRefs.length > 0) await saveSources(sourcesPath, registry);
+			const chainPath = chainPathOf(dir);
+			let updated = false;
+			if (args.chain !== void 0) {
+				const candidate = args.chain;
+				const problems = validateChainMap(candidate);
+				if (problems.length > 0) throw new Error(`chain 校验失败（${problems.length} 项）：${problems.join("；")}`);
+				await mkdir(dir, { recursive: true });
+				await writeFile(chainPath, `${JSON.stringify(candidate, null, 2)}\n`, "utf8");
+				updated = true;
+			}
+			let current = null;
+			try {
+				current = JSON.parse(await readFile(chainPath, "utf8"));
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+			}
+			const gaps = current === null ? ["尚无产业链结构图：请基于 seed 与来源撰写 chain 后再次调用"] : chainGaps(current);
+			if (updated && current !== null) {
+				const payload = {
+					industry: name,
+					path: chainPath,
+					nodes: current.nodes.length,
+					edges: current.edges.length,
+					gaps: gaps.length
+				};
+				ctx.emit("industry-research/map", payload);
+			}
+			return {
+				industry: name,
+				dir,
+				chainPath,
+				updated,
+				chain: current,
+				gaps,
+				sources: registry.items,
+				seedRefs,
+				webDigest,
+				webNote
+			};
+		}
+	});
+}
+//#endregion
+//#region src/timeline.ts
+/**
+* The per-industry timeline store (`timeline.jsonl`): one JSON entry per line,
+* appended by `industry_track`, deduplicated by normalized URL, and capped by
+* `timelineMaxEntries` (oldest entries dropped first). Pure file store — the
+* web retrieval policy lives in `tools/track.ts`.
+* @module dsh-industry-research/timeline
+*/
+/**
+* Normalize a URL for dedupe: lowercase scheme and host, strip default ports,
+* strip a lone trailing slash on the path. Unparseable URLs are returned
+* verbatim (dedupe then falls back to exact string equality).
+* @param url - the raw URL.
+* @returns the normalized dedupe key.
+*/
+function normalizeUrl(url) {
+	try {
+		const parsed = new URL(url);
+		parsed.protocol = parsed.protocol.toLowerCase();
+		parsed.hostname = parsed.hostname.toLowerCase();
+		if (parsed.protocol === "https:" && parsed.port === "443" || parsed.protocol === "http:" && parsed.port === "80") parsed.port = "";
+		if (parsed.pathname.length > 1 && parsed.pathname.endsWith("/")) parsed.pathname = parsed.pathname.slice(0, -1);
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+/**
+* Decide whether a source URL passes the host allow/block lists. Entries are
+* host suffixes (`gov.cn` matches `www.gov.cn`) or URL prefixes
+* (`https://www.gov.cn/zhengce/`). The blocklist wins. An empty allowlist
+* allows every host.
+* @param url - the candidate URL.
+* @param allowlist - configured allow entries.
+* @param blocklist - configured block entries.
+* @returns whether the URL may be tracked.
+*/
+function sourceAllowed(url, allowlist, blocklist) {
+	let host = "";
+	try {
+		host = new URL(url).hostname.toLowerCase();
+	} catch {
+		host = "";
+	}
+	const matches = (entry) => {
+		const normalized = entry.toLowerCase();
+		if (normalized.includes("://")) return url.toLowerCase().startsWith(normalized);
+		return host === normalized || host.endsWith(`.${normalized}`);
+	};
+	if (blocklist.some(matches)) return false;
+	if (allowlist.length === 0) return true;
+	return allowlist.some(matches);
+}
+/**
+* Read a timeline store, tolerating a missing file. Corrupt lines are skipped
+* and counted (never silently: the caller surfaces the count), because a
+* single torn line must not drop the rest of a durable log.
+* @param path - absolute path of the JSONL file.
+* @returns the parsed entries plus the number of skipped corrupt lines.
+*/
+async function readTimeline(path) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return {
+			entries: [],
+			corrupt: 0
+		};
+		throw error;
+	}
+	const entries = [];
+	let corrupt = 0;
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0) continue;
+		try {
+			const parsed = JSON.parse(trimmed);
+			if (typeof parsed.url !== "string" || typeof parsed.title !== "string") throw new Error("missing fields");
+			entries.push(parsed);
+		} catch {
+			corrupt += 1;
+		}
+	}
+	return {
+		entries,
+		corrupt
+	};
+}
+/**
+* Merge a batch into the store and persist: dedupe by normalized URL (both
+* against the store and within the batch), append the survivors, and rewrite
+* the file keeping only the newest `maxEntries` when the cap is exceeded.
+* @param path - absolute path of the JSONL file.
+* @param batch - candidate entries, in arrival order.
+* @param maxEntries - retention cap (oldest dropped first).
+* @returns the merge outcome.
+*/
+async function mergeTimeline(path, batch, maxEntries) {
+	const { entries } = await readTimeline(path);
+	const seen = new Set(entries.map((entry) => normalizeUrl(entry.url)));
+	const added = [];
+	let duplicates = 0;
+	for (const entry of batch) {
+		const key = normalizeUrl(entry.url);
+		if (seen.has(key)) {
+			duplicates += 1;
+			continue;
+		}
+		seen.add(key);
+		added.push(entry);
+	}
+	const merged = [...entries, ...added];
+	const kept = merged.length > maxEntries ? merged.slice(merged.length - maxEntries) : merged;
+	const truncated = kept.length !== merged.length;
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, kept.map((entry) => JSON.stringify(entry)).join("\n") + (kept.length > 0 ? "\n" : ""), "utf8");
+	return {
+		added,
+		duplicates,
+		total: kept.length,
+		truncated
+	};
+}
+//#endregion
+//#region src/tools/track.ts
+/** How many snapshot fetches may run concurrently. */
+const FETCH_CONCURRENCY = 4;
+/**
+* Run `limit`-bounded concurrent workers over `items`.
+* @param items - the work items.
+* @param limit - concurrency bound.
+* @param worker - the per-item async worker.
+*/
+async function pool(items, limit, worker) {
+	let next = 0;
+	const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+		while (next < items.length) {
+			const item = items[next];
+			next += 1;
+			if (item !== void 0) await worker(item);
+		}
+	});
+	await Promise.all(runners);
+}
+/**
+* Build the `industry_track` tool definition.
+* @param ctx - the plugin context (event emission + optional web lookup).
+* @param config - the resolved plugin config.
+* @returns the tool definition to register.
+*/
+function buildIndustryTrackTool(ctx, config) {
+	return defineTool({
+		name: "industry_track",
+		description: "行业研究员的政策与动态跟踪工具：经官方 ctx.web 检索行业政策/要闻，产出带日期、标题、来源 URL、摘要与抓取快照哈希的结构化时间线条目，追加去重写入 timeline.jsonl。只使用公开源；来源不可达或数据缺口会显式列出，禁止编造。仅供研究，不构成投资建议。",
+		parameters: {
+			industry: {
+				type: "string",
+				required: true,
+				description: "行业名（作为目录段，如「白酒」）"
+			},
+			topics: {
+				type: "array",
+				items: { type: "string" },
+				description: "检索主题列表；缺省用「<行业> 行业 政策」与「<行业> 行业 动态 要闻」"
+			},
+			since: {
+				type: "string",
+				description: "只保留该日期（ISO-8601）及之后的条目（按来源发布日期过滤；无日期的来源保留）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					industry: {
+						type: "string",
+						required: true
+					},
+					path: {
+						type: "string",
+						required: true
+					},
+					added: {
+						type: "array",
+						items: { type: "json" },
+						required: true
+					},
+					duplicates: {
+						type: "number",
+						required: true
+					},
+					blocked: {
+						type: "number",
+						required: true
+					},
+					tooOld: {
+						type: "number",
+						required: true
+					},
+					fetchFailed: {
+						type: "array",
+						items: { type: "json" },
+						required: true
+					},
+					total: {
+						type: "number",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					},
+					corruptSkipped: {
+						type: "number",
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const current = value;
+				const lines = [`行业「${current.industry}」政策与动态：新增 ${current.added.length} 条（去重 ${current.duplicates}，拦截 ${current.blocked}，过早 ${current.tooOld}），时间线共 ${current.total} 条 → ${current.path}`];
+				for (const entry of current.added.slice(0, 10)) lines.push(`- ${entry.date ?? "日期未知"} — ${entry.title}（${entry.url}）`);
+				if (current.added.length > 10) lines.push(`- ……其余 ${current.added.length - 10} 条见 timeline.jsonl`);
+				if (current.fetchFailed.length > 0) lines.push(`快照抓取失败 ${current.fetchFailed.length} 条（仍以纯引用条目记录）：${current.fetchFailed.map((failure) => failure.url).join("；")}`);
+				if (current.truncated) lines.push("已达 retention 上限，最旧条目已被裁剪。");
+				if (current.corruptSkipped > 0) lines.push(`警告：跳过 ${current.corruptSkipped} 行损坏的既有时间线记录。`);
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: Math.max(6e4, config.fetchTimeoutMs * config.track.maxFetchesPerCall),
+		async execute(args, exec) {
+			const web = requireWeb(ctx, config, "industry_track");
+			const { dir, name } = industryDirOf(config, workspaceOf(exec), args.industry);
+			const path = timelinePathOf(dir);
+			const topics = (args.topics ?? [`${name} 行业 政策`, `${name} 行业 动态 要闻`]).map((topic) => topic.trim()).filter((topic) => topic.length > 0);
+			if (topics.length === 0) throw new Error("topics must contain at least one non-empty topic");
+			const since = args.since?.trim();
+			if (since !== void 0 && Number.isNaN(Date.parse(since))) throw new Error(`since must be an ISO-8601 date, got ${JSON.stringify(args.since)}`);
+			const byUrl = /* @__PURE__ */ new Map();
+			for (const topic of topics) {
+				const outcome = await web.search({
+					query: topic,
+					maxResults: config.track.maxResultsPerTopic
+				}, requestSignal(exec.signal, config.fetchTimeoutMs));
+				for (const source of outcome.sources) {
+					const existing = byUrl.get(source.url);
+					if (existing !== void 0) {
+						if (!existing.topics.includes(topic)) existing.topics.push(topic);
+						continue;
+					}
+					byUrl.set(source.url, {
+						url: source.url,
+						title: source.title ?? null,
+						snippet: source.snippet ?? null,
+						publishedAt: source.publishedAt ?? null,
+						topics: [topic]
+					});
+				}
+			}
+			let blocked = 0;
+			let tooOld = 0;
+			const candidates = [];
+			for (const candidate of byUrl.values()) {
+				if (!sourceAllowed(candidate.url, config.sourceAllowlist, config.sourceBlocklist)) {
+					blocked += 1;
+					continue;
+				}
+				if (since !== void 0 && candidate.publishedAt !== null) {
+					const published = Date.parse(candidate.publishedAt);
+					if (!Number.isNaN(published) && published < Date.parse(since)) {
+						tooOld += 1;
+						continue;
+					}
+				}
+				candidates.push(candidate);
+			}
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const fetchFailed = [];
+			const snapshots = /* @__PURE__ */ new Map();
+			const fetchable = candidates.slice(0, config.track.maxFetchesPerCall);
+			await pool(fetchable, FETCH_CONCURRENCY, async (candidate) => {
+				try {
+					const outcome = await web.fetch({ url: candidate.url }, requestSignal(exec.signal, config.fetchTimeoutMs));
+					snapshots.set(candidate.url, sha256Of(outcome.body.content));
+				} catch (error) {
+					fetchFailed.push({
+						url: candidate.url,
+						note: webErrorMessage(error)
+					});
+				}
+			});
+			const batch = candidates.map((candidate) => {
+				const snapshotHash = snapshots.get(candidate.url) ?? null;
+				const failure = fetchFailed.find((entry) => entry.url === candidate.url);
+				const beyondBudget = !fetchable.includes(candidate);
+				return {
+					date: candidate.publishedAt,
+					title: candidate.title ?? candidate.url,
+					url: candidate.url,
+					summary: candidate.snippet,
+					snapshotHash,
+					capturedAt: now,
+					topics: candidate.topics,
+					...snapshotHash === null ? { note: failure !== void 0 ? `快照抓取失败：${failure.note}` : beyondBudget ? "超出本次抓取预算，未抓取快照" : "无快照" } : {}
+				};
+			});
+			const { corrupt } = await readTimeline(path);
+			const merge = await mergeTimeline(path, batch, config.timelineMaxEntries);
+			const payload = {
+				industry: name,
+				path,
+				added: merge.added.length,
+				duplicates: merge.duplicates,
+				total: merge.total
+			};
+			ctx.emit("industry-research/track", payload);
+			return {
+				industry: name,
+				path,
+				added: merge.added,
+				duplicates: merge.duplicates,
+				blocked,
+				tooOld,
+				fetchFailed,
+				total: merge.total,
+				truncated: merge.truncated,
+				corruptSkipped: corrupt
+			};
+		}
+	});
+}
+//#endregion
+//#region src/company.ts
+/**
+* Company scan support: read user-supplied data files from the workspace,
+* hash them, extract a lightweight outline (Markdown headings) and
+* figure-candidate lines (lines carrying digits, so every number the model
+* cites can point at a file and a line), and persist the scan card
+* (`card.json` + `card.md`). v1 reads text formats only — no PDF.
+* @module dsh-industry-research/company
+*/
+/** File extensions v1 can read as text. PDF and office formats are out of scope. */
+const READABLE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".md",
+	".txt",
+	".csv",
+	".tsv",
+	".json"
+]);
+/** The research-only disclaimer text shared by cards and reports. */
+const DISCLAIMER = "仅供研究，不构成投资建议";
+/** Maximum length of one surfaced figure-candidate line. */
+const FIGURE_LINE_CAP = 200;
+/** Maximum headings surfaced per file. */
+const OUTLINE_CAP = 50;
+/**
+* Read one containment-verified data file and extract its outline and figure
+* candidates. Unsupported extensions and unreadable entries throw — the tool
+* wraps them into the card's gap list where the contract allows skipping.
+* @param path - absolute, containment-verified file path.
+* @param maxBytes - per-file read cap.
+* @returns the scanned file.
+*/
+async function scanFile(path, maxBytes) {
+	const ext = extname(path).toLowerCase();
+	if (!READABLE_EXTENSIONS.has(ext)) throw new Error(`unsupported data-file extension ${JSON.stringify(ext)} (v1 reads ${[...READABLE_EXTENSIONS].join(", ")}; PDF is out of scope)`);
+	const info = await stat(path);
+	if (!info.isFile()) throw new Error(`not a regular file: ${path}`);
+	if (info.size > maxBytes) throw new Error(`file exceeds scan.maxFileBytes (${info.size} > ${maxBytes}): ${path}`);
+	const content = await readFile(path, "utf8");
+	const lines = content.split("\n");
+	const headings = [];
+	const figures = [];
+	if (ext === ".md") for (const line of lines) {
+		const match = /^#{1,3}\s+(.+?)\s*$/u.exec(line);
+		if (match?.[1] !== void 0 && headings.length < OUTLINE_CAP) headings.push(match[1]);
+	}
+	lines.forEach((raw, index) => {
+		const text = raw.trim();
+		if (text.length === 0 || !/\d/u.test(text)) return;
+		figures.push({
+			path,
+			line: index + 1,
+			text: text.length > FIGURE_LINE_CAP ? `${text.slice(0, FIGURE_LINE_CAP)}…` : text
+		});
+	});
+	return {
+		source: {
+			path,
+			sha256: sha256Of(content),
+			bytes: info.size,
+			lines: lines.length
+		},
+		outline: headings.length > 0 ? {
+			path,
+			headings
+		} : void 0,
+		figures,
+		content
+	};
+}
+/**
+* Persist a company card as `card.json` + `card.md` inside its directory.
+* The Markdown card is a template whose analytical sections stay explicitly
+* 待补 — the tool surfaces evidence (sources, outline, figure candidates); it
+* never invents business structure, financials, or risks.
+* @param dir - absolute company card directory.
+* @param card - the card to persist.
+* @returns the written file paths.
+*/
+async function writeCard(dir, card) {
+	await mkdir(dir, { recursive: true });
+	const cardJsonPath = join(dir, "card.json");
+	const cardPath = join(dir, "card.md");
+	await writeFile(cardJsonPath, `${JSON.stringify(card, null, 2)}\n`, "utf8");
+	await writeFile(cardPath, renderCardMarkdown(card), "utf8");
+	return {
+		cardJsonPath,
+		cardPath
+	};
+}
+/**
+* Render the human-facing Markdown card. Every section that the scan could
+* not fill from evidence is an explicit 待补 line, never prose.
+* @param card - the card to render.
+* @returns the Markdown text.
+*/
+function renderCardMarkdown(card) {
+	const lines = [
+		`# 公司速览卡：${card.name}`,
+		"",
+		`> ${card.disclaimer}。扫描时间（asOf）：${card.asOf}`,
+		"",
+		"## 业务结构",
+		""
+	];
+	if (card.outline.length > 0) {
+		lines.push("数据文件目录结构（供研究定位，非分析结论）：");
+		for (const outline of card.outline) {
+			lines.push(`- \`${outline.path}\``);
+			for (const heading of outline.headings) lines.push(`  - ${heading}`);
+		}
+	} else lines.push("待补：未从数据文件中提取到目录结构。");
+	lines.push("", "## 财务要点", "");
+	if (card.figureCandidates.length > 0) {
+		lines.push(`数字候选行（共 ${card.figureCandidates.length} 行，引用时必须标注文件与行号）：`);
+		for (const figure of card.figureCandidates.slice(0, 20)) lines.push(`- \`${figure.path}\`:${figure.line} — ${figure.text}`);
+		if (card.figureCandidates.length > 20) lines.push(`- ……其余 ${card.figureCandidates.length - 20} 行见 card.json`);
+	} else lines.push("待补：数据文件中未发现数字行。");
+	lines.push("", "## 风险点", "", "待补：由研究者基于来源材料归纳；不得凭空列举。", "", "## 来源清单", "");
+	if (card.sources.length > 0) for (const source of card.sources) lines.push(`- \`${source.path}\` — SHA-256 \`${source.sha256}\`，${source.bytes} 字节，${source.lines} 行`);
+	else lines.push("无用户提供的数据文件。");
+	if (card.webSources !== null) {
+		lines.push("", "公开源检索（ctx.web）：");
+		for (const source of card.webSources) {
+			const label = source.title ?? source.url;
+			const when = source.publishedAt !== void 0 ? `（${source.publishedAt}）` : "";
+			lines.push(`- [${label}](${source.url})${when}`);
+		}
+	}
+	lines.push("", "## 缺口声明", "");
+	if (card.gaps.length > 0) for (const gap of card.gaps) lines.push(`- ${gap}`);
+	else lines.push("无。");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* Load a persisted card (for report assembly). Missing/corrupt cards fail
+* loud to the caller, which decides per-card tolerance.
+* @param cardJsonPath - absolute path of `card.json`.
+* @returns the parsed card.
+*/
+async function readCard(cardJsonPath) {
+	const text = await readFile(cardJsonPath, "utf8");
+	const parsed = JSON.parse(text);
+	if (typeof parsed.name !== "string" || !Array.isArray(parsed.sources) || !Array.isArray(parsed.gaps)) throw new Error(`company card at ${cardJsonPath} is malformed`);
+	return parsed;
+}
+/**
+* Apply the figure-candidate budget to a scan result set, keeping files in
+* scan order and noting the cut in the card gaps when it applies.
+* @param figures - all candidates, in scan order.
+* @param config - resolved config (budget source).
+* @returns the bounded candidate list.
+*/
+function boundFigures(figures, config) {
+	return figures.slice(0, config.scan.maxFigureCandidates);
+}
+//#endregion
+//#region src/tools/company.ts
+/**
+* Build the `company_scan` tool definition.
+* @param ctx - the plugin context (optional web lookup).
+* @param config - the resolved plugin config.
+* @returns the tool definition to register.
+*/
+function buildCompanyScanTool(ctx, config) {
+	return defineTool({
+		name: "company_scan",
+		description: "公司研究员的速览卡工具：以用户提供的工作区数据文件（年报摘录、数据表）为主、ctx.web 公开检索为辅，产出公司速览卡（业务结构 / 财务要点 / 风险点框架），所有数字都能标注来源文件与行号。不接付费/需登录数据源；缺口显式声明，禁止编造公司数字。仅供研究，不构成投资建议。",
+		parameters: {
+			name: {
+				type: "string",
+				required: true,
+				description: "公司名（作为目录段，如「样例酒业」）"
+			},
+			dataFiles: {
+				type: "array",
+				items: { type: "string" },
+				description: "工作区内数据文件的相对路径列表（.md/.txt/.csv/.tsv/.json；v1 不解析 PDF）"
+			},
+			web: {
+				type: "boolean",
+				description: "是否做 web 公开源补充检索（默认 true；config.offline 时自动跳过）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					name: {
+						type: "string",
+						required: true
+					},
+					slug: {
+						type: "string",
+						required: true
+					},
+					dir: {
+						type: "string",
+						required: true
+					},
+					cardPath: {
+						type: "string",
+						required: true
+					},
+					cardJsonPath: {
+						type: "string",
+						required: true
+					},
+					card: {
+						type: "json",
+						required: true
+					},
+					rejected: {
+						type: "array",
+						items: { type: "json" },
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const current = value;
+				const card = current.card;
+				const lines = [`公司速览卡「${card.name}」→ ${current.cardPath}`, `数据文件 ${card.sources.length} 份，数字候选行 ${card.figureCandidates.length} 行（引用数字必须标注文件与行号）。`];
+				if (card.webSources !== null && card.webSources.length > 0) lines.push(`公开源 ${card.webSources.length} 条：${card.webSources.map((source) => source.title ?? source.url).join("；")}`);
+				if (current.rejected.length > 0) lines.push(`未采纳文件 ${current.rejected.length} 份：${current.rejected.map((entry) => `${entry.path}（${entry.reason}）`).join("；")}`);
+				if (card.gaps.length > 0) lines.push(`缺口声明：${card.gaps.join("；")}`);
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: Math.max(3e4, config.fetchTimeoutMs * 3),
+		async execute(args, exec) {
+			const cwd = workspaceOf(exec);
+			const { dir, slug } = companyDirOf(config, cwd, args.name);
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const gaps = [];
+			const rejected = [];
+			const scanned = [];
+			for (const file of args.dataFiles ?? []) {
+				let absolute;
+				try {
+					absolute = resolveWorkspaceFile(cwd, file);
+				} catch (error) {
+					throw error;
+				}
+				try {
+					scanned.push(await scanFile(absolute, config.scan.maxFileBytes));
+				} catch (error) {
+					rejected.push({
+						path: file,
+						reason: error instanceof Error ? error.message : String(error)
+					});
+				}
+			}
+			if ((args.dataFiles ?? []).length === 0) gaps.push("未提供数据文件（dataFiles）：业务结构 / 财务要点 / 风险点均待补");
+			let webSources = null;
+			if (args.web === false) gaps.push("按调用方要求未做 web 公开源检索");
+			else if (config.offline) gaps.push("config.offline 为 true，未做 web 公开源检索");
+			else {
+				const web = lookupWeb(ctx);
+				if (web === void 0) gaps.push("ctx.web 未挂载，未做 web 公开源检索");
+				else try {
+					webSources = (await web.search({
+						query: `${args.name} 公司 业务 简介`,
+						maxResults: 5
+					}, requestSignal(exec.signal, config.fetchTimeoutMs))).sources.map((source) => ({
+						url: source.url,
+						...source.title !== void 0 ? { title: source.title } : {},
+						...source.snippet !== void 0 ? { snippet: source.snippet } : {},
+						...source.publishedAt !== void 0 ? { publishedAt: source.publishedAt } : {}
+					}));
+				} catch (error) {
+					gaps.push(`web 公开源检索失败：${webErrorMessage(error)}`);
+				}
+			}
+			const figures = boundFigures(scanned.flatMap((file) => file.figures), config);
+			const totalFigures = scanned.reduce((sum, file) => sum + file.figures.length, 0);
+			if (totalFigures > figures.length) gaps.push(`数字候选行超出 scan.maxFigureCandidates（${totalFigures} > ${figures.length}），仅保留前 ${figures.length} 行`);
+			if (scanned.length > 0 && totalFigures === 0) gaps.push("数据文件中未发现数字行：财务要点待补");
+			const card = {
+				name: args.name.trim(),
+				slug,
+				asOf: now,
+				sources: scanned.map((file) => file.source),
+				outline: scanned.flatMap((file) => file.outline !== void 0 ? [file.outline] : []),
+				figureCandidates: figures,
+				webSources,
+				gaps,
+				disclaimer: "仅供研究，不构成投资建议"
+			};
+			const { cardJsonPath, cardPath } = await writeCard(dir, card);
+			return {
+				name: card.name,
+				slug,
+				dir,
+				cardPath,
+				cardJsonPath,
+				card,
+				rejected
+			};
+		}
+	});
+}
+//#endregion
+//#region src/report.ts
+/**
+* Report assembly for `industry_report`: load nothing itself — it turns the
+* already-loaded artifacts (chain map, timeline, company cards) into the
+* frozen evidence/sections/claims contract, validates model-authored drafts,
+* auto-drafts when the model supplied none, and renders the builtin-fallback
+* Markdown + manifest when no `ctx.researchReport` engine is mounted.
+* @module dsh-industry-research/report
+*/
+/** The standard auto-draft section keys selectable via the `sections` argument. */
+const AUTO_SECTIONS = [
+	"overview",
+	"chain",
+	"timeline",
+	"companies",
+	"gaps"
+];
+/**
+* Build the frozen-contract evidence list from the loaded artifacts: one
+* entry per artifact file, carrying the verbatim content for byte-level
+* checks.
+* @param artifacts - the loaded artifacts.
+* @param capturedAt - ISO-8601 assembly time recorded on every entry.
+* @returns the evidence list.
+*/
+function buildEvidence(artifacts, capturedAt) {
+	const evidence = [];
+	if (artifacts.chain !== void 0) evidence.push({
+		id: "E-chain",
+		title: "产业链结构图 chain.json",
+		origin: artifacts.chain.path,
+		content: artifacts.chain.content,
+		capturedAt
+	});
+	if (artifacts.timeline !== void 0) evidence.push({
+		id: "E-timeline",
+		title: "政策与动态时间线 timeline.jsonl",
+		origin: artifacts.timeline.path,
+		content: artifacts.timeline.content,
+		capturedAt
+	});
+	for (const { path, content, card } of artifacts.cards) evidence.push({
+		id: `E-company-${card.slug}`,
+		title: `公司速览卡 ${card.name}`,
+		origin: path,
+		content,
+		capturedAt
+	});
+	return evidence;
+}
+/**
+* Validate a draft against the registered evidence: every claim's
+* `evidenceIds` must reference registered evidence, and every `claimIds`
+* reference in the sections must resolve to a registered claim.
+* @param draft - the candidate draft.
+* @param evidenceIds - registered evidence ids.
+* @returns human-readable problems (empty when valid).
+*/
+function validateDraft(draft, evidenceIds) {
+	const problems = [];
+	if (typeof draft.title !== "string" || draft.title.trim().length === 0) problems.push("draft.title must be a non-empty string");
+	if (draft.sections.length === 0) problems.push("draft.sections must not be empty");
+	const claimIds = /* @__PURE__ */ new Set();
+	for (const claim of draft.claims) {
+		if (typeof claim.id !== "string" || claim.id.trim().length === 0) {
+			problems.push("a claim has an empty id");
+			continue;
+		}
+		if (claimIds.has(claim.id)) problems.push(`duplicate claim id "${claim.id}"`);
+		claimIds.add(claim.id);
+		for (const evidenceId of claim.evidenceIds) if (!evidenceIds.has(evidenceId)) problems.push(`claim "${claim.id}" references unknown evidence "${evidenceId}"`);
+	}
+	for (const section of draft.sections) for (const paragraph of section.paragraphs) for (const claimId of paragraph.claimIds ?? []) if (!claimIds.has(claimId)) problems.push(`section "${section.heading}" references unregistered claim "${claimId}"`);
+	return problems;
+}
+/**
+* Build the mechanical draft when the model supplied none: sourced chain
+* metrics and recent timeline entries become claims bound to their artifact
+* evidence; everything unsourced stays a declared gap, never prose.
+* @param industry - the industry display name.
+* @param artifacts - the loaded artifacts.
+* @param sections - which standard sections to include (default all).
+* @returns the auto-built draft.
+*/
+function autoDraft(industry, artifacts, sections = [...AUTO_SECTIONS]) {
+	const wanted = new Set(sections);
+	const claims = [];
+	const draftSections = [];
+	if (wanted.has("overview")) {
+		const presence = [
+			artifacts.chain !== void 0 ? `产业链结构图：${artifacts.chain.map.nodes.length} 节点 / ${artifacts.chain.map.edges.length} 边` : "产业链结构图：缺失",
+			artifacts.timeline !== void 0 ? `政策与动态：${artifacts.timeline.entries.length} 条` : "政策与动态：无",
+			`公司速览卡：${artifacts.cards.length} 张`
+		];
+		draftSections.push({
+			heading: "概览",
+			paragraphs: [{ text: `本报告汇总「${industry}」行业研究工作区内的已有材料：${presence.join("；")}。所有数值均以来源回溯表中的证据为准，缺口见文末清单。` }]
+		});
+	}
+	if (wanted.has("chain")) {
+		const paragraphs = [];
+		if (artifacts.chain !== void 0) {
+			const map = artifacts.chain.map;
+			for (const tier of [
+				"upstream",
+				"midstream",
+				"downstream"
+			]) {
+				const names = map.nodes.filter((node) => node.tier === tier).map((node) => node.name);
+				paragraphs.push({ text: `${tier}：${names.length > 0 ? names.join("、") : "（无节点）"}` });
+			}
+			const edgeText = map.edges.map((edge) => {
+				return `${map.nodes.find((node) => node.id === edge.from)?.name ?? edge.from} → ${map.nodes.find((node) => node.id === edge.to)?.name ?? edge.to}${edge.note !== void 0 ? `（${edge.note}）` : ""}`;
+			});
+			if (edgeText.length > 0) paragraphs.push({ text: `链上关系：${edgeText.join("；")}` });
+			const metricClaims = [];
+			for (const node of map.nodes) node.metrics.forEach((metric, index) => {
+				if (metric.value === void 0 || metric.sourceRef === void 0) return;
+				const id = `C-chain-${node.id}-${index}`;
+				claims.push({
+					id,
+					text: `${node.name} 的 ${metric.key} 为 ${metric.value}${metric.unit ?? ""}${metric.asOf !== void 0 ? `（截至 ${metric.asOf}，来源 ${metric.sourceRef}）` : `（来源 ${metric.sourceRef}）`}`,
+					evidenceIds: ["E-chain"]
+				});
+				metricClaims.push(id);
+			});
+			if (metricClaims.length > 0) paragraphs.push({
+				text: "链上关键指标见 claims 清单（逐条绑定来源证据）。",
+				claimIds: metricClaims
+			});
+			else paragraphs.push({ text: "链上暂无有来源的指标数值（均为待补槽位）。" });
+		} else paragraphs.push({ text: "待补：尚无产业链结构图（先运行 industry_map）。" });
+		draftSections.push({
+			heading: "产业链结构",
+			paragraphs
+		});
+	}
+	if (wanted.has("timeline")) {
+		const paragraphs = [];
+		if (artifacts.timeline !== void 0 && artifacts.timeline.entries.length > 0) {
+			const recent = artifacts.timeline.entries.slice(-10);
+			for (const [index, entry] of recent.entries()) {
+				const id = `C-timeline-${index}`;
+				claims.push({
+					id,
+					text: `${entry.date ?? "日期未知"}：${entry.title}（来源 ${entry.url}）`,
+					evidenceIds: ["E-timeline"]
+				});
+				paragraphs.push({
+					text: `${entry.date ?? "日期未知"} — ${entry.title}`,
+					claimIds: [id]
+				});
+			}
+			if (artifacts.timeline.entries.length > recent.length) paragraphs.push({ text: `（时间线共 ${artifacts.timeline.entries.length} 条，此处仅列最近 ${recent.length} 条。）` });
+		} else paragraphs.push({ text: "待补：尚无政策与动态条目（先运行 industry_track）。" });
+		draftSections.push({
+			heading: "政策与动态",
+			paragraphs
+		});
+	}
+	if (wanted.has("companies")) {
+		const paragraphs = [];
+		if (artifacts.cards.length > 0) for (const { card } of artifacts.cards) paragraphs.push({ text: `「${card.name}」（asOf ${card.asOf}）：数据文件 ${card.sources.length} 份，数字候选行 ${card.figureCandidates.length} 行，缺口 ${card.gaps.length} 项；详见该卡 card.md。` });
+		else paragraphs.push({ text: "待补：尚无公司速览卡（先运行 company_scan）。" });
+		draftSections.push({
+			heading: "公司速览",
+			paragraphs
+		});
+	}
+	if (wanted.has("gaps")) draftSections.push({
+		heading: "缺口与待补",
+		paragraphs: artifacts.gaps.length > 0 ? artifacts.gaps.map((gap) => ({ text: gap })) : [{ text: "本次组装未发现材料级缺口（指标级待补见产业链结构一节）。" }]
+	});
+	return {
+		title: `${industry} 行业研究报告`,
+		sections: draftSections,
+		claims
+	};
+}
+/**
+* Render the builtin-fallback Markdown report: sections with claim footnote
+* markers, a source-traceability appendix with SHA-256 per evidence, and the
+* unverified claims appendix. The fallback never claims independent
+* verification.
+* @param industry - the industry display name.
+* @param draft - the validated draft.
+* @param evidence - the registered evidence.
+* @param generatedAt - ISO-8601 generation time.
+* @returns the Markdown text.
+*/
+function renderFallbackMarkdown(industry, draft, evidence, generatedAt) {
+	const lines = [
+		`# ${draft.title}`,
+		"",
+		`> ${DISCLAIMER}。`,
+		`> 行业：${industry}；生成时间：${generatedAt}；引擎：builtin-fallback（未经过独立核查引擎，claims 未做逐条核查）。`,
+		""
+	];
+	for (const section of draft.sections) {
+		lines.push(`## ${section.heading}`, "");
+		for (const paragraph of section.paragraphs) {
+			const markers = (paragraph.claimIds ?? []).map((id) => `[${id}]`).join("");
+			lines.push(`${paragraph.text}${markers}`, "");
+		}
+	}
+	lines.push("## 附录：来源回溯表", "", "| 证据 | 来源 | SHA-256 | 抓取时间 |", "|---|---|---|---|");
+	for (const item of evidence) lines.push(`| ${item.id} | ${item.title}（\`${item.origin}\`） | \`${sha256Of(item.content)}\` | ${item.capturedAt} |`);
+	lines.push("", "## 附录：claims 清单（builtin-fallback，未核查）", "");
+	if (draft.claims.length > 0) {
+		lines.push("| claim | 内容 | 证据 | 状态 |", "|---|---|---|---|");
+		for (const claim of draft.claims) lines.push(`| ${claim.id} | ${claim.text} | ${claim.evidenceIds.join(", ")} | unverified |`);
+	} else lines.push("无 claims。");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* Write the fallback report directory: `report.md` + `manifest.json`.
+* @param reportDir - absolute target directory (created).
+* @param industry - the industry display name.
+* @param draft - the validated draft.
+* @param evidence - the registered evidence.
+* @param gaps - artifact-level gaps to record in the manifest.
+* @param generatedAt - ISO-8601 generation time.
+* @returns the written file paths.
+*/
+async function writeFallbackReport(reportDir, industry, draft, evidence, gaps, generatedAt) {
+	await mkdir(reportDir, { recursive: true });
+	const reportPath = join(reportDir, "report.md");
+	const manifestPath = join(reportDir, "manifest.json");
+	const manifest = {
+		engine: "builtin-fallback",
+		industry,
+		title: draft.title,
+		generatedAt,
+		disclaimer: DISCLAIMER,
+		evidence: evidence.map((item) => ({
+			id: item.id,
+			title: item.title,
+			origin: item.origin,
+			sha256: sha256Of(item.content),
+			capturedAt: item.capturedAt,
+			bytes: Buffer.byteLength(item.content, "utf8")
+		})),
+		claims: draft.claims.map((claim) => ({
+			...claim,
+			status: "unverified"
+		})),
+		gaps: [...gaps]
+	};
+	await writeFile(reportPath, renderFallbackMarkdown(industry, draft, evidence, generatedAt), "utf8");
+	await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+	return {
+		reportPath,
+		manifestPath
+	};
+}
+/**
+* The report directory name for one generation: `<YYYYMMDD-HHmmss>` with a
+* numeric suffix when the same second collides.
+* @param at - the generation time.
+* @param exists - whether a candidate directory already exists.
+* @returns the directory name (not a path).
+*/
+function reportDirName(at, exists) {
+	const pad = (value) => String(value).padStart(2, "0");
+	const base = `${at.getFullYear()}${pad(at.getMonth() + 1)}${pad(at.getDate())}-${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}`;
+	if (!exists(base)) return base;
+	for (let suffix = 2;; suffix += 1) {
+		const candidate = `${base}-${suffix}`;
+		if (!exists(candidate)) return candidate;
+	}
+}
+//#endregion
+//#region src/engine-bridge.ts
+/**
+* Look up the optional report engine.
+* @param ctx - the plugin context.
+* @returns the engine surface, or undefined when no engine is mounted.
+*/
+function lookupEngine(ctx) {
+	return ctx.get("researchReport");
+}
+//#endregion
+//#region src/tools/report.ts
+/**
+* The `industry_report` tool: assemble one industry's report from the
+* workspace artifacts (chain map, timeline, company cards). With a mounted
+* `ctx.researchReport` engine the evidence/sections/claims go to its
+* `assemble` and the sealed directory plus per-claim verdicts come back;
+* without one the builtin fallback renders versioned Markdown
+* (`reports/<YYYYMMDD-HHmmss>/report.md` + `manifest.json` with the
+* source-traceability table) and says so honestly (`engine:
+* 'builtin-fallback'`). The model may author the draft (sections + claims) or
+* leave it to the mechanical auto-draft.
+* @module dsh-industry-research/tools/report
+*/
+/** The draft parameter schema (semantic reference checks live in {@link validateDraft}). */
+const DRAFT_PARAMETER = {
+	type: "object",
+	properties: {
+		title: {
+			type: "string",
+			description: "报告标题；缺省「<行业> 行业研究报告」"
+		},
+		sections: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				properties: {
+					heading: {
+						type: "string",
+						required: true
+					},
+					paragraphs: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							properties: {
+								text: {
+									type: "string",
+									required: true
+								},
+								claimIds: {
+									type: "array",
+									items: { type: "string" },
+									description: "本段引用的 claim id 列表"
+								}
+							},
+							additionalProperties: false
+						}
+					}
+				},
+				additionalProperties: false
+			}
+		},
+		claims: {
+			type: "array",
+			required: true,
+			items: {
+				type: "object",
+				properties: {
+					id: {
+						type: "string",
+						required: true,
+						description: "claim id（如 C1）"
+					},
+					text: {
+						type: "string",
+						required: true,
+						description: "断言内容（数字须与证据一致）"
+					},
+					evidenceIds: {
+						type: "array",
+						items: { type: "string" },
+						required: true,
+						description: "支撑证据 id（E-chain / E-timeline / E-company-<slug>）"
+					}
+				},
+				additionalProperties: false
+			}
+		}
+	},
+	additionalProperties: false,
+	description: "模型撰写的报告草稿；缺省时由工具按已有材料机械组装"
+};
+/**
+* Load every artifact a report assembles from. Missing artifacts are gaps,
+* not failures; unreadable ones are gaps with the reason recorded.
+* @param config - resolved plugin config.
+* @param cwd - absolute workspace root.
+* @param industry - validated industry argument.
+* @param companies - optional company-name filter for card inclusion.
+* @returns the loaded artifacts.
+*/
+async function loadArtifacts(config, cwd, industry, companies) {
+	const { root, dir } = industryDirOf(config, cwd, industry);
+	const gaps = [];
+	const artifacts = {
+		cards: [],
+		gaps
+	};
+	const chainPath = chainPathOf(dir);
+	try {
+		const content = await readFile(chainPath, "utf8");
+		const map = JSON.parse(content);
+		artifacts.chain = {
+			path: chainPath,
+			content,
+			map
+		};
+		gaps.push(...chainGaps(map));
+	} catch (error) {
+		if (error.code === "ENOENT") gaps.push("缺少产业链结构图 chain.json（先运行 industry_map）");
+		else gaps.push(`chain.json 读取/解析失败：${error instanceof Error ? error.message : String(error)}`);
+	}
+	const timelinePath = timelinePathOf(dir);
+	try {
+		const content = await readFile(timelinePath, "utf8");
+		const { entries, corrupt } = await readTimeline(timelinePath);
+		if (entries.length > 0) artifacts.timeline = {
+			path: timelinePath,
+			content,
+			entries
+		};
+		else gaps.push("timeline.jsonl 为空：尚无政策与动态条目（先运行 industry_track）");
+		if (corrupt > 0) gaps.push(`timeline.jsonl 有 ${corrupt} 行损坏已跳过`);
+	} catch (error) {
+		if (error.code === "ENOENT") gaps.push("缺少政策与动态 timeline.jsonl（先运行 industry_track）");
+		else throw error;
+	}
+	const companiesDir = join(root, "companies");
+	let slugs = [];
+	if (companies !== void 0 && companies.length > 0) slugs = companies.map((company) => companyDirOf(config, cwd, company).slug);
+	else try {
+		slugs = (await readdir(companiesDir, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	for (const slug of slugs) {
+		const cardJsonPath = join(companiesDir, slug, "card.json");
+		try {
+			const content = await readFile(cardJsonPath, "utf8");
+			const card = await readCard(cardJsonPath);
+			artifacts.cards.push({
+				path: cardJsonPath,
+				content,
+				card
+			});
+		} catch (error) {
+			if (error.code === "ENOENT") gaps.push(`公司「${slug}」无速览卡（先运行 company_scan）`);
+			else gaps.push(`公司「${slug}」的 card.json 读取/解析失败：${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	if (artifacts.cards.length === 0 && slugs.length === 0) gaps.push("尚无公司速览卡（可选：运行 company_scan 补充公司维度）");
+	return artifacts;
+}
+/**
+* Build the `industry_report` tool definition.
+* @param ctx - the plugin context (event emission + optional engine lookup).
+* @param config - the resolved plugin config.
+* @returns the tool definition to register.
+*/
+function buildIndustryReportTool(ctx, config) {
+	return defineTool({
+		name: "industry_report",
+		description: "行业研究员的报告组装工具：汇总产业链结构图、政策时间线与公司速览卡，产出可核查的行业研究报告。挂载 ctx.researchReport 引擎时提交其 assemble 封存并回传逐 claim 核查结论；否则走内置降级路径（版本化 Markdown + 来源回溯表，如实标注 engine: builtin-fallback）。数字均须对应来源证据；仅供研究，不构成投资建议。",
+		parameters: {
+			industry: {
+				type: "string",
+				required: true,
+				description: "行业名（作为目录段，如「白酒」）"
+			},
+			sections: {
+				type: "array",
+				items: {
+					type: "string",
+					enum: [...AUTO_SECTIONS]
+				},
+				description: `自动草稿包含哪些标准小节（${AUTO_SECTIONS.join("/")}）；提供 draft 时忽略`
+			},
+			companies: {
+				type: "array",
+				items: { type: "string" },
+				description: "纳入报告的公司名列表；缺省纳入 companies/ 下全部速览卡"
+			},
+			draft: DRAFT_PARAMETER
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					industry: {
+						type: "string",
+						required: true
+					},
+					engine: {
+						type: "string",
+						enum: ["research-report", "builtin-fallback"],
+						required: true
+					},
+					reportDir: {
+						type: "string",
+						required: true
+					},
+					reportPath: {
+						oneOf: [{ type: "string" }, { type: "null" }],
+						required: true
+					},
+					manifestPath: {
+						oneOf: [{ type: "string" }, { type: "null" }],
+						required: true
+					},
+					sealHash: {
+						oneOf: [{ type: "string" }, { type: "null" }],
+						required: true
+					},
+					verdicts: {
+						oneOf: [{
+							type: "array",
+							items: { type: "json" }
+						}, { type: "null" }],
+						required: true
+					},
+					claims: {
+						type: "number",
+						required: true
+					},
+					evidence: {
+						type: "number",
+						required: true
+					},
+					gaps: {
+						type: "array",
+						items: { type: "string" },
+						required: true
+					},
+					generatedAt: {
+						type: "string",
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const current = value;
+				const lines = current.engine === "research-report" ? [`行业「${current.industry}」研究报告已经独立核查引擎封存 → ${current.reportDir}`, `sealHash：${current.sealHash ?? ""}；claims ${current.claims} 条（verified ${(current.verdicts ?? []).filter((verdict) => verdict.status === "verified").length} 条）。`] : [`行业「${current.industry}」研究报告（builtin-fallback，未经过独立核查引擎）→ ${current.reportPath}`, `claims ${current.claims} 条均标记 unverified；来源回溯表见 report.md 附录与 ${current.manifestPath ?? ""}。`];
+				if (current.gaps.length > 0) lines.push(`缺口声明：${current.gaps.join("；")}`);
+				lines.push("仅供研究，不构成投资建议。");
+				return [{
+					type: "text",
+					text: lines.join("\n")
+				}];
+			}
+		},
+		timeoutMs: 6e4,
+		async execute(args, exec) {
+			const cwd = workspaceOf(exec);
+			const { dir, name } = industryDirOf(config, cwd, args.industry);
+			const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
+			const artifacts = await loadArtifacts(config, cwd, name, args.companies);
+			const evidence = buildEvidence(artifacts, generatedAt);
+			const evidenceIds = new Set(evidence.map((item) => item.id));
+			let draft;
+			if (args.draft !== void 0) {
+				draft = {
+					title: args.draft.title ?? `${name} 行业研究报告`,
+					sections: args.draft.sections,
+					claims: args.draft.claims
+				};
+				const problems = validateDraft(draft, evidenceIds);
+				if (problems.length > 0) throw new Error(`draft 校验失败（${problems.length} 项）：${problems.join("；")}（已登记证据：${[...evidenceIds].join(", ") || "无"}）`);
+			} else draft = autoDraft(name, artifacts, args.sections ?? [...AUTO_SECTIONS]);
+			const engine = lookupEngine(ctx);
+			let value;
+			if (engine !== void 0) {
+				const result = await engine.assemble({
+					title: draft.title,
+					topic: name,
+					evidence,
+					sections: draft.sections,
+					claims: draft.claims
+				});
+				value = {
+					industry: name,
+					engine: "research-report",
+					reportDir: result.reportDir,
+					reportPath: null,
+					manifestPath: null,
+					sealHash: result.sealHash,
+					verdicts: result.verdicts,
+					claims: draft.claims.length,
+					evidence: evidence.length,
+					gaps: artifacts.gaps,
+					generatedAt
+				};
+			} else {
+				const reportsDir = reportsDirOf(dir);
+				const dirName = reportDirName(/* @__PURE__ */ new Date(), (candidate) => existsSync(join(reportsDir, candidate)));
+				const reportDir = join(reportsDir, dirName);
+				const { reportPath, manifestPath } = await writeFallbackReport(reportDir, name, draft, evidence, artifacts.gaps, generatedAt);
+				value = {
+					industry: name,
+					engine: "builtin-fallback",
+					reportDir,
+					reportPath,
+					manifestPath,
+					sealHash: null,
+					verdicts: null,
+					claims: draft.claims.length,
+					evidence: evidence.length,
+					gaps: artifacts.gaps,
+					generatedAt
+				};
+			}
+			const payload = {
+				industry: name,
+				engine: value.engine,
+				reportDir: value.reportDir,
+				claims: value.claims,
+				evidence: value.evidence
+			};
+			ctx.emit("industry-research/report", payload);
+			return value;
+		}
+	});
+}
+//#endregion
+//#region src/version.ts
+/**
+* Single source of truth for the package version (stamped by the release
+* script together with package.json and CHANGELOG.md).
+* @module dsh-industry-research/version
+*/
+/** The package version. */
+const VERSION = "0.1.0";
+//#endregion
+//#region src/index.ts
+/**
+* `dsh-industry-research` — industry and company research domain pack for
+* DeepSeek Harness. Mounts four workspace-bound research tools
+* (`industry_map` / `industry_track` / `company_scan` / `industry_report`),
+* publishes two methodology skills (`industry-research-method`,
+* `company-research-method`) from the packaged `skills/` directory, and emits
+* typed Cordis events after each committed artifact. The web capability
+* (`ctx.web`) and the report engine (`ctx.researchReport`) are optional and
+* looked up structurally at execution time — never injected. Research only;
+* not investment advice.
+*
+* Function plugin — no default export (the Loader unwraps
+* `exports.default ?? exports`, and a stray default would discard
+* `name`/`inject`/`Config`/`apply`).
+* @module dsh-industry-research
+*/
+const name = "industry-research";
+/** The four tools and the skill provider; web/engine stay optional lookups. */
+const inject = ["skills", "tools"];
+/** Directory of this module: `src/` under tsx/vitest or `lib/` when built. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+/** Whether a directory contains at least one `<skill>/SKILL.md` bundle. */
+function hasSkillBundles(dir) {
+	if (!existsSync(dir)) return false;
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	return entries.some((entry) => entry.isDirectory() && existsSync(join(dir, entry.name, "SKILL.md")));
+}
+/**
+* Resolve the skills root to publish and fail loud on misconfiguration: an
+* explicit `skillsDir` must exist and hold bundles, and the packaged default
+* (`skills/` beside `src/` or `lib/`) must exist — never mount silently with
+* zero skills.
+* @param skillsDir - explicit config override, if any.
+* @returns the validated skills root.
+*/
+function resolveSkillsRoot(skillsDir) {
+	if (skillsDir !== void 0) {
+		const root = resolve(skillsDir);
+		if (!hasSkillBundles(root)) throw new Error(`industry-research: config.skillsDir "${skillsDir}" does not exist or contains no <skill>/SKILL.md bundles`);
+		return root;
+	}
+	const root = join(MODULE_DIR, "..", "skills");
+	if (!hasSkillBundles(root)) throw new Error(`industry-research: packaged skills root ${root} is missing; expected skills/<name>/SKILL.md bundles beside the built lib/. Set config.skillsDir to an explicit root.`);
+	return root;
+}
+/**
+* Mount the research pack: validate config (fail loud), publish the packaged
+* skills, and register the four tools. With `enabled: false` nothing is
+* registered and the plugin stays inert.
+* @param ctx - the plugin context (host).
+* @param config - raw plugin config.
+*/
+function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	const logger = ctx.logger("industry-research");
+	if (!resolved.enabled) {
+		logger.info("disabled: enabled is false — no research capabilities are mounted");
+		return;
+	}
+	const skillsRoot = resolveSkillsRoot(resolved.skillsDir);
+	ctx.effect(function* () {
+		yield ctx.skills.registerProvider((control) => new FileSystemSkillProvider(ctx, control, {
+			providerName: "industry-research",
+			includeDefaultRoots: false,
+			customSkillDirs: [skillsRoot],
+			watch: false
+		}));
+	});
+	ctx.tools.register(buildIndustryMapTool(ctx, resolved));
+	ctx.tools.register(buildIndustryTrackTool(ctx, resolved));
+	ctx.tools.register(buildCompanyScanTool(ctx, resolved));
+	ctx.tools.register(buildIndustryReportTool(ctx, resolved));
+	logger.info(`industry-research ${VERSION} mounted: 4 tools, skills from ${skillsRoot}`);
+}
+//#endregion
+export { AUTO_SECTIONS, CHAIN_TIERS, Config, DISCLAIMER, READABLE_EXTENSIONS, VERSION, apply, autoDraft, boundFigures, buildCompanyScanTool, buildEvidence, buildIndustryMapTool, buildIndustryReportTool, buildIndustryTrackTool, chainGaps, chainPathOf, companyDirOf, industryDirOf, inject, loadArtifacts, loadSources, lookupEngine, lookupWeb, mergeTimeline, name, normalizeUrl, notesDirOf, readCard, readTimeline, registerSource, renderCardMarkdown, renderFallbackMarkdown, reportDirName, reportsDirOf, requestSignal, requireWeb, resolveConfig, resolveContained, resolveIndustryRoot, resolveWorkspaceFile, safeSegment, saveSources, scanFile, sha256Of, sourceAllowed, sourcesPathOf, timelinePathOf, validateChainMap, validateDraft, webErrorMessage, workspaceOf, writeCard, writeFallbackReport };