Skip to content

Latest commit

 

History

History
715 lines (508 loc) · 37.5 KB

MANUAL.md

File metadata and controls

715 lines (508 loc) · 37.5 KB

RedCode 用户手册

从克隆到精通,一步步配置和使用 RedCode 的全部功能。


目录

  1. 快速启动
  2. 首次设置
  3. 配置模型
  4. MCP 服务器
  5. AI 人格系统
  6. 记忆系统
  7. 配置详解
  8. 内置命令
  9. Skill 技能系统
  10. 隐私与多机同步

1. 快速启动

前置要求

  • 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

启动后发生了什么

第一次启动时,系统自动:

  1. 创建 ~/.redcode/ 目录(存放全局配置和记忆),以及 souls/ 子目录(memory/ 只作归档,不再写入)
  2. 保留式迁移旧 Tsoul.md / Gsoul.md,再补齐 souls/karina.md、souls/yuqi.md 与 MEMORY.md 的缺省模板——模板编译时内嵌在二进制里,已有文件与自定义正文不覆盖,旧文件保留
  3. 从可找到的 seed/skill/ 播种技能到 ~/.redcode/skill/(只补不覆盖)。先查当前目录,再查可执行文件上一级的 seed/skill/;单独复制 exe 不保证附带这些文件,缺失时会记录警告,技能也可自行安装
  4. 加载配置、MCP 服务器与 skill 技能
  5. 启动 TUI/GUI 界面

你已经可以开始聊天了。 但要想发挥全部能力,继续往下看。


2. 首次设置

2.1 添加 AI 模型

RedCode 支持多种模型。首次启动后,你需要至少配置一个 provider 才能对话。

建议先在 ~/.redcode/redcode.local.jsonc(全局、仅本机)中添加。下面的密钥只是占位符,真实密钥不要写进要提交或同步的配置:

{
  "provider": {
    "deepseek": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://api.deepseek.com/v1",
      },
    },
  },
  "model": "deepseek/deepseek-chat",
}

注意两点(写错了不会报错,只会静默失效):

  • 没有 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 是一份可直接参照的真实配置模板。

2.2 设置称呼

redcode.jsonc 的 username 字段提供用户名称(不填则用电脑名):

{ "username": "哥哥" }

具体称呼、AI 的性格、语气与协作方式写在灵魂文件里(见 5.1)。0.8.2 之前这些散在 ~/.redcode/USER.md,与灵魂文件大量重复,已下线;老用户那份文件留着不会再被加载,可以自行删除。

2.3 自定义 AI 人格

Soul 文件定义 AI 的身份、性格、语气与协作方式。TUI 和 GUI 都可以选择同一份 Soul:

$EDITOR ~/.redcode/souls/karina.md
$EDITOR ~/.redcode/souls/yuqi.md

灵魂文件内容自由格式,但建议包括:

  • AI 的身份和名字
  • 怎么称呼你
  • 语气风格(简洁/详细、正式/随意)
  • 重点帮你做什么
  • 不该碰的话题

人格自动加载:新会话保存所选 Soul 的 ID,之后由这个 ID 加载人格,不再由客户端决定身份。TUI 用 /soul,GUI 用设置里的 Soul 选择器修改后续新会话的默认值;当前会话不换人格。Soul 文件保存后在新会话生效。


3. 配置模型

3.1 选哪个适配器(npm)

配置里没有 "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 兼容处理。

3.2 切换模型

对话时点击模型选择器切换,或在 redcode.jsonc 中设置默认模型:

"model": "my-provider/my-model"

3.3 本地模型(Ollama)

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"
}

4. MCP 服务器

MCP(Model Context Protocol)让 AI 按需要接入外部工具。

仓库的 seed/redcode.home.jsonc 提供以下服务的配置模板,不代表首次启动就已安装全部依赖。先安装对应程序,再启用所需服务;本机是否可用,以实际配置与连接状态为准。

4.1 代码智能

服务器 用途 首次使用前
jCodeMunch 结构化代码检索:符号、引用、调用链与影响范围,具体工具取决于白名单 安装服务后,让 AI 用 jcodemunch_index_folder 索引目标工程;模板关闭 AI 摘要,可按需开启

4.2 文件与文档

服务器 用途 首次使用前
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/。

4.3 网络与视觉

