@downcity/agent 1.1.337 → 1.1.399

package/src/types/workspace/FileTool.ts

@@ -1,225 +0,0 @@
-/**
- * 文件工具公开类型。
- *
- * 关键点（中文）
- * - 文件工具由 Workspace 持有，与 Shell/PTY action 分离。
- * - 所有模型可见字段统一使用 snake_case。
- * - 成功与失败均返回结构化结果，避免依赖异常文本判断执行状态。
- */
-
-import type { Tool } from "ai";
-
-/** 文件工具支持的结构化错误码。 */
-export type FileToolErrorCode =
-  | "invalid_path"
-  | "sandbox_denied"
-  | "file_not_found"
-  | "not_a_file"
-  | "permission_denied"
-  | "file_exists"
-  | "file_too_large"
-  | "content_too_large"
-  | "line_too_large"
-  | "encoding_error"
-  | "binary_file"
-  | "no_edits"
-  | "too_many_edits"
-  | "duplicate_match"
-  | "not_found"
-  | "overlapping_edits"
-  | "edit_too_large"
-  | "file_changed"
-  | "internal_error";
-
-/** 文件读取工具输入。 */
-export interface ReadFileToolInput {
-  /** 要读取的项目内相对路径或绝对路径。 */
-  file_path: string;
-  /** 从第几行开始读取，使用 0-based 行号。 */
-  offset?: number;
-  /** 本次最多返回的行数。 */
-  limit?: number;
-}
-
-/** 文件写入工具输入。 */
-export interface WriteFileToolInput {
-  /** 要创建或覆盖的项目内相对路径或绝对路径。 */
-  file_path: string;
-  /** 要写入的 UTF-8 文本内容。 */
-  content: string;
-  /** 文件存在时是否允许覆盖，默认不允许。 */
-  overwrite?: boolean;
-}
-
-/** 单项精确文本编辑。 */
-export interface FileEditOperation {
-  /** 必须在原文件中唯一匹配的原始文本。 */
-  old_text: string;
-  /** 用于替换唯一匹配区域的新文本。 */
-  new_text: string;
-}
-
-/** 文件编辑工具输入。 */
-export interface EditFileToolInput {
-  /** 要编辑的项目内相对路径或绝对路径。 */
-  file_path: string;
-  /** 一次原子应用的精确文本编辑列表。 */
-  edits: FileEditOperation[];
-  /** 可选的读取时 SHA-256；文件变化后拒绝编辑。 */
-  expected_sha256?: string;
-}
-
-/** 文件工具统一失败结果。 */
-export interface FileToolFailure {
-  /** 表示本次文件操作失败。 */
-  success: false;
-  /** 供模型和调用方稳定解析的错误码。 */
-  error_code: FileToolErrorCode;
-  /** 面向模型和日志的人类可读错误信息。 */
-  message: string;
-  /** 已完成解析时的目标绝对路径。 */
-  file_path?: string;
-  /** 编辑失败时每项匹配的详细结果。 */
-  details?: FileEditDetail[];
-}
-
-/** 文件读取成功结果。 */
-export interface ReadFileToolSuccess {
-  /** 表示本次文件读取成功。 */
-  success: true;
-  /** 解析并校验后的目标绝对路径。 */
-  file_path: string;
-  /** 原始文件总字节数。 */
-  total_bytes: number;
-  /** 文本文件总行数；图片和其他二进制文件固定为 0。 */
-  total_lines: number;
-  /** 本次返回内容的 0-based 起始行。 */
-  start_line: number;
-  /** 本次返回内容的 0-based 结束行；没有返回行时小于 start_line。 */
-  end_line: number;
-  /** 返回给模型的文本内容；图片和其他二进制文件为空字符串。 */
-  content: string;
-  /** 是否还有后续文本行未返回。 */
-  truncated: boolean;
-  /** 有后续文本时建议下一次使用的 offset。 */
-  next_offset?: number;
-  /** 当前文件被识别为文本、图片还是其他二进制文件。 */
-  type: "text" | "image" | "binary";
-  /** 当前文件的 MIME 类型。 */
-  mime_type?: string;
-  /** 文本文件实际采用的解码格式。 */
-  encoding?: "utf-8" | "utf-16le" | "utf-16be";
-  /** 原始文件内容的 SHA-256，可传给 edit 防止并发覆盖。 */
-  sha256: string;
-}
-
-/** 文件写入成功结果。 */
-export interface WriteFileToolSuccess {
-  /** 表示本次文件写入成功。 */
-  success: true;
-  /** 解析并校验后的目标绝对路径。 */
-  file_path: string;
-  /** 实际写入的 UTF-8 字节数。 */
-  bytes_written: number;
-  /** 实际写入的文本行数。 */
-  lines_written: number;
-  /** 本次操作是否覆盖了已有文件。 */
-  overwritten: boolean;
-  /** 写入完成后的 ISO 时间戳。 */
-  timestamp: string;
-  /** 写入后文件内容的 SHA-256。 */
-  sha256: string;
-}
-
-/** 单项编辑匹配详情。 */
-export interface FileEditDetail {
-  /** 当前编辑项的原始索引。 */
-  index: number;
-  /** 当前编辑项的匹配与应用状态。 */
-  status: "applied" | "not_found" | "duplicate";
-  /** 当前 old_text 在原文件中的匹配次数。 */
-  match_count: number;
-  /** 唯一匹配成功时的 0-based 起始行。 */
-  line_start?: number;
-}
-
-/** 文件编辑成功结果。 */
-export interface EditFileToolSuccess {
-  /** 表示全部编辑已原子应用。 */
-  success: true;
-  /** 解析并校验后的目标绝对路径。 */
-  file_path: string;
-  /** 成功应用的编辑数量。 */
-  applied: number;
-  /** 每项编辑的匹配与应用详情。 */
-  details: FileEditDetail[];
-  /** 编辑后文件的总行数。 */
-  new_total_lines: number;
-  /** 编辑前文件内容的 SHA-256。 */
-  previous_sha256: string;
-  /** 编辑后文件内容的 SHA-256。 */
-  sha256: string;
-}
-
-/** 文件读取工具结果。 */
-export type ReadFileToolResult = ReadFileToolSuccess | FileToolFailure;
-
-/** 文件写入工具结果。 */
-export type WriteFileToolResult = WriteFileToolSuccess | FileToolFailure;
-
-/** 文件编辑工具结果。 */
-export type EditFileToolResult = EditFileToolSuccess | FileToolFailure;
-
-/** 文件工具内部 action 名称。 */
-export type FileToolAction = "read" | "write" | "edit";
-
-/** 文件 action 的判别式请求。 */
-export type FileToolActionRequest =
-  | {
-      /** 指定执行文件读取。 */
-      action: "read";
-      /** 文件读取输入。 */
-      input: ReadFileToolInput;
-    }
-  | {
-      /** 指定执行文件写入。 */
-      action: "write";
-      /** 文件写入输入。 */
-      input: WriteFileToolInput;
-    }
-  | {
-      /** 指定执行文件编辑。 */
-      action: "edit";
-      /** 文件编辑输入。 */
-      input: EditFileToolInput;
-    };
-
-/** 文件 action 的统一结果。 */
-export type FileToolActionResult =
-  | ReadFileToolResult
-  | WriteFileToolResult
-  | EditFileToolResult;
-
-/** 文件工具运行器协议。 */
-export interface FileToolRunner {
-  /** 执行一个独立文件 action。 */
-  run_file_action(request: FileToolActionRequest): Promise<FileToolActionResult>;
-}
-
-/** `@downcity/shell` 对模型暴露的文件工具集合。 */
-export interface FileToolSet {
-  /** 分页读取文本并识别二进制文件。 */
-  read: Tool;
-  /** 创建或显式覆盖 UTF-8 文本文件。 */
-  write: Tool;
-  /** 通过唯一文本匹配原子编辑单个文件。 */
-  edit: Tool;
-}
-
-/** 已通过项目根目录约束的文件工具路径。 */
-export interface ResolvedFileToolPath {
-  /** 解析后的目标绝对路径。 */
-  file_path: string;
-  /** 解析后的项目根目录绝对路径。 */
-  root_path: string;
-}

