用途：指导在 Konsole 中交互测试 mastracode 的终端 UI（TUI），涵盖模型配置、线程生命周期、任务状态隔离与常见阻塞问题。
构建与准备：在仓库根目录执行 COREPACK_ENABLE_STRICT=0 pnpm build:mastracode。若 pnpm 的 corepack 有问题，可执行 npm install -g pnpm@10.11.0。若因 @mastra/core 或 @mastra/memory 既有的 DTS 错误导致构建失败，可用 COREPACK_ENABLE_STRICT=0 pnpm turbo build --filter ./mastracode --continue 继续构建下游包。单元测试报缺少 @mastra/core/workspace 时，先运行 pnpm build:core。
启动：进入 mastracode 目录后执行 COREPACK_ENABLE_STRICT=0 pnpm cli。首次启动可能显示设置向导，可选择 Skip 进入主 TUI。
自定义提供方：若无 Anthropic/OpenAI 直连密钥，可编辑 ~/.local/share/mastracode/settings.json，配置 customProviders（如 OpenRouter，URL 为 https://openrouter.ai/api/v1），设置 models.activeModelPackId 与 modeDefaults，并在 customModelPacks 中定义 Custom 包，引用 openrouter/minimax/minimax-m2.7 等模型。启动后可通过 /models 选择 Custom 并 Activate，确认状态栏显示正确模型。OPENROUTER_API_KEY 用于 OpenRouter 自定义提供方。
常用命令：/new 新建空线程，/threads 打开线程选择器（↑↓ 导航、Enter 选择），/clone 克隆当前线程，/models 切换模型包，/help 查看全部命令。
渲染测试：针对边框对齐、内边距、换行等视觉问题，可写 tsx 脚本直接渲染组件，执行 npx tsx test-script.ts。直接导入组件（如 UserMessageComponent），在 40、60、80、100、120+ 等宽度渲染并剥离 ANSI 码测量可见宽度，断言所有行可见宽度一致；测量时过滤 Spacer 的尾部空行；可用内联模拟旧逻辑做前后对比。
线程状态隔离测试：让模型显式调用 task_write 创建 3 个任务（如 Fix login bug、Add unit tests、Update docs），确认状态行与输入框之间出现“Tasks [0/N completed]”及 ○/▶/✓ 图标；测试 /new 应使任务进度组件完全消失；测试 /threads 切回原线程应恢复消息与任务；克隆线程任务应为空（任务不持久化到克隆）。
常见问题：观测记忆（OM）模型报 GOOGLE_GENERATIVE_AI_API_KEY 错误时，可通过 /om 或 settings.json 的 models.omModelOverride 改设为 OpenRouter 模型；能力较弱的模型可能不调用工具，需明确指定工具名；改 settings.json 后状态栏模型不对，需在 TUI 中用 /models 激活自定义包；pnpm cli 报模块解析错误时，在仓库根目录构建全部传递依赖。用户消息框在按 Enter 后即渲染、无需 LLM 响应，可用于测试渲染问题。
单元测试：在仓库根目录执行 COREPACK_ENABLE_STRICT=0 pnpm --filter mastracode exec vitest run src/tui/tests/，注意可能存在既有失败用例，聚焦待验证功能相关测试。