码行客户端 verseles/codewalk

CodeWalk

https://github.com/user-attachments/assets/032f64e2-e8ee-4024-b49a-ca95a774653f

CodeWalk Logo

OpenCode 服务器模式的原生客户端（真的很快！！），跨平台。用 Flutter 构建，提供对话式界面，通过 HTTP API 和流式事件完成基于会话的 AI 编码交互。

🏷️ v1.244.0 新增： 助手回复现在能渲染基础 HTML 格式和原生进度条。查看支持的标签和示例。

📰 新消息： CodeWalk 现在能直接在浏览器里跑 —— 打开 https://codewalk.verseles.com，添加你的 OpenCode 服务器配置档，就能开始聊天。无需安装。

你的 OpenCode 服务器必须允许该 Web 来源，否则浏览器会拦截连接：

opencode serve --cors "https://codewalk.verseles.com"

功能

- 🌐 完整翻译成 14 种语言：English、Português (Brasil)、Español、Deutsch、Français、Italiano、Русский、中文、日本語、한국어、हिन्दी、বাংলা、العربية、اردو —— 支持即时切换、自动检测系统默认语言，阿拉伯语和乌尔都语使用 RTL 布局
- 💬 实时 AI 聊天，支持流式响应、加载更早的历史记录，从缓存即时重开会话
- 🗂 以项目为中心的侧边栏，对话按项目分组，支持置顶，兼容 Git 仓库和普通文件夹
- 🖧 多服务器配置档，支持健康检查、切换活动服务器，可在设置里安装并启动 OpenCode 服务器
- 🧠 模型和服务商选择，支持变体、收藏和推理控制
- 🗃 窗口顶部的会话标签页，浏览器风格，桌面端集成进标题栏
- 📁 内置文件管理器和编辑器 —— 浏览、打开、重命名、复制和编辑项目文件，支持自动保存、撤销重做，高亮器自带的所有语言都有语法高亮
- 📎 拖入或粘贴即可附加图片和 PDF，包括直接从剪贴板粘贴的截图
- ↪️ 把消息转发到一个或多个其他会话
- 🧱 块渲染模式 —— 每个块完成时才显示，不用盯着文字一个字符一个字符地流
- 📉 上下文用量指标，一眼看出会话占用了多少窗口
- 🎨 自动从仓库发现每个项目的图标，会话标签页配色与之匹配，可在「外观」里关闭
- 📶 流量节省模式，在蜂窝网络下缩减后台同步
- 🖥 服务器托管的 PTY 终端 —— 跑在 OpenCode 主机上的真实命令行，内嵌在应用里
- 🎙 所有平台都支持语音转文字，包括 Linux
- 🔊 助手消息朗读，语速和音调可调
- 📊 主机配额监控，支持 Claude、OpenRouter、Codex/OpenAI、Gemini、GitHub Copilot、OpenCode Go、NanoGPT、Wafer、Kimi、ZhipuAI、MiniMax、z.ai、Cursor 和 Ollama Cloud
- 📈 Mermaid 图表和 LaTeX 数学公式直接内联渲染，内容来自对话本身
- 🏷️ 助手回复中的基础 HTML — 粗体、斜体、下划线、换行、下标/上标，以及跟随应用主题的原生 进度条
- 📤 把任意消息分享为主题图片，或把整个会话导出为 Markdown 或 JSON
- ↩️ 回退到任意更早的轮次，草稿一并恢复
- 💬 预设回答，支持全局或按项目限定范围
- ⌨️ 桌面端键盘优先，包括 Alt+Tab 式会话切换
- 🔐 Cloudflare Access OAuth 配合 PKCE，适用于部署在企业反向代理后面的服务器
- 🔔 交互式权限与提问提示，答案到达时通知自动清除
- 🔄 应用内更新，自动检查并直接安装
- 📱 响应式 Material 3，覆盖 Linux、Windows、macOS、Web 和 Android，提供五档密度

助手回复中的基础 HTML

支持的标签与示例

助手回复可以把下面这些不区分大小写的 HTML 标签与 Markdown 混用。格式和进度条在移动端与桌面端都跟随应用主题。

| 标签 | 效果 | 示例 |
| | 粗体 | Important |
| | 斜体 | Note |
| | 下划线 | Highlighted |
| | 换行； 和 同样可用 | First lineSecond line |
| | 下标 | H2O |
| | 上标 | x2 |
| | 原生进度条 | Loading |

格式标签可以嵌套，例如 Bold and italic。进度条默认 max="1"；省略 value 得到不确定进度条，例如 。显式自闭合的 progress 标签同样可用。

