Merge pull request #496 from pionxe/feat/url-wake-session-hydration-mvp

feat(step2): 打通 neocode://run 唤醒-会话创建-终端接管闭环并补齐系统级 URL 注册

Author: phantom5099

README.md

@@ -124,6 +124,50 @@ neocode --workdir /path/to/your/project
 /skill off <id>       停用 skill
 ```
 
+### 5. url scheme使用
+详细指南链接： [HTTP URL 唤醒使用指南（用户故事版）](https://neocode-docs.pages.dev/guide/http-daemon-wake-user-guide)
+
+```bash
+# 启动本地 HTTP daemon（默认 127.0.0.1:18921）
+go run ./cmd/neocode daemon serve
+
+# 安装用户态自启动 + best-effort hosts 别名写入（127.0.0.1 neocode）
+go run ./cmd/neocode daemon install
+
+# 查看运行与安装状态
+go run ./cmd/neocode daemon status
+
+# 卸载自启动配置
+go run ./cmd/neocode daemon uninstall
+```
+
+可点击链接示例：
+
+```text
+http://neocode:18921/review?path=README.md
+http://neocode:18921/run?prompt=写一个简单的HTTP服务器
+```
+
+> 当前支持动作：
+> - `review`：必须携带 `path` 参数。
+> - `run`：必须携带 `prompt` 参数，网关会返回 `session_id` 并触发终端接管链路。
+
+会话接管启动方式：
+
+```bash
+go run ./cmd/neocode --session <session_id>
+```
+
+> 当传入 `--session` 时，TUI 会优先按会话历史中的 `workdir` 进行上下文接管；若该路径在本地失效，会保留当前工作区并显示告警。
+>
+> Linux（及其他非 Windows/macOS）当前尚未接入自动弹窗终端；`wake.run` 会返回 `not_supported`，可手动执行 `neocode --session <session_id>` 接管。
+>
+> `daemon serve` 不提供 `--token-file`，默认仅监听 `127.0.0.1`，并限制 Host 白名单为 `neocode` / `localhost` / `127.0.0.1`。
+>
+> Linux 自启动策略：优先 `systemd --user`，若不可用则回落到 `~/.config/autostart/neocode-daemon.desktop`。
+>
+> 若未通过安装脚本安装（例如 `go build` / 裸二进制），请手动执行一次 `neocode daemon install`。
+
 ---
 
 ## Gateway / MCP / Skills

docs/gateway-detailed-design.md

@@ -19,7 +19,7 @@
 
 ### 2.2 并发与稳定性
 
-URL 派发（`url-dispatch`）在网关未启动时需要确定性恢复策略。  
+URL 派发（`daemon dispatcher`）在网关未启动时需要确定性恢复策略。  
 本次引入统一 launcher，固定发现顺序并限制单次回退，避免无限重试。
 
 ### 2.3 资产与运维复用
@@ -50,7 +50,7 @@ flowchart LR
 3. 鉴权与 ACL 装配。
 4. IPC/HTTP server 启停流程。
 
-### 3.3 自动拉起状态机（url-dispatch）
+### 3.3 自动拉起状态机（daemon dispatcher）
 
 ```mermaid
 stateDiagram-v2
@@ -79,8 +79,8 @@ stateDiagram-v2
 
 ### 3.4 子进程回收
 
-launcher 启动网关后立即 `Release` 进程句柄，不阻塞 url-dispatch 主流程。  
-网关生命周期由目标进程自身管理，url-dispatch 仅负责“拉起 + 等待可连通 + 单次重拨”。
+launcher 启动网关后立即 `Release` 进程句柄，不阻塞 daemon dispatcher 主流程。  
+网关生命周期由目标进程自身管理，daemon dispatcher 仅负责“拉起 + 等待可连通 + 单次重拨”。
 
 ## 4. Design Trade-offs
 
@@ -105,7 +105,7 @@ launcher 启动网关后立即 `Release` 进程句柄，不阻塞 url-dispatch 
 
 ### 5.2 连接重置与重试
 
-1. url-dispatch 仅在首拨失败时触发一次 launcher 回退。
+1. daemon dispatcher 仅在首拨失败时触发一次 launcher 回退。
 2. 回退后仅重拨一次，避免无界重试。
 
 ### 5.3 心跳与超时
@@ -137,3 +137,17 @@ launcher 启动网关后立即 `Release` 进程句柄，不阻塞 url-dispatch 
 3. 日志白名单字段具备自动化断言：`listen_address`、`auth_mode`、`request_id`、`method`、`source`、`status`、`gateway_code`。
 4. CI 包含 gateway-only 冒烟链路：启动 -> `/healthz` -> `/rpc` 未鉴权失败 -> 清理。
 5. 安装脚本支持 `full|gateway` flavor 与 dry-run，且 URL/资产/checksum 命名规则可回归验证。
+## 8. HTTP Daemon Wake (Step 2.5)
+
+为解决多数文档平台无法直接点击 `http://neocode:18921/` 的限制，引入本机 HTTP daemon 入口并与 HTTP daemon 单入口：
+
+- 入口：`http://neocode:18921/run?...`、`http://neocode:18921/review?...`
+- `daemon` 不再执行 `HTTP -> http://neocode:18921/ -> ParseNeoCodeURL` 双序列化；而是直接将 HTTP 参数映射为 `protocol.WakeIntent`，复用与 `daemon dispatcher` 相同的 IPC/RPC 派发核心。
+- Gateway 在 IPC 来源下对 `wake.openUrl` 提供最小豁免（仅此方法），其余方法仍遵循既有鉴权与 ACL 约束。
+- Linux 自启动采用双分支：优先 `systemd --user`，不可用时回落 `~/.config/autostart/neocode-daemon.desktop`。
+
+迁移节奏：
+
+1. Step 2.5 先新增 daemon 方案并人工验收。
+2. 验收通过后，再在后续 PR 中移除 `http://neocode:18921/` 系统注册链路。
+

docs/gateway-rpc-api.md

@@ -441,4 +441,4 @@ type ResolvePermissionParams struct {
 - Response Schema: `ack` 或标准 `error`
 - Observation:
   - 统计进入 `gateway_requests_total{method="wake.openUrl",...}`
-  - 与 url-dispatch 自动拉起链路联动
+  - 与 daemon dispatcher 自动拉起链路联动

docs/guides/http-daemon-wake-user-guide.md

@@ -0,0 +1,194 @@
+# HTTP URL 唤醒使用指南（用户故事版）
+
+本指南面向最终用户，目标是让你在文档、网页、IM 聊天里点击一个链接，就能拉起 NeoCode 并接管会话。
+
+---
+
+## 你会得到什么
+
+- 点击 `http://neocode:18921/run?...` 可直接发起一次新任务。
+- 点击 `http://neocode:18921/review?...` 可直接发起文件审查任务。
+- 首次点击会自动创建会话并执行。
+- 后续点击带 `session_id` 的链接会直接进入同一会话，不重复发送提示词。
+
+---
+
+## 一分钟理解工作流
+
+1. 浏览器打开链接（`run` 或 `review`）。
+2. 本机 daemon 收到请求并转发到 Gateway。
+3. Gateway 返回 `session_id`。
+4. daemon 拉起 `neocode --session <session_id>`。
+5. 首次点击时，TUI 启动后自动走标准 Submit 链路执行任务。
+6. 复点（带 `session_id`）时，只接管会话，不重复执行。
+
+---
+
+## 0. 首次准备（只做一次）
+
+### 0.1 安装并注册 daemon 自启动
+
+```bash
+neocode daemon install
+```
+
+说明：
+
+- 会配置用户态自启动。
+- 会 best-effort 写入 hosts 别名（`127.0.0.1 neocode`）。
+
+### 0.2 启动 daemon（开发期可手动）
+
+```bash
+neocode daemon serve
+```
+
+默认监听：`127.0.0.1:18921`
+
+### 0.3 查看状态
+
+```bash
+neocode daemon status
+```
+
+---
+
+## 1. 用户故事 A：首次点击 run 链接并开始执行
+
+场景：你在需求文档里放一个“让 NeoCode 直接开始做事”的链接。
+
+### 1.1 生成可点击链接（推荐）
+
+```bash
+neocode daemon encode run --prompt "实现一个最小 HTTP 服务" --workdir "C:\project"
+```
+
+示例输出：
+
+```text
+http://neocode:18921/run?prompt=%E5%AE%9E%E7%8E%B0%E4%B8%80%E4%B8%AA%E6%9C%80%E5%B0%8F+HTTP+%E6%9C%8D%E5%8A%A1&workdir=C%3A%5Cproject
+```
+
+### 1.2 点击链接后的预期
+
+- 弹出一个成功页，页面会显示：
+  - `session_id`
+  - `reusable_url`（可复用链接）
+- 自动拉起 TUI。
+- TUI 会显示完整思考/流式过程（与手动输入一致）。
+
+---
+
+## 2. 用户故事 B：首次点击 review 链接发起文件审查
+
+场景：你在代码评审文档里放一个“审查这个文件”的链接。
+
+### 2.1 生成 review 链接
+
+```bash
+neocode daemon encode review --path "internal/gateway/bootstrap.go" --workdir "C:\project"
+```
+
+示例输出：
+
+```text
+http://neocode:18921/review?path=internal%2Fgateway%2Fbootstrap.go&workdir=C%3A%5Cproject
+```
+
+### 2.2 review 首次点击的执行语义
+
+- 系统会自动组装输入：`请审查文件 internal/gateway/bootstrap.go`
+- 然后按标准 Submit 链路执行（不是旁路执行）。
+
+### 2.3 review 参数规则（首次）
+
+- `path` 必填。
+- `workdir` 必填（除非你传了 `session_id`）。
+- `path` 必须是安全相对路径（不能绝对路径、不能 `..` 越界）。
+
+---
+
+## 3. 用户故事 C：复用同一会话（不重复发送提示词）
+
+场景：你第一次点击后结果不错，想让团队后续都续接同一个会话。
+
+### 3.1 使用成功页里的 `reusable_url`
+
+成功页会给出带 `session_id` 的链接，形如：
+
+```text
+http://neocode:18921/run?prompt=...&workdir=...&session_id=session_xxx
+```
+
+### 3.2 带 `session_id` 的行为
+
+- 只接管会话（打开同一 session）。
+- 不会再次自动发送 `prompt/path`。
+- 适合“继续对话”和“多人协同续接”。
+
+---
+
+## 4. 推荐实践（避免踩坑）
+
+1. 所有要放进文档/IM 的链接都先用 `neocode daemon encode ...` 生成。
+2. `review` 首次点击一定显式带 `workdir`，避免审错仓库。
+3. 首次执行后，把成功页里的 `reusable_url` 保存到文档，后续统一点它。
+4. Windows 路径、中文、空格都不要手写拼接，交给 `encode` 命令处理。
+
+---
+
+## 5. 常见问题排查
+
+### Q1：点击后提示 `forbidden host`
+
+原因：Host 不在白名单。  
+允许的 Host：`neocode`、`localhost`、`127.0.0.1`。
+
+### Q2：提示 `missing required query: prompt`
+
+原因：`run` 首次点击没带 `prompt`。  
+处理：补上 `prompt`，或直接使用 `daemon encode run`。
+
+### Q3：提示 `missing required query: workdir or session_id`
+
+原因：`review` 首次点击没带 `workdir` 且没带 `session_id`。  
+处理：补 `workdir`，或使用已有 `session_id` 的复用链接。
+
+### Q4：提示 `wake session not found`
+
+原因：链接里的 `session_id` 在本机不存在。  
+处理：重新走一次首次点击，获取新的 `session_id`。
+
+### Q5：Linux 下没有自动弹终端
+
+当前 Linux 终端自动拉起能力受限。  
+可手动执行：
+
+```bash
+neocode --session <session_id>
+```
+
+---
+
+## 6. 命令速查
+
+```bash
+# 启动 daemon
+neocode daemon serve
+
+# 安装自启动
+neocode daemon install
+
+# 卸载自启动
+neocode daemon uninstall
+
+# 查看状态
+neocode daemon status
+
+# 生成 run 链接
+neocode daemon encode run --prompt "..." --workdir "..."
+
+# 生成 review 链接
+neocode daemon encode review --path "..." --workdir "..."
+```
+

docs/guides/update.md

@@ -4,7 +4,7 @@
 
 1. `neocode` 启动时会后台检测新版本（默认 3 秒超时）。
 2. 为避免干扰 TUI，提示在程序退出后展示。
-3. `url-dispatch`、`update` 与 `version` 子命令默认跳过静默检测（避免同次命令重复探测）。
+3. `update` 与 `version` 子命令默认跳过静默检测（避免同次命令重复探测）。
 
 ## 2. 版本查询
 

docs/reference/gateway-rpc-api.md

@@ -1689,7 +1689,7 @@ Request：
     "params": {
       "path": "README.md"
     },
-    "raw_url": "neocode://review?path=README.md"
+    "raw_url": "http://neocode:18921/review?path=README.md"
   }
 }
 ```

internal/app/bootstrap.go

@@ -13,6 +13,7 @@ import (
 	"neo-code/internal/config"
 	configstate "neo-code/internal/config/state"
 	agentcontext "neo-code/internal/context"
+	"neo-code/internal/gateway/protocol"
 	"neo-code/internal/memo"
 	"neo-code/internal/provider"
 	"neo-code/internal/provider/builtin"
@@ -55,7 +56,9 @@ var (
 
 // BootstrapOptions 描述应用启动时可注入的运行时选项。
 type BootstrapOptions struct {
-	Workdir string
+	Workdir      string
+	SessionID    string
+	WakeInputB64 string
 }
 
 type memoExtractorScheduler interface {
@@ -265,6 +268,29 @@ func NewProgram(ctx context.Context, opts BootstrapOptions) (*tea.Program, func(
 		}
 		return nil, nil, err
 	}
+	if sessionID := strings.TrimSpace(opts.SessionID); sessionID != "" {
+		if err := tuiApp.HydrateSession(ctx, sessionID); err != nil {
+			if cleanup != nil {
+				_ = cleanup()
+			}
+			return nil, nil, err
+		}
+	}
+	if encodedWakeInput := strings.TrimSpace(opts.WakeInputB64); encodedWakeInput != "" {
+		wakeInput, decodeErr := protocol.DecodeWakeStartupInput(encodedWakeInput)
+		if decodeErr != nil {
+			if cleanup != nil {
+				_ = cleanup()
+			}
+			return nil, nil, decodeErr
+		}
+		if configureErr := tuiApp.ConfigureStartupWakeInput(wakeInput.Text, wakeInput.Workdir); configureErr != nil {
+			if cleanup != nil {
+				_ = cleanup()
+			}
+			return nil, nil, configureErr
+		}
+	}
 	return tea.NewProgram(
 		tuiApp,
 		tea.WithAltScreen(),