@downcity/agent 1.1.287 → 1.1.310

package/src/workspace/store/LocalStorePaths.ts

@@ -0,0 +1,209 @@
+/**
+ * Workspace LocalAgentStore 的 Session 路径规则。
+ *
+ * 关键点（中文）
+ * - 所有 agent session 统一落盘到 `.downcity/agents/<agent_id>/sessions/<session_id>/...`。
+ * - `agent_id` 是唯一隔离维度，不再保留第二套旧 session 根目录。
+ */
+
+import path from "node:path";
+
+/**
+ * `.downcity` 根目录路径。
+ */
+export function get_sdk_downcity_dir_path(workspace_path: string): string {
+  return path.join(workspace_path, ".downcity");
+}
+
+/**
+ * SDK agents 根目录路径。
+ */
+export function get_sdk_agents_root_dir_path(workspace_path: string): string {
+  return path.join(get_sdk_downcity_dir_path(workspace_path), "agents");
+}
+
+/**
+ * 单个 agent 根目录路径。
+ */
+export function get_sdk_agent_dir_path(
+  workspace_path: string,
+  agent_id: string,
+): string {
+  return path.join(
+    get_sdk_agents_root_dir_path(workspace_path),
+    encodeURIComponent(String(agent_id || "").trim()),
+  );
+}
+
+/**
+ * 单个 agent 的 sessions 根目录路径。
+ */
+export function get_sdk_agent_sessions_root_dir_path(
+  workspace_path: string,
+  agent_id: string,
+): string {
+  return path.join(get_sdk_agent_dir_path(workspace_path, agent_id), "sessions");
+}
+
+/**
+ * 单个 agent 的已归档 sessions 根目录路径。
+ *
+ * 关键点（中文）
+ * - `archive_session` 会把整个 session 目录从 `sessions/<session_id>` 移动到此处。
+ * - `clean_archive` 会永久删除该目录下的全部内容。
+ */
+export function get_sdk_agent_archived_sessions_dir_path(
+  workspace_path: string,
+  agent_id: string,
+): string {
+  return path.join(get_sdk_agent_dir_path(workspace_path, agent_id), "archived-sessions");
+}
+
+/**
+ * 单个已归档 session 的根目录路径。
+ */
+export function get_sdk_agent_archived_session_dir_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_archived_sessions_dir_path(workspace_path, agent_id),
+    encodeURIComponent(String(session_id || "").trim()),
+  );
+}
+
+/**
+ * 单个已归档 session 的消息目录路径。
+ */
+export function get_sdk_agent_archived_session_messages_dir_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_archived_session_dir_path(workspace_path, agent_id, session_id),
+    "messages",
+  );
+}
+
+/**
+ * 单个已归档 session 的 Active JSONL 文件路径。
+ */
+export function get_sdk_agent_archived_session_messages_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_archived_session_messages_dir_path(workspace_path, agent_id, session_id),
+    "active.jsonl",
+  );
+}
+
+/**
+ * 单个已归档 session 的 meta.json 路径。
+ */
+export function get_sdk_agent_archived_session_meta_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_archived_session_messages_dir_path(workspace_path, agent_id, session_id),
+    "meta.json",
+  );
+}
+
+/**
+ * 单个 session 根目录路径。
+ */
+export function get_sdk_agent_session_dir_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_sessions_root_dir_path(workspace_path, agent_id),
+    encodeURIComponent(String(session_id || "").trim()),
+  );
+}
+
+/**
+ * 单个 session 显式固化完整 system 的 instruction.md 路径。
+ *
+ * 关键点（中文）
+ * - 文件不存在表示 Session 恢复时继续采用 Agent 当前 instruction。
+ * - 空文件表示调用方显式固化了空 system。
+ */
+export function get_sdk_agent_session_instruction_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
+    "instruction.md",
+  );
+}
+
+/**
+ * 单个 session 的消息目录路径。
+ */
+export function get_sdk_agent_session_messages_dir_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_dir_path(workspace_path, agent_id, session_id),
+    "messages",
+  );
+}
+
+/**
+ * 单个 session 的 Active JSONL 文件路径。
+ */
+export function get_sdk_agent_session_messages_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
+    "active.jsonl",
+  );
+}
+
+/**
+ * 单个 session 的 meta.json 路径。
+ */
+export function get_sdk_agent_session_meta_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
+    "meta.json",
+  );
+}
+
+/**
+ * 单个 session 的 inflight assistant 路径。
+ *
+ * 关键点（中文）
+ * - 运行中的 assistant 只保留一份增量快照。
+ * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
+ * - 完成后再把最终 assistant 合并进 `active.jsonl`，并清理该文件。
+ */
+export function get_sdk_agent_session_assistant_message_path(
+  workspace_path: string,
+  agent_id: string,
+  session_id: string,
+): string {
+  return path.join(
+    get_sdk_agent_session_messages_dir_path(workspace_path, agent_id, session_id),
+    "assistant_message.json",
+  );
+}

