@downcity/plugins 1.0.4

package/src/shell/ShellPlugin.ts

@@ -0,0 +1,199 @@
+/**
+ * ShellPlugin：shell plugin 的类实现。
+ *
+ * 关键点（中文）
+ * - shell session map 与 bound runtime 都归属于 plugin 实例。
+ * - agent 持有 ShellPlugin 实例，从而形成 per-agent shell 状态边界。
+ * - ShellActionRuntime 只保留纯运行时流程，不再承载模块级单例状态。
+ */
+
+import type { AgentRuntime } from "@downcity/agent/internal/types/runtime/agent/AgentRuntime.js";
+import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
+import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ShellPluginState,
+  ShellSessionRuntimeState,
+} from "@/shell/ShellRuntimeTypes.js";
+import type {
+  ShellCloseRequest,
+  ShellExecRequest,
+  ShellQueryRequest,
+  ShellReadRequest,
+  ShellStartRequest,
+  ShellWaitRequest,
+  ShellWriteRequest,
+} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+import {
+  bindShellRuntime,
+  closeAllShellSessions,
+  closeShellSession,
+  createShellPluginState,
+  execShellCommand,
+  getShellSessionStatus,
+  readShellSession,
+  startShellSession,
+  waitShellSession,
+  writeShellSession,
+} from "./runtime/ShellActionRuntime.js";
+
+/**
+ * Shell plugin 类实现。
+ */
+export class ShellPlugin extends BasePlugin {
+  /**
+   * plugin 名称。
+   */
+  readonly name = "shell";
+
+  /**
+   * 当前实例持有的 shell 状态对象。
+   */
+  private readonly state: ShellPluginState;
+
+  /**
+   * 当前实例暴露的 action 定义表。
+   */
+  readonly actions: PluginActions;
+
+  /**
+   * 当前实例持有的 in-memory shell sessions。
+   */
+  public readonly sessions: Map<string, ShellSessionRuntimeState>;
+
+  constructor(agent: AgentRuntime | null) {
+    super(agent);
+    this.state = createShellPluginState();
+    this.sessions = this.state.sessions;
+    this.actions = {
+      exec: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.exec(params.context, params.payload as ShellExecRequest),
+        }),
+      },
+      start: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.start(params.context, params.payload as ShellStartRequest),
+        }),
+      },
+      status: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.status(params.context, params.payload as ShellQueryRequest),
+        }),
+      },
+      read: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.read(params.context, params.payload as ShellReadRequest),
+        }),
+      },
+      write: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.write(params.context, params.payload as ShellWriteRequest),
+        }),
+      },
+      wait: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.wait(params.context, params.payload as ShellWaitRequest),
+        }),
+      },
+      close: {
+        execute: async (params) => ({
+          success: true,
+          data: await this.close(params.context, params.payload as ShellCloseRequest),
+        }),
+      },
+    };
+
+    this.lifecycle = {
+      start: async (context) => {
+        bindShellRuntime(this.state, context);
+      },
+      stop: async () => {
+        await closeAllShellSessions(this.state, true);
+        for (const session of this.state.sessions.values()) {
+          if (session.cleanupTimer) {
+            clearTimeout(session.cleanupTimer);
+          }
+        }
+        this.state.sessions.clear();
+        this.state.boundRuntime = null;
+      },
+    };
+  }
+
+  /**
+   * 启动一个 shell session。
+   */
+  async start(
+    context: AgentContext,
+    request: ShellStartRequest,
+  ) {
+    return await startShellSession(this.state, context, request);
+  }
+
+  /**
+   * 查询 shell session 状态。
+   */
+  async status(
+    context: AgentContext,
+    request: ShellQueryRequest,
+  ) {
+    return await getShellSessionStatus(this.state, context, request);
+  }
+
+  /**
+   * 读取 shell session 输出。
+   */
+  async read(
+    context: AgentContext,
+    request: ShellReadRequest,
+  ) {
+    return await readShellSession(this.state, context, request);
+  }
+
+  /**
+   * 向 shell session 写入 stdin。
+   */
+  async write(
+    context: AgentContext,
+    request: ShellWriteRequest,
+  ) {
+    return await writeShellSession(this.state, context, request);
+  }
+
+  /**
+   * 等待 shell session 状态变化。
+   */
+  async wait(
+    context: AgentContext,
+    request: ShellWaitRequest,
+  ) {
+    return await waitShellSession(this.state, context, request);
+  }
+
+  /**
+   * 关闭 shell session。
+   */
+  async close(
+    context: AgentContext,
+    request: ShellCloseRequest,
+  ) {
+    return await closeShellSession(this.state, context, request);
+  }
+
+  /**
+   * 执行一次 one-shot shell command。
+   */
+  async exec(
+    context: AgentContext,
+    request: ShellExecRequest,
+  ) {
+    return await execShellCommand(this.state, context, request);
+  }
+}

