dsh-continual-evolve 0.15.3 → 0.15.5

package/lib/skill-tools.js

@@ -0,0 +1,198 @@
+/**
+ * The model-facing skill tools: `skill_write` (the explicit write path
+ * through the store's gates, plus the manual move to the global scope) and
+ * `skill_read` (bodies and search across the project partition and the
+ * global scope, project shadowing global on name collisions).
+ *
+ * Skills are created in the project only — global rows arise solely from an
+ * explicit `move-to-global`. There is no promotion mechanism: no counters,
+ * no confidence, no automation. Definitions are hand-built to the shape
+ * `ctx.tools.register` consumes (standard JSON Schema with a root-level
+ * `required` array, docs/FAQ.md #2). Host API shapes are declared locally;
+ * the plugin imports nothing from DSH at runtime.
+ */
+import { cwdOf } from "./memory-section.js";
+function textTool(name, description, parameters, execute) {
+    return {
+        name,
+        description,
+        parameters,
+        output: {
+            schema: {
+                type: "object",
+                properties: { text: { type: "string", description: "结果说明" } },
+                required: ["text"],
+                additionalProperties: false,
+            },
+            render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
+        },
+        execute: async (args, exec) => ({ text: await execute(args, exec) }),
+    };
+}
+/** The calling agent's session id (provenance for the ledger). */
+function sessionIdOf(exec) {
+    const id = exec?.agent?.id;
+    return typeof id === "string" && id.length > 0 ? id : undefined;
+}
+const SKILL_WRITE_PARAMETERS = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["create", "update", "delete", "move-to-global"],
+            description: "create 在本项目新建技能；update 更新已有技能（只给要改的字段）；delete 删除技能；move-to-global 把本项目技能手动搬到全局（项目侧归档，没有自动晋升）。",
+        },
+        scope: {
+            type: "string",
+            enum: ["project", "global"],
+            description: "update/delete 的目标分区（默认 project；全局行只可显式指定 global 更新或删除）。",
+        },
+        id: {
+            type: "string",
+            description: "短横线小写标识。update/delete/move-to-global 必填；create 可省略（从 title 推导，中文标题会得到哈希后缀）。",
+        },
+        title: { type: "string", description: "短标题（create 必填）。" },
+        description: {
+            type: "string",
+            description: "一句话触发钩子——决定未来会话会不会想起这个技能（create 必填，会进 SKILL.md 的 description）。",
+        },
+        body: { type: "string", description: "技能正文（create 必填；update 时传新正文整体替换）。" },
+    },
+    required: ["action"],
+    additionalProperties: false,
+};
+const SKILL_READ_PARAMETERS = {
+    type: "object",
+    properties: {
+        id: { type: "string", description: "按 id 直取一条技能的完整内容（同名时项目遮蔽全局）。" },
+        query: { type: "string", description: "关键词检索（不传 id 时生效；不传 query 则列出本项目与全局技能）。" },
+        limit: { type: "number", description: "检索/列出的最大条数，默认 3，上限 10。" },
+    },
+    additionalProperties: false,
+};
+/**
+ * Register the skill tools and return a disposer that removes them (the
+ * host may return one; call only the functions among whatever comes back).
+ */
+export function registerSkillTools(tools, store) {
+    const disposers = [];
+    disposers.push(tools.register(textTool("skill_write", "写入可复用的技能（create 新建 / update 更新 / delete 删除 / move-to-global 手动搬到全局）。用户明确要求沉淀技能时使用；技能只在本项目创建，全局只接受手动搬家，由插件代码校验后落库并物化为 SKILL.md。", SKILL_WRITE_PARAMETERS, async (args, exec) => {
+        const cwd = cwdOf(exec.agent);
+        if (cwd === undefined) {
+            return "错误：当前会话没有可用的工作区路径，无法写入技能。";
+        }
+        const action = args.action;
+        const { outcomes, warnings } = store.applySkillProposals({ workspaceId: cwd, trigger: "explicit", sessionId: sessionIdOf(exec) }, [
+            {
+                action,
+                scope: typeof args.scope === "string" ? args.scope : undefined,
+                id: typeof args.id === "string" ? args.id : undefined,
+                title: typeof args.title === "string" ? args.title : undefined,
+                description: typeof args.description === "string" ? args.description : undefined,
+                body: typeof args.body === "string" ? args.body : undefined,
+            },
+        ]);
+        const outcome = outcomes[0];
+        if (outcome === undefined || !outcome.ok) {
+            return `写入被门禁拒绝，技能未落盘：${outcome?.reason ?? "未知原因"}`;
+        }
+        const warningText = warnings.length > 0 ? `（文件投影告警：${warnings.map((w) => w.warning).join("；")}）` : "";
+        if (outcome.action === "delete") {
+            return `已删除技能 \`${outcome.id}\`。旧内容保留在技能账本中，可由用户恢复。${warningText}`;
+        }
+        if (outcome.action === "move-to-global") {
+            return `已把技能 \`${outcome.id}\` 手动搬到全局（本项目侧已归档）。重启后所有工作区可用。${warningText}`;
+        }
+        return `已${outcome.action === "create" ? "写入" : "更新"}技能 \`${outcome.id}\`（本项目，重启后本工作区可用）。${warningText}`;
+    })));
+    disposers.push(tools.register(textTool("skill_read", "读取技能：按 id 取一条的完整内容，或按关键词检索本项目与全局的技能（同名时项目遮蔽全局，只返回项目那条）。", SKILL_READ_PARAMETERS, async (args, exec) => {
+        const cwd = cwdOf(exec.agent);
+        if (cwd === undefined) {
+            return "错误：当前会话没有可用的工作区路径，无法读取技能。";
+        }
+        const limit = clampLimit(args.limit);
+        if (typeof args.id === "string" && args.id.length > 0) {
+            const found = readWithScope(store, cwd, args.id);
+            return found === undefined ? `没有找到 id 为 "${args.id}" 的技能。` : formatSkill(found.record, found.scope);
+        }
+        const query = typeof args.query === "string" ? args.query : "";
+        const merged = query.length > 0 ? searchWithScope(store, cwd, query, limit) : listWithScope(store, cwd, limit);
+        if (merged.length === 0) {
+            return query.length > 0 ? `没有匹配 "${query}" 的技能。` : "本项目和全局都还没有技能。";
+        }
+        return merged.map((entry) => formatSkill(entry.record, entry.scope)).join("\n\n---\n\n");
+    })));
+    return () => {
+        for (const disposer of disposers) {
+            if (typeof disposer === "function") {
+                disposer();
+            }
+        }
+    };
+}
+/** Project-first read: a project row shadows the global row of the same id. */
+function readWithScope(store, workspaceId, id) {
+    const project = store.getSkill(workspaceId, id);
+    if (project !== undefined && project.status !== "archived") {
+        return { record: project, scope: "project" };
+    }
+    const global = store.getSkill("", id);
+    if (global !== undefined && global.status !== "archived") {
+        return { record: global, scope: "global" };
+    }
+    return undefined;
+}
+/** Scope-merged search: project wins on id collisions, global fills the rest. */
+function searchWithScope(store, workspaceId, query, limit) {
+    const seen = new Set();
+    const merged = [];
+    for (const record of store.searchSkills(workspaceId, query, limit)) {
+        if (seen.has(record.id)) {
+            continue;
+        }
+        seen.add(record.id);
+        merged.push({ record, scope: "project" });
+    }
+    if (merged.length < limit) {
+        for (const record of store.searchSkills("", query, limit)) {
+            if (seen.has(record.id)) {
+                continue;
+            }
+            seen.add(record.id);
+            merged.push({ record, scope: "global" });
+        }
+    }
+    return merged.slice(0, limit);
+}
+/** Scope-merged listing: project rows first, then global rows. */
+function listWithScope(store, workspaceId, limit) {
+    const merged = store
+        .listSkills(workspaceId)
+        .slice(0, limit)
+        .map((record) => ({ record, scope: "project" }));
+    if (merged.length < limit) {
+        const seen = new Set(merged.map((entry) => entry.record.id));
+        for (const record of store.listSkills("")) {
+            if (merged.length >= limit) {
+                break;
+            }
+            if (seen.has(record.id)) {
+                continue;
+            }
+            seen.add(record.id);
+            merged.push({ record, scope: "global" });
+        }
+    }
+    return merged;
+}
+function clampLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return 3;
+    }
+    return Math.min(10, Math.max(1, Math.floor(value)));
+}
+/** Full skill text: header line with scope, then the body. */
+function formatSkill(record, scope) {
+    return [`# ${record.title}`, `id: ${record.id} ｜ 范围: ${scope === "global" ? "全局" : "本项目"} ｜ 状态: ${record.status} ｜ 更新: ${record.updatedAt}`, `钩子: ${record.description}`, "", record.body].join("\n");
+}
+//# sourceMappingURL=skill-tools.js.map

