oh-my-knowledge 0.29.0 → 0.31.0

package/dist/src/server/skill-insights.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Insight detection — 把 4 类报告(doctor / eval-评分 / eval-功能 / observe)合并成
+ * 一组结构化"问题",每个 Insight 自带:
+ *   - audience: 该问题主要由谁来修(skill-author / sample-author / omk-maintainer)
+ *   - 多 perspective 的证据(支持现象证据 illustration: 真实 prompt / LLM 输出 / 工具调用)
+ *   - 改进建议(可带可粘贴 patch 片段)
+ *
+ * 设计原则:
+ *   - 用户语去黑话:title/message 写成"用户能复现的现象",不直接吐 omk 内部枚举
+ *   - 受众 explicit:每条 insight 标谁该 own,UI 拆区,不让 skill 开发者看 omk 维护待办
+ *   - action 错位修对:环境拦截 → sample.mocks(不是 skill);doctor 盲区 → omk(不是 skill)
+ *   - 现象 > 统计:展开 1-2 条真实 sample 的 prompt/output/toolCall 让用户"看见"问题
+ *   - 可粘贴 patch:推荐带文件位置 + 代码片段,不只是"改一段"的空话
+ *
+ * 6 类 detection(audience 标在每条):
+ *   1. environment-blocked-mocks   sample-author  评测环境 mock 列表盖不全
+ *   2. skill-doc-gap               skill-author + sample-author  skill 文档某段缺/模糊 + sample environment 没声明
+ *   3. failure-mode-skill          skill-author   skill 写法上的反模式(硬编码/幻觉/跳步/误读)
+ *   4. coverage-gap                sample-author  生产 + 评测都漏的文件
+ *   5. production-instability      skill-author + sample-author  真实环境失败率高
+ *   6. skill-too-long              skill-author   skill 文档过长 LLM 找不到段落
+ *   7. omk-doctor-blindspot        omk-maintainer doctor 应该卡却没规则的反模式
+ */
+import type { EvaluationReport } from '../types/index.js';
+import type { SkillIndexEntry, SkillEvalSnapshot } from './skill-index.js';
+import { type Diagnosis } from '../diagnosis/types.js';
+export type InsightCategory = 'environment-blocked-mocks' | 'skill-doc-gap' | 'failure-mode-skill' | 'coverage-gap' | 'production-instability' | 'skill-too-long' | 'omk-doctor-blindspot' | 'other';
+export type InsightSeverity = 'high' | 'medium' | 'low';
+export type InsightAudience = 'skill-author' | 'sample-author' | 'omk-maintainer';
+export type InsightPerspective = 'doctor' | 'eval-score' | 'eval-functional' | 'observe';
+/** 现象证据:把抽象"X 模式 N 条"翻译成用户能看到的具体行为。 */
+export interface InsightIllustration {
+    sampleId: string;
+    /** 用户给 LLM 的 prompt(截断到 ~200 字)。 */
+    samplePrompt?: string;
+    /** LLM 最终输出(截断到 ~200 字)。 */
+    llmOutput?: string;
+    /** LLM 实际调的工具(简化字符串列表,顺序保留)。 */
+    toolCalls?: string[];
+    /** 哪条 assertion 没过 + value。 */
+    failedAssertion?: string;
+}
+export interface InsightEvidence {
+    perspective: InsightPerspective;
+    status: 'flagged' | 'blind' | 'silent' | 'na';
+    /** 简短说明(用户语,不堆术语)。 */
+    message: string;
+    ref?: string;
+    /** 如果有现象证据,展开看 1-2 条具体 sample 的实际 prompt/output/toolCalls。 */
+    illustrations?: InsightIllustration[];
+}
+/** 可粘贴的 patch 片段。target 指明改哪种文件,location 是文件/章节,snippet 是代码块。 */
+export interface InsightPatch {
+    target: 'skill' | 'sample-environment' | 'sample-mocks' | 'doctor-rule';
+    /** 目标位置描述,如 'sample s003 的 mocks 数组' / 'SKILL.md「项目创建」节'。 */
+    location: string;
+    /** 代码块或 diff 片段。 */
+    snippet: string;
+}
+export interface InsightRecommendation {
+    action: string;
+    priority: InsightSeverity;
+    patch?: InsightPatch;
+}
+/** 该 insight 关联的具体阶段元素 — UI 渲染 timeline 时用来在阶段卡内挂 #N 徽章。 */
+export interface InsightStageRefs {
+    doctorRuleIds?: string[];
+    evalSampleIds?: string[];
+    /** observe 信号类型标签:'high-failure-rate' / 'gap' / 'uncovered-files'。
+     *  observe 内单条信号没像 doctor rule / eval sample 那么细的 id,用类型标即可。 */
+    observeRefs?: string[];
+}
+export interface Insight {
+    id: string;
+    category: InsightCategory;
+    audience: InsightAudience;
+    /** 用户语标题。 */
+    title: string;
+    /** 一句话现象描述(标题之外的细节)。 */
+    description?: string;
+    severity: InsightSeverity;
+    affectedCount: number;
+    evidence: InsightEvidence[];
+    recommendations: InsightRecommendation[];
+    /** 关联到 timeline 哪些阶段元素 — renderer 据此在阶段卡内插入 #N 徽章。 */
+    stageRefs?: InsightStageRefs;
+}
+export interface DetectInsightsOptions {
+    /**
+     * Diagnosis 是 observe 侧迁移后的主数据源。传入该字段时,observe 相关 insight
+     * 从 Diagnosis 投影,不再从 entry.observe 重复推断,避免维护者新增规则时双写。
+     */
+    diagnostics?: Diagnosis[];
+}
+export declare function projectDiagnosticsToInsights(diagnostics: Diagnosis[]): Insight[];
+export declare function detectInsights(entry: SkillIndexEntry, evalReport: EvaluationReport | null, options?: DetectInsightsOptions): Insight[];
+export declare function flattenRecommendations(insights: Insight[]): InsightRecommendation[];
+/** 按 audience 分桶 — UI 拆区用。 */
+export declare function groupInsightsByAudience(insights: Insight[]): Record<InsightAudience, Insight[]>;
+export type _SkillEvalSnapshotForInsight = SkillEvalSnapshot;
+//# sourceMappingURL=skill-insights.d.ts.map

package/dist/src/server/skill-insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-insights.d.ts","sourceRoot":"","sources":["../../../src/server/skill-insights.ts"],"names":[],"mappings":"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"}