@fitlab-ai/agent-infra 0.5.5 → 0.5.7

package/lib/sandbox/commands/rm.js

@@ -11,7 +11,7 @@ import {
   sandboxLabel,
   worktreeDirCandidates
 } from '../constants.js';
-import { isVmManaged } from '../engine.js';
+import { detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.js';
 import { run, runOk, runSafe } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
@@ -165,13 +165,15 @@ async function rmAll(config, tools) {
     runSafe('docker', ['rmi', config.imageName]);
   }
 
-  if (isVmManaged()) {
+  const engine = detectEngine(config);
+  if (isManagedEngine(engine)) {
+    const name = engineDisplayName(engine);
     const shouldStopVm = await p.confirm({
-      message: 'Stop Colima VM?',
+      message: `Stop ${name} VM?`,
       initialValue: false
     });
     if (!p.isCancel(shouldStopVm) && shouldStopVm) {
-      runSafe('colima', ['stop']);
+      stopManagedVm(config);
     }
   }
 

package/lib/sandbox/commands/vm.js

@@ -3,31 +3,49 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.js';
 import { parsePositiveIntegerOption } from '../constants.js';
-import { detectEngine, ensureDocker, isVmManaged } from '../engine.js';
-import { run, runOk, runSafe } from '../shell.js';
+import {
+  ENGINES,
+  detectEngine,
+  engineDisplayName,
+  ensureDocker,
+  isManagedEngine,
+  stopManagedVm
+} from '../engine.js';
+import { runOk, runSafe } from '../shell.js';
 
 const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
 
-function ensureManagedVm() {
-  if (!isVmManaged()) {
-    throw new Error(`VM management is unavailable on ${detectEngine()}.`);
+function ensureManagedVm(engine) {
+  if (!isManagedEngine(engine)) {
+    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }
 }
 
 function status() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Sandbox VM status'));
 
-  if (runOk('colima', ['status'])) {
-    process.stdout.write(`${runSafe('colima', ['status'])}\n`);
-  } else {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA) {
+    if (runOk('colima', ['status'])) {
+      process.stdout.write(`${runSafe('colima', ['status'])}\n`);
+    } else {
+      p.log.warn('Colima VM is not running');
+    }
+    return;
+  }
+
+  if (!runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
   }
+
+  process.stdout.write(`${runSafe('orb', ['status'])}\n`);
 }
 
 async function start(args) {
-  ensureManagedVm();
-
   const { values } = parseArgs({
     args,
     allowPositionals: true,
@@ -45,6 +63,8 @@ async function start(args) {
   }
 
   const config = loadConfig();
+  const engine = detectEngine(config);
+  ensureManagedVm(engine);
   const effectiveConfig = {
     ...config,
     vm: {
@@ -62,15 +82,22 @@ async function start(args) {
 }
 
 function stop() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Stopping sandbox VM'));
 
-  if (!runOk('colima', ['status'])) {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA && !runOk('colima', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
+  }
+  if (engine === ENGINES.ORBSTACK && !runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
     return;
   }
 
-  run('colima', ['stop']);
+  stopManagedVm(config);
   p.outro(pc.green('VM stopped'));
 }
 

package/lib/sandbox/config.js

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { validateSandboxEngine } from './engine.js';
 
 const DEFAULTS = Object.freeze({
+  engine: null,
   runtimes: ['node20'],
   tools: ['claude-code', 'codex', 'opencode', 'gemini-cli'],
   dockerfile: null,
@@ -26,6 +28,7 @@ function detectRepoRoot() {
 
 function cloneDefaults() {
   return {
+    engine: DEFAULTS.engine,
     runtimes: [...DEFAULTS.runtimes],
     tools: [...DEFAULTS.tools],
     dockerfile: DEFAULTS.dockerfile,
@@ -49,6 +52,7 @@ export function loadConfig() {
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
+  const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine);
   const project = airc.project;
 
   if (!project || typeof project !== 'string') {
@@ -64,6 +68,7 @@ export function loadConfig() {
     containerPrefix: `${project}-dev`,
     imageName: `${project}-sandbox:latest`,
     worktreeBase: path.join(home, '.agent-infra', 'worktrees', project),
+    engine,
     runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
       ? [...sandbox.runtimes]
       : defaults.runtimes,

package/lib/sandbox/engine.js

@@ -2,26 +2,56 @@ import { platform } from 'node:os';
 import { detectHostResources } from './constants.js';
 import { run, runOk, runSafe, runVerbose } from './shell.js';
 
-export function detectEngine() {
-  const os = platform();
-  if (os === 'darwin') {
-    return 'colima';
+export const ENGINES = Object.freeze({
+  COLIMA: 'colima',
+  ORBSTACK: 'orbstack',
+  DOCKER_DESKTOP: 'docker-desktop'
+});
+
+const VALID_CONFIG_ENGINES = new Set(Object.values(ENGINES));
+
+export function validateSandboxEngine(engine) {
+  if (engine === null || engine === undefined) {
+    return null;
   }
+
+  if (VALID_CONFIG_ENGINES.has(engine)) {
+    return engine;
+  }
+
+  throw new Error(
+    `sandbox: invalid "sandbox.engine" value "${engine}". `
+    + 'Expected one of: null, colima, orbstack, docker-desktop. '
+    + 'This setting only affects macOS sandbox engine selection.'
+  );
+}
+
+export function detectEngine(config = {}, { platformFn = platform } = {}) {
+  const configured = validateSandboxEngine(config.engine);
+  const os = platformFn();
   if (os === 'linux') {
     return 'native';
   }
   if (os === 'win32') {
     return 'wsl2';
   }
+  if (os === 'darwin') {
+    if (configured) {
+      return configured;
+    }
+
+    return ENGINES.COLIMA;
+  }
   return 'unsupported';
 }
 
 function colimaArgs(config, runSafeFn = runSafe) {
   const arch = runSafeFn('uname', ['-m']);
   const defaults = detectHostResources();
-  const cpu = config.vm.cpu ?? defaults.cpu;
-  const memory = config.vm.memory ?? defaults.memory;
-  const disk = config.vm.disk ?? 60;
+  const vm = config.vm ?? {};
+  const cpu = vm.cpu ?? defaults.cpu;
+  const memory = vm.memory ?? defaults.memory;
+  const disk = vm.disk ?? 60;
   const args = ['start', '--cpu', String(cpu), '--memory', String(memory), '--disk', String(disk)];
 
   if (arch === 'arm64') {
@@ -53,14 +83,54 @@ export async function ensureColima(
   }
 }
 
+export async function ensureOrbStack(
+  _config,
+  onMessage,
+  { runOkFn = runOk, runVerboseFn = runVerbose } = {}
+) {
+  if (!runOkFn('which', ['orb'])) {
+    onMessage?.('Installing OrbStack via Homebrew...');
+    runVerboseFn('brew', ['install', '--cask', 'orbstack']);
+  }
+
+  if (!runOkFn('docker', ['info'])) {
+    onMessage?.('Starting OrbStack...');
+    runVerboseFn('orb', ['start']);
+  }
+
+  if (!runOkFn('docker', ['info'])) {
+    throw new Error('Docker daemon is not available after starting OrbStack');
+  }
+}
+
+export async function ensureDockerDesktop(
+  _config,
+  onMessage,
+  { runOkFn = runOk } = {}
+) {
+  if (!runOkFn('docker', ['info'])) {
+    throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
+  }
+}
+
 export async function ensureDocker(config, onMessage) {
-  const engine = detectEngine();
+  const engine = detectEngine(config);
 
-  if (engine === 'colima') {
+  if (engine === ENGINES.COLIMA) {
     await ensureColima(config, onMessage);
     return;
   }
 
+  if (engine === ENGINES.ORBSTACK) {
+    await ensureOrbStack(config, onMessage);
+    return;
+  }
+
+  if (engine === ENGINES.DOCKER_DESKTOP) {
+    await ensureDockerDesktop(config, onMessage);
+    return;
+  }
+
   if (engine === 'native') {
     if (!runOk('docker', ['info'])) {
       throw new Error('Docker daemon is not running. Please start Docker first.');
@@ -75,19 +145,58 @@ export async function ensureDocker(config, onMessage) {
   throw new Error(`Unsupported sandbox engine: ${engine}`);
 }
 
-export function isVmManaged() {
-  return detectEngine() === 'colima';
+export function isVmManaged(config = {}, dependencies = {}) {
+  const engine = detectEngine(config, dependencies);
+  return isManagedEngine(engine);
 }
 
-export function startManagedVm(config) {
-  if (!isVmManaged()) {
-    throw new Error('VM management is only available on macOS with Colima.');
+export function isManagedEngine(engine) {
+  return engine === ENGINES.COLIMA || engine === ENGINES.ORBSTACK;
+}
+
+export function engineDisplayName(engine) {
+  const names = {
+    [ENGINES.COLIMA]: 'Colima',
+    [ENGINES.ORBSTACK]: 'OrbStack',
+    [ENGINES.DOCKER_DESKTOP]: 'Docker Desktop',
+    native: 'native Docker',
+    wsl2: 'WSL2'
+  };
+  return names[engine] ?? engine;
+}
+
+export function startManagedVm(
+  config,
+  { platformFn = platform, runOkFn = runOk, runVerboseFn = runVerbose } = {}
+) {
+  const engine = detectEngine(config, { platformFn });
+  if (!isManagedEngine(engine)) {
+    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }
 
-  if (runOk('colima', ['status'])) {
+  if (engine === ENGINES.COLIMA && runOkFn('colima', ['status'])) {
+    return 'already-running';
+  }
+  if (engine === ENGINES.ORBSTACK && runOkFn('orb', ['status'])) {
     return 'already-running';
   }
 
-  runVerbose('colima', colimaArgs(config));
+  if (engine === ENGINES.COLIMA) {
+    runVerboseFn('colima', colimaArgs(config));
+  } else if (engine === ENGINES.ORBSTACK) {
+    runVerboseFn('orb', ['start']);
+  }
   return 'started';
 }
+
+export function stopManagedVm(config, { platformFn = platform, runFn = run } = {}) {
+  const engine = detectEngine(config, { platformFn });
+  if (engine === ENGINES.COLIMA) {
+    runFn('colima', ['stop']);
+    return 'stopped';
+  } else if (engine === ENGINES.ORBSTACK) {
+    runFn('orb', ['stop']);
+    return 'stopped';
+  }
+  throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
+}

package/lib/sandbox/shell.js

@@ -1,4 +1,6 @@
 import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 
@@ -11,25 +13,62 @@ function normalizeOptions(opts = {}, stdio) {
   };
 }
 
+function resolveCommand(cmd) {
+  if (process.platform !== 'win32' || path.extname(cmd)) {
+    return cmd;
+  }
+
+  const pathValue = process.env.Path || process.env.PATH || '';
+  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .filter(Boolean);
+
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(dir, `${cmd}${extension.toLowerCase()}`);
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+      const upperCandidate = path.join(dir, `${cmd}${extension.toUpperCase()}`);
+      if (fs.existsSync(upperCandidate)) {
+        return upperCandidate;
+      }
+    }
+  }
+
+  return cmd;
+}
+
+function commandOptions(cmd, opts) {
+  if (process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(cmd)) {
+    return { ...opts, shell: true };
+  }
+  return opts;
+}
+
 export function run(cmd, args, opts = {}) {
-  return execFileSync(cmd, args, {
+  const resolved = resolveCommand(cmd);
+  return execFileSync(resolved, args, commandOptions(resolved, {
     ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
     encoding: 'utf8'
-  }).trim();
+  })).trim();
 }
 
 export function runOk(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'pipe'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'pipe')));
   return result.status === 0;
 }
 
 export function runInteractive(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
   return result.status ?? 1;
 }
 
 export function runVerbose(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
 
   if (result.status !== 0) {
     if (result.signal === 'SIGTERM') {
@@ -40,9 +79,10 @@ export function runVerbose(cmd, args, opts = {}) {
 }
 
 export function runSafe(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, {
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, {
     ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
     encoding: 'utf8',
-  });
+  }));
   return (result.stdout ?? '').trim();
 }

package/lib/sandbox/task-resolver.js

@@ -2,24 +2,31 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
+
+function stripQuotes(value) {
+  return value.replace(/^(["'])(.*)\1$/, '$2');
+}
 
 function readTaskContent(repoRoot, taskId) {
-  const taskPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
-  if (!fs.existsSync(taskPath)) {
-    throw new Error(`Task not found: ${taskId}`);
+  for (const dir of WORKSPACE_DIRS) {
+    const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
+    if (fs.existsSync(taskPath)) {
+      return fs.readFileSync(taskPath, 'utf8');
+    }
   }
-  return fs.readFileSync(taskPath, 'utf8');
+  throw new Error(`Task not found: ${taskId}`);
 }
 
 function resolveBranchFromTaskContent(content, taskId) {
   const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
   if (frontmatterBranch && frontmatterBranch[1].trim()) {
-    return frontmatterBranch[1].trim();
+    return stripQuotes(frontmatterBranch[1].trim());
   }
 
   const contextBranch = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
   if (contextBranch && contextBranch[1].trim()) {
-    return contextBranch[1].trim();
+    return stripQuotes(contextBranch[1].trim());
   }
 
   throw new Error(`Task ${taskId} has no branch field in task.md`);

package/lib/sandbox/tools.js

@@ -18,6 +18,10 @@ import { safeNameCandidates, sanitizeBranchName } from './constants.js';
  * @property {string[]=} postSetupCmds
  */
 
+function hostJoin(basePath, ...segments) {
+  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
+}
+
 function createBuiltinTools(home, project) {
   /** @type {Record<string, SandboxTool>} */
   return {
@@ -25,7 +29,7 @@ function createBuiltinTools(home, project) {
       id: 'claude-code',
       name: 'Claude Code',
       npmPackage: '@anthropic-ai/claude-code',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'claude-code'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
       containerMount: '/home/devuser/.claude',
       versionCmd: 'claude --version',
       setupHint: 'Authenticates via host credentials live-mounted at ~/.claude/.credentials.json',
@@ -38,7 +42,7 @@ function createBuiltinTools(home, project) {
       // letting ensureClaudeOnboarding actually take effect.
       envVars: { CLAUDE_CONFIG_DIR: '/home/devuser/.claude' },
       hostPreSeedDirs: [
-        { hostDir: path.join(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
+        { hostDir: hostJoin(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
       ],
       pathRewriteFiles: [
         'plugins/installed_plugins.json',
@@ -46,7 +50,7 @@ function createBuiltinTools(home, project) {
       ],
       hostLiveMounts: [
         {
-          hostPath: path.join(home, '.agent-infra', 'credentials', project, 'claude-code', '.credentials.json'),
+          hostPath: hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code', '.credentials.json'),
           containerSubpath: '.credentials.json'
         }
       ]
@@ -55,12 +59,12 @@ function createBuiltinTools(home, project) {
       id: 'codex',
       name: 'Codex',
       npmPackage: '@openai/codex',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'codex'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
       setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
       hostLiveMounts: [
-        { hostPath: path.join(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
+        { hostPath: hostJoin(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
       ],
       postSetupCmds: [
         'test -d /workspace/.codex/commands && ln -sfn /workspace/.codex/commands /home/devuser/.codex/prompts || true'
@@ -70,13 +74,13 @@ function createBuiltinTools(home, project) {
       id: 'opencode',
       name: 'OpenCode',
       npmPackage: 'opencode-ai',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'opencode'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
       containerMount: '/home/devuser/.local/share/opencode',
       versionCmd: 'opencode version',
       setupHint: 'Configure OpenCode credentials inside the container before first use.',
       hostLiveMounts: [
         {
-          hostPath: path.join(home, '.local', 'share', 'opencode', 'auth.json'),
+          hostPath: hostJoin(home, '.local', 'share', 'opencode', 'auth.json'),
           containerSubpath: 'auth.json'
         }
       ]
@@ -85,16 +89,16 @@ function createBuiltinTools(home, project) {
       id: 'gemini-cli',
       name: 'Gemini CLI',
       npmPackage: '@google/gemini-cli',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
       containerMount: '/home/devuser/.gemini',
       versionCmd: 'gemini --version',
       setupHint: 'Run gemini inside the container to finish authentication.',
       hostLiveMounts: [
-        { hostPath: path.join(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
+        { hostPath: hostJoin(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
       ],
       hostPreSeedFiles: [
-        { hostPath: path.join(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
-        { hostPath: path.join(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
+        { hostPath: hostJoin(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
+        { hostPath: hostJoin(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
       ]
     }
   };
@@ -119,15 +123,15 @@ export function resolveTools(config) {
 }
 
 export function toolConfigDir(tool, project, branch) {
-  return path.join(tool.sandboxBase, project, sanitizeBranchName(branch));
+  return hostJoin(tool.sandboxBase, project, sanitizeBranchName(branch));
 }
 
 export function toolConfigDirCandidates(tool, project, branch) {
-  return safeNameCandidates(branch).map((name) => path.join(tool.sandboxBase, project, name));
+  return safeNameCandidates(branch).map((name) => hostJoin(tool.sandboxBase, project, name));
 }
 
 export function toolProjectDirCandidates(tool, project) {
-  return [path.join(tool.sandboxBase, project)];
+  return [hostJoin(tool.sandboxBase, project)];
 }
 
 export function toolNpmPackagesArg(tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -46,7 +46,7 @@
   },
   "scripts": {
     "build": "node scripts/build-inline.js",
-    "demo:regen": "vhs assets/demo-init.tape",
+    "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .github/hooks || true",
     "test": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js",
     "prepublishOnly": "node scripts/build-inline.js --check && node --test tests/cli/*.test.js tests/templates/*.test.js tests/core/*.test.js"

package/templates/.agents/QUICKSTART.en.md

@@ -18,6 +18,23 @@ git config core.hooksPath .github/hooks
 
 This makes Git invoke the hooks synced into `.github/hooks/`, including `pre-commit` and `check-version-format.sh`.
 
+## External Templates And Skills
+
+If your team maintains private platform templates or shared custom skills, configure local sources in `.agents/.airc.json`:
+
+```json
+{
+  "templates": {
+    "sources": [{ "type": "local", "path": "~/private-templates" }]
+  },
+  "skills": {
+    "sources": [{ "type": "local", "path": "~/private-skills" }]
+  }
+}
+```
+
+Built-in templates take priority over external templates. Later external template sources override earlier external sources, and `update-agent-infra` reports conflicts in `templateSources.conflicts`. Only use trusted local paths because external templates and skills may contain executable scripts.
+
 ## Creating Your First Task
 
 1. Copy the task template to the active workspace:

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -18,6 +18,23 @@ git config core.hooksPath .github/hooks
 
 这样 Git 才会调用同步到 `.github/hooks/` 下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
 
+## 外部模板与 Skill
+
+如果团队维护私有平台模板或共享自定义 skill，可在 `.agents/.airc.json` 中配置本地源：
+
+```json
+{
+  "templates": {
+    "sources": [{ "type": "local", "path": "~/private-templates" }]
+  },
+  "skills": {
+    "sources": [{ "type": "local", "path": "~/private-skills" }]
+  }
+}
+```
+
+内置模板优先级高于外部模板。多个外部模板源之间，后面的 source 覆盖前面的 source，`update-agent-infra` 会在 `templateSources.conflicts` 中报告冲突。外部模板和 skill 可能包含可执行脚本，只使用可信本地路径。
+
 ## 创建第一个任务
 
 1. 将任务模板复制到活跃工作区：