从克隆到精通,一步步配置和使用 RedCode 的全部功能。
- Bun 1.3+
- Windows 10/11(仅测试此平台,其他平台需自行适配)
- Git
git clone https://github.com/JiaHuiRed/RedCode.git
cd RedCode
bun install
# 启动 TUI(终端界面)
bun dev
# 或启动桌面 GUI
cd packages/desktop && bun run dev嫌敲命令麻烦?直接双击两个一键 bat 即可: TUI →
packages/opencode/build.bat;桌面 GUI →packages/desktop/build-and-package.bat。
# TUI 单文件 exe(可在无 Bun 环境的机器运行)
# 产物本来就是 Windows 单目标,无需额外开关
cd packages/opencode && bun run build
# 桌面 GUI
cd packages/desktop && bun run build && bun run package第一次启动时,系统自动:
- 创建
~/.redcode/目录(存放全局配置和记忆),以及souls/子目录(memory/只作归档,不再写入) - 保留式迁移旧
Tsoul.md/Gsoul.md,再补齐souls/karina.md、souls/yuqi.md与MEMORY.md的缺省模板——模板编译时内嵌在二进制里,已有文件与自定义正文不覆盖,旧文件保留 - 从可找到的
seed/skill/播种技能到~/.redcode/skill/(只补不覆盖)。先查当前目录,再查可执行文件上一级的seed/skill/;单独复制 exe 不保证附带这些文件,缺失时会记录警告,技能也可自行安装 - 加载配置、MCP 服务器与 skill 技能
- 启动 TUI/GUI 界面
你已经可以开始聊天了。 但要想发挥全部能力,继续往下看。
RedCode 支持多种模型。首次启动后,你需要至少配置一个 provider 才能对话。
建议先在 ~/.redcode/redcode.local.jsonc(全局、仅本机)中添加。下面的密钥只是占位符,真实密钥不要写进要提交或同步的配置:
注意两点(写错了不会报错,只会静默失效):
- 没有
type字段。决定用哪个协议适配器的是npm。 apiKey/baseURL必须嵌在options里,不能放在 provider 顶层。多余的键会被静默丢弃,结果是一个没有凭据的 provider,且不产生任何报错。
provider 顶层可用的键只有:npm、options、models、name、api、env、id、whitelist、blacklist(定义见 packages/opencode/src/config/provider.ts)。
常用的 npm 适配器:
| 适配器 | 适用 |
|---|---|
@ai-sdk/openai-compatible |
绝大多数第三方/自建服务(DeepSeek、GLM、MiniMax、各类中转、Ollama 的 /v1) |
@ai-sdk/anthropic |
Anthropic 官方 API |
@ai-sdk/google |
Google Gemini 官方 API |
参考配置示例(本地 Ollama,省略 npm 时默认按 OpenAI 兼容处理):
{
"provider": {
"ollama": {
"options": { "baseURL": "http://localhost:11434/v1" },
"models": {
"qwen3.5:9b-q8_0": { "name": "Qwen3.5 9B" },
},
},
},
"model": "ollama/qwen3.5:9b-q8_0",
}仓库里的
seed/redcode.home.jsonc是一份可直接参照的真实配置模板。
redcode.jsonc 的 username 字段提供用户名称(不填则用电脑名):
{ "username": "哥哥" }具体称呼、AI 的性格、语气与协作方式写在灵魂文件里(见 5.1)。0.8.2 之前这些散在
~/.redcode/USER.md,与灵魂文件大量重复,已下线;老用户那份文件留着不会再被加载,可以自行删除。
Soul 文件定义 AI 的身份、性格、语气与协作方式。TUI 和 GUI 都可以选择同一份 Soul:
$EDITOR ~/.redcode/souls/karina.md
$EDITOR ~/.redcode/souls/yuqi.md灵魂文件内容自由格式,但建议包括:
- AI 的身份和名字
- 怎么称呼你
- 语气风格(简洁/详细、正式/随意)
- 重点帮你做什么
- 不该碰的话题
人格自动加载:新会话保存所选 Soul 的 ID,之后由这个 ID 加载人格,不再由客户端决定身份。TUI 用 /soul,GUI 用设置里的 Soul 选择器修改后续新会话的默认值;当前会话不换人格。Soul 文件保存后在新会话生效。
配置里没有 "provider 类型" 这个概念——决定走哪套协议的是 npm 字段,填的是 AI SDK 适配器包名。
npm |
API 格式 | 适用 |
|---|---|---|
@ai-sdk/openai-compatible |
OpenAI 兼容 | DeepSeek、Moonshot、Ollama、Groq、Step、GLM、MiniMax、各类中转 |
@ai-sdk/anthropic |
Anthropic 原生 | Claude 官方 API |
@ai-sdk/google |
Gemini 原生 | Google Gemini 官方 API |
绝大多数国内服务和自建服务都提供 OpenAI 兼容端点,用第一行即可——GLM、MiniMax 也在此列,它们不需要专门的适配器。省略 npm 时按 OpenAI 兼容处理。
对话时点击模型选择器切换,或在 redcode.jsonc 中设置默认模型:
"model": "my-provider/my-model"2.1 的 Ollama 示例用的是另一个模型,只为给出最小可抄的形状;这里换成 coder 模型,顺带演示
temperature/tool_call/limit的完整写法。
# 安装 Ollama
# 下载模型
ollama pull qwen2.5-coder:7b
# 在 redcode.jsonc 中配置
{
"provider": {
"ollama": {
"options": { "baseURL": "http://localhost:11434/v1" },
"models": {
"qwen2.5-coder:7b": {
"name": "Qwen2.5 Coder 7B",
"temperature": true,
"tool_call": true,
"limit": { "context": 32768, "output": 8192 }
}
}
}
},
"model": "ollama/qwen2.5-coder:7b"
}MCP(Model Context Protocol)让 AI 按需要接入外部工具。
仓库的 seed/redcode.home.jsonc 提供以下服务的配置模板,不代表首次启动就已安装全部依赖。先安装对应程序,再启用所需服务;本机是否可用,以实际配置与连接状态为准。
| 服务器 | 用途 | 首次使用前 |
|---|---|---|
| jCodeMunch | 结构化代码检索:符号、引用、调用链与影响范围,具体工具取决于白名单 | 安装服务后,让 AI 用 jcodemunch_index_folder 索引目标工程;模板关闭 AI 摘要,可按需开启 |
| 服务器 | 用途 | 首次使用前 |
|---|---|---|
| markitdown | 二进制文档转 Markdown:.docx/.xlsx/.pptx/.pdf 等 read 读不了的文件用它提取文本 |
— |
| fff | 高性能文件查找/grep(fff_find_files/fff_grep/fff_multi_grep) |
— |
SQLite 结构化查询使用原生工具 sqlite_query,不再是 MCP 服务器;源码构建时由同步脚本把 seed/tool/sqlite.ts 播种到 ~/.redcode/tool/。
| 服务器 | 用途 | 首次使用前 |
|---|---|---|
| Web Search | 网页搜索:DuckDuckGo + Yahoo 兜底,内置服务,零 API Key | — |
| webqa | 浏览器自动化(Playwright):observe 语义快照 + aria-ref 定位、坐标点击(canvas/自绘控件)、滚轮/悬停/多标签、元素级截图,做 Web 前端验证闭环 | — |
| 服务器 | 用途 | 首次使用前 |
|---|---|---|
| su-prememory | 可选的本地记忆库服务;模板的 tools: [] 不向模型暴露工具,需要时再配置白名单。记忆维护仍须遵守索引与全文双写 |
本地记忆库与服务依赖 |
| mcp-process-mgmt | 管理交互式/长驻 shell 会话(REPL、dev server 等需要 stdin 的进程) | — |
曾预配置过的 gbrain(记忆)、Exa Search(语义搜索)、Agent Reach(B站/抖音/GitHub 统一搜索)已彻底移除(gbrain 元数据损坏且功能被 su-prememory 覆盖;Exa 与 Web Search 冗余;Agent Reach 实际使用率过低,插件源码已删除)。
{
"mcp": {
"my-server": {
"type": "local", // local = 本地进程
"command": ["node", "./path/to/server.js"],
"environment": {
"API_KEY": "xxx",
},
"timeout": 30000, // 可选,默认 30s
"enabled": true,
},
},
}本地 MCP 也可以用 npx、uvx 等工具启动,或在 ~/.redcode/redcode.jsonc 中添加永久配置。
Soul 是助手身份的唯一来源,客户端只负责选择新会话的默认值:
- Soul Registry 发现
~/.redcode/souls/*.md,解析身份元数据与人格正文。 - 客户端偏好 分别记住 TUI / GUI 上次选择的 Soul,只影响之后新建的根会话。
- 会话绑定 将 Soul ID 存入
session.soul;继续旧会话、fork 和子代理都保留原身份。
显示名、会话标题前缀与 commit 署名都来自所绑定的 Soul,不再根据 TUI / GUI 猜测。文件缺失或无效时会明确提示,并保留原绑定,不偷偷换成另一个人格。
0.8.2 之前还有一层
~/.redcode/USER.md(用户画像),内容与灵魂文件大量重复,每轮白吃一道加载,已下线。
在对话中输入:
/soul # TUI:打开选择器
/soul karina # TUI:选择指定 ID
GUI 在 设置 → 个性化 → Soul 中选择新会话的默认人格。两端的偏好独立保存,已有会话显示自己绑定的 Soul。
选择只影响后续新会话,当前会话保持原人格。 旧 /tui-persona、/gui-persona 已弃用,不应再用来向当前会话手动加载另一份人格正文。
在 ~/.redcode/souls/ 添加一个 Markdown 文件即可,不需要给客户端或核心代码增加人格分支。例如 chi.md:
---
id: chi
name: 赤
display_name: 赤
commit_prefix: Chi
avatar: chi
description: 擅长简洁分析与清晰解释
---
# 赤
在这里写身份、语气与协作方式。id 是唯一、稳定的小写标识,只允许字母、数字、- 和 _,且首字符必须是字母或数字。name 必填;display_name、commit_prefix、avatar、description 可选,avatar 只是资源键,description 是用于 /soul 选择器展示与搜索的简短单行说明,最多 256 个 UTF-8 字节。未填写时继续显示名称或 ID。Soul 不配置模型、权限、MCP 或执行策略;description 不会注入模型提示词。
每份文件上限 16 KiB(UTF-8 字节),超限整份拒绝,不截断人格正文;无效文件或重复 ID 会显示问题,不影响其它有效 Soul。编辑文件不会热替换当前会话的快照,新会话才使用新正文。
首次启动自动补齐缺省模板。旧 Tsoul.md / Gsoul.md 迁移时保留原文件与正文;明显自定义的人格使用稳定的 legacy ID,不冒充官方人格,也不覆盖已有目标文件。
长期记忆由规则与 memory skill 引导 AI 维护,引擎负责加载已有的记忆文件,不会把每段对话自动提炼成长期教训。记忆分两层:
- 项目级
.redcode/MEMORY.md——当前项目的决策、踩坑与工作路标 - 全局级
~/.redcode/MEMORY.md——跨项目通用的历史教训
两层同时注入(全局在前、项目在后),不是二选一。
早期版本还有一层当日日志(
~/.redcode/memory/YYMMDD.md),260729 起退役——实测几乎无人主动读、写入质量也不稳定,历史文件保留可查,不再写入。
记忆已索引化:MEMORY.md 正文只存索引行(编号 + 4-8 字主题 + 关键动作词),完整教训全文落在本地记忆库 ~/.redcode/supermemory.db(memories 表,project=global/项目名,FTS5 全文索引)。写入必须双写——MEMORY.md 加索引行 + 数据库存全文,缺一不可。
配套核对机制:
- 自检脚本
bun ~/.redcode/scripts/check-memory-dualwrite.mjs——每个#NN索引行必须对数据库全文,缺则列出 - 长期记忆只在本机维护,
MEMORY.md与supermemory.db不进入同步仓库;双写核对在本机运行 - 260825 定案:索引化前的存量项目(正文无
#NN索引行结构)不做一次性迁移,在该工作区整理记忆或收尾时就地索引化(全文入库 + 正文改写为索引行)
收工时,AI 自动:
- 审视当前项目的
.redcode/MEMORY.md,删掉已完成、过时的进度段,保留经验教训 - 把跨项目通用的教训摘入全局
~/.redcode/MEMORY.md - 每条过三道门禁(换项目仍成立?忘了会再踩且修复贵?未被 AGENTS.md/skill 覆盖?)
全局记忆每轮都要付 token,只留值得长期持有的条目。进度正文放项目 .redcode/docs/,MEMORY.md 只留工作路标;参考文档同样放在项目 .redcode/ 下,只留一句指针。
两条 MEMORY.md 由引擎固定注入(session/instruction.ts 的 systemPaths 硬编码路径),没有官方开关。确实不想要的话:清空两份 MEMORY.md 内容,或改 instruction.ts 重新编译(不推荐)。
按加载顺序排列,后加载的覆盖先加载的:
| 文件 | 作用域 | 说明 |
|---|---|---|
~/.redcode/redcode.jsonc |
全局 — 所有项目 | 通用 provider、MCP、权限规则 |
~/.redcode/redcode.local.jsonc |
全局 · 仅本机 | 机器本地覆盖层,优先级高于上一行。放绝对路径、按显存挑的模型档位这类因机而异的值;多机同步时把它 gitignore 掉,见 10.2 |
项目根 redcode.jsonc |
项目级 | 覆盖或补充全局配置 |
项目内 .redcode/redcode.jsonc |
项目级 | 同上;会从当前目录逐级向上查找到 worktree 根,适合放在子目录里做局部覆盖。同目录下的 redcode.local.jsonc 同样生效且优先级更高 |
其余全局资源(不是配置文件,但同样从 ~/.redcode/ 读):
| 路径 | 内容 |
|---|---|
~/.redcode/MEMORY.md |
长期记忆,AI 自动读写 |
~/.redcode/souls/*.md |
Soul 元数据与人格正文,按会话保存的 Soul ID 注入 |
~/.redcode/skill/ command/ agent/ |
全局技能、斜杠指令、子代理定义(agent/ 与 agents/ 两种目录名都认) |
~/.redcode/plugin/ themes/ |
全局插件与自定义主题 |
配置合并规则:深合并,项目级覆盖全局级,
instructions数组拼接而非替换。 注意redcode.local.*只由人手写——引擎自身写回配置(例如在界面里切主题)落在redcode.jsonc,不会污染本地层。
权限门控由代码强制层(doom_loop 检测,服务端拦截)兜底,配合默认规则、配置中的 permission 与各 agent 的规则工作。内置子代理定义随程序编译,自定义子代理可放在 ~/.redcode/agent/。行为指令层(ECC_PROFILE guardrail)已退役。
ask、allow、deny 分别表示询问、放行、拒绝;工具调用权限接口不代表一定弹窗,命中 allow 时会直接执行。例如,想让历史会话查询先询问,可以配置:
{ "permission": { "session_query": "ask" } }session_query 默认只查当前工程的其它会话,显式指定 directory: "*" 才会跨工程。这个参数只是查询范围,不是用户授权;历史内容也不构成当前操作的授权。
软层——递进提醒(session/repeat-tool-reminder.ts,0.8.17 起):同一工具+同一参数连续调用 3 / 5 / 8 次时,把 [System notice] 提醒贴在该次结果尾部让模型自纠——不打扰你,纯建议。轮询类调用(每次输出在变)只会触发这层。todowrite/todoread 这类记账工具不计数也不打断计数。
硬层——权限弹窗(processor.ts doom_loop 检测),自动检测两种模式:
- 精确重复:同一工具+同一输入连续 3 次,且至少一次报错,或输出也完全相同(全成功的原地空转)
- 周期循环:6 步内形成 A→B→A→B 或 A→B→C→A→B→C 模式,且至少一次报错
检测触发时向用户提示确认,防止 AI 无意识空转。默认配置 doom_loop: "ask"。
AI 正在干活时你发的消息怎么处理,redcode.jsonc 顶层 busy_enter 二选一:
{
// "steer"(默认):插话——消息在下一个工具调用结束后立刻送达模型,
// 适合中途纠偏("别改那个文件"),不用等本轮跑完
// "queue":排队——消息对当前轮完全隐藏,本轮结束后自动作为新一轮的输入,
// 适合攒任务("下一件事做 X"),不打断当前思路
"busy_enter": "steer",
}TUI 和 GUI 都可以直接 /busy-enter 切换(命令面板同样可搜"繁忙时消息"),GUI 还可以在 设置 → 通用设置 → 繁忙时消息送达 下拉切换。三个入口都走 API 写回 redcode.jsonc 并强制重载配置,立即生效不用重启;手改配置文件则需重启。
排队消息由服务端持久化,重启后仍可恢复:TUI 用 /pending 逐条送达、编辑或取消,GUI 在排队消息上直接操作。TUI 的 QUEUED 徽标表示消息尚未装配进模型上下文,不等于消息已丢失。
会话列表太长时,把做完的会话归档——它从首页列表消失,但数据一个字节都不删(只是打了个时间戳,列表查询默认过滤掉带时间戳的)。
| 操作 | 位置 |
|---|---|
| 归档 | 首页会话行/看板卡片 右键 → 归档会话;或命令面板 session.archive;或 Ctrl+Shift+Backspace |
| 查看已归档 | 首页搜索框右侧的归档图标按钮,切换后列表显示已归档会话 |
| 取消归档 | 在已归档视图里 右键 → 取消归档,会话立刻回到正常列表 |
归档不省磁盘(消息和历史都还在库里)。想真正释放空间只能删会话,那是不可逆的。
见 第 4.5 节。
| 界面 | 位置 |
|---|---|
| TUI | 侧边栏 Context 块(常驻) |
| GUI | 输入控件行里模型名旁边的圆环;悬浮看用量,点击弹出精简会话确认窗。详细账本从右侧「上下文」入口打开 |
两边都显示:当前占用 / 模型标称窗口 · 占用率、会话累计、解码速率与首字延迟、in/out/思考 token、缓存读写与命中率、花费。
颜色按绝对上下文用量提示,不按百分比,也不代表正在执行某种压缩操作。 当前 GUI 的提醒档位:
| 颜色 | 上下文用量 |
|---|---|
| 绿 | < 320k |
| 黄 | 320k–360k |
| 橙 | 360k–400k |
| 红 | ≥ 400k |
原生自动压缩开启时,模板的 compaction.native.trigger_tokens 为 400k,实际触发还受模型可用窗口限制。旧的工具输出 prune 在当前模板中已关闭,不能把橙色理解成“已经开始裁剪工具结果”。
日常可主动精简:TUI 在命令面板选择 /compact 或按 <leader>c,GUI 点击圆环或在命令面板选择精简会话,都会先确认。用量数字仍以模型标称窗口为分母显示,与颜色档位分开读取。
解码速率与首字延迟是两回事,所以分开显示。 52.4 tok/s · 首字 2.3s——首字慢是排队与
预填(供应商侧负载、上下文长度),解码慢是吐字本身。合成一个「总速度」会让这两种完全不同
的问题看起来一样。
| 块 | 数据来自 | 覆盖范围 |
|---|---|---|
| 真实构成 | 服务端在请求真正发出的那一刻记的账 | 系统提示 / 工具定义 / 对话,工具定义还列出最贵的 8 个 |
| 上下文拆分 | 客户端按字符数估算 | 只有消息——看不到系统提示与工具定义 |
差别不是精度是范围:系统提示与工具定义这两块从来没到过客户端,估算器手里根本没有这份数据, 而它们恰恰是前缀里最大且最不透明的部分。想知道「哪个 MCP 挂上来悄悄吃掉几千 token」,看 真实构成里的工具定义那一列。
真实构成只留最后一轮、只在服务端内存里。会话在本次启动后还没发过请求时显示「暂无」,下一轮 请求后就有了。
回复末尾出现 输出被截断(达到 token 上限) 时,说明模型撞到单次输出上限被切断,不是话 说完了——TUI 显示在消息尾行(警示色),GUI 是一条分割线。
以下包含内置入口和随仓库播种的命令;客户端差异在表内注明:
| 命令 | 作用 |
|---|---|
/goal <目标> |
钉住会话目标,防止 AI 跑题(见 8.1) |
/goal clear |
清掉当前目标 |
/goal done |
标为完成,自动归档教训 |
/soul [ID] |
打开 Soul 选择器,或按 ID 直接选择(TUI);只影响后续新会话,见 5.2 |
/recall <关键词> |
按关键词从记忆库(含 supermemory.db)语义召回历史教训 |
/subtask <任务> |
在隔离子会话中执行子任务,上下文隔离不污染当前会话(父流程等待结果) |
/commit |
按 conventional commit 格式提交代码 |
/changelog |
生成 CHANGELOG.md 条目 |
/issues |
查看或创建 GitHub issues |
/learn |
从当前会话提取非显而易见的教训写入 AGENTS.md |
/translate |
把改动的英文文档/UI 文案翻译成其他语言 |
/rmslop |
清理本分支引入的 AI 代码痕迹(多余注释/防御性代码等) |
/spellcheck |
检查改动的 Markdown 文件拼写和语法 |
/ai-deps |
排查 AI SDK 依赖可升级的 minor/patch 版本 |
/lan |
打开或查看手机(局域网)远程访问入口 |
/busy-enter |
切换繁忙时消息送达:插话 ↔ 排队(TUI/GUI 均内置,立即生效,见 7.3) |
/compact |
打开精简会话确认:TUI 命令面板或 <leader>c;GUI 命令面板或上下文圆环 |
/pending |
管理排队消息,逐条送达、编辑或取消(TUI;GUI 在排队消息上直接操作) |
命令文件位于 seed/command/ 和 ~/.redcode/command/,纯文本,可以自己添加或修改;/soul、/busy-enter、/compact、/pending 是内置入口,不在命令文件里。
目标不是纯 prompt 引导,是落库状态——钉住之后每轮都会注入系统提示,直到 /goal done 或
/goal clear。落库依赖 goal_set / goal_done / goal_clear 三个工具,而它们默认关闭:
需要环境变量 REDCODE_ENABLE_GOAL_TOOLS=true(不是配置文件项)。工具没开时 /goal
仍会把目标写进本轮提示词,但不会持久化,换会话/重启就丢。
| 界面 | 位置 | 显示什么 |
|---|---|---|
| TUI | 侧边栏,Todo 上方 | 目标原文 + 状态 + 该目标已用 token |
| GUI | 侧栏 Plan 标签页顶部 | 同上 |
状态有五种:进行中 / 已完成 / 受阻 / 预算用尽 / 已清除。清除后这块整个消失。
开了自动续跑(experimental.goal_auto_continue,默认关)之后会多一条预算进度:
已用 / 预算 · 自动续跑第 n/20 轮。没开的时候只显示已用量、不显示分母——20 轮上限与
预算天花板只在自动续跑开着时才真的会拦人,关着还画进度会让人以为有个并不存在的限制在逼近。
预算默认 200k tokens,改 experimental.goal_token_budget。用超了会自动标成「预算用尽」并让
AI 收尾。
Skill 是扩展 AI 行为的机制——本质上是注入给 AI 的指令文件。
| Skill | 作用 | 触发词 |
|---|---|---|
| memory | 记忆的写与剪:双层 MEMORY.md 注入 + 索引化双写 + 剪枝阈值 | "整理记忆""记忆太长了" |
| ce-code-review | 结构化多维度代码审查 | "帮我看看代码""review一下" |
| diagnose | 形式化 bug 诊断循环 | "查bug""排查一下""debug" |
| tdd-flow | 测试先行、假阳性过滤与置信度门控,已整合原 defensive-agent | "认真做""用 TDD""别乱改" |
| goal-automation | 检测大任务并建议钉住目标 | 自动检测 |
| gui-regression | 用 webqa 实测长会话、流式输出、IME、分页与面板拖拽 | GUI 改动后的定向回归 |
| frontend-design | 生成 macOS 风格的高质量前端界面,避免 AI 通用观感 | "做个页面""写个组件" |
| simplify | 检测过度工程,建议精简 | "太复杂了""精简一下" |
| red-scribe | Red 的写作风格与中英去 AI 味,已整合 yuqi-slop、stop-slop | "按我的风格写""去AI味" |
| effect | 在本仓编写与调试 Effect v4 代码(service / layer / Schema / 类型化错误) | 写或调 Effect 代码时 |
| harmonyos-android-compat | Android 应用移植/验证到华为鸿蒙(HarmonyOS 6+、卓易通) | 鸿蒙移植与兼容验证时 |
以上 11 个随仓库分发(seed/skill/),找到种子目录时会播种到 ~/.redcode/skill/。播种不覆盖本机已有的同名技能;更新仓库不等于自动更新个人修改过的副本。
下面这些只存在于维护者本机的 ~/.redcode/skill/,不在仓库里,克隆的人不会有——举例说明个人库可以怎么扩展(不是全量清单,个人库随维护者习惯持续增删):
| Skill | 作用 | 触发词 |
|---|---|---|
| new-project | 新项目脚手架 | "新项目""搭个项目" |
| bump-version | 一键升版 | "升版""bump""放版" |
| config-edit | 安全修改 RedCode 配置 | "改配置""加 MCP" |
| technical-documentation | 构建与检查技术文档 | "写 README""审文档" |
# 在 ~/.redcode/skill/ 下创建目录和 SKILL.md
mkdir -p ~/.redcode/skill/my-rules
$EDITOR ~/.redcode/skill/my-rules/SKILL.mdSKILL.md 需要 YAML frontmatter(name + description),引擎靠 description 语义匹配自动触发:
---
name: my-rules
description: 我的编码规范。用户说"按规范来""检查规范"时触发。
---
# 我的编码规范
- 所有函数必须有 TypeScript 类型注解
- 使用 `const` 而非 `let`
- 避免 `any` 类型
- 行尾不要分号无需在 redcode.jsonc 中注册——引擎自动扫描 ~/.redcode/skill/ 下所有 SKILL.md,重启对话即生效。
仓库(公开) 用户本地(私有)
seed/ ~/.redcode/
├── skill/ ← 种子 ├── souls/*.md ← 你的人格(karina / yuqi,首启由内嵌模板播种)
├── command/ ← 种子 ├── MEMORY.md ← 你的记忆
├── tool/sqlite.ts ← 种子 ├── supermemory.db ← 本机长期记忆全文
├── scripts/ ← 种子 ├── skill/ command/ agent/
└── redcode.home.jsonc ← 配置模板 └── data/ ← 会话 DB / 日志 / 快照
(seed/ 是播种源,不是项目配置目录;技能首启播种见第 1 节,其余共享资源由 script/sync-home.bat 同步。
人格与 MEMORY 模板已内嵌进二进制,见 packages/opencode/src/project/template/)
内置子代理(explore/execute)定义在 packages/opencode/src/agent/definition/,构建时内联,不复制到用户目录;自行编写的 ~/.redcode/agent/*.md 仍可使用。
- 仓库仅包含模板和共享配置,没有任何你的个人数据
~/.redcode/不在仓库中,不会被推送- 其他人克隆此项目只会看到空白模板
多台电脑可用私有 GitHub 仓库同步人格、技能、自定义命令、插件与不含密钥的共享配置,不要直接同步整个 ~/.redcode/。
长期记忆只在本机维护和备份:MEMORY.md、supermemory.db 及其备份不进入同步仓库。会话数据、凭据和本地覆盖配置也必须排除。
# 第一台电脑:初始化私有仓
cd ~/.redcode
# 创建 .gitignore 排除机器本地数据
# data/ 含会话数据库和凭据;长期记忆、备份和本地配置也不共享
@'
data/
cache/
state/
locks/
node_modules/
MEMORY.md
MEMORY-archive.md
supermemory.db*
memory/
backup/
scripts/
temp/
redcode.local.json
redcode.local.jsonc
'@ | Set-Content -Encoding utf8 .gitignore
git init
git add .gitignore
git commit -m "init"
# 在 GitHub 创建一个 Private 仓库
git remote add origin https://github.com/你的用户名/redcode-private.git
git push -u origin main
# 第二台电脑:克隆
cd ~
git clone https://github.com/你的用户名/redcode-private.git .redcode
git clone https://github.com/JiaHuiRed/RedCode.git之后只用 git add <具体文件> 暂存确认可共享的内容,例如 git add souls/karina.md。.gitignore 不会自动移除已经被 Git 跟踪的文件,同步前要检查暂存内容;共享配置中也不能包含 provider.options.apiKey 等真实密钥。
日常同步:
# 在家:改完就推
cd RedCode && git push
cd ~/.redcode && git push
# 在公司:先拉
cd RedCode && git pull
cd ~/.redcode && git pull同步 ~/.redcode/ 会遇到一个必然的问题:配置里有些值天生因机而异——某个 MCP 的绝对安装路径、按显存挑的本地模型档位、只有一台机器装了的服务。它们一旦写进被同步的 redcode.jsonc,就会进入死循环:这台机改好推上去,另一台拉下来直接报错(路径不存在,MCP 启动失败);在另一台改回来,轮到这台报错。
解法是把这类值下沉到 ~/.redcode/redcode.local.jsonc,它加载在 redcode.jsonc 之后、优先级更高,且不进版本库:
// ~/.redcode/redcode.local.jsonc —— 只在这台机器上生效
{
"$schema": "https://redcode.dev/config.json",
"mcp": {
"indexgraph": {
"type": "local",
"command": ["node", "D:/AI/IndexGraph/mcp-server.js"], // 换台机器路径就不同
"enabled": true,
},
},
}在 ~/.redcode/.gitignore 里加上:
redcode.local.json
redcode.local.jsonc
判断标准很简单:这个值换台机器还成立吗? 不成立就放本地层。同步文件里只留机器无关的东西——provider、权限规则、以及用 $REDCODE_ROOT 表达的相对路径命令。
RedCode 目前主要在 Windows 10/11 上开发和测试。跨平台兼容性问题欢迎提交 PR。
如有其他问题,请查看 CHANGELOG.md 了解版本历史,或提交 GitHub Issue。
{ "provider": { "deepseek": { "npm": "@ai-sdk/openai-compatible", "options": { "apiKey": "sk-xxxxxxxx", "baseURL": "https://api.deepseek.com/v1", }, }, }, "model": "deepseek/deepseek-chat", }