cc-reforged

v0.5.1

Published

a day ago

CCR is a terminal coding agent recovery build with a built-in pluggable LLM runtime.

0High
0Medium
0Low

mhdfy1988

ccr coding-agent llm codex-oauth terminal

免责声明： 本仓库包含从 @anthropic-ai/[email protected] npm 包内置的 source map（cli.js.map）恢复出的源码。这不是 Anthropic 官方发布的源码。相关权利归各自权利方所有。

简体中文 | English

CCR

CCR 是一个终端编码 Agent 的恢复构建与持续演进版本。它保留终端优先的工作方式，同时把配置、LLM 运行时、App Server 和 Desktop 客户端逐步收敛到 CCR 自己的边界内。

当前 0.5.x 版本线聚焦多模型、多模态、工具调用和 MCP 基础管理面。下一条 0.6.0 主线会进入 Skill、Plugin 与外部能力包治理。

CCR

一眼看懂

CCR 的目标不是简单“换一个模型接口”，而是把一个本地编码 Agent 需要的几条链路统一起来：

| 层面 | CCR 负责什么 | | --- | --- | | 终端 Agent | 保留 ccr CLI / TUI 对话、工具调用、权限确认和项目上下文体验 | | Desktop 工作台 | 管理工作区、历史会话、模型配置、权限、日志、更新和生成物展示 | | LLM Runtime | 管理 provider、Profile、凭据、模型目录、协议适配、能力声明和每轮元数据 | | 多模态协议 | 统一文本、图片、文件、工具结果、生成图片和历史恢复的内部内容块 | | 工具治理 | 让模型只看到当前真实可用的工具，并把 MCP 工具、安装、启停和诊断纳入统一管理 | | 项目隔离 | 使用 .ccr 项目配置，避免污染 Claude Code、Codex、OpenClaw 等其它工具 |

你可以把它理解成三层组合：

ccr CLI / TUI
  -> Core Agent Runtime
  -> LLM Runtime / Tools / Permission / Session

CCR Desktop
  -> App Server
  -> 同一套 Core Agent Runtime

Provider Adapters
  -> Codex OAuth / OpenAI / DeepSeek / MiniMax / Kimi / GLM

当前状态

| 项目 | 当前值 | | --- | --- | | npm 包名 | cc-reforged | | 当前版本 | 0.5.1 | | CLI 命令 | ccr | | 桌面应用 | CCR | | 运行时要求 | Node.js >=24.0.0 | | 默认配置目录 | ~/.ccr | | LLM 配置文件 | ~/.ccr/data/llm.config.local.json | | LLM 凭据文件 | ~/.ccr/data/llm.credentials.local.json | | 发布入口 | mhdfy1988/cc-reforged GitHub Releases |

主分支可能包含最新版本之后的开发中改动。面向用户的版本变化见 CHANGELOG.md，版本路线见 docs/architecture/version-roadmap.md。

适合做什么

CCR 当前更像一个本地 Agent 工作台，而不是单纯的 CLI 包：

在终端中运行 ccr，继续使用编码 Agent 的对话、工具和权限流程。
在 Windows Desktop 中管理工作区、历史会话、权限、模型连接和自动更新。
使用内置 LLM Runtime 管理多个 provider、多个 Profile、不同协议和每轮实际模型元数据。
在同一套生成物协议下展示模型生成图片、工具图片、远程图片 URL、本地附件和历史恢复结果。
把项目级设置放进 .ccr/settings*.json，避免和 Claude Code、Codex、OpenClaw 等工具互相污染。

典型使用路径：

| 场景 | 推荐入口 | 说明 | | --- | --- | --- | | 继续终端编码 | ccr | 适合熟悉 TUI、希望直接在终端里和 Agent 协作的人 | | 本地工作台 | CCR Windows 客户端 | 适合需要历史会话、模型切换、权限页、日志页和图片预览的人 | | 多模型调试 | Desktop 模型页 / ccr model | 适合比较 Codex OAuth、OpenAI、DeepSeek、MiniMax、Kimi、GLM 等供应商 | | 多模态 / 生图 | Desktop 会话 | 适合发送图片、生成图片、查看缩略图和预览生成物 | | MCP 浏览器工具 | Desktop MCP 页 / ccr mcp add-playwright | 适合安装 Playwright MCP，让模型在需要时调用真实浏览器工具 | | Provider 接入开发 | docs/architecture/provider-integrations/ | 适合继续补新模型、新协议、新能力矩阵 |

