Merge remote-tracking branch 'upstream/main'

# Conflicts:
#	internal/tui/core/app/app.go

Author: creatang

.github/workflows/release.yml

@@ -27,6 +27,17 @@ jobs:
         with:
           go-version-file: 'go.mod' # 💡 修复点 1：让 Action 自动跟随项目真实的 Go 版本
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Build web dist
+        working-directory: web
+        run: |
+          npm ci
+          npm run build
+
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:
@@ -35,4 +46,4 @@ jobs:
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}       # 💡 修复点 2：补回本仓库的内置鉴权令牌
-          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+          TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}

.goreleaser.yaml

@@ -10,6 +10,8 @@ builds:
   - id: neocode
     env:
       - CGO_ENABLED=0
+    tags:
+      - webembed
     ldflags:
       - -s -w -X 'neo-code/internal/version.Version={{.Version}}'
     goos:

README.en.md

@@ -8,11 +8,11 @@
   <a href="https://go.dev/">
     <img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white" alt="Go Version" />
   </a>
-  <a href="https://github.com/1024XEngineer/neo-code/actions/workflows/ci.yml">
-    <img src="https://img.shields.io/github/actions/workflow/status/1024XEngineer/neo-code/ci.yml?branch=main&label=CI" alt="CI Status" />
+  <a href="https://github.com/1024XEngineer/neo-code">
+    <img src="https://codecov.io/gh/1024XEngineer/neo-code/branch/main/graph/badge.svg" alt="Codecov Coverage" />
   </a>
   <a href="https://github.com/1024XEngineer/neo-code/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/1024XEngineer/neo-code?color=97CA00" alt="License" />
+    <img src="https://img.shields.io/badge/License-MIT-purple?logo=opensourceinitiative&logoColor=white" alt="License MIT" />
   </a>
   <a href="https://neocode-docs.pages.dev/">
     <img src="https://img.shields.io/badge/Docs-Official-1677FF?logo=readthedocs&logoColor=white" alt="Docs" />
@@ -22,6 +22,7 @@
   </a>
 </p>
 
+
 <p align="center">
   <a href="https://neocode-docs.pages.dev/en/">Docs</a>
   ·
@@ -55,6 +56,8 @@ Core loop:
 - Skills system for task-specific behaviors.
 - MCP integration via stdio servers.
 - Gateway mode with local JSON-RPC / SSE / WebSocket access.
+- Feishu Adapter: Webhook and SDK long-connection ingress with live status card updates.
+- Local Runner: execute tools on your local machine via WebSocket connection to a cloud Gateway — no inbound ports needed.
 
 ---
 
@@ -110,6 +113,14 @@ Then start with your workspace:
 neocode --workdir /path/to/your/project
 ```
 
+To launch the browser-based Web UI:
+
+```bash
+neocode web
+```
+
+Tagged release builds already embed `web/dist` into the `neocode` binary, so the target machine does not need Node.js or npm. When running from source, missing `web/dist` still triggers the local frontend build path.
+
 ### 4. Common commands
 
 ```text
@@ -126,14 +137,25 @@ neocode --workdir /path/to/your/project
 
 ---
 
-## Gateway / MCP / Skills
+## Gateway / MCP / Skills / Runner
 
 Detailed docs are intentionally split out. README keeps entry links:
 
 - Gateway integration and protocol: `docs/guides/gateway-integration-guide.md`
 - MCP configuration: `docs/guides/mcp-configuration.md`
 - Skills design: `docs/skills-system-design.md`
 - Runtime event flow: `docs/runtime-provider-event-flow.md`
+- Feishu remote setup: `www/guide/feishu-remote-setup.md`
+
+### CLI Quick Reference
+
+```bash
+# Start local runner daemon (connects to cloud Gateway for remote tool execution)
+neocode runner --gateway-address "your-gateway.com:8080" --token-file ~/.neocode/auth.json
+
+# Start feishu adapter (SDK mode, no public network required)
+neocode feishu-adapter --ingress sdk --gateway-listen "127.0.0.1:8080"
+```
 
 ---
 

README.md

@@ -8,20 +8,21 @@
   <a href="https://go.dev/">
     <img src="https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white" alt="Go Version" />
   </a>
-  <a href="https://github.com/1024XEngineer/neo-code/actions/workflows/ci.yml">
-    <img src="https://img.shields.io/github/actions/workflow/status/1024XEngineer/neo-code/ci.yml?branch=main&label=CI" alt="CI Status" />
+  <a href="https://github.com/1024XEngineer/neo-code">
+    <img src="https://codecov.io/gh/1024XEngineer/neo-code/branch/main/graph/badge.svg" alt="Codecov Coverage" />
   </a>
   <a href="https://github.com/1024XEngineer/neo-code/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/1024XEngineer/neo-code?color=97CA00" alt="License" />
+    <img src="https://img.shields.io/badge/License-MIT-purple?logo=opensourceinitiative&logoColor=white" alt="License MIT" />
   </a>
   <a href="https://neocode-docs.pages.dev/">
     <img src="https://img.shields.io/badge/Docs-Official-1677FF?logo=readthedocs&logoColor=white" alt="Docs" />
   </a>
-  <a href="https://neocode-docs.pages.dev/guide/install">
+  <a href="https://neocode-docs.pages.dev/en/guide/install">
     <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-4EAA25" alt="Platform" />
   </a>
 </p>
 
+
 <p align="center">
   <a href="https://neocode-docs.pages.dev/">文档</a>
   ·
@@ -56,6 +57,7 @@ NeoCode 是一个运行在本地开发环境中的 AI Coding Agent。
 - MCP 接入：通过 MCP stdio server 扩展外部工具能力。
 - Gateway 模式：通过本地 JSON-RPC / SSE / WebSocket 接口连接桌面端、脚本和第三方客户端。
 - Feishu Adapter：支持 Webhook 与 SDK 长连接接入，并用单张状态卡片持续回传 run 状态。
+- Local Runner：`neocode runner` 在本机执行工具，通过 WebSocket 主动连接云端 Gateway，无需开放入站端口。
 
 ---
 
@@ -111,6 +113,13 @@ $env:OPENAI_API_KEY = "your_key_here"
 neocode --workdir /path/to/your/project
 ```
 
+如果你希望使用浏览器 Web UI，可以直接运行：
+```bash
+neocode web
+```
+
+标签发布版已经将 Web UI 的 `web/dist` 内嵌进 `neocode` 二进制，执行 `neocode web` 时不再要求用户机器安装 Node.js 或 npm。如果你在源码仓库里运行 `go run ./cmd/neocode web`，当本地缺少 `web/dist` 时仍会自动尝试构建前端。
+
 ### 4. 常用命令
 
 ```text
@@ -176,6 +185,21 @@ neocode use <provider> --model <model-id>
 neocode use openai --model gpt-4.1
 ```
 
+#### Local Runner
+
+在本机启动执行守护进程，主动连接云端 Gateway 接收工具执行请求。
+
+```bash
+# 启动 runner（默认连接 127.0.0.1:8080）
+neocode runner
+
+# 指定远程 Gateway 地址和 token
+neocode runner --gateway-address "your-gateway.com:8080" --token-file ~/.neocode/auth.json
+
+# 指定 Runner 名称与工作目录
+neocode runner --runner-name "我的本机" --workdir /path/to/project
+```
+
 ### 6. Shell 诊断代理
 
 用于进入代理 shell、初始化 shell integration、手动触发诊断和控制自动诊断模式。

docs/gateway-rpc-api.md

@@ -421,6 +421,27 @@ type ResolvePermissionParams struct {
 
 ---
 
+## Method: gateway.userQuestionAnswer
+
+- Stability: Beta
+- Auth Required: Yes
+- Request Schema:
+
+```go
+type UserQuestionAnswerParams struct {
+	RequestID string   `json:"request_id"`        // MUST
+	Status    string   `json:"status,omitempty"`  // answered|skipped，默认 answered
+	Values    []string `json:"values,omitempty"`  // 可选：选择值
+	Message   string   `json:"message,omitempty"` // 可选：文本回答
+}
+```
+
+- Response Schema: `ack`（提交成功）或标准 `error`
+- Observation:
+  - `gateway_requests_total{method="gateway.userQuestionAnswer",...}`
+
+---
+
 ## Method: gateway.listProviders
 
 - Stability: Stable
@@ -656,6 +677,14 @@ type GetRuntimeSnapshotParams struct {
 
 - Response Schema:
   - Success: `ack` + `payload.snapshot`（runtime facts、decision、todo snapshot）
+  - `payload.snapshot.pending_user_question`（可选）：
+    - `request_id`
+    - `question_id`
+    - `title` / `description`
+    - `kind`（`text|single_choice|multi_choice`）
+    - `options`
+    - `required` / `allow_skip`
+    - `max_choices` / `timeout_sec`
   - Failure: 标准 `error`
 - Observation:
   - `gateway_requests_total{method="runtime.snapshot.get",...}`

docs/guides/feishu-adapter.md

@@ -12,11 +12,12 @@
   - `gateway.bindStream`
   - `gateway.run`
   - `gateway.resolvePermission`
+  - `gateway.userQuestionAnswer`
   - `gateway.event`
 - 会话与运行 ID 保持实现一致：
   - `session_id = "feishu_" + stableHash(chat_id)`
   - `run_id = "feishu_" + stableHash(message_id)`
-- #557 只新增 SDK 入站，不包含 #555 Local Runner 主动长连。
+- #557 新增 SDK 入站；#555 新增 Local Runner 主动长连（工具在 Runner 本机执行）。
 
 ## 2. 事件执行顺序
 
@@ -45,23 +46,32 @@
 ### 4.1 Webhook 模式（#554）
 
 ```bash