代码示例里的标签保持字面显示，复制整条消息会保留其源标记。Markdown 链接文字中省略下划线/下标/上标装饰，以保证链接可点击。仅支持上面列出的标签；任意 HTML 和 CSS 不会渲染。

一条命令安装

使用 install.cat 模式安装：

- Linux 和 macOS

curl -fsSL install.cat/verseles/codewalk | sh

- Windows（PowerShell）

irm install.cat/verseles/codewalk | iex

随时再次运行同一条命令，即可更新/重装到最新的 GitHub release。

在 Linux 和 macOS 上，install.sh 还接受发布通道。为 sh 设置变量，由它运行脚本：

Stay on CodeWalk 1 (remembered for later updates and reinstalls)
curl -fsSL install.cat/verseles/codewalk | CODEWALK_CHANNEL=v1 sh
Opt in to CodeWalk 2 betas
curl -fsSL install.cat/verseles/codewalk | CODEWALK_CHANNEL=beta CODEWALK_MIGRATION=accept-v2 sh
Install one exact release
curl -fsSL install.cat/verseles/codewalk | CODEWALK_VERSION=v1.265.1 sh

新安装使用 stable 通道；已有安装会保留其通道安装时用的是哪个版本。把 CodeWalk 1 安装迁移到 CodeWalk 2 需要 CODEWALK_MIGRATION=accept-v2，因为 CodeWalk 2 只能配合 OpenCode 2 服务器使用；不设置这个变量，安装程序会停下，什么都不改。Windows 安装程序始终安装最新版本。

安装程序会自动挑选适合你平台的版本。

在 Linux 上，发布文件安装在 ${XDG_DATA_HOME:-$HOME/.local/share}/codewalk-app 下，与用户数据分开存放。已有安装把偏好设置和缓存留在旧的 codewalk 支持目录里；全新安装使用 com.verseles.codewalk。更新和卸载只删除应用文件，两个用户数据目录都不动。

- Android

在 Android 浏览器中打开下面的链接下载 APK： install.cat/verseles/codewalk

卸载

- Linux 和 macOS

curl -fsSL https://raw.githubusercontent.com/verseles/codewalk/main/uninstall.sh | sh

- Windows（PowerShell）

irm https://raw.githubusercontent.com/verseles/codewalk/main/uninstall.ps1 | iex

快速上手

前置条件

- Flutter SDK（>=3.8.1）
- Dart SDK
- 一个兼容 OpenCode 的服务器实例
- 目标平台的工具链：
- Linux 桌面：clang、cmake、ninja、pkg-config
- Windows 桌面：在 Windows 主机上构建
- macOS 桌面：在 macOS 主机上构建

配置

1. 安装依赖：

flutter pub get

2. 运行应用（示例）：

flutter run -d linux
flutter run -d chrome
flutter run -d android

3. 构建产物（示例）： flutter build linux flutter build web

Make 目标

make check # deps + codegen + analyze + coverage/v2-tool fixtures + full tests
make check-fast # same setup, with the fast test selection
make test-fast # excludes slow/integration; includes ChatPage smoke scenarios
make test-chat # ChatPage smoke + extended scenarios
make test-web # browser capability tests; requires Chrome/Chromium
make test-coverage-tools # LCOV validation and threshold regression fixtures
make test-release-tools # v2 beta release plan, publication guards and tooling
make coverage # full tests with coverage + global and protected-file floors
make web # build the legacy Flutter web app into build/web (CodeWalk 1 versions only)
make android # build the legacy arm64 APK (CodeWalk 1 versions only)
make release V=beta # main: cut the next v2.0.0-beta.N (DRY_RUN=1 prints the plan only)

在 main 分支上，Release 工作流只发布 v2.0.0-beta.N 标签：Android arm64 和 Linux x64/ARM64 由 lib/main_v2.dart 构建，经过校验（v2 入口库、生产签名、versionCode 高于所有已发布 APK、摘要），然后作为预发布版本发布，永远不会成为 latest。从 main 手动触发并带上 dry_run_version 时，会构建并校验同样的产物，但不发布。
Stable、patch 和 CodeWalk 1 三个版本都在 v1 分支上发布。

迭代时跑聚焦测试，到稳定验证关口再跑 make check。测试目标默认开四个 worker；主机合适时用 TEST_JOBS=N 覆盖。make test-fast 保留五个 ChatPage 冒烟场景，完整检查里仍要求跑扩展套件。浏览器测试单独跑，用 make test-web，也在 CI 里跑；浏览器没被自动发现时，设置 CHROME_EXECUTABLE。

完整 make test 套件默认有 10 分钟执行上限。主机较慢时，make check TEST_TIMEOUT=15m 保留全部测试和单个测试的超时，同时给整套测试更大的有限预算。上限到期会附带信号诊断；这算检查失败或不完整，不算通过。