0.5.1 重点

工具治理：新增只读工具注册目录、可用性判断和 ToolSearch 搜索策略，让模型只看到当前真实可用的 deferred 工具。
MCP 管理：Desktop MCP 页支持 Playwright MCP 的安装、启停、检测、卸载和安装记录展示，默认写入用户全局 ~/.ccr。
文件搜索：打包前准备内置 ripgrep，开发态缺少内置二进制时会回退系统 rg，再回退 Node 原生文件搜索。
Desktop 导航：新增 Skill / Plugin 占位入口，为 0.6.0 外部能力包治理预留位置。
发布链路：Windows 安装包继续保持 CCR-<version>-win-x64.exe 命名，并保留 .blockmap、latest.yml 和校验 smoke。

0.5.1 更具体的变化可以按几条线看：

| 方向 | 已完成 | | --- | --- | | 工具注册目录 | CcrToolRegistry、中文名、分类、来源、direct/deferred/internal 展示建议 | | 工具可用性 | App Server 工具池集中输出不可用原因，ToolSearch 只返回 available + deferred 候选 | | MCP | 用户全局安装、安装清单、锁文件、缓存目录、启停、检测、卸载和工具卡展示 | | 文件搜索 | prepare:ripgrep、内置 rg、系统 rg、Node 原生 fallback 和 smoke 验收 | | Desktop 导航 | MCP、Skill、Plugin 入口并列，Skill / Plugin 先占位不抢 0.5.x 主线 | | 发布 | CCR-0.5.1-win-x64.exe、.blockmap、latest.yml 和发布资产校验 |

安装

从 npm 安装 CLI：

npm.cmd install -g cc-reforged
ccr --version
ccr

桌面端请从 GitHub Releases 下载最新 Windows 安装器：

CCR-<version>-win-x64.exe

当前 Windows 安装包暂未购买代码签名证书。如果 Windows 提示未知发布者，请以 GitHub Release 页面和 release note 中的 SHA256 校验值确认来源。

首次启动建议

如果你只是想快速试用，建议按这个顺序：

先安装或启动 ccr。
通过 /login 完成 Codex OAuth 登录。
用一个简单问题确认文本对话可用。
再打开 Desktop，配置其它 API Key 或切换模型。
需要生图时，优先切到支持图片生成的 provider，例如 GLM API、OpenAI、MiniMax 或 Codex OAuth。

如果你主要使用 Desktop，可以先安装 Windows 包，再在“模型”页面里完成连接配置。

从源码运行

安装依赖并构建：

npm.cmd install
npm.cmd run build

运行 CLI：

node --no-warnings --experimental-loader ./bun-bundle-loader.mjs ./cli.js --version
node --no-warnings --experimental-loader ./bun-bundle-loader.mjs ./cli.js

可选的本地全局链接：

npm.cmd link
ccr --version
ccr

桌面端开发：

npm.cmd run desktop:dev

桌面安装包构建：

npm.cmd run desktop:dist

源码开发时常用路径：

| 路径 | 说明 | | --- | --- | | src/ | CLI、Core、LLM Runtime、工具、配置和协议适配 | | apps/desktop/ | Electron Desktop 主进程、renderer、IPC 和 UI | | scripts/ | smoke、打包、发布、probe 和辅助检查脚本 | | docs/architecture/ | 长期架构、协议、provider、Desktop、发布与升级文档 | | docs/stages/ | 当前 todo、阶段指针、修复清单和交接记录 | | docs/goals/ | 每个阶段的目标、验收标准和完成记录 |

模型与供应商

Codex OAuth 是当前默认供应商。推荐首次使用流程：