package/src/shell/ShellRuntimeTypes.ts

@@ -0,0 +1,94 @@
+/**
+ * ShellRuntime 类型定义。
+ *
+ * 关键点（中文）
+ * - 这些类型描述 shell plugin runtime 的实例级运行态。
+ * - 状态所有权归属于 `ShellPlugin` 实例，而不是模块级单例。
+ * - 统一归档到 `src/shell/` 相邻层级，避免继续分散在跨域目录里。
+ */
+
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ShellSessionSnapshot } from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+
+/**
+ * 单个 shell wait 调用挂起时注册的 waiter。
+ */
+export type ShellSessionWaiter = {
+  /**
+   * 当前等待完成后的唤醒回调。
+   */
+  resolve: () => void;
+  /**
+   * 当前 waiter 对应的超时定时器。
+   */
+  timer: NodeJS.Timeout;
+};
+
+/**
+ * 单个 shell session 的内存运行态。
+ */
+export type ShellSessionRuntimeState = {
+  /**
+   * 当前 shell session 的对外快照。
+   */
+  snapshot: ShellSessionSnapshot;
+  /**
+   * 当前 shell session 对应的子进程句柄。
+   */
+  child: ChildProcessWithoutNullStreams;
+  /**
+   * 当前已缓存的标准输出与标准错误文本。
+   */
+  outputText: string;
+  /**
+   * 当前输出持久化文件路径。
+   */
+  outputFilePath: string;
+  /**
+   * 当前快照持久化文件路径。
+   */
+  snapshotFilePath: string;
+  /**
+   * 串行化文件写入链，避免并发 append 乱序。
+   */
+  writeChain: Promise<void>;
+  /**
+   * 终态后的延迟清理定时器。
+   */
+  cleanupTimer: NodeJS.Timeout | null;
+  /**
+   * 当前挂起等待该 session 状态变化的 waiter 集合。
+   */
+  waiters: Set<ShellSessionWaiter>;
+  /**
+   * 当前 shell 进入终态后的完成 promise。
+   *
+   * 关键点（中文）
+   * - 供 `shell.exec` 这类 one-shot 路径直接等待进程结束。
+   * - 这样可以减少对版本轮询的依赖，降低瞬时命令的竞态超时。
+   */
+  completionPromise: Promise<void>;
+  /**
+   * 当前 shell 进入终态时触发的完成回调。
+   */
+  resolveCompletion: () => void;
+};
+
+/**
+ * `ShellPlugin` 实例级状态。
+ */
+export type ShellPluginState = {
+  /**
+   * 当前实例持有的全部 in-memory shell session。
+   */
+  sessions: Map<string, ShellSessionRuntimeState>;
+  /**
+   * 当前实例最近一次绑定的 execution runtime。
+   *
+   * 关键点（中文）
+   * - 仅用于 shell 自动通知 chat 的回调路径。
+   * - 这是实例字段，不再是模块级全局变量。
+   */
+  boundRuntime: AgentContext | null;
+};

package/src/shell/runtime/Paths.ts

@@ -0,0 +1,28 @@
+/**
+ * Shell service 路径工具。
+ *
+ * 关键点（中文）
+ * - shell 运行产物统一落在 `.downcity/shell/<shellId>/`。
+ * - 目录结构简单稳定，便于调试与后续恢复。
+ */
+
+import path from "node:path";
+
+export function getShellRootDir(projectRoot: string): string {
+  return path.join(projectRoot, ".downcity", "shell");
+}
+
+export function getShellDir(projectRoot: string, shellId: string): string {
+  return path.join(getShellRootDir(projectRoot), String(shellId || "").trim());
+}
+
+export function getShellSnapshotPath(
+  projectRoot: string,
+  shellId: string,
+): string {
+  return path.join(getShellDir(projectRoot, shellId), "snapshot.json");
+}
+
+export function getShellOutputPath(projectRoot: string, shellId: string): string {
+  return path.join(getShellDir(projectRoot, shellId), "output.log");
+}