服务器 用途 首次使用前
Web Search 网页搜索:DuckDuckGo + Yahoo 兜底,内置服务,零 API Key —
webqa 浏览器自动化(Playwright):observe 语义快照 + aria-ref 定位、坐标点击(canvas/自绘控件)、滚轮/悬停/多标签、元素级截图,做 Web 前端验证闭环 —

4.4 记忆与进程

服务器 用途 首次使用前
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 实际使用率过低,插件源码已删除)。

4.5 添加自己的 MCP

{
  "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 中添加永久配置。


5. AI 人格系统

5.1 工作原理

Soul 是助手身份的唯一来源,客户端只负责选择新会话的默认值:

  1. Soul Registry 发现 ~/.redcode/souls/*.md,解析身份元数据与人格正文。
  2. 客户端偏好 分别记住 TUI / GUI 上次选择的 Soul,只影响之后新建的根会话。
  3. 会话绑定 将 Soul ID 存入 session.soul;继续旧会话、fork 和子代理都保留原身份。

显示名、会话标题前缀与 commit 署名都来自所绑定的 Soul,不再根据 TUI / GUI 猜测。文件缺失或无效时会明确提示,并保留原绑定,不偷偷换成另一个人格。

0.8.2 之前还有一层 ~/.redcode/USER.md(用户画像),内容与灵魂文件大量重复,每轮白吃一道加载,已下线。

5.2 选择 Soul

在对话中输入:

/soul          # TUI:打开选择器
/soul karina   # TUI:选择指定 ID

GUI 在 设置 → 个性化 → Soul 中选择新会话的默认人格。两端的偏好独立保存,已有会话显示自己绑定的 Soul。

选择只影响后续新会话,当前会话保持原人格。 旧 /tui-persona、/gui-persona 已弃用,不应再用来向当前会话手动加载另一份人格正文。

5.3 新增与编辑 Soul

在 ~/.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,不冒充官方人格,也不覆盖已有目标文件。


6. 记忆系统

6.1 概述

长期记忆由规则与 memory skill 引导 AI 维护,引擎负责加载已有的记忆文件,不会把每段对话自动提炼成长期教训。记忆分两层:

  • 项目级 .redcode/MEMORY.md——当前项目的决策、踩坑与工作路标
  • 全局级 ~/.redcode/MEMORY.md——跨项目通用的历史教训

两层同时注入(全局在前、项目在后),不是二选一。

早期版本还有一层当日日志(~/.redcode/memory/YYMMDD.md),260729 起退役——实测几乎无人主动读、写入质量也不稳定,历史文件保留可查,不再写入。

6.2 索引化与双写(260812 起)

记忆已索引化: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 索引行结构)不做一次性迁移,在该工作区整理记忆或收尾时就地索引化(全文入库 + 正文改写为索引行)

6.3 教训提炼

收工时,AI 自动:

  1. 审视当前项目的 .redcode/MEMORY.md,删掉已完成、过时的进度段,保留经验教训
  2. 把跨项目通用的教训摘入全局 ~/.redcode/MEMORY.md
  3. 每条过三道门禁(换项目仍成立?忘了会再踩且修复贵?未被 AGENTS.md/skill 覆盖?)

全局记忆每轮都要付 token,只留值得长期持有的条目。进度正文放项目 .redcode/docs/,MEMORY.md 只留工作路标;参考文档同样放在项目 .redcode/ 下,只留一句指针。

6.4 关闭记忆

两条 MEMORY.md 由引擎固定注入(session/instruction.ts 的 systemPaths 硬编码路径),没有官方开关。确实不想要的话:清空两份 MEMORY.md 内容,或改 instruction.ts 重新编译(不推荐)。


7. 配置详解

7.1 配置文件层次

按加载顺序排列,后加载的覆盖先加载的:

文件 作用域 说明
~/.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,不会污染本地层。

7.2 权限门控

权限门控由代码强制层(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 检测),自动检测两种模式:

  1. 精确重复:同一工具+同一输入连续 3 次,且至少一次报错,或输出也完全相同(全成功的原地空转)
  2. 周期循环:6 步内形成 A→B→A→B 或 A→B→C→A→B→C 模式,且至少一次报错

检测触发时向用户提示确认,防止 AI 无意识空转。默认配置 doom_loop: "ask"。

7.3 繁忙时消息送达(busy_enter)

AI 正在干活时你发的消息怎么处理,redcode.jsonc 顶层 busy_enter 二选一:

{
  // "steer"(默认):插话——消息在下一个工具调用结束后立刻送达模型,
  //   适合中途纠偏("别改那个文件"),不用等本轮跑完
  // "queue":排队——消息对当前轮完全隐藏,本轮结束后自动作为新一轮的输入,
  //   适合攒任务("下一件事做 X"),不打断当前思路
  "busy_enter": "steer",
}

TUI 和 GUI 都可以直接 /busy-enter 切换(命令面板同样可搜"繁忙时消息"),GUI 还可以在 设置 → 通用设置 → 繁忙时消息送达 下拉切换。三个入口都走 API 写回 redcode.jsonc 并强制重载配置,立即生效不用重启;手改配置文件则需重启。

排队消息由服务端持久化,重启后仍可恢复:TUI 用 /pending 逐条送达、编辑或取消,GUI 在排队消息上直接操作。TUI 的 QUEUED 徽标表示消息尚未装配进模型上下文,不等于消息已丢失。

7.4 归档会话(仅 GUI)

会话列表太长时,把做完的会话归档——它从首页列表消失,但数据一个字节都不删(只是打了个时间戳,列表查询默认过滤掉带时间戳的)。

操作 位置
归档 首页会话行/看板卡片 右键 → 归档会话;或命令面板 session.archive;或 Ctrl+Shift+Backspace
查看已归档 首页搜索框右侧的归档图标按钮,切换后列表显示已归档会话
取消归档 在已归档视图里 右键 → 取消归档,会话立刻回到正常列表

归档不省磁盘(消息和历史都还在库里)。想真正释放空间只能删会话,那是不可逆的。

7.5 添加自定义 MCP

见 第 4.5 节。

7.6 上下文用量:在哪看、怎么读

界面 位置
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——首字慢是排队与 预填(供应商侧负载、上下文长度),解码慢是吐字本身。合成一个「总速度」会让这两种完全不同 的问题看起来一样。

GUI 上下文标签页里有两块拆分,别混

块 数据来自 覆盖范围
真实构成 服务端在请求真正发出的那一刻记的账 系统提示 / 工具定义 / 对话,工具定义还列出最贵的 8 个
上下文拆分 客户端按字符数估算 只有消息——看不到系统提示与工具定义

差别不是精度是范围:系统提示与工具定义这两块从来没到过客户端,估算器手里根本没有这份数据, 而它们恰恰是前缀里最大且最不透明的部分。想知道「哪个 MCP 挂上来悄悄吃掉几千 token」,看 真实构成里的工具定义那一列。

真实构成只留最后一轮、只在服务端内存里。会话在本次启动后还没发过请求时显示「暂无」,下一轮 请求后就有了。

回复被砍断时会有标记

回复末尾出现 输出被截断(达到 token 上限) 时,说明模型撞到单次输出上限被切断,不是话 说完了——TUI 显示在消息尾行(警示色),GUI 是一条分割线。


8. 内置命令

以下包含内置入口和随仓库播种的命令;客户端差异在表内注明:

命令 作用
/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 是内置入口,不在命令文件里。

8.1 钉住的目标:钉了之后在哪看

目标不是纯 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 收尾。


9. Skill 技能系统

Skill 是扩展 AI 行为的机制——本质上是注入给 AI 的指令文件。

9.1 内置 Skill

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""审文档"

9.2 添加自定义 Skill

# 在 ~/.redcode/skill/ 下创建目录和 SKILL.md
mkdir -p ~/.redcode/skill/my-rules
$EDITOR ~/.redcode/skill/my-rules/SKILL.md

SKILL.md 需要 YAML frontmatter(name + description),引擎靠 description 语义匹配自动触发:

---
name: my-rules
description: 我的编码规范。用户说"按规范来""检查规范"时触发。
---

# 我的编码规范

- 所有函数必须有 TypeScript 类型注解
- 使用 `const` 而非 `let`
- 避免 `any` 类型
- 行尾不要分号

无需在 redcode.jsonc 中注册——引擎自动扫描 ~/.redcode/skill/ 下所有 SKILL.md,重启对话即生效。


10. 隐私与多机同步

10.1 隐私模型

仓库(公开)                   用户本地(私有)
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/ 不在仓库中,不会被推送
  • 其他人克隆此项目只会看到空白模板

10.2 多机同步

多台电脑可用私有 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 表达的相对路径命令。

10.3 跨平台注意事项

RedCode 目前主要在 Windows 10/11 上开发和测试。跨平台兼容性问题欢迎提交 PR。


如有其他问题,请查看 CHANGELOG.md 了解版本历史,或提交 GitHub Issue。