@downcity/agent 1.1.287 → 1.1.310

package/src/types/workspace/SearchTool.ts

@@ -0,0 +1,156 @@
+/**
+ * 项目搜索工具公开类型。
+ *
+ * 关键点（中文）
+ * - `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

@@ -0,0 +1,27 @@
+/**
+ * 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

@@ -0,0 +1,19 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+/**
+ * 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/Id.ts

@@ -8,6 +8,6 @@
 
 import { nanoid } from "nanoid";
 
-export function generateId(): string {
+export function generate_id(): string {
   return nanoid(16);
 }

package/src/utils/Template.ts

@@ -15,7 +15,7 @@ import type { TemplateVariableMap } from "@/types/common/Template.js";
  * - 变量名支持字母、数字、下划线，且允许写成 `{{ key }}`。
  * - 未提供值的变量保持原样，便于排查模板与变量映射不一致问题。
  */
-export function renderTemplateVariables(
+export function render_template_variables(
   template: string,
   variables: TemplateVariableMap,
 ): string {

package/src/utils/Time.ts

@@ -6,18 +6,18 @@
  * 2. 提供耗时格式化，便于日志和 CLI 输出使用一致单位。
  * 3. 提供 runtime 时区格式化，确保 prompt / message / task 共享同一时间口径。
  */
-export function getTimestamp(): string {
+export function get_timestamp(): string {
   return new Date().toISOString();
 }
 
-export function resolveRuntimeTimezone(): string {
+export function resolve_runtime_timezone(): string {
   const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
   return String(timezone || "").trim() || "UTC";
 }
 
-export function formatDateInTimezone(
+export function format_date_in_timezone(
   date: Date = new Date(),
-  timezone: string = resolveRuntimeTimezone(),
+  timezone: string = resolve_runtime_timezone(),
 ): string {
   try {
     // 关键点（中文）：sv-SE locale 默认输出 ISO 风格日期，便于模型稳定解析。
@@ -32,9 +32,9 @@ export function formatDateInTimezone(
   }
 }
 
-export function formatDateTimeInTimezone(
+export function format_date_time_in_timezone(
   date: Date = new Date(),
-  timezone: string = resolveRuntimeTimezone(),
+  timezone: string = resolve_runtime_timezone(),
 ): string {
   try {
     // 关键点（中文）：使用固定格式，确保模型读取时区信息时稳定。
@@ -56,9 +56,9 @@ export function formatDateTimeInTimezone(
   }
 }
 
-export function formatYearInTimezone(
+export function format_year_in_timezone(
   date: Date = new Date(),
-  timezone: string = resolveRuntimeTimezone(),
+  timezone: string = resolve_runtime_timezone(),
 ): string {
   try {
     return new Intl.DateTimeFormat("en-US", {

package/src/utils/cli/CliOutput.ts

@@ -6,8 +6,8 @@
  * - 保持 shell 调用与 AI 调用都可稳定解析。
  */
 import {
-  printPanel,
-  renderKeyValueLines,
+  print_panel,
+  render_key_value_lines,
   type StatusTone,
 } from "@/utils/cli/PrettyStatus.js";
 
@@ -18,7 +18,7 @@ import {
  * - 默认 JSON（便于脚本解析）。
  * - `asJson=false` 时输出可读文本。
  */
-export function printResult(params: {
+export function print_result(params: {
   asJson?: boolean;
   success: boolean;
   title: string;
@@ -40,7 +40,7 @@ export function printResult(params: {
   );
   const lines = renderObject(entries, 0);
   const tone: StatusTone = params.success ? "success" : "error";
-  printPanel({
+  print_panel({
     title: params.title,
     tone,
     lines: lines.length > 0 ? lines : ["  no details"],
@@ -56,7 +56,7 @@ function renderScalar(
   value: string | number | boolean | null,
   indent: number,
 ): string[] {
-  return renderKeyValueLines(
+  return render_key_value_lines(
     [[key, value === null ? "null" : String(value)]],
     indent,
   );
@@ -68,7 +68,7 @@ function renderArray(
   indent: number,
 ): string[] {
   const lines: string[] = [];
-  const [header] = renderKeyValueLines([[key, value.length === 0 ? "[]" : ""]], indent);
+  const [header] = render_key_value_lines([[key, value.length === 0 ? "[]" : ""]], indent);
   if (header) lines.push(header);
   if (value.length === 0) {
     return lines;
@@ -116,7 +116,7 @@ function renderObject(entries: Array<[string, unknown]>, indent: number): string
     }
 
     if (isPlainObject(value)) {
-      const [header] = renderKeyValueLines([[key, ""]], indent);
+      const [header] = render_key_value_lines([[key, ""]], indent);
       if (header) lines.push(header);
       lines.push(...renderObject(Object.entries(value), indent + 2));
       continue;

package/src/utils/cli/PrettyStatus.ts

@@ -29,7 +29,7 @@ function paint(input: string, code: string): string {
   return `${code}${input}${ANSI.reset}`;
 }
 
-export function toneTag(tone: StatusTone): string {
+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);
@@ -48,13 +48,13 @@ export function bold(input: string): string {
 /**
  * 打印面板。
  */
-export function printPanel(params: {
+export function print_panel(params: {
   title: string;
   tone?: StatusTone;
   lines: string[];
 }): void {
   const tone = params.tone || "neutral";
-  const title = `${toneTag(tone)} ${bold(params.title)}`;
+  const title = `${tone_tag(tone)} ${bold(params.title)}`;
   const contentLines = [title, ...params.lines];
 
   const maxLineLength = Math.max(
@@ -75,7 +75,7 @@ export function printPanel(params: {
 /**
  * 渲染对齐字段行。
  */
-export function renderKeyValueLines(
+export function render_key_value_lines(
   entries: Array<[string, string]>,
   indent: number = 2,
 ): string[] {