Merge pull request #36 from itmisx/feature/exec_mode

✨ exec mode

Author: itmisx

README.en.md

@@ -29,6 +29,7 @@
 - **💾 Lossless session persistence** — gob preserves `tool_calls` / tool results / `reasoning_content`, so restarts resume seamlessly; auto layered compaction when the window fills.
 - **🔌 MCP + skill ecosystem** — native MCP; compatible with Claude's skill directories, reuse what you have.
 - **🛡️ Review mode** — file writes / shell run behind human confirmation by default.
+- **⚡ Non-interactive `exec` mode** — `deepx exec "task"` runs once and prints the result straight to stdout; pipe data in, redirect output, drop it into scripts / CI / cron — **no TUI needed** (see the section below).
 
 ## 📊 vs Claude Code
 
@@ -64,11 +65,16 @@ irm https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.ps1
 
 Installs to `~/.local/bin/deepx`; upgrade any time with `deepx upgrade`.
 
-**2. Enter a project and launch**
+**2. Open a terminal in your project and launch**
+
+deepx is a **terminal program**: open a terminal, `cd` into your project, and run `deepx` to enter the interactive UI.
+
+- Any terminal works: macOS Terminal / iTerm2, a Linux terminal, Windows Terminal / PowerShell.
+- The **VS Code integrated terminal** is recommended too (`Terminal → New Terminal`, or `` Ctrl+` ``): it already sits in your open project, so `deepx` works right against it and edits show up live in the editor.
 
 ```bash
-cd <your-project>
-deepx
+cd <your-project>   # VS Code's integrated terminal is usually already at the project root
+deepx               # enter the interactive TUI
 ```
 
 **3. Configure**
@@ -80,6 +86,16 @@ deepx
 | Skills       | Drop into `<workspace>/.deepx/skills/`, or reuse `~/.claude/skills/` etc. |
 | MCP          | Add via `/mcp-add` inside the TUI; list with `/mcp-list`.    |
 
+## ⚡ Non-interactive execution (`deepx exec`)
+
+When you'd rather not enter the full TUI and want to drop deepx into a script, use `deepx exec "<task>"`: it runs the task, prints the result straight to your terminal (stdout), then exits — result only, no intermediate noise.
+
+```bash
+deepx exec "Translate the feature list in README to English and write it to README.en.md"
+```
+
+Piping data in is also supported (`cat error.log | deepx exec "analyze this error"`). Configure your API key once via the interactive `deepx` first.
+
 ## 🧠 How It Works
 
 <details>

README.ja.md

@@ -29,6 +29,7 @@
 - **💾 ロスレスなセッション永続化** —— gob が `tool_calls` / ツール結果 / `reasoning_content` を完全保持し、再起動後もシームレスに継続。ウィンドウが埋まると自動で階層圧縮。
 - **🔌 MCP + Skill エコシステム** —— MCP ネイティブ対応。Claude の skill ディレクトリと互換で、既存の skill をそのまま再利用。
 - **🛡️ レビューモード** —— ファイル書き込み / Shell 実行はデフォルトで人間の確認を要求。
+- **⚡ 非対話 `exec` モード** —— `deepx exec "タスク"` は一度だけ実行して結果を stdout に直接出力。パイプで入力、出力をリダイレクト、スクリプト / CI / cron に組み込み可能で、**TUI に入る必要なし**(下記参照)。
 
 ## 📊 Claude Code との比較
 
@@ -64,11 +65,16 @@ irm https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.ps1
 
 `~/.local/bin/deepx` にインストールされます。`deepx upgrade` でいつでも更新可能。
 
-**2. プロジェクトに入って起動**
+**2. ターミナルでプロジェクトに入って起動**
+
+deepx は**ターミナルプログラム**です。ターミナルを開き、プロジェクトに `cd` して `deepx` を実行すると対話 UI に入ります。
+
+- どのターミナルでも OK:macOS の Terminal / iTerm2、Linux のターミナル、Windows Terminal / PowerShell。
+- **VS Code 内蔵ターミナル**もおすすめ(`Terminal → New Terminal`、または `` Ctrl+` ``):開いているプロジェクトのディレクトリにいるので、`deepx` がそのプロジェクトに対して動き、編集はエディタに即座に反映されます。
 
 ```bash
-cd <あなたのプロジェクト>
-deepx
+cd <あなたのプロジェクト>   # VS Code の内蔵ターミナルなら通常すでにプロジェクト直下
+deepx                       # 対話型 TUI に入る
 ```
 
 **3. 設定**
@@ -80,6 +86,16 @@ deepx
 | Skill         | `<ワークスペース>/.deepx/skills/` に配置、または `~/.claude/skills/` などを再利用。 |
 | MCP           | TUI 内で `/mcp-add` で追加、`/mcp-list` で一覧。              |
 
+## ⚡ 非対話実行（`deepx exec`）
+
+フル TUI に入らず deepx をスクリプトに組み込みたいときは `deepx exec "<タスク>"` を使います。タスクを実行し、結果をそのままターミナル(stdout)に出力して終了します。結果のみ、途中の出力はありません。
+
+```bash
+deepx exec "README の機能リストを英語に翻訳して README.en.md に書き込む"
+```
+
+パイプ入力にも対応(`cat error.log | deepx exec "このエラーを分析して"`)。先に対話型 `deepx` で API キーを設定しておいてください。
+
 ## 🧠 仕組み
 
 <details>

README.ko.md

@@ -29,6 +29,7 @@
 - **💾 무손실 세션 영속화** —— gob가 `tool_calls` / 도구 결과 / `reasoning_content`를 완전 보존해 재시작 후에도 매끄럽게 이어감. 윈도가 차면 자동 계층 압축.
 - **🔌 MCP + Skill 생태계** —— MCP 네이티브 지원. Claude의 skill 디렉터리와 호환되어 기존 skill을 그대로 재사용.
 - **🛡️ 검토 모드** —— 파일 쓰기 / Shell 실행은 기본적으로 사람의 확인을 요구.
+- **⚡ 비대화형 `exec` 모드** —— `deepx exec "작업"` 은 한 번 실행하고 결과를 바로 stdout으로 출력. 파이프로 입력하고, 출력을 리다이렉트하고, 스크립트 / CI / cron에 넣을 수 있어 **TUI에 들어갈 필요 없음**(아래 참조).
 
 ## 📊 Claude Code 비교
 
@@ -64,11 +65,16 @@ irm https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.ps1
 
 `~/.local/bin/deepx`에 설치됩니다. `deepx upgrade`로 언제든 업데이트.
 