使用 ccr 或上面的源码命令启动 CCR。
在 TUI 里运行 /login。
选择 Codex OAuth。
在浏览器中完成登录。
输入一个简单问题，确认模型可以正常响应。

可以用下面的命令查看运行时状态：

node --no-warnings --experimental-loader ./bun-bundle-loader.mjs ./cli.js auth status --json

模型配置采用 Profile 优先模型：llm.config.local.json 保存 schemaVersion + current + profiles + providerOverrides，llm.credentials.local.json 按 profileCredentials[profileId] 保存敏感凭据。一个 Profile 组合供应商类型、协议、endpoint、凭据槽、可用模型和默认模型。

常用 CLI：

ccr model status
ccr model list
ccr model set gpt-5.5
ccr model profile codex-oauth-1 gpt-5.4

Desktop 内置一级“模型”页面，用于管理供应商 / Profile、填写 API Key、测试连接，并配合顶部“模型 / 连接配置”两个快速切换入口。顶部切换只影响下一轮消息，不会改写或绑定恢复出来的历史会话。

| 供应商 | 协议 | 认证 | 当前能力 | | --- | --- | --- | --- | | Codex OAuth | OpenAI Responses | OAuth | 文本、图片输入、hosted image generation | | OpenAI | OpenAI Chat / Images / Responses | API Key | 文本、图片输入、图片生成 | | DeepSeek | OpenAI Chat Completions | API Key | 文本与工具调用 | | MiniMax 国际版 | Anthropic Messages + 原生图片接口 | API Key | 文本、工具调用、图片生成 | | MiniMax 国内版 | Anthropic Messages + 原生图片接口 | API Key | 文本、工具调用、图片生成 | | Kimi API / Kimi Code | OpenAI Chat / Anthropic Messages compatible | API Key | 文本与工具调用 | | GLM API | OpenAI Chat compatible + Images | API Key | 文本、视觉模型、glm-image 生图 | | GLM Coding Plan | OpenAI Chat compatible | API Key | Coding Plan 专用端点 |

Profile 是什么

CCR 里“供应商”和“连接配置”是两回事：

供应商类型：例如 glm-api、openai、minimax-cn，表示协议、默认 base URL 和内置模型目录。
Profile：一条真实连接配置，包含名称、供应商类型、endpoint、默认模型、模型列表和凭据槽。
凭据：API Key 或 OAuth token，单独按 profileId 存在 llm.credentials.local.json。

这样同一个供应商可以保存多个账号或多个 endpoint，例如：

glm-api-1    -> 个人 GLM API Key
glm-api-2    -> 团队 GLM API Key
openai-1     -> 官方 OpenAI
minimax-cn-1 -> 国内 MiniMax

恢复历史会话不会自动切换当前模型。CCR 会在每轮 turn metadata 里记录当时实际使用的 profileId / provider / model / apiMode，用于排查和审计。

多模态与生图

CCR 不把各家 provider 原始响应直接交给 UI。统一链路是：

Provider 原始响应
-> CCR 标准内容块
-> generatedArtifact / DisplayEvent
-> Desktop 附件卡、缩略图、预览、复制、定位

当前稳定口径：

文本模型默认只接收文本，未知模型不会因为名字像 OpenAI 就默认启用图片。
支持视觉的模型可以接收图片附件，发送前会按能力目录和 Profile 覆盖校验。
GenerateImage 是模型可见的统一生图工具。
支持生图的 provider 返回图片后，CCR 会优先落盘到 ~/.ccr/generated_outputs/...。
GLM 这类返回临时下载 URL 的模型，CCR 会先下载再展示，避免 UI 直接依赖远程 URL 导致缩略图破图。
当前 provider 不支持生图时，工具返回友好提示，引导用户切换到 GLM API、OpenAI 或 Codex OAuth。

生图调用口径

生图不是让模型“自己画图”，也不是让模型写一个 SVG 文件糊弄用户。CCR 的目标是把生图变成模型可见的真实工具能力：

