@sparkelf/dsh-dataops-managed 0.3.21 → 0.3.22

package/lib/index.js

@@ -5,10 +5,34 @@ import * as McpClient from "@sparkelf/dsh-plugin-mcp-credentials";
 import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
 //#region src/auth-state.ts
 let state = "unknown";
+const listeners = /* @__PURE__ */ new Set();
+/**
+* Observe every recorded transition.
+*
+* The tool manager uses this to drop its disclosure as soon as any DataOps call reports a 401:
+* the scope that produced the tool list can no longer be trusted, and waiting for another
+* explicit sync would leave tools offered against an ended session. Listener failures are
+* contained so a broken observer cannot turn a credential observation into a failed call.
+* @param listener - Called with the new state after it is recorded.
+* @returns The exact unsubscriber.
+*/
+const onAuthStateChange = (listener) => {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+};
+/** Record one observation and notify observers. */
+const setState = (next) => {
+	state = next;
+	for (const listener of listeners) try {
+		listener(next);
+	} catch {}
+};
 /**
 * Record that a DataOps call was accepted.
 *
@@ -16,11 +40,11 @@ let state = "unknown";
 * says the session is fine and the permission is not, so it must not raise the sign-in prompt.
 */
 const noteAccepted = () => {
-	state = "valid";
+	setState("valid");
 };
 /** Record that DataOps refused the credential, which means the session is over. */
 const noteExpired = () => {
-	state = "expired";
+	setState("expired");
 };
 /**
 * Read the current observation.
@@ -28,6 +52,12 @@ const noteExpired = () => {
 * @returns `unknown` before any call has completed, then what the last one said.
 */
 const currentAuthState = () => state;
+/**
+* Test-only reset, so one case cannot leak its observation into the next.
+*/
+const resetAuthState = () => {
+	setState("unknown");
+};
 //#endregion
 //#region src/model-settings.ts
 /** Profile entry id whose Config holds the model providers. */
@@ -811,63 +841,401 @@ var ReviewApi = class {
 	}
 };
 //#endregion