package/src/workspace/store/SessionMessageStoreFactory.ts

@@ -0,0 +1,18 @@
+/**
+ * Workspace Session Message Store 工厂。
+ *
+ * 关键点（中文）
+ * - 跨 package 调用方只依赖 SessionMessageStore contract，不依赖 JSONL 实现类。
+ * - 物理格式由 @downcity/agent 内部选择，后续替换实现不会扩散到 Plugin。
+ */
+
+import { JsonlSessionMessageStore } from "@/workspace/store/JsonlSessionMessageStore.js";
+import type { JsonlSessionMessageStoreOptions } from "@/types/store/LocalStore.js";
+import type { SessionMessageStore } from "@/types/store/SessionStore.js";
+
+/** 创建当前默认的本地 Session Message Store。 */
+export function create_session_message_store(
+  options: JsonlSessionMessageStoreOptions,
+): SessionMessageStore {
+  return new JsonlSessionMessageStore(options);
+}

package/src/workspace/tool/FileToolSchemas.ts

@@ -0,0 +1,77 @@
+/**
+ * 文件工具输入 schema。
+ *
+ * 关键点（中文）
+ * - schema 只描述模型可调用协议，不混入路径与文件系统逻辑。
+ * - 参数名统一采用 snake_case，与现有 Shell tools 保持一致。
+ */
+
+import { z } from "zod";
+
+/** read 工具输入 schema。 */
+export const read_file_tool_input_schema = z.object({
+  file_path: z
+    .string()
+    .min(1)
+    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .default(0)
+    .describe("Zero-based line offset. Defaults to 0."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(2000)
+    .optional()
+    .default(500)
+    .describe("Maximum lines to return. Defaults to 500 and cannot exceed 2000."),
+});
+
+/** write 工具输入 schema。 */
+export const write_file_tool_input_schema = z.object({
+  file_path: z
+    .string()
+    .min(1)
+    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
+  content: z.string().describe("Complete UTF-8 text content to write."),
+  overwrite: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Whether an existing file may be atomically replaced. Defaults to false."),
+});
+
+/** 单项 edit 输入 schema。 */
+export const file_edit_operation_schema = z.object({
+  old_text: z
+    .string()
+    .min(1)
+    .max(10000)
+    .describe("Exact text that must occur exactly once in the original file."),
+  new_text: z
+    .string()
+    .max(50000)
+    .describe("Replacement text for the unique old_text match."),
+});
+
+/** edit 工具输入 schema。 */
+export const edit_file_tool_input_schema = z.object({
+  file_path: z
+    .string()
+    .min(1)
+    .describe("Project-relative or absolute file path. Paths outside the project root are rejected."),
+  edits: z
+    .array(file_edit_operation_schema)
+    .min(1)
+    .max(10)
+    .describe("One to ten non-overlapping exact replacements applied atomically."),
+  expected_sha256: z
+    .string()
+    .regex(/^[a-fA-F0-9]{64}$/)
+    .optional()
+    .describe("Optional SHA-256 returned by read. The edit is rejected if the file changed."),
+});

package/src/workspace/tool/FileTools.ts

@@ -0,0 +1,91 @@
+/**
+ * 文件 AI SDK tools。
+ *
+ * 关键点（中文）
+ * - 模型看到独立的 read/write/edit 工具，不需要构造 shell 命令。
+ * - 工具只负责 schema 与 action 转发，文件语义由 FileActionRuntime 统一实现。
+ */
+
+import path from "node:path";
+import { tool } from "ai";
+import type { ActionResult } from "@/types/action/ActionResult.js";
+import type {
+  EditFileToolInput,
+  EditFileToolResult,
+  FileToolRunner,
+  FileToolSet,
+  ReadFileToolInput,
+  ReadFileToolResult,
+  WriteFileToolInput,
+  WriteFileToolResult,
+} from "@/types/workspace/FileTool.js";
+import {
+  edit_file_tool_input_schema,
+  read_file_tool_input_schema,
+  write_file_tool_input_schema,
+} from "@/workspace/tool/FileToolSchemas.js";
+
+/** 创建 Workspace 持有的结构化文件工具。 */
+export function create_file_tools(runner: FileToolRunner): FileToolSet {
+  const read = tool({
+    description:
+      "Read a project file instead of using cat or sed. Images and PDFs are attached to the next model step as local file parts. Text output is limited to 500 lines and 256KB by default; use offset and limit to continue. Other binary files return metadata only.",
+    inputSchema: read_file_tool_input_schema,
+    execute: async (
+      input: ReadFileToolInput,
+    ): Promise<ActionResult<ReadFileToolResult>> => {
+      const output = await runner.run_file_action({
+        action: "read",
+        input,
+      }) as ReadFileToolResult;
+      const messages: ActionResult<ReadFileToolResult>["messages"] = [];
+      if (
+        output.success &&
+        (output.type === "image" || output.mime_type === "application/pdf")
+      ) {
+        messages.push({
+          role: "user",
+          parts: [{
+            type: "file",
+            url: output.file_path,
+            mediaType: output.mime_type || "application/octet-stream",
+            filename: path.basename(output.file_path),
+          }],
+        });
+      }
+      return { output, messages };
+    },
+  });
+
+  const write = tool({
+    description:
+      "Create a new UTF-8 text file or atomically replace an existing file when overwrite=true. Parent directories are created automatically. Use edit for partial changes.",
+    inputSchema: write_file_tool_input_schema,
+    execute: async (
+      input: WriteFileToolInput,
+    ): Promise<ActionResult<WriteFileToolResult>> => {
+      const output = await runner.run_file_action({
+        action: "write",
+        input,
+      }) as WriteFileToolResult;
+      return { output, messages: [] };
+    },
+  });
+
+  const edit = tool({
+    description:
+      "Atomically edit one text file using exact replacements. Every edits[].old_text must match exactly once in the original file, and edit regions must not overlap. Combine separate changes to one file in a single call.",
+    inputSchema: edit_file_tool_input_schema,
+    execute: async (
+      input: EditFileToolInput,
+    ): Promise<ActionResult<EditFileToolResult>> => {
+      const output = await runner.run_file_action({
+        action: "edit",
+        input,
+      }) as EditFileToolResult;
+      return { output, messages: [] };
+    },
+  });
+
+  return { read, write, edit };
+}

package/src/workspace/tool/SearchToolSchemas.ts

@@ -0,0 +1,62 @@
+/**
+ * 搜索工具输入 schema。
+ *
+ * 关键点（中文）
+ * - schema 只描述模型可调用协议，路径校验与搜索逻辑由运行时负责。
+ * - 参数名统一采用 snake_case，与其他 Shell tools 保持一致。
+ */
+
+import { z } from "zod";
+
+/** grep 工具输入 schema。 */
+export const grep_tool_input_schema = z.object({
+  query: z.string().min(1).describe("Literal text or ripgrep regular expression to search for."),
+  path: z
+    .string()
+    .min(1)
+    .optional()
+    .default(".")
+    .describe("Project-relative or absolute file/directory path. Defaults to the project root."),
+  glob: z
+    .array(z.string().min(1))
+    .max(20)
+    .optional()
+    .describe("Optional ripgrep glob patterns used to include or exclude candidate files."),
+  case_sensitive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Whether matching is case-sensitive. Defaults to false."),
+  literal: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Treat query as literal text. Set false to use ripgrep regular expressions."),
+  max_results: z
+    .number()
+    .int()
+    .min(1)
+    .max(2000)
+    .optional()
+    .default(200)
+    .describe("Maximum matches to return. Defaults to 200 and cannot exceed 2000."),
+});
+
+/** find 工具输入 schema。 */
+export const find_tool_input_schema = z.object({
+  pattern: z.string().min(1).describe("POSIX glob pattern used to discover files."),
+  path: z
+    .string()
+    .min(1)
+    .optional()
+    .default(".")
+    .describe("Project-relative or absolute directory to search. Defaults to the project root."),
+  max_results: z
+    .number()
+    .int()
+    .min(1)
+    .max(2000)
+    .optional()
+    .default(200)
+    .describe("Maximum files to return. Defaults to 200 and cannot exceed 2000."),
+});

package/src/workspace/tool/SearchTools.ts

@@ -0,0 +1,61 @@
+/**
+ * 项目搜索 AI SDK tools。
+ *
+ * 关键点（中文）
+ * - 模型通过独立的 `grep` / `find` 工具搜索内容和发现文件。
+ * - 工具只负责 schema、abort signal 与 action 转发，搜索语义由运行时实现。
+ */
+
+import { tool, type ToolExecutionOptions } from "ai";
+import type { ActionResult } from "@/types/action/ActionResult.js";
+import type {
+  FindToolInput,
+  FindToolResult,
+  GrepToolInput,
+  GrepToolResult,
+  SearchToolRunner,
+  SearchToolSet,
+} from "@/types/workspace/SearchTool.js";
+import {
+  find_tool_input_schema,
+  grep_tool_input_schema,
+} from "@/workspace/tool/SearchToolSchemas.js";
+
+/** 创建 Workspace 持有的结构化搜索工具。 */
+export function create_search_tools(runner: SearchToolRunner): SearchToolSet {
+  const grep = tool({
+    description:
+      "Search project file contents with ripgrep instead of running rg through the shell. Returns structured file, line, column, and matched text data; respects ignore files by default.",
+    inputSchema: grep_tool_input_schema,
+    execute: async (
+      input: GrepToolInput,
+      options: ToolExecutionOptions,
+    ): Promise<ActionResult<GrepToolResult>> => {
+      const output = await runner.run_search_action({
+        action: "grep",
+        input,
+        abort_signal: options.abortSignal,
+      }) as GrepToolResult;
+      return { output, messages: [] };
+    },
+  });
+
+  const find = tool({
+    description:
+      "Find project files with a POSIX glob pattern instead of running shell find. Respects .gitignore, includes dotfiles, and does not follow symbolic links.",
+    inputSchema: find_tool_input_schema,
+    execute: async (
+      input: FindToolInput,
+      options: ToolExecutionOptions,
+    ): Promise<ActionResult<FindToolResult>> => {
+      const output = await runner.run_search_action({
+        action: "find",
+        input,
+        abort_signal: options.abortSignal,
+      }) as FindToolResult;
+      return { output, messages: [] };
+    },
+  });
+
+  return { grep, find };
+}

package/src/workspace/tool/WorkspaceTools.ts

@@ -0,0 +1,31 @@
+/**
+ * Workspace Tools 组合模块。
+ *
+ * 职责说明（中文）
+ * - 统一创建当前 Workspace 的文件、搜索与可选 Shell 工具。
+ * - 这里只组合 Workspace 资源，不注册 Plugin Tool 或调用方自定义 Tool。
+ */
+
+import { create_file_tools } from "@/workspace/tool/FileTools.js";
+import { create_search_tools } from "@/workspace/tool/SearchTools.js";
+import type {
+  CreateWorkspaceToolsOptions,
+  WorkspaceTools,
+} from "@/types/workspace/WorkspaceTools.js";
+
+/** 创建当前 Workspace 的完整模型工具集合。 */
+export function create_workspace_tools(
+  options: CreateWorkspaceToolsOptions,
+): WorkspaceTools {
+  return {
+    ...create_file_tools({
+      run_file_action: async (request) =>
+        await options.files.run_file_action(request),
+    }),
+    ...create_search_tools({
+      run_search_action: async (request) =>
+        await options.files.run_search_action(request),
+    }),
+    ...(options.shell?.tools || {}),
+  };
+}