Clouds Coder

云端 CLI 编码智能体运行时

CLI 执行面 × Web 用户面分离协同，构建可靠可观测的 Vibe Coding 体验。

English · 中文 · 日本語

Release Notes · 2026-06-22 更新日志（EN/中文/日本語） · 2026-06-05 更新日志（EN/中文/日本語） · 2026-05-28 更新日志（EN/中文/日本語） · 2026-05-02 更新日志（EN/中文/日本語） · 2026-03-31 更新日志（EN/中文/日本語） · 2026-03-25 更新日志（EN/中文/日本語） · 2026-03-20 更新日志（EN/中文/日本語） · 2026-03-16 更新日志 · 2026-03-07 更新日志 · MIT License · LLM Config Template

Clouds Coder 是一个以“CLI 执行层与 Web 用户层分离”为核心的本地优先（local-first）通用任务智能体平台，不局限于编程场景，集成 Web UI、Skills Studio、鲁棒流式回传与复杂任务恢复能力。

它的首要问题定义是：CLI 编程门槛高、环境分发困难、学习曲线陡。Clouds Coder 通过前后端分离（云端 CLI 执行 + Web 端交互控制）来降低 Vibe Coding 上手成本，同时把超时、截断、上下文预算、空想循环治理作为并列核心能力，保障复杂任务可执行、可收敛、可复盘。

架构更新日志归档：CHANGELOG-2026-06-22.md | CHANGELOG-2026-06-05.md | CHANGELOG-2026-05-28.md | CHANGELOG-2026-05-02.md | CHANGELOG-2026-03-31.md | CHANGELOG-2026-03-25.md | CHANGELOG-2026-03-20.md | CHANGELOG-2026-03-16.md | CHANGELOG-2026-03-07.md

1. 项目定位

Clouds Coder 的核心目标：

• 构建 CLI 执行面与 Web 用户面的分离协同环境，让用户以更低门槛获得高质量、可观测、可追溯的 Vibe Coding 体验。

本仓库从学习型 agent 代码演进为可部署的 standalone 运行时，聚焦：

• 前后端分离协同：云端执行、Web 端交互，降低本地环境耦合
• 降低 CLI 学习门槛：把复杂执行过程转为可视化、可追踪、可操作流程
• 降低分发与部署成本：统一运行时入口，减少“每端独立配置”负担
• 降低 Vibe Coding 采纳成本：让非 CLI 重度用户也能快速进入高质量工作流
• 稳定性与执行收敛能力作为核心能力：timeout 调度、截断续写、上下文预算、执行收敛控制

1.1 架构传承与复用说明

Clouds Coder 明确借鉴并扩展了以下项目的内核思想：

• shareAI-lab/learn-claude-code: https://github.com/shareAI-lab/learn-claude-code/tree/main

具体借鉴点（并在本项目中的映射）：

• 最小 agent 循环（LLM -> tool_use -> tool_result -> loop）
• 规划优先（TodoWrite）与复杂任务防漂移机制
• SKILL.md 按需加载协议
• 上下文压缩与召回（compact/recall）
• task/background/team/worktree 多步骤协同思想

Clouds Coder 在此基础上的扩展：

• 单体内核运行时（Clouds_Coder.py）：agent loop、工具路由、会话管理、API Handler、SSE 流、Web UI bridge、Skills Studio 处于同一进程状态域内协作。
• 结构化截断续写引擎：强截断信号检测、尾部重叠扫描、括号/符号配对修复启发式、多 pass 续写与 pass/token 实时遥测。
• 面向恢复的执行控制器：no-tool idle 诊断、运行时恢复提示注入、truncation-rescue 的 todo/task 自动创建，以及复杂任务死循环收敛诱导。
• 统一 timeout 治理：全局 timeout 调度 + 最小下限 + 回合级计账，并排除模型 active 时段，降低“仍在生成却被误超时”的概率。
• 分阶段 live-input 仲裁：针对 write/tool/normal 阶段使用不同延迟与权重策略，把晚到用户指令安全并入长任务执行。
• 上下文生命周期管理：自适应预算与手动锁定（--ctx_limit）、归档驱动 compact、按需 context recall，支撑长会话稳定运行。
• Provider/Profile 编排层：Ollama + OpenAI-compatible 配置解析、能力推断（含多模态标记）、media endpoint 映射、运行时选择与回退。
• 流式可靠性与可观测栈：SSE 心跳、写异常容错、模型调用周期进度事件、event+snapshot 混合刷新保障 UI 一致性。
• 工件优先工作区模型：每会话 files/uploads/context_archive/code_preview 持久化、上传文件镜像到工作区、阶段化代码预览保障可复现。

