@deployxai/dxc 0.3.1 → 0.3.3

package/dist/chunks/{knowledge-JCYMCMSP.js → knowledge-QIIEPI2V.js}

@@ -7,23 +7,29 @@ import {
   CONTENT_KNOWLEDGE_EMBEDDING_REVISION,
   CONTENT_KNOWLEDGE_SCHEMA_VERSION,
   LocalStateError,
+  ProjectCli,
+  contentKnowledgeAdoptResultSchema,
   contentKnowledgeImportResultSchema,
   contentKnowledgeModelSchema,
   contentKnowledgeQuoteListResultSchema,
   contentKnowledgeQuoteMutationResultSchema,
   contentKnowledgeQuoteStatusResultSchema,
+  contentKnowledgeRefSchema,
   contentKnowledgeRemoveResultSchema,
   contentKnowledgeSearchModeSchema,
   contentKnowledgeSearchResultSchema,
+  contentKnowledgeSourceFilterSchema,
   contentKnowledgeStatusResultSchema,
+  contentWorkflowAdoptedKnowledgeSchema,
   ensurePrivateDirectory,
   ensurePrivateRegularFile,
   readPrivateBuffer,
   readPrivateFile,
   resolveUserPath,
+  withPrivateFileLocks,
   writePrivateBuffer,
   writePrivateJson
-} from "./chunk-6JNQZHAQ.js";
+} from "./chunk-P5VZG7OG.js";
 
 // apps/cli/src/knowledge.ts
 import { createHash as createHash2, randomUUID } from "node:crypto";
@@ -330,8 +336,6 @@ var LocalBgeKnowledgeEmbedder = class {
 };
 
 // apps/cli/src/knowledge.ts
-var DATABASE_DISPLAY_PATH = "~/.dxc/content-memory.sqlite";
-var QUOTE_SOURCE_DISPLAY_PATH = "~/Documents/DxC/\u91D1\u53E5\u5E93.md";
 var QUOTE_SOURCE_FILE_NAME = "\u91D1\u53E5\u5E93.md";
 var LEGACY_QUOTE_SOURCE_FILE_NAME = "quotes.json";
 var MAXIMUM_ARTICLE_BYTES = 5 * 1024 * 1024;
@@ -348,15 +352,20 @@ var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".markdown", ".txt"])
 var MAXIMUM_DIRECTORY_ARTICLES = 1e3;
 var MAXIMUM_DIRECTORY_DEPTH = 32;
 var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+var KNOWLEDGE_REF_PATTERN = /^kr1_([A-Za-z0-9_-]+)\.([a-f0-9]{32})$/u;