package/lib/store.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryProposal } from "./memory-rules.js";
+import { type SkillProposal } from "./skill-rules.js";
 import { type ProposalContext, type ProposalOutcome } from "./store-apply.js";
 export type { MemoryProposal, ProposalContext, ProposalOutcome };
 /** Thrown when the runtime lacks `node:sqlite` — the degrade signal. */
@@ -12,6 +13,36 @@ export declare const MD_IMPORT_STATE_KEY = "md-imported";
 export declare const GLOBAL_WORKSPACE = "";
 /** Preview size cap for the card's content endpoint (ZCode's viewer uses 5 MiB). */
 export declare const MEMORY_FILE_PREVIEW_LIMIT: number;
+/** One stored skill record (snake_case columns camelCased). Skills carry no type. */
+export interface SkillRecord {
+    workspaceId: string;
+    id: string;
+    title: string;
+    description: string;
+    body: string;
+    status: "active" | "quarantined" | "archived";
+    /** Origin session id, `null` for imports. */
+    sourceSession: string | null;
+    /** Trajectory seq range the skill came from ("820-831"), `null` when unknown. */
+    sourceSeqs: string | null;
+    /** The run that wrote it; `'explicit'` for tool writes. */
+    sourceRun: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a single skill proposal produced. */
+export interface SkillProposalOutcome {
+    id: string;
+    action: SkillProposal["action"];
+    ok: boolean;
+    /** Blocking reason when `ok` is false. */
+    reason?: string;
+}
+/** A non-fatal file-projection problem the caller should surface. */
+export interface SkillFileWarning {
+    id: string;
+    warning: string;
+}
 /** One stored memory record (snake_case columns camelCased). */
 export interface MemoryRecord {
     workspaceId: string;
@@ -67,6 +98,20 @@ export interface PatrolResult {
         id: string;
         reason: string;
     }[];
+    /** Orphan skill FTS rows (no matching skill) removed. */
+    skillOrphanFtsRows: number;
+    /** Skills quarantined by the secret screen, with the redacted reasons. */
+    skillQuarantined: {
+        workspaceId: string;
+        id: string;
+        reason: string;
+    }[];
+    /** Managed SKILL.md files rewritten or created to match the store. */
+    skillFilesReconciled: number;
+    /** Orphan managed SKILL.md files (no active store row) removed. */
+    skillOrphanFilesRemoved: number;
+    /** Managed file operations that failed (retried by the next patrol). */
+    skillFileErrors: number;
 }
 /** The store surface every consumer (tool, extraction, card, injection) uses. */
 export interface MemoryStore {
@@ -93,11 +138,11 @@ export interface MemoryStore {
     listWorkspaces(): WorkspaceSummary[];
     /**
      * The partition with the most recent session activity: the newest ledger
-     * instant against the newest memory write, whichever is later. The ledger
-     * carries a row for every run — including skips and explicit writes — so it
-     * tracks "a session worked here", while the memory write is the durable
-     * fallback for a partition whose ledger rows were pruned. Undefined only
-     * when the store holds neither.
+     * instant against the newest memory or skill write, whichever is later.
+     * The ledgers carry a row for every run — including skips and explicit
+     * writes — so they track "a session worked here", while the memory write
+     * is the durable fallback for a partition whose ledger rows were pruned.
+     * Undefined only when the store holds neither.
      */
     mostRecentlyActiveWorkspace(): string | undefined;
     /** Hygiene pass: orphan FTS cleanup + secret quarantine. */
@@ -105,6 +150,29 @@ export interface MemoryStore {
     /** Ledger rows older than the cutoff, removed (the one unbounded table). */
     pruneLedger(beforeIso: string): number;
     close(): void;
+    /** One active skill row from a partition, undefined when absent. */
+    getSkill(workspaceId: string, id: string): SkillRecord | undefined;
+    /** Active skills of one partition, newest first. */
+    listSkills(workspaceId: string): SkillRecord[];
+    /** Every non-archived skill of one partition, newest first. */
+    listAllSkills(workspaceId: string): SkillRecord[];
+    /**
+     * Keyword search over skills, workspace-scoped: same AND-combined
+     * trigram/LIKE discipline as memory search.
+     */
+    searchSkills(workspaceId: string, query: string, limit?: number): SkillRecord[];
+    /**
+     * The sole skill write gate: validate all proposals, apply atomically,
+     * ledger with before/after snapshots, then sync the materialized files.
+     * File sync never fails the batch — the database is the source of truth
+     * and patrol retries whatever the filesystem refused.
+     */
+    applySkillProposals(ctx: ProposalContext, proposals: readonly SkillProposal[]): {
+        outcomes: SkillProposalOutcome[];
+        warnings: SkillFileWarning[];
+    };
+    /** Partitions holding active skills (the card's skill fence). */
+    listSkillWorkspaces(): WorkspaceSummary[];
 }
 /** Default database location: `$DSH_HOME/evolve/memory.db`, else `~/.dsh/…`. */
 export declare function defaultStorePath(): string;