lbiceman/iceCoder
lbiceman/iceCoder has 86 GitHub stars and 16 forks. GitHot measured 0 stars in 24 hours and -1 in 7 days. Last checked 2026-11-15 20:33 UTC. Last push 2026-11-03.
实测星标增长
- 24小时
- 0
- 7天
- -1
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Self-hosted AI coding agent with desktop & mobile UI
人工智能README.zh-CN.md
原文iceCoder
自托管 AI 编程助手,桌面端 + 移动端。 模型主导的单循环 Agent + Plan 模式、可派子 Agent、定时任务、文件记忆与 MCP。Windows 安装包开箱即用,也可以用 Node.js 22+ 从源码或 CLI 运行。
English README · 使用说明与命令 · 项目介绍 · Project guide
界面预览
桌面端
左侧导航是 工作 / 任务 / 知识库 / 统计,底栏是 设置。工作页下列表分成 普通会话 和 任务会话。
工作 / 聊天 — 中间是聊天区,右侧是 iceCoder 工作台,底部是 # / @ 输入区,可切换模型和推理强度。工作台无 Tab:上半「检查点」按用户句切章(旧上新下;点章看下边执行流;标题右侧 ↩ 回滚),下半「执行流」是该章的 Harness 轮次与工具短预览。底栏:上下文、工具、文件。


任务 — #/tasks。定时任务把提示词连同引用的技能、图片和文件发到各自的专属会话。支持按间隔、每天、每周、每月,以及只执行一次;可立即执行、启停、编辑、打开会话。
知识库 — #/skills、#/memory、#/rules 三个页签:技能(新建、查看、编辑、删除)、记忆图谱、全局用户规则。
统计 — Token 消耗按每次 LLM 调用记入独立账本(会话 / 记忆分开),另有记忆读写;日 / 当周 / 当月是滚动的 24 小时 / 7 天 / 30 天:


设置 — #/settings(#/config 同页)。三个页签:通用、模型配置、MCP 配置。通用里有四套主题(深色 / 浅色 / 现代蓝 / 暖阳)、数据目录、子 Agent 开关、执行透明层、桌面宠物、任务完成通知,以及 Shell 强制确认规则。
移动端 H5
与桌面共用同一 bundle,路由 #/m/*。底栏四个 Tab:工作 / 任务 / 知识库 / 设置。窄屏打开 / 会进移动壳;桌面和移动的主题分开保存。
工作 — 聊天详情、底部模型与推理强度、冰豆:

工作(浅色主题) — 相同聊天布局下的浅色外观:

知识库 · 技能 — 技能卡片,支持新建、编辑、删除与「使用技能」:

设置 — 主题、数据目录与执行选项:

设置(浅色主题) — 相同设置页的浅色外观:

快速上手
二选一:Windows 安装包(无需 Node.js),或 CLI tgz(需 Node.js 22+)。
| 下载 | 环境 | 用法 |
|---|---|---|
| Windows x64 安装包 | — | 安装后启动 iceCoder |
| CLI tgz | Node.js 22+ | npm install -g ./ice-coder.tgz,然后 iceCoder start |
当前版本见 package.json(1.0.8)。
Windows 桌面版
安装包内置服务端 + Electron 壳 + 悬浮冰豆。首次启动请在「设置」页填写 API Key;数据目录默认 ~/.iceCoder/,可在设置里改到其他磁盘(重启后生效,需自行搬迁旧目录)。
从源码打包桌面版(开发者):执行 npm run build:desktop。Windows 上 /shell 依赖 node-pty 原生重编译,需 VS 2022「使用 C++ 的桌面开发」+ Windows SDK;Spectre 库由打包脚本默认绕过。无 C++ 工具链时会跳过 rebuild、打包仍可成功,但桌面包内 /shell 不可用。详见 docs/使用文档.md §桌面打包(Electron)。
源码 / Web / CLI
安装、配置 API Key、启动开发/Web/CLI、一次性任务、测试与覆盖率 — 全部命令见 docs/使用文档.md(README 不重复罗列)。
Node.js 22+(必需,与 engines.node >=22 一致)。仓库 data/ 只放模板;运行时数据不在这里。npm run dev 用 ICE_CACHE_ROOT(未设置时代码默认 E:/my/iceCoderCache)。安装包、npm start 和 Electron 用 ~/.iceCoder/,设置页可改,并与 %APPDATA%/iceCoder/data-directory.json 共用。环境变量见 docs/环境变量.md。
npm run dev 同时起 API 1024 和 Vite 1025(浏览器开 1025)。未设置 PORT 时,源码 CLI 默认 API 3784;安装包 / npm start / Electron 默认 1024。VITE_PORT 可改前端端口。
核心能力
Harness 主循环(模型主导)
和 Codex、Claude Code、OpenCode 一样,Harness 只有一个循环:读文件、改代码、跑命令都由模型自己决定。运行时不切换执行档位、不按步骤拦工具,也不因为同一文件反复修改、同一条命令反复失败而停手。「先想清楚再动手」只交给 Plan 模式(/plan)。
自由 / 自适应 / 严格三档监管、L1
free↔forced执行档、TaskGraph 任务步骤表和分支预算已于 2026-10-16 移除,见docs/requirement/监管收束-愿景.md。旧config.json里残留的supervisorMode会被忽略。更早的 L2 已于 2026-08-31 删除。
循环里仍然生效的:
- 权限规则(allow / confirm / deny),
skipPermissionChecks也不能跳过显式 deny;Shell 沙箱、宿主进程保护(HostGuard)、工作区写边界、missing-file 预检。 - 连续工具全失败阶梯:第 1 轮只保留工具结果;26 轮失败证据包、79 轮强警告、≥10 轮熔断(
circuit_breaker);「同参数重复失败」会给提示。 - D′ 停时验收:工程改动可跑一次有界验收计划,验收命令走与普通工具轮相同的权限与执行链。
- 无工具早停兜底、上下文微/硬压缩与恢复重注入。
- TaskState + RepoContext:跟踪 intent、阶段、改动文件、验证状态与读过的仓库面。
- CheckpointEngine v2:在同一份
{sessionId}.checkpoint.json上叠加runtimeV2(最近工具、失败、验收状态),在tool_failed/verification_failed/ 压缩 / 最终草稿时单独落盘,每轮收尾再落一次,长会话可续跑。带分支预算、执行档字段的旧 checkpoint 仍能打开,读取时丢弃这些字段。 - 意图检查点:每条用户消息发送前快照工作区;回滚到该句会还原文件,并删掉这条及之后的子 Agent 记录。
子 Agent
默认模式下,主 Agent 用 task 派出完整的子 Harness(压缩、恢复、权限、停时验收都在),同一条回复里的多个 task 并行。设置页可关闭;关闭后不再下发工具和说明。规划模式和 Shell 协作不暴露 task。
| 类型 | 能做什么 |
|---|---|
general |
读、改、跑命令、自己验证一块边界清楚的实现或修复 |
explore |
只读搜索和梳理,不改文件、不跑会改工作区的命令 |
run_in_background: true:立刻返回 agentId,主 Agent 继续干活;用check_agent查询,或等结束后自动注入报告。- 写租约:并行的子 Agent 不能写同一个文件。子 Agent 不能再派子 Agent,也不能
git commit/push/reset/checkout等改历史的命令。 - 委派卡片:和本轮的工具列表分开。收起时是标题、状态和当前一句;展开后才是过程、报告和改动。可打开只读子会话。确认弹窗会标明是哪个子 Agent 发起的。
- 子 Agent 的完整对话不进入主上下文,主 Agent 只看到
[Agent Result]。
三种会话模式
| 模式 | 怎么进 | 行为 |
|---|---|---|
| 默认 | 普通发消息 | 读写代码、派子 Agent、创建定时任务 |
| 规划 | /plan |
只完善计划文档,不能改代码;不暴露 task |
| Shell 协作 | /shell |
整段会话绑定一块持久 PTY;AI 读终端,你在聊天里决策。无内嵌黑窗口。详见 Shell 协作模式 |
一次 /plan 或 /shell 固定当前会话,直到退出。Shell 协作优先于规划模式。
输入 / 还有:/also(运行中追加备注)、/next(静默排下一条)、/open(确定性列出磁盘和目录,也接受 ~open)。+ 打开 ~ 面板:~scan、~tokens、~telemetry。
定时任务
任务页和 scheduled_task 工具都能创建。调度可以是间隔、每天、每周、每月,或只跑一次。每个任务有专属会话,出现在侧栏「任务会话」里。
无人值守时,工具确认(含删除文件和高危命令)会自动通过,任务页有明示。不进确认框的灾难性拦截和宿主进程保护仍然生效。上一次还在跑时,本次定时触发会跳过。
冰豆(Web 会话指示器)
仅 Web 聊天页 的 Canvas 宠物「冰豆」,把后端 Harness 事件映射成可见反馈,不参与运行时决策。
- 表情与 token 环:约 20 种表情(运行中、等待工具、成功、失败、压缩等)+ 外圈 token 用量。
- 桌面端最小化主窗口时,可在桌面显示同一只宠物;任务结束可发系统通知。两者都在设置里开关。
文件记忆(Memory v2)
长期事实以 Markdown 文件 落在 data/memory-files/(及用户记忆目录),无需外置向量库。知识库「记忆」页用图谱浏览。
- 结构化分级:
hard_rule/project_fact/preference/observation/session_state,配合evidenceStrength参与排序与淘汰。 - 意图感知召回:按 execute / inspect / question 过滤;同主题冲突记忆同轮只注入一侧。
- 粗召回(pre-LLM):按关键词从文件记忆拉最多 3 条注入提示。
- 提取与维护(post-tool):工具执行后写入/更新片段;Dream 与淘汰策略控制体积与冲突。
- 会话笔记:
session-notes与icecoder-runtime块保存压缩前快照。 - 可导出 ZIP。导入需要自行把 Markdown 放回记忆目录。
Agent Skills 与用户规则
可复用的 Markdown 技能 在 data/skills/(ICE_SKILLS_DIR)。
- 技能页:列表、预览、新建简单技能、编辑、删除。带脚本的技能在聊天里用「创建技能」来写。
- 聊天
#选择器:输入#挂上技能 chip,发送时把正文注入提示词。 - 用户规则(
#/rules):对所有工作区生效的全局提示,每次对话都会带上,有总字数上限。 - API:
GET/POST/PUT/DELETE /api/skills。Agent 创建或修改技能只能写在ICE_SKILLS_DIR。
多模型、推理强度与图片
同一 Provider 可在 modelName 里写多个模型(英文逗号分隔)。聊天页底部切换,选中值写入 activeModelName。
- 推理强度:
reasoningEffort同样用逗号列出档位(如low,high,max),输入区旁边切换。OpenAI 兼容发reasoning_effort,Anthropic 发thinking。留空则不发。 - 接口:OpenAI 兼容,默认
/v1/chat/completions,也可选/v1/responses。 supportsVision(默认true):先发多模态;API 拒绝图片时去图重试一次,并说明当前模型不支持识图。supportsVision: false:图片落到imagesCache,提示模型用image_read读绝对路径。image_read本身不会走这次去图重试。
字段说明见 docs/使用文档.md §配置。
多会话、移动端 H5 与跨端同步
侧栏对会话增删改查。每条会话有自己的历史、session-notes、checkpoint 和 工作区根目录。
- 移动端 H5:
#/m/work、#/m/work/:sessionId、#/m/tasks、#/m/skills、#/m/memory、#/m/rules、#/m/config。 ~scan:二维码把手机和电脑绑到 同一个会话 id。- 刷新或断线后,runningTurn 会把进行中的流式输出和子 Agent 卡片接回来。
文件引用与系统浏览
@工作区引用:级联选择器浏览会话工作区(/api/workspace/browse),选中路径以 chip 留在输入框上方。- 系统文件工具:
list_drives、browse_directory、open_file。 /open:服务端直接列目录,避免模型编造磁盘列表。
Checkpoint、压缩与断点恢复
磁盘 checkpoint 带上任务态和 runtimeV2(最近工具、失败、验收状态、后台任务)。写盘在 Harness 里串行,避免文件写坏。
- 硬压缩后重新注入 TaskState + RepoContext。
- F5 / WebSocket 重连靠
runningTurn和 checkpoint 重放。 - 没有
runtimeV2的旧 checkpoint 仍能读。
工具(内置 + MCP)
默认模式大约 30 个内置工具:文件读写与补丁、glob / grep、Git、run_command、搜索与 URL、Office / XMind / notebook 解析、系统文件浏览、image_read、undo_edit、env_info,以及 task、check_agent、scheduled_task。
Shell 协作会话另外使用 interactive_shell、shell_exec、shell_wait、shell_send_keys。MCP 把外部 Server 的工具注册进同一个 ToolRegistry。需要多轮 input_required 的 MCP 工具目前会直接返回不支持。
- Shell 双轨:长命令进后台,短命令在前台;软超时后可以升级为后台,避免
npm test堵住聊天。 - Diff:编辑类工具在聊天里嵌 Git 风格 diff。
- 权限:需要确认但没有 UI 回调时默认拒绝。设置里可以跳过普通确认;命中 Shell 强制确认规则的命令仍然要人点通过。灾难性命令和宿主进程保护始终生效。
- 文档工具按需携带:解析类工具不必每次都塞进提示词。
遥测与可观测性
Harness 轮次、记忆操作写入 data/*/telemetry.jsonl。Token 用量是独立 JSONL。统计页按当前时间范围拆成会话、子 Agent 和记忆。
- Web:
~tokens、~telemetry。 - 命令与路径详见
docs/使用文档.md。
测试与质量基线
test/**/*.test.ts 现有 384 个文件,覆盖权限与验收门控、子 Agent、定时任务、记忆、Web 路由和部分前端页面。用例数和覆盖率以本地命令为准,不再沿用旧的「约 2000 条 / 78%」口径。
npm test·npm run test:coverage·npm run lintnpm run eval:agent:Agent 行为回归。--mode=local跑带scriptedTurns的本地改文件用例;--mode=mock不给这些用例发假通过分。--category=model-led只跑「模型主导」类用例(同一文件连改 5 次、同一条失败命令重跑、长时间只读探索,另有两条真实模型用例);--case支持逗号分隔多个 id。所有用例都会额外检查不得出现任何监管文案和execution_mode_*/task_graph_*事件,报告附行为统计表(轮次、工具次数、写入次数、token、停止原因等)。详见docs/harness/收尾策略-模型停手与验收门控-finish.md。npm run telemetry:runtime:汇总 runtime 遥测 JSONL。
本地 Benchmark
与 Claude Code 等同模型、同 prompt、同沙箱的历史对比;看 验收通过率(SR) 和 Composite(Gate 40 + Judge 60)。下面的表是已归档跑分,不是当前 HEAD 的自动结果。
- 任务分层 L1–L8(billing L4+:97 文件 19 BUG;L7 融合 33 探针;L8 SaaS 融合:多租户订单 × 供应链 × 审批 × 计费)。
- 跑法:
docs/使用文档.md§本地 Benchmark · 体系benchMark/md/三平台同模对比评测与裁判评分体系.md。
深入阅读: 记忆 → docs/记忆系统详解.md · 压缩 → docs/压缩机制详解.md · 全貌 → docs/项目介绍.md · 移动端 → docs/requirement/移动端H5-Shell方案-finish.md · 子 Agent 设计 → docs/requirement/多agent协同.md
本地 Benchmark 跑分
裁判:Cursor Composer 2.5 · 体系:benchMark/md/三平台同模对比评测与裁判评分体系.md
报告:benchMark/reports/ · 任务:benchMark/tasks/ · 如何跑: docs/使用文档.md §本地 Benchmark
跨平台对比须 同模型批次(
m2.7/m2.5-pro/MiniMax-M3勿混比)。
| 任务 | 平台 | 模型 | SR | Composite | 相对 CC | 耗时 |
|---|---|---|---|---|---|---|
| 订单流水线 | iceCoder | m2.7 | ✅ | 86 | +3 | — |
| Saga 对账 | iceCoder | m2.7 | ✅ | 88 | +3 | — |
| Spell Brigade | iceCoder / CC | m2.5-pro | 1 / 1 | 81 / 80 | +1 | ~120分 / 87分 |
| 计费 19 BUG 01 | iceCoder | MiniMax-M3 | ✅ 19/19 | 93 | 比 02 +1 | ≈3.6 分 · 23 轮 |
| 计费 19 BUG 02 | CC | MiniMax-M3 | ✅ 19/19 | 92 | — | 5 分 45 秒 |
| 融合 L7 33 探针 01 | iceCoder | MiniMax-M3 | ✅ 33/33 | 91 | — | ≈5.3 分 |
| 融合 L7 33 探针 02 | CC | MiniMax-M3 | ✅ 33/33 | 92 | +1 | 6m 17s |
| SaaS L8 融合 01 | iceCoder | GPT-5.5 裁判 | ✅ 7/7 Gate | 71 | 比 02 +2 | ≈16 分 · 122 轮 |
| SaaS L8 融合 02 | CC | GPT-5.5 裁判 | ✅ 7/7 Gate | 69 | — | ≈5 分 |
结论: 同模同仓 — iceCoder 在验收通过、综合分或 L4+ 墙钟上更稳;CC 在个别模块实现或纯速度上可更优。L8 双方公开 Gate 均为 38/40,实现相对 160–220 文件设计口径偏薄;iceCoder +2 Composite(71 vs 69)主要来自发货超量修复。
架构(简图)
CLI / Web / WS / 移动端 H5
→ 记忆 + 技能 + 用户规则
→ Harness(模型主导单循环:工具、权限、停时验收、压缩)
→ 子 Harness(task:general / explore,可后台)
→ Checkpoint + 写租约
→ 内置工具 + MCP
| 模块 | 作用 |
|---|---|
| Harness | 主循环、D′ 停时验收、压缩、遥测 |
| 子 Agent | task / check_agent;子 Harness 写同一工作区,文件租约防冲突 |
| 文件记忆 | Memory v2:分级 / 证据强度 / 冲突裁决 + 会话笔记 |
| Skills / 规则 | 技能 Markdown 与全局用户规则 |
| 定时任务 | 间隔或日历调度,专属会话 |
| Web / 移动端 | 冰豆、多会话、H5、@/#、Diff、/ 与 ~ 命令 |
文档索引
| 文档 | 内容 |
|---|---|
| 使用文档 | 命令大全 — 安装、dev、CLI、测试、Benchmark、命令 |
| Shell 协作(/shell) | SSH / 交互终端:进入方式、安全、与 run_command 的区别 |
| 使用文档 · 桌面打包 | Electron 打包、node-pty、VS 2022 / Windows SDK |
| 多 Agent 协同 | task 子 Harness 的设计(含尚未落地的自定义类型与 worktree) |
| PROJECT-GUIDE | 架构与模块(部分段落仍写旧的 request_analysis) |
| 项目介绍 | 中文架构说明(同上,以本 README 和源码为准) |
| 记忆系统详解 | Memory v2 |
| 压缩机制详解 | 分层压缩 + 结构化恢复 |
| 双模机制详解 | 历史文档:L0 / L1 / L3 监管(已于 2026-10-16 移除) |
| L2监管层详解 | 历史文档:L2 退役说明 |
| PACKAGE_USAGE | 打包安装 |
| Benchmark 体系 | 评分方法 |
许可证
MIT — 见 LICENSE