@jangts/agent-core 0.1.1 → 0.2.0

package/development/docs/api/support.md

@@ -167,6 +167,33 @@ modelInteractionCatalog 按明确登记的交互 ID 选择原生函数或 JSON a
 
 兼容 Provider 的 `requestBody` 用于供应商扩展字段。模型身份、输入消息、流式协议和 token 上限由适配器与 Core 调用合同控制。覆盖这些字段会在发送请求前报错。需要使用另一种请求协议时，可以直接实现同一个 `ChatProvider` 接口。
 
+完成判定通过 `ports.completionPolicy` 选择，缺省为 `Support.completionPolicyCatalog.default`，是否接受函数分片、期望的 `finish_reason`、`[DONE]` 前的完整性都按调用是否声明 `functions` 判定，缺结束标记的断流仍按 `MODEL_INCOMPLETE` 结束。`Support.completionPolicyCatalog.session` 按线上 `tool_choice` 判定：`auto` 要求已开始的调用全部完整并允许伴随正文，`required` 与指定函数对象要求至少一个完整调用，`none` 拒绝任何调用分片，字段省略采用 default 的完成规则，未知值在发请求前按配置错误拒绝。策略只判定响应是否满足请求，不接管请求循环、传输保护或工具执行；取消与传输失败不会因为策略而变成成功。
+
+`Support.createToolCallCollector` 按 index 聚合调用分片，完成策略与直接调用方共用同一实现。分片 ID 冲突、跨 index 重复 ID 与残缺调用都按协议错误拒绝，一个完整调用不会掩盖另一个残缺调用。
+
+协议层从不限制接收多个调用分片，`parallel_tool_calls` 只是发送字段，不表达执行授权或调度策略。Agent 路径的单提案限制由 `nativeFunctionInteraction` 的 collector 决定；直接使用 Provider 不受该限制，也不因此获得工具执行、授权或循环能力。
+
+`ProviderMessage` 提供直连所需的 `tool` 结果与 assistant `toolCalls` 形状，`chatCompletionMessages` 显式映射为 `tool_call_id` 与嵌套 `tool_calls`；角色与字段不匹配、调用字段不完整时按 `TypeError` 拒绝。只发送声明字段，额外字段（包括原始 wire 字段）不透传；`toolCallId` 必须是非空字符串，`role` 与 `content` 按消息合同校验。Core `ModelMessage` 与 `ChatProvider` 抽象签名不变。
+
+直连工具线程使用声明字段，assistant 的 `content` 可以为空字符串；工具结果通过同一个调用 ID 关联：
+
+```ts
+import { Support } from '@jangts/agent-core';
+
+const messages: Support.ProviderMessage[] = [
+  { role: 'user', content: '查询资料' },
+  {
+    role: 'assistant', content: '',
+    toolCalls: [{ id: 'call-1', name: 'lookup', arguments: '{"query":"资料"}' }],
+  },
+  { role: 'tool', content: '{"found":true}', toolCallId: 'call-1' },
+];
+const wireMessages = Support.chatCompletionMessages(messages);
+// 工具声明映射为 tool_calls，工具结果映射为 tool_call_id。
+```
+
+工具的注册、参数业务校验、授权和执行由宿主负责。`createToolCallCollector.complete()` 检查调用 ID 与名称的完整性，不解析或验证业务参数 JSON。
+
 多个请求复用同一个 Provider 时，可以用 `Support.createProviderObservationScope` 绑定应用自己的输出规则。将返回的 `observer` 配给 Provider，每次请求用 `attach(diagnostics, destination)` 关联日志目标。子作用域会自动继承关联。应用负责脱敏、保留期和写入策略，Provider 事件按现有应用日志出口记录。
 
 ## 拒绝检查

package/development/skills/agent-core-app/scripts/create-app.mjs

@@ -1,149 +1,346 @@
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import {
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  rmdir,
+  writeFile,
+} from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveSdkResources } from './resources.mjs';
 