+# 开发模式 (go run)
+go run ./cmd/neocode feishu-adapter --ingress webhook
+
+# 安装模式 (neocode)
 neocode feishu-adapter --ingress webhook
 ```
 
 通常还会覆盖地址参数：
 
 ```bash
-neocode feishu-adapter \
-  --ingress webhook \
-  --listen 127.0.0.1:18080 \
-  --event-path /feishu/events \
-  --card-path /feishu/cards
+# 开发模式 (go run)
+go run ./cmd/neocode feishu-adapter --ingress webhook --listen 127.0.0.1:18080 --event-path /feishu/events --card-path /feishu/cards
+
+# 安装模式 (neocode)
+neocode feishu-adapter --ingress webhook --listen 127.0.0.1:18080 --event-path /feishu/events --card-path /feishu/cards
 ```
 
 ### 4.2 SDK 模式（#557，本地无公网）
 
 ```bash
 export FEISHU_APP_SECRET="cli_secret_xxx"
+
+# 开发模式 (go run)
+go run ./cmd/neocode feishu-adapter --ingress sdk
+
+# 安装模式 (neocode)
 neocode feishu-adapter --ingress sdk
 ```
 
@@ -77,7 +87,7 @@ SDK 模式下不要求公网回调地址，不要求 `adapter.listen/event_path/
 ## 6. 幂等与重试
 
 - 消息去重键：`event_id + message_id`
-- 卡片去重键：`request_id + decision`
+- 卡片去重键：优先 `event_id`，无 `event_id` 时回退到动作键（如 `request_id + decision/status`）
 - 仅当 `gateway.run` 成功受理后才标记成功；
 - 若 `run` 失败会释放去重状态，Webhook 返回 `HTTP 500`，SDK 长连接回调返回失败 ACK，允许飞书重试恢复。
 