用户说“生成一张图片”
-> Desktop / App Server 识别生图意图
-> 当前 provider 支持生图则调用 GenerateImage
-> provider adapter 调用真实图片生成接口
-> 输出归一化为 generatedArtifact
-> 后端落盘或下载 URL
-> Desktop 展示缩略图、预览、打开、定位、另存、复制

当前各 provider 的生图路径：

| Provider | 生图路径 | | --- | --- | | Codex OAuth | Responses hosted image_generation tool | | OpenAI | /images/generations，也支持 Responses hosted tool 路径 | | MiniMax | 原生 image_generation 接口 | | GLM API | glm-image / /images/generations，返回 URL 后先下载落盘 |

后续如果接音频、视频、文件生成，也会先扩展 generatedArtifact 生命周期，而不是把 provider 原始响应直接塞进 UI。

MCP 安装与使用

MCP 已提前进入 0.5.x 工具治理线。CCR 当前已经有用户级 MCP 配置、Desktop MCP 管理页、受控安装计划、安装记录、启用/禁用、检测、卸载和 MCP 工具卡展示。

Desktop 推荐流程

日常使用优先走 Desktop：

打开 CCR Desktop，进入左侧 MCP 页面。
在安装区搜索 playwright。
点击 安装。
在确认弹窗里检查写入位置、启动方式、风险提示和数据边界。
点击 确认安装。
安装后点击 检测，确认工具能被发现。
会话里需要浏览器时，明确说“用浏览器打开/查询/操作”。成功时会看到 MCP playwright / browser_* 工具卡。

如果已经安装，候选会显示“已安装”，不要重复安装；直接在 MCP 页面里使用 检测、重启、禁用/启用 或 卸载。

CLI 安装

Playwright MCP 用户级快捷安装：

ccr mcp add-playwright

常用变体：

ccr mcp add-playwright --headless
ccr mcp add-playwright --version 0.0.71
ccr mcp add-playwright --mode managed

也可以手动添加其它 MCP：

ccr mcp add --scope user playwright -- npx.cmd -y @playwright/mcp@latest
ccr mcp add --scope user --transport http sentry https://mcp.sentry.dev/mcp

配置和安全边界

| 路径 | 用途 | | --- | --- | | ~/.ccr/mcp.json | 用户全局 MCP 配置，Desktop 推荐安装默认写这里 | | 项目根目录 .mcp.json | 项目级共享 MCP 配置 | | ~/.ccr/mcp/installed.json | CCR 受控安装记录 | | ~/.ccr/mcp/lock.json | CCR 受控安装锁定记录 | | ~/.ccr/mcp/packages/ | CCR installer-owned 包缓存和 owner marker | | ~/.ccr/logs/mcp/ | MCP 安装、连接和诊断日志 |

npx 快速模式不会把 @playwright/mcp 复制进 CCR 安装目录；首次启动时会由 npm/npx 获取并缓存。managed 模式会把指定版本安装到 ~/.ccr/mcp/servers/playwright/ 并把配置指向本地入口。

模型可以建议需要某类 MCP 能力，但不能绕过用户确认自行下载安装、写配置、启动陌生 stdio server 或卸载删除文件。

更完整的 MCP 文档见 MCP 文档入口。

Desktop 能力

本地 App Server 生命周期管理。
工作区切换和项目级 settings 隔离。
按工作区分组的历史会话、搜索和恢复。
一级“模型”页面，支持供应商 Profile、凭据、模型和测试连接管理。
一级“MCP”页面，支持 MCP server 查看、安装、检测、启用 / 禁用、重启和卸载。
一级“技能 / 插件”占位入口，给后续 Skill / Plugin 扩展包治理预留位置。
顶部当前模型和连接配置快速切换。
多模态输入卡片、模型生成图片卡片、本地缩略图 / 预览和生成物持久化。
本地 / 项目 / 用户级权限设置页面。
日志页、错误诊断和原始 JSON 复制。
通过 GitHub Releases 检查自动更新。
Windows 安装器打包、发布资产校验和 unsigned 发布提示。

Desktop 当前工作流

Desktop 当前围绕一个“本地工作区 + 会话流”展开：

