@huyooo/ai-chat-core 0.2.44 → 0.3.2

package/src/extension/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Extension Types — 运行时元数据类型
+ *
+ * 仅包含跨平台（浏览器 + Node）的资产元数据类型定义。
+ * 构建工具链相关（externals、脚手架模板、代码生成）在 @huyooo/ai-chat-host-node 中。
+ */
+
+export type {
+  AssetApprovalPolicy,
+  AssetExecutionIsolation,
+  AssetGovernance,
+  AssetGovernanceOverrides,
+  AssetHostDependency,
+  AssetKind,
+  AssetRuntime,
+  AssetScope,
+  AssetSideEffectLevel,
+} from '../governance';
+
+export type {
+  AssetType,
+  AssetToolMeta,
+  AssetMeta,
+} from './types';

package/src/extension/types.ts

@@ -0,0 +1,49 @@
+/**
+ * 扩展资产元数据类型（manifest / 市场）
+ *
+ * - 描述 tool、part、mcp-server 等扩展在 manifest 中的静态字段
+ * - 与 AssetGovernance 组合，表达审批策略、副作用级别等治理信息
+ */
+
+import type { AssetGovernance, AssetKind } from '../governance/types';
+import type { JsonSchemaObject } from '../types';
+
+export type AssetType = Extract<AssetKind, 'tool' | 'part' | 'mcp-server'>;
+
+export interface AssetToolMeta {
+  /** scope 内的工具名（tools[] 多工具时必填） */
+  name?: string;
+  displayName?: string;
+  description: string;
+  parameters?: JsonSchemaObject;
+  outputSchema?: JsonSchemaObject;
+  errorSchema?: JsonSchemaObject;
+  category?: string;
+  tags?: string[];
+  enabled?: boolean;
+  governance?: Partial<AssetGovernance>;
+}
+
+/**
+ * manifest.json 中的资产元数据。
+ *
+ * 必填字段（手写）：type, template, enabled
+ * manifest 是元数据唯一权威源，构建时只读不写。
+ */
+export interface AssetMeta {
+  type: AssetType;
+  template: string;
+  assetId?: string;
+  /** 单工具资产的工具调用名 */
+  name?: string;
+  description?: string;
+  parameters?: JsonSchemaObject;
+  outputSchema?: JsonSchemaObject;
+  errorSchema?: JsonSchemaObject;
+  category?: string;
+  tags?: string[];
+  enabled: boolean;
+  governance?: Partial<AssetGovernance>;
+  /** 多工具集时的子工具列表 */
+  tools?: AssetToolMeta[];
+}

package/src/families/index.ts

@@ -0,0 +1,28 @@
+/**
+ * 模型家族（Model Family）模块导出
+ *
+ * - types：家族 ID、thinking / 工具调用格式等行为差异
+ * - presets：各厂商内置家族默认配置
+ * - resolver：从 LLMConfig 解析 ModelConfig.family
+ */
+
+export type {
+  ModelFamilyId,
+  ThinkingFormat,
+  ToolCallFormat,
+  ModelFamilyConfig,
+} from './types';
+export {
+  DOUBAO_FAMILY,
+  DEEPSEEK_FAMILY,
+  QWEN_FAMILY,
+  GLM_FAMILY,
+  MOONSHOT_FAMILY,
+  MINIMAX_FAMILY,
+  GEMINI_FAMILY,
+  GPT_FAMILY,
+  CLAUDE_FAMILY,
+  GROK_FAMILY,
+  MODEL_FAMILIES,
+} from './presets';
+export { resolveModelFamilyConfig } from './resolver';

package/src/families/presets.ts