-const execute = promisify(execFile), receiptName = 'agent-core.template.json';
-const usage = 'node create-app.mjs TARGET [--name PACKAGE_NAME] [--purpose TEXT] [--template node-ts] [--sdk-from PROJECT] [--source UTF8_FILE --id DOCUMENT_ID] [--write | --check]';
-const hash = value => createHash('sha256').update(value).digest('hex');
-const pathInside = value => typeof value === 'string' && !!value && !isAbsolute(value) && !value.includes('\\')
-  && value.split('/').every(part => !!part && !['.', '..'].includes(part));
-async function exists(path) { try { return await lstat(path); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+const execute = promisify(execFile),
+  receiptName = 'agent-core.template.json';
+const usage =
+  'node create-app.mjs TARGET [--name PACKAGE_NAME] [--purpose TEXT] [--template node-ts] [--sdk-from PROJECT] [--source UTF8_FILE --id DOCUMENT_ID] [--write | --check]';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const pathInside = (value) =>
+  typeof value === 'string' &&
+  !!value &&
+  !isAbsolute(value) &&
+  !value.includes('\\') &&
+  value.split('/').every((part) => !!part && !['.', '..'].includes(part));
+async function exists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
 function inputs(name, purpose) {
-  if (typeof name !== 'string' || name.length > 214 || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)) throw new TypeError('Use a lowercase npm package name');
-  if (typeof purpose !== 'string' || purpose.length > 800 || !purpose.trim()) throw new TypeError('Use a purpose of 1–800 characters');
+  if (
+    typeof name !== 'string' ||
+    name.length > 214 ||
+    !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name)
+  )
+    throw new TypeError('Use a lowercase npm package name');
+  if (typeof purpose !== 'string' || purpose.length > 800 || !purpose.trim())
+    throw new TypeError('Use a purpose of 1–800 characters');
   return { name, purpose: purpose.trim() };
 }
 function parse(args, cwd) {
   if (!args.length || args[0].startsWith('--')) throw new TypeError(usage);
-  const values = {}, switches = new Set(['--write', '--check']), options = new Set(['--name', '--purpose', '--template', '--sdk-from', '--source', '--id']);
+  const values = {},
+    switches = new Set(['--write', '--check']),
+    options = new Set(['--name', '--purpose', '--template', '--sdk-from', '--source', '--id']);
   for (let index = 1; index < args.length; index++) {
     const key = args[index];
     if (Object.hasOwn(values, key)) throw new TypeError(`Duplicate option: ${key}`);
     if (switches.has(key)) values[key] = true;
-    else if (options.has(key) && args[index + 1] !== undefined && !args[index + 1].startsWith('--')) values[key] = args[++index];
+    else if (options.has(key) && args[index + 1] !== undefined && !args[index + 1].startsWith('--'))
+      values[key] = args[++index];
     else throw new TypeError(usage);
   }
-  if (values['--write'] && values['--check'] || !!values['--source'] !== !!values['--id']
-    || values['--check'] && ['--name', '--purpose', '--source', '--id'].some(key => Object.hasOwn(values, key))) throw new TypeError(usage);
+  if (
+    (values['--write'] && values['--check']) ||
+    !!values['--source'] !== !!values['--id'] ||
+    (values['--check'] &&
+      ['--name', '--purpose', '--source', '--id'].some((key) => Object.hasOwn(values, key)))
+  )
+    throw new TypeError(usage);
   return { target: resolve(cwd, args[0]), values };
 }
 async function emptyTarget(target) {
   const item = await exists(target);
-  if (item && (!item.isDirectory() || item.isSymbolicLink() || (await readdir(target)).length)) throw new Error('TARGET must be absent or an empty real directory; existing files are preserved');
+  if (item && (!item.isDirectory() || item.isSymbolicLink() || (await readdir(target)).length))
+    throw new Error(
+      'TARGET must be absent or an empty real directory; existing files are preserved',
+    );
 }
 async function templateResources(resources, id) {
   const root = join(resources.sdk.root, 'development/skills/agent-core-app');
   const catalog = JSON.parse(await readFile(join(root, 'templates/catalog.json'), 'utf8'));
-  if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.templates)) throw new Error('Unsupported template catalog');
-  const template = catalog.templates.find(item => item.id === id);
-  if (!template || typeof template.revision !== 'string' || !pathInside(template.directory) || !Array.isArray(template.files)
-    || template.files.some(file => !pathInside(file.source) || !pathInside(file.target) || !['template', 'skill'].includes(file.origin))
-    || new Set(template.files.map(file => file.target)).size !== template.files.length || template.files.some(file => file.target === receiptName)) throw new Error('Invalid or unknown template');
+  if (catalog.schemaVersion !== 1 || !Array.isArray(catalog.templates))
+    throw new Error('Unsupported template catalog');
+  const template = catalog.templates.find((item) => item.id === id);
+  if (
+    !template ||
+    typeof template.revision !== 'string' ||
+    !pathInside(template.directory) ||
+    !Array.isArray(template.files) ||
+    template.files.some(
+      (file) =>
+        !pathInside(file.source) ||
+        !pathInside(file.target) ||
+        !['template', 'skill'].includes(file.origin),
+    ) ||
+    new Set(template.files.map((file) => file.target)).size !== template.files.length ||
+    template.files.some((file) => file.target === receiptName)
+  )
+    throw new Error('Invalid or unknown template');
   return { root, template };
 }
 async function render(resources, definition, input) {
   const manifest = JSON.parse(await readFile(join(resources.sdk.root, 'package.json'), 'utf8'));
-  if (manifest.name !== '@jangts/agent-core' || manifest.version !== resources.sdk.version || typeof manifest.devDependencies?.typescript !== 'string') throw new Error('SDK manifest does not describe the selected template dependencies');
-  const configuration = { name: input.name, purpose: input.purpose, maxCalls: 4, maxRounds: 8,
-    callTimeoutMs: 30000, maxInputChars: 48000, maxOutputChars: 8000 };
-  const substitutions = { '__APP_CONFIG__': JSON.stringify(configuration, null, 2), '__PACKAGE_NAME__': JSON.stringify(input.name),
-    '__SDK_VERSION__': JSON.stringify(manifest.version), '__TYPESCRIPT_VERSION__': JSON.stringify(manifest.devDependencies.typescript) };
-  return Promise.all(definition.template.files.map(async file => {
-    const source = file.origin === 'skill' ? join(definition.root, file.source) : join(definition.root, 'templates', definition.template.directory, file.source);
-    const info = await lstat(source); if (!info.isFile() || info.isSymbolicLink()) throw new Error('Template assets must be regular files');
-    let content = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(source));
-    // One pass: user-provided purpose text cannot become another substitution instruction.
-    if (file.origin === 'template') content = content.replace(/__APP_CONFIG__|__PACKAGE_NAME__|__SDK_VERSION__|__TYPESCRIPT_VERSION__/g, token => substitutions[token]);
-    const bytes = Buffer.from(content); return { path: file.target, bytes, sha256: hash(bytes) };
-  }));
+  if (
+    manifest.name !== '@jangts/agent-core' ||
+    manifest.version !== resources.sdk.version ||
+    typeof manifest.devDependencies?.typescript !== 'string'
+  )
+    throw new Error('SDK manifest does not describe the selected template dependencies');
+  const configuration = {
+    name: input.name,
+    purpose: input.purpose,
+    maxCalls: 4,
+    maxRounds: 8,
+    callTimeoutMs: 30000,
+    maxInputChars: 48000,
+    maxOutputChars: 8000,
+  };
+  const substitutions = {
+    __APP_CONFIG__: JSON.stringify(configuration, null, 2),
+    __PACKAGE_NAME__: JSON.stringify(input.name),
+    __SDK_VERSION__: JSON.stringify(manifest.version),
+    __TYPESCRIPT_VERSION__: JSON.stringify(manifest.devDependencies.typescript),
+  };
+  return Promise.all(
+    definition.template.files.map(async (file) => {
+      const source =
+        file.origin === 'skill'
+          ? join(definition.root, file.source)
+          : join(definition.root, 'templates', definition.template.directory, file.source);
+      const info = await lstat(source);
+      if (!info.isFile() || info.isSymbolicLink())
+        throw new Error('Template assets must be regular files');
+      let content = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(source));
+      // One pass: user-provided purpose text cannot become another substitution instruction.
+      if (file.origin === 'template')
+        content = content.replace(
+          /__APP_CONFIG__|__PACKAGE_NAME__|__SDK_VERSION__|__TYPESCRIPT_VERSION__/g,
+          (token) => substitutions[token],
+        );
+      const bytes = Buffer.from(content);
+      return { path: file.target, bytes, sha256: hash(bytes) };
+    }),
+  );
 }
 async function compare(target, resources, definition) {
   const directory = await lstat(target);
-  if (!directory.isDirectory() || directory.isSymbolicLink()) throw new Error('TARGET must be a real directory');
-  const receiptPath = join(target, receiptName), info = await lstat(receiptPath);
-  if (!info.isFile() || info.isSymbolicLink()) throw new Error('Template receipt must be a regular file');
+  if (!directory.isDirectory() || directory.isSymbolicLink())
+    throw new Error('TARGET must be a real directory');
+  const receiptPath = join(target, receiptName),
+    info = await lstat(receiptPath);
+  if (!info.isFile() || info.isSymbolicLink())
+    throw new Error('Template receipt must be a regular file');
   const receipt = JSON.parse(await readFile(receiptPath, 'utf8'));
-  if (receipt.schemaVersion !== 1 || receipt.template?.id !== definition.template.id || !Array.isArray(receipt.files)
-    || receipt.files.some(file => !pathInside(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256))
-    || new Set(receipt.files.map(file => file.path)).size !== receipt.files.length) throw new Error('Invalid template receipt');
-  const files = await render(resources, definition, inputs(receipt.inputs?.name, receipt.inputs?.purpose));
-  const baseline = new Map(receipt.files.map(file => [file.path, file.sha256])), currentTemplate = new Map(files.map(file => [file.path, file.sha256]));
+  if (
+    receipt.schemaVersion !== 1 ||
+    receipt.template?.id !== definition.template.id ||
+    !Array.isArray(receipt.files) ||
+    receipt.files.some((file) => !pathInside(file.path) || !/^[a-f0-9]{64}$/.test(file.sha256)) ||
+    new Set(receipt.files.map((file) => file.path)).size !== receipt.files.length
+  )
+    throw new Error('Invalid template receipt');
+  const files = await render(
+    resources,
+    definition,
+    inputs(receipt.inputs?.name, receipt.inputs?.purpose),
+  );
+  const baseline = new Map(receipt.files.map((file) => [file.path, file.sha256])),
+    currentTemplate = new Map(files.map((file) => [file.path, file.sha256]));
   const changes = [];
   for (const path of [...new Set([...baseline.keys(), ...currentTemplate.keys()])].sort()) {
-    if (!currentTemplate.has(path)) { changes.push({ path, state: 'not-in-current-template', baselineSha256: baseline.get(path), templateChanged: true }); continue; }
+    if (!currentTemplate.has(path)) {
+      changes.push({
+        path,
+        state: 'not-in-current-template',
+        baselineSha256: baseline.get(path),
+        templateChanged: true,
+      });
+      continue;
+    }
     // Reject symlinks at every managed path component, without reading their destinations.
     let blocked = false;
     for (let index = 1; index <= path.split('/').length; index++) {
       const part = await exists(join(target, ...path.split('/').slice(0, index)));
-      if (part?.isSymbolicLink()) { blocked = true; break; }
+      if (part?.isSymbolicLink()) {
+        blocked = true;
+        break;
+      }
     }
     const item = blocked ? undefined : await exists(join(target, path));
     const actual = item?.isFile() ? hash(await readFile(join(target, path))) : undefined;
-    changes.push({ path, state: blocked ? 'symlink' : actual === undefined ? 'missing' : actual === baseline.get(path) ? 'unchanged' : 'modified',
-      baselineSha256: baseline.get(path), currentSha256: actual, templateSha256: currentTemplate.get(path), templateChanged: currentTemplate.get(path) !== baseline.get(path) });
+    changes.push({
+      path,
+      state: blocked
+        ? 'symlink'
+        : actual === undefined
+          ? 'missing'
+          : actual === baseline.get(path)
+            ? 'unchanged'
+            : 'modified',
+      baselineSha256: baseline.get(path),
+      currentSha256: actual,
+      templateSha256: currentTemplate.get(path),
+      templateChanged: currentTemplate.get(path) !== baseline.get(path),
+    });
   }
-  return { status: 'checked', target, installed: { template: receipt.template, sdk: receipt.sdk }, available: { template: { id: definition.template.id, revision: definition.template.revision }, sdk: { name: manifestName, version: resources.sdk.version } }, files: changes, changedFiles: [] };
+  return {
+    status: 'checked',
+    target,
+    installed: { template: receipt.template, sdk: receipt.sdk },
+    available: {
+      template: { id: definition.template.id, revision: definition.template.revision },
+      sdk: { name: manifestName, version: resources.sdk.version },
+    },
+    files: changes,
+    changedFiles: [],
+  };
 }
 const manifestName = '@jangts/agent-core';
 export async function createApplication(args, cwd = process.cwd()) {
   const { target, values } = parse(args, cwd);
-  if (basename(target) === '.local') throw new TypeError('Choose an application directory outside the temporary .local directory itself');
+  if (basename(target) === '.local')
+    throw new TypeError(
+      'Choose an application directory outside the temporary .local directory itself',
+    );
   const resources = await resolveSdkResources(resolve(cwd, values['--sdk-from'] ?? '.'));
   const definition = await templateResources(resources, values['--template'] ?? 'node-ts');
   if (values['--check']) return compare(target, resources, definition);
   await emptyTarget(target);
-  const defaultName = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '') || 'agent-app';
-  const input = inputs(values['--name'] ?? defaultName, values['--purpose'] ?? '依据当前问题和获准读取的资料提供帮助。');
+  const defaultName =
+    basename(target)
+      .toLowerCase()
+      .replace(/[^a-z0-9._-]+/g, '-')
+      .replace(/^[._-]+|[._-]+$/g, '') || 'agent-app';
+  const input = inputs(
+    values['--name'] ?? defaultName,
+    values['--purpose'] ?? '依据当前问题和获准读取的资料提供帮助。',
+  );
   const files = await render(resources, definition, input);
   let source;
   if (values['--source']) {
     const path = resolve(cwd, values['--source']);
-    const info = await lstat(path); if (!info.isFile() || info.isSymbolicLink() || info.size > 32000) throw new TypeError('Source must be a regular UTF-8 file within 32000 bytes');
-    const library = await import(pathToFileURL(join(dirname(resources.knowledgeLoader), 'source.mjs')));
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 32000)
+      throw new TypeError('Source must be a regular UTF-8 file within 32000 bytes');
+    const library = await import(
+      pathToFileURL(join(dirname(resources.knowledgeLoader), 'source.mjs'))
+    );
     source = await library.readSuppliedSource(path, values['--id'], 32000);
     const knowledge = await import(pathToFileURL(resources.knowledgeLoader));