-//#region src/tools.ts
-const open = {
-	type: "object",
-	additionalProperties: true
+//#region src/tool-scope.ts
+/**
+* Tool-to-capability disclosure map.
+*
+* `review_notifications_list/read` intentionally carry no policy: every authenticated principal
+* owns their own notification inbox. `dataops_api_docs` is gated by the role itself because the
+* backend grants the OpenAPI reader to 超级管理员 by default; an administrator who happens to hold
+* `developer:openapi:read` is still outside that role and does not receive the tool.
+*/
+const AI_TOOL_ACCESS = {
+	skill_list: { permission: "skill:read" },
+	skill_get: { permission: "skill:read" },
+	skill_submit: { permission: "skill:submit" },
+	skill_install: { permission: "skill:install" },
+	skill_uninstall: { permission: "skill:install" },
+	skill_enable: { permission: "skill:manage" },
+	skill_disable: { permission: "skill:manage" },
+	skill_unshare: { permission: "skill:manage" },
+	skill_delete: { permission: "skill:manage" },
+	review_scan: {
+		permission: "skill:read",
+		reviewer: true
+	},
+	review_decide: {
+		permission: "skill:review:decide",
+		reviewer: true
+	},
+	review_notifications_list: {},
+	review_notifications_read: {},
+	dataops_api_docs: { superAdminOnly: true }
 };
-const render = (_args, value) => [{
-	type: "text",
-	text: JSON.stringify(value, null, 2)
-}];
+/** Every managed tool name, in the order the manager considers them. */
+const AI_TOOL_NAMES = Object.keys(AI_TOOL_ACCESS);
+/**
+* Backend permission aliases.
+*
+* The DataOps role matrix stores the capability family as `skill:capability:*`; this task's
+* disclosure contract names them `skill:*`. Accepting both keeps the plugin working against
+* either spelling without asking the backend to rename a published key.
+*/
+const PERMISSION_ALIASES = {
+	"skill:read": ["skill:read", "skill:capability:read"],
+	"skill:submit": ["skill:submit", "skill:capability:submit"],
+	"skill:install": ["skill:install", "skill:capability:install"],
+	"skill:manage": ["skill:manage", "skill:capability:manage"],
+	"skill:review:decide": ["skill:review:decide"]
+};
+const SUPER_ADMIN = "超级管理员";
+const ADMIN = "管理员";
+const DEPARTMENT_ADMIN = "部门管理员";
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const strings$1 = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : void 0;
 const roleSet = (scope) => new Set(scope.roleCodes ?? []);
-const isSuper = (scope) => roleSet(scope).has("超级管理员") || scope.primaryRole === "超级管理员";
-const isAdmin = (scope) => isSuper(scope) || roleSet(scope).has("管理员") || scope.primaryRole === "管理员";
-const isDeptAdmin = (scope) => roleSet(scope).has("部门管理员") || scope.primaryRole === "部门管理员";
-const canReview = (scope) => scope.review?.canReview === true || isAdmin(scope) || isDeptAdmin(scope);
-const forbidden = (message) => /* @__PURE__ */ new Error("Forbidden (403): " + message);
-/** Permission codes from the context, tolerating either field name during rollout. */
-const permissionsOf = (scope) => new Set(scope.permissions ?? scope.permissionKeys ?? []);
+/** Whether the context carries the stable super-administrator role. */
+const isSuperAdmin = (scope) => roleSet(scope).has(SUPER_ADMIN) || scope.primaryRole === SUPER_ADMIN || (scope.systemKeys ?? []).includes("SUPER_ADMIN");
+/** Whether the context carries an administrator or super-administrator role. */
+const isAdmin = (scope) => isSuperAdmin(scope) || roleSet(scope).has(ADMIN) || scope.primaryRole === ADMIN || (scope.systemKeys ?? []).includes("ADMIN");
+/** Whether the context carries a department-administrator role. */
+const isDepartmentAdmin = (scope) => roleSet(scope).has(DEPARTMENT_ADMIN) || scope.primaryRole === DEPARTMENT_ADMIN || (scope.systemKeys ?? []).includes("DEPT_ADMIN");
+/**
+* Whether the caller may run review operations.
+*
+* The current backend returns `canReview` at the top level; the nested `review` shape is
+* accepted for older contexts. Role membership is a fallback, not an override.
+*/
+const canReview = (scope) => scope.canReview === true || scope.review?.canReview === true || isAdmin(scope) || isDepartmentAdmin(scope);
+/** The effective permission list, or `undefined` for a context that predates permission keys. */
+const permissionList = (scope) => scope.permissions ?? scope.permissionKeys;
 /**
-* Whether the caller holds one `skill:*` capability.
+* Whether the caller holds one capability.
 *
-* The context is the authority once it carries a permission list; before task-70 ships,
-* the role-name fallback keeps the existing four-role behavior. A present-but-empty list is
-* a denial, not a reason to fall back: an authenticated user with no keys must not inherit
-* administrator powers from their role label alone.
+* A context that carries a permission list is authoritative. Before the list existed, the
+* four-role fallback kept the old behavior; it is only used when neither spelling is present.
 */
-const hasSkillPermission = (scope, key) => {
-	const permissions = permissionsOf(scope);
-	if (scope.permissions !== void 0 || scope.permissionKeys !== void 0) return permissions.has(key);
+const hasPermission = (scope, key) => {
+	const permissions = permissionList(scope);
+	if (permissions !== void 0) {
+		const set = new Set(permissions);
+		return (PERMISSION_ALIASES[key] ?? [key]).some((alias) => set.has(alias));
+	}
 	if (isAdmin(scope)) return true;
-	if (isDeptAdmin(scope)) return key !== "skill:review:global";
+	if (isDepartmentAdmin(scope)) return key !== "skill:review:global";
+	if (roleSet(scope).size === 0) return false;
 	return key === "skill:read" || key === "skill:install" || key === "skill:submit";
 };
-const requireSkillPermission = (scope, key) => {
-	if (!hasSkillPermission(scope, key)) throw forbidden("missing permission " + key);
-};
-/** Fetch and validate the caller's DataOps scope. */
-async function loadScope(api) {
-	const result = await api.request("/api/ai/review/context");
-	if (result.status === 401) throw new Error("Unauthorized (401): DataOps session expired");
-	if (result.status === 403) throw forbidden("no review context");
-	if (result.status !== 200) throw new Error("review context failed: HTTP " + result.status.toString());
-	const body = result.body;
-	if (body === null || typeof body.roleCodes !== "object" || !Array.isArray(body.roleCodes)) throw new Error("review context is missing roleCodes");
-	return body;
+/**
+* Whether one tool should be registered for this scope.
+*
+* Every check is disclosure metadata, not an execution gate: a visible tool still lets DataOps
+* answer with 403 when the underlying grant changed between a scope sync and the call.
+*/
+function isToolVisible(name, scope) {
+	const policy = AI_TOOL_ACCESS[name];
+	if (policy.superAdminOnly === true && !isSuperAdmin(scope)) return false;
+	if (policy.reviewer === true && !canReview(scope)) return false;
+	if (policy.permission !== void 0 && !hasPermission(scope, policy.permission)) return false;
+	return true;
+}
+/**
+* Validate one `/api/ai/review/context` body.
+*
+* A body without `roleCodes` is not a usable scope: treating it as "no roles" would let the
+* role-name fallback hand an ordinary capability set to an answer this plugin cannot interpret.
+* @param body - Parsed JSON from the context endpoint.
+* @returns The normalized scope, or undefined when the answer is not a context document.
+*/
+function normalizeScope(body) {
+	if (!isRecord$1(body)) return void 0;
+	const roleCodes = strings$1(body.roleCodes);
+	if (roleCodes === void 0) return void 0;
+	const roleSystemKeys = (Array.isArray(body.roles) ? body.roles : []).flatMap((entry) => {
+		if (!isRecord$1(entry)) return [];
+		return typeof entry.systemKey === "string" ? [entry.systemKey] : [];
+	});
+	const explicitSystemKeys = strings$1(body.systemKeys) ?? [];
+	const systemKeys = Array.from(/* @__PURE__ */ new Set([...explicitSystemKeys, ...roleSystemKeys]));
+	const permissions = strings$1(body.permissions) ?? (Array.isArray(body.permissionKeys) ? strings$1(body.permissionKeys) : void 0);
+	const review = isRecord$1(body.review) ? {
+		...typeof body.review.canReview === "boolean" ? { canReview: body.review.canReview } : {},
+		...typeof body.review.canReviewGlobal === "boolean" ? { canReviewGlobal: body.review.canReviewGlobal } : {},
+		...typeof body.review.canManagePermissions === "boolean" ? { canManagePermissions: body.review.canManagePermissions } : {}
+	} : void 0;
+	return {
+		...typeof body.userId === "string" ? { userId: body.userId } : {},
+		...typeof body.username === "string" ? { username: body.username } : {},
+		roleCodes,
+		...typeof body.primaryRole === "string" ? { primaryRole: body.primaryRole } : {},
+		...systemKeys.length === 0 ? {} : { systemKeys },
+		...typeof body.departmentCode === "string" || body.departmentCode === null ? { departmentCode: body.departmentCode } : {},
+		...permissions === void 0 ? {} : { permissions },
+		...isRecord$1(body.dataScope) ? { dataScope: body.dataScope } : {},
+		...review === void 0 ? {} : { review },
+		...typeof body.canReview === "boolean" ? { canReview: body.canReview } : {},
+		...typeof body.canReviewGlobal === "boolean" ? { canReviewGlobal: body.canReviewGlobal } : {}
+	};
+}
+//#endregion
+//#region src/api-docs.ts
+/** Raised when the upstream body is not an OpenAPI document this module can search. */
+var ApiDocsUnavailableError = class extends Error {};
+/** HTTP methods a path item may declare, in a stable presentation order. */
+const HTTP_METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"head",
+	"options",
+	"trace"
+];
+/** Cap on returned operations, so one broad query cannot flood a model turn. */
+const MAX_RESULTS = 50;
+/** Cap on projected schema properties. */
+const MAX_PROPERTIES = 25;
+/** Cap on projected parameters. */
+const MAX_PARAMETERS = 25;
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const strings = (value) => Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : void 0;
+const normalized = (value) => (value ?? "").trim().toLowerCase();
+/** Split a query into whitespace-separated keywords; an empty query matches everything. */
+const keywords = (query) => normalized(query).split(/\s+/u).filter((token) => token !== "");
+/** Resolve one local JSON pointer such as `#/components/schemas/ReviewQuery`. */
+function resolvePointer(document, ref) {
+	if (!ref.startsWith("#/")) return void 0;
+	let current = document;
+	for (const raw of ref.slice(2).split("/")) {
+		if (!isRecord(current)) return void 0;
+		const key = decodeURIComponent(raw).replace(/~1/gu, "/").replace(/~0/gu, "~");
+		current = current[key];
+	}
+	return current;
+}
+/** Resolve one `$ref` object one level, leaving a non-reference value unchanged. */
+function dereference(value, document, depth = 0) {
+	if (!isRecord(value) || typeof value.$ref !== "string" || depth >= 4) return value;
+	return dereference(resolvePointer(document, value.$ref), document, depth + 1);
+}
+/** The final segment of a local reference, used as a stable type label. */
+function refName(ref) {
+	const segment = ref.split("/").pop() ?? ref;
+	return decodeURIComponent(segment).replace(/~1/gu, "/").replace(/~0/gu, "~");
+}
+/** A short type label for one schema, resolving one local reference chain when useful. */
+function schemaType(schema, document, depth = 0) {
+	const resolved = dereference(schema, document, depth);
+	if (!isRecord(resolved)) return "unknown";
+	if (typeof resolved.type === "string") {
+		if (resolved.type === "array" && isRecord(resolved.items)) return schemaType(resolved.items, document, depth + 1) + "[]";
+		return resolved.type;
+	}
+	if (isRecord(resolved.properties)) return "object";
+	if (resolved.items !== void 0) return "array";
+	if (typeof resolved.$ref === "string") return refName(resolved.$ref);
+	return "unknown";
+}
+/** Project one schema into a bounded summary without following cycles forever. */
+function summarizeSchema(schema, document, depth = 0) {
+	if (!isRecord(schema)) return null;
+	const ref = typeof schema.$ref === "string" ? refName(schema.$ref) : void 0;
+	const resolved = dereference(schema, document, depth);
+	if (!isRecord(resolved)) return ref === void 0 ? null : { ref };
+	const required = strings(resolved.required) ?? [];
+	const requiredSet = new Set(required);
+	const properties = isRecord(resolved.properties) ? Object.entries(resolved.properties).slice(0, MAX_PROPERTIES).map(([name, property]) => ({
+		name,
+		type: schemaType(property, document, depth + 1),
+		required: requiredSet.has(name)
+	})) : void 0;
+	const type = typeof resolved.type === "string" ? resolved.type : isRecord(resolved.properties) ? "object" : resolved.items === void 0 ? void 0 : "array";
+	return {
+		...type === void 0 ? {} : { type },
+		...ref === void 0 ? {} : { ref },
+		...required.length === 0 ? {} : { required },
+		...properties === void 0 ? {} : { properties }
+	};
+}
+/** Merge path-level and operation-level parameters; the operation wins on name+location. */
+function summarizeParameters(pathItem, operation, document) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const source of [pathItem.parameters, operation.parameters]) {
+		if (!Array.isArray(source)) continue;
+		for (const raw of source) {
+			const parameter = dereference(raw, document);
+			if (!isRecord(parameter)) continue;
+			if (typeof parameter.name !== "string" || typeof parameter.in !== "string") continue;
+			const schema = parameter.schema !== void 0 ? parameter.schema : parameter;
+			merged.set(parameter.in + ":" + parameter.name, {
+				name: parameter.name,
+				in: parameter.in,
+				required: parameter.required === true,
+				type: schemaType(schema, document)
+			});
+		}
+	}
+	return [...merged.values()].slice(0, MAX_PARAMETERS);
+}
+/** Describe the request body's chosen media type and bounded schema fields. */
+function summarizeRequestBody(operation, document) {
+	const body = dereference(operation.requestBody, document);
+	if (!isRecord(body) || !isRecord(body.content)) return null;
+	const contentTypes = Object.keys(body.content);
+	if (contentTypes.length === 0) return null;
+	const preferred = contentTypes.includes("application/json") ? "application/json" : contentTypes[0];
+	const media = body.content[preferred];
+	const schema = isRecord(media) ? summarizeSchema(media.schema, document) : null;
+	return {
+		required: body.required === true,
+		contentTypes,
+		schema
+	};
+}
+/** The security requirement list that applies to one operation. */
+function summarizeSecurity(operation, document) {
+	return (Array.isArray(operation.security) ? operation.security : Array.isArray(document.security) ? document.security : []).filter(isRecord);
 }