@@ -0,0 +1,124 @@
+/**
+ * 内置模型家族预设（MODEL_FAMILIES）
+ *
+ * - 各厂商默认 thinking 参数形态、工具格式、视觉能力标记
+ * - 与 protocols 正交：家族描述「行为」，协议描述「HTTP/SSE」
+ */
+
+import type { ModelFamilyConfig, ModelFamilyId } from './types';
+
+export const DOUBAO_FAMILY: ModelFamilyConfig = {
+  id: 'doubao',
+  displayName: 'Doubao',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'reasoning',
+  toolCallFormat: 'responses',
+};
+
+export const DEEPSEEK_FAMILY: ModelFamilyConfig = {
+  id: 'deepseek',
+  displayName: 'DeepSeek',
+  supportsVision: false,
+  supportsThinking: true,
+  thinkingFormat: 'thinking_object',
+  toolCallFormat: 'openai',
+};
+
+export const QWEN_FAMILY: ModelFamilyConfig = {
+  id: 'qwen',
+  displayName: 'Qwen',
+  supportsVision: false,
+  supportsThinking: true,
+  thinkingFormat: 'thinking_enabled',
+  toolCallFormat: 'openai',
+};
+
+/** GLM 家族（OpenAI 兼容 API，thinking 用 {"thinking": {"type": "enabled"}}） */
+export const GLM_FAMILY: ModelFamilyConfig = {
+  id: 'glm',
+  displayName: 'GLM',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'thinking_object',
+  toolCallFormat: 'openai',
+};
+
+/** Kimi 家族（OpenAI 兼容 API，thinking 用 reasoning: {enabled: true}） */
+export const MOONSHOT_FAMILY: ModelFamilyConfig = {
+  id: 'moonshot',
+  displayName: 'Kimi',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'reasoning_object',
+  toolCallFormat: 'openai',
+};
+
+/** MiniMax 家族（Anthropic 兼容 API，thinking 始终开启） */
+export const MINIMAX_FAMILY: ModelFamilyConfig = {
+  id: 'minimax',
+  displayName: 'MiniMax',
+  supportsVision: false,
+  supportsThinking: true,
+  thinkingFormat: 'anthropic_native',
+  thinkingAlwaysOn: true,
+  toolCallFormat: 'openai',
+};
+
+/** Gemini 家族（原生 API 透传，完整 thinking + thoughtSignature 支持） */
+export const GEMINI_FAMILY: ModelFamilyConfig = {
+  id: 'gemini',
+  displayName: 'Gemini',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'thought_signature',
+  toolCallFormat: 'gemini',
+};
+
+/** GPT 家族（Responses API，统一支持 GPT / Codex / o-series） */
+export const GPT_FAMILY: ModelFamilyConfig = {
+  id: 'gpt',
+  displayName: 'GPT',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'reasoning',
+  toolCallFormat: 'responses',
+};
+
+/** Claude 家族（Anthropic 原生协议） */
+export const CLAUDE_FAMILY: ModelFamilyConfig = {
+  id: 'claude',
+  displayName: 'Claude',
+  supportsVision: true,
+  supportsThinking: true,
+  thinkingFormat: 'anthropic_native',
+  toolCallFormat: 'openai',
+};
+
+/**
+ * Grok 家族（xAI，OpenAI 兼容 API）
+ * - grok-4-0709：旗舰推理模型
+ * - grok-4-1-fast-reasoning：快速推理模型（reasoning_effort 参数）
+ */
+export const GROK_FAMILY: ModelFamilyConfig = {
+  id: 'grok',
+  displayName: 'Grok',
+  supportsVision: true,
+  supportsThinking: false,
+  thinkingFormat: 'none',
+  toolCallFormat: 'openai',
+};
+
+/** 家族配置映射 */
+export const MODEL_FAMILIES: Record<ModelFamilyId, ModelFamilyConfig> = {
+  doubao: DOUBAO_FAMILY,
+  deepseek: DEEPSEEK_FAMILY,
+  qwen: QWEN_FAMILY,
+  glm: GLM_FAMILY,
+  moonshot: MOONSHOT_FAMILY,
+  minimax: MINIMAX_FAMILY,
+  gemini: GEMINI_FAMILY,
+  gpt: GPT_FAMILY,
+  claude: CLAUDE_FAMILY,
+  grok: GROK_FAMILY,
+};

package/src/families/resolver.ts