-    const policy = JSON.parse(files.find(file => file.path === 'knowledge/knowledge.config.json').bytes.toString('utf8'));
+    const policy = JSON.parse(
+      files.find((file) => file.path === 'knowledge/knowledge.config.json').bytes.toString('utf8'),
+    );
     knowledge.compileApplicationKnowledge([source.document], policy);
   }
-  const receipt = { schemaVersion: 1, template: { id: definition.template.id, revision: definition.template.revision },
-    sdk: { name: manifestName, version: resources.sdk.version }, inputs: input,
-    files: files.map(({ path, sha256 }) => ({ path, sha256 })) };
-  const plan = { status: 'planned', target, ...receipt, files: [...receipt.files, { path: receiptName }],
-    source: source ? { documentId: values['--id'], originalName: source.name, sha256: source.digest, status: 'candidate-only' } : null,
-    changedFiles: [], installedDependencies: false, modelCalled: false, published: false };
+  const receipt = {
+    schemaVersion: 1,
+    template: { id: definition.template.id, revision: definition.template.revision },
+    sdk: { name: manifestName, version: resources.sdk.version },
+    inputs: input,
+    files: files.map(({ path, sha256 }) => ({ path, sha256 })),
+  };
+  const plan = {
+    status: 'planned',
+    target,
+    ...receipt,
+    files: [...receipt.files, { path: receiptName }],
+    source: source
+      ? {
+          documentId: values['--id'],
+          originalName: source.name,
+          sha256: source.digest,
+          status: 'candidate-only',
+        }
+      : null,
+    changedFiles: [],
+    installedDependencies: false,
+    modelCalled: false,
+    published: false,
+  };
   if (!values['--write']) return plan;