@@ -100,8 +110,71 @@ SDK 模式下不要求公网回调地址，不要求 `adapter.listen/event_path/
 
 以上两种路径都复用 `gateway.resolvePermission`，不新增 Gateway action。
 
+## 7.1 ask_user 统一交互（permission + user_question）
+
+飞书端卡片回调已升级为通用 `action_type`：
+
+- `action_type=permission` -> `gateway.resolvePermission`
+- `action_type=user_question` -> `gateway.userQuestionAnswer`
+
+V1 交互策略：
+
+- 单选/跳过：优先卡片按钮提交
+- 文本/多选：回退文本指令提交
+  - `回答 <request_id> <内容>`
+  - `跳过 <request_id>`
+
+`webhook` 与 `sdk` 两条 ingress 使用同一动作映射与幂等规则，保证行为一致。
+
 ## 8. 安全要求
 
 - 默认启用签名校验（Webhook）；
 - 日志不会输出 `app_secret`、签名密钥、gateway token、Authorization 等敏感信息；
 - 用户侧只回关键状态（受理、权限请求、完成、失败），不暴露内部堆栈和控制面细节。
+
+## 9. Local Runner 远程工具执行（#555）
+
+Runner 是部署在用户本机的执行守护进程，通过 WebSocket 主动连接云端 Gateway，接收工具执行请求并在本机完成。
+
+```
+飞书消息 -> Feishu Adapter (cloud) -> Gateway (cloud) -> WebSocket -> Local Runner (本机)
+                                                           ↑ 主动出站连接
+```
+
+### 9.1 启动 Runner
+
+```bash
+# 开发模式 (go run)
+go run ./cmd/neocode runner --gateway-address "your-gateway:8080" --token-file ~/.neocode/auth.json --runner-name "我的本机" --workdir /path/to/project
+
+# 安装模式 (neocode)
+neocode runner --gateway-address "your-gateway:8080" --token-file ~/.neocode/auth.json --runner-name "我的本机" --workdir /path/to/project
+```
+
+Runner 启动后会主动连接 Gateway，注册自身并保持心跳。当飞书消息触发工具调用时，Gateway 将工具请求推送到 Runner 本机执行。
+
+### 9.2 参数说明
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|:---:|--------|------|
+| `--gateway-address` | 否 | `127.0.0.1:8080` | Gateway WebSocket 地址 |
+| `--token-file` | 否 | — | Gateway 认证 token 文件路径 |
+| `--runner-id` | 否 | 本机 hostname | Runner 唯一标识 |
+| `--runner-name` | 否 | — | 人类可读的 Runner 名称 |
+| `--workdir` | 否 | 当前目录 | Runner 工作目录 |
+
+### 9.3 安全模型
+
+- Runner 端验证 CapabilityToken（HMAC-SHA256 签名、TTL、AllowedTools、AllowedPaths）
+- 支持 Workdir Allowlist 限制可访问路径
+- 所有工具在 Runner 本机执行，结果通过 Gateway 回传飞书
+
+### 9.4 错误翻译
+
+当 Runner 不可用或权限不足时，Feishu Adapter 会将错误码翻译为用户可读消息：
+
+| 错误码 | 飞书消息 |
+|--------|----------|
+| `runner_offline` | 本机 Runner 未连接，请在电脑上启动 `neocode runner` |
+| `capability_denied` | 权限不足：当前能力令牌不允许此操作 |
+| `tool_execution_failed` | 工具执行失败：{详情} |

docs/guides/modelscope-provider-setup.md

@@ -14,9 +14,11 @@
 2. 打开登录页：<https://www.modelscope.cn/>
 3. 打开 Token 页：<https://www.modelscope.cn/my/access/token>
 4. 在 TUI 引导面板粘贴 token 并提交校验
+5. 打开阿里云绑定页完成账号绑定：<https://www.modelscope.cn/my/settings/account>
 
-如果返回认证或权限类错误，会自动回退并打开阿里云认证页：
-<https://www.modelscope.cn/my/settings/account>
+> **注意**：步骤 5 的阿里云账号绑定是必须步骤。ModelScope API 依赖阿里云账号体系进行鉴权与计费，
+> 未绑定将导致 API 调用返回认证错误。如果 token 校验时提前检测到认证问题，
+> TUI 会自动打开绑定页引导完成。
 
 ## 安全说明
 

internal/app/bootstrap.go

@@ -230,6 +230,15 @@ func BuildGatewayServerDeps(ctx context.Context, opts BootstrapOptions) (Runtime
 		return RuntimeBundle{}, err
 	}
 
+	// Wire ask_user broker from runtime into the pre-registered ask_user tool.
+	if brokerAdapter := runtimeSvc.AskUserBrokerAdapter(); brokerAdapter != nil {
+		if askTool, err := toolRegistry.Get(tools.ToolNameAskUser); err == nil {
+			if setter, ok := askTool.(tools.AskUserBrokerSetter); ok {
+				setter.SetAskUserBroker(brokerAdapter)
+			}
+		}
+	}
+
 	// 注入记忆提取钩子：当 AutoExtract 启用且 memoSvc 可用时，ReAct 循环完成后异步提取记忆。
 	if memoSvc != nil && cfg.Memo.AutoExtract {
 		runtimeSvc.SetMemoExtractor(newMemoExtractorAdapter(
@@ -466,6 +475,7 @@ func buildToolRegistry(cfg config.Config) (*tools.Registry, func() error, error)
 	toolRegistry.Register(codebase.NewRead(repoSvc, cfg.Workdir))
 	toolRegistry.Register(codebase.NewSearchText(repoSvc, cfg.Workdir))
 	toolRegistry.Register(codebase.NewSearchSymbol(repoSvc, cfg.Workdir))
+	toolRegistry.Register(tools.NewAskUserTool(nil)) // broker injected after runtime creation
 	mcpRegistry, err := BuildMCPRegistry(cfg)
 	if err != nil {
 		return nil, nil, err