@@ -0,0 +1,22 @@
+/**
+ * 解析模型家族配置（resolveModelFamilyConfig）
+ *
+ * - 对象 family：内联自定义家族，直接使用
+ * - 字符串 family：优先 LLMConfig.families，其次 MODEL_FAMILIES 内置表
+ * - 不做隐式推导；未命中返回 undefined，由调用方抛错
+ */
+
+import type { LLMConfig, ModelConfig } from '../llm-config';
+import { MODEL_FAMILIES } from './presets';
+import type { ModelFamilyConfig, ModelFamilyId } from './types';
+
+export function resolveModelFamilyConfig(
+  modelId: string,
+  modelConfig: ModelConfig,
+  llmConfig: LLMConfig,
+): ModelFamilyConfig | undefined {
+  const { family } = modelConfig;
+  if (typeof family === 'object') return family;
+  const familyId = family;
+  return llmConfig.families?.[familyId] ?? MODEL_FAMILIES[familyId as ModelFamilyId];
+}

package/src/families/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Family 层类型定义
+ *
+ * Family 负责模型行为差异：thinking 格式、工具调用格式、视觉能力等。
+ * 与 Protocol 层（通信差异）正交。
+ */
+
+/** 模型家族 ID */
+export type ModelFamilyId =
+  | 'doubao'
+  | 'deepseek'
+  | 'qwen'
+  | 'glm'
+  | 'moonshot'
+  | 'minimax'
+  | 'gemini'
+  | 'gpt'
+  | 'claude'
+  | 'grok';
+
+/** Thinking 输出格式 */
+export type ThinkingFormat =
+  | 'reasoning'          // ARK/Doubao: reasoning_summary_text
+  | 'thinking_enabled'   // Qwen: enable_thinking 参数
+  | 'thinking_object'    // DeepSeek/GLM: {"thinking": {"type": "enabled"}} 参数
+  | 'reasoning_object'   // Moonshot: {"reasoning": {"enabled": true}} 参数
+  | 'anthropic_native'   // MiniMax/Claude: Anthropic SSE 格式
+  | 'thought_signature'  // Gemini: 需要 thought_signature 循环
+  | 'none';              // 不支持 thinking
+
+/** 工具调用格式 */
+export type ToolCallFormat =
+  | 'responses'    // ARK Responses API: function_call/function_call_output
+  | 'openai'       // OpenAI 兼容: tool_calls/tool
+  | 'gemini';      // Gemini: functionCall/functionResponse
+
+/**
+ * 模型家族配置
+ *
+ * 定义同一家族模型的共同行为特征
+ */
+export interface ModelFamilyConfig {
+  id: ModelFamilyId;
+  displayName: string;
+
+  supportsVision: boolean;
+  supportsThinking: boolean;
+  thinkingFormat: ThinkingFormat;
+  /** thinking 是否由模型强制开启（无法关闭），开关仅控制前端是否展示思考过程 */
+  thinkingAlwaysOn?: boolean;
+
+  toolCallFormat: ToolCallFormat;
+
+  requiresSpecialHandling?: string[];
+}

package/src/governance/command-safety.ts