Skills 复用说明：

• skills/ 继续采用同一 SKILL.md 协议与 runtime loading 模型
• skills/code-review、skills/agent-builder、skills/mcp-builder、skills/pdf 为基础可复用 skills
• skills/generated/* 为本项目扩展的场景化 skills（报告、退化恢复、HTML 管线、上传解析等）
• 运行时工具接口与 skill 链路保持兼容（如 load_skill、list_skills、write_skill）

MiniMax skills 来源说明：

• 本仓库内 skills 下打包的本地 skill 套件，基于 MiniMax AI 的开源 skills 仓库改编而来：https://github.com/MiniMax-AI/skills
• 上游原始源码依据 MIT License 使用
• 感谢 MiniMax AI 及其上游贡献者提供原始 skill 内容、结构设计与生态建设

1.2 超越编程 CLI：面向通用任务的内核定位

Clouds Coder 并不是“只做写代码”的 CLI 包装器，而是一个可在单会话中执行并审计复合知识工作流的通用智能体运行时：

• 编程类任务：实现、重构、调试、测试、补丁审阅
• 分析类任务：文件挖掘、文档解析、结构化提取、对比研究
• 综合类任务：跨源推理、决策备忘录、风险与假设汇总
• 报告与可视化任务：HTML 报告、Markdown 叙事、阶段化代码与工件预览

核心执行链路强调三阶段高效闭环：

• LLM（思考/规划） -> 把目标拆解为约束明确的步骤与验收条件
• Coding（解析/执行） -> 通过确定性工具执行与产物落地推进任务
• LLM（汇总/分析） -> 校验中间结果并输出可追溯的最终结论

这种设计通过“思考必须转化为可执行动作与可验证工件”的机制，显著降低只思考不执行的漂移风险。

2. 核心特性

• 会话隔离的 agent runtime
• 单会话内通用任务路由（编程 + 分析 + 综合 + 报告）
• 内置 LLM -> Coding -> LLM 三阶段执行模式，适配复杂多步骤工作
• Plan Mode — UI 开关（Auto/On/Off），研究 → 方案 → 用户选择 → 逐步执行，Single 和 Sync 模式均支持
• 多智能体协作 — 4 角色（manager/explorer/developer/reviewer）+ blackboard 中心化协调
• 短上下文模型的长线处理能力放大 — 多 Agent 将任务拆成分角色上下文，让较小的本地模型也能连续完成调研、实现、审查与修复链路，而不依赖单次巨大 prompt
• Reviewer Debug Mode — 检测到错误时 reviewer 获得写权限，独立诊断修复 bug
• 6 类通用错误检测（test/lint/compilation/build/deploy/runtime）+ 统一 failure ledger
• 4 级分层上下文压缩（normal → light → medium → heavy）+ 文件缓冲卸载，支持 4K 到 1M token
• 分 Agent 独立压缩 — Manager / Explorer / Developer / Reviewer 上下文通道在同一分层 compact 框架下独立压缩，简单 single 任务保持原有单一全局上下文通道
• 任务阶段感知委派 — manager 根据当前阶段（research/design/implement/test/review/deploy）路由到合适的 agent
• 原生多模态支持 — read_file 自动检测图片/音频/视频，模型支持时作为原生输入注入
• 实时用户输入合并 — 执行中途的反馈可调整 plan 方向，无需重启
• Restart 意图融合 — 恢复时按 用户意图 > plan 意图 > 上下文意图 优先级融合
• Skills 生态全面兼容 — 兼容 5 大生态系统（awesome-claude-skills / Minimax-skills / skills-main / kimi-agent-internals / academic-pptx），LLM 自主判断按任务类型加载，支持多 skills 并发 + 冲突检测
• 双库 RAG 知识架构 — Code RAG（CodeIngestionService）+ Data RAG（RAGIngestionService），均基于 TF_G_IDF_RAG，统一检索接口 query_knowledge_library，RAG 检索指南注入到内置 skills
• 持久化 Wiki RAG — WikiStore 将 raw library sources 编译为长期维护的 Markdown Wiki（sources/、entities/、concepts/、synthesis/overview.md、index.md、log.md、schema.md），检索优先复用累计综合，再回退 raw chunks
• 编程工作流记忆 — WorkflowMemoryStore 对完成的编程 session 自动评分，把优质工作流卡片收录到 Code Wiki memory，通过 workflow 路由召回工具调用、任务交接、验证和实现模式
• 多因素优先级上下文压缩 — 10 因素消息重要性评分（时间近因、角色权重、任务进度、错误、目标相关性、skills、compact-resume），替代纯时序裁剪
• 内置 Web UI + 可选外部 Web UI
• Skills Studio（独立端口）用于扫描/编辑/生成/上传 skills
• Ollama 探测与模型目录加载
• 通过 LLM.config.json 支持 OpenAI-compatible 多配置
• 私有 vLLM / OpenAI-compatible 韧性：5 次 HTTP 重试治理、默认 60 秒间隔、遵循 Retry-After / 限流恢复信号、endpoint cooldown、nginx/upstream 临时错误重试
• 统一 timeout 调度（全局超时，模型 active 时段排除）
• 截断恢复循环（续写 pass/token 计数 + UI 实时展示）
• 上下文压缩 + 历史归档召回 + 无损状态衔接
• 无工具空转诊断与恢复提示
• Task/Todo/Background/Team/Worktree 一体化机制
• SSE 心跳与写入异常处理
• 预览链路：Markdown/HTML/代码/PDF/CSV/Excel/Word/PPT/媒体/代码阶段预览
• 前端资源控制：live/static 冻结、快照调度、对话虚拟化
• 可导入架构拆分工具：split_coder.py 通过 _source_bridge.py 重新生成可 import 的 Code_Structure/ 导航包
• 科研任务友好：工件优先、阶段可追溯、可复现持久化链路

3. 架构总览

┌───────────────────────────────────────────────────────────────────────┐
│                            Clouds Coder                              │
├───────────────────────────────────────────────────────────────────────┤
│ 体验与溯源层                                                         │
│  - 多预览中心（Markdown / HTML / 代码 / PDF / Office / 媒体）        │
│  - 阶段化代码历史备份 + 差异/溯源时间线                              │
│  - 运行进度卡片（thinking/run/truncation/recovery）                 │
│  - Skills 可视化流程构建 + SKILL.md 生成注入                         │
├───────────────────────────────────────────────────────────────────────┤
│ 展示层                                                               │
│  - Agent Web UI（对话、看板、预览、运行状态）                        │
│  - Plan Mode 开关（Auto/On/Off）+ Planner 气泡（橙红色）     │
│  - Skills Studio（扫描/生成/保存/上传 skills）                       │
├───────────────────────────────────────────────────────────────────────┤
│ API 与流式层                                                         │
│  - REST APIs：sessions/config/models/tools/preview/render/plan-mode │
│  - SSE：/api/sessions/{id}/events（心跳 + 容错）                     │
├───────────────────────────────────────────────────────────────────────┤
│ 编排与控制层                                                         │
│  - AppContext / SessionManager / SessionState                        │
│  - EventHub / TodoManager / TaskManager / WorktreeManager            │
│  - Plan Mode（Auto/On/Off）+ 阶段感知委派                           │
│  - 截断恢复 + timeout 治理 + 执行恢复控制器                          │
├───────────────────────────────────────────────────────────────────────┤
│ 模型与工具执行层                                                     │
│  - Ollama/OpenAI-compatible profile 编排                             │
│  - tools: bash/read/write/edit/Todo/skills/context/task/render       │
│  - 原生多模态 + 6 类错误检测 + 4 级压缩 + Reviewer Debug Mode       │
│  - live-input 仲裁 + 小模型保护策略                                  │
├───────────────────────────────────────────────────────────────────────┤
│ 工件与持久化层                                                       │
│  - 每会话 files/uploads/context_archive/code_preview                 │
│  - conversation/activity/operations/todos/tasks/worktree             │
│  - file_buffer（大内容卸载到磁盘）                                   │
└───────────────────────────────────────────────────────────────────────┘

Mermaid：

flowchart TB
  UX["体验与溯源层

多预览 / 阶段历史 / 运行进度 / Skills Flow"]
  UI["展示层

Agent Web UI + Plan Mode 开关 + Skills Studio"]
  API["API 与流式层

REST（含 plan-mode）+ SSE + render-state/frame"]
  ORCH["编排与控制层

AppContext / SessionManager / SessionState

EventHub / Todo / Task / Worktree

Plan Mode / 阶段感知委派"]
  AGENT["多智能体协作层

Manager / Explorer / Developer / Reviewer

Blackboard + 分角色工作上下文"]
  EXEC["模型与工具执行层

OllamaClient + tool dispatch

原生多模态 + 6 类错误检测 + 全局/分 Agent 分层压缩"]
  DATA["工件与持久化层

files / uploads / context_archive / code_preview

conversation / activity / operations / file_buffer"]
  UX --> UI --> API --> ORCH --> AGENT --> EXEC --> DATA
  EXEC --> API
  DATA --> UI

3.1 程序交互架构图

用户（Browser/Web UI）
        │
        │ REST（message/config/uploads/preview） + SSE（runtime events）
        ▼
ThreadingHTTPServer
  ├─ Handler（Agent APIs）
  └─ SkillsHandler（Skills Studio APIs）
        │
        ▼
SessionManager ──► SessionState（会话级运行时状态机）
        │                    │
        │                    ├─ 模型调用编排（Ollama/OpenAI-compatible）
        │                    ├─ 工具执行（bash/read/write/edit/skills/task）
        │                    └─ 恢复控制（truncation/timeout/no-tool idle）
        │
        ├─ EventHub（瞬时运行时事件）
        └─ 工件存储（files/uploads/code_preview/context_archive）
                │
                ▼
       Preview APIs + Render bridge + 历史溯源时间线
                │
                ▼
        Web UI 实时更新（chat/runtime/preview/skills）

Mermaid：

flowchart LR
  U["用户浏览器 / Web UI"] -->|REST + SSE| S["ThreadingHTTPServer"]
  S --> H["Handler (Agent APIs)"]
  S --> SH["SkillsHandler (Skills Studio APIs)"]
  H --> SM["SessionManager"]
  SM --> SS["SessionState"]
  SS --> MC["模型调用编排

Ollama/OpenAI-compatible"]
  SS --> TD["工具执行

bash/read/write/edit/skills/task"]
  SS --> RC["恢复控制

truncation/timeout/no-tool idle"]
  SS --> EH["EventHub"]
  SS --> FS["工件存储

files/uploads/code_preview/context_archive"]
  FS --> PV["Preview APIs + render-state/frame + 历史溯源"]
  PV --> U

3.2 任务逻辑图

用户目标
   │
   ▼
意图与上下文摄入
   │（上传/历史/上下文预算）
   ▼
Plan Mode 门控（Auto/On/Off）
   │
   ▼
规划与分解（Todo/Task/Worktree）
   │
   ▼
阶段感知委派（research→explorer / implement→developer / review→reviewer）
   │
   ▼
Agent Loop
  ├─ Model Call
  │    ├─ 正常输出 ───────────────┐
  │    ├─ 工具调用请求 ─► 执行工具├─► 回填结果 -> 下一轮
  │    └─ 截断信号 ──────► 续写/恢复
  │
  ├─ no-tool idle 检测 -> 诊断与恢复提示
  ├─ timeout 治理（模型 active 时段不计时）
  ├─ 上下文压力 -> 4 级分层压缩 + compact + recall
  ├─ Reviewer Debug Mode（检测到错误 → 获写权限独立修复）
  ├─ 实时用户输入合并（中途调整 plan 方向）
  └─ Plan Step 自动推进
   │
   ▼
收敛结果与工件
   │
   ▼
预览/历史/导出（MD/代码/HTML + 阶段备份）

Mermaid：

flowchart TD
  A["用户目标"] --> B["意图与上下文摄入

上传/历史/上下文预算"]
  B --> PM["Plan Mode 门控

Auto / On / Off"]
  PM --> C["规划与分解

Todo/Task/Worktree"]
  C --> PH["阶段感知委派

research→explorer / implement→developer / review→reviewer"]
  PH --> D["Agent Loop"]
  D --> E["Model Call"]
  E --> F["正常输出"]
  E --> G["工具调用请求"]
  G --> H["执行工具"]
  H --> D
  E --> I["截断信号"]
  I --> J["续写/恢复"]
  J --> D
  D --> K["no-tool idle 检测 + 恢复提示"]
  D --> L["timeout 治理

模型 active 时段不计时"]
  D --> M["context 压力 -> 4 级分层压缩 + compact + recall"]
  D --> DBG["Reviewer Debug Mode

检测到错误 → 获写权限独立修复"]
  D --> LI["实时用户输入合并

中途调整 plan 方向"]
  D --> PS["Plan Step 自动推进"]
  D --> N["收敛结果与工件"]
  N --> O["预览/历史/导出

MD/代码/HTML + 阶段备份"]

3.3 单体化同频多智能体协作（Blackboard 模式）

Clouds Coder 已支持在单体内核中进行角色专职协作：

• manager：仅负责路由与仲裁（不直接写实现）+ 阶段感知委派
• explorer：调研、依赖分析、路径与环境探测
• developer：代码实现、文件修改、工具执行
• reviewer：校验、测试判定、通过/阻断裁决；Debug Mode 可获得写权限独立修复 bug

这不是微服务拆分模型，而是“单进程 + 单黑板”的协作范式。核心收益：

• 无跨服务 RPC 开销，协同延迟更低
• 黑板状态可快照、可重放，Manager 决策更稳定
• 任一环节报错时可快速中断并重路由
• 通过分角色工作记忆，显著提升短上下文模型的长线任务连续性

上下文拓扑：

• Single 模式保持单一全局上下文通道和单条上下文进度条。
• Multi-agent 模式只为 Manager 与真实参与的 agent 创建活跃角色通道。
• 每个角色通道都按同一分层压缩策略独立估算与 compact。
• 下一次模型调用只注入当前角色相关通道，而不是重新加载所有角色完整历史。
• UI 只有在真实进入 multi-agent 后才显示嵌套角色上下文条；L1/L2 single 任务保持原有单条进度条。

黑板核心切片（Single Source of Truth）：

• original_goal、status、manager_cycles
• plan（plan steps + plan_mode 状态）、phase（当前阶段）、errors（6 类错误列表）
• research_notes、code_artifacts、execution_logs、review_feedback
• 带 owner 的 todos（manager/explorer/developer/reviewer）
• manager 判定字段（任务等级、预算、剩余轮次、确认门禁）

执行拓扑：

• sequential：Explorer -> Developer -> Reviewer 串行流水线
• sync：Manager 主导的同频协作，支持动态跨角色回调与接管

任务等级策略（由 Manager 语义判定，每次用户输入都会重评）：

等级	典型任务形态	模式决策	预算策略