package/src/types/workspace/SearchTool.ts

@@ -1,156 +0,0 @@
-/**
- * 项目搜索工具公开类型。
- *
- * 关键点（中文）
- * - `grep` 通过 ripgrep 搜索文件内容，`find` 通过 glob 发现文件。
- * - 模型可见字段统一使用 snake_case，并返回稳定的结构化结果。
- * - 两个工具都受 Shell 项目根目录约束，不允许搜索根目录之外的路径。
- */
-
-import type { Tool } from "ai";
-
-/** 搜索工具支持的结构化错误码。 */
-export type SearchToolErrorCode =
-  | "invalid_path"
-  | "sandbox_denied"
-  | "path_not_found"
-  | "not_a_directory"
-  | "invalid_pattern"
-  | "rg_unavailable"
-  | "search_failed"
-  | "aborted"
-  | "internal_error";
-
-/** grep 工具输入。 */
-export interface GrepToolInput {
-  /** 要搜索的文本或正则表达式。 */
-  query: string;
-  /** 搜索范围的项目内相对路径或绝对路径，默认为项目根目录。 */
-  path?: string;
-  /** 用于限制候选文件的 ripgrep glob 模式列表。 */
-  glob?: string[];
-  /** 是否区分大小写，默认不区分。 */
-  case_sensitive?: boolean;
-  /** 是否按字面量搜索；设为 false 时把 query 作为 ripgrep 正则表达式。 */
-  literal?: boolean;
-  /** 本次最多返回的匹配数量，默认 200，最大 2000。 */
-  max_results?: number;
-}
-
-/** find 工具输入。 */
-export interface FindToolInput {
-  /** 用于发现文件的 POSIX glob 模式。 */
-  pattern: string;
-  /** 开始匹配的项目内目录，默认为项目根目录。 */
-  path?: string;
-  /** 本次最多返回的文件数量，默认 200，最大 2000。 */
-  max_results?: number;
-}
-
-/** grep 返回的单项内容匹配。 */
-export interface GrepToolMatch {
-  /** 匹配文件相对于项目根目录的 POSIX 路径。 */
-  file_path: string;
-  /** 匹配所在的 1-based 行号。 */
-  line_number: number;
-  /** 匹配起始位置的 1-based UTF-8 字节列号。 */
-  column: number;
-  /** 匹配所在行的文本预览，不包含行尾换行符。 */
-  text: string;
-  /** 当前子匹配命中的原始文本。 */
-  match_text: string;
-  /** 行文本是否因为输出限制而被截断。 */
-  line_truncated: boolean;
-}
-
-/** 搜索工具统一失败结果。 */
-export interface SearchToolFailure {
-  /** 表示本次搜索失败。 */
-  success: false;
-  /** 供模型和调用方稳定解析的错误码。 */
-  error_code: SearchToolErrorCode;
-  /** 面向模型和日志的人类可读错误信息。 */
-  message: string;
-  /** 已完成解析时的搜索绝对路径。 */
-  search_path?: string;
-}
-
-/** grep 工具成功结果。 */
-export interface GrepToolSuccess {
-  /** 表示本次内容搜索成功。 */
-  success: true;
-  /** Shell 当前约束的项目根目录绝对路径。 */
-  root_path: string;
-  /** 实际执行搜索的绝对路径。 */
-  search_path: string;
-  /** 本次传给 ripgrep 的查询文本。 */
-  query: string;
-  /** 按 ripgrep 输出顺序返回的内容匹配。 */
-  matches: GrepToolMatch[];
-  /** ripgrep 实际开始搜索的文件数量。 */
-  files_searched: number;
-  /** 本次结果中返回的匹配数量。 */
-  match_count: number;
-  /** 是否因为 max_results 限制而省略了后续匹配。 */
-  truncated: boolean;
-}
-
-/** find 工具成功结果。 */
-export interface FindToolSuccess {
-  /** 表示本次文件发现成功。 */
-  success: true;
-  /** Shell 当前约束的项目根目录绝对路径。 */
-  root_path: string;
-  /** 实际开始 glob 匹配的绝对目录。 */
-  search_path: string;
-  /** 本次执行的 glob 模式。 */
-  pattern: string;
-  /** 排序后返回的项目相对 POSIX 文件路径。 */
-  files: string[];
-  /** 本次结果中返回的文件数量。 */
-  match_count: number;
-  /** 是否因为 max_results 限制而省略了后续文件。 */
-  truncated: boolean;
-}
-
-/** grep 工具结果。 */
-export type GrepToolResult = GrepToolSuccess | SearchToolFailure;
-
-/** find 工具结果。 */
-export type FindToolResult = FindToolSuccess | SearchToolFailure;
-
-/** 搜索 action 的判别式请求。 */
-export type SearchToolActionRequest = (
-  | {
-      /** 指定执行内容搜索。 */
-      action: "grep";
-      /** grep 工具输入。 */
-      input: GrepToolInput;
-    }
-  | {
-      /** 指定执行文件发现。 */
-      action: "find";
-      /** find 工具输入。 */
-      input: FindToolInput;
-    }
-) & {
-  /** AI SDK 传入的单次工具调用中止信号。 */
-  abort_signal?: AbortSignal;
-};
-
-/** 搜索 action 的统一结果。 */
-export type SearchToolActionResult = GrepToolResult | FindToolResult;
-
-/** 搜索工具运行器协议。 */
-export interface SearchToolRunner {
-  /** 执行一个独立的搜索 action。 */
-  run_search_action(request: SearchToolActionRequest): Promise<SearchToolActionResult>;
-}
-
-/** `@downcity/shell` 对模型暴露的项目搜索工具集合。 */
-export interface SearchToolSet {
-  /** 通过 ripgrep 搜索项目文件内容。 */
-  grep: Tool;
-  /** 通过 glob 模式发现项目文件。 */
-  find: Tool;
-}