@@ -0,0 +1,224 @@
+/**
+ * Shell / 命令行风险分析与治理快照
+ *
+ * - 从用户或工具拟执行的命令字符串推导风险标签与建议审批策略
+ * - 与 AssetGovernance 对齐，供动态工具元数据与 UI 提示使用
+ */
+
+import type { AssetApprovalPolicy, AssetHostDependency, AssetSideEffectLevel } from './types';
+import { createLocalToolGovernance } from './governance';
+
+export type CommandRiskTag =
+  | 'filesystem'
+  | 'delete'
+  | 'git'
+  | 'package-manager'
+  | 'process'
+  | 'system'
+  | 'network'
+  | 'shell-eval'
+  | 'script';
+
+export interface CommandRiskAssessment {
+  level: AssetSideEffectLevel;
+  summary: string;
+  signals: string[];
+  tags: CommandRiskTag[];
+  recommendedApprovalPolicy: AssetApprovalPolicy;
+}
+
+export interface CommandSafetyPolicy {
+  unknownCommandLevel?: Extract<AssetSideEffectLevel, 'write' | 'destructive'>;
+  elevateTagsToLevel?: Partial<Record<CommandRiskTag, AssetSideEffectLevel>>;
+  approvalByLevel?: Partial<Record<AssetSideEffectLevel, AssetApprovalPolicy>>;
+  approvalByTag?: Partial<Record<CommandRiskTag, AssetApprovalPolicy>>;
+}
+
+export interface CommandToolMetadata {
+  approvalPolicy: AssetApprovalPolicy;
+  sideEffectLevel: AssetSideEffectLevel;
+  hostDependency: AssetHostDependency;
+}
+
+const APPROVAL_POLICY_ORDER: Record<AssetApprovalPolicy, number> = {
+  auto: 0,
+  'destructive-only': 1,
+  manual: 2,
+};
+
+function pickStricterApprovalPolicy(
+  left: AssetApprovalPolicy,
+  right: AssetApprovalPolicy,
+): AssetApprovalPolicy {
+  return APPROVAL_POLICY_ORDER[left] >= APPROVAL_POLICY_ORDER[right] ? left : right;
+}
+
+function pickHigherRiskLevel(
+  left: AssetSideEffectLevel,
+  right: AssetSideEffectLevel,
+): AssetSideEffectLevel {
+  const order: Record<AssetSideEffectLevel, number> = {
+    read: 0,
+    write: 1,
+    destructive: 2,
+  };
+  return order[left] >= order[right] ? left : right;
+}
+
+export function createCommandToolMetadata(
+  sideEffectLevel: AssetSideEffectLevel,
+  approvalPolicy: AssetApprovalPolicy = 'auto',
+): CommandToolMetadata {
+  const governance = createLocalToolGovernance({
+    sideEffectLevel,
+    approvalPolicy,
+    hostDependency: 'os-service',
+  });
+
+  return {
+    approvalPolicy: governance.approvalPolicy,
+    sideEffectLevel: governance.sideEffectLevel,
+    hostDependency: governance.hostDependency,
+  };
+}
+
+export function createCommandGovernanceSnapshot(
+  assessment: CommandRiskAssessment,
+): CommandToolMetadata & {
+  riskSummary: string;
+  riskTags: CommandRiskTag[];
+  riskSignals: string[];
+} {
+  return {
+    ...createCommandToolMetadata(assessment.level, assessment.recommendedApprovalPolicy),
+    riskSummary: assessment.summary,
+    riskTags: assessment.tags,
+    riskSignals: assessment.signals,
+  };
+}
+
+export function analyzeCommandRisk(
+  input: string,
+  policy: CommandSafetyPolicy = {},
+): CommandRiskAssessment {
+  const normalized = input.trim();
+  const signals: string[] = [];
+  const tags = new Set<CommandRiskTag>();
+  let level: AssetSideEffectLevel | null = null;
+
+  function applyMatch(match: {
+    level: AssetSideEffectLevel;
+    signal: string;
+    tags?: CommandRiskTag[];
+  }) {
+    level = level ? pickHigherRiskLevel(level, match.level) : match.level;
+    signals.push(match.signal);
+    for (const tag of match.tags ?? []) {
+      tags.add(tag);
+    }
+  }
+
+  const destructivePatterns: Array<{ pattern: RegExp; signal: string; tags: CommandRiskTag[] }> = [
+    { pattern: /(^|\s)rm\s+-[^\n]*r[^\n]*f\b/, signal: '检测到 rm -rf 类删除命令', tags: ['filesystem', 'delete'] },
+    { pattern: /\bgit\s+reset\s+--hard\b/, signal: '检测到 git reset --hard', tags: ['git'] },
+    { pattern: /\bgit\s+clean\b[^\n]*\s-f/, signal: '检测到 git clean 强制清理', tags: ['git', 'delete'] },
+    { pattern: /\bdd\s+if=.*of=\/dev\//, signal: '检测到 dd 直接写块设备', tags: ['system'] },
+    { pattern: /\bmkfs(\.[a-z0-9_-]+)?\b/, signal: '检测到格式化文件系统命令', tags: ['system'] },
+    { pattern: /\bdiskutil\s+erase(Disk|Volume)\b/, signal: '检测到磁盘抹除命令', tags: ['system'] },
+    { pattern: /\b(format|shutdown|reboot|poweroff|halt)\b/i, signal: '检测到系统级破坏/关机命令', tags: ['system'] },
+    { pattern: /\b(del|erase)\b[^\n]*\s\/f\b/i, signal: '检测到 Windows 强制删除命令', tags: ['filesystem', 'delete'] },
+    { pattern: /\brd\b[^\n]*\s\/s\b[^\n]*\s\/q\b/i, signal: '检测到 Windows 递归删除目录命令', tags: ['filesystem', 'delete'] },
+    { pattern: /\b(curl|wget)\b[^\n|]*\|\s*(sh|bash|zsh|fish|pwsh|powershell)\b/i, signal: '检测到网络下载后直接交给 shell 执行', tags: ['network', 'shell-eval'] },
+    { pattern: /\b(bash|sh|zsh|fish)\s+-c\b/, signal: '检测到 shell -c 动态执行命令', tags: ['shell-eval'] },
+    { pattern: /\bpowershell(\.exe)?\s+-Command\b/i, signal: '检测到 PowerShell 动态执行命令', tags: ['shell-eval'] },
+  ];
+
+  for (const item of destructivePatterns) {
+    if (item.pattern.test(normalized)) {
+      applyMatch({ level: 'destructive', signal: item.signal, tags: item.tags });
+    }
+  }
+
+  const writePatterns: Array<{ pattern: RegExp; signal: string; tags: CommandRiskTag[] }> = [
+    { pattern: /(^|\s)rm\s+([^-][^\n]*)/, signal: '检测到文件删除命令', tags: ['filesystem', 'delete'] },
+    { pattern: /\b(npm|pnpm|yarn)\s+(install|add|remove|uninstall|update)\b/, signal: '检测到依赖变更命令', tags: ['package-manager'] },
+    { pattern: /\bgit\s+(commit|push|merge|rebase|pull)\b/, signal: '检测到 Git 写操作命令', tags: ['git'] },
+    { pattern: /(^|\s)(mv|cp|mkdir|touch|chmod|chown)\b/, signal: '检测到文件系统写操作命令', tags: ['filesystem'] },
+    { pattern: /\bsed\b[^\n]*\s-i(\b|['"])/, signal: '检测到 sed 原地修改命令', tags: ['filesystem'] },
+    { pattern: /\bkill(\s+-9)?\b/, signal: '检测到进程控制命令', tags: ['process'] },
+    { pattern: /\b(curl|wget)\b/, signal: '检测到网络访问命令', tags: ['network'] },
+    { pattern: /^\s*(python|python3|node|tsx|ts-node|deno|ruby|perl)\b/, signal: '检测到脚本解释器执行入口', tags: ['script'] },
+    { pattern: /^\s*(make|just)\b/, signal: '检测到任务脚本执行入口', tags: ['script'] },
+  ];
+
+  for (const item of writePatterns) {
+    if (item.pattern.test(normalized)) {
+      applyMatch({ level: 'write', signal: item.signal, tags: item.tags });
+    }
+  }
+
+  const readPatterns = [
+    /^\s*(pwd|ls|cat|rg|which|echo|env)\b/,
+    /^\s*git\s+(status|diff|log|show)\b/,
+    /^\s*(curl|wget)\b[^\n]*(https?:\/\/|\s+-I\b|\s+--head\b)/,
+    /^\s*(npm|pnpm|yarn)\s+(test|run\s+test)\b/,
+  ];
+
+  if (readPatterns.some((pattern) => pattern.test(normalized))) {
+    applyMatch({
+      level: 'read',
+      signal: '命令模式符合只读查询或测试执行',
+      tags: normalized.startsWith('git ') ? ['git'] : undefined,
+    });
+  }
+
+  if (!level) {
+    const fallbackLevel = policy.unknownCommandLevel ?? 'write';
+    applyMatch({
+      level: fallbackLevel,
+      signal: fallbackLevel === 'destructive'
+        ? '未识别命令且策略要求按 destructive 处理'
+        : '未识别为只读命令，保守按写操作处理',
+    });
+  }
+
+  for (const tag of tags) {
+    const elevatedLevel = policy.elevateTagsToLevel?.[tag];
+    if (elevatedLevel) {
+      level = pickHigherRiskLevel(level ?? 'write', elevatedLevel);
+      signals.push(`策略已将 ${tag} 标签提升为 ${elevatedLevel}`);
+    }
+  }
+
+  const resolvedLevel = level ?? 'write';
+  let recommendedApprovalPolicy: AssetApprovalPolicy = resolvedLevel === 'destructive' ? 'manual' : 'auto';
+  if (tags.has('system') || tags.has('shell-eval')) {
+    recommendedApprovalPolicy = 'manual';
+  }
+  if (policy.approvalByLevel?.[resolvedLevel]) {
+    recommendedApprovalPolicy = pickStricterApprovalPolicy(
+      recommendedApprovalPolicy,
+      policy.approvalByLevel[resolvedLevel]!,
+    );
+  }
+  for (const tag of tags) {
+    const tagPolicy = policy.approvalByTag?.[tag];
+    if (tagPolicy) {
+      recommendedApprovalPolicy = pickStricterApprovalPolicy(recommendedApprovalPolicy, tagPolicy);
+    }
+  }
+
+  const summary = resolvedLevel === 'read'
+    ? '检测到只读或低风险命令'
+    : resolvedLevel === 'destructive'
+      ? `检测到高风险命令：${signals.join('，')}`
+      : `检测到可能修改环境的命令：${signals.join('，')}`;
+
+  return {
+    level: resolvedLevel,
+    summary,
+    signals,
+    tags: Array.from(tags),
+    recommendedApprovalPolicy,
+  };
+}

package/src/governance/governance.ts

@@ -0,0 +1,125 @@
+/**
+ * 资产治理默认值与摘要基座
+ *
+ * - 从 manifest / 代码元数据构造 AssetGovernance、管理 API 摘要字段
+ * - 支持覆盖合并（readAssetGovernanceOverrides / applyGovernanceOverrides）
+ */
+
+import type {
+  AssetApprovalPolicy,
+  AssetGovernance,
+  AssetGovernanceOverrides,
+  AssetHostDependency,
+  AssetSideEffectLevel,
+  ManagedAssetSummaryBase,
+} from './types';
+
+function applyGovernanceOverrides(
+  base: AssetGovernance,
+  overrides: AssetGovernanceOverrides,
+): AssetGovernance {
+  return {
+    ...base,
+    ...(overrides.sideEffectLevel ? { sideEffectLevel: overrides.sideEffectLevel } : {}),
+    ...(overrides.approvalPolicy ? { approvalPolicy: overrides.approvalPolicy } : {}),
+    ...(overrides.hostDependency ? { hostDependency: overrides.hostDependency } : {}),
+  };
+}
+
+function isSideEffectLevel(value: unknown): value is AssetSideEffectLevel {
+  return value === 'read' || value === 'write' || value === 'destructive';
+}
+
+function isApprovalPolicy(value: unknown): value is AssetApprovalPolicy {
+  return value === 'auto' || value === 'manual' || value === 'destructive-only';
+}
+
+function isHostDependency(value: unknown): value is AssetHostDependency {
+  return value === 'none'
+    || value === 'local-app'
+    || value === 'os-service'
+    || value === 'remote-service';
+}
+
+export function createAssetSummaryBase(
+  input: ManagedAssetSummaryBase,
+): ManagedAssetSummaryBase {
+  return input.governance
+    ? { ...input, governance: input.governance }
+    : { kind: input.kind, scope: input.scope, runtime: input.runtime };
+}
+
+export function createLocalToolGovernance(
+  overrides: AssetGovernanceOverrides = {},
+): AssetGovernance {
+  return applyGovernanceOverrides({
+    sideEffectLevel: 'write',
+    approvalPolicy: 'auto',
+    executionIsolation: 'in-process',
+    hostDependency: 'none',
+  }, overrides);
+}
+
+export function createLocalMcpServerGovernance(
+  overrides: AssetGovernanceOverrides = {},
+): AssetGovernance {
+  return applyGovernanceOverrides({
+    sideEffectLevel: 'write',
+    approvalPolicy: 'manual',
+    executionIsolation: 'mcp',
+    hostDependency: 'none',
+  }, overrides);
+}
+
+export function createPartAssetGovernance(
+  overrides: AssetGovernanceOverrides = {},
+): AssetGovernance {
+  return applyGovernanceOverrides({
+    sideEffectLevel: 'read',
+    approvalPolicy: 'auto',
+    executionIsolation: 'part-render',
+    hostDependency: 'none',
+  }, overrides);
+}
+
+export function createSkillAssetGovernance(
+  overrides: AssetGovernanceOverrides = {},
+): AssetGovernance {
+  return applyGovernanceOverrides({
+    sideEffectLevel: 'read',
+    approvalPolicy: 'auto',
+    executionIsolation: 'prompt-injection',
+    hostDependency: 'none',
+  }, overrides);
+}
+
+export function toAssetGovernanceOverrides(
+  governance?: AssetGovernance,
+): AssetGovernanceOverrides | undefined {
+  if (!governance) return undefined;
+  return {
+    sideEffectLevel: governance.sideEffectLevel,
+    approvalPolicy: governance.approvalPolicy,
+    hostDependency: governance.hostDependency,
+  };
+}
+
+export function readAssetGovernanceOverrides(input: {
+  sideEffectLevel?: unknown;
+  approvalPolicy?: unknown;
+  hostDependency?: unknown;
+}): AssetGovernanceOverrides | undefined {
+  const governance: AssetGovernanceOverrides = {};
+
+  if (isSideEffectLevel(input.sideEffectLevel)) {
+    governance.sideEffectLevel = input.sideEffectLevel;
+  }
+  if (isApprovalPolicy(input.approvalPolicy)) {
+    governance.approvalPolicy = input.approvalPolicy;
+  }
+  if (isHostDependency(input.hostDependency)) {
+    governance.hostDependency = input.hostDependency;
+  }
+
+  return Object.keys(governance).length > 0 ? governance : undefined;
+}

package/src/governance/index.ts

@@ -0,0 +1,38 @@
+/**
+ * 治理子系统导出（barrel）
+ *
+ * - types：资产种类、来源、运行时、审批策略等
+ * - governance：摘要与默认治理构造
+ * - command-safety：命令行风险分析
+ */
+
+export type {
+  AssetApprovalPolicy,
+  AssetExecutionIsolation,
+  AssetGovernance,
+  AssetGovernanceOverrides,
+  AssetHostDependency,
+  AssetKind,
+  AssetRuntime,
+  AssetScope,
+  AssetSideEffectLevel,
+  AssetSource,
+  ManagedAssetSummaryBase,
+} from './types';
+
+export {
+  createAssetSummaryBase,
+  createPartAssetGovernance,
+  createLocalMcpServerGovernance,
+  createSkillAssetGovernance,
+  createLocalToolGovernance,
+  readAssetGovernanceOverrides,
+  toAssetGovernanceOverrides,
+} from './governance';
+export { analyzeCommandRisk, createCommandGovernanceSnapshot, createCommandToolMetadata } from './command-safety';
+export type {
+  CommandRiskAssessment,
+  CommandRiskTag,
+  CommandSafetyPolicy,
+  CommandToolMetadata,
+} from './command-safety';