-**2. 프로젝트로 이동해 실행**
+**2. 터미널에서 프로젝트로 이동해 실행**
+
+deepx는 **터미널 프로그램**입니다. 터미널을 열고 프로젝트로 `cd` 한 뒤 `deepx` 를 실행하면 대화형 UI로 들어갑니다.
+
+- 어떤 터미널이든 OK: macOS Terminal / iTerm2, Linux 터미널, Windows Terminal / PowerShell.
+- **VS Code 내장 터미널**도 추천(`Terminal → New Terminal`, 또는 `` Ctrl+` ``): 열려 있는 프로젝트 디렉터리에 이미 있어서 `deepx` 가 그 프로젝트를 대상으로 동작하고, 수정 사항이 에디터에 즉시 반영됩니다.
 
 ```bash
-cd <당신의 프로젝트>
-deepx
+cd <당신의 프로젝트>   # VS Code 내장 터미널이면 보통 이미 프로젝트 루트에 있음
+deepx                   # 대화형 TUI 진입
 ```
 
 **3. 설정**
@@ -80,6 +86,16 @@ deepx
 | Skill         | `<워크스페이스>/.deepx/skills/`에 두거나 `~/.claude/skills/` 등 재사용. |
 | MCP           | TUI에서 `/mcp-add`로 추가, `/mcp-list`로 목록 확인.          |
 
+## ⚡ 비대화형 실행（`deepx exec`）
+
+전체 TUI에 들어가지 않고 deepx를 스크립트에 넣고 싶을 때는 `deepx exec "<작업>"` 을 사용하세요. 작업을 실행하고 결과를 그대로 터미널(stdout)에 출력한 뒤 종료합니다. 결과만 나오고 중간 과정은 표시되지 않습니다.
+
+```bash
+deepx exec "README의 기능 목록을 영어로 번역해 README.en.md에 작성"
+```
+
+파이프 입력도 지원합니다(`cat error.log | deepx exec "이 에러를 분석해줘"`). 먼저 대화형 `deepx`로 API 키를 설정해 두세요.
+
 ## 🧠 동작 원리
 
 <details>

README.md

@@ -29,6 +29,7 @@
 - **💾 无损会话持久化** —— gob 完整保留 `tool_calls` / `tool results` / `reasoning_content`，重启无缝续接；超窗自动分层压缩。
 - **🔌 MCP + Skill 生态** —— 原生 MCP；兼容 Claude 的 skill 目录，已有 skill 直接复用。
 - **🛡️ 审核模式** —— 写文件 / 执行 Shell 默认需人工确认，安全可控。
+- **⚡ 非交互 `exec` 模式** —— `deepx exec "任务"` 一次性跑完直接把结果打到 stdout，支持管道喂数据、重定向输出、塞进脚本 / CI / cron，**不必进 TUI**（用法见下方「非交互执行」一节）。
 
 ## 📊 对比 Claude Code
 
@@ -64,11 +65,16 @@ irm https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.ps1
 
 安装到 `~/.local/bin/deepx`，随时用 `deepx upgrade` 升级。
 
-**2. 进入项目并启动**
+**2. 在终端里进入项目并启动**
+
+deepx 是个**终端程序**:打开一个终端,`cd` 进你的项目目录,运行 `deepx` 即可进入交互式界面。
+
+- 任何终端都行:macOS 自带 Terminal / iTerm2、Linux 终端、Windows Terminal / PowerShell。
+- 也推荐 **VS Code 内置终端**(菜单 `Terminal → New Terminal`,或快捷键 `` Ctrl+` ``):它默认就在当前打开的工程目录,`deepx` 起来直接对着这个项目干活,改完文件 VS Code 里实时可见。
 
 ```bash
-cd <你的项目目录>
-deepx
+cd <你的项目目录>   # VS Code 内置终端通常已经在项目根,可跳过
+deepx               # 进入交互式 TUI
 ```
 
 **3. 配置**
@@ -80,6 +86,16 @@ deepx
 | Skill       | 放到 `<工作区>/.deepx/skills/`，或复用 `~/.claude/skills/` 等已有目录。 |
 | MCP         | TUI 内 `/mcp-add` 添加，`/mcp-list` 查看。                    |
 
+## ⚡ 非交互执行（`deepx exec`）
+
+不想进全屏 TUI、想把 deepx 塞进脚本时,用 `deepx exec "<任务>"`:跑完把结果直接打到终端(stdout)再退出,只输出结果、不显示中间过程。
+
+```bash
+deepx exec "把 README 的功能列表翻译成英文,写到 README.en.md"
+```
+
+也支持管道喂数据(`cat error.log | deepx exec "分析这段报错"`)。需先用交互式 `deepx` 配好 API key。
+
 ## 🧠 核心机制
 
 <details>

main.go

@@ -5,7 +5,9 @@ import (
 	"deepx/config"
 	"deepx/tui"
 	"fmt"
+	"io"
 	"os"
+	"strings"
 )
 
 // 由 goreleaser 在 build 时通过 -ldflags "-X main.version=..." 注入。
@@ -28,6 +30,11 @@ func main() {
 		}
 		return
 	}
+	// deepx exec [--mode plan|auto] "<任务>" —— 非交互一次性执行,结果打到 stdout,可脚本化 / 管道。
+	// 也可从 stdin 接管道输入(cat x | deepx exec "分析这段")。默认 auto(全工具,不弹审批)。
+	if len(os.Args) > 1 && os.Args[1] == "exec" {
+		runExecAndExit(os.Args[2:])
+	}
 	cfg, needsSetup, err := loadOrEmptyConfig()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, "错误:", err)
@@ -63,3 +70,44 @@ func toAgentConfig(c *config.Config) agent.ModelConfig {
 		Pro:   agent.ModelEntry(c.Pro),
 	}
 }
