📄 packages/opencode/src/index.ts（第 1-30 行）

import yargs from "yargs"
import { hideBin } from "yargs/helpers"
import { RunCommand } from "./cli/cmd/run"
import { GenerateCommand } from "./cli/cmd/generate"
import { ServeCommand } from "./cli/cmd/serve"
import { DebugCommand } from "./cli/cmd/debug"
import { StatsCommand } from "./cli/cmd/stats"
import { McpCommand } from "./cli/cmd/mcp"
import { GithubCommand } from "./cli/cmd/github"
import { ExportCommand } from "./cli/cmd/export"
import { ImportCommand } from "./cli/cmd/import"
import { AttachCommand } from "./cli/cmd/attach"
import { TuiThreadCommand } from "./cli/cmd/tui"
import { AcpCommand } from "./cli/cmd/acp"
import { WebCommand } from "./cli/cmd/web"
import { PrCommand } from "./cli/cmd/pr"
import { SessionCommand } from "./cli/cmd/session"
import { DbCommand } from "./cli/cmd/db"
import { PluginCommand } from "./cli/cmd/plug"
// ... 共 20+ 个命令模块

📄 packages/opencode/src/index.ts（第 32-70 行）

const cli = yargs(args)
  .parserConfiguration({ "populate--": true })
  .scriptName("opencode")
  .wrap(100)
  .help("help", "show help")
  .alias("help", "h")
  .version("version", "show version", InstallationVersion)
  .alias("version", "v")
  .option("print-logs", {
    describe: "print logs to stderr",
    type: "boolean",
  })
  .option("log-level", {
    describe: "log level",
    type: "string",
    choices: ["DEBUG", "INFO", "WARN", "ERROR"],
  })
  .option("pure", {
    describe: "run without external plugins",
    type: "boolean",
  })
  .middleware(async (opts) => {
    if (opts.printLogs) process.env.OPENCODE_PRINT_LOGS = "1"
    if (opts.logLevel) process.env.OPENCODE_LOG_LEVEL = opts.logLevel
    if (opts.pure) process.env.OPENCODE_PURE = "1"
    Heap.start()
    process.env.AGENT = "1"
    process.env.OPENCODE = "1"
    process.env.OPENCODE_PID = String(process.pid)
  })

📄 packages/opencode/src/index.ts（第 72-142 行）

  .command(RunCommand)
  .command(ServeCommand)
  .command(DebugCommand)
  .command(StatsCommand)
  .command(McpCommand)
  .command(GithubCommand)
  .command(ExportCommand)
  .command(ImportCommand)
  .command(AttachCommand)
  .command(TuiThreadCommand)
  .command(AcpCommand)
  .command(WebCommand)
  .command(PrCommand)
  .command(SessionCommand)
  .command(DbCommand)
  .command(PluginCommand)
  .fail((msg, err) => {
    if (err) throw err
    process.exit(1)
  })
  .strict()

try {
  if (args.includes("-h") || args.includes("--help")) {
    await cli.parse(args, (err, _argv, out) => {
      if (err) throw err
      if (!out) return
      show(out)
    })
  } else {
    await cli.parse()
  }
} catch (e) {
  const formatted = FormatError(e)
  if (formatted) UI.error(formatted)
  if (formatted === undefined) {
    UI.error("Unexpected error" + EOL)
    process.stderr.write(errorMessage(e) + EOL)
  }
  process.exitCode = 1
} finally {
  process.exit()
}

📄 packages/opencode/src/cli/effect-cmd.ts（第 20-50 行）

interface EffectCmdOpts<Args, A> {
  command: string | readonly string[]
  aliases?: string | readonly string[]
  describe: string | false
  builder?: (yargs: Argv) => Argv<Args>
  /**
   * Whether the command needs a project InstanceContext.
   * true (default): wraps handler in InstanceStore.Service.provide
   * false: skip instance entirely
   * Function: (args) => boolean per-invocation
   */
  instance?: boolean | ((args: Args) => boolean)
  directory?: (args: Args) => string
  handler: (args: WithDoubleDash<Args>) =>
    Effect.Effect<A, CliError, AppServices | InstanceStore.Service>
}

