Appearance
功能规格说明
本目录包含功能规格说明文件，作为功能设计和实现的唯一真实来源。
每个规格是一个独立的 markdown 文件（按主题分组存放于子目录），包含用户故事与验收场景。
为什么没有 Plan？
- 内置能力足够强大。 Plan 模式结合权限系统控制读写范围，Task 系统对多 Agent 协作友好且自带系统提示防止上下文丢失。
- 无法仅靠思考设计出完美方案。 边界情况、API 怪癖、集成问题只有在实现中才会暴露，静态 plan 注定频繁改动、迅速过时，不如交给 Agent 用完即弃。
统计
| 指标 | 数量 |
|---|---|
| 规格文件 | 86 |
| 用户故事 | 528 |
| 验收场景 | 2,585 |
| 测试用例 | 8,339 |
规格列表
Agent 核心
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| 文件系统工具 | Read, Write, Edit, Glob, Grep 文件操作工具 | 4 | 19 | 规格 |
| Bash 工具 | Bash, BashOutput, KillBash shell 命令执行工具 | 8 | 37 | 规格 |
| WebFetch 工具 | 获取 URL 内容，HTML 转 markdown，AI 模型处理，支持缓存 | 5 | 13 | 规格 |
| Artifact 工具 | 发布本地 HTML/Markdown 为默认私有的可分享网页，读取 artifact 原文/摘要 | 8 | 55 | 规格 |
| Exec 工具 | 把 MCP 工具池收敛为一个可编排的沙箱脚本工具 | 10 | 83 | 规格 |
| LSP 集成 | Language Server Protocol 代码智能（定义跳转、引用查找、悬停信息） | 3 | 4 | 规格 |
| 自定义工具 buildTool() | buildTool() 工厂方法，供 SDK 用户定义自定义工具 | 3 | 7 | 规格 |
| Agent 配置 | 基于构造函数的配置替代环境变量，支持 max output tokens 和自定义 headers | 14 | 58 | 规格 |
| 消息压缩 | 对话历史和用户输入大小管理 | 15 | 73 | 规格 |
| Prompt 工程 | Prompt 构建和管理框架 | 5 | 14 | 规格 |
| Prompt 缓存控制 | 基于正则匹配的显式缓存标记，支持 Claude、Qwen 等多种模型 | 5 | 26 | 规格 |
| 记忆管理 | 通过记忆文件在对话间持久化信息 | 15 | 70 | 规格 |
| 流式输出 | 助手消息和工具参数的实时内容流式传输 | 10 | 53 | 规格 |
| AI 错误处理 | 处理输出 token 限制超限，提示 agent 将工作拆分为更小的块；连续截断达到上限时终止回合；截断恢复时保留上一轮推理内容 | 8 | 16 | 规格 |
| 工具权限系统 | 权限系统，支持模式、通配符、拒绝规则、信任、acceptEdits、dontAsk、安全区 | 21 | 92 | 规格 |
| Plan 模式 | Shift+Tab plan 模式，只读分析并增量编辑 plan 文件 | 15 | 85 | 规格 |
| Agent 生命周期 | destroy() 的确定性排空语义：存活工作注册表、destroy 后公开 API 抛错、destroy 终态守卫（防幽灵 dispatch） | 3 | 12 | 规格 |
| 后台任务完成通知 | Bash/Agent/Workflow 后台任务完成时注入主对话的 task-notification 消息语义（UI 隐藏、模型可见、持久化） | 1 | 5 | 规格 |
| 会话文件保留清理 | 按可配置保留期清理过期的会话 jsonl 文件（对齐 Claude Code） | 4 | 14 | 规格 |
交互与 UI
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| 会话管理 | 高性能、基于项目的会话管理系统 | 13 | 85 | 规格 |
| Markdown 渲染 | 终端 Markdown 渲染，Ink 组件支持标题、列表、代码块、表格 | 3 | 12 | 规格 |
| 消息渲染 | 基于 Ink 的消息/块渲染——静态历史 + 动态工具执行 | 8 | 39 | 规格 |
| 图片粘贴 | 从剪贴板粘贴图片到聊天输入，支持占位符和附件；粘贴时就降到 2000 像素预算，出站图片再按 2000 像素 / 5MB 预算统一收口 | 8 | 31 | 规格 |
| 文件选择器 | 快速文件/目录选择器 UI 组件 | 4 | 13 | 规格 |
| 长文本占位符 | 用 `[LongText#ID]` 占位符替换粘贴的长文本，提交时展开 | 1 | 2 | 规格 |
| 确认 UI | 工具权限审批的确认对话框 UI 组件 | 10 | 44 | 规格 |
| AskUserQuestion 工具 | 结构化用户交互工具，支持选项 | 5 | 25 | 规格 |
| Clear 命令 | `/clear` 命令重置对话历史和会话 | 2 | 5 | 规格 |
| Rewind 命令 | `/rewind` 回退对话到上一条用户消息，同时回退文件变更 | 5 | 19 | 规格 |
| Print 模式 | `-p` 模式下的纯净响应输出，抑制所有子代理内部信息 | 4 | 13 | 规格 |
| 工具选择 | CLI `--tools` 标志限制 agent 使用特定工具集 | 4 | 5 | 规格 |
| 斜杠命令 | 用户可调用的自定义斜杠命令系统 | 6 | 20 | 规格 |
| Bash 模式 | `!` 前缀直接从聊天输入执行 shell 命令 | 3 | 4 | 规格 |
| 技能列表命令 | 通过 /skills 斜杠命令浏览和查看所有可用技能 | 10 | 49 | 规格 |
| 钩子命令 | 通过 /hooks 斜杠命令查看已配置的钩子 | 3 | 12 | 规格 |
| Help 命令 | `/help` 交互式帮助，显示快捷键、内置命令和插件命令 | 3 | 7 | 规格 |
| Model 命令 | `/model` 交互式切换已配置的 AI 模型（CLI 选择器 + Webview 菜单，三端可用） | 4 | 16 | 规格 |
| BTW 命令 | `/btw` 旁路问题，绕过主消息队列 | 4 | 32 | 规格 |
| 状态栏 | 左下角状态栏组件，用于模式和 shell 命令状态显示 | 1 | 5 | 规格 |
| 通知组件 | 右下角 Notifications 组件：token 用量与登录提示 | 2 | 9 | 规格 |
| Status 命令 | `/status` 显示版本、会话 ID、cwd、模型和运行时信息 | 1 | 2 | 规格 |
| Update 命令 | `wave update` / `wave-code update` 更新到最新版本 | 3 | 6 | 规格 |
| 历史搜索 | Ctrl+R 历史搜索，复用 `~/.wave/history.jsonl` 中的历史提示 | 2 | 6 | 规格 |
| 输入编辑键与清空 | 修复 SSH/tmux 退格失效、新增 Ctrl+U/K/W/A/E 行编辑键与空闲态 Esc 双击清空输入 | 5 | 23 | 规格 |
| Stdio 传输层 | 编辑器插件与 `wave --stdio` 子进程的 JSON-RPC 通信，CLI 解析/安装/升级、多会话路由、错误诊断 | 11 | 74 | 规格 |
| IDE 插件 | VS Code/JetBrains 共享 React webview 的横切关注点：主题变量、共享包与构建产物、生命周期与消息协议、IDE 专属对话框 | 4 | 12 | 规格 |
| 插件更新策略 | VS Code 扩展与 JetBrains 插件的更新统一交给官方市场机制，插件自身不再内置更新检查 | 2 | 5 | 规格 |
| Webview 链接解析 | webview 中链接的解析与点击行为：消息 markdown、行内代码内的 URL、围栏代码块内的 URL、bash 命令输出中的 URL | 3 | 20 | 规格 |
| Webview 文件路径点击识别 | 助手文本 markdown 中文件路径的识别与点击打开：行内代码与正文纯文本两通道、行号后缀、点击打开文件面板/编辑器 | 5 | 34 | 规格 |
| 操作确认对话框 | 3 | 11 | 规格 | |
| 文本粘贴 | 修复粘贴文本被立即提交：对齐 Claude Code 启用 bracketed paste（DECSET 2004）并在 stdin 原始字节层识别粘贴标记，粘贴内容仅插入不提交 | 1 | 6 | 规格 |
| Daemon 客户端命令 | `wave daemon create/list/status/wait/send/respond/abort/destroy/stop/restart` — 按需创建、查看、阻塞等待空闲、续聊、审批、中断、销毁与优雅停止/重启 daemon 托管的远端后台会话 | 10 | 76 | 规格 |
桌面应用
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| 桌面端壳层与分发 | CodeWave IDE 桌面端壳层：内置 CLI 交付、SSO 登录、与 IDE 一致的交互、跨平台分发、自动更新、主题设置、应用菜单栏与 macOS 隐藏标题栏 | 12 | 70 | 规格 |
| 桌面端会话与远程 | CodeWave IDE 桌面端会话与远程：会话管理、SSH 远程主机/后台/重连、远程 daemon 常驻、历史恢复、worktree 隔离、快捷键、后台通知与会话状态看板 | 13 | 134 | 规格 |
| 桌面端布局与分屏 | CodeWave IDE 桌面端布局与分屏：侧边栏收起、侧边栏滚动区间、并排多对话、新会话并排、分屏重排调宽与两行布局 | 7 | 48 | 规格 |
| 桌面端面板与工作区 | CodeWave IDE 桌面端右侧面板与工作区：一级 Tab 栏/空态与＋/展开折叠与空间守卫、会话变更差异面板（变更基准与提交选择、文件树导航、统一/并排视图、大规模差异降级）、行评论与内嵌终端 | 9 | 77 | 规格 |
| 桌面端原型预览 | CodeWave IDE 桌面端独有原型预览闭环：localhost 原型预览、本地 HTML 文件预览、元素评论与全屏 | 4 | 28 | 规格 |
| 桌面端文件面板 | CodeWave IDE 桌面端文件面板：工具路径只读查看、自动刷新、文件搜索与拖拽上传 | 4 | 45 | 规格 |
| 桌面端设置与账户 | CodeWave IDE 桌面端设置页面、上下文用量指示器与账户卡片（用量常驻区/个人信息纯功能菜单/更新按钮状态机） | 6 | 67 | 规格 |
| 桌面对话流排版、表格与链接 | CodeWave IDE 桌面端对话流（助手消息 Markdown）的文字角色、表格展示与对齐、链接角色，以及键盘可达与无障碍；含用户明示接受的对比度偏离 | 6 | 39 | 规格 |
多 Agent 与并发
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| 子代理 | 将任务委派给预配置 AI 人格的子代理支持 | 5 | 20 | 规格 |
| 内置子代理 | Explore agent 内置子代理支持 | 2 | 4 | 规格 |
| 通用代理 | 内置子代理，用于复杂研究、代码搜索和多步骤任务 | 2 | 4 | 规格 |
| Plan 子代理 | 内置 Plan 子代理，在编码前设计实现方案 | 4 | 10 | 规格 |
| Bash 子代理 | 内置 Bash 子代理，执行 shell 命令 | 1 | 2 | 规格 |
| 任务后台执行 | `run_in_background`、`TaskOutput`/`TaskStop` 工具，`/tasks` 命令替代 `/bashes` | 7 | 26 | 规格 |
| 任务管理工具 | TaskCreate/TaskGet/TaskUpdate/TaskList，`~/.wave/tasks/` 存储和任务列表 UI | 6 | 16 | 规格 |
| Workflow 编排 | 确定性多子代理编排，支持 pipeline、parallel 和 phase 控制流 | 6 | 19 | 规格 |
| CLI Worktree | `-w/--worktree` 隔离的 git worktree，位于 `.wave/worktrees/`，支持安全退出 | 15 | 68 | 规格 |
| Agents 命令 | `/agents` 查看与管理当前会话可见的 agent 定义 | 8 | 38 | 规格 |
| 视觉子代理 | WAVE_VISION_MODEL 环境变量 + 内置 vision 子代理，让非视觉主模型可委托图像识别 | 3 | 9 | 规格 |
扩展与生态
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| Agent 技能 | 可发现的技能包，通过 SKILL.md 文件提供模型可调用的能力 | 9 | 31 | 规格 |
| 内置 Settings 技能 | 引导用户配置 `settings.json`、钩子和 Wave 设置管理 | 3 | 4 | 规格 |
| Init 命令 | `/init` 斜杠命令，使用 init-prompt.md 进行项目初始化 | 2 | 4 | 规格 |
| Code Review 技能 | 审查当前 `git diff` 的正确性 bug，附带文件/行号引用 | 5 | 19 | 规格 |
| Simplify 技能 | 审查已变更代码的质量问题（重复、低效）并通过 `/simplify` 自动修复 | 3 | 10 | 规格 |
| MCP | Model Context Protocol 外部工具和上下文源支持 | 10 | 50 | 规格 |
| 内置 SDD 插件 | 规格优先工作流：specify 技能、会话引导与规格校验 | 9 | 35 | 规格 |
| 插件系统 | 插件系统，支持 marketplace、作用域、技能、LSP、MCP、钩子、代理 | 12 | 94 | 规格 |
自动化
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| 钩子系统 | 扩展 Wave 行为的事件钩子系统 | 22 | 74 | 规格 |
| Loop 命令 | `/loop` 通过 cron 调度循环提示（如 `/loop 5m check the build`），支持持久化和多会话调度锁 | 2 | 3 | 规格 |
| 会话生命周期钩子 | SessionStart / SessionEnd 钩子在会话启动与运行时恢复时的行为 | 4 | 12 | 规格 |
企业管控
| 功能 | 描述 | 用户故事 | 验收场景 | 链接 |
|---|---|---|---|---|
| SSO 认证 | /login 浏览器 SSO 登录、token 存储、自动 API 代理路由 | 6 | 29 | 规格 |
| 服务端托管配置 | 从 Wave AI 下载并应用托管设置，支持校验和缓存和合并优先级 | 4 | 15 | 规格 |
| OpenTelemetry 集成 | OpenTelemetry 指标、追踪和日志插桩，支持多种导出器（jsonl、OTLP） | 3 | 10 | 规格 |
| 用量追踪 | SDK 用量追踪回调（`onUsagesChange`），用于 AI 调用和压缩 | 4 | 13 | 规格 |
上下文消息结构总览
发送给 AI 模型的 messages 数组按以下顺序组装：
| 位置 | 角色 | 内容 | 缓存标记 | 持久化 | 用户可见 | 说明 |
|---|---|---|---|---|---|---|
| [0] | system | 基础系统提示词 + 任务执行准则 + 行动准则 + 工具策略 + 输出效率 + 语气风格 | 有 | 不持久化 | 否 | 子代理替换基础系统提示词，其余相同 |
语言指令 + 环境信息（主代理 # Environment 列表 / 子代理 Notes + <env> 块）+ 自动记忆 (MEMORY.md) | 无 | 不持久化 | 否 | |||
| [1] | user (meta) | <system-reminder>: 项目 AGENTS.md + 用户 AGENTS.md + 无条件规则 | 无 | 不持久化，每轮插入头部 | 否 | 唯一每轮注入 |
| 历史 | user / assistant / tool | 文本块 / 图片块 / 工具块 / 后台任务通知块 / 推理块 | 最后一条有 | 持久化到 session JSONL | 是 | |
| user (isMeta) | 计划模式提醒 / 条件规则 / 任务提醒 / SessionStart Hook 上下文 / 后台任务通知 / Token 限制续写 | 同上 | 同上 | 否 | 触发时插入当时的结尾，各类型有独立触发条件 |
专用调用：
- Fork 复用主对话上下文（复用主系统提示词、工具、模型与生成参数，指令作为末尾 user 消息追加，命中 prompt cache；无独立系统提示词）：上下文压缩（
runCompactFork→runForkLoop）、自动记忆提取（runAutoMemoryFork→runForkLoop）、BTW 旁路问题（runBtwFork，同构的内联单轮调用）。 - 独立调用（自带独立系统提示词，不经过主系统提示词组装）：网页内容提取（
processWebContent，内置WEB_CONTENT_SYSTEM_PROMPT，独立请求，不走会话历史）。 - 常规子代理机制：Workflow 结构化输出——spawn 常规子代理（general-purpose），schema 指令追加到 prompt 末尾并强制 StructuredOutput
tool_choice，非独立调用路径。