+/** Read one operation into its compact projection. */
+function compactOperation(method, path, pathItem, operation, document) {
+	return {
+		method: method.toUpperCase(),
+		path,
+		operationId: typeof operation.operationId === "string" ? operation.operationId : null,
+		summary: typeof operation.summary === "string" ? operation.summary : null,
+		tags: strings(operation.tags) ?? [],
+		parameters: summarizeParameters(pathItem, operation, document),
+		requestBody: summarizeRequestBody(operation, document),
+		security: summarizeSecurity(operation, document)
+	};
+}
+/** Whether one operation passes every supplied filter. */
+function matches(operation, filters, tokens) {
+	if (filters.tag !== "" && !operation.tags.some((tag) => tag.toLowerCase() === filters.tag)) return false;
+	if (filters.path !== "" && !operation.path.toLowerCase().includes(filters.path)) return false;
+	if (filters.operationId !== "" && !(operation.operationId ?? "").toLowerCase().includes(filters.operationId)) return false;
+	if (filters.method !== "" && operation.method !== filters.method) return false;
+	if (tokens.length === 0) return true;
+	const haystack = [
+		operation.path,
+		operation.operationId ?? "",
+		operation.summary ?? "",
+		operation.description,
+		operation.tags.join(" ")
+	].join(" ").toLowerCase();
+	return tokens.every((token) => haystack.includes(token));
+}
+/** Relevance used only to order matches; equal scores keep the document order. */
+function scoreOf(operation, tokens) {
+	if (tokens.length === 0) return 0;
+	let score = 0;
+	const operationId = (operation.operationId ?? "").toLowerCase();
+	const path = operation.path.toLowerCase();
+	const summary = (operation.summary ?? "").toLowerCase();
+	const tags = operation.tags.map((tag) => tag.toLowerCase());
+	const description = operation.description.toLowerCase();
+	for (const token of tokens) {
+		if (operationId === token) score += 5;
+		else if (operationId.includes(token)) score += 3;
+		if (path.includes(token)) score += 2;
+		if (summary.includes(token)) score += 1;
+		if (tags.some((tag) => tag.includes(token))) score += 1;
+		if (description.includes(token)) score += 2;
+	}
+	return score;
+}
+/**
+* Search one parsed OpenAPI document.
+* @param document - Parsed `/api/openapi.json` body.
+* @param filters - Keyword, tag, path, operationId and method filters.
+* @returns Matching operations, bounded and ordered by relevance.
+* @throws ApiDocsUnavailableError when the document has no searchable `paths` object.
+*/
+function searchOpenApiDocument(document, filters = {}) {
+	if (!isRecord(document)) throw new ApiDocsUnavailableError("DataOps API docs are unavailable: the response is not an OpenAPI document");
+	if (!isRecord(document.paths)) throw new ApiDocsUnavailableError("DataOps API docs are unavailable: the document has no paths object");
+	const wanted = {
+		tag: normalized(filters.tag),
+		path: normalized(filters.path),
+		operationId: normalized(filters.operation_id),
+		method: normalized(filters.method)
+	};
+	const tokens = keywords(filters.query);
+	const matched = [];
+	let index = 0;
+	for (const [path, rawPathItem] of Object.entries(document.paths)) {
+		const pathItem = dereference(rawPathItem, document);
+		if (!isRecord(pathItem)) continue;
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+			if (!isRecord(operation)) continue;
+			const candidate = {
+				method,
+				path,
+				operationId: typeof operation.operationId === "string" ? operation.operationId : null,
+				summary: typeof operation.summary === "string" ? operation.summary : null,
+				tags: strings(operation.tags) ?? [],
+				description: typeof operation.description === "string" ? operation.description : "",
+				pathItem,
+				operation,
+				index
+			};
+			index += 1;
+			if (!matches(candidate, wanted, tokens)) continue;
+			matched.push({
+				operation: candidate,
+				score: scoreOf(candidate, tokens)
+			});
+		}
+	}
+	matched.sort((left, right) => right.score - left.score || left.operation.index - right.operation.index);
+	const results = matched.slice(0, MAX_RESULTS).map(({ operation }) => compactOperation(operation.method, operation.path, operation.pathItem, operation.operation, document));
+	const info = isRecord(document.info) ? document.info : {};
+	return {
+		title: typeof info.title === "string" ? info.title : null,
+		version: typeof info.version === "string" ? info.version : null,
+		openapi: typeof document.openapi === "string" ? document.openapi : typeof document.swagger === "string" ? "swagger " + document.swagger : null,
+		total: matched.length,
+		returned: results.length,
+		truncated: matched.length > results.length,
+		results
+	};
+}
+//#endregion
+//#region src/tool-output.ts
+/** An open object schema: tools declare their canonical shape in code and docs. */
+const OPEN_OBJECT_SCHEMA = {
+	type: "object",
+	additionalProperties: true
+};
+/** Render one canonical value as pretty JSON text. */
+const renderJson = (_args, value) => [{
+	type: "text",
+	text: JSON.stringify(value, null, 2)
+}];
+//#endregion
+//#region src/tools.ts
 /** Parse one plaza response body into rows without trusting its shape. */
 function rowsOf(body) {
 	if (Array.isArray(body)) return body.filter((row) => typeof row === "object" && row !== null);
 	if (typeof body === "object" && body !== null && Array.isArray(body.skills)) return body.skills.filter((row) => typeof row === "object" && row !== null);
 	return [];
 }