true：加载项目实例上下文（InstanceBootstrap），适合 run、session 等命令

false：跳过实例加载，适合 models、serve、upgrade 等命令

函数：动态判断，如 run --attach 连接远程服务器时不需要本地实例

📄 packages/opencode/src/cli/effect-cmd.ts（第 69-96 行）

export const effectCmd = <Args, A>(opts: EffectCmdOpts<Args, A>) =>
  cmd<{}, Args>({
    command: opts.command,
    aliases: opts.aliases,
    describe: opts.describe,
    builder: opts.builder as never,
    async handler(rawArgs) {
      const { AppRuntime } = await import("@/effect/app-runtime")
      const args = rawArgs as unknown as WithDoubleDash<Args>
      const useInstance = typeof opts.instance === "function"
        ? opts.instance(args) : opts.instance !== false
      if (!useInstance) {
        await AppRuntime.runPromise(opts.handler(args))
        return
      }
      const { InstanceStore } = await import("@/project/instance-store")
      const { InstanceRef } = await import("@/effect/instance-ref")
      const directory = opts.directory?.(args) ?? process.cwd()
      const { store, ctx } = await AppRuntime.runPromise(
        InstanceStore.Service.use((store) =>
          store.load({ directory }).pipe(
            Effect.map((ctx) => ({ store, ctx }))
          )
        )
      )
      try {
        await AppRuntime.runPromise(
          opts.handler(args).pipe(
            Effect.provideService(InstanceRef, ctx)
          )
        )
      } finally {
        await AppRuntime.runPromise(store.dispose(ctx))
      }
    },
  })

┌─────────────────────────────────────────────────┐
│            RunCommand (1011 行)                   │
│                                                 │
│  模式 1: 非交互模式 (默认)                        │
│  • 发送消息 → 流式输出 → 会话空闲后退出           │
│  • 示例: opencode run "fix the bug"             │
│                                                 │
│  模式 2: 交互本地模式 (--mini)                    │
│  • 启动 split-footer 直接模式                    │
│  • 进程内服务器，无外部 HTTP                      │
│  • 示例: opencode --mini                        │
│                                                 │
│  模式 3: 交互远程模式 (--mini --attach)          │
│  • 连接已运行的 opencode server                  │
│  • 示例: opencode --mini --attach               │
│         http://localhost:4096                    │
└─────────────────────────────────────────────────┘

📄 packages/opencode/src/cli/cmd/run.ts（第 126-260 行）

export const RunCommand = effectCmd({
  command: "run [message..]",
  describe: "run opencode with a message",
  instance: (args) => !args.attach,
  directory: (args) => (args.dir && !args.attach
    ? path.resolve(process.cwd(), args.dir)
    : process.cwd()),
  builder: (yargs: Argv) =>
    yargs
      .positional("message", {
        describe: "message to send",
        type: "string",
        array: true,
        default: [],
      })
      .option("command", {
        describe: "the command to run",
        type: "string",
      })
      .option("continue", {
        alias: ["c"],
        describe: "continue the last session",
        type: "boolean",
      })
      .option("session", {
        alias: ["s"],
        describe: "session id to continue",
        type: "string",
      })
      .option("model", {
        type: "string",
        alias: ["m"],
        describe: "model (provider/model)",
      })
      .option("file", {
        alias: ["f"],
        type: "string",
        array: true,
        describe: "file(s) to attach",
      })
      .option("attach", {
        type: "string",
        describe: "attach to running server",
      })
      .option("dir", {
        type: "string",
        describe: "directory to run in",
      })
      .option("interactive", {
        alias: ["i"],
        type: "boolean",
        describe: "direct interactive mode",
        default: false,
      })
      .option("yolo", {
        type: "boolean",
        hidden: true,
        default: false,
      })