package/src/types/workspace/Workspace.ts

@@ -1,27 +0,0 @@
-/**
- * Workspace 公共类型。
- *
- * 关键点（中文）
- * - Workspace 是统一资源容器，同时提供 Store、Tool 与可选 Shell。
- * - 所有平台共用同一类型，平台差异由可选 Shell 的 Sandbox Adapter 处理。
- */
-
-import type { Shell } from "@downcity/shell";
-
-/** Workspace 构造参数。 */
-export interface WorkspaceOptions {
-  /** Workspace 绑定的本地项目目录；构造时会解析为真实绝对路径。 */
-  path: string;
-
-  /** Workspace 内可选的受控命令执行能力。 */
-  shell?: Shell;
-
-  /**
-   * Workspace 的显式环境变量覆盖项。
-   *
-   * 关键点（中文）
-   * - 显式值覆盖 Workspace 根目录 `.env` 中的同名字段。
-   * - 最终环境变量由 Workspace 持有，不会写回 `process.env` 或 `.env`。
-   */
-  env?: Record<string, string | undefined>;
-}

package/src/types/workspace/WorkspaceEnv.ts

@@ -1,19 +0,0 @@
-/**
- * Workspace 环境变量公共类型。
- *
- * 关键点（中文）
- * - Env 属于项目执行环境，由 Workspace 持有。
- * - Agent 只订阅 Env 变化并在 Session Step 检查点同步。
- */
-
-/** Workspace 环境变量的运行时修改输入。 */
-export type WorkspaceEnvPatch = Record<string, string | null | undefined>;
-
-/** Workspace 环境变量变化订阅器。 */
-export type WorkspaceEnvSubscriber = (
-  /** 本次修改完成后的完整环境变量快照。 */
-  env: Readonly<Record<string, string>>,
-) => void;
-
-/** 取消 Workspace 环境变量订阅的函数。 */
-export type WorkspaceEnvUnsubscribe = () => void;