覆盖率过滤用 Python 3，不需要系统 lcov。关口校验新生成的 Flutter LCOV 记录，排除 .g.dart、本地化和插件注册源文件，并执行全局下限以及 tool/ci/coverage_baseline.tsv 里经过评审的逐文件下限。受保护源文件缺失、总计不一致、源路径不属于本仓库、覆盖率低于配置下限，都会让关口失败；旧的过滤产物绝不会拿来兜底。下限要有意修改，不能自动重新生成或调低。

需要可测试的 Android 产物时，检查通过后运行 HEY_CAPTION="specific caption" make android。

main 上的 V2 开发目标

保留的应用仍默认用 lib/main.dart。下面这些独立目标显式选择当前生效的 v2 实现：

make v2-native-check # all workspace packages, architecture/l10n and VM/CHP tests
make v2-linux-debug # Linux host architecture: x64 or arm64
make v2-android-debug # Linux x64 build host; Android arm64, split-per-ABI debug APK

用全新检出或副本，并解析好依赖，再做原生编译。已有的 build/linux 或 build/app 产物会让构建拒绝执行，而不是被删除或覆盖。build/native-evidence/ 下的构建回执记录源修订、Flutter SDK、显式指定的 lib/main_v2.dart 目标和产物哈希，包括 ABI/ELF 检查和非空 debug kernel 检查。CI 用独立的原生检查和编译器任务；这个原生聚合不需要浏览器。

这些 debug 构建只提供编译证据，不代表 release AOT、签名、安装或 MVP 验收。Android/Linux 是 MVP 目标；完整的延后平台证据另行保留。make v2-foundations 保留 Chrome 和 Web 检查；检查器的 --no-build 选项只省略 Web 构建。

自动 push/PR CI 在 v2_foundations 和 v2_native_checks 里都跑 make v2-native-check，用严格的 native 关口保留现有状态上下文。V2 deferred Web checkpoint（v2-deferred-web.yml）只能手动触发，跑完整的 make v2-foundations 配置档。它失败就是失败；延迟执行的 Chrome/Web 检查不属于原生 MVP 或 full-GA 验收。quality 中保留的旧版浏览器检查，以及旧版 Web 部署，仍然各自独立。

在显式原生 v2 应用中，展开已加载的目录行，选择 View history，打开配套的只读阅读器。返回会回到目录。刷新和分页都是手动操作，且有上限；发送和实时更新不可用。这个增量阅读器不是最终与 v1 对齐的聊天界面，也不是已安装设备/MVP 验收结果。

隔离的 Linux 开发预览

Linux 原生 CI 任务会打包 codewalk-v2-preview-linux-x64.tar.gz，并在 Xvfb 下打开这些确切的归档字节，然后才提供已验证预览产物。成功结果会附带截图、完成的冒烟报告和归档校验和。仅编译成功不算完成这项视觉验证。

在兼容的 Ubuntu 24.04 桌面（X11/XWayland）上，解压对应机器架构的已验证归档，运行 ./Open-preview.sh；预览会拒绝在其他架构的主机上打开。不需要 Flutter SDK，也不需要编译。启动器依赖常规桌面运行时、Python 3、D-Bus 和 GNOME Keyring；缺少前置条件时它会报告，而不会回退到主机的凭据会话。包内的 PREVIEW.txt 包含打开和移除步骤。

预览使用单独标记的锁定配置档、私有 D-Bus 和受监管的加密临时 keyring。非机密偏好会持久保存；启动器会话关闭时凭据会被清除。这是常规存储隔离，不是 OS 沙箱，也不是 GPU/Wayland 验收、更新器或公开 beta。应用不会注册新的桌面/URI 处理器，也不会替换已安装的 v1 应用。冒烟报告会列出实际操作的界面，以及未测试的服务器/设备路径。

make v2-linux-preview-package # requires the fresh verified build for this host (x64 or arm64)
make v2-linux-preview-smoke # requires an existing Xvfb/X11 visual QA runtime
make v2-android-preview # Linux x64 build host; profile APK under the preview identity

所有者预览（CP1）

手动 V2 owner preview 工作流（v2-owner-preview.yml）从派发的提交构建每个预览，并且只保留它启动过的预览：Linux x64 和 ARM64 归档（各自在对应架构上构建，并在 Xvfb 下冒烟测试）以及 Android arm64 APK。APK 会作为 CodeWalk v2 Preview（com.verseles.codewalk.v2preview，debug 签名的配置档构建）安装在 CodeWalk v1 旁边，绝不替换它或其数据。CI 会在 Android 16 模拟器上启动同一构建的 x86_64 拆分；arm64 APK 本身会先在所有者设备上启动。工作流只产出产物：不发布、不打标签、不部署任何东西。