-/** Register the skill-centre and review tools. */
-function registerAiManagementTools(ctx, reviewApi) {
-	const disposers = [];
-	const register = (tool) => {
-		disposers.push(ctx.tools.register(tool));
-	};
+const forbidden = (message) => /* @__PURE__ */ new Error("Forbidden (403): " + message);
+/**
+* Build every managed tool definition.
+*
+* The definitions are built once; `readScope` is a live getter so a tool that survives a role
+* change reports the scope the manager currently holds instead of the one it was registered
+* with. An undefined scope can only be observed by an in-flight call during disposal, where the
+* safe behavior is to show only the public catalogue.
+* @param ctx - Host context used for local skills, approval and audit.
+* @param reviewApi - Same-origin bridge holding the workspace JWT.
+* @param readScope - Live accessor for the manager's current scope.
+* @returns One definition per managed tool name.
+*/
+function buildAiManagementTools(ctx, reviewApi, readScope) {
 	const approve = async (tool, exec, reason) => {
 		if (exec.agent === void 0) throw new Error(tool + " requires an initiating agent");
 		const outcome = await ctx.approval.request({
@@ -900,7 +1268,6 @@ function registerAiManagementTools(ctx, reviewApi) {
 		return result.body;
 	};
 	const listSkills = async (scope, includeLocal) => {
-		requireSkillPermission(scope, "skill:read");
 		const mine = rowsOf(await call("/api/ai/skill-plaza/skills?scope=mine"));
 		const publicRows = rowsOf(await call("/api/ai/skill-plaza/skills"));
 		const admin = isAdmin(scope) ? rowsOf(await call("/api/ai/skill-plaza/admin/skills")) : [];
@@ -927,389 +1294,714 @@ function registerAiManagementTools(ctx, reviewApi) {
 			},
 			canReview: canReview(scope),
 			isAdmin: isAdmin(scope),
-			isDepartmentAdmin: isDeptAdmin(scope),
+			isDepartmentAdmin: isDepartmentAdmin(scope),
 			departmentCode: scope.departmentCode ?? null,
 			skills: rows
 		};
 	};
-	register(defineTool({
-		name: "skill_list",
-		description: "List skills in the DataOps skill centre: local workspace skills plus the caller's pending/rejected submissions and the approved plaza entries they may install. Scope follows the caller role (department admins see their department; ordinary users see their own and approved entries). Read-only.",
-		parameters: { include_local: {
-			type: "boolean",
-			description: "Include local workspace skills (default true)."
-		} },
-		output: {
-			schema: open,
-			render
+	/**
+	* Build the enable/disable pair.
+	*
+	* The two tools share one body so their approval reason, audit detail and endpoint stay in
+	* step; only the verb and the boolean they send differ.
+	*/
+	function defineSkillStatusTool(enabled) {
+		const name = enabled ? "skill_enable" : "skill_disable";
+		return defineTool({
+			name,
+			description: (enabled ? "Enable" : "Disable") + " one plaza skill for distribution. Administrator only. Requires user approval; audited.",
+			parameters: { skill_id: {
+				type: "number",
+				required: true,
+				description: "Plaza skill id."
+			} },
+			output: {
+				schema: OPEN_OBJECT_SCHEMA,
+				render: renderJson
+			},
+			execute: async (args, exec) => {
+				await approve(name, exec, (enabled ? "Enable" : "Disable") + " skill " + args.skill_id.toString());
+				await call("/api/ai/skill-plaza/admin/skills/" + args.skill_id.toString() + "/status", {
+					method: "PATCH",
+					body: JSON.stringify({ enabled })
+				});
+				audit(name, exec, {
+					skillId: args.skill_id,
+					enabled
+				});
+				return {
+					skillId: args.skill_id,
+					enabled
+				};
+			}
+		});
+	}
+	return [
+		{
+			name: "skill_list",
+			definition: defineTool({
+				name: "skill_list",
+				description: "List skills in the DataOps skill centre: local workspace skills plus the caller's pending/rejected submissions and the approved plaza entries they may install. Scope follows the caller role (department admins see their department; ordinary users see their own and approved entries). Read-only.",
+				parameters: { include_local: {
+					type: "boolean",
+					description: "Include local workspace skills (default true)."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args) => {
+					return await listSkills(readScope() ?? {}, args.include_local !== false);
+				}
+			})
 		},
-		execute: async (args) => {
-			const scope = await loadScope(reviewApi);
-			return listSkills(scope, args.include_local !== false);
-		}
-	}));
-	register(defineTool({
-		name: "skill_get",
-		description: "Read one skill-centre entry by id: description, instruction, review status, review note, risk report and visibility. Only entries visible to the caller can be read.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Skill/plaza id from skill_list."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_get",
+			definition: defineTool({
+				name: "skill_get",
+				description: "Read one skill-centre entry by id: description, instruction, review status, review note, risk report and visibility. Only entries visible to the caller can be read.",
+				parameters: { skill_id: {
+					type: "number",
+					required: true,
+					description: "Skill/plaza id from skill_list."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args) => {
+					const found = (await listSkills(readScope() ?? {}, false)).skills.find((row) => row.id === args.skill_id);
+					if (found === void 0) throw new Error("Skill not found or not visible: " + args.skill_id.toString());
+					return found;
+				}
+			})
 		},
-		execute: async (args) => {
-			const scope = await loadScope(reviewApi);
-			const found = (await listSkills(scope, false)).skills.find((row) => row.id === args.skill_id);
-			if (found === void 0) throw new Error("Skill not found or not visible: " + args.skill_id.toString());
-			return found;
-		}
-	}));
-	register(defineTool({
-		name: "skill_submit",
-		description: "Submit the caller's own skill for plaza review. When the workspace review switch is off DataOps approves immediately; otherwise the entry becomes pending. Requires user approval; audited.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Own skill/plaza id."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_submit",
+			definition: defineTool({
+				name: "skill_submit",
+				description: "Submit the caller's own skill for plaza review. When the workspace review switch is off DataOps approves immediately; otherwise the entry becomes pending. Requires user approval; audited.",
+				parameters: { skill_id: {
+					type: "number",
+					required: true,
+					description: "Own skill/plaza id."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					await approve("skill_submit", exec, "Submit skill " + args.skill_id.toString() + " for review");
+					const value = await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/submit", {
+						method: "POST",
+						body: "{}"
+					});
+					audit("skill_submit", exec, { skillId: args.skill_id });
+					return value;
+				}
+			})
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:submit");
-			await approve("skill_submit", exec, "Submit skill " + args.skill_id.toString() + " for review");
-			const value = await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/submit", {
-				method: "POST",
-				body: "{}"
-			});
-			audit("skill_submit", exec, { skillId: args.skill_id });
-			return value;
-		}
-	}));
-	register(defineTool({
-		name: "skill_install",
-		description: "Install one approved, visible plaza skill into the caller's workspace. Requires user approval; audited. The secret-free result reports the local skill key.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Plaza skill id."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_install",
+			definition: defineTool({
+				name: "skill_install",
+				description: "Install one approved, visible plaza skill into the caller's workspace. Requires user approval; audited. The secret-free result reports the local skill key.",
+				parameters: { skill_id: {
+					type: "number",
+					required: true,
+					description: "Plaza skill id."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					await approve("skill_install", exec, "Install skill " + args.skill_id.toString());
+					const value = await call("/api/ai/skill-plaza/install", {
+						method: "POST",
+						body: JSON.stringify({ skillId: args.skill_id })
+					});
+					audit("skill_install", exec, { skillId: args.skill_id });
+					return value;
+				}
+			})
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:install");
-			await approve("skill_install", exec, "Install skill " + args.skill_id.toString());
-			const value = await call("/api/ai/skill-plaza/install", {
-				method: "POST",
-				body: JSON.stringify({ skillId: args.skill_id })
-			});
-			audit("skill_install", exec, { skillId: args.skill_id });
-			return value;
-		}
-	}));
-	register(defineTool({
-		name: "skill_uninstall",
-		description: "Uninstall one skill from the caller's own workspace only: deletes the current user's installation record. The plaza entry, its review status, visibility and enabled flag are unchanged and no “unpublished” notification is sent. Requires user approval; audited.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Plaza skill id."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_uninstall",
+			definition: defineTool({
+				name: "skill_uninstall",
+				description: "Uninstall one skill from the caller's own workspace only: deletes the current user's installation record. The plaza entry, its review status, visibility and enabled flag are unchanged and no “unpublished” notification is sent. Requires user approval; audited.",
+				parameters: { skill_id: {
+					type: "number",
+					required: true,
+					description: "Plaza skill id."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					await approve("skill_uninstall", exec, "Uninstall skill " + args.skill_id.toString() + " from the current workspace");
+					const result = await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/install", { method: "DELETE" });
+					audit("skill_uninstall", exec, {
+						skillId: args.skill_id,
+						scope: "installation-only",
+						removed: result.removed ?? null
+					});
+					return {
+						uninstalled: result.uninstalled === true,
+						removed: typeof result.removed === "number" ? result.removed : 0
+					};
+				}
+			})
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:install");
-			await approve("skill_uninstall", exec, "Uninstall skill " + args.skill_id.toString() + " from the current workspace");
-			const result = await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/install", { method: "DELETE" });
-			audit("skill_uninstall", exec, {
-				skillId: args.skill_id,
-				scope: "installation-only",
-				removed: result.removed ?? null
-			});
-			return {
-				uninstalled: result.uninstalled === true,
-				removed: typeof result.removed === "number" ? result.removed : 0
-			};
-		}
-	}));
-	const setEnabled = (enabled) => defineTool({
-		name: enabled ? "skill_enable" : "skill_disable",
-		description: (enabled ? "Enable" : "Disable") + " one plaza skill for distribution. Administrator only. Requires user approval; audited.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Plaza skill id."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_enable",
+			definition: defineSkillStatusTool(true)
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:manage");
-			await approve(enabled ? "skill_enable" : "skill_disable", exec, (enabled ? "Enable" : "Disable") + " skill " + args.skill_id.toString());
-			await call("/api/ai/skill-plaza/admin/skills/" + args.skill_id.toString() + "/status", {
-				method: "PATCH",
-				body: JSON.stringify({ enabled })
-			});
-			audit(enabled ? "skill_enable" : "skill_disable", exec, {
-				skillId: args.skill_id,
-				enabled
-			});
-			return {
-				skillId: args.skill_id,
-				enabled
-			};
-		}
-	});
-	register(setEnabled(true));
-	register(setEnabled(false));
-	register(defineTool({
-		name: "skill_unshare",
-		description: "Stop sharing one plaza skill (soft unpublish): the entry and its installations remain, review status/visibility are kept, and DataOps sends an “unpublished” notification. Owners may unshare their own entries; 超级管理员/管理员 any entry; 部门管理员 their department. Requires user approval; audited.",
-		parameters: { skill_id: {
-			type: "number",
-			required: true,
-			description: "Plaza skill id."
-		} },
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_disable",
+			definition: defineSkillStatusTool(false)
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:manage");
-			if (!isAdmin(scope) && !isDeptAdmin(scope)) {
-				const found = (await listSkills(scope, false)).skills.find((row) => row.id === args.skill_id);
-				if (found === void 0 || found.sharedByMe !== true) throw forbidden("only the owner or an administrator may unshare this skill");
-			}
-			await approve("skill_unshare", exec, "Unshare skill " + args.skill_id.toString());
-			await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString(), { method: "DELETE" });
-			audit("skill_unshare", exec, {
-				skillId: args.skill_id,
-				effect: "soft-unpublish"
-			});
-			return {
-				unshared: args.skill_id,
-				effect: "plaza-sharing-disabled"
-			};
-		}
-	}));
-	register(defineTool({
-		name: "skill_delete",
-		description: "Permanently delete one plaza skill. This is not unshare: the record is removed, DataOps sends a “deleted” notification (not “unpublished”), and the audit entry records the permanent action. Requires confirm=true as a second confirmation; owners may delete their own entries, 超级管理员/管理员 any entry, 部门管理员 their department. If installations still exist the backend returns 409 and the error is passed through. Requires user approval; audited.",
-		parameters: {
-			skill_id: {
-				type: "number",
-				required: true,
-				description: "Plaza skill id."
-			},
-			confirm: {
-				type: "boolean",
-				required: true,
-				description: "Must be true: explicitly confirms permanent deletion."
-			}
+		{
+			name: "skill_unshare",
+			definition: defineTool({
+				name: "skill_unshare",
+				description: "Stop sharing one plaza skill (soft unpublish): the entry and its installations remain, review status/visibility are kept, and DataOps sends an “unpublished” notification. Owners may unshare their own entries; 超级管理员/管理员 any entry; 部门管理员 their department. Requires user approval; audited.",
+				parameters: { skill_id: {
+					type: "number",
+					required: true,
+					description: "Plaza skill id."
+				} },
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					await approve("skill_unshare", exec, "Unshare skill " + args.skill_id.toString());
+					await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString(), { method: "DELETE" });
+					audit("skill_unshare", exec, {
+						skillId: args.skill_id,
+						effect: "soft-unpublish"
+					});
+					return {
+						unshared: args.skill_id,
+						effect: "plaza-sharing-disabled"
+					};
+				}
+			})
 		},
-		output: {
-			schema: open,
-			render
+		{
+			name: "skill_delete",
+			definition: defineTool({
+				name: "skill_delete",
+				description: "Permanently delete one plaza skill. This is not unshare: the record is removed, DataOps sends a “deleted” notification (not “unpublished”), and the audit entry records the permanent action. Requires confirm=true as a second confirmation; owners may delete their own entries, 超级管理员/管理员 any entry, 部门管理员 their department. If installations still exist the backend returns 409 and the error is passed through. Requires user approval; audited.",
+				parameters: {
+					skill_id: {
+						type: "number",
+						required: true,
+						description: "Plaza skill id."
+					},
+					confirm: {
+						type: "boolean",
+						required: true,
+						description: "Must be true: explicitly confirms permanent deletion."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					if (args.confirm !== true) throw new Error("skill_delete requires confirm=true (permanent deletion)");
+					await approve("skill_delete", exec, "Permanently delete skill " + args.skill_id.toString());
+					await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/permanent", { method: "DELETE" });
+					audit("skill_delete", exec, {
+						skillId: args.skill_id,
+						permanent: true
+					});
+					return {
+						deleted: args.skill_id,
+						permanent: true
+					};
+				}
+			})
 		},
-		execute: async (args, exec) => {
-			if (args.confirm !== true) throw new Error("skill_delete requires confirm=true (permanent deletion)");
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:manage");
-			if (!isAdmin(scope) && !isDeptAdmin(scope)) {
-				const found = (await listSkills(scope, false)).skills.find((row) => row.id === args.skill_id);
-				if (found === void 0 || found.sharedByMe !== true) throw forbidden("only the owner or an administrator may delete this skill");
-			}
-			await approve("skill_delete", exec, "Permanently delete skill " + args.skill_id.toString());
-			await call("/api/ai/skill-plaza/skills/" + args.skill_id.toString() + "/permanent", { method: "DELETE" });
-			audit("skill_delete", exec, {
-				skillId: args.skill_id,
-				permanent: true
-			});
-			return {
-				deleted: args.skill_id,
-				permanent: true
-			};
-		}
-	}));
-	register(defineTool({
-		name: "review_scan",
-		description: "Run the DataOps AI risk scan for skill and/or workflow ids. Reviewers only (超级管理员/管理员/部门管理员 with review capability); ordinary users receive 403. Read-only.",
-		parameters: {
-			skills: {
-				type: "array",
-				items: { type: "number" },
-				description: "Skill ids to scan."
-			},
-			workflows: {
-				type: "array",
-				items: { type: "string" },
-				description: "Workflow ids to scan."
-			}
+		{
+			name: "review_scan",
+			definition: defineTool({
+				name: "review_scan",
+				description: "Run the DataOps AI risk scan for skill and/or workflow ids. Reviewers only; the tool is disclosed to principals with review capability and skill read access, and DataOps still enforces the permission on every call. Read-only.",
+				parameters: {
+					skills: {
+						type: "array",
+						items: { type: "number" },
+						description: "Skill ids to scan."
+					},
+					workflows: {
+						type: "array",
+						items: { type: "string" },
+						description: "Workflow ids to scan."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args) => {
+					return await call("/api/ai/review/scan", {
+						method: "POST",
+						body: JSON.stringify({
+							skills: args.skills ?? [],
+							workflows: args.workflows ?? []
+						})
+					});
+				}
+			})
 		},
-		output: {
-			schema: open,
-			render
+		{
+			name: "review_decide",
+			definition: defineTool({
+				name: "review_decide",
+				description: "Approve or reject skills/workflows. Requires authorization.confirmed=true (the administrator explicitly confirmed), a reviewer role, resource scope and the review-decide capability; DataOps enforces all of them on the call. Requires a second user approval at tool level and writes an audit entry.",
+				parameters: {
+					skills: {
+						type: "array",
+						items: { type: "number" },
+						description: "Skill ids."
+					},
+					workflows: {
+						type: "array",
+						items: { type: "string" },
+						description: "Workflow ids."
+					},
+					decision: {
+						type: "string",
+						required: true,
+						description: "approve or reject."
+					},
+					note: {
+						type: "string",
+						description: "Review note (max 2000 chars)."
+					},
+					confirmed: {
+						type: "boolean",
+						required: true,
+						description: "Must be true: the administrator confirmed this decision."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					if (args.confirmed !== true) throw new Error("authorization.confirmed=true is required for review_decide");
+					if (args.decision !== "approve" && args.decision !== "reject") throw new Error("decision must be approve or reject");
+					if ((args.skills ?? []).length === 0 && (args.workflows ?? []).length === 0) throw new Error("at least one skill or workflow id is required");
+					await approve("review_decide", exec, "Review " + args.decision + " for " + (args.skills ?? []).length.toString() + " skill(s) / " + (args.workflows ?? []).length.toString() + " workflow(s)");
+					const value = await call("/api/ai/review/decide", {
+						method: "POST",
+						body: JSON.stringify({
+							skills: args.skills ?? [],
+							workflows: args.workflows ?? [],
+							decision: args.decision,
+							note: args.note ?? "",
+							authorization: { confirmed: true }
+						})
+					});
+					audit("review_decide", exec, {
+						decision: args.decision,
+						skills: args.skills ?? [],
+						workflows: args.workflows ?? [],
+						confirmed: true
+					});
+					return value;
+				}
+			})
 		},
-		execute: async (args) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:read");
-			if (!canReview(scope)) throw forbidden("the current role cannot review");
-			return await call("/api/ai/review/scan", {
-				method: "POST",
-				body: JSON.stringify({
-					skills: args.skills ?? [],
-					workflows: args.workflows ?? []
-				})
-			});
-		}
-	}));
-	register(defineTool({
-		name: "review_decide",
-		description: "Approve or reject skills/workflows. Requires authorization.confirmed=true (the administrator explicitly confirmed), reviewer role and department scope; requires a second user approval at tool level and writes an audit entry. Ordinary users receive 403.",
-		parameters: {
-			skills: {
-				type: "array",
-				items: { type: "number" },
-				description: "Skill ids."
-			},
-			workflows: {
-				type: "array",
-				items: { type: "string" },
-				description: "Workflow ids."
-			},
-			decision: {
-				type: "string",
-				required: true,
-				description: "approve or reject."
-			},
-			note: {
-				type: "string",
-				description: "Review note (max 2000 chars)."
-			},
-			confirmed: {
-				type: "boolean",
-				required: true,
-				description: "Must be true: the administrator confirmed this decision."
-			}
+		{
+			name: "review_notifications_list",
+			definition: defineTool({
+				name: "review_notifications_list",
+				description: "List the caller's review notifications and unread count. Read-only and always scoped to the current DataOps user.",
+				parameters: {
+					unread_only: {
+						type: "boolean",
+						description: "Only unread notifications."
+					},
+					limit: {
+						type: "number",
+						description: "Maximum rows (default 20)."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args) => {
+					const query = new URLSearchParams({
+						unreadOnly: args.unread_only === true ? "true" : "false",
+						limit: String(args.limit ?? 20)
+					});
+					return await call("/api/ai/review-notifications?" + query.toString());
+				}
+			})
 		},
-		output: {
-			schema: open,
-			render
+		{
+			name: "review_notifications_read",
+			definition: defineTool({
+				name: "review_notifications_read",
+				description: "Mark the caller's review notifications as read, either selected ids or all. Scoped to the current DataOps user; no secret is involved.",
+				parameters: {
+					ids: {
+						type: "array",
+						items: { type: "string" },
+						description: "Notification ids to mark read."
+					},
+					all: {
+						type: "boolean",
+						description: "Mark every notification read."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args, exec) => {
+					const value = await call("/api/ai/review-notifications/read", {
+						method: "POST",
+						body: JSON.stringify({
+							ids: args.ids ?? [],
+							all: args.all === true
+						})
+					});
+					audit("review_notifications_read", exec, {
+						count: args.ids?.length ?? 0,
+						all: args.all === true
+					});
+					return value;
+				}
+			})
 		},
-		execute: async (args, exec) => {
-			const scope = await loadScope(reviewApi);
-			requireSkillPermission(scope, "skill:review:decide");
-			if (!canReview(scope)) throw forbidden("the current role cannot review");
-			if (args.confirmed !== true) throw new Error("authorization.confirmed=true is required for review_decide");
-			if (args.decision !== "approve" && args.decision !== "reject") throw new Error("decision must be approve or reject");
-			if ((args.skills ?? []).length === 0 && (args.workflows ?? []).length === 0) throw new Error("at least one skill or workflow id is required");
-			if (!isAdmin(scope) && isDeptAdmin(scope)) {
-				const rows = (await listSkills(scope, false)).skills;
-				const allowed = new Set(scope.dataScope?.departmentCodes ?? (scope.departmentCode === void 0 ? [] : [scope.departmentCode]));
-				for (const id of args.skills ?? []) {
-					const row = rows.find((item) => item.id === id);
-					if (row !== void 0 && (row.departmentCode === null || row.departmentCode === void 0)) requireSkillPermission(scope, "skill:review:global");
-					if (row !== void 0 && row.departmentCode !== null && row.departmentCode !== void 0 && !allowed.has(String(row.departmentCode))) throw forbidden("department administrators may only review their own department");
+		{
+			name: "dataops_api_docs",
+			definition: defineTool({
+				name: "dataops_api_docs",
+				description: "Search the DataOps HTTP API reference (OpenAPI 3) for endpoint contracts. Super administrators only; read-only. Returns compact operations — method, path, operationId, summary, tags, parameters, request-body fields and security — filtered by keyword, tag, path, operationId or HTTP method. It only reads the fixed /api/openapi.json document and cannot execute arbitrary requests.",
+				parameters: {
+					query: {
+						type: "string",
+						description: "Case-insensitive keywords matched against path, operationId, summary, tags and description. All keywords must match."
+					},
+					tag: {
+						type: "string",
+						description: "Exact OpenAPI tag (case-insensitive)."
+					},
+					path: {
+						type: "string",
+						description: "Case-insensitive substring of the operation path."
+					},
+					operation_id: {
+						type: "string",
+						description: "Case-insensitive substring of the operationId."
+					},
+					method: {
+						type: "string",
+						description: "HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS or TRACE."
+					}
+				},
+				output: {
+					schema: OPEN_OBJECT_SCHEMA,
+					render: renderJson
+				},
+				execute: async (args) => {
+					const result = await reviewApi.request("/api/openapi.json");
+					if (result.status === 401) throw new Error("Unauthorized (401): DataOps session expired; sign in again to read the API reference");
+					if (result.status === 403) throw new Error("Forbidden (403): the DataOps OpenAPI document is not available to this role");
+					if (result.status === 404) throw new Error("DataOps API docs are unavailable: /api/openapi.json is not configured (DATAOPS_OPENAPI_UNAVAILABLE)");
+					if (result.status === 503) throw new Error("DataOps API docs are unavailable: this workspace has no DataOps session");
+					if (result.status < 200 || result.status >= 300) throw new Error("DataOps API docs request failed: HTTP " + result.status.toString());
+					try {
+						return searchOpenApiDocument(result.body, args);
+					} catch (error) {
+						if (error instanceof ApiDocsUnavailableError) throw new Error(error.message);
+						throw error;
+					}
 				}
-			}
-			await approve("review_decide", exec, "Review " + args.decision + " for " + (args.skills ?? []).length.toString() + " skill(s) / " + (args.workflows ?? []).length.toString() + " workflow(s)");
-			const value = await call("/api/ai/review/decide", {
-				method: "POST",
-				body: JSON.stringify({
-					skills: args.skills ?? [],
-					workflows: args.workflows ?? [],
-					decision: args.decision,
-					note: args.note ?? "",
-					authorization: { confirmed: true }
-				})
-			});
-			audit("review_decide", exec, {
-				decision: args.decision,
-				skills: args.skills ?? [],
-				workflows: args.workflows ?? [],
-				confirmed: true
-			});
-			return value;
+			})
 		}
-	}));
-	register(defineTool({
-		name: "review_notifications_list",
-		description: "List the caller's review notifications and unread count. Read-only and always scoped to the current DataOps user.",
-		parameters: {
-			unread_only: {
-				type: "boolean",
-				description: "Only unread notifications."
-			},
-			limit: {
-				type: "number",
-				description: "Maximum rows (default 20)."
-			}
-		},
-		output: {
-			schema: open,
-			render
-		},
-		execute: async (args) => {
-			await loadScope(reviewApi);
-			const query = new URLSearchParams({
-				unreadOnly: args.unread_only === true ? "true" : "false",
-				limit: String(args.limit ?? 20)
-			});
-			return await call("/api/ai/review-notifications?" + query.toString());
+	];
+}
+//#endregion
+//#region src/tool-manager.ts
+/**
+* Reconcile the managed tools with the current DataOps scope.
+*
+* Construct once per plugin activation. `refresh` is idempotent and coalesces concurrent calls;
+* the constructor also subscribes to the credential observation so an expired session removes
+* the tools without waiting for another explicit sync.
+*/
+var AiToolManager = class {
+	ctx;
+	reviewApi;
+	definitions;
+	registrations = /* @__PURE__ */ new Map();
+	unsubscribeExpiry;
+	disposeViewer;
+	scope;
+	revision = 0;
+	inflight;
+	disposed = false;
+	constructor(ctx, reviewApi) {
+		this.ctx = ctx;
+		this.reviewApi = reviewApi;
+		this.definitions = new Map(buildAiManagementTools(ctx, reviewApi, () => this.scope).map((tool) => [tool.name, tool.definition]));
+		this.unsubscribeExpiry = onAuthStateChange((state) => {
+			if (state === "expired") this.clear();
+		});
+	}
+	/** The scope the current registration set was derived from, when one has been read. */
+	currentScope() {
+		return this.scope;
+	}
+	/** The tool names currently registered, for diagnostics and tests. */
+	registeredToolNames() {
+		return AI_TOOL_NAMES.filter((name) => this.registrations.has(name));
+	}
+	/**
+	* Re-read the workspace's DataOps scope and reconcile the tool list.
+	*
+	* Definitive denials clear the list; transient failures (network, 5xx) keep what the last good
+	* observation produced. The method never throws: sync happens in the background of a browser
+	* request and must not fail that request.
+	* @param force - Start a new read even when one is already in flight. Credential adoption uses
+	*   this because an older read may have captured the previous token; its answer must not win
+	*   over the scope the new token produces.
+	*/
+	async refresh(force = false) {
+		if (this.disposed) return;
+		if (this.inflight !== void 0 && !force) return this.inflight;
+		const revision = ++this.revision;
+		const run = this.loadScope(revision).catch((error) => {
+			this.ctx.logger.warn("dataops-managed: tool disclosure refresh failed");
+			this.ctx.logger.warn(error);
+		}).finally(() => {
+			if (this.inflight === run) this.inflight = void 0;
+		});
+		this.inflight = run;
+		return run;
+	}
+	/**
+	* Apply a context answer already fetched by a same-origin route.
+	*
+	* The review-context route is how the UI learns about a role change, so its answer is also the
+	* freshest scope this plugin will see. Reusing it avoids a second fetch on a page that polls.
+	* @param result - The upstream status and parsed body.
+	*/
+	observeContext(result) {
+		if (result.status === 200) {
+			this.applyContext(result.body);
+			return;
 		}
-	}));
-	register(defineTool({
-		name: "review_notifications_read",
-		description: "Mark the caller's review notifications as read, either selected ids or all. Scoped to the current DataOps user; no secret is involved.",
-		parameters: {
-			ids: {
-				type: "array",
-				items: { type: "string" },
-				description: "Notification ids to mark read."
-			},
-			all: {
-				type: "boolean",
-				description: "Mark every notification read."
+		if (result.status === 401 || result.status === 403 || result.status === 404 || result.status === 503) this.clear();
+	}
+	/**
+	* Apply one parsed context body without contacting DataOps.
+	* @param body - Parsed `/api/ai/review/context` body.
+	*/
+	applyContext(body) {
+		if (this.disposed) return;
+		this.revision += 1;
+		const scope = normalizeScope(body);
+		this.applyScope(scope);
+	}
+	/** Drop every managed tool because no usable DataOps scope is known. */
+	clear() {
+		if (this.disposed) return;
+		this.revision += 1;
+		this.applyScope(void 0);
+	}
+	/** Dispose every tool this manager registered and stop observing auth state. */
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.revision += 1;
+		this.unsubscribeExpiry();
+		this.disposeRegistrations();
+		this.disposeViewer?.();
+		this.disposeViewer = void 0;
+		this.scope = void 0;
+	}
+	async loadScope(revision) {
+		let result;
+		try {
+			result = await this.reviewApi.request("/api/ai/review/context");
+		} catch (error) {
+			this.ctx.logger.warn("dataops-managed: tool disclosure could not read the DataOps scope");
+			this.ctx.logger.warn(error);
+			return;
+		}
+		if (this.disposed || revision !== this.revision) return;
+		if (result.status === 200) {
+			this.applyScope(normalizeScope(result.body));
+			return;
+		}
+		if (result.status === 401 || result.status === 403 || result.status === 404 || result.status === 503) {
+			this.applyScope(void 0);
+			return;
+		}
+		this.ctx.logger.warn("dataops-managed: tool disclosure scope read failed with HTTP " + result.status.toString());
+	}
+	/** Store the scope and make the registry match it. */
+	applyScope(scope) {
+		this.scope = scope;
+		if (this.disposed) return;
+		this.applyViewer(scope);
+		const desired = new Set(scope === void 0 ? [] : AI_TOOL_NAMES.filter((name) => isToolVisible(name, scope)));
+		for (const [name, registration] of this.registrations) {
+			if (desired.has(name)) continue;
+			this.disposeRegistration(name, registration);
+		}
+		for (const name of AI_TOOL_NAMES) {
+			if (!desired.has(name) || this.registrations.has(name)) continue;
+			const definition = this.definitions.get(name);
+			if (definition === void 0) continue;
+			try {
+				const dispose = this.ctx.tools.register(definition);
+				this.registrations.set(name, { dispose });
+			} catch (error) {
+				this.ctx.logger.warn("dataops-managed: could not register tool " + name);
+				this.ctx.logger.warn(error);
 			}
-		},
-		output: {
-			schema: open,
-			render
-		},
-		execute: async (args, exec) => {
-			await loadScope(reviewApi);
-			const value = await call("/api/ai/review-notifications/read", {
-				method: "POST",
-				body: JSON.stringify({
-					ids: args.ids ?? [],
-					all: args.all === true
-				})
-			});
-			audit("review_notifications_read", exec, {
-				count: args.ids?.length ?? 0,
-				all: args.all === true
-			});
-			return value;
 		}
+	}
+	/** Map one DataOps scope to the skill registry's audience filter. */
+	applyViewer(scope) {
+		this.disposeViewer?.();
+		this.disposeViewer = void 0;
+		const viewer = scope === void 0 ? {
+			role: "user",
+			permissions: []
+		} : {
+			role: isSuperAdmin(scope) ? "super-admin" : isAdmin(scope) || isDepartmentAdmin(scope) ? "admin" : "user",
+			permissions: [...scope.permissions ?? scope.permissionKeys ?? []]
+		};
+		try {
+			const skills = this.ctx.skills;
+			if (typeof skills.useViewer !== "function") return;
+			this.disposeViewer = skills.useViewer(viewer);
+		} catch (error) {
+			this.ctx.logger.warn("dataops-managed: could not apply the skill viewer");
+			this.ctx.logger.warn(error);
+		}
+	}
+	/** Dispose one registration, tolerating a disposer that has already run. */
+	disposeRegistration(name, registration) {
+		this.registrations.delete(name);
+		try {
+			registration.dispose();
+		} catch (error) {
+			this.ctx.logger.warn("dataops-managed: could not dispose tool " + name);
+			this.ctx.logger.warn(error);
+		}
+	}
+	/** Dispose the whole current set. */
+	disposeRegistrations() {
+		for (const [name, registration] of [...this.registrations]) this.disposeRegistration(name, registration);
+	}
+};
+//#endregion
+//#region src/connector-state.ts
+/**
+* The DataOps connector's workspace-visible state and skill-center catalogue.
+*
+* The skill center is skill-first, with connectors as its fourth tab. DataOps contributes one
+* connector whose capability rows are derived from the same scope that drives tool disclosure;
+* a capability the account cannot use is omitted rather than rendered as a disabled placeholder.
+*
+* This module owns only state and presentation. It never authorizes a tool call or a DataOps
+* request: the backend remains the final boundary.
+*
+* @module connector-state
+*/
+/** Same-origin route the skill center's connector tab reads and writes. */
+const CONNECTORS_PATH = "/api/dsh-skill-center/connectors";
+/** Connector id shown in the skill center. */
+const DATAOPS_CONNECTOR_ID = "dataops-managed";
+/** Resolve the persisted state file without depending on a global DSH path. */
+const CONNECTOR_STATE_PATH = join(process.env.DSH_HOME?.trim() || "/workspace/.dataops/dsh", "dataops-managed", "connector-state.json");
+/** Capability definitions before permission filtering. */
+const CAPABILITIES = [
+	{
+		id: "skill.plaza",
+		name: "技能广场",
+		description: "读取、安装和管理当前账号可见的技能",
+		allowed: (scope) => hasPermission(scope, "skill:read")
+	},
+	{
+		id: "review.queue",
+		name: "审核队列",
+		description: "查看待审技能、扫描风险并给出审核结论",
+		allowed: (scope) => canReview(scope)
+	},
+	{
+		id: "data.query",
+		name: "数据查询",
+		description: "通过 DataOps 数据查询能力回答业务问题",
+		allowed: () => true
+	},
+	{
+		id: "api.docs",
+		name: "管理接口文档",
+		description: "仅超级管理员可查询 DataOps OpenAPI 接口文档",
+		allowed: (scope) => isSuperAdmin(scope)
+	}
+];
+/** Read state; a missing or corrupt file is a safe disabled state. */
+async function readConnectorState(path = CONNECTOR_STATE_PATH) {
+	try {
+		const payload = JSON.parse(await readFile(path, "utf8"));
+		return {
+			enabled: payload.enabled === true,
+			capabilities: typeof payload.capabilities === "object" && payload.capabilities !== null ? { ...payload.capabilities } : {}
+		};
+	} catch {
+		return {
+			enabled: false,
+			capabilities: {}
+		};
+	}
+}
+/** Persist state atomically. */
+async function writeConnectorState(state, path = CONNECTOR_STATE_PATH) {
+	await mkdir(dirname(path), { recursive: true });
+	const temporary = path + ".tmp-" + process.pid.toString();
+	await writeFile(temporary, JSON.stringify(state, null, 2), "utf8");
+	await rename(temporary, path);
+}
+/** Build the connector row for one current scope. */
+function buildConnectorView(scope, state) {
+	const capabilities = scope === void 0 ? [] : CAPABILITIES.filter((capability) => capability.allowed(scope)).map((capability) => ({
+		id: capability.id,
+		name: capability.name,
+		description: capability.description,
+		enabled: state.capabilities[capability.id] !== false,
+		permitted: true
 	}));
-	return () => {
-		for (const dispose of disposers) dispose();
+	return {
+		id: DATAOPS_CONNECTOR_ID,
+		name: "万相AI中台连接器",
+		vendor: "DataOps",
+		description: "把万相AI中台的技能、审核和数据能力接入当前工作区。",
+		enabled: state.enabled,
+		connected: scope !== void 0,
+		capabilities
 	};
 }
+/** Whether one capability id is in the fixed catalogue. */
+function hasCapability(id) {
+	return CAPABILITIES.some((capability) => capability.id === id);
+}
 //#endregion
 //#region src/workspace-limits.ts
 /** Narrow a value to a plain object. */
@@ -1874,8 +2566,12 @@ function adoptRequestJwt(ctx, accessRef, request) {
 	const token = bearerToken(request);
 	if (token === null) return Promise.resolve();
 	return (async () => {
-		if ((await ctx.credentials.resolve(accessRef))?.value === token) return;
+		if ((await ctx.credentials.resolve(accessRef))?.value === token) {
+			resetAuthState();
+			return;
+		}
 		await ctx.credentials.set(accessRef, token);
+		resetAuthState();
 	})().catch((error) => {
 		ctx.logger.warn("dataops-managed: request JWT could not be adopted");
 		ctx.logger.warn(error);
@@ -1964,7 +2660,11 @@ async function apply(ctx, config) {
 	* a failed connect is reported rather than thrown.
 	*/
 	const connectExisting = async () => {
-		if (await ctx.credentials.resolve(accessRef) === void 0) return;
+		if (await ctx.credentials.resolve(accessRef) === void 0) {
+			aiTools.clear();
+			return;
+		}
+		aiTools.refresh();
 		try {
 			await ensureMcp();
 		} catch (error) {
@@ -2044,7 +2744,21 @@ async function apply(ctx, config) {
 		credentialRef: config.credentialRef
 	});
 	reviewApiRef = reviewApi;
-	ctx.effect(() => registerAiManagementTools(ctx, reviewApi), "dataops-managed: skill and review tools");
+	/**
+	* The managed tool list follows the workspace's DataOps scope.
+	*
+	* `AiToolManager` registers only the skill/review tools the current principal can use and
+	* disposes them when the role changes. The credential event below is the existing auth-sync
+	* path: JWT adoption and the managed-auth route both go through `credentials.set`, which
+	* publishes this event after the write commits. The manager also observes the review-context
+	* route's answer, because a role edit does not change the JWT but does change the scope.
+	*/
+	const aiTools = new AiToolManager(ctx, reviewApi);
+	ctx.effect(() => () => aiTools.dispose(), "dataops-managed: skill and review tool disclosure");
+	ctx.effect(() => ctx.on("credentials/reference-updated", (ref) => {
+		if (String(ref) !== config.credentialRef) return;
+		aiTools.refresh(true);
+	}), "dataops-managed: tool disclosure follows the DataOps credential");
 	setWorkspaceLimits(new WorkspaceLimits(ctx, {
 		baseUrl,
 		credentialRef: config.credentialRef
@@ -2095,6 +2809,8 @@ async function apply(ctx, config) {
 				return;
 			}
 			await ctx.credentials.set(accessRef, token);
+			resetAuthState();
+			aiTools.refresh(true);
 			await ensureMcp();
 			await adoptNow();
 			response.writeHead(204, { "cache-control": "no-store" });
@@ -2330,6 +3046,7 @@ async function apply(ctx, config) {
 			}
 			try {
 				const result = await api.request("/api/ai/review/context");
+				aiTools.observeContext(result);
 				writeJson(response, result.status, result.body);
 			} catch (error) {
 				ctx.logger.warn("dataops-managed: review context failed");
@@ -2766,9 +3483,75 @@ async function apply(ctx, config) {
 				response.end();
 				return;
 			}
+			await adoptRequestJwt(ctx, accessRef, request);
 			writeJson(response, 200, { state: currentAuthState() });
 		}
 	}), "dataops-managed: auth state route");
+	/**
+	* The skill center's connector tab. The route is a same-origin presentation bridge: reads
+	* return only capabilities the current scope can use, and writes persist the connector's own
+	* enable state. It never substitutes for a DataOps authorization decision.
+	*/
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: CONNECTORS_PATH,
+		handler: async (request, response) => {
+			try {
+				if (request.method === "GET") {
+					if (aiTools.currentScope() === void 0) await aiTools.refresh();
+					const state = await readConnectorState();
+					writeJson(response, 200, { connectors: [buildConnectorView(aiTools.currentScope(), state)] });
+					return;
+				}
+				if (request.method === "POST") {
+					const body = await readJson(request);
+					if (body === null) {
+						writeJson(response, 400, { error: "connector state requires a JSON body" });
+						return;
+					}
+					if (body.connectorId !== "dataops-managed") {
+						writeJson(response, 404, { error: "unknown connector" });
+						return;
+					}
+					const state = await readConnectorState();
+					const capabilityId = typeof body.capabilityId === "string" ? body.capabilityId : void 0;
+					if (capabilityId !== void 0) {
+						if (!hasCapability(capabilityId)) {
+							writeJson(response, 400, { error: "unknown capability" });
+							return;
+						}
+						if (!buildConnectorView(aiTools.currentScope(), state).capabilities.some((row) => row.id === capabilityId)) {
+							writeJson(response, 403, { error: "capability is not available to this account" });
+							return;
+						}
+						if (typeof body.enabled !== "boolean") {
+							writeJson(response, 400, { error: "capability state requires enabled:boolean" });
+							return;
+						}
+						state.capabilities[capabilityId] = body.enabled;
+					} else {
+						if (typeof body.enabled !== "boolean") {
+							writeJson(response, 400, { error: "connector state requires enabled:boolean" });
+							return;
+						}
+						state.enabled = body.enabled;
+					}
+					await writeConnectorState(state);
+					writeJson(response, 200, { connectors: [buildConnectorView(aiTools.currentScope(), state)] });
+					return;
+				}
+				response.writeHead(405, {
+					allow: "GET, POST",
+					"content-length": "0"
+				});
+				response.end();
+			} catch (error) {
+				ctx.logger.warn("dataops-managed: connector catalogue route failed");
+				ctx.logger.warn(error);
+				writeJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+			}
+		}
+	}), "dataops-managed: skill-center connector catalogue");
 	await connectExisting();
 }
 /** Read and parse a JSON request body, tolerating an absent one. */