Merge pull request #621 from Cai-Tang-www/feat/issue-586-web-ui-polish

fix: 修复飞书审批卡片回闪并完善 Web/README 体验

Author: phantom5099

README.en.md

@@ -2,7 +2,7 @@
 
 # <img src="docs/assert/readme/neo-code.svg" alt="neo-code" />
 
-> A local-first AI coding agent that helps you understand code, edit projects, call tools, and connect your workflow across terminal, desktop, and automation.
+> A local-first AI coding agent that helps you understand code, edit projects, call tools, and connect your development workflow across terminal, desktop, and automation.
 
 <p align="center">
   <a href="https://go.dev/">
@@ -35,9 +35,9 @@
 
 ## What Is NeoCode?
 
-NeoCode is an AI coding agent running in your local development environment.
+NeoCode is an AI coding agent that runs in your local development environment.
 
-It can read your workspace, understand code, call tools, run commands, manage sessions, and expose a unified local Gateway interface (JSON-RPC / SSE / WebSocket) for terminal, desktop, or third-party clients.
+It can read your workspace, understand code, call tools, execute commands, manage sessions, and expose a unified local Gateway interface via JSON-RPC / SSE / WebSocket for terminal, desktop, or third-party clients.
 
 Core loop:
 
@@ -47,25 +47,30 @@ Core loop:
 
 ## Features
 
-- Local-first execution with real project context.
-- Terminal-native TUI experience.
-- Built-in tools for file access, project inspection, and command execution.
-- Multi-provider support: OpenAI, Gemini, ModelScope, Qiniu, OpenLL, plus custom providers.
-- Session persistence and recovery.
-- Memory for preferences and project facts across sessions.
-- 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.
+- Local-first: runs in your workspace with real project context.
+- Terminal interaction: conversational coding-agent experience based on TUI.
+- Tool calls: supports file access, project inspection, command execution, and system tools.
+- Multi-provider support: OpenAI, Gemini, ModelScope, Qiniu, OpenLL, and custom providers.
+- Session persistence: save and restore historical sessions to reduce repeated context switching.
+- Memory: store preferences, project facts, and cross-session context.
+- Skills system: enable specialized behaviors and workflows for different tasks.
+- MCP integration: extend external tool capabilities through MCP stdio servers.
+- Gateway mode: connect desktop apps, scripts, and third-party clients via local JSON-RPC / SSE / WebSocket.
+- Web UI: launch browser-based interface with `neocode web` for visual chat and session management.
+- Feishu Adapter: supports both Webhook and SDK long-connection access, with continuous run status updates in a single status card.
+- Local Runner: `neocode runner` executes tools locally and actively connects to a cloud Gateway via WebSocket, with no inbound port required.
 
 ---
 
 ## Preview
 
 ![NeoCode TUI chat view](docs/assert/readme/preview-1.png)
-![NeoCode TUI execution view](docs/assert/readme/preview-4.png)
-![NeoCode Gateway interaction example](docs/assert/readme/preview-5.png)
+![NeoCode Web UI view](docs/assert/readme/preview-2.png)
+![NeoCode Feishu adapter view](docs/assert/readme/preview-3.png)
+
+More screenshots and interaction details:
+- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)
+- [Feishu Remote Setup](https://neocode-docs.pages.dev/guide/feishu-remote-setup)
 
 ---
 
@@ -95,7 +100,7 @@ go run ./cmd/neocode
 
 ### 3. Configure API key
 
-Set environment variables for your provider, for example:
+Set the environment variable for your selected provider, for example:
 
 ```bash
 export OPENAI_API_KEY="your_key_here"
@@ -107,21 +112,41 @@ Windows PowerShell:
 $env:OPENAI_API_KEY = "your_key_here"
 ```
 
-Then start with your workspace:
+Then start in your project directory:
 
 ```bash
 neocode -w /path/to/your/project
 ```
 
-To launch the browser-based Web UI:
+If you want to use the browser-based Web UI, run:
 
 ```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.
+Tagged release builds already embed Web UI assets (`web/dist`) into the `neocode` binary, so running `neocode web` does not require Node.js or npm on the target machine. If you run from source with `go run ./cmd/neocode web`, NeoCode will still automatically try to build the frontend when `web/dist` is missing.
+
+### 4. Quick Web / Feishu Entry
+
+```bash
+# Browser Web UI (default 127.0.0.1:8080)
+neocode web
+
+# Specify Web UI listen address (for local debugging)
+neocode web --http-listen 127.0.0.1:8080 --skip-build
+
+# Feishu SDK mode (recommended, no public ingress required)
+neocode feishu-adapter --ingress sdk --gateway-listen "127.0.0.1:8080"
+
+# Feishu Webhook mode (requires callback-reachable address from Feishu)
+neocode feishu-adapter --ingress webhook --gateway-listen "127.0.0.1:8080" --listen "127.0.0.1:18080"
+```
 
-### 4. Common commands
+Detailed guides:
+- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)
+- [Feishu Remote Setup (SDK / Webhook)](https://neocode-docs.pages.dev/guide/feishu-remote-setup)
+
+### 5. Common commands
 
 ```text
 /help                 Show help
@@ -131,40 +156,181 @@ Tagged release builds already embed `web/dist` into the `neocode` binary, so the
 /memo                 Show memory
 /remember <text>      Save memory
 /skills               List available skills
-/skill use <id>       Enable skill
-/skill off <id>       Disable skill
+/skill use <id>       Enable a skill
+/skill off <id>       Disable a skill
 ```
 
----
+### 6. CLI Routing Quick Reference
+
+#### Provider management
+
+Use these commands to add, list, and remove custom providers. Changes are stored under `~/.neocode/providers/`.
 
-## Gateway / MCP / Skills / Runner
+```bash
+# Add a custom provider (ensure --api-key-env points to an existing environment variable)
+neocode provider add <name> --driver <driver> --url <url> --api-key-env <env> [--discovery-endpoint <path>]
+
+# Example
+export MOCK_KEY="sk-xxx"
+neocode provider add my-openai --driver openaicompat --url https://api.openai.com/v1 --api-key-env MOCK_KEY --discovery-endpoint /v1/models
 
-Detailed docs are intentionally split out. README keeps entry links:
+# List all providers
+neocode provider ls
+
+# Remove a custom provider
+neocode provider rm my-openai
+```
 
-- 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`
+#### Model selection
 
-### CLI Quick Reference
+Use these commands to list model candidates for the current provider and switch to a specific model.
 
 ```bash
-# Start local runner daemon (connects to cloud Gateway for remote tool execution)
+# List available models for the current provider (prefer local snapshot; trigger one sync discovery only when needed)
+neocode model ls
+
+# Set current model (validates model ownership against the current provider)
+neocode model set <model-id>
+
+# Example
+neocode model set gpt-4.1
+```
+
+#### One-step provider + model switch
+
+Use this flow to switch provider, and optionally override the auto-selected model via `--model`.
+
+```bash
+# Switch provider only (auto-corrects to an available model)
+neocode use <provider>
+
+# Switch provider and set model (with provider-model ownership validation)
+neocode use <provider> --model <model-id>
+
+# Example
+neocode use openai --model gpt-4.1
+```
+
+#### Local Runner
+
+Start a local execution daemon that actively connects to a cloud Gateway and receives tool-execution requests.
+
+```bash
+# Start runner (connects to 127.0.0.1:8080 by default)
+neocode runner
+
+# Set remote Gateway address and token
 neocode runner --gateway-address "your-gateway.com:8080" --token-file ~/.neocode/auth.json
 
+# Set runner name and working directory
+neocode runner --runner-name "My Local Machine" --workdir /path/to/project
 # Start feishu adapter (SDK mode, no public network required)
 neocode adapter feishu --ingress sdk --gateway-listen "127.0.0.1:8080"
 ```
 
+### 7. Shell Diagnostic Agent
+
+Use these commands to enter proxy shell mode, initialize shell integration, trigger manual diagnosis, and manage automatic diagnosis.
+
+```bash
+# Enter proxy shell (currently Unix-like only)
+neocode shell
+
+# Print shell integration script (also supports --init <shell>)
+neocode shell --init bash
+neocode shell --init zsh
+
+# Trigger one manual diagnosis (both forms are equivalent)
+neocode diag
+neocode diag diagnose
+
+# Enter IDM interactive diagnostic sandbox (exit with "exit" or Ctrl+C when idle)
+neocode diag -i
+
+# Automatic diagnosis switch and status
+neocode diag auto on
+neocode diag auto off
+neocode diag auto status
+```
+
+### 8. URL Scheme Usage
+
+Detailed guide: [HTTP URL Wake-up Guide (User Story Version)](https://neocode-docs.pages.dev/guide/http-daemon-wake-user-guide)
+
+```bash
+# Start local HTTP daemon (default: 127.0.0.1:18921)
+go run ./cmd/neocode daemon serve
+
+# Install user-level autostart + best-effort hosts alias write (127.0.0.1 neocode)
+go run ./cmd/neocode daemon install
+
+# Check running and installation status
+go run ./cmd/neocode daemon status
+
+# Uninstall autostart configuration
+go run ./cmd/neocode daemon uninstall
+```
+
+Clickable URL examples:
+
+```text
+http://neocode:18921/review?path=README.md
+http://neocode:18921/run?prompt=Write%20a%20simple%20HTTP%20server
+```
+
+> Currently supported actions:
+> - `review`: requires the `path` parameter.
+> - `run`: requires the `prompt` parameter. Gateway returns `session_id` and triggers terminal handoff.
+
+Session handoff startup:
+
+```bash
+go run ./cmd/neocode --session <session_id>
+```
+
+> When `--session` is provided, TUI first attempts context handoff using the `workdir` saved in session history. If that path is no longer valid locally, NeoCode keeps the current workspace and displays a warning.
+>
+> On Linux (and other non-Windows/macOS platforms), automatic terminal popup is not yet integrated. `wake.run` returns `not_supported`, and you can manually run `neocode --session <session_id>` for handoff.
+>
+> `daemon serve` does not provide `--token-file`, listens only on `127.0.0.1`, and limits Host allowlist to `neocode` / `localhost` / `127.0.0.1`.
+>
+> Linux autostart strategy: prefer `systemd --user`; fall back to `~/.config/autostart/neocode-daemon.desktop` when unavailable.
+>
+> If NeoCode was not installed via install script (for example, built from source or using a bare binary), run `neocode daemon install` manually once.
+
 ---
 
-## Documentation
+## Documentation Map (By Scenario)
+
+Official docs site (English): [https://neocode-docs.pages.dev/en/](https://neocode-docs.pages.dev/en/)
+
+Recommended reading path:
+
+1. First-time setup
+- [Installation Guide](https://neocode-docs.pages.dev/guide/install)
+- [Daily Use Guide](https://neocode-docs.pages.dev/guide/daily-use)
+- [Configuration Guide](https://neocode-docs.pages.dev/guide/configuration)
+
+2. Entry surfaces (Web / Feishu)
+- [Web UI Guide](https://neocode-docs.pages.dev/guide/web-ui)
+- [Feishu Remote Setup (SDK / Webhook)](https://neocode-docs.pages.dev/guide/feishu-remote-setup)
+- [HTTP URL Wake-up Guide](https://neocode-docs.pages.dev/guide/http-daemon-wake-user-guide)
+
+3. Extensibility (MCP / Skills / Hooks)
+- [MCP Integration](https://neocode-docs.pages.dev/guide/mcp)
+- [Skills Guide](https://neocode-docs.pages.dev/guide/skills)
+- [Hooks Guide](https://neocode-docs.pages.dev/guide/hooks)
+- [Tools and Permissions](https://neocode-docs.pages.dev/guide/tools-permissions)
+
+4. Protocol and internals
+- [Gateway Integration & Protocol (Reference)](https://neocode-docs.pages.dev/reference/gateway)
+- [Runtime / Provider Event Flow (Repo Doc)](docs/runtime-provider-event-flow.md)
 
-- Official docs site: [https://neocode-docs.pages.dev/en/](https://neocode-docs.pages.dev/en/)
-- English guide index: [www/en/guide/index.md](www/en/guide/index.md)
+5. Maintenance and troubleshooting
+- [Update Guide](https://neocode-docs.pages.dev/guide/update)
+- [Troubleshooting](https://neocode-docs.pages.dev/guide/troubleshooting)
 
-Docs site source lives in `www/`. Local preview:
+Docs site source is under `www/`. Local preview:
 
 ```bash
 cd www
@@ -176,14 +342,14 @@ pnpm docs:dev
 
 ## Contributing
 
-Contributions are welcome via Issues, Discussions, and Pull Requests.
+Contributions via Issues, Discussions, and Pull Requests are welcome.
 
-Suggested flow:
+Suggested workflow:
 
-1. Open an issue for problems, requirements, or design proposals.
-2. Fork and create a focused feature branch.
-3. Keep changes scoped and explain impact clearly.
-4. Run checks before submitting:
+1. Describe your problem, requirement, or design idea in an Issue first.
+2. Fork the repository and create a feature branch.
+3. Keep your changes focused and explain motivation and impact clearly.
+4. Run baseline checks before submitting:
 
 ```bash
 gofmt -w ./cmd ./internal