package/src/shell/runtime/ShellActionResponse.ts

@@ -0,0 +1,135 @@
+/**
+ * Shell action 返回结构辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理输出游标、token 近似裁剪与标准 action response。
+ * - 这里不读取文件、不修改 session，只基于传入文本构造返回对象。
+ */
+
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ShellActionResponse,
+  ShellOutputChunk,
+  ShellSessionSnapshot,
+} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+
+const DEFAULT_MAX_OUTPUT_CHARS = 12_000;
+const DEFAULT_MAX_OUTPUT_LINES = 200;
+const APPROX_CHARS_PER_TOKEN = 4;
+
+function resolveOutputLimits(params: {
+  context: AgentContext;
+  maxOutputTokens?: number;
+}): {
+  maxChars: number;
+  maxLines: number;
+} {
+  const byTokens =
+    typeof params.maxOutputTokens === "number" &&
+    Number.isFinite(params.maxOutputTokens) &&
+    params.maxOutputTokens > 0
+      ? Math.max(200, Math.floor(params.maxOutputTokens * APPROX_CHARS_PER_TOKEN))
+      : null;
+  return {
+    maxChars:
+      byTokens == null
+        ? DEFAULT_MAX_OUTPUT_CHARS
+        : Math.min(DEFAULT_MAX_OUTPUT_CHARS, byTokens),
+    maxLines: DEFAULT_MAX_OUTPUT_LINES,
+  };
+}
+
+function splitOutputByLimits(
+  text: string,
+  maxChars: number,
+  maxLines: number,
+): { head: string; tail: string } {
+  const limitedByChars = text.slice(0, Math.min(text.length, maxChars));
+  let head = limitedByChars;
+  if (maxLines > 0) {
+    const lines = limitedByChars.split("\n");
+    if (lines.length > maxLines) {
+      head = lines.slice(0, maxLines).join("\n");
+    }
+  }
+  return {
+    head,
+    tail: text.slice(head.length),
+  };
+}
+
+/**
+ * 根据游标与 token 限制构造输出块。
+ */
+export function createOutputChunk(params: {
+  /**
+   * 当前 shell session 标识。
+   */
+  shellId: string;
+  /**
+   * 当前完整输出文本。
+   */
+  outputText: string;
+  /**
+   * 本次读取起始游标。
+   */
+  fromCursor?: number;
+  /**
+   * 当前 Agent 执行上下文。
+   */
+  context: AgentContext;
+  /**
+   * 输出 token 近似上限。
+   */
+  maxOutputTokens?: number;
+}): ShellOutputChunk {
+  const fromCursor =
+    typeof params.fromCursor === "number" && params.fromCursor >= 0
+      ? Math.floor(params.fromCursor)
+      : 0;
+  const available = params.outputText.slice(fromCursor);
+  const originalChars = available.length;
+  const originalLines = available ? available.split("\n").length : 0;
+  const limits = resolveOutputLimits({
+    context: params.context,
+    maxOutputTokens: params.maxOutputTokens,
+  });
+  const { head, tail } = splitOutputByLimits(
+    available,
+    limits.maxChars,
+    limits.maxLines,
+  );
+  return {
+    shellId: params.shellId,
+    output: head,
+    startCursor: fromCursor,
+    endCursor: fromCursor + head.length,
+    originalChars,
+    originalLines,
+    hasMoreOutput: tail.length > 0,
+  };
+}
+
+/**
+ * 构造 shell action 标准返回。
+ */
+export function buildActionResponse(params: {
+  /**
+   * 当前 shell 快照。
+   */
+  shell: ShellSessionSnapshot;
+  /**
+   * 可选输出块。
+   */
+  chunk?: ShellOutputChunk;
+  /**
+   * 可选人类可读提示。
+   */
+  note?: string;
+}): ShellActionResponse {
+  return {
+    shell: params.shell,
+    ...(params.chunk ? { chunk: params.chunk } : {}),
+    ...(params.note ? { note: params.note } : {}),
+  };
+}