顶部选择当前工作区。
顶部选择当前模型和连接配置。
会话区发送消息、附件或生图请求。
工具调用、权限请求、计划确认、错误诊断都以卡片形式进入时间线。
历史会话按 workspace 分组展示，运行中的会话不能被重复切换。
日志页用于查看 Desktop / App Server 事件，长 JSON 在内部滚动，不撑开页面。

这套体验仍在 0.5.x 继续打磨，特别是工具能力治理、错误诊断、运行中状态和多会话观测。

配置与目录

| 路径 | 用途 | | --- | --- | | ~/.ccr/data/llm.config.local.json | 普通模型配置、Profile、当前选择、provider 覆盖 | | ~/.ccr/data/llm.credentials.local.json | API Key、OAuth token 等敏感凭据 | | ~/.ccr/mcp.json | 用户全局 MCP 配置 | | ~/.ccr/mcp/installed.json | CCR 受控 MCP 安装记录 | | ~/.ccr/mcp/lock.json | CCR 受控 MCP 安装锁定记录 | | ~/.ccr/generated_outputs/ | 模型生成图片等本地持久化产物 | | .ccr/settings*.json | 项目级 CCR 设置 | | %APPDATA%/CCR/ | Windows Desktop 的窗口状态、日志、UI 本地状态 |

凭据只按 profileId 写入本地凭据文件，不进入仓库、不进入普通导出，也不应写进 llm.config.local.json。

数据和安全边界

API Key、OAuth token、refresh token 只进入本机凭据文件，不写入仓库。
生成图片默认落盘到 ~/.ccr/generated_outputs/，历史恢复只保存轻量引用。
远程图片 URL 会尽量由后端下载为本地文件，避免 UI 依赖临时链接。
项目级设置使用 .ccr/settings*.json，不再运行时读取旧 .claude/settings*.json。
当前不会默认跨供应商路由用户数据；未来跨供应商能力路由必须显式配置。
错误诊断会尽量结构化和脱敏，原始 JSON 只放在可展开详情里。

架构边界

CCR 当前按这些边界推进：

CLI / TUI：保留终端优先的编码 Agent 体验。
Core：负责会话、turn、工具、权限、历史和标准内容块。
LLM Runtime：负责 provider、Profile、协议适配、模型能力和生成物归一化。
App Server：负责 Desktop / 未来客户端和 Core 之间的事件协议。
Desktop：负责工作区、历史、模型配置、权限、日志、展示和发布更新体验。

长期方向不是把所有能力都塞到一个模型里，而是通过能力声明、Profile、工具治理和外部扩展边界，让模型只看到当前真实可用的能力。

运行链路

用户输入
-> Desktop / CLI
-> App Server turn/start
-> CoreSessionService
-> LLM Runtime
-> Provider Adapter
-> 标准内容块 / 工具事件 / generatedArtifact
-> App Server events
-> Desktop DisplayEvent

这条链路的核心约束是：UI 不解析 provider 原始协议，provider adapter 不决定 UI 展示，工具执行结果不伪装成用户消息。

开发验证

常用验证命令：

npm.cmd run typecheck -- --pretty false
npm.cmd run typecheck:desktop
npm.cmd run build -- --pretty false
npm.cmd run desktop:build

LLM Runtime 与 provider：

npm.cmd run smoke:llm-config
npm.cmd run smoke:llm-runtime
npm.cmd run smoke:llm-runtime-status
npm.cmd run smoke:openai-chat-protocol
npm.cmd run smoke:codex-oauth-session
npm.cmd run smoke:codex-oauth-provider
npm.cmd run smoke:deepseek-provider
npm.cmd run smoke:minimax-provider
npm.cmd run smoke:generated-output-provider
npm.cmd run smoke:generate-image-tool
npm.cmd run smoke:session-generated-image-flow

App Server / Desktop：

npm.cmd run smoke:app-server
npm.cmd run smoke:app-server-client
npm.cmd run smoke:desktop-display-events
npm.cmd run smoke:desktop-session-state
npm.cmd run smoke:desktop-release-artifacts