+var PROJECT_CONTEXT_FILE = ".dxc/context.json";
+var PROJECT_CONTEXT_MAXIMUM_BYTES = 64 * 1024;
 var KnowledgeCliError = class extends Error {
-  constructor(code, message, details) {
+  constructor(code, message, details, fields = { recovery: "\u8BF7\u6309 Skill \u8FD4\u56DE\u7684\u6062\u590D\u52A8\u4F5C\u91CD\u8BD5\u3002" }) {
     super(message);
     this.code = code;
     this.details = details;
+    this.fields = fields;
     this.name = "KnowledgeCliError";
   }
   code;
   details;
+  fields;
 };
 var quoteMetadataValueSchema = z.string().trim().min(1).max(300).refine((value) => !/[\r\n]/u.test(value) && value !== "\uFF08\u65E0\uFF09", {
   message: "quote metadata must stay on one line"
@@ -426,6 +435,75 @@ function skippedArticle(error, inputPath) {
 function sha2562(value) {
   return createHash2("sha256").update(value).digest("hex");
 }
+var projectContextStoreSchema = z.object({
+  adoptedKnowledge: z.array(
+    z.union([
+      contentWorkflowAdoptedKnowledgeSchema,
+      z.object({
+        attribution: z.string().trim().min(1).max(300).nullable(),
+        knowledgeRef: contentKnowledgeRefSchema,
+        label: z.string().trim().min(1).max(300),
+        snippet: z.string().trim().min(1).max(420),
+        sourceType: z.literal("quote"),
+        verbatimUse: z.literal("do-not-use-verbatim")
+      }).strict()
+    ])
+  ).max(20),
+  quoteVerbatimGuards: z.array(
+    z.object({
+      knowledgeRef: contentKnowledgeRefSchema,
+      text: z.string().trim().min(1).max(2e3)
+    }).strict()
+  ).max(20).default([]),
+  schemaVersion: z.literal("1")
+}).strict();
+function encodeKnowledgeRef(payload) {
+  const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+  return `kr1_${encoded}.${sha2562(encoded).slice(0, 32)}`;
+}
+function decodeKnowledgeRef(value) {
+  const match = KNOWLEDGE_REF_PATTERN.exec(value);
+  if (match?.[1] === void 0 || match[2] === void 0 || sha2562(match[1]).slice(0, 32) !== match[2]) {
+    throw new KnowledgeCliError(
+      "DXC_KNOWLEDGE_REFERENCE_INVALID",
+      "\u77E5\u8BC6\u5F15\u7528\u683C\u5F0F\u6216\u5B8C\u6574\u6027\u65E0\u6548\u3002",
+      void 0,
+      {
+        actual: value,
+        expected: "knowledge search \u8FD4\u56DE\u7684 knowledgeRef",
+        field: "item",
+        recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5E76\u4F7F\u7528\u5F53\u524D\u7ED3\u679C\u8FD4\u56DE\u7684 knowledgeRef\u3002"
+      }
+    );
+  }
+  try {
+    const payload = JSON.parse(Buffer.from(match[1], "base64url").toString("utf8"));
+    if (typeof payload !== "object" || payload === null || !("version" in payload) || payload.version !== 1 || !("sourceType" in payload) || payload.sourceType !== "history-article" && payload.sourceType !== "quote" || !("contentSha256" in payload) || typeof payload.contentSha256 !== "string") {
+      throw new Error("invalid");
+    }
+    return payload;
+  } catch {
+    throw new KnowledgeCliError(
+      "DXC_KNOWLEDGE_REFERENCE_INVALID",
+      "\u77E5\u8BC6\u5F15\u7528\u5185\u5BB9\u65E0\u6548\u3002",
+      void 0,
+      {
+        recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5E76\u4F7F\u7528\u5F53\u524D\u7ED3\u679C\u8FD4\u56DE\u7684 knowledgeRef\u3002"
+      }
+    );
+  }
+}
+function sameKnowledgeEntity(value, expected) {
+  try {
+    const actual = decodeKnowledgeRef(value);
+    if (actual.sourceType !== expected.sourceType) {
+      return false;
+    }
+    return actual.sourceType === "quote" ? actual.quoteId === (expected.sourceType === "quote" ? expected.quoteId : void 0) : actual.articleId === (expected.sourceType === "history-article" ? expected.articleId : void 0) && actual.chunkId === (expected.sourceType === "history-article" ? expected.chunkId : void 0);
+  } catch {
+    return false;
+  }
+}
 function knowledgeModelChoices(operation, inputFingerprint) {
   const choiceId = (mode) => {
     const payload = Buffer.from(
@@ -772,7 +850,6 @@ function articleSummary(row) {
   return {
     articleId: row.id,
     chunkCount: row.chunkCount,
-    contentSha256: row.contentSha256,
     importedAt: row.importedAt,
     sourceLabel: row.sourceLabel,
     title: row.title,
@@ -1151,10 +1228,26 @@ async function readQuoteSource(sourcePath, allowLegacyPermissions = false) {
     quotes: preparedQuotes(document.data)
   };
 }
-async function writeQuoteSource(sourcePath, quotes) {
+async function writeQuoteSource(sourcePath, quotes, expectedSha256) {
   try {
-    await writePrivateBuffer(sourcePath, Buffer.from(quoteSourceTemplate(quotes), "utf8"));
-  } catch {
+    if (expectedSha256 !== void 0) {
+      const current = await readQuoteSource(sourcePath);
+      if (current.contentSha256 !== expectedSha256) {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_REFERENCE_STALE",
+          "\u91D1\u53E5\u5E93\u5DF2\u88AB\u5176\u4ED6\u52A8\u4F5C\u6216\u7528\u6237\u4FEE\u6539\u3002",
+          void 0,
+          { recovery: "\u8BF7\u91CD\u65B0\u67E5\u770B\u91D1\u53E5\u5E93\uFF0C\u518D\u91CD\u505A\u672C\u6B21\u4FEE\u6539\u3002" }
+        );
+      }
+    }
+    const contents = quoteSourceTemplate(quotes);
+    await writePrivateBuffer(sourcePath, Buffer.from(contents, "utf8"));
+    return sha2562(contents);
+  } catch (error) {
+    if (error instanceof KnowledgeCliError) {
+      throw error;
+    }
     throw new KnowledgeCliError("DXC_KNOWLEDGE_IO_FAILED", "Unable to write quote source file");
   }
 }
@@ -1179,13 +1272,10 @@ function quoteSourceSummary(database, sourceInitialized) {
         FROM quotes`
     ).get()
   );
-  const source = database.prepare("SELECT content_sha256 FROM quote_sources WHERE source_key = 'default' LIMIT 1").get();
   return {
     activeCount: numberColumn(counts, "active_count"),
     archivedCount: numberColumn(counts, "archived_count"),
-    sourceInitialized,
-    sourcePath: QUOTE_SOURCE_DISPLAY_PATH,
-    sourceSha256: source === void 0 ? null : stringColumn(sqlRow(source), "content_sha256")
+    sourceInitialized
   };
 }
 function quoteEmbeddingText(quote) {
@@ -1397,9 +1487,11 @@ function semanticIndexComplete(database, articleId) {
   );
   return numberColumn(row, "total") > 0 && numberColumn(row, "total") === numberColumn(row, "indexed");
 }
-function saveArticle(database, article, existing, vectors, timestamp, createId) {
+function saveArticle(database, article, existing, vectors, timestamp, createId, manageTransaction = true) {
   const articleId = existing?.id ?? createId();
-  database.exec("BEGIN IMMEDIATE");
+  if (manageTransaction) {
+    database.exec("BEGIN IMMEDIATE");
+  }
   try {
     if (existing === void 0) {
       database.prepare(
@@ -1476,11 +1568,15 @@ function saveArticle(database, article, existing, vectors, timestamp, createId)
       );
       insertSearch.run(chunkId, articleId, article.title, chunk.heading ?? "", chunk.body);
     }
-    database.exec("COMMIT");
+    if (manageTransaction) {
+      database.exec("COMMIT");
+    }
   } catch (error) {
-    try {
-      database.exec("ROLLBACK");
-    } catch {
+    if (manageTransaction) {
+      try {
+        database.exec("ROLLBACK");
+      } catch {
+      }
     }
     if (error instanceof KnowledgeCliError) {
       throw error;
@@ -1651,12 +1747,15 @@ function fusedResults(chunks, mode, lexical, semantic, limit) {
     }
     articleCounts.set(chunk.articleId, (articleCounts.get(chunk.articleId) ?? 0) + 1);
     results.push({
-      articleId: chunk.articleId,
-      chunkId: chunk.id,
-      chunkSha256: chunk.chunkSha256,
       heading: chunk.heading,
+      knowledgeRef: encodeKnowledgeRef({
+        articleId: chunk.articleId,
+        chunkId: chunk.id,
+        contentSha256: chunk.chunkSha256,
+        sourceType: "history-article",
+        version: 1
+      }),
       lanes: [...score.lanes].sort(),
-      ordinal: chunk.ordinal,
       rank: results.length + 1,
       snippet: snippet(chunk.body),
       sourceLabel: chunk.sourceLabel,
@@ -1692,15 +1791,18 @@ function fusedQuoteResults(quotes, mode, lexical, semantic, limit) {
     }
     results.push({
       attribution: quote.attribution,
-      contentSha256: quote.contentSha256,
+      knowledgeRef: encodeKnowledgeRef({
+        contentSha256: quote.contentSha256,
+        quoteId: quote.id,
+        sourceType: "quote",
+        version: 1
+      }),
       lanes: [...score.lanes].sort(),
       origin: quote.origin,
-      quoteId: quote.id,
       rank: results.length + 1,
       snippet: snippet(quote.text),
       sourceLabel: quote.sourceLabel,
       sourceType: "quote",
-      status: quote.status,
       tags: [...quote.tags],
       verbatimUse: quote.verbatimUse
     });
@@ -1756,6 +1858,7 @@ var KnowledgeCli = class {
     try {
       const imported = [];
       const skipped = [];
+      const pending = [];
       let semanticPreparationAnnounced = false;
       for (const file of options.files) {
         let article;
@@ -1772,40 +1875,59 @@ var KnowledgeCli = class {
         const existing = findExistingArticle(database, article);
         const unchanged = existing?.contentSha256 === article.contentSha256 && existing.chunkerVersion === CONTENT_KNOWLEDGE_CHUNKER_VERSION;
         const semanticComplete = existing === void 0 ? false : semanticIndexComplete(database, existing.id);
-        if (unchanged && (options.lexicalOnly || semanticComplete)) {
-          imported.push({
-            article: articleSummary(existing),
-            semanticIndexed: semanticComplete,
-            status: "unchanged"
-          });
-          continue;
-        }
-        if (!options.lexicalOnly && !semanticPreparationAnnounced) {
+        const fullyUnchanged = unchanged && (options.lexicalOnly || semanticComplete);
+        if (!fullyUnchanged && !options.lexicalOnly && !semanticPreparationAnnounced) {
           this.#writeStderr(
             "Preparing the local semantic index; first use downloads a quantized model of about 24 MB.\n"
           );
           semanticPreparationAnnounced = true;
         }
-        const vectors = options.lexicalOnly ? void 0 : await embedArticle(this.#embedder, article);
-        const saved = saveArticle(
-          database,
+        pending.push({
           article,
           existing,
-          vectors,
-          this.#now().toISOString(),
-          this.#randomUUID
-        );
-        imported.push({
-          article: articleSummary(saved),
-          semanticIndexed: vectors !== void 0,
-          status: existing === void 0 ? "created" : "updated"
+          semanticComplete,
+          unchanged: fullyUnchanged,
+          vectors: fullyUnchanged || options.lexicalOnly ? void 0 : await embedArticle(this.#embedder, article)
         });
       }
+      database.exec("BEGIN IMMEDIATE");
+      try {
+        for (const item of pending) {
+          if (item.unchanged && item.existing !== void 0) {
+            imported.push({
+              article: articleSummary(item.existing),
+              semanticIndexed: item.semanticComplete,
+              status: "unchanged"
+            });
+            continue;
+          }
+          const saved = saveArticle(
+            database,
+            item.article,
+            item.existing,
+            item.vectors,
+            this.#now().toISOString(),
+            this.#randomUUID,
+            false
+          );
+          imported.push({
+            article: articleSummary(saved),
+            semanticIndexed: item.vectors !== void 0,
+            status: item.existing === void 0 ? "created" : "updated"
+          });
+        }
+        database.exec("COMMIT");
+      } catch (error) {
+        try {
+          database.exec("ROLLBACK");
+        } catch {
+        }
+        throw error;
+      }
       return contentKnowledgeImportResultSchema.parse({
         command: "knowledge.import",
         data: {
           imported,
-          model: options.lexicalOnly ? null : this.#embedder.model,
           skipped
         },
         ok: true
@@ -1873,144 +1995,219 @@ var KnowledgeCli = class {
     }
     await this.#syncQuotes(true);
   }
-  async listQuotes() {
+  async #withQuoteLock(action) {
     const sourcePath = quoteSourcePath(this.#homeDirectory);
-    if (!await quoteSourceExists(sourcePath)) {
-      await this.#initQuotes();
-    } else {
-      await this.#syncQuotes(true);
-    }
-    const source = await readQuoteSource(sourcePath);
-    return contentKnowledgeQuoteListResultSchema.parse({
-      command: "knowledge.quotes.list",
-      data: { quotes: source.quotes.map(quoteRecord) },
-      ok: true
+    return withPrivateFileLocks([sourcePath], action).catch((error) => {
+      if (error instanceof LocalStateError && error.failure === "busy") {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_BUSY",
+          "\u91D1\u53E5\u5E93\u6B63\u5728\u88AB\u53E6\u4E00\u4E2A\u52A8\u4F5C\u66F4\u65B0\u3002",
+          void 0,
+          {
+            recovery: "\u8BF7\u7B49\u5F85\u5F53\u524D\u91D1\u53E5\u52A8\u4F5C\u5B8C\u6210\u540E\u91CD\u8BD5\u540C\u4E00\u64CD\u4F5C\u3002",
+            retryable: true
+          }
+        );
+      }
+      throw error;
+    });
+  }
+  async listQuotes() {
+    return this.#withQuoteLock(async () => {
+      const sourcePath = quoteSourcePath(this.#homeDirectory);
+      if (!await quoteSourceExists(sourcePath)) {
+        await this.#initQuotes();
+      } else {
+        await this.#syncQuotes(true);
+      }
+      const source = await readQuoteSource(sourcePath);
+      return contentKnowledgeQuoteListResultSchema.parse({
+        command: "knowledge.quotes.list",
+        data: { quotes: source.quotes.map(quoteRecord) },
+        ok: true
+      });
     });
   }
   async addQuote(options) {
-    const sourcePath = quoteSourcePath(this.#homeDirectory);
-    if (!await quoteSourceExists(sourcePath)) {
-      await this.#initQuotes();
+    if (options.origin !== "original" && options.origin !== "third-party") {
+      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "\u91D1\u53E5\u6765\u6E90\u5F52\u5C5E\u65E0\u6548\u3002", void 0, {
+        candidates: ["original", "third-party"],
+        expected: "\u672C\u4EBA\u539F\u521B\u6216\u7B2C\u4E09\u65B9\u6765\u6E90",
+        field: "origin",
+        recovery: "\u8BF7\u5148\u786E\u8BA4\u91D1\u53E5\u662F\u5426\u4E3A\u7528\u6237\u672C\u4EBA\u539F\u521B\uFF0C\u518D\u6309\u91D1\u53E5 Skill \u63D0\u4EA4\u6765\u6E90\u5F52\u5C5E\u3002"
+      });
     }
-    const source = await readQuoteSource(sourcePath);
-    const duplicate = source.quotes.find(
-      (item) => item.status === "active" && item.text.trim() === options.text.trim()
-    );
-    if (duplicate !== void 0) {
-      await this.#syncQuotes(false);
+    const origin = options.origin;
+    return this.#withQuoteLock(async () => {
+      const sourcePath = quoteSourcePath(this.#homeDirectory);
+      if (!await quoteSourceExists(sourcePath)) {
+        await this.#initQuotes();
+      }
+      const source = await readQuoteSource(sourcePath);
+      const duplicate = source.quotes.find(
+        (item) => item.status === "active" && item.text.trim() === options.text.trim()
+      );
+      if (duplicate !== void 0) {
+        await this.#syncQuotes(false);
+        return contentKnowledgeQuoteMutationResultSchema.parse({
+          command: "knowledge.quotes.add",
+          data: { quote: quoteRecord(duplicate), synced: true },
+          ok: true
+        });
+      }
+      const quote = quoteSourceItemSchema.safeParse({
+        attribution: options.attribution ?? null,
+        origin,
+        quoteId: this.#randomUUID(),
+        source: options.source ?? null,
+        status: "active",
+        tags: options.tags ?? [],
+        text: options.text,
+        verbatimUse: options.verbatimUse ?? (origin === "third-party" ? "needs-verification" : "original")
+      });
+      if (!quote.success) {
+        throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "\u91D1\u53E5\u8F93\u5165\u65E0\u6548\u3002", void 0, {
+          candidates: ["original", "third-party"],
+          expected: "\u660E\u786E\u6765\u6E90\u5F52\u5C5E\uFF1B\u7B2C\u4E09\u65B9\u91D1\u53E5\u5FC5\u987B\u6709\u7F72\u540D",
+          field: quote.error.issues[0]?.path.join(".") || "quote",
+          recovery: "\u8BF7\u6309\u91D1\u53E5 Skill \u8865\u5145\u6765\u6E90\u5F52\u5C5E\u3001\u7F72\u540D\u548C\u4F7F\u7528\u8FB9\u754C\u3002"
+        });
+      }
+      const nextQuotes = [...source.quotes, quote.data];
+      const writtenSha256 = await writeQuoteSource(sourcePath, nextQuotes, source.contentSha256);
+      try {
+        await this.#syncQuotes(false);
+        if ((await readQuoteSource(sourcePath)).contentSha256 !== writtenSha256) {
+          throw new KnowledgeCliError(
+            "DXC_KNOWLEDGE_REFERENCE_STALE",
+            "\u91D1\u53E5\u5E93\u5728\u7D22\u5F15\u671F\u95F4\u88AB\u4FEE\u6539\u3002",
+            void 0,
+            { recovery: "\u8BF7\u91CD\u65B0\u67E5\u770B\u91D1\u53E5\u5E93\u5E76\u786E\u8BA4\u672C\u6B21\u6536\u5F55\u7ED3\u679C\u3002" }
+          );
+        }
+      } catch (error) {
+        if (error instanceof KnowledgeCliError && error.code === "DXC_KNOWLEDGE_REFERENCE_STALE") {
+          throw error;
+        }
+        await writeQuoteSource(sourcePath, source.quotes, writtenSha256);
+        throw error;
+      }
       return contentKnowledgeQuoteMutationResultSchema.parse({
         command: "knowledge.quotes.add",
-        data: { quote: quoteRecord(duplicate), synced: true },
+        data: { quote: quoteRecord(quote.data), synced: true },
         ok: true
       });
-    }
-    const quote = quoteSourceItemSchema.safeParse({
-      attribution: options.attribution ?? null,
-      origin: options.origin ?? "original",
-      quoteId: this.#randomUUID(),
-      source: options.source ?? null,
-      status: "active",
-      tags: options.tags ?? [],
-      text: options.text,
-      verbatimUse: options.verbatimUse ?? (options.origin === "third-party" ? "needs-verification" : "original")
-    });
-    if (!quote.success) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote input is invalid");
-    }
-    const nextQuotes = [...source.quotes, quote.data];
-    await writeQuoteSource(sourcePath, nextQuotes);
-    try {
-      await this.#syncQuotes(false);
-    } catch (error) {
-      await writeQuoteSource(sourcePath, source.quotes);
-      throw error;
-    }
-    return contentKnowledgeQuoteMutationResultSchema.parse({
-      command: "knowledge.quotes.add",
-      data: { quote: quoteRecord(quote.data), synced: true },
-      ok: true
     });
   }
   async updateQuote(quoteId, options) {
     if (!UUID_PATTERN.test(quoteId) || Object.keys(options).length === 0) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote update is invalid");
-    }
-    const sourcePath = quoteSourcePath(this.#homeDirectory);
-    if (!await quoteSourceExists(sourcePath)) {
-      await this.#initQuotes();
-    }
-    const source = await readQuoteSource(sourcePath);
-    const index = source.quotes.findIndex((quote) => quote.quoteId === quoteId);
-    if (index < 0) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote ID was not found");
-    }
-    const existing = source.quotes[index];
-    if (existing === void 0) {
-      throw new KnowledgeCliError(
-        "DXC_KNOWLEDGE_STATE_INVALID",
-        "Knowledge quote state is invalid"
-      );
-    }
-    const updated = quoteSourceItemSchema.safeParse({
-      ...sourceQuote(existing),
-      ...options,
-      attribution: options.attribution === void 0 ? existing.attribution ?? null : options.attribution,
-      source: options.source === void 0 ? existing.source ?? null : options.source,
-      tags: options.tags === void 0 ? existing.tags : options.tags,
-      verbatimUse: options.verbatimUse ?? (options.origin === "third-party" && existing.origin !== "third-party" ? "needs-verification" : existing.verbatimUse)
-    });
-    if (!updated.success) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote update is invalid");
-    }
-    const quotes = source.quotes.map(sourceQuote);
-    quotes[index] = updated.data;
-    await writeQuoteSource(sourcePath, quotes);
-    try {
-      await this.#syncQuotes(false);
-    } catch (error) {
-      await writeQuoteSource(sourcePath, source.quotes);
-      throw error;
+      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "\u91D1\u53E5\u66F4\u65B0\u8F93\u5165\u65E0\u6548\u3002", void 0, {
+        expected: "\u5F53\u524D\u91D1\u53E5 ID \u548C\u81F3\u5C11\u4E00\u4E2A\u53D8\u5316\u5B57\u6BB5",
+        field: "quote",
+        recovery: "\u8BF7\u91CD\u65B0\u5217\u51FA\u91D1\u53E5\u5E76\u53EA\u63D0\u4EA4\u7528\u6237\u660E\u786E\u4FEE\u6539\u7684\u5B57\u6BB5\u3002"
+      });
     }
-    return contentKnowledgeQuoteMutationResultSchema.parse({
-      command: "knowledge.quotes.update",
-      data: { quote: quoteRecord(updated.data), synced: true },
-      ok: true
+    return this.#withQuoteLock(async () => {
+      const sourcePath = quoteSourcePath(this.#homeDirectory);
+      if (!await quoteSourceExists(sourcePath)) {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_QUOTE_SOURCE_NOT_INITIALIZED",
+          "\u91D1\u53E5\u5E93\u5C1A\u672A\u521B\u5EFA\u3002",
+          void 0,
+          { recovery: "\u8BF7\u5148\u6536\u5F55\u7B2C\u4E00\u6761\u91D1\u53E5\uFF0C\u518D\u6267\u884C\u66F4\u65B0\u3002" }
+        );
+      }
+      const source = await readQuoteSource(sourcePath);
+      const index = source.quotes.findIndex((quote) => quote.quoteId === quoteId);
+      if (index < 0) {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_QUOTE_INVALID",
+          "\u6CA1\u6709\u627E\u5230\u8BE5\u91D1\u53E5 ID\u3002",
+          void 0,
+          {
+            actual: quoteId,
+            expected: "quotes list \u8FD4\u56DE\u7684 quoteId",
+            field: "quoteId",
+            recovery: "\u8BF7\u91CD\u65B0\u5217\u51FA\u91D1\u53E5\u5E76\u4F7F\u7528\u5F53\u524D ID\u3002"
+          }
+        );
+      }
+      const existing = source.quotes[index];
+      const updated = quoteSourceItemSchema.safeParse({
+        ...sourceQuote(existing),
+        ...options,
+        attribution: options.attribution === void 0 ? existing.attribution ?? null : options.attribution,
+        source: options.source === void 0 ? existing.source ?? null : options.source,
+        tags: options.tags === void 0 ? existing.tags : options.tags,
+        verbatimUse: options.verbatimUse ?? (options.origin === "third-party" && existing.origin !== "third-party" ? "needs-verification" : existing.verbatimUse)
+      });
+      if (!updated.success) {
+        throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "\u91D1\u53E5\u66F4\u65B0\u65E0\u6548\u3002", void 0, {
+          field: updated.error.issues[0]?.path.join(".") || "quote",
+          recovery: "\u8BF7\u8865\u9F50\u6765\u6E90\u3001\u7F72\u540D\u548C\u9010\u5B57\u4F7F\u7528\u8FB9\u754C\u540E\u91CD\u8BD5\u3002"
+        });
+      }
+      const quotes = source.quotes.map(sourceQuote);
+      quotes[index] = updated.data;
+      const writtenSha256 = await writeQuoteSource(sourcePath, quotes, source.contentSha256);
+      try {
+        await this.#syncQuotes(false);
+      } catch (error) {
+        await writeQuoteSource(sourcePath, source.quotes, writtenSha256);
+        throw error;
+      }
+      return contentKnowledgeQuoteMutationResultSchema.parse({
+        command: "knowledge.quotes.update",
+        data: { quote: quoteRecord(updated.data), synced: true },
+        ok: true
+      });
     });
   }
   async archiveQuote(quoteId) {
     if (!UUID_PATTERN.test(quoteId)) {
       throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote ID is invalid");
     }
-    const sourcePath = quoteSourcePath(this.#homeDirectory);
-    if (!await quoteSourceExists(sourcePath)) {
-      await this.#initQuotes();
-    }
-    const source = await readQuoteSource(sourcePath);
-    const index = source.quotes.findIndex((quote) => quote.quoteId === quoteId);
-    if (index < 0) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUOTE_INVALID", "Quote ID was not found");
-    }
-    const existing = source.quotes[index];
-    if (existing === void 0) {
-      throw new KnowledgeCliError(
-        "DXC_KNOWLEDGE_STATE_INVALID",
-        "Knowledge quote state is invalid"
-      );
-    }
-    const archived = { ...sourceQuote(existing), status: "archived" };
-    const quotes = source.quotes.map(sourceQuote);
-    quotes[index] = archived;
-    await writeQuoteSource(sourcePath, quotes);
-    try {
-      await this.#syncQuotes(false);
-    } catch (error) {
-      await writeQuoteSource(sourcePath, source.quotes);
-      throw error;
-    }
-    return contentKnowledgeQuoteMutationResultSchema.parse({
-      command: "knowledge.quotes.archive",
-      data: { quote: quoteRecord(archived), synced: true },
-      ok: true
+    return this.#withQuoteLock(async () => {
+      const sourcePath = quoteSourcePath(this.#homeDirectory);
+      if (!await quoteSourceExists(sourcePath)) {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_QUOTE_SOURCE_NOT_INITIALIZED",
+          "\u91D1\u53E5\u5E93\u5C1A\u672A\u521B\u5EFA\u3002",
+          void 0,
+          { recovery: "\u65E0\u9700\u5F52\u6863\uFF1B\u5F53\u524D\u6CA1\u6709\u91D1\u53E5\u5E93\u3002" }
+        );
+      }
+      const source = await readQuoteSource(sourcePath);
+      const index = source.quotes.findIndex((quote) => quote.quoteId === quoteId);
+      if (index < 0) {
+        throw new KnowledgeCliError(
+          "DXC_KNOWLEDGE_QUOTE_INVALID",
+          "\u6CA1\u6709\u627E\u5230\u8BE5\u91D1\u53E5 ID\u3002",
+          void 0,
+          {
+            actual: quoteId,
+            expected: "quotes list \u8FD4\u56DE\u7684 quoteId",
+            field: "quoteId",
+            recovery: "\u8BF7\u91CD\u65B0\u5217\u51FA\u91D1\u53E5\u5E76\u4F7F\u7528\u5F53\u524D ID\u3002"
+          }
+        );
+      }
+      const existing = source.quotes[index];
+      const archived = { ...sourceQuote(existing), status: "archived" };
+      const quotes = source.quotes.map(sourceQuote);
+      quotes[index] = archived;
+      const writtenSha256 = await writeQuoteSource(sourcePath, quotes, source.contentSha256);
+      try {
+        await this.#syncQuotes(false);
+      } catch (error) {
+        await writeQuoteSource(sourcePath, source.quotes, writtenSha256);
+        throw error;
+      }
+      return contentKnowledgeQuoteMutationResultSchema.parse({
+        command: "knowledge.quotes.archive",
+        data: { quote: quoteRecord(archived), synced: true },
+        ok: true
+      });
     });
   }
   async quoteStatus() {
@@ -2021,9 +2218,7 @@ var KnowledgeCli = class {
         data: {
           activeCount: 0,
           archivedCount: 0,
-          sourceInitialized,
-          sourcePath: QUOTE_SOURCE_DISPLAY_PATH,
-          sourceSha256: null
+          sourceInitialized
         },
         ok: true
       });
@@ -2083,58 +2278,89 @@ var KnowledgeCli = class {
       database.close();
     }
   }
-  async remove(articleId) {
-    if (!UUID_PATTERN.test(articleId)) {
+  async remove(knowledgeRef) {
+    const reference = decodeKnowledgeRef(knowledgeRef);
+    if (reference.sourceType !== "history-article") {
       throw new KnowledgeCliError(
         "DXC_KNOWLEDGE_ARTICLE_INVALID",
-        "Knowledge article ID is invalid"
+        "\u53EA\u6709\u5386\u53F2\u6587\u7AE0\u68C0\u7D22\u7ED3\u679C\u53EF\u4EE5\u7528\u4E8E\u5220\u9664\u6587\u7AE0\u3002",
+        void 0,
+        { recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5386\u53F2\u6587\u7AE0\uFF0C\u5E76\u539F\u6837\u4F7F\u7528\u76EE\u6807\u7ED3\u679C\u7684 knowledgeRef\u3002" }
       );
     }
+    const articleId = reference.articleId;
     if (!await databaseExists(this.#databasePath)) {
       return contentKnowledgeRemoveResultSchema.parse({
         command: "knowledge.remove",
-        data: { articleId, removed: false },
+        data: { knowledgeRef, removed: false },
         ok: true
       });
     }
     const database = await openDatabase(this.#databasePath);
     try {
+      let removed = false;
       database.exec("BEGIN IMMEDIATE");
       try {
+        const current = loadChunks(database).find(
+          (chunk) => chunk.id === reference.chunkId && chunk.articleId === reference.articleId
+        );
+        if (current === void 0 || current.chunkSha256 !== reference.contentSha256) {
+          throw new KnowledgeCliError(
+            "DXC_KNOWLEDGE_REFERENCE_STALE",
+            "\u5386\u53F2\u6587\u7AE0\u68C0\u7D22\u7ED3\u679C\u5DF2\u53D8\u5316\u3002",
+            void 0,
+            { recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5386\u53F2\u6587\u7AE0\uFF0C\u5E76\u8BA9\u7528\u6237\u91CD\u65B0\u9009\u62E9\u8981\u5220\u9664\u7684\u5F53\u524D\u7ED3\u679C\u3002" }
+          );
+        }
         database.prepare("DELETE FROM chunk_search WHERE article_id = ?").run(articleId);
         const result = database.prepare("DELETE FROM articles WHERE id = ?").run(articleId);
+        removed = result.changes > 0;
         database.exec("COMMIT");
-        return contentKnowledgeRemoveResultSchema.parse({
-          command: "knowledge.remove",
-          data: {
-            articleId,
-            removed: result.changes > 0
-          },
-          ok: true
-        });
-      } catch {
+      } catch (error) {
         database.exec("ROLLBACK");
+        if (error instanceof KnowledgeCliError) {
+          throw error;
+        }
         throw new KnowledgeCliError(
           "DXC_KNOWLEDGE_IO_FAILED",
           "Unable to remove knowledge article"
         );
       }
+      return contentKnowledgeRemoveResultSchema.parse({
+        command: "knowledge.remove",
+        data: { knowledgeRef, removed },
+        ok: true
+      });
     } finally {
       database.close();
     }
   }
-  async search(queryInput, modeInput, limitInput, choiceId) {
+  async search(queryInput, modeInput, limitInput, choiceId, sourceFilterInput = "all") {
     const query = queryInput.trim();
     const modelAction = knowledgeModelChoices(
       "search",
-      sha2562(JSON.stringify({ limit: limitInput, mode: modeInput, query }))
+      sha2562(
+        JSON.stringify({
+          limit: limitInput,
+          mode: modeInput,
+          query,
+          sourceFilter: sourceFilterInput
+        })
+      )
     );
     const selectedMode = selectedKnowledgeMode(modelAction, choiceId);
     const mode = contentKnowledgeSearchModeSchema.safeParse(
       selectedMode === "lexical" ? "lexical" : modeInput
     );
-    if (query.length === 0 || query.length > 500 || !mode.success || !Number.isSafeInteger(limitInput) || limitInput < 1 || limitInput > MAXIMUM_RESULTS) {
-      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUERY_INVALID", "Knowledge query is invalid");
+    const sourceFilter = contentKnowledgeSourceFilterSchema.safeParse(sourceFilterInput);
+    if (query.length === 0 || query.length > 500 || !mode.success || !sourceFilter.success || !Number.isSafeInteger(limitInput) || limitInput < 1 || limitInput > MAXIMUM_RESULTS) {
+      throw new KnowledgeCliError("DXC_KNOWLEDGE_QUERY_INVALID", "\u77E5\u8BC6\u68C0\u7D22\u8F93\u5165\u65E0\u6548\u3002", void 0, {
+        actual: !mode.success ? modeInput : !sourceFilter.success ? sourceFilterInput : queryInput,
+        candidates: !mode.success ? contentKnowledgeSearchModeSchema.options : contentKnowledgeSourceFilterSchema.options,
+        expected: "\u6709\u6548\u67E5\u8BE2\u3001\u68C0\u7D22\u6A21\u5F0F\u3001\u6765\u6E90\u8303\u56F4\u548C 1\u201320 \u6761\u7ED3\u679C\u6570",
+        field: !mode.success ? "mode" : !sourceFilter.success ? "source" : "query",
+        recovery: "\u8BF7\u6309\u5BF9\u5E94 Skill \u58F0\u660E\u7684\u68C0\u7D22\u52A8\u4F5C\u4FEE\u6B63\u5931\u8D25\u5B57\u6BB5\u3002"
+      });
     }
     if (!await databaseExists(this.#databasePath)) {
       return contentKnowledgeSearchResultSchema.parse({
@@ -2143,15 +2369,16 @@ var KnowledgeCli = class {
           mode: mode.data,
           model: mode.data === "lexical" ? null : this.#embedder.model,
           query,
-          results: []
+          results: [],
+          sourceFilter: sourceFilter.data
         },
         ok: true
       });
     }
     const database = await openDatabase(this.#databasePath);
     try {
-      const chunks = loadChunks(database);
-      const quotes = loadActiveQuotes(database);
+      const chunks = sourceFilter.data === "quotes" ? [] : loadChunks(database);
+      const quotes = sourceFilter.data === "history" ? [] : loadActiveQuotes(database);
       const usesSemantic = mode.data !== "lexical";
       if (usesSemantic && (chunks.some((chunk) => chunk.embedding === null) || quotes.some((quote) => quote.embedding === null))) {
         throw new KnowledgeCliError(
@@ -2182,13 +2409,13 @@ var KnowledgeCli = class {
         command: "knowledge.search",
         data: {
           mode: mode.data,
-          model: usesSemantic ? this.#embedder.model : null,
           query,
           results: mergeSearchResults(
             fusedResults(chunks, mode.data, lexical, semantic, limitInput),
             fusedQuoteResults(quotes, mode.data, quoteLexical, quoteSemantic, limitInput),
             limitInput
-          )
+          ),
+          sourceFilter: sourceFilter.data
         },
         ok: true
       });
@@ -2196,6 +2423,127 @@ var KnowledgeCli = class {
       database.close();
     }
   }
+  async adopt(projectId, knowledgeRef) {
+    const payload = decodeKnowledgeRef(knowledgeRef);
+    if (!await databaseExists(this.#databasePath)) {
+      throw new KnowledgeCliError(
+        "DXC_KNOWLEDGE_REFERENCE_STALE",
+        "\u77E5\u8BC6\u5F15\u7528\u5BF9\u5E94\u7684\u672C\u5730\u7D22\u5F15\u4E0D\u5B58\u5728\u3002",
+        void 0,
+        { recovery: "\u8BF7\u91CD\u65B0\u5BFC\u5165\u6216\u68C0\u7D22\u5185\u5BB9\uFF0C\u518D\u91C7\u7528\u65B0\u7684\u7ED3\u679C\u3002" }
+      );
+    }
+    const database = await openDatabase(this.#databasePath);
+    let adopted;
+    let quoteVerbatimGuard;
+    try {
+      if (payload.sourceType === "history-article") {
+        const chunk = loadChunks(database).find(
+          (candidate) => candidate.id === payload.chunkId && candidate.articleId === payload.articleId
+        );
+        if (chunk === void 0 || chunk.chunkSha256 !== payload.contentSha256) {
+          throw new KnowledgeCliError(
+            "DXC_KNOWLEDGE_REFERENCE_STALE",
+            "\u5386\u53F2\u6587\u7AE0\u7247\u6BB5\u5DF2\u53D8\u5316\u3002",
+            void 0,
+            { recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5E76\u8BA9\u7528\u6237\u91CD\u65B0\u9009\u62E9\u5F53\u524D\u7247\u6BB5\u3002" }
+          );
+        }
+        adopted = contentWorkflowAdoptedKnowledgeSchema.parse({
+          heading: chunk.heading,
+          knowledgeRef,
+          label: chunk.title,
+          snippet: snippet(chunk.body),
+          sourceType: "history-article"
+        });
+      } else {
+        const quote = loadActiveQuotes(database).find(
+          (candidate) => candidate.id === payload.quoteId
+        );
+        if (quote === void 0 || quote.contentSha256 !== payload.contentSha256) {
+          throw new KnowledgeCliError(
+            "DXC_KNOWLEDGE_REFERENCE_STALE",
+            "\u91D1\u53E5\u5DF2\u53D8\u5316\u6216\u5DF2\u5F52\u6863\u3002",
+            void 0,
+            { recovery: "\u8BF7\u91CD\u65B0\u68C0\u7D22\u5E76\u8BA9\u7528\u6237\u91CD\u65B0\u9009\u62E9\u5F53\u524D\u91D1\u53E5\u3002" }
+          );
+        }
+        if (quote.verbatimUse === "do-not-use-verbatim") {
+          throw new KnowledgeCliError(
+            "DXC_KNOWLEDGE_REFERENCE_INVALID",
+            "\u8BE5\u91D1\u53E5\u7981\u6B62\u91C7\u7528\u5230\u6587\u7AE0\u9879\u76EE\u3002",
+            void 0,
+            { recovery: "\u8BF7\u4FDD\u7559\u5B83\u4EC5\u4F9B\u4EBA\u5DE5\u67E5\u770B\uFF0C\u6216\u91CD\u65B0\u68C0\u7D22\u5E76\u9009\u62E9\u5141\u8BB8\u91C7\u7528\u7684\u5176\u4ED6\u91D1\u53E5\u3002" }
+          );
+        }
+        adopted = contentWorkflowAdoptedKnowledgeSchema.parse({
+          attribution: quote.attribution,
+          knowledgeRef,
+          label: quote.attribution ?? quote.sourceLabel ?? "\u5DF2\u91C7\u7528\u91D1\u53E5",
+          snippet: snippet(quote.text),
+          sourceType: "quote",
+          verbatimUse: quote.verbatimUse
+        });
+        if (quote.verbatimUse === "needs-verification") {
+          quoteVerbatimGuard = quote.text;
+        }
+      }
+    } finally {
+      database.close();
+    }
+    const project = await new ProjectCli({
+      currentDirectory: this.#currentDirectory,
+      homeDirectory: this.#homeDirectory,
+      now: this.#now
+    }).locateByProjectId(projectId);
+    const target = path2.join(project.directory, PROJECT_CONTEXT_FILE);
+    return withPrivateFileLocks([target], async () => {
+      let store = {
+        adoptedKnowledge: [],
+        quoteVerbatimGuards: [],
+        schemaVersion: "1"
+      };
+      try {
+        store = projectContextStoreSchema.parse(
+          JSON.parse(await readPrivateFile(target, PROJECT_CONTEXT_MAXIMUM_BYTES))
+        );
+      } catch (error) {
+        if (!(error instanceof LocalStateError && error.failure === "missing")) {
+          throw error;
+        }
+      }
+      const adoptedKnowledge = [
+        ...store.adoptedKnowledge.filter(
+          (item) => !sameKnowledgeEntity(item.knowledgeRef, payload)
+        ),
+        adopted
+      ].slice(-20);
+      const quoteVerbatimGuards = [
+        ...store.quoteVerbatimGuards.filter(
+          (item) => !sameKnowledgeEntity(item.knowledgeRef, payload)
+        ),
+        ...quoteVerbatimGuard === void 0 ? [] : [{ knowledgeRef, text: quoteVerbatimGuard }]
+      ].slice(-20);
+      await writePrivateJson(target, {
+        adoptedKnowledge,
+        quoteVerbatimGuards,
+        schemaVersion: "1"
+      });
+      return contentKnowledgeAdoptResultSchema.parse({
+        command: "knowledge.adopt",
+        data: { adopted, projectId: project.manifest.projectId },
+        ok: true
+      });
+    }).catch((error) => {
+      if (error instanceof LocalStateError && error.failure === "busy") {
+        throw new KnowledgeCliError("DXC_KNOWLEDGE_BUSY", "\u9879\u76EE\u77E5\u8BC6\u4E0A\u4E0B\u6587\u6B63\u5728\u66F4\u65B0\u3002", void 0, {
+          recovery: "\u8BF7\u7B49\u5F85\u5F53\u524D\u91C7\u7528\u52A8\u4F5C\u5B8C\u6210\u540E\u91CD\u8BD5\u540C\u4E00 knowledgeRef\u3002",
+          retryable: true
+        });
+      }
+      throw error;
+    });
+  }
   async status() {
     let articleCount = 0;
     let chunkCount = 0;
@@ -2203,9 +2551,7 @@ var KnowledgeCli = class {
     let quoteSummary = {
       activeCount: 0,
       archivedCount: 0,
-      sourceInitialized: await quoteSourceExists(quoteSourcePath(this.#homeDirectory)),
-      sourcePath: QUOTE_SOURCE_DISPLAY_PATH,
-      sourceSha256: null
+      sourceInitialized: await quoteSourceExists(quoteSourcePath(this.#homeDirectory))
     };
     if (await databaseExists(this.#databasePath)) {
       const database = await openDatabase(this.#databasePath);
@@ -2251,13 +2597,6 @@ var KnowledgeCli = class {
       data: {
         articleCount,
         chunkCount,
-        databasePath: DATABASE_DISPLAY_PATH,
-        model: contentKnowledgeModelSchema.parse({
-          dimensions: CONTENT_KNOWLEDGE_EMBEDDING_DIMENSIONS,
-          id: CONTENT_KNOWLEDGE_EMBEDDING_MODEL,
-          quantization: CONTENT_KNOWLEDGE_EMBEDDING_QUANTIZATION,
-          revision: CONTENT_KNOWLEDGE_EMBEDDING_REVISION
-        }),
         modelCached: await this.#isModelCached(),
         semanticIndexedChunkCount,
         quotes: quoteSummary