skyloom 1.13.6 → 1.13.8

package/src/agents/snow.ts

@@ -1,239 +1,239 @@
-/**
- * 雪 (Snow) — 架构规划型全能 Agent.
- * A general-purpose agent specializing in architecture and planning.
- * Also handles task decomposition and orchestration.
- */
-
-import { BaseAgent, Task } from '../core/agent';
-
-// Valid agents for task assignment (fair is independent, not part of orchestration)
-const VALID_AGENTS = new Set(['fog', 'rain', 'frost', 'snow', 'dew']);
-
-export class SnowAgent extends BaseAgent {
-  name = 'snow';
-  displayName = '雪';
-  emoji = '❉';
-  specialty = '架构规划';
-  skillNames = ['task_planner', 'arch_designer', 'workflow_designer', 'self_evolve'];
-
-  systemPrompt = `你是 Skyloom 的「雪」。
-
-你是全能 agent —— 代码、写作、审查、部署、规划、研究,你都能独立交付。
-你的特质是「全局视野」:先看清结构、依赖、顺序、风险,再动手。
-混乱的需求经你一拆,就变成清晰的步骤树。这是你看世界的方式,不仅是你做编排时才用。
-
-## 协作
-
-90% 的事自己做完。只有任务跨 5+ 领域、上下文塞不下、或需要多轮独立审查时,才调其他 agent。
-调用时给足上下文,拿到结果整合成完整答复,用户不需要感知协作过程。
-
-## 风格
-
-像雪一样静默但覆盖一切 —— 结构清晰,考虑周全。
-- 大任务先给整体框架,再深入
-- 标注依赖、风险、预计工作量
-- 规划:框架先于理由
-- 执行:按优先级推进,完成后汇总
-- 让人感觉「一切都在掌控之中」`;
-
-  systemPromptEn = `You are "Snow" of Skyloom.
-
-A general-purpose agent — code, writing, review, ops, planning, research — you ship anything alone.
-Your nature: see the whole. Structure, dependencies, sequence, risk — all before the first move.
-Messy requirements come out as clear step trees. That's how you see, not just how you orchestrate.
-
-## Collaboration
-Do 90% alone. Delegate only when 5+ domains, context overflow, or multi-round review is needed.
-Pass full context; synthesize the result yourself.
-
-## Style
-Like snow — silent but all-covering. Clear structure, thorough consideration.
-- Big work: framework first, then detail
-- Note dependencies, risks, effort estimates
-- Planning: structure before justification
-- Execution: prioritize, deliver, summarize
-- Leaves the user feeling "this is under control"`;
-
-  /**
-   * Decompose a goal into tasks and dispatch to agents.
-   */
-  async orchestrate(goal: string): Promise<Task[]> {
-    const prompt = `请将以下目标分解为子任务，并分配给合适的 Agent。
-
-目标: ${goal}
-
-请严格按照以下 JSON Schema 输出，不要包含其他内容：
-{"goal": "目标描述", "steps": [
-  {"id": "1", "description": "任务描述", "agent": "fog"},
-  {"id": "2", "description": "后续任务", "agent": "rain", "depends_on": ["1"]}
-]}
-
-可用 Agent: fog(调研/搜索), rain(代码生成/写作), frost(审查/安全), dew(部署/运维)
-注意:fair 是独立的情感陪伴 agent,**不参与任何任务编排**,绝不要分配给她。
-注意：如果任务有先后依赖关系，必须用 depends_on 字段标出。
-不要使用工具，直接输出 JSON 即可。`;
-
-    this.memory.addMessage('user', prompt);
-    const response = await this.llmLoop();
-    this.memory.addMessage('assistant', response.content);
-
-    // Try schema-validated parsing first
-    try {
-      const { parseTaskPlan } = require('../core/schemas');
-      const parsed = parseTaskPlan(response.content);
-      if (parsed && parsed.steps && parsed.steps.length > 0) {
-        return this.schemaToTasks(parsed, goal);
-      }
-    } catch { /* fallthrough */ }
-
-    // Fallback to heuristic parsing
-    return this.parseTaskPlan(response.content, goal);
-  }
-
-  /**
-   * Produce additional tasks that close the gap reported by the judge.
-   */
-  async replanForMissing(
-    goal: string,
-    priorResults: any[],
-    missing: string,
-    existingIds?: Set<string>
-  ): Promise<Task[]> {
-    const usedIds = existingIds || new Set<string>();
-    const priorLines = priorResults.map(r => {
-      const status = r.success ? '成功' : '失败';
-      return `- task ${r.id} (${r.agent}, ${status}): ${(r.content || '').slice(0, 200)}`;
-    });
-    const priorText = priorLines.length > 0 ? priorLines.join('\n') : '(none yet)';
-
-    // Identify failing agents
-    const failingAgents = new Set(
-      priorResults
-        .filter(r => !r.success || !r.content || r.content.trim().length < 16)
-        .map(r => r.agent)
-        .filter(Boolean)
-    );
-    const failingHint = failingAgents.size > 0
-      ? `\n\n## 已证明无效的 agent\n${[...failingAgents].sort().join(', ')} 已在上一轮返回占位/无交付物。\n**禁止把同类任务再交给以上 agent**。`
-      : '';
-
-    const prompt = `之前的子任务执行后，验收员发现还有缺口。请仅针对**缺失的部分**追加新的子任务。
-
-## 原目标
-${goal}
-
-## 已执行子任务
-${priorText}
-
-## 缺口（验收员报告）
-${missing}
-
-## 已使用的 task id（必须避开）
-${usedIds.size > 0 ? [...usedIds].sort().join(', ') : '(none)'}
-${failingHint}
-
-请输出新任务的 JSON 计划：
-{"steps": [{"id": "新id", "agent": "fog|rain|frost|dew", "description": "具体任务", "depends_on": ["可选已完成任务id"]}]}
-
-约束：
-- 只输出新增任务，不要重复已完成的；id 必须避开上面的列表
-- 控制在 2 个新任务以内（精简优先）
-- 只输出 JSON，无其他文本`;
-
-    this.memory.addMessage('user', prompt);
-    const response = await this.llmLoop();
-    this.memory.addMessage('assistant', response.content);
-
-    let newTasks: Task[];
-    try {
-      const { parseTaskPlan } = require('../core/schemas');
-      const parsed = parseTaskPlan(response.content);
-      if (parsed && parsed.steps) {
-        newTasks = this.schemaToTasks(parsed, goal);
-      } else {
-        newTasks = this.parseTaskPlan(response.content, goal);
-      }
-    } catch {
-      newTasks = this.parseTaskPlan(response.content, goal);
-    }
-
-    // Deduplicate IDs
-    const deduped: Task[] = [];
-    for (const t of newTasks) {
-      if (usedIds.has(t.id)) {
-        t.id = `r${usedIds.size + deduped.length + 1}_${t.id}`;
-      }
-      deduped.push(t);
-      usedIds.add(t.id);
-    }
-    return deduped;
-  }
-
-  private schemaToTasks(plan: any, goal: string): Task[] {
-    const tasks: Task[] = [];
-    for (const step of plan.steps || []) {
-      const sid = String(step.id);
-      const depends: string[] = step.depends_on || [];
-      const agent = VALID_AGENTS.has(step.agent) ? step.agent : 'rain';
-      tasks.push(new Task({
-        id: sid,
-        description: step.description,
-        assignedTo: agent,
-        parentId: depends.length > 0 ? depends[0] : null,
-        dependsOn: depends,
-        metadata: { goal, priority: step.priority || 'medium' },
-      }));
-    }
-    return tasks;
-  }
-
-  private parseTaskPlan(content: string, goal: string): Task[] {
-    // Try to extract JSON from markdown code blocks
-    const jsonBlockPatterns = [
-      /```json\s*\n(.*?)\n```/s,
-      /```\s*\n(\{.*?\})\n```/s,
-    ];
-
-    for (const pattern of jsonBlockPatterns) {
-      const match = content.match(pattern);
-      if (match) {
-        try {
-          const plan = JSON.parse(match[1].trim());
-          const tasks = this.planToTasks(plan, goal);
-          if (tasks.length > 0) return tasks;
-        } catch { /* continue */ }
-      }
-    }
-
-    // Try to find raw JSON in response
-    try {
-      const start = content.indexOf('{');
-      const end = content.lastIndexOf('}') + 1;
-      if (start >= 0 && end > start) {
-        const plan = JSON.parse(content.slice(start, end));
-        const tasks = this.planToTasks(plan, goal);
-        if (tasks.length > 0) return tasks;
-      }
-    } catch { /* continue */ }
-
-    // Fallback: single task for rain
-    return [new Task({ id: '1', description: goal, assignedTo: 'rain', metadata: { goal } })];
-  }
-
-  private planToTasks(plan: Record<string, any>, goal: string): Task[] {
-    const tasks: Task[] = [];
-    for (const step of (plan.steps || []) as any[]) {
-      const agent = VALID_AGENTS.has(step.agent) ? step.agent : 'rain';
-      const depends: string[] = Array.isArray(step.depends_on) ? step.depends_on : [];
-      tasks.push(new Task({
-        id: String(step.id || tasks.length + 1),
-        description: step.description || '',
-        assignedTo: agent,
-        parentId: depends.length > 0 ? depends[0] : null,
-        dependsOn: depends,
-        metadata: { goal, priority: step.priority || 'medium' },
-      }));
-    }
-    return tasks;
-  }
-}
+/**
+ * 雪 (Snow) — 架构规划型全能 Agent.
+ * A general-purpose agent specializing in architecture and planning.
+ * Also handles task decomposition and orchestration.
+ */
+
+import { BaseAgent, Task } from '../core/agent';
+
+// Valid agents for task assignment (fair is independent, not part of orchestration)
+const VALID_AGENTS = new Set(['fog', 'rain', 'frost', 'snow', 'dew']);
+
+export class SnowAgent extends BaseAgent {
+  name = 'snow';
+  displayName = '雪';
+  emoji = '❉';
+  specialty = '架构规划';
+  skillNames = ['task_planner', 'arch_designer', 'workflow_designer', 'self_evolve'];
+
+  systemPrompt = `你是 Skyloom 的「雪」。
+
+你是全能 agent —— 代码、写作、审查、部署、规划、研究,你都能独立交付。
+你的特质是「全局视野」:先看清结构、依赖、顺序、风险,再动手。
+混乱的需求经你一拆,就变成清晰的步骤树。这是你看世界的方式,不仅是你做编排时才用。
+
+## 协作
+
+90% 的事自己做完。只有任务跨 5+ 领域、上下文塞不下、或需要多轮独立审查时,才调其他 agent。
+调用时给足上下文,拿到结果整合成完整答复,用户不需要感知协作过程。
+
+## 风格
+
+像雪一样静默但覆盖一切 —— 结构清晰,考虑周全。
+- 大任务先给整体框架,再深入
+- 标注依赖、风险、预计工作量
+- 规划:框架先于理由
+- 执行:按优先级推进,完成后汇总
+- 让人感觉「一切都在掌控之中」`;
+
+  systemPromptEn = `You are "Snow" of Skyloom.
+
+A general-purpose agent — code, writing, review, ops, planning, research — you ship anything alone.
+Your nature: see the whole. Structure, dependencies, sequence, risk — all before the first move.
+Messy requirements come out as clear step trees. That's how you see, not just how you orchestrate.
+
+## Collaboration
+Do 90% alone. Delegate only when 5+ domains, context overflow, or multi-round review is needed.
+Pass full context; synthesize the result yourself.
+
+## Style
+Like snow — silent but all-covering. Clear structure, thorough consideration.
+- Big work: framework first, then detail
+- Note dependencies, risks, effort estimates
+- Planning: structure before justification
+- Execution: prioritize, deliver, summarize
+- Leaves the user feeling "this is under control"`;
+
+  /**
+   * Decompose a goal into tasks and dispatch to agents.
+   */
+  async orchestrate(goal: string): Promise<Task[]> {
+    const prompt = `请将以下目标分解为子任务，并分配给合适的 Agent。
+
+目标: ${goal}
+
+请严格按照以下 JSON Schema 输出，不要包含其他内容：
+{"goal": "目标描述", "steps": [
+  {"id": "1", "description": "任务描述", "agent": "fog"},
+  {"id": "2", "description": "后续任务", "agent": "rain", "depends_on": ["1"]}
+]}
+
+可用 Agent: fog(调研/搜索), rain(代码生成/写作), frost(审查/安全), dew(部署/运维)
+注意:fair 是独立的情感陪伴 agent,**不参与任何任务编排**,绝不要分配给她。
+注意：如果任务有先后依赖关系，必须用 depends_on 字段标出。
+不要使用工具，直接输出 JSON 即可。`;
+
+    this.memory.addMessage('user', prompt);
+    const response = await this.llmLoop();
+    this.memory.addMessage('assistant', response.content);
+
+    // Try schema-validated parsing first
+    try {
+      const { parseTaskPlan } = require('../core/schemas');
+      const parsed = parseTaskPlan(response.content);
+      if (parsed && parsed.steps && parsed.steps.length > 0) {
+        return this.schemaToTasks(parsed, goal);
+      }
+    } catch { /* fallthrough */ }
+
+    // Fallback to heuristic parsing
+    return this.parseTaskPlan(response.content, goal);
+  }
+
+  /**
+   * Produce additional tasks that close the gap reported by the judge.
+   */
+  async replanForMissing(
+    goal: string,
+    priorResults: any[],
+    missing: string,
+    existingIds?: Set<string>
+  ): Promise<Task[]> {
+    const usedIds = existingIds || new Set<string>();
+    const priorLines = priorResults.map(r => {
+      const status = r.success ? '成功' : '失败';
+      return `- task ${r.id} (${r.agent}, ${status}): ${(r.content || '').slice(0, 200)}`;
+    });
+    const priorText = priorLines.length > 0 ? priorLines.join('\n') : '(none yet)';
+
+    // Identify failing agents
+    const failingAgents = new Set(
+      priorResults
+        .filter(r => !r.success || !r.content || r.content.trim().length < 16)
+        .map(r => r.agent)
+        .filter(Boolean)
+    );
+    const failingHint = failingAgents.size > 0
+      ? `\n\n## 已证明无效的 agent\n${[...failingAgents].sort().join(', ')} 已在上一轮返回占位/无交付物。\n**禁止把同类任务再交给以上 agent**。`
+      : '';
+
+    const prompt = `之前的子任务执行后，验收员发现还有缺口。请仅针对**缺失的部分**追加新的子任务。
+
+## 原目标
+${goal}
+
+## 已执行子任务
+${priorText}
+
+## 缺口（验收员报告）
+${missing}
+
+## 已使用的 task id（必须避开）
+${usedIds.size > 0 ? [...usedIds].sort().join(', ') : '(none)'}
+${failingHint}
+
+请输出新任务的 JSON 计划：
+{"steps": [{"id": "新id", "agent": "fog|rain|frost|dew", "description": "具体任务", "depends_on": ["可选已完成任务id"]}]}
+
+约束：
+- 只输出新增任务，不要重复已完成的；id 必须避开上面的列表
+- 控制在 2 个新任务以内（精简优先）
+- 只输出 JSON，无其他文本`;
+
+    this.memory.addMessage('user', prompt);
+    const response = await this.llmLoop();
+    this.memory.addMessage('assistant', response.content);
+
+    let newTasks: Task[];
+    try {
+      const { parseTaskPlan } = require('../core/schemas');
+      const parsed = parseTaskPlan(response.content);
+      if (parsed && parsed.steps) {
+        newTasks = this.schemaToTasks(parsed, goal);
+      } else {
+        newTasks = this.parseTaskPlan(response.content, goal);
+      }
+    } catch {
+      newTasks = this.parseTaskPlan(response.content, goal);
+    }
+
+    // Deduplicate IDs
+    const deduped: Task[] = [];
+    for (const t of newTasks) {
+      if (usedIds.has(t.id)) {
+        t.id = `r${usedIds.size + deduped.length + 1}_${t.id}`;
+      }
+      deduped.push(t);
+      usedIds.add(t.id);
+    }
+    return deduped;
+  }
+
+  private schemaToTasks(plan: any, goal: string): Task[] {
+    const tasks: Task[] = [];
+    for (const step of plan.steps || []) {
+      const sid = String(step.id);
+      const depends: string[] = step.depends_on || [];
+      const agent = VALID_AGENTS.has(step.agent) ? step.agent : 'rain';
+      tasks.push(new Task({
+        id: sid,
+        description: step.description,
+        assignedTo: agent,
+        parentId: depends.length > 0 ? depends[0] : null,
+        dependsOn: depends,
+        metadata: { goal, priority: step.priority || 'medium' },
+      }));
+    }
+    return tasks;
+  }
+
+  private parseTaskPlan(content: string, goal: string): Task[] {
+    // Try to extract JSON from markdown code blocks
+    const jsonBlockPatterns = [
+      /```json\s*\n(.*?)\n```/s,
+      /```\s*\n(\{.*?\})\n```/s,
+    ];
+
+    for (const pattern of jsonBlockPatterns) {
+      const match = content.match(pattern);
+      if (match) {
+        try {
+          const plan = JSON.parse(match[1].trim());
+          const tasks = this.planToTasks(plan, goal);
+          if (tasks.length > 0) return tasks;
+        } catch { /* continue */ }
+      }
+    }
+
+    // Try to find raw JSON in response
+    try {
+      const start = content.indexOf('{');
+      const end = content.lastIndexOf('}') + 1;
+      if (start >= 0 && end > start) {
+        const plan = JSON.parse(content.slice(start, end));
+        const tasks = this.planToTasks(plan, goal);
+        if (tasks.length > 0) return tasks;
+      }
+    } catch { /* continue */ }
+
+    // Fallback: single task for rain
+    return [new Task({ id: '1', description: goal, assignedTo: 'rain', metadata: { goal } })];
+  }
+
+  private planToTasks(plan: Record<string, any>, goal: string): Task[] {
+    const tasks: Task[] = [];
+    for (const step of (plan.steps || []) as any[]) {
+      const agent = VALID_AGENTS.has(step.agent) ? step.agent : 'rain';
+      const depends: string[] = Array.isArray(step.depends_on) ? step.depends_on : [];
+      tasks.push(new Task({
+        id: String(step.id || tasks.length + 1),
+        description: step.description || '',
+        assignedTo: agent,
+        parentId: depends.length > 0 ? depends[0] : null,
+        dependsOn: depends,
+        metadata: { goal, priority: step.priority || 'medium' },
+      }));
+    }
+    return tasks;
+  }
+}

package/src/cli/commands_md.ts

@@ -0,0 +1,112 @@
+/**
+ * 自定义斜杠命令 — markdown prompt templates promoted to commands.
+ *
+ * Drop a .md file into `.sky/commands/` (project) or `~/.skyloom/commands/`
+ * (user); the filename becomes the command. Subdirectories namespace:
+ * `.sky/commands/git/commit.md` → /git:commit.
+ *
+ * File format:
+ *   ---
+ *   description: 修复指定的 GitHub issue       (optional, shown in palette)
+ *   agent: rain                                (optional, runs as this agent)
+ *   ---
+ *   请修复 issue #$ARGUMENTS：
+ *   1. 读取 issue 详情 …
+ *
+ * Placeholders: $ARGUMENTS = everything after the command; $1…$9 = positional.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+export interface CustomCommand {
+  /** Command name without the leading slash (may contain ':'). */
+  name: string;
+  description: string;
+  agent?: string;
+  body: string;
+  file: string;
+}
+
+const MAX_BODY_CHARS = 12000;
+
+function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
+  const m = /^---\n([\s\S]*?)\n---\n?/.exec(raw);
+  if (!m) return { meta: {}, body: raw };
+  const meta: Record<string, string> = {};
+  for (const line of m[1].split('\n')) {
+    const kv = /^([\w-]+)\s*:\s*(.+)$/.exec(line.trim());
+    if (kv) meta[kv[1].toLowerCase()] = kv[2].trim();
+  }
+  return { meta, body: raw.slice(m[0].length) };
+}
+
+function scanDir(dir: string, prefix: string, out: CustomCommand[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      scanDir(full, prefix ? `${prefix}:${e.name}` : e.name, out);
+      continue;
+    }
+    if (!e.name.endsWith('.md')) continue;
+    try {
+      const raw = fs.readFileSync(full, 'utf-8');
+      const { meta, body } = parseFrontmatter(raw);
+      const base = e.name.slice(0, -3);
+      const name = prefix ? `${prefix}:${base}` : base;
+      out.push({
+        name,
+        description: meta.description || body.trim().split('\n')[0].slice(0, 50),
+        agent: meta.agent,
+        body: body.trim().slice(0, MAX_BODY_CHARS),
+        file: full,
+      });
+    } catch { /* unreadable file: skip */ }
+  }
+}
+
+/**
+ * Load custom commands. Project commands shadow user commands of the same
+ * name. Re-scans on every call so edits take effect without a restart.
+ */
+export function loadCustomCommands(cwd: string = process.cwd()): CustomCommand[] {
+  const user: CustomCommand[] = [];
+  const project: CustomCommand[] = [];
+  scanDir(path.join(os.homedir(), '.skyloom', 'commands'), '', user);
+  scanDir(path.join(cwd, '.sky', 'commands'), '', project);
+  const byName = new Map<string, CustomCommand>();
+  for (const c of [...user, ...project]) byName.set(c.name, c); // project wins
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Substitute $ARGUMENTS and $1…$9 into a command body. */
+export function substituteArgs(body: string, argString: string): string {
+  const args = argString.trim() ? argString.trim().split(/\s+/) : [];
+  return body
+    .replace(/\$ARGUMENTS/g, argString.trim())
+    .replace(/\$([1-9])/g, (_, n) => args[parseInt(n, 10) - 1] ?? '');
+}
+
+/**
+ * Match an input line like "/fix-issue 123" against the loaded commands.
+ * Returns the expanded prompt (and optional agent) or null.
+ */
+export function resolveCustomCommand(
+  input: string,
+  commands: CustomCommand[]
+): { command: CustomCommand; prompt: string } | null {
+  if (!input.startsWith('/')) return null;
+  const space = input.indexOf(' ');
+  const name = (space < 0 ? input.slice(1) : input.slice(1, space)).toLowerCase();
+  const argString = space < 0 ? '' : input.slice(space + 1);
+  const command = commands.find(c => c.name.toLowerCase() === name);
+  if (!command) return null;
+  return { command, prompt: substituteArgs(command.body, argString) };
+}

package/src/cli/input_macros.ts

@@ -0,0 +1,83 @@
+/**
+ * Input macros — Claude Code-style line conveniences for both CLIs:
+ *
+ *   @path/to/file   pull a file's content into the message (Tab-free attach)
+ *   !command        run a shell command; output goes into context, no LLM turn
+ *   #note           append a quick memory line to SKY.md, no LLM turn
+ */
+
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const MAX_ATTACH_CHARS = 16000;
+const MAX_ATTACH_FILES = 3;
+const BANG_TIMEOUT_MS = 15_000;
+const BANG_TAIL = 8000;
+
+/** `#note` quick-memory line? (single `#` + content; `##` is markdown, skip) */
+export function isHashMemory(text: string): boolean {
+  return /^#(?!#)\s*\S/.test(text.trim());
+}
+
+export function hashNote(text: string): string {
+  return text.trim().replace(/^#\s*/, '');
+}
+
+/** `!cmd` shell line? */
+export function isBangCommand(text: string): boolean {
+  return /^!\s*\S/.test(text.trim());
+}
+
+export function bangCommand(text: string): string {
+  return text.trim().replace(/^!\s*/, '');
+}
+
+/** Run a `!cmd` line; returns the (tail-clamped) combined output. */
+export function runBang(cmd: string, cwd: string = process.cwd()): { ok: boolean; output: string } {
+  try {
+    const out = execSync(cmd, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: BANG_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, FORCE_COLOR: '0' },
+    });
+    const text = out.trim() || '(无输出)';
+    return { ok: true, output: text.length > BANG_TAIL ? '…' + text.slice(-BANG_TAIL) : text };
+  } catch (e: any) {
+    const text = `${e?.stdout || ''}${e?.stderr || ''}`.trim() || String(e?.message || e);
+    return { ok: false, output: text.length > BANG_TAIL ? '…' + text.slice(-BANG_TAIL) : text };
+  }
+}
+
+/**
+ * Expand `@file` references: for each token that names an existing file,
+ * append its (clamped) content as a fenced attachment. The original message
+ * text is preserved so the model still sees what the user pointed at.
+ */
+export function expandFileRefs(
+  text: string,
+  cwd: string = process.cwd()
+): { text: string; attached: string[] } {
+  const attached: string[] = [];
+  const refs = [...text.matchAll(/(?:^|\s)@([\w\-./\\]+)/g)].map(m => m[1]);
+  if (refs.length === 0) return { text, attached };
+
+  const sections: string[] = [];
+  for (const ref of refs) {
+    if (attached.length >= MAX_ATTACH_FILES) break;
+    const p = path.resolve(cwd, ref);
+    try {
+      if (!fs.existsSync(p) || !fs.statSync(p).isFile()) continue;
+      let content = fs.readFileSync(p, 'utf-8');
+      if (content.length > MAX_ATTACH_CHARS) content = content.slice(0, MAX_ATTACH_CHARS) + '\n…[truncated]';
+      sections.push(`[附件 @${ref}]\n\`\`\`\n${content}\n\`\`\``);
+      attached.push(ref);
+    } catch {
+      /* unreadable file: leave the reference as plain text */
+    }
+  }
+  if (sections.length === 0) return { text, attached };
+  return { text: `${text}\n\n${sections.join('\n\n')}`, attached };
+}