+
+// runExecAndExit 解析 `deepx exec` 的参数(args = os.Args[2:]),跑非交互执行,然后退出进程。
+// 用法:deepx exec "<任务>";也可从 stdin 管道喂输入。固定 auto 模式、只输出结果,无任何参数。
+// 退出码:成功 0;用法错误 2;执行/配置错误 1。
+func runExecAndExit(args []string) {
+	prompt := strings.TrimSpace(strings.Join(args, " "))
+
+	// stdin 若是管道(非终端),读进来拼到 prompt 后面:prompt 当指令,管道内容当数据。
+	if fi, _ := os.Stdin.Stat(); fi != nil && (fi.Mode()&os.ModeCharDevice) == 0 {
+		if data, err := io.ReadAll(os.Stdin); err == nil {
+			if piped := strings.TrimSpace(string(data)); piped != "" {
+				if prompt == "" {
+					prompt = piped
+				} else {
+					prompt = prompt + "\n\n" + piped
+				}
+			}
+		}
+	}
+	if prompt == "" {
+		fmt.Fprintln(os.Stderr, `用法: deepx exec "<任务>"   (也可通过管道喂输入)`)
+		os.Exit(2)
+	}
+
+	cfg, needsSetup, err := loadOrEmptyConfig()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "错误:", err)
+		os.Exit(1)
+	}
+	ac := toAgentConfig(cfg)
+	if needsSetup || (ac.Flash.Model == "" && ac.Pro.Model == "") {
+		fmt.Fprintln(os.Stderr, "错误: 尚未配置模型 / API key。先运行 `deepx`(交互式)完成配置,再用 exec。")
+		os.Exit(1)
+	}
+
+	if err := tui.RunExec(ac, prompt); err != nil {
+		fmt.Fprintln(os.Stderr, "\nexec 失败:", err)
+		os.Exit(1)
+	}
+	os.Exit(0)
+}

tui/exec.go

@@ -0,0 +1,65 @@
+package tui
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+
+	"deepx/agent"
+	"deepx/skill"
+	"deepx/tools"
+)
+
+// RunExec 执行一次性非交互任务(`deepx exec "<任务>"`):把 prompt 发给 agent,**只把模型最终
+// 结果打到 stdout**,跑完即退出,不启动 TUI。供脚本 / 管道 / CI / cron 使用。
+//
+//   - 固定 auto 模式(全工具,不弹人工审批——非交互下无法确认,这是有意为之)。
+//   - 工具调用进度 / 思考过程一律不显示,保证 stdout 干净(`> file` 拿到的就是结果)。
+//   - 出错通过返回值上报,调用方据此给非零退出码。
+func RunExec(cfg agent.ModelConfig, prompt string) error {
+	wd, _ := os.Getwd()
+	home, _ := os.UserHomeDir()
+
+	// skill 发现 + codegraph 绑定,与 TUI 启动时保持一致,保证 exec 下工具能力对齐。
+	loader := skill.New(
+		[]string{filepath.Join(wd, ".deepx", "skills")},
+		[]string{
+			filepath.Join(home, ".agents", "skills"),
+			filepath.Join(home, ".claude", "skills"),
+			filepath.Join(home, ".deepx", "skills"),
+		},
+	)
+	tools.SetSkillLoader(loader)
+	tools.SetCodeGraphRoot(wd)
+	skillCatalog := buildSkillCatalog(loader)
+
+	// Ctrl+C → 取消 ctx;StartStream 在轮次间 / HTTP 层检测到取消会平滑收尾并 close channel。
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, os.Interrupt)
+	go func() {
+		<-sigCh
+		cancel()
+	}()
+
+	history := []agent.ChatMessage{{Role: "user", Content: prompt}}
+
+	// 固定 auto 模式;forceRole 传 "auto" → 走本地关键词路由(零 token 决定起手模型)。
+	// summary 空(一次性,无压缩)。
+	_, ch := agent.StartStream(ctx, cfg, history, agent.AgentMode_Auto, wd, skillCatalog, "", "auto")
+
+	var streamErr error
+	for msg := range ch {
+		switch m := msg.(type) {
+		case agent.TokenMsg:
+			fmt.Print(string(m)) // 只输出模型正式回复 → stdout;工具调用 / 思考一律不打印
+		case agent.StreamErrMsg:
+			streamErr = m.Err
+		}
+	}
+	fmt.Println() // 给 stdout 末尾补个换行,终端更整洁(重定向到文件也无害)
+	return streamErr
+}