@webskill/sdk 0.0.1

package/dist/governance.d.ts

@@ -0,0 +1,440 @@
+import { Mt as FileSystemProvider, Rt as SkillCatalogEntry, ht as WebSkillRuntime, j as LlmMessage, k as LlmClient, pt as UiBridge, tt as RuntimeRun } from "./index-88KNOnbr.js";
+import { f as SkillManager, p as SkillManifest } from "./index-Bq-bTWh3.js";
+//#region ../governance/dist/index.d.ts
+//#region src/types.d.ts
+type CandidateStatus = 'draft' | 'pending-review' | 'approved' | 'published' | 'rejected';
+type CandidateSource = 'runtime-miss' | 'document' | 'manual';
+type CandidateRisk = 'low' | 'medium' | 'high';
+interface CandidateFile {
+  path: string;
+  kind: 'skill-md' | 'script' | 'reference' | 'asset';
+  content: string;
+}
+interface CandidateSkill {
+  id: string;
+  name: string;
+  description: string;
+  status: CandidateStatus;
+  source: CandidateSource;
+  risk: CandidateRisk;
+  riskReasons: string[];
+  files: CandidateFile[];
+  suggestedTests?: string[];
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+interface AuditEvent {
+  id: string;
+  type: string;
+  target: string;
+  actor?: string;
+  ts: string;
+  data?: Record<string, unknown>;
+}
+interface AuditLog {
+  append(event: Omit<AuditEvent, 'id' | 'ts'> & {
+    id?: string;
+    ts?: string;
+  }): Promise<AuditEvent>;
+  query(filter: {
+    target?: string;
+    type?: string;
+    since?: string;
+  }): Promise<AuditEvent[]>;
+}
+interface SkillVersion {
+  versionId: string;
+  parentVersionId?: string;
+  createdAt: string;
+  reason: string;
+  manifest: SkillManifest;
+  auditEventId?: string;
+}
+type SkillState = 'active' | 'quarantined' | 'deprecated' | 'disabled';
+//#endregion
+//#region src/candidate/candidateNormalizer.d.ts
+/** 剥 markdown fence 与 <think> 块、截取首尾 {}；非对象 → CANDIDATE_INVALID */
+declare function parseJsonObject(raw: string): Record<string, unknown>;
+/** 小写连字符化、≤64、过 isValidSkillName */
+declare function sanitizeCandidateName(raw: string): string;
+/**
+ * 文件归一：补 SKILL.md；路径含 `..` / 以 `/` 开头 / 含 `\` → CANDIDATE_INVALID；
+ * scripts/ 下必须是 .ts/.js。
+ */
+declare function normalizeCandidateFiles(files: Array<{
+  path: string;
+  content: string;
+}>, name: string, description: string): CandidateFile[];
+/** 含脚本且 LLM 自报 low → 强制 medium 并追加"必须人工审批"原因 */
+declare function normalizeRisk(declared: unknown, files: CandidateFile[], reasons: string[]): {
+  risk: CandidateRisk;
+  reasons: string[];
+};
+/** 不信任归一化管线全链路；状态恒为 draft */
+declare function normalizeCandidate(input: {
+  raw: Record<string, unknown>;
+  source: CandidateSource;
+  now?: () => string;
+  createId?: () => string;
+}): CandidateSkill;
+//#endregion
+//#region src/candidate/candidateValidator.d.ts
+/** 候选校验：缺 SKILL.md / 非法扩展名 → CANDIDATE_INVALID */
+declare function validateCandidate(candidate: CandidateSkill): void;
+//#endregion
+//#region src/candidate/candidateStore.d.ts
+/** 逐文件持久化的候选存储：<managedRoot>/.webskill/candidates/<id>.json */
+declare class CandidateStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+  });
+  save(candidate: CandidateSkill): Promise<void>;
+  get(id: string): Promise<CandidateSkill>;
+  list(): Promise<CandidateSkill[]>;
+  updateStatus(id: string, status: CandidateStatus, now?: string): Promise<CandidateSkill>;
+}
+/** 硬门禁：仅 published 可转换为 Catalog 条目，否则 APPROVAL_REQUIRED */
+declare function candidateToCatalogEntry(candidate: CandidateSkill): SkillCatalogEntry;
+//#endregion
+//#region src/candidate/llmCandidateGenerator.d.ts
+/** LLM 候选生成器：prompt 强制约束 + 不信任归一化管线 + candidate.created 审计 */
+declare class LlmCandidateGenerator {
+  #private;
+  constructor(deps: {
+    llm: LlmClient;
+    audit?: AuditLog;
+    now?: () => string;
+    createId?: () => string;
+  });
+  generate(input: {
+    prompt: string;
+    source: CandidateSource;
+    context?: string;
+  }): Promise<CandidateSkill>;
+}
+//#endregion
+//#region src/approval/policies.d.ts
+interface ApprovalDecision {
+  needsHuman: boolean;
+  reason: string;
+}
+interface ApprovalPolicy {
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+/** 默认策略：任何候选都必须人工审批 */
+declare class AlwaysHumanApprovalPolicy implements ApprovalPolicy {
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+/** 规则组合策略：首个命中的规则胜出，全部未命中走 fallback（默认 AlwaysHuman） */
+declare class CompositeApprovalPolicy implements ApprovalPolicy {
+  #private;
+  constructor(rules: Array<(candidate: CandidateSkill) => ApprovalDecision | undefined>, fallback?: ApprovalPolicy);
+  evaluate(candidate: CandidateSkill): ApprovalDecision;
+}
+//#endregion
+//#region src/versioning/skillVersionStore.d.ts
+/** 版本存储：manifest 快照 + parentVersionId 链；回滚 = 追加新版本（谱系不断） */
+declare class SkillVersionStore {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+    now?: () => string;
+    createId?: () => string;
+    audit?: AuditLog;
+  });
+  add(skillName: string, input: {
+    reason: string;
+    manifest: SkillManifest;
+    parentVersionId?: string;
+  }): Promise<SkillVersion>;
+  list(skillName: string): Promise<SkillVersion[]>;
+  get(skillName: string, versionId: string): Promise<SkillVersion>;
+  /** 回滚：基于旧 manifest 追加新版本 + skill.rolled_back 审计 */
+  rollback(skillName: string, targetVersionId: string, input: {
+    actor?: string;
+    reason?: string;
+  }): Promise<SkillVersion>;
+}
+//#endregion
+//#region src/approval/approvalWorkflow.d.ts
+/** 审批工作流：review（UiBridge confirm 真实接线）/ publish（校验→安装→版本→审计） */
+declare class ApprovalWorkflow {
+  #private;
+  constructor(deps: {
+    policy: ApprovalPolicy;
+    audit: AuditLog;
+    store: CandidateStore;
+    skillManager: SkillManager;
+    versions: SkillVersionStore;
+    fs?: FileSystemProvider;
+  });
+  /** 策略评估；needs-human 时经 UiBridge confirm 真实询问，按应答迁移状态 */
+  review(candidateId: string, input: {
+    actor: string;
+    uiBridge?: UiBridge;
+  }): Promise<CandidateSkill>;
+  /** publish 全链路：approved 前置 → 写出 staging → validateSkills → install → 版本 → 审计 */
+  publish(candidateId: string, input: {
+    actor: string;
+  }): Promise<SkillManifest>;
+}
+//#endregion
+//#region src/audit/fsAuditLog.d.ts
+/** JSONL 追加的审计日志：<managedRoot>/.webskill/audit.jsonl；跨实例可恢复查询 */
+declare class FsAuditLog implements AuditLog {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+    now?: () => string;
+    createId?: () => string;
+  });
+  append(event: Omit<AuditEvent, 'id' | 'ts'> & {
+    id?: string;
+    ts?: string;
+  }): Promise<AuditEvent>;
+  query(filter: {
+    target?: string;
+    type?: string;
+    since?: string;
+  }): Promise<AuditEvent[]>;
+}
+//#endregion
+//#region src/repair/failureAnalyzer.d.ts
+interface FailureDiagnosis {
+  cause: string;
+  suggestedFix: string;
+  errorCode?: string;
+}
+/** 失败诊断：trace 摘要 → LLM 诊断（JSON）；无 LLM 时规则版（错误码归类） */
+declare class FailureAnalyzer {
+  #private;
+  constructor(deps?: {
+    llm?: LlmClient;
+  });
+  analyze(input: {
+    run: RuntimeRun;
+  }): Promise<FailureDiagnosis>;
+}
+//#endregion
+//#region src/repair/repairPlanner.d.ts
+interface RepairOption {
+  kind: 'patch' | 'rollback' | 'quarantine';
+  description: string;
+  patch?: Array<{
+    path: string;
+    content: string;
+  }>;
+  targetVersionId?: string;
+}
+/**
+ * 修订选项规划：patch（按诊断给具体文件变更）/ rollback（有旧版本时）/ quarantine。
+ * 注意：任何 option 的 apply 都必须经 ApprovalWorkflow 审批后执行。
+ */
+declare class RepairPlanner {
+  plan(input: {
+    diagnosis: FailureDiagnosis;
+    skillName: string;
+    versions: SkillVersion[];
+  }): RepairOption[];
+}
+//#endregion
+//#region src/state/skillStatePolicy.d.ts
+/**
+ * 降级治理：states.json 持久化；失败达阈值 → quarantined；
+ * canRoute 仅 active；canExecute active|deprecated；disabled 执行抛 SKILL_DISABLED；
+ * 卸载/状态变更经 UiBridge confirm 审批。
+ */
+declare class SkillStatePolicy {
+  #private;
+  constructor(deps: {
+    root: string;
+    fs: FileSystemProvider;
+    audit?: AuditLog;
+    failureThreshold?: number;
+  });
+  getState(skillName: string): Promise<SkillState>;
+  listStates(): Promise<Record<string, SkillState>>;
+  setState(skillName: string, state: SkillState, input: {
+    actor?: string;
+    reason?: string;
+  }): Promise<void>;
+  /** 失败计数；达阈值（默认 3）→ quarantined + 审计 */
+  recordFailure(skillName: string, input?: {
+    actor?: string;
+  }): Promise<SkillState>;
+  canRoute(state: SkillState): boolean;
+  canExecute(state: SkillState): boolean;
+  /** disabled → SKILL_DISABLED；quarantined → SKILL_QUARANTINED */
+  assertExecutable(skillName: string): Promise<void>;
+  /** runtime catalogFilter 实现：quarantined/deprecated/disabled 技能被路由过滤 */
+  catalogFilter(): (entries: SkillCatalogEntry[]) => Promise<SkillCatalogEntry[]>;
+  /** 卸载需显式审批（UiBridge confirm 真实接线）；拒绝 → APPROVAL_REQUIRED */
+  uninstall(skillName: string, input: {
+    actor: string;
+    uiBridge: UiBridge;
+    skillManager: SkillManager;
+  }): Promise<void>;
+}
+//#endregion
+//#region src/evaluation/types.d.ts
+interface EvaluationTask {
+  id: string;
+  prompt: string;
+  /** 字符串 → output 包含判定；函数 → 自定义判定 */
+  expected?: string | ((output: string, run: RuntimeRun) => boolean);
+  skillNames?: string[];
+  metadata?: Record<string, unknown>;
+}
+interface EvaluationResult {
+  taskId: string;
+  ok: boolean;
+  score: number;
+  output?: string;
+  error?: string;
+}
+interface EvaluationReport {
+  id: string;
+  generatedAt: string;
+  results: EvaluationResult[];
+  summary: {
+    total: number;
+    passed: number;
+    failed: number;
+    averageScore?: number;
+  };
+}
+//#endregion
+//#region src/evaluation/evaluationRunner.d.ts
+/** 批量评估：顺序执行（单任务异常不中断批）；expected 参与判定；结构化报告 */
+declare class EvaluationRunner {
+  #private;
+  constructor(deps: {
+    runtime: WebSkillRuntime;
+    now?: () => string;
+    createId?: () => string;
+  });
+  run(tasks: EvaluationTask[]): Promise<EvaluationReport>;
+}
+//#endregion
+//#region src/evaluation/testSuggestion.d.ts
+/** 失败 trace → 回归评估任务建议（prompt 复现 + expected 错误模式） */
+declare function suggestFromFailedRun(run: RuntimeRun): EvaluationTask;
+//#endregion
+//#region src/scoring/skillScorer.d.ts
+declare const SCORING_WEIGHTS: {
+  readonly success: 0.5;
+  readonly usage: 0.2;
+  readonly eval: 0.2;
+  readonly risk: 0.1;
+};
+interface ScoreInput {
+  /** 0..1（skill:{name} memory 的 successes/(successes+failures)） */
+  successRate: number;
+  usageCount: number;
+  /** 0..1，缺省按 0 计 */
+  evalScore?: number;
+  risk: 'low' | 'medium' | 'high';
+  /** usage 归一基线（默认 100 次 = 1.0） */
+  usageBaseline?: number;
+}
+/**
+ * 综合评分：successRate*W_SUCCESS + usageNorm*W_USAGE + evalScore*W_EVAL − risk*W_RISK
+ * （clamp [0,1]）；低于阈值给 improve 建议。usage 数据来自 skill:{name} memory scope。
+ */
+declare class SkillScorer {
+  #private;
+  constructor(weights?: {
+    success: number;
+    usage: number;
+    eval: number;
+    risk: number;
+  }, improveThreshold?: number);
+  score(input: ScoreInput): {
+    value: number;
+    suggestion?: string;
+  };
+}
+//#endregion
+//#region src/scoring/similarity.d.ts
+declare function jaccardSimilarity(a: string, b: string): number;
+/** 描述词集 Jaccard 查重 */
+declare class SimilarityDetector {
+  #private;
+  constructor(threshold?: number);
+  /** 返回首个超过阈值的已有技能名；无重复返回 undefined */
+  findDuplicate(description: string, existing: Array<{
+    name: string;
+    description: string;
+  }>): string | undefined;
+}
+//#endregion
+//#region src/scoring/dependencyGraph.d.ts
+/** 技能引用依赖图（references/ 中引用其他技能的声明关系） */
+declare class DependencyGraph {
+  #private;
+  addDependency(from: string, to: string): void;
+  dependenciesOf(name: string): string[];
+  dependentsOf(name: string): string[];
+}
+//#endregion
+//#region src/documents/documentSource.d.ts
+interface SourceDocument {
+  path: string;
+  content: string;
+  hash: string;
+}
+/** 读文档 + sha256 hash（变更检测用） */
+declare function readDocument(fs: FileSystemProvider, path: string): Promise<SourceDocument>;
+//#endregion
+//#region src/documents/documentSkillExtractor.d.ts
+/** 文档 → LLM 抽取 → 完整防御管线 → draft 候选（source: document） */
+declare class DocumentSkillExtractor {
+  #private;
+  constructor(deps: {
+    llm: LlmClient;
+    audit?: AuditLog;
+    now?: () => string;
+    createId?: () => string;
+  });
+  extract(input: {
+    document: SourceDocument;
+    nameHint?: string;
+  }): Promise<CandidateSkill>;
+  /** hash 变化 → 生成新候选（关联原技能名，不覆盖已发布技能）；无变化返回 changed:false */
+  checkUpdate(input: {
+    document: SourceDocument;
+    previousHash: string;
+    previousSkillName?: string;
+  }): Promise<{
+    changed: boolean;
+    candidate?: CandidateSkill;
+  }>;
+}
+//#endregion
+//#region src/missHook.d.ts
+/**
+ * runtime-miss 现成适配（opt-in）：run 未激活技能时生成 draft 候选入库待审。
+ * 返回的 hook 失败会向上抛（由 runtime 降级为 warning）。
+ */
+declare function createMissHook(deps: {
+  generator: LlmCandidateGenerator;
+  store: CandidateStore;
+  audit?: AuditLog;
+}): (input: {
+  prompt: string;
+  run: RuntimeRun;
+}) => Promise<void>;
+//#endregion
+//#region src/llmText.d.ts
+/**
+ * 文本补全：优先走流式（慢速本地模型下非流式整响应缓冲会触发 fetch 头超时，
+ * SSE 首包秒到不受此限）；无 stream 的客户端回退 complete。
+ */
+declare function completeText(llm: LlmClient, messages: LlmMessage[]): Promise<string>;
+//#endregion
+export { AlwaysHumanApprovalPolicy, type ApprovalDecision, type ApprovalPolicy, ApprovalWorkflow, type AuditEvent, type AuditLog, type CandidateFile, type CandidateRisk, type CandidateSkill, type CandidateSource, type CandidateStatus, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, type EvaluationReport, type EvaluationResult, EvaluationRunner, type EvaluationTask, FailureAnalyzer, type FailureDiagnosis, FsAuditLog, LlmCandidateGenerator, type RepairOption, RepairPlanner, SCORING_WEIGHTS, type ScoreInput, SimilarityDetector, SkillScorer, type SkillState, SkillStatePolicy, type SkillVersion, SkillVersionStore, type SourceDocument, candidateToCatalogEntry, completeText, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };