Skip to content

Commit e3996f6

Browse files
pionxepionxe
committed
docs(guide): 新增 HTTP URL 唤醒用户故事版指南
1 parent de34f90 commit e3996f6

2 files changed

Lines changed: 375 additions & 0 deletions

File tree

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

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
# HTTP URL 唤醒使用指南（用户故事版）
2+
3+
本指南面向最终用户，目标是让你在文档、网页、IM 聊天里点击一个链接，就能拉起 NeoCode 并接管会话。
4+
5+
---
6+
7+
## 你会得到什么
8+
9+
- 点击 `http://neocode:18921/run?...` 可直接发起一次新任务。
10+
- 点击 `http://neocode:18921/review?...` 可直接发起文件审查任务。
11+
- 首次点击会自动创建会话并执行。
12+
- 后续点击带 `session_id` 的链接会直接进入同一会话，不重复发送提示词。
13+
14+
---
15+
16+
## 一分钟理解工作流
17+
18+
1. 浏览器打开链接（`run` 或 `review`）。
19+
2. 本机 daemon 收到请求并转发到 Gateway。
20+
3. Gateway 返回 `session_id`。
21+
4. daemon 拉起 `neocode --session <session_id>`。
22+
5. 首次点击时，TUI 启动后自动走标准 Submit 链路执行任务。
23+
6. 复点（带 `session_id`）时，只接管会话，不重复执行。
24+
25+
---
26+
27+
## 0. 首次准备（只做一次）
28+
29+
### 0.1 安装并注册 daemon 自启动
30+
31+
```bash
32+
neocode daemon install
33+
```
34+
35+
说明：
36+
37+
- 会配置用户态自启动。
38+
- 会 best-effort 写入 hosts 别名（`127.0.0.1 neocode`）。
39+
40+
### 0.2 启动 daemon（开发期可手动）
41+
42+
```bash
43+
neocode daemon serve
44+
```
45+
46+
默认监听：`127.0.0.1:18921`
47+
48+
### 0.3 查看状态
49+
50+
```bash
51+
neocode daemon status
52+
```
53+
54+
---
55+
56+
## 1. 用户故事 A：首次点击 run 链接并开始执行
57+
58+
场景：你在需求文档里放一个“让 NeoCode 直接开始做事”的链接。
59+
60+
### 1.1 生成可点击链接（推荐）
61+
62+
```bash
63+
neocode daemon encode run --prompt "实现一个最小 HTTP 服务" --workdir "C:\project"
64+
```
65+
66+
示例输出：
67+
68+
```text
69+
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
70+
```
71+
72+
### 1.2 点击链接后的预期
73+
74+
- 弹出一个成功页，页面会显示：
75+
- `session_id`
76+
- `reusable_url`（可复用链接）
77+
- 自动拉起 TUI。
78+
- TUI 会显示完整思考/流式过程（与手动输入一致）。
79+
80+
---
81+
82+
## 2. 用户故事 B：首次点击 review 链接发起文件审查
83+
84+
场景：你在代码评审文档里放一个“审查这个文件”的链接。
85+
86+
### 2.1 生成 review 链接
87+
88+
```bash
89+
neocode daemon encode review --path "internal/gateway/bootstrap.go" --workdir "C:\project"
90+
```
91+
92+
示例输出：
93+
94+
```text
95+
http://neocode:18921/review?path=internal%2Fgateway%2Fbootstrap.go&workdir=C%3A%5Cproject
96+
```
97+
98+
### 2.2 review 首次点击的执行语义
99+
100+
- 系统会自动组装输入：`请审查文件 internal/gateway/bootstrap.go`
101+
- 然后按标准 Submit 链路执行（不是旁路执行）。
102+
103+
### 2.3 review 参数规则（首次）
104+
105+
- `path` 必填。
106+
- `workdir` 必填（除非你传了 `session_id`）。
107+
- `path` 必须是安全相对路径（不能绝对路径、不能 `..` 越界）。
108+
109+
---
110+
111+
## 3. 用户故事 C：复用同一会话（不重复发送提示词）
112+
113+
场景：你第一次点击后结果不错，想让团队后续都续接同一个会话。
114+
115+
### 3.1 使用成功页里的 `reusable_url`
116+
117+
成功页会给出带 `session_id` 的链接，形如：
118+
119+
```text
120+
http://neocode:18921/run?prompt=...&workdir=...&session_id=session_xxx
121+
```
122+
123+
### 3.2 带 `session_id` 的行为
124+
125+
- 只接管会话（打开同一 session）。
126+
- 不会再次自动发送 `prompt/path`。
127+
- 适合“继续对话”和“多人协同续接”。
128+
129+
---
130+
131+
## 4. 推荐实践（避免踩坑）
132+
133+
1. 所有要放进文档/IM 的链接都先用 `neocode daemon encode ...` 生成。
134+
2. `review` 首次点击一定显式带 `workdir`，避免审错仓库。
135+
3. 首次执行后，把成功页里的 `reusable_url` 保存到文档，后续统一点它。
136+
4. Windows 路径、中文、空格都不要手写拼接，交给 `encode` 命令处理。
137+
138+
---
139+
140+
## 5. 常见问题排查
141+
142+
### Q1：点击后提示 `forbidden host`
143+
144+
原因：Host 不在白名单。
145+
允许的 Host：`neocode`、`localhost`、`127.0.0.1`。
146+
147+
### Q2：提示 `missing required query: prompt`
148+
149+
原因：`run` 首次点击没带 `prompt`。
150+
处理：补上 `prompt`，或直接使用 `daemon encode run`。
151+
152+
### Q3：提示 `missing required query: workdir or session_id`
153+
154+
原因：`review` 首次点击没带 `workdir` 且没带 `session_id`。
155+
处理：补 `workdir`，或使用已有 `session_id` 的复用链接。
156+
157+
### Q4：提示 `wake session not found`
158+
159+
原因：链接里的 `session_id` 在本机不存在。
160+
处理：重新走一次首次点击，获取新的 `session_id`。
161+
162+
### Q5：Linux 下没有自动弹终端
163+
164+
当前 Linux 终端自动拉起能力受限。
165+
可手动执行：
166+
167+
```bash
168+
neocode --session <session_id>
169+
```
170+
171+
---
172+
173+
## 6. 命令速查
174+
175+
```bash
176+
# 启动 daemon
177+
neocode daemon serve
178+
179+
# 安装自启动
180+
neocode daemon install
181+
182+
# 卸载自启动
183+
neocode daemon uninstall
184+
185+
# 查看状态
186+
neocode daemon status
187+
188+
# 生成 run 链接
189+
neocode daemon encode run --prompt "..." --workdir "..."
190+
191+
# 生成 review 链接
192+
neocode daemon encode review --path "..." --workdir "..."
193+
```
194+

‎www/guide/http-daemon-wake-user-guide.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
---
2+
title: HTTP URL 唤醒指南
3+
description: 用用户故事快速掌握 NeoCode daemon 链接唤醒，从首次执行到会话复用。
4+
---
5+
6+
# HTTP URL 唤醒使用指南（用户故事版）
7+
8+
本指南面向最终用户，目标是让你在文档、网页、IM 聊天里点击一个链接，就能拉起 NeoCode 并接管会话。
9+
10+
## 你会得到什么
11+
12+
- 点击 `http://neocode:18921/run?...` 可直接发起一次新任务。
13+
- 点击 `http://neocode:18921/review?...` 可直接发起文件审查任务。
14+
- 首次点击会自动创建会话并执行。
15+
- 后续点击带 `session_id` 的链接会直接进入同一会话，不重复发送提示词。
16+
17+
## 一分钟理解工作流
18+
19+
1. 浏览器打开链接（`run` 或 `review`）。
20+
2. 本机 daemon 收到请求并转发到 Gateway。
21+
3. Gateway 返回 `session_id`。
22+
4. daemon 拉起 `neocode --session <session_id>`。
23+
5. 首次点击时，TUI 启动后自动走标准 Submit 链路执行任务。
24+
6. 复点（带 `session_id`）时，只接管会话，不重复执行。
25+
26+
## 0. 首次准备（只做一次）
27+
28+
### 0.1 安装并注册 daemon 自启动
29+
30+
```bash
31+
neocode daemon install
32+
```
33+
34+
说明：
35+
36+
- 会配置用户态自启动。
37+
- 会 best-effort 写入 hosts 别名（`127.0.0.1 neocode`）。
38+
39+
### 0.2 启动 daemon（开发期可手动）
40+
41+
```bash
42+
neocode daemon serve
43+
```
44+
45+
默认监听：`127.0.0.1:18921`
46+
47+
### 0.3 查看状态
48+
49+
```bash
50+
neocode daemon status
51+
```
52+
53+
## 1. 用户故事 A：首次点击 run 链接并开始执行
54+
55+
场景：你在需求文档里放一个“让 NeoCode 直接开始做事”的链接。
56+
57+
### 1.1 生成可点击链接（推荐）
58+
59+
```bash
60+
neocode daemon encode run --prompt "实现一个最小 HTTP 服务" --workdir "C:\project"
61+
```
62+
63+
示例输出：
64+
65+
```text
66+
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
67+
```
68+
69+
### 1.2 点击链接后的预期
70+
71+
- 弹出一个成功页，页面会显示：
72+
- `session_id`
73+
- `reusable_url`（可复用链接）
74+
- 自动拉起 TUI。
75+
- TUI 会显示完整思考/流式过程（与手动输入一致）。
76+
77+
## 2. 用户故事 B：首次点击 review 链接发起文件审查
78+
79+
场景：你在代码评审文档里放一个“审查这个文件”的链接。
80+
81+
### 2.1 生成 review 链接
82+
83+
```bash
84+
neocode daemon encode review --path "internal/gateway/bootstrap.go" --workdir "C:\project"
85+
```
86+
87+
示例输出：
88+
89+
```text
90+
http://neocode:18921/review?path=internal%2Fgateway%2Fbootstrap.go&workdir=C%3A%5Cproject
91+
```
92+
93+
### 2.2 review 首次点击的执行语义
94+
95+
- 系统会自动组装输入：`请审查文件 internal/gateway/bootstrap.go`
96+
- 然后按标准 Submit 链路执行（不是旁路执行）。
97+
98+
### 2.3 review 参数规则（首次）
99+
100+
- `path` 必填。
101+
- `workdir` 必填（除非你传了 `session_id`）。
102+
- `path` 必须是安全相对路径（不能绝对路径、不能 `..` 越界）。
103+
104+
## 3. 用户故事 C：复用同一会话（不重复发送提示词）
105+
106+
场景：你第一次点击后结果不错，想让团队后续都续接同一个会话。
107+
108+
### 3.1 使用成功页里的 `reusable_url`
109+
110+
成功页会给出带 `session_id` 的链接，形如：
111+
112+
```text
113+
http://neocode:18921/run?prompt=...&workdir=...&session_id=session_xxx
114+
```
115+
116+
### 3.2 带 `session_id` 的行为
117+
118+
- 只接管会话（打开同一 session）。
119+
- 不会再次自动发送 `prompt/path`。
120+
- 适合“继续对话”和“多人协同续接”。
121+
122+
## 4. 推荐实践（避免踩坑）
123+
124+
1. 所有要放进文档/IM 的链接都先用 `neocode daemon encode ...` 生成。
125+
2. `review` 首次点击一定显式带 `workdir`，避免审错仓库。
126+
3. 首次执行后，把成功页里的 `reusable_url` 保存到文档，后续统一点它。
127+
4. Windows 路径、中文、空格都不要手写拼接，交给 `encode` 命令处理。
128+
129+
## 5. 常见问题排查
130+
131+
### Q1：点击后提示 `forbidden host`
132+
133+
原因：Host 不在白名单。
134+
允许的 Host：`neocode`、`localhost`、`127.0.0.1`。
135+
136+
### Q2：提示 `missing required query: prompt`
137+
138+
原因：`run` 首次点击没带 `prompt`。
139+
处理：补上 `prompt`，或直接使用 `daemon encode run`。
140+
141+
### Q3：提示 `missing required query: workdir or session_id`
142+
143+
原因：`review` 首次点击没带 `workdir` 且没带 `session_id`。
144+
处理：补 `workdir`，或使用已有 `session_id` 的复用链接。
145+
146+
### Q4：提示 `wake session not found`
147+
148+
原因：链接里的 `session_id` 在本机不存在。
149+
处理：重新走一次首次点击，获取新的 `session_id`。
150+
151+
### Q5：Linux 下没有自动弹终端
152+
153+
当前 Linux 终端自动拉起能力受限。
154+
可手动执行：
155+
156+
```bash
157+
neocode --session <session_id>
158+
```
159+
160+
## 6. 命令速查
161+
162+
```bash
163+
# 启动 daemon
164+
neocode daemon serve
165+
166+
# 安装自启动
167+
neocode daemon install
168+
169+
# 卸载自启动
170+
neocode daemon uninstall
171+
172+
# 查看状态
173+
neocode daemon status
174+
175+
# 生成 run 链接
176+
neocode daemon encode run --prompt "..." --workdir "..."
177+
178+
# 生成 review 链接
179+
neocode daemon encode review --path "..." --workdir "..."
180+
```
181+

0 commit comments

Comments
 (0)