-  const parent = dirname(target), temporary = join(parent, '.local');
+  const parent = dirname(target),
+    temporary = join(parent, '.local');
   await mkdir(parent, { recursive: true });
-  let madeTemporary = false, staging;
+  let madeTemporary = false,
+    staging;
   try {
-    try { await mkdir(temporary); madeTemporary = true; } catch (error) { if (error.code !== 'EEXIST') throw error; }
-    const info = await lstat(temporary); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error('Temporary directory must be a real directory');
+    try {
+      await mkdir(temporary);
+      madeTemporary = true;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    const info = await lstat(temporary);
+    if (!info.isDirectory() || info.isSymbolicLink())
+      throw new Error('Temporary directory must be a real directory');
     staging = await mkdtemp(join(temporary, 'agent-core-create-'));
-    for (const file of files) { await mkdir(dirname(join(staging, file.path)), { recursive: true }); await writeFile(join(staging, file.path), file.bytes, { flag: 'wx' }); }
+    for (const file of files) {
+      await mkdir(dirname(join(staging, file.path)), { recursive: true });
+      await writeFile(join(staging, file.path), file.bytes, { flag: 'wx' });
+    }
     let candidate;
     if (source) {
       const snapshot = join(staging, '.local/initial-source', source.name);
-      await mkdir(dirname(snapshot), { recursive: true }); await writeFile(snapshot, source.bytes, { flag: 'wx' });
-      const output = await execute(process.execPath, [resources.tools['prepare-source'], join(staging, 'knowledge'), '--source', snapshot, '--id', values['--id']]);
+      await mkdir(dirname(snapshot), { recursive: true });
+      await writeFile(snapshot, source.bytes, { flag: 'wx' });
+      const output = await execute(process.execPath, [
+        resources.tools['prepare-source'],
+        join(staging, 'knowledge'),
+        '--source',
+        snapshot,
+        '--id',
+        values['--id'],
+      ]);
       candidate = relative(staging, JSON.parse(output.stdout).candidate);
-      if (!pathInside(candidate.split(sep).join('/'))) throw new Error('Candidate escaped the generated project');
+      if (!pathInside(candidate.split(sep).join('/')))
+        throw new Error('Candidate escaped the generated project');
       await rm(join(staging, '.local/initial-source'), { recursive: true });
       await rmdir(join(staging, '.local'));
     }
-    await writeFile(join(staging, receiptName), JSON.stringify({ ...receipt, createdAtMs: Date.now() }, null, 2) + '\n', { flag: 'wx' });
+    await writeFile(
+      join(staging, receiptName),
+      JSON.stringify({ ...receipt, createdAtMs: Date.now() }, null, 2) + '\n',
+      { flag: 'wx' },
+    );
     // Recheck before the atomic directory rename; a concurrent writer's non-empty target is preserved.
-    await emptyTarget(target); await rename(staging, target); staging = undefined;
-    return { ...plan, status: 'created', changedFiles: [...files.map(file => file.path), receiptName], ...(candidate ? { candidate: join(target, candidate) } : {}) };
+    await emptyTarget(target);
+    await rename(staging, target);
+    staging = undefined;
+    return {
+      ...plan,
+      status: 'created',
+      changedFiles: [...files.map((file) => file.path), receiptName],
+      ...(candidate ? { candidate: join(target, candidate) } : {}),
+    };
   } finally {
     if (staging) await rm(staging, { recursive: true });
     if (madeTemporary) await rmdir(temporary).catch(() => {});
   }
 }
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  try { console.log(JSON.stringify(await createApplication(process.argv.slice(2)), null, 2)); }
-  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+  try {
+    console.log(JSON.stringify(await createApplication(process.argv.slice(2)), null, 2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
 }

package/development/skills/agent-core-app/scripts/lib/knowledge.mjs

@@ -4,8 +4,14 @@ import { Knowledge } from '@jangts/agent-core/kits/knowledge';
 
 // This is App-owned configuration and loading code, not a Core file-store API.
 export function compileApplicationKnowledge(documents, policy) {
-  if (!policy || policy.schemaVersion !== 1 || !Number.isSafeInteger(policy.maxReadChars) || policy.maxReadChars < 1
-    || !Array.isArray(policy.requiredReads)) throw new TypeError('Invalid application knowledge policy');
+  if (
+    !policy ||
+    policy.schemaVersion !== 1 ||
+    !Number.isSafeInteger(policy.maxReadChars) ||
+    policy.maxReadChars < 1 ||
+    !Array.isArray(policy.requiredReads)
+  )
+    throw new TypeError('Invalid application knowledge policy');
   const catalog = Knowledge.defineKnowledgeCatalog(documents, { maxChars: policy.maxReadChars });
   // Required task reads must fit their runtime content budget as well as resolve.
   for (const read of policy.requiredReads) catalog.read(read);
@@ -17,19 +23,38 @@ export async function readApplicationKnowledge(directory = new URL('./', import.
   const configBytes = await readFile(new URL('knowledge.config.json', directory));
   const baseConfigSha256 = createHash('sha256').update(configBytes).digest('hex');
   const policy = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(configBytes));
-  if (!Array.isArray(policy.documents) || !Number.isSafeInteger(policy.maxDocumentBytes)
-    || policy.maxDocumentBytes < 1) throw new TypeError('Invalid application document catalog');
-  const documents = await Promise.all(policy.documents.map(async entry => {
-    // The allowlist is App-maintained. Neither a model nor a request supplies this filesystem path.
-    if (!entry || typeof entry.id !== 'string' || typeof entry.file !== 'string'
-      || !/^[a-z0-9][a-z0-9.-]*\.knowledge\.md$/.test(entry.file)
-      || (entry.locale !== undefined && typeof entry.locale !== 'string')) throw new TypeError('Invalid application document entry');
-    const bytes = await readFile(new URL(entry.file, directory));
-    if (bytes.length > policy.maxDocumentBytes) throw new RangeError('Source document exceeds the App limit');
-    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-    const revision = createHash('sha256').update(JSON.stringify([entry.id, entry.locale, text])).digest('hex');
-    return Knowledge.parseKnowledgeDocument({ id: entry.id, revision, locale: entry.locale, text });
-  }));
+  if (
+    !Array.isArray(policy.documents) ||
+    !Number.isSafeInteger(policy.maxDocumentBytes) ||
+    policy.maxDocumentBytes < 1
+  )
+    throw new TypeError('Invalid application document catalog');
+  const documents = await Promise.all(
+    policy.documents.map(async (entry) => {
+      // The allowlist is App-maintained. Neither a model nor a request supplies this filesystem path.
+      if (
+        !entry ||
+        typeof entry.id !== 'string' ||
+        typeof entry.file !== 'string' ||
+        !/^[a-z0-9][a-z0-9.-]*\.knowledge\.md$/.test(entry.file) ||
+        (entry.locale !== undefined && typeof entry.locale !== 'string')
+      )
+        throw new TypeError('Invalid application document entry');
+      const bytes = await readFile(new URL(entry.file, directory));
+      if (bytes.length > policy.maxDocumentBytes)
+        throw new RangeError('Source document exceeds the App limit');
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+      const revision = createHash('sha256')
+        .update(JSON.stringify([entry.id, entry.locale, text]))
+        .digest('hex');
+      return Knowledge.parseKnowledgeDocument({
+        id: entry.id,
+        revision,
+        locale: entry.locale,
+        text,
+      });
+    }),
+  );
   return { documents, policy, baseConfigSha256 };
 }
 

package/development/skills/agent-core-app/scripts/lib/source.mjs

@@ -1,16 +1,44 @@
+/*
+ * Reader for a knowledge source file supplied by the operator.
+ *
+ * The file belongs to the App's development skills (开发技能). It turns one UTF-8 source
+ * file into a parsed knowledge document plus the hashes that identify it. The Knowledge
+ * Kit owns the document contract; this module only owns the file access, the byte budget
+ * and the identity derivation.
+ *
+ * Main exports: `readSuppliedSource`.
+ */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { Knowledge } from '@jangts/agent-core/kits/knowledge';
 
+/**
+ * Read and parse one supplied knowledge source file.
+ *
+ * @param file - Path of the UTF-8 source file.
+ * @param id - Stable document id; must be a lowercase slug of at most 64 characters.
+ * @param maxBytes - Maximum accepted file size in bytes.
+ * @param locale - Optional locale carried over from the document this one replaces.
+ * @returns The raw bytes, the parsed document, the original file name and the content hash.
+ * @throws TypeError For an invalid document id or a file that is not valid UTF-8.
+ * @throws RangeError When the file is empty or exceeds the byte budget.
+ * @throws Error When the decoded text is blank, or the anchors of the document are invalid.
+ */
 export async function readSuppliedSource(file, id, maxBytes = 32000, locale) {
+  // The id becomes part of the published document identity, so its shape is fixed.
   if (!/^[a-z][a-z0-9_.:-]{0,63}$/.test(id)) throw new TypeError('Choose a stable document ID');
   const bytes = await readFile(file);
-  if (!bytes.length || bytes.length > maxBytes) throw new RangeError('Source must contain text within the configured byte budget');
+  if (!bytes.length || bytes.length > maxBytes)
+    throw new RangeError('Source must contain text within the configured byte budget');
+  // `fatal` rejects malformed UTF-8 instead of replacing the invalid bytes.
   const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
   if (!text.trim()) throw new Error('Source has no content; use empty initialization instead');
+  // The content hash covers the raw bytes; the revision covers the parsed identity.
   const digest = createHash('sha256').update(bytes).digest('hex');
-  const revision = createHash('sha256').update(JSON.stringify([id, locale, text])).digest('hex');
+  const revision = createHash('sha256')
+    .update(JSON.stringify([id, locale, text]))
+    .digest('hex');
   const document = Knowledge.parseKnowledgeDocument({ id, revision, locale, text });
   return { bytes, document, name: basename(file), digest };
 }

package/development/skills/agent-core-app/scripts/plan.mjs

@@ -9,28 +9,53 @@ if (![1, 3].includes(args.length) || (args.length === 3 && args[1] !== '--source
   throw new Error('Usage: node plan.mjs PROJECT [--source UTF8_FILE]');
 const project = resolve(args[0]);
 let exists = true;
-try { if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory'); }
-catch (error) { if (error.code !== 'ENOENT') throw error; exists = false; }
+try {
+  if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory');
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error;
+  exists = false;
+}
 const { sdk, tools, docs, knowledgeLoader } = await resolveSdkResources(project);
 let documents = [];
 let knowledgeConfigured = false;
 let knowledgeStatus = 'unconfigured';
 let baseConfigSha256;
 if (exists) {
-  try { await stat(resolve(project, 'knowledge.config.json')); knowledgeConfigured = true; }
-  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try {
+    await stat(resolve(project, 'knowledge.config.json'));
+    knowledgeConfigured = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   if (knowledgeConfigured) {
-    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(pathToFileURL(knowledgeLoader));
+    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(
+      pathToFileURL(knowledgeLoader)
+    );
     const snapshot = await readApplicationKnowledge(pathToFileURL(project + sep));
     const catalog = compileApplicationKnowledge(snapshot.documents, snapshot.policy);
-    documents = snapshot.policy.documents.map(item => ({ id: item.id, file: item.file }));
+    documents = snapshot.policy.documents.map((item) => ({ id: item.id, file: item.file }));
     knowledgeStatus = catalog.ids().length ? 'valid' : 'empty-awaiting-source';
     baseConfigSha256 = snapshot.baseConfigSha256;
   }
 }
-console.log(JSON.stringify({ project, mode: exists ? 'integrate-or-maintain' : 'create-application', sdk,
-  knowledgeConfigured, knowledgeStatus, baseConfigSha256, suppliedSource: args[2] ? resolve(args[2]) : null,
-  factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
-  documents, tools, docs,
-  changedFiles: [], published: false,
-}, null, 2));
+console.log(
+  JSON.stringify(
+    {
+      project,
+      mode: exists ? 'integrate-or-maintain' : 'create-application',
+      sdk,
+      knowledgeConfigured,
+      knowledgeStatus,
+      baseConfigSha256,
+      suppliedSource: args[2] ? resolve(args[2]) : null,
+      factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
+      documents,
+      tools,
+      docs,
+      changedFiles: [],
+      published: false,
+    },
+    null,
+    2,
+  ),
+);