不要直接用 node scripts/... 运行 runtime smoke 脚本，除非确认该脚本不需要项目 loader。npm scripts 已经处理了需要 bun-bundle-loader.mjs 的入口。

发布

版本更新日志：CHANGELOG.md
版本路线图：docs/architecture/version-roadmap.md
Desktop 发布验收 Runbook：docs/architecture/desktop-release-acceptance-runbook.md
GitHub Release 发布流程：docs/architecture/desktop-github-release-workflow.md
npm 发布流程：docs/release/npm-publish-workflow.md

0.5.1 本地正式包命名为：

CCR-0.5.1-win-x64.exe
CCR-0.5.1-win-x64.exe.blockmap
latest.yml

正式公开发布以 GitHub Release 和 tag 为准；上一公开版本 0.5.0 的 SHA256 记录保留在 Desktop 发布验收 Runbook 中。

当前安装包允许 unsigned 发布，release note 会保留 SHA256 校验值。未来如果购买代码签名证书，可以开启 CCR_REQUIRE_SIGNED=1 做强制签名门禁。

路线图

| 版本线 | 重点 | | --- | --- | | 0.5.x | 多模态、多模型、工具调用、MCP 管理面、错误诊断、历史会话、发布质量继续稳定化 | | 0.6.0 | Skill、Plugin、外部能力包治理、能力发现、安装启用、命名空间和审计 | | 后续 | 跨供应商能力路由、音频 / 视频 / 文件生成、更多 provider conformance matrix |

0.5.x 期间不会把没有能力声明的模型伪装成全能模型，也不会默认跨供应商发送用户数据。所有 provider 能力都应进入模型目录、Profile 覆盖或显式工具配置。

文档导航

如果你是第一次看这个仓库，建议按这个顺序读：

如果你要继续开发某个 provider，直接看：

常见问题

为什么默认 README 是中文？

CCR 当前主要维护和协作场景是中文环境，很多路径、Windows PowerShell、Desktop 体验和 provider 调试记录都来自中文工作流。英文版保留在 README.en.md。

为什么 Windows 安装包会提示未知发布者？

当前没有购买代码签名证书，所以安装器允许 unsigned 发布。请以 GitHub Release 地址和 release note 中的 SHA256 校验值确认来源。

为什么生图要先落盘？

不同 provider 返回结果不同：OpenAI / MiniMax 可能返回 base64，GLM 可能返回临时下载 URL，Codex OAuth 走 hosted tool。CCR 统一落盘后再展示，能保证缩略图、预览、历史恢复和复制路径行为一致。

为什么不是所有模型都能发图片或生图？

CCR 不靠模型名猜能力。模型是否支持图片输入、工具调用、结构化输出或图片生成，必须来自内置能力目录、Profile 覆盖或 provider 明确声明。

为什么要用 `.ccr` 而不是 `.claude`？

CCR 需要和 Claude Code、Codex、OpenClaw 等本机工具并存。项目级设置放在 .ccr/settings*.json，可以避免权限、配置和历史文件互相污染。

`README.zh-CN.md` 和 `README.md` 有什么区别？

当前两者内容保持一致，README.md 是 GitHub 默认中文入口，README.zh-CN.md 保留给旧链接和明确语言文件名使用。

重要边界

CCR 不是 Anthropic 官方源码发布版本。
CLAUDE.md 在恢复代码的部分流程中仍是兼容文件名。
一些 Anthropic、Claude、Claude Desktop、Chrome extension、GitHub App 和 remote-session 文案可能仍会保留，因为它们指向真实外部服务或协议。
新增或面向用户展示的产品身份，应统一使用 CCR 或 ccr。
0.5.x 不默认跨供应商路由用户数据；跨供应商能力路由要等后续显式设计和配置。

问题反馈

可以在 CCR 内使用 /bug 命令，也可以提交 GitHub issue。

上游参考

上游源码来源：@anthropic-ai/[email protected]
上游产品介绍：Claude Code
上游文档参考：code.claude.com/docs