package/src/types/workspace/WorkspaceTools.ts

@@ -1,23 +0,0 @@
-/**
- * Workspace 工具集合类型。
- *
- * 关键点（中文）
- * - 只包含对当前 Workspace 文件、搜索和可选 Shell 的操作。
- * - Plugin Tool 与调用方自定义 Tool 不属于本类型，由 Agent 统一注册。
- */
-
-import type { Tool } from "ai";
-import type { FileSystem } from "@/types/workspace/FileSystem.js";
-import type { Shell } from "@downcity/shell";
-
-/** 当前 Workspace 向 Agent 提供的模型工具集合。 */
-export type WorkspaceTools = Record<string, Tool>;
-
-/** Workspace Tools 构造参数。 */
-export interface CreateWorkspaceToolsOptions {
-  /** 当前 Workspace 唯一的 rooted 文件能力。 */
-  files: FileSystem;
-
-  /** 当前 Workspace 可选的命令与进程能力。 */
-  shell?: Shell;
-}

package/src/utils/cli/CliOutput.ts

@@ -1,128 +0,0 @@
-/**
- * CLI 输出工具。
- *
- * 关键点（中文）
- * - 统一支持 JSON / 文本输出。
- * - 保持 shell 调用与 AI 调用都可稳定解析。
- */
-import {
-  print_panel,
-  render_key_value_lines,
-  type StatusTone,
-} from "@/utils/cli/PrettyStatus.js";
-
-/**
- * 标准化输出结果。
- *
- * 输出策略（中文）
- * - 默认 JSON（便于脚本解析）。
- * - `asJson=false` 时输出可读文本。
- */
-export function print_result(params: {
-  asJson?: boolean;
-  success: boolean;
-  title: string;
-  payload: Record<string, unknown>;
-}): void {
-  const asJson = params.asJson !== false;
-  const payload = {
-    success: params.success,
-    ...params.payload,
-  };
-
-  if (asJson) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-
-  const entries = Object.entries(payload).filter(
-    ([key, value]) => key !== "success" && value !== undefined,
-  );
-  const lines = renderObject(entries, 0);
-  const tone: StatusTone = params.success ? "success" : "error";
-  print_panel({
-    title: params.title,
-    tone,
-    lines: lines.length > 0 ? lines : ["  no details"],
-  });
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function renderScalar(
-  key: string,
-  value: string | number | boolean | null,
-  indent: number,
-): string[] {
-  return render_key_value_lines(
-    [[key, value === null ? "null" : String(value)]],
-    indent,
-  );
-}
-
-function renderArray(
-  key: string,
-  value: unknown[],
-  indent: number,
-): string[] {
-  const lines: string[] = [];
-  const [header] = render_key_value_lines([[key, value.length === 0 ? "[]" : ""]], indent);
-  if (header) lines.push(header);
-  if (value.length === 0) {
-    return lines;
-  }
-
-  for (const [index, item] of value.entries()) {
-    if (isPlainObject(item)) {
-      lines.push(`${" ".repeat(indent + 2)}- [${index + 1}]`);
-      lines.push(...renderObject(Object.entries(item), indent + 4));
-      continue;
-    }
-    if (Array.isArray(item)) {
-      lines.push(`${" ".repeat(indent + 2)}- [${index + 1}] (array)`);
-      lines.push(...renderArray("items", item, indent + 4));
-      continue;
-    }
-    lines.push(`${" ".repeat(indent + 2)}- [${index + 1}] ${String(item)}`);
-  }
-  return lines;
-}
-
-function renderObject(entries: Array<[string, unknown]>, indent: number): string[] {
-  if (entries.length === 0) return [];
-  const ordered = [...entries].sort((a, b) => {
-    if (a[0] === "error") return 1;
-    if (b[0] === "error") return -1;
-    return a[0].localeCompare(b[0]);
-  });
-  const lines: string[] = [];
-
-  for (const [key, value] of ordered) {
-    if (
-      value === null ||
-      typeof value === "string" ||
-      typeof value === "number" ||
-      typeof value === "boolean"
-    ) {
-      lines.push(...renderScalar(key, value, indent));
-      continue;
-    }
-
-    if (Array.isArray(value)) {
-      lines.push(...renderArray(key, value, indent));
-      continue;
-    }
-
-    if (isPlainObject(value)) {
-      const [header] = render_key_value_lines([[key, ""]], indent);
-      if (header) lines.push(header);
-      lines.push(...renderObject(Object.entries(value), indent + 2));
-      continue;
-    }
-
-    lines.push(...renderScalar(key, String(value), indent));
-  }
-  return lines;
-}

package/src/utils/cli/PrettyStatus.ts

@@ -1,94 +0,0 @@
-/**
- * 终端状态渲染工具。
- *
- * 设计目标（中文）
- * - 为 status 类命令提供统一、可读性更强的“面板化”输出。
- * - 保持零依赖：不引入第三方库，直接使用 ANSI 转义序列。
- * - 在非 TTY 或 NO_COLOR 场景自动降级为无色输出。
- */
-
-export type StatusTone = "success" | "error" | "warning" | "info" | "neutral";
-
-const ANSI = {
-  reset: "\u001b[0m",
-  bold: "\u001b[1m",
-  dim: "\u001b[2m",
-  fgGreen: "\u001b[32m",
-  fgRed: "\u001b[31m",
-  fgYellow: "\u001b[33m",
-  fgCyan: "\u001b[36m",
-  fgGray: "\u001b[90m",
-};
-
-function colorEnabled(): boolean {
-  return Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
-}
-
-function paint(input: string, code: string): string {
-  if (!colorEnabled()) return input;
-  return `${code}${input}${ANSI.reset}`;
-}
-
-export function tone_tag(tone: StatusTone): string {
-  if (tone === "success") return paint("OK", ANSI.fgGreen);
-  if (tone === "error") return paint("ERR", ANSI.fgRed);
-  if (tone === "warning") return paint("WARN", ANSI.fgYellow);
-  if (tone === "info") return paint("INFO", ANSI.fgCyan);
-  return paint("STATE", ANSI.fgGray);
-}
-
-export function dim(input: string): string {
-  return paint(input, ANSI.dim);
-}
-
-export function bold(input: string): string {
-  return paint(input, ANSI.bold);
-}
-
-/**
- * 打印面板。
- */
-export function print_panel(params: {
-  title: string;
-  tone?: StatusTone;
-  lines: string[];
-}): void {
-  const tone = params.tone || "neutral";
-  const title = `${tone_tag(tone)} ${bold(params.title)}`;
-  const contentLines = [title, ...params.lines];
-
-  const maxLineLength = Math.max(
-    24,
-    ...contentLines.map((line) => stripAnsi(line).length),
-  );
-  const border = "─".repeat(maxLineLength + 2);
-
-  console.log(`┌${border}┐`);
-  for (const line of contentLines) {
-    const plain = stripAnsi(line).length;
-    const pad = " ".repeat(Math.max(0, maxLineLength - plain));
-    console.log(`│ ${line}${pad} │`);
-  }
-  console.log(`└${border}┘`);
-}
-
-/**
- * 渲染对齐字段行。
- */
-export function render_key_value_lines(
-  entries: Array<[string, string]>,
-  indent: number = 2,
-): string[] {
-  if (entries.length === 0) return [];
-  const keyWidth = Math.max(...entries.map(([key]) => key.length), 8);
-  const pad = " ".repeat(Math.max(0, indent));
-  return entries.map(([key, value]) => {
-    const left = `${pad}${dim(key.padEnd(keyWidth, " "))}`;
-    return `${left} : ${value}`;
-  });
-}
-
-function stripAnsi(input: string): string {
-  return input.replace(/\u001b\[[0-9;]*m/g, "");
-}
-