mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 22:35:51 +00:00
feat: 添加 skill learning 技能学习闭环系统
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
unraid
499
src/services/skillLearning/skillGapStore.ts
Normal file
499
src/services/skillLearning/skillGapStore.ts
Normal file
@@ -0,0 +1,499 @@
|
||||
import { existsSync } from 'node:fs'
|
||||
import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
|
||||
import { createHash } from 'node:crypto'
|
||||
import { dirname, join } from 'node:path'
|
||||
import type { SearchResult } from '../skillSearch/localSearch.js'
|
||||
import { createInstinct, type StoredInstinct } from './instinctParser.js'
|
||||
import {
|
||||
getProjectStorageDir,
|
||||
resolveProjectContext,
|
||||
} from './projectContext.js'
|
||||
import { generateSkillDraft, writeLearnedSkill } from './skillGenerator.js'
|
||||
import type {
|
||||
InstinctDomain,
|
||||
SkillGapStatus,
|
||||
SkillLearningProjectContext,
|
||||
} from './types.js'
|
||||
|
||||
export type SkillGapRecommendation = Pick<
|
||||
SearchResult,
|
||||
'name' | 'description' | 'score'
|
||||
>
|
||||
|
||||
export type SkillGapMaterialization =
|
||||
| {
|
||||
type: 'draft'
|
||||
name: string
|
||||
skillPath: string
|
||||
}
|
||||
| {
|
||||
type: 'active'
|
||||
name: string
|
||||
skillPath: string
|
||||
}
|
||||
|
||||
export type SkillGapRecord = {
|
||||
key: string
|
||||
prompt: string
|
||||
count: number
|
||||
draftHits: number
|
||||
// Session IDs that have already contributed a draft hit for this gap —
|
||||
// prevents one session from inflating `draftHits` beyond 1 and flipping the
|
||||
// `draftHits >= 2` active-promotion gate by itself.
|
||||
draftHitSessions: string[]
|
||||
status: SkillGapStatus
|
||||
sessionId: string
|
||||
cwd: string
|
||||
projectId: string
|
||||
projectName: string
|
||||
recommendations: SkillGapRecommendation[]
|
||||
createdAt: string
|
||||
updatedAt: string
|
||||
draft?: SkillGapMaterialization
|
||||
active?: SkillGapMaterialization
|
||||
}
|
||||
|
||||
// P0-2 hook: when outcome-aware observation lands, augment this with a
|
||||
// lookup into observationStore for a matching `outcome: 'success'` tool_complete
|
||||
// observation keyed by (sessionId, gap.key). Until then, draft promotion uses
|
||||
// count/signal only.
|
||||
const DRAFT_PROMOTION_COUNT = 2
|
||||
const ACTIVE_PROMOTION_COUNT = 4
|
||||
const ACTIVE_PROMOTION_DRAFT_HITS = 2
|
||||
|
||||
type SkillGapState = {
|
||||
version: 1
|
||||
gaps: Record<string, SkillGapRecord>
|
||||
}
|
||||
|
||||
export type RecordSkillGapOptions = {
|
||||
prompt: string
|
||||
cwd?: string
|
||||
sessionId?: string
|
||||
recommendations?: SearchResult[]
|
||||
project?: SkillLearningProjectContext
|
||||
rootDir?: string
|
||||
}
|
||||
|
||||
export async function recordSkillGap(
|
||||
options: RecordSkillGapOptions,
|
||||
): Promise<SkillGapRecord> {
|
||||
const prompt = options.prompt.trim()
|
||||
if (!prompt) {
|
||||
throw new Error('Cannot record an empty skill gap')
|
||||
}
|
||||
|
||||
const project = options.project ?? resolveProjectContext(options.cwd)
|
||||
const state = await readSkillGapState(project, options.rootDir)
|
||||
const key = buildSkillGapKey(prompt)
|
||||
const now = new Date().toISOString()
|
||||
const existing = state.gaps[key]
|
||||
|
||||
const gap: SkillGapRecord = {
|
||||
key,
|
||||
prompt,
|
||||
count: (existing?.count ?? 0) + 1,
|
||||
draftHits: existing?.draftHits ?? 0,
|
||||
draftHitSessions: existing?.draftHitSessions ?? [],
|
||||
status: existing?.status ?? 'pending',
|
||||
sessionId: options.sessionId ?? 'unknown-session',
|
||||
cwd: options.cwd ?? project.cwd,
|
||||
projectId: project.projectId,
|
||||
projectName: project.projectName,
|
||||
recommendations: (options.recommendations ?? []).slice(0, 5).map(r => ({
|
||||
name: r.name,
|
||||
description: r.description,
|
||||
score: r.score,
|
||||
})),
|
||||
createdAt: existing?.createdAt ?? now,
|
||||
updatedAt: now,
|
||||
draft: existing?.draft,
|
||||
active: existing?.active,
|
||||
}
|
||||
|
||||
if (gap.status === 'rejected') {
|
||||
state.gaps[key] = gap
|
||||
await writeSkillGapState(project, state, options.rootDir)
|
||||
return gap
|
||||
}
|
||||
|
||||
if (!gap.draft && shouldPromoteToDraft(gap)) {
|
||||
gap.draft = await writeSkillGapDraft(gap, project)
|
||||
gap.status = 'draft'
|
||||
await clearRuntimeSkillCaches()
|
||||
}
|
||||
|
||||
if (gap.draft && !gap.active && shouldPromoteToActive(gap)) {
|
||||
gap.active = await writeActiveSkillForGap(gap, project)
|
||||
gap.status = 'active'
|
||||
await clearRuntimeSkillCaches()
|
||||
}
|
||||
|
||||
state.gaps[key] = gap
|
||||
await writeSkillGapState(project, state, options.rootDir)
|
||||
return gap
|
||||
}
|
||||
|
||||
export async function readSkillGaps(
|
||||
project = resolveProjectContext(),
|
||||
rootDir?: string,
|
||||
): Promise<SkillGapRecord[]> {
|
||||
const state = await readSkillGapState(project, rootDir)
|
||||
return Object.values(state.gaps).sort((a, b) => a.key.localeCompare(b.key))
|
||||
}
|
||||
|
||||
export async function findGapKeyByDraftPath(
|
||||
draftPath: string,
|
||||
project = resolveProjectContext(),
|
||||
rootDir?: string,
|
||||
): Promise<string | undefined> {
|
||||
const state = await readSkillGapState(project, rootDir)
|
||||
for (const gap of Object.values(state.gaps)) {
|
||||
if (gap.draft?.skillPath === draftPath) return gap.key
|
||||
}
|
||||
return undefined
|
||||
}
|
||||
|
||||
export async function recordDraftHit(
|
||||
key: string,
|
||||
project = resolveProjectContext(),
|
||||
rootDir?: string,
|
||||
sessionId = 'unknown-session',
|
||||
): Promise<SkillGapRecord | undefined> {
|
||||
const state = await readSkillGapState(project, rootDir)
|
||||
const gap = state.gaps[key]
|
||||
if (!gap || !gap.draft || gap.active) return gap
|
||||
// One draft hit per session: a single actor reloading the same draft
|
||||
// repeatedly must not flip the draftHits>=2 gate.
|
||||
const existingSessions = gap.draftHitSessions ?? []
|
||||
if (existingSessions.includes(sessionId)) return gap
|
||||
const now = new Date().toISOString()
|
||||
const updated: SkillGapRecord = {
|
||||
...gap,
|
||||
draftHits: gap.draftHits + 1,
|
||||
draftHitSessions: [...existingSessions, sessionId],
|
||||
updatedAt: now,
|
||||
}
|
||||
|
||||
if (shouldPromoteToActive(updated)) {
|
||||
updated.active = await writeActiveSkillForGap(updated, project)
|
||||
updated.status = 'active'
|
||||
await clearRuntimeSkillCaches()
|
||||
}
|
||||
|
||||
state.gaps[key] = updated
|
||||
await writeSkillGapState(project, state, rootDir)
|
||||
return updated
|
||||
}
|
||||
|
||||
export async function promoteGapToDraft(
|
||||
key: string,
|
||||
project = resolveProjectContext(),
|
||||
rootDir?: string,
|
||||
): Promise<SkillGapRecord | undefined> {
|
||||
const state = await readSkillGapState(project, rootDir)
|
||||
const gap = state.gaps[key]
|
||||
if (!gap) return undefined
|
||||
if (gap.status === 'rejected') return gap
|
||||
if (gap.draft) return gap
|
||||
const updated: SkillGapRecord = {
|
||||
...gap,
|
||||
draft: await writeSkillGapDraft(gap, project),
|
||||
status: 'draft',
|
||||
updatedAt: new Date().toISOString(),
|
||||
}
|
||||
state.gaps[key] = updated
|
||||
await writeSkillGapState(project, state, rootDir)
|
||||
await clearRuntimeSkillCaches()
|
||||
return updated
|
||||
}
|
||||
|
||||
export async function rejectSkillGap(
|
||||
key: string,
|
||||
project = resolveProjectContext(),
|
||||
rootDir?: string,
|
||||
): Promise<SkillGapRecord | undefined> {
|
||||
const state = await readSkillGapState(project, rootDir)
|
||||
const gap = state.gaps[key]
|
||||
if (!gap) return undefined
|
||||
const updated: SkillGapRecord = {
|
||||
...gap,
|
||||
status: 'rejected',
|
||||
updatedAt: new Date().toISOString(),
|
||||
}
|
||||
state.gaps[key] = updated
|
||||
await writeSkillGapState(project, state, rootDir)
|
||||
return updated
|
||||
}
|
||||
|
||||
export function shouldPromoteToDraft(gap: SkillGapRecord): boolean {
|
||||
// Draft promotion now requires repeated occurrence. The legacy
|
||||
// `isStrongReusableSignal` path was the cause of single-utterance Chinese
|
||||
// exhortations being promoted straight to active — P0-2 will reintroduce
|
||||
// outcome-aware signal once the observation layer supplies it.
|
||||
return gap.count >= DRAFT_PROMOTION_COUNT
|
||||
}
|
||||
|
||||
export function shouldPromoteToActive(gap: SkillGapRecord): boolean {
|
||||
if (!gap.draft) return false
|
||||
return (
|
||||
gap.count >= ACTIVE_PROMOTION_COUNT ||
|
||||
gap.draftHits >= ACTIVE_PROMOTION_DRAFT_HITS
|
||||
)
|
||||
}
|
||||
|
||||
async function writeSkillGapDraft(
|
||||
gap: SkillGapRecord,
|
||||
project: SkillLearningProjectContext,
|
||||
): Promise<SkillGapMaterialization> {
|
||||
const instinct = createGapInstinct(gap, 'pending')
|
||||
const draftsRoot = join(
|
||||
project.projectRoot ?? project.cwd,
|
||||
'.claude',
|
||||
'skills',
|
||||
'.drafts',
|
||||
)
|
||||
const draft = generateSkillDraft([instinct], {
|
||||
cwd: project.projectRoot ?? project.cwd,
|
||||
outputRoot: draftsRoot,
|
||||
scope: 'project',
|
||||
name: `draft-${buildNameFragment(gap.prompt)}`,
|
||||
description:
|
||||
'Draft learned skill candidate. Promote after repeated evidence or explicit user correction.',
|
||||
})
|
||||
const skillFile = join(draft.outputPath, 'SKILL.md')
|
||||
if (!existsSync(skillFile)) {
|
||||
await writeLearnedSkill({
|
||||
...draft,
|
||||
content:
|
||||
draft.content +
|
||||
'\n## Promotion Rule\n\nDo not move this draft into active skills until the same gap repeats or the user explicitly confirms this should become reusable.\n',
|
||||
})
|
||||
}
|
||||
return { type: 'draft', name: draft.name, skillPath: skillFile }
|
||||
}
|
||||
|
||||
async function writeActiveSkillForGap(
|
||||
gap: SkillGapRecord,
|
||||
project: SkillLearningProjectContext,
|
||||
): Promise<SkillGapMaterialization> {
|
||||
const instinct = createGapInstinct(gap, 'active')
|
||||
const draft = generateSkillDraft([instinct], {
|
||||
cwd: project.projectRoot ?? project.cwd,
|
||||
scope: 'project',
|
||||
name: buildNameFragment(gap.prompt),
|
||||
description: buildGapAction(gap.prompt),
|
||||
})
|
||||
const skillFile = join(draft.outputPath, 'SKILL.md')
|
||||
if (!existsSync(skillFile)) {
|
||||
await writeLearnedSkill(draft)
|
||||
}
|
||||
return { type: 'active', name: draft.name, skillPath: skillFile }
|
||||
}
|
||||
|
||||
function createGapInstinct(
|
||||
gap: SkillGapRecord,
|
||||
status: StoredInstinct['status'],
|
||||
): StoredInstinct {
|
||||
return createInstinct({
|
||||
trigger: `When the user asks for ${summarize(gap.prompt, 120)}`,
|
||||
action: buildGapAction(gap.prompt),
|
||||
confidence: status === 'active' ? 0.82 : 0.55,
|
||||
domain: inferDomain(gap.prompt),
|
||||
source: 'session-observation',
|
||||
scope: 'project',
|
||||
projectId: gap.projectId,
|
||||
projectName: gap.projectName,
|
||||
evidence: [
|
||||
`Skill gap prompt: ${summarize(gap.prompt, 180)}`,
|
||||
`No high-confidence active skill was auto-loaded.`,
|
||||
`Observed ${gap.count} time(s).`,
|
||||
],
|
||||
status,
|
||||
})
|
||||
}
|
||||
|
||||
function buildGapAction(prompt: string): string {
|
||||
if (
|
||||
/feature\s*\(|feature flag|flag_name|stub|no-op|noop|最小实现/i.test(prompt)
|
||||
) {
|
||||
return 'Audit feature flags by scanning feature() call sites, excluding generated/dependency noise, classifying each candidate as stub, shell, MVP, or thin-toggle, and writing an evidence-backed document.'
|
||||
}
|
||||
if (/skill|技能|学习|进化|evolve|learning/i.test(prompt)) {
|
||||
return 'Run skill discovery first; auto-load only high-confidence matching skills; record a skill gap when none match; promote repeated or corrected gaps into learned skills.'
|
||||
}
|
||||
if (/test|测试|stub|调用链|参数/i.test(prompt)) {
|
||||
return 'Infer tests from existing files, parameters, exports, and call chains before simplifying mocks or inventing behavior.'
|
||||
}
|
||||
return `Reuse the workflow learned from this prompt: ${summarize(prompt, 180)}.`
|
||||
}
|
||||
|
||||
function inferDomain(prompt: string): InstinctDomain {
|
||||
const text = prompt.toLowerCase()
|
||||
if (/test|测试|stub|fixture|断言/.test(text)) return 'testing'
|
||||
if (/error|bug|fix|失败|错误|修复|debug/.test(text)) return 'debugging'
|
||||
if (/security|安全|漏洞|secret|token/.test(text)) return 'security'
|
||||
if (/git|commit|branch|pr\b/.test(text)) return 'git'
|
||||
if (/style|lint|format|命名|规范/.test(text)) return 'code-style'
|
||||
return 'workflow'
|
||||
}
|
||||
|
||||
async function readSkillGapState(
|
||||
project: SkillLearningProjectContext,
|
||||
rootDir?: string,
|
||||
): Promise<SkillGapState> {
|
||||
const path = getSkillGapStatePath(project, rootDir)
|
||||
let raw: string
|
||||
try {
|
||||
raw = await readFile(path, 'utf8')
|
||||
} catch (error) {
|
||||
// Only treat "file doesn't exist yet" as empty state. Every other error
|
||||
// (EACCES, EIO, disk full, etc.) must throw — swallowing them here would
|
||||
// let a subsequent write persist {} and zero out all gap records.
|
||||
if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
|
||||
return { version: 1, gaps: {} }
|
||||
}
|
||||
throw error
|
||||
}
|
||||
try {
|
||||
return migrateLegacyGapState(JSON.parse(raw) as SkillGapState)
|
||||
} catch {
|
||||
// Corrupt/truncated JSON — don't silently reset. Backup and start fresh,
|
||||
// so the crash isn't masked and the data can be recovered manually.
|
||||
const backup = `${path}.corrupt-${Date.now()}`
|
||||
try {
|
||||
await writeFile(backup, raw, 'utf8')
|
||||
} catch {
|
||||
/* best effort */
|
||||
}
|
||||
return { version: 1, gaps: {} }
|
||||
}
|
||||
}
|
||||
|
||||
function migrateLegacyGapState(state: SkillGapState): SkillGapState {
|
||||
const migrated: Record<string, SkillGapRecord> = {}
|
||||
for (const [key, record] of Object.entries(state.gaps ?? {})) {
|
||||
const legacy = record as Partial<SkillGapRecord> & {
|
||||
status?: unknown
|
||||
}
|
||||
const draftHits =
|
||||
typeof legacy.draftHits === 'number' && Number.isFinite(legacy.draftHits)
|
||||
? legacy.draftHits
|
||||
: 0
|
||||
const count = typeof legacy.count === 'number' ? legacy.count : 1
|
||||
const normalizedStatus = normalizeLegacyStatus(legacy.status)
|
||||
const hasDraftFile = Boolean(legacy.draft)
|
||||
const hasActiveFile = Boolean(legacy.active)
|
||||
|
||||
let status: SkillGapStatus = normalizedStatus
|
||||
if (status === 'draft' && count < DRAFT_PROMOTION_COUNT && !hasDraftFile) {
|
||||
// Legacy first-call-writes-draft artifact with no file on disk yet.
|
||||
status = 'pending'
|
||||
}
|
||||
if (status === 'active' && !hasActiveFile) {
|
||||
status = hasDraftFile ? 'draft' : 'pending'
|
||||
}
|
||||
|
||||
const draftHitSessions = Array.isArray(legacy.draftHitSessions)
|
||||
? legacy.draftHitSessions.filter(
|
||||
(session): session is string => typeof session === 'string',
|
||||
)
|
||||
: []
|
||||
migrated[key] = {
|
||||
...(record as SkillGapRecord),
|
||||
count,
|
||||
draftHits,
|
||||
draftHitSessions,
|
||||
status,
|
||||
}
|
||||
}
|
||||
return { version: 1, gaps: migrated }
|
||||
}
|
||||
|
||||
function normalizeLegacyStatus(value: unknown): SkillGapStatus {
|
||||
if (
|
||||
value === 'pending' ||
|
||||
value === 'draft' ||
|
||||
value === 'active' ||
|
||||
value === 'rejected'
|
||||
) {
|
||||
return value
|
||||
}
|
||||
return 'pending'
|
||||
}
|
||||
|
||||
async function writeSkillGapState(
|
||||
project: SkillLearningProjectContext,
|
||||
state: SkillGapState,
|
||||
rootDir?: string,
|
||||
): Promise<void> {
|
||||
const path = getSkillGapStatePath(project, rootDir)
|
||||
await mkdir(dirname(path), { recursive: true })
|
||||
// Atomic write: temp + rename. A direct writeFile leaves a truncated file
|
||||
// on crash mid-write; combined with the (now strict) readSkillGapState,
|
||||
// that would lose gap records.
|
||||
const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`
|
||||
await writeFile(tmpPath, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
|
||||
await rename(tmpPath, path)
|
||||
}
|
||||
|
||||
function getSkillGapStatePath(
|
||||
project: SkillLearningProjectContext,
|
||||
rootDir?: string,
|
||||
): string {
|
||||
const base = rootDir
|
||||
? project.projectId === 'global'
|
||||
? join(rootDir, 'global')
|
||||
: join(rootDir, 'projects', project.projectId)
|
||||
: getProjectStorageDir(project.projectId)
|
||||
return join(base, 'skill-gaps.json')
|
||||
}
|
||||
|
||||
function buildSkillGapKey(prompt: string): string {
|
||||
return `${buildNameFragment(prompt)}-${hash(prompt).slice(0, 8)}`
|
||||
}
|
||||
|
||||
function buildNameFragment(prompt: string): string {
|
||||
const mapped = prompt
|
||||
.replaceAll('技能', ' skill ')
|
||||
.replaceAll('学习', ' learning ')
|
||||
.replaceAll('进化', ' evolution ')
|
||||
.replaceAll('测试', ' testing ')
|
||||
.replaceAll('最小实现', ' minimal implementation ')
|
||||
.toLowerCase()
|
||||
const stop = new Set([
|
||||
'the',
|
||||
'and',
|
||||
'for',
|
||||
'with',
|
||||
'this',
|
||||
'that',
|
||||
'user',
|
||||
'about',
|
||||
'feature',
|
||||
'flag',
|
||||
'name',
|
||||
])
|
||||
const words = (mapped.match(/[a-z0-9][a-z0-9_-]{2,}/g) ?? [])
|
||||
.filter(word => !stop.has(word))
|
||||
.slice(0, 5)
|
||||
const value = words.join('-') || 'learned-gap'
|
||||
return value.slice(0, 54).replace(/-+$/g, '')
|
||||
}
|
||||
|
||||
function summarize(value: string, max: number): string {
|
||||
return value.replace(/\s+/g, ' ').trim().slice(0, max)
|
||||
}
|
||||
|
||||
function hash(value: string): string {
|
||||
return createHash('sha1').update(value).digest('hex')
|
||||
}
|
||||
|
||||
async function clearRuntimeSkillCaches(): Promise<void> {
|
||||
try {
|
||||
const { clearCommandsCache } = await import('../../commands.js')
|
||||
clearCommandsCache()
|
||||
} catch {
|
||||
// Best effort only; generated skill files are still available next process.
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user