Web 部署：Cloudflare Pages 或静态托管

CodeWalk 的 Web 构建产物是静态 Flutter 应用。构建过程不需要 Cloudflare 密钥，也不需要编译期的 OpenCode 凭据；用户打开部署好的站点后，在应用内添加自己的 OpenCode 服务器配置档即可。

1. 构建 Web 应用：

make web

这条命令会执行 flutter build web --release --base-href "/"，把静态站点写入 build/web。

2. 部署到子路径时，设置一个以 / 开头、也以 / 结尾的 base href：

WEB_BASE_HREF="/codewalk/" make web

3. 根路径托管时，在本地预览静态产物：

python3 -m http.server 8080 --directory build/web

如果你用子路径 WEB_BASE_HREF 构建，就要在相同路径前缀下预览；否则浏览器请求的资源 URL 会和本地服务器根路径对不上。

4. 把 build/web 发布到 Cloudflare Pages。

用 Wrangler 直接上传：

npx wrangler pages deploy build/web --project-name codewalk

Cloudflare Pages 的 Git 设置（前提是你的 Pages 构建镜像里有 Flutter）：

Build command: make web
Build output directory: build/web
Root directory: (leave blank)

5. 配置浏览器应用要连接的 OpenCode 服务器。如果 Pages 部署地址是 https://your-codewalk.pages.dev，就放行这个确切的源：

export OPENCODE_SERVER_PASSWORD="choose-a-password"
opencode serve --hostname 0.0.0.0 --port 4096 --cors "https://your-codewalk.pages.dev"

6. 在 Web 应用里添加 CodeWalk 服务器配置档，填入可访问的服务器 URL 和 Basic Auth 凭据。

已知限制：

- HTTPS 托管的 CodeWalk 站点无法调用局域网 IP 上的纯 HTTP OpenCode 服务器，因为浏览器会拦截混合内容。可以给 OpenCode 源启用 HTTPS，走可信的反向代理或隧道，或者在私下测试时从本地 HTTP 源运行 CodeWalk Web 构建。
- 使用 Basic Auth 或其他凭据时，CORS 必须放行确切的 CodeWalk 源；带认证的浏览器请求不要依赖通配符 CORS。
- OpenCode 服务器 URL 必须能从用户浏览器访问，而不是从 Cloudflare 的构建系统访问。

服务器配置

1. 启动应用，从侧边栏打开 Settings
2. 点 Add Server，在终端里运行 Quick setup 命令
3. 保留默认的 Server URL（http://127.0.0.1:4096），或设置你自己的服务器 URL
4. 只在服务器要求时配置 Basic Auth
5. 保存，按需切换活动配置档或默认配置档

OpenCode 项目智能体

在这个仓库里运行 OpenCode 时，仓库自带一个项目智能体，位于 .opencode/agents/opencodeNews.md：

- @opencodeNews 审查最新 OpenCode 版本对 CodeWalk 的影响
- @opencodeNews review vX.Y.Z 或 @opencodeNews check https://github.com/anomalyco/opencode/releases/tag/... 审查同一提示词里提到的指定版本目标智能体返回发布摘要、按领域划分的影响与风险、建议调整，以及执行计划——但仅在需要 CodeWalk 工作时才返回。

架构

项目遵循 Clean Architecture，分三层：Domain、Data、Presentation。依赖注入用 get_it，HTTP 用 dio，状态管理用 provider。

ADR-023 兼容性基线和当前 OpenCode 契约清单，见 CONTRACT_MATRIX.md。

技术栈

- 框架： Flutter
- 语言： Dart
- 状态管理： Provider
- HTTP 客户端： Dio
- 本地存储： SharedPreferences
- 依赖注入： GetIt
- 设计系统： Material Design 3

社区

和用户聊天、获取发布消息、发送反馈：Telegram — t.me/codewalkapp。带标签的发布可以附带一条 What's-new 说明，在应用内「设置 › 关于」下展示。

许可证

本项目采用双许可证：

- 开源： GNU Affero General Public License v3.0 (AGPLv3) —— 对所有人免费。
- 商业： 年收入超过 100 万美元、希望在不承担 AGPLv3 义务的前提下使用本软件的组织，可申请单独的商业许可证。

起源与致谢

CodeWalk 是 OpenMode 的分支，原项目由 easychen 创建。原项目采用 MIT 许可证。

分支之后做了大量修改，包括变更许可证、重构代码、更换品牌、全面英文化、重写文档。所有修改均按 AGPLv3 授权（适用时按商业许可证授权）。

完整署名信息见 NOTICE。