Shell / 命令执行

6. 用户输入到 agent 行动的整体链路

model tool-call(shell)
  -> ShellTool.execute
  -> parse(params.command)
  -> collect(rootNode, cwd)
  -> ctx.ask(external_directory / shell)
  -> ChildProcessSpawner.spawn
  -> ctx.metadata(output preview)
  -> return { title, metadata, output }
  -> processor writes tool result
  -> next LLM round

7. 核心源码逐段讲解

命令风险词表

const CWD = new Set(["cd", "chdir", "popd", "pushd", "push-location", "set-location"])
const FILES = new Set([
  ...CWD,
  "rm",
  "cp",
  "mv",
  "mkdir",
  "touch",
  "chmod",
  "chown",
  "cat",
])

type Scan = {
  dirs: Set<string>
  patterns: Set<string>
  always: Set<string>
}

路径：packages/opencode/src/tool/shell.ts:28-78。这些集合告诉扫描器哪些命令可能携带路径参数。

审批

if (scan.dirs.size > 0) {
  yield* ctx.ask({
    permission: "external_directory",
    patterns: globs,
    always: globs,
    metadata: {},
  })
}

if (scan.patterns.size === 0) return
yield* ctx.ask({
  permission: ShellID.ToolID,
  patterns: Array.from(scan.patterns),
  always: Array.from(scan.always),
  metadata: {},
})

路径：packages/opencode/src/tool/shell.ts:266-287。外部目录和 shell 命令是两个权限维度。

扫描 AST

for (const node of commands(root)) {
  const command = parts(node)
  const tokens = command.map((item) => item.text)
  const cmd = ps || shellKind === "cmd" ? tokens[0]?.toLowerCase() : tokens[0]

  if (cmd && (FILES.has(cmd) || (shellKind === "cmd" && CMD_FILES.has(cmd)))) {
    for (const arg of pathArgs(command, ps, shellKind === "cmd")) {
      const resolved = yield* argPath(arg, cwd, ps, shell)
      if (!resolved || containsPath(resolved, instance)) continue
      const dir = (yield* fs.isDir(resolved)) ? resolved : path.dirname(resolved)
      scan.dirs.add(dir)
    }
  }
}

路径：packages/opencode/src/tool/shell.ts:388-400。它不是字符串 split，而是从 tree-sitter AST 抽取命令和参数。

执行与输出回写

const handle = yield* spawner.spawn(cmd(input.shell, input.command, input.cwd, input.env))

yield* Effect.forkScoped(
  Stream.runForEach(Stream.decodeText(handle.all), (chunk) => {
    last = preview(last + chunk)
    return ctx.metadata({
      metadata: {
        output: last,
        description: input.description,
      },
    })
  }),
)

路径：packages/opencode/src/tool/shell.ts:479-530。输出不是最后一次性返回，而是持续更新 tool part。

超时和取消

const exit = yield* Effect.raceAll([
  handle.exitCode.pipe(Effect.map((code) => ({ kind: "exit" as const, code }))),
  abort.pipe(Effect.map(() => ({ kind: "abort" as const, code: null }))),
  timeout.pipe(Effect.map(() => ({ kind: "timeout" as const, code: null }))),
])

if (exit.kind === "abort") {
  aborted = true
  yield* handle.kill({ forceKillAfter: "3 seconds" }).pipe(Effect.orDie)
}

路径：packages/opencode/src/tool/shell.ts:542-555。

用户直接执行 shell

const userPart: MessageV2.Part = {
  type: "text",
  id: PartID.ascending(),
  messageID: userMsg.id,
  sessionID: input.sessionID,
  text: "The following tool was executed by the user",
  synthetic: true,
}

路径：packages/opencode/src/session/prompt.ts:520-528。直接 shell 也会写进 session history。

8. 关键 TypeScript 语法复习

• Set<string>：类似 Java HashSet<String>。
• { kind: "exit" as const }：字面量类型，类似 sealed subtype tag。
• params.timeout ?? defaultTimeout：只在 null/undefined 时取默认值。
• await import("web-tree-sitter")：运行时动态 import。
• Effect.acquireRelease：类似 Java try-with-resources。
• { ...process.env, ...extra.env }：对象 spread，后者覆盖前者。

9-10. 架构思想与模块协作

• Strategy：ShellTool 是 tool strategy。
• Preflight scanner：collect 先扫描再执行。
• Policy enforcement point：ctx.ask 统一进入权限系统。
• Streaming progress：ctx.metadata 持续回写输出预览。
• Session 协作：tool result 写回 message history，供下一轮 LLM 使用。
• Plugin 协作：shell.env hook 注入环境变量。

11. mini agent 对应代码

async function runShellTool(input, ctx) {
  const pattern = input.command.split(/\s+/).slice(0, 2).join(" ") + " *"
  await ctx.ask("shell", [pattern])
  const child = spawn(input.command, { cwd: input.cwd, shell: true, signal: ctx.signal })
  child.stdout.on("data", chunk => ctx.updateMetadata({ output: String(chunk) }))
  const result = await waitWithTimeout(child, input.timeoutMs)
  return truncateShellOutput(result)
}