NeoCode TUI 评审与全流程测试指南

[creatang]

1. 评审范围与依据

本指南基于以下内容交叉评审并整理：

• README.md / README.en.md
• www/guide/*.md（安装、日常使用、Slash 指令、工具权限、MCP、Skills、排障、HTTP 唤醒）
• internal/tui/**（TUI 交互实现）
• internal/cli/root.go（启动参数）

同时执行了 TUI 相关测试：

go test ./internal/tui/...

结果：全部通过（2026-04-30）。

2. 评审发现（需重点关注）

P1 文档与真实行为不一致：/clear

• 文档写法（www/guide/slash-commands.md）：/clear 仅清空当前输入草稿，不影响会话历史。
• 实际行为（internal/tui/core/app/update.go:4608）：/clear 执行 startDraftSession()，会切到 Draft 并清空当前会话展示内容。
• 风险：演示时用户可能误以为只是清空输入框，导致“会话不见了”的误解。

P1 文档与真实行为不一致：Ctrl+O

• 文档写法（www/guide/daily-use.md）：Ctrl+O 打开工作区选择。
• 实际行为（internal/tui/core/app/command_menu.go:360 + update.go:2068）：Ctrl+O 打开文件浏览器，用于插入 @文件引用 或添加图片附件，不是切换工作区。
• 风险：演示人员会按错预期路径，造成“功能异常”错觉。

P2 文档残留过时命令：/cwd

• 文档写法（www/guide/tools-permissions.md）仍提示可用 /cwd 查看工作区。
• 代码侧已移除该命令（internal/tui/core/utils/view_helpers.go 注释明确 /cwd 移除）。
• 风险：用户按文档操作会收到未知命令错误。

3. 用户故事（用于演示主线）

角色

• 角色：项目开发者（首次接触项目，需快速理解并完成一个小修复）。
• 目标：在 TUI 中完成“读代码 -> 规划 -> 修改 -> 测试 -> 总结”，并验证权限与会话能力可控。

故事

作为一名开发者，我希望在 NeoCode 的 TUI 里：

1. 能快速启动并指定工作区；
2. 能通过自然语言让 Agent 先分析再实施；
3. 在写文件和命令执行时可清晰审批；
4. 能管理会话、记忆、技能、模型与 Provider；
5. 在长对话中通过 /compact 维持质量；
6. 遇到中断/误操作可恢复，并最终得到可验证结果。

验收标准：

• 能完整跑通一次“分析 + 修改 + 测试 +收尾”任务；
• Slash 命令、快捷键、审批流、会话切换、文件/图片引用均可操作；
• 行为符合本指南“预期结果”。

4. 测试准备

4.1 环境准备

1. 安装并可执行 neocode。
2. 至少配置一个可用 Provider 的 API Key（如 OPENAI_API_KEY）。
3. 准备一个可写测试仓库（建议本仓库）。

4.2 启动命令

neocode --workdir /path/to/project

Windows PowerShell 示例：

neocode --workdir C:\repo\neo-code

4.3 建议演示任务

请先阅读 internal/config 下配置加载相关代码，给出最小修复方案，暂时不要改文件。

5. 全流程测试用例（覆盖所有主要操作）

说明：每条用例都包含“操作步骤 + 预期结果”。按顺序执行可覆盖完整演示路径。

A. 启动与基础交互

1. 启动 TUI：
   操作：neocode --workdir ...
   预期：进入 TUI，状态为 Ready，可输入自然语言。

2. 首次发送消息：
   操作：输入一句自然语言并按 Enter。
   预期：开始运行（Thinking），出现流式响应或工具活动。

3. 输入换行：
   操作：输入多行内容，使用 Ctrl+J 换行。
   预期：不触发发送，输入框增加新行。

4. 取消当前任务：
   操作：运行中按 Ctrl+W。
   预期：状态出现 Canceling / Canceled，任务停止。

5. 忙时排队干预：
   操作：任务运行时再次输入并回车。
   预期：新输入进入 queued intervention；当前任务取消后自动执行排队输入。

B. Slash 命令（完整覆盖）

6. /help：
   操作：输入 /help 或按 Ctrl+Q。
   预期：打开 Slash 命令帮助选择器。

7. /exit：
   操作：输入 /exit（或 Ctrl+U）。
   预期：退出程序。

8. /clear：
   操作：在已有会话输入 /clear。
   预期：切到 Draft（不是仅清空输入框），会话展示清空。

9. /compact 成功路径：
   前置：已有活跃会话且不在运行中。
   操作：输入 /compact。
   预期：状态变为 Compacting，完成后出现 compact 结果消息。

10. /compact 异常路径：
    操作：无活跃会话时执行，或写成 /compact now。
    预期：出现 usage/前置条件错误提示。

11. /session：
    操作：输入 /session，在选择器中切换到其他会话。
    预期：会话内容、标题、上下文随会话切换。

12. /memo：
    操作：输入 /memo。
    预期：显示记忆列表（或空列表提示）。

13. /remember <text>：
    操作：输入 /remember 本项目测试命令是 go test ./...。
    预期：提示保存成功。

14. /forget <keyword>：
    操作：输入 /forget 测试命令。
    预期：提示删除匹配记忆。

15. /skills：
    操作：输入 /skills。
    预期：显示可用技能列表及 active 标记。

16. /skill use <id>：
    前置：存在该 skill，且会话已激活（至少发过一条消息）。
    操作：/skill use xxx。
    预期：提示 Skill activated。

17. /skill off <id>：
    操作：/skill off xxx。
    预期：提示 Skill deactivated。

18. /skill active：
    操作：输入 /skill active。
    预期：显示当前会话已启用技能。

19. /provider：
    操作：输入 /provider。
    预期：打开 Provider 选择器，可上下选择并回车确认。

20. /model：
    操作：输入 /model。
    预期：打开模型选择器，切换后状态更新。

21. /provider add：
    操作：输入 /provider add。
    预期：进入新增 Provider 表单，可 Tab/Shift+Tab 切字段、Enter 提交、Esc 取消。

22. 未知 slash 命令：
    操作：输入 /unknown。
    预期：返回 unknown command 或本地命令错误。

C. 选择器与导航操作

23. 选择器过滤：
    操作：在 /help、/provider、/model 中输入筛选关键字。
    预期：列表动态过滤，光标可上下移动。

24. Esc 关闭选择器：
    操作：任何 picker 中按 Esc。
    预期：关闭 picker，焦点回输入区。

25. 面板焦点切换：
    操作：Tab / Shift+Tab。
    预期：在 Transcript 与 Composer（及有 Todo 时）间循环切换。

26. 聚焦输入区：
    操作：按 Esc（非 picker 场景）。
    预期：焦点回输入框。

D. 文件/图片引用与剪贴板

27. @ 文件引用建议：
    操作：输入 @ 或 @inte...。
    预期：出现文件建议列表，Tab/Enter 可应用建议。

28. Ctrl+O 文件浏览器：
    操作：按 Ctrl+O，选中文件。
    预期：文本文件插入 @相对路径；图片文件添加为附件。

29. @image:<path> 引用：
    操作：输入 @image:/abs/path/to/a.png 后发送。
    预期：图片加入附件，消息发送成功。

30. Ctrl+V 粘贴图片：
    前置：剪贴板中是图片。
    操作：在输入框按 Ctrl+V。
    预期：图片附件增加，状态提示 added image from clipboard。

31. Ctrl+V 粘贴文件路径：
    前置：剪贴板是一个或多个文件路径。
    操作：按 Ctrl+V。
    预期：非图片路径转成 @file 引用；图片路径转附件。

32. Ctrl+V 粘贴长文本：
    操作：粘贴超长文本。
    预期：输入区可见粘贴处理过程，必要时触发折叠/摘要，不应卡死。

33. 附件上限：
    操作：连续添加超过 3 张图片。
    预期：第 4 张时报错 maximum 3 image attachments allowed。

E. 权限审批与 Full Access

34. 手动审批（Allow once）：
    操作：触发写文件或高风险命令，权限弹窗选 y。
    预期：本次请求通过，继续执行。

35. 手动审批（Allow session）：
    操作：在权限弹窗选 a。
    预期：当前会话同类请求减少重复确认。

36. 手动审批（Reject）：
    操作：选 n。
    预期：请求被拒绝，运行给出拒绝相关反馈。

37. Full Access 开启：
    操作：按 Ctrl+F，在风险提示中选 Yes（y）。
    预期：进入 Full Access，后续权限自动通过。

38. Full Access 关闭：
    操作：再次按 Ctrl+F。
    预期：Full Access 关闭，恢复正常审批流程。

F. 会话、上下文与工作区行为

39. 新建会话：
    操作：按 Ctrl+N。
    预期：进入 Draft 新会话。

40. 会话切换限制（忙时）：
    操作：任务运行中执行 /session。
    预期：报错 cannot switch sessions while run or compact is active。

41. --session 接管：
    操作：neocode --session <session_id> 启动。
    预期：加载目标会话历史；若会话内 workdir 丢失，显示告警并保留当前目录。

42. 上下文压缩后续接：
    操作：/compact 后立刻给出“继续目标”说明。
    预期：模型能按新目标继续，不显著引用无关旧上下文。

G. 日志、滚动与复制

43. 日志视图开关：
    操作：Ctrl+L 打开，Ctrl+L 或 Esc 关闭。
    预期：日志面板可正常开关。

44. 视图滚动：
    操作：在 transcript/log 中用 Up/Down、PgUp/PgDn、Home/End、g/G。
    预期：滚动行为符合按键定义，无异常跳动。

45. 文本选择复制：
    操作：鼠标在 transcript 拖拽选中，按 Ctrl+C。
    预期：状态提示 Copied selected text，剪贴板内容正确。

H. Todo 面板（事件驱动）

46. Todo 面板显示：
    前置：任务触发 todo 事件（如代理规划型任务）。
    预期：出现 Todo 面板，显示状态、优先级、owner、更新时间。

47. Todo 操作：
    操作：Up/Down 移动、Enter 看详情、c 折叠/展开。
    预期：行为与状态提示一致（collapsed/expanded/opened）。

I. HTTP URL 唤醒（可选但建议演示）

48. run 首次唤醒：
    操作：neocode daemon encode run ... 生成链接并点击。
    预期：返回 session_id，自动拉起并执行一次提交。

49. review 首次唤醒：
    操作：neocode daemon encode review ...。
    预期：按 review 语义发起审查任务。

50. session_id 复用唤醒：
    操作：点击 reusable_url。
    预期：只接管会话，不重复发送首次提示词。

6. 建议后续动作（文档修正）

为避免用户误操作，建议尽快统一文档口径：

1. 将 /clear 描述改为“切到 Draft/清空当前会话展示”。
2. 将 Ctrl+O 描述改为“打开文件浏览器（插入文件引用/图片）”。
3. 移除或更正 /cwd 相关文案。

[creatang]

在已经配置好环境变量的情况下，从仓库clone最新源码进行测试

1. 启动方式等待下载方式无误后进行测试
2. 自然语言发送无误，大模型思考时会展示think..
3. 在终端操作中，无热键冲突ctrl+j可以正常换行
4. 在终端操作中，无热键冲突ctrl+w可以正常终止任务
5. 新指令可直接插队干预
6. 在终端操作中，无热键冲突ctrl+q ，/help可以正常打开帮助界面
7. /exit 可以正常退出neocode
8. /clear可以正常清空会话展示
9. /compact 指令意义不明确，像是无用指令，或者是用户使用指令辅助不明确
10. 同上
11. /session 会话显示无误
12. /memo会以日志方式展示记忆列表
13. /remember 可以正常保存，但是实际是用在哪里？不明确实际使用意义
14. /forget 测试无误，但是实际使用不清楚用法
15. /skills可以正常展示存在的skill
16. /skill use id不太明确
17. /skill off 同上
18. /skill active 在有会话时会展示会话当前活跃的skill，无会话会进行错误提示
19. /provider可正常打开 Provider 选择器，可上下选择并回车确认。
20. /model可正常打开模型选择器，切换后状态更新
21. /provider add可正常进入新增 Provider 表单，可 Tab/Shift+Tab 切字段、Enter 提交、Esc 取消。
22. 未知 slash 命令，会返回 unknown command 或本地命令错误。
23. 选择器过滤,slash指令中输入筛选关键字，列表会动态过滤，光标可上下移动。
24. Esc 关闭选择器，可正常关闭 picker，焦点回输入区
25. 面板焦点切换，这个功能为废止功能，后续将TAB作为plan/build的切换
26. 输入区聚焦：现在是长期聚焦在输入区
27. @ 文件引用建议，会在当前工作区应用文件，并有建议选择列表
28. Ctrl+O 文件浏览，这个功能应该是冗余功能，后续删除
29. @image:重复说明，引用文件路径即可
30. Ctrl+V 粘贴图片：会粘贴图片路径
31. 同上
32. 粘贴超长文本，会展示【paste x line】
33. 附件现在没有上限
    34-38. 均可以正常提示
34. 新建会话正常
35. 会话切换好像执行中是不行的
36. --session 接管，暂时无法测试，要安装到本地有neocode指令才可以测试
37. /compact 压缩测试需要长工作完成（暂时未测试）
38. 日志视图可以正常打开
39. 视图可以正常滚动
40. 鼠标选择复制正常
41. todo面板可以正常显示
42. todo面板可以正常查看折叠（但是样式不好看需要优化
43. HTTP URL 唤醒（此部分暂时未测试）

需要明确/修改部分

• /compact 指令意义不明确，像是无用指令
• /remember ， /forget 不明确实际使用意义
• 在使用带有空格的slash指令进行补全会出现部分多词的异常
• /skill use ，/skill off id不太明确，在skills中未看到id
• 面板焦点切换，这个功能为废止功能，后续将TAB作为plan/build的切换
• Ctrl+O 文件浏览，这个功能应该是冗余功能，后续删除
• 优化todo展示面板
• 粘贴的缓冲区似乎没有刷新，有异常
• 暂时未测试部分：
• --session 接管，暂时无法测试，要安装到本地有neocode指令才可以测试
• /compact 压缩测试需要长工作完成（暂时未测试）
• HTTP URL 唤醒（此部分暂时未测试）

[creatang]

skill部分（id为图示前面部分）

[creatang]

/skill use 和/skill off 正在考究功能的可拓展性，/compact为文本压缩也在讨论

[phantom5099]

时间：2026.05.07
卡点：未对接完成