用 AI 工具在 kernelvibe 写代码

你的 AI 助手（Claude Code、Codex、Grok Build……）运行在你自己的电脑上，用你的账号和一个访问令牌来拉代码、推代码、开合并请求。kernelvibe 不会保存你的 AI 账号或模型密钥。

1. 准备账号和令牌（只做一次）

1. 注册并等管理员审核（见首页「怎么加入」）。要参与团队项目，把你的用户名告诉管理员，他会把你加进团队、给你建好自己的仓库。
2. 创建访问令牌：右上角头像 → 设置 → 左侧 应用 → 「访问令牌」里点 创建访问令牌（直达：/user/settings/applications）。
   • 令牌名称：写清楚给谁用，比如 claude-code-笔记本。一个工具一个令牌，出问题只删那一个。
   • 仓库和组织访问权限和选择权限，二选一：

   用法	仓库和组织访问权限	选择权限
   推荐：AI 推代码，还要开合并请求、回评论（要用下面的 tea 或 MCP）	全部（公开、私有和受限）	repository「读写」、issue「读写」、user「可读」；要用检查点和对话记录再加 package「读写」
   更保守：AI 只推代码到指定的几个仓库	仅限部分仓库（勾上要改的仓库）	repository「读写」（这种令牌加不了 user 权限，tea 登录会失败）

3. 点 生成令牌。令牌只显示这一次，马上存进密码管理器。

把令牌放进环境变量（写进你的 shell 配置文件，比如 ~/.zshrc 或 ~/.bashrc；Windows 用「系统环境变量」）：

export FORGEJO_ACCESS_TOKEN="这里粘贴你的令牌"

更安全的做法是让密码管理器的命令行工具在启动时取出令牌，而不是明文写在配置文件里。

2. 让 git 用上令牌

本站只支持 HTTPS（不支持 SSH）。仓库地址长这样：https://code.kernelvibe.com/用户名/仓库名.git

推荐：用 tea 保存登录

tea 是 Gitea 的命令行工具，本站（Forgejo）也能用。它可以兼做 git 的「凭据助手」，以后推拉都不再问密码，AI 也能用它开合并请求。从发布页下载对应系统的版本，然后：

tea login add --name kernelvibe --url https://code.kernelvibe.com --token "$FORGEJO_ACCESS_TOKEN" --helper
git clone https://code.kernelvibe.com/用户名/仓库名.git

不装 tea 也行

第一次推送时 git 会问用户名和密码：用户名填你的用户名，密码粘贴令牌，交给系统自带的凭据管理器保存。开了两步验证的账号只能用令牌。

提交身份

提交里的邮箱所有能看仓库的人都看得到。不想公开真实邮箱，就用本站给你的隐私邮箱：

git config --global user.name "你的用户名"
git config --global user.email "你的用户名@noreply.code.kernelvibe.com"

3. 接上你的 AI 工具

所有工具都能直接用 git 推拉。想让 AI 直接开合并请求、回评论、看议题，再接一个 MCP 服务：推荐 forgejo-mcp（专为 Forgejo 做的，作者在 Forgejo 15 和 16 上测过，合并请求、评审、合并、评论都有）。安装（需要先装 Go），或到它的发布页下载：

go install git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest

也可以只用 tea：让 AI 运行 tea pr create --title "…" --description "…" --base main --head 分支名 开合并请求，tea comment 编号 "内容" 回评论。

Claude Code

在仓库根目录放一个 .mcp.json（里面没有令牌，令牌从环境变量读，可以放心提交；Grok Build 也会读这个文件）：

{
  "mcpServers": {
    "kernelvibe": {
      "command": "forgejo-mcp",
      "args": ["--transport", "stdio", "--url", "https://code.kernelvibe.com"],
      "env": { "FORGEJO_ACCESS_TOKEN": "${FORGEJO_ACCESS_TOKEN}" }
    }
  }
}

第一次在这个仓库里打开 Claude Code 时会问你是否启用这个服务，选同意；会话里用 /mcp 查看状态。项目说明放 CLAUDE.md，里面写一行 @AGENTS.md 就能引用下面的通用模板。

Codex（命令行 / 编辑器插件 / 桌面版）

写进 ~/.codex/config.toml（命令行、插件、桌面版共用这一份）：

[mcp_servers.kernelvibe]
command = "forgejo-mcp"
args = ["--transport", "stdio", "--url", "https://code.kernelvibe.com"]
env_vars = ["FORGEJO_ACCESS_TOKEN"]

Codex 会自动读仓库里的 AGENTS.md。Codex 的云端任务目前不能挂自定义 MCP，只能用 git 推拉。

Grok Build（xAI 官方命令行）

安装，然后运行 grok（第一次运行会打开浏览器登录，要 SuperGrok / X Premium+ 订阅；也可以用 XAI_API_KEY）：

curl -fsSL https://x.ai/cli/install.sh | bash
grok

它会直接读取仓库里的 .mcp.json 和 AGENTS.md，跟 Claude Code 共用一套配置。也可以写进 ~/.grok/config.toml；git push 默认每次都要确认，想放行要显式允许：

[mcp_servers.kernelvibe]
command = "forgejo-mcp"
args = ["--transport", "stdio", "--url", "https://code.kernelvibe.com"]
env = { FORGEJO_ACCESS_TOKEN = "${FORGEJO_ACCESS_TOKEN}" }

[permission]
allow = ["Bash(git *)", "Bash(git push *)"]
deny = ["Bash(git push --force*)", "Bash(rm -rf *)"]

其他工具

• Cursor、aider：用的是你电脑上的 git，按第 2 步配好就能推。aider 不支持 MCP，开合并请求用 tea。
• opencode、Cline：支持 MCP，按上面同样的命令和参数接 forgejo-mcp；也都能选 Grok、Claude、GPT 等模型。

4. 推荐的工作流程

改自己的仓库

1. 让 AI 在新分支上改，不要直接推到 main。
2. 推送分支，开合并请求（MCP 或 tea）。
3. 在网页上看这次更改的「AI 改动档案」和「改了哪里」，确认后合并。

给别人的仓库提改动（你只有「可读」）

不用先复制一份到自己名下，一条命令就能在对方仓库开合并请求：

git push origin HEAD:refs/for/main/简短主题 -o title="标题" -o description="改了什么、为什么"

• 再推同一个主题会更新这个合并请求；改写过历史时加 -o force-push。
• 令牌仍然要有 repository「读写」（推送需要写权限的令牌，但不要求你对这个仓库有写权限）。
• 只能用 refs/for/，refs/draft 之类的写法本站不支持。

别让 AI 狂刷接口

同一个网络地址 10 秒内超过 100 次接口请求会被暂时拦 10 秒（git 推拉、页面里的图片样式不算）。告诉 AI 不要循环轮询；遇到 429 就等一会儿再试。一个办公室共用一个出口时，大家共享这个额度。

5. 检查点：AI 动手前先存一份

AI 改坏了想退回去？让它每次开工前存一个检查点：把「还没提交的改动（包括还没 git add 的新文件，.gitignore 里的除外）+ 还没推送的提交」打成一个包，用你自己的钥匙加密，存到你名下「软件包」里的 ai-checkpoints。网站上的人最多看到「这个时间存过一份、多大」，打不开内容，也看不到是哪个仓库；超过 365 天网站自动删除。什么都没改、或者和上一个检查点一样时会自动跳过；只给远程地址在 code.kernelvibe.com 的仓库存。整个过程在临时目录里做，不往你的仓库里写任何东西（小工具自己的记录都放在 ~/.config/kernelvibe）。

先准备好（只做一次）：

1. 装 age（加密用的小程序）和 Python 3.8 以上。
2. 令牌要有 package「读写」，还要能读你的仓库（第 1 步推荐的那种令牌都有了），放在环境变量 FORGEJO_ACCESS_TOKEN。
3. 在终端里下载小工具、填用户名、生成钥匙（Windows 用 Git Bash 也可以照抄）：

curl -fsSL --create-dirs -o ~/.kernelvibe/kv.py "https://code.kernelvibe.com/assets/tools/kv.py?v=20261020d"
git config --global kernelvibe.user 你的用户名
python3 ~/.kernelvibe/kv.py setup-keys

Windows 的 PowerShell 里这样写；下面所有命令在 PowerShell 里也同样把 python3 换成 python、~/.kernelvibe 换成 $HOME\.kernelvibe：

curl.exe -fsSL --create-dirs -o "$HOME\.kernelvibe\kv.py" "https://code.kernelvibe.com/assets/tools/kv.py?v=20261020d"
git config --global kernelvibe.user 你的用户名
python "$HOME\.kernelvibe\kv.py" setup-keys

在仓库目录里用。存一个检查点（说明随便写，中文也行）：

python3 ~/.kernelvibe/kv.py checkpoint --note "改登录页之前"

列出这个仓库的检查点（加 --all 列出所有仓库的）：

python3 ~/.kernelvibe/kv.py checkpoints

把某个检查点拿回来：放进新分支 kv-restore-…，不动你现在的工作（把时间换成上面列出来的名字）：

python3 ~/.kernelvibe/kv.py restore 20261020-063025

自动存的检查点、对话记录当时没传上去（比如没联网），联网后再传一次：

python3 ~/.kernelvibe/kv.py flush

• 检查点的名字是存的时间（UTC）。恢复后用 git diff HEAD kv-restore-… 看差别，满意再切过去。
• 还没 git add 的新文件：手动存时单个超过 20 MB、自动存时超过 2 MB 就不放进去，会提示是哪个。整份加密后手动最多 50 MB、自动最多 10 MB，超了就存不上并提醒你；已经跟踪的大文件照样会放进去。
• 子模块里的改动不在检查点里，会提醒你。用 Git LFS 管的大文件：改过的会把原始内容放进检查点（也受上面的大小上限限制），只是时间戳变了的不重复存。
• 检查点只存网站上还没有的部分，恢复时缺的旧提交会自动从网站拉（合并请求里的提交也会拉）。之后那些提交要是被强推、删分支清理掉了，换台电脑可能就恢复不了。
• 仓库改名或换了地址以后，用 checkpoints --all 能看到以前存的，restore 后面跟它列出的完整名字就行。

6. 对话记录：加密后存到网站

把你和 AI 的完整对话也存到网站上，以后想查「当时为什么这么改」可以翻出来。准备工作和上面的检查点一样。上传前会：

1. 打码常见的令牌、密钥、私钥、口令（尽力而为，所以还是别把密钥贴进对话）；
2. 压缩；
3. 用你自己的钥匙加密，再存到你名下「软件包」里的 ai-sessions。别人最多看到上传时间和大小，打不开，也看不到是哪个项目；
4. 超过 365 天网站自动删除（网站的加密备份里最多再留约 190 天，之后也会消失）。检查点也一样。

子代理（subagent）的完整对话会和主对话打在同一份里（Claude Code 和 Codex 都是）。同一份对话接着聊完再结束，会替换上一次传的那份，不会重复占空间；换成了另一段对话就两份都留着。检查点和对话记录都算进你的空间额度（和代码一起算），满了连 git push 都会被拒；kv 会提示你，到个人主页的「软件包」一栏（网址 /你的用户名/-/packages）删掉不要的就行。

Claude Code 自动做：写进 ~/.claude/settings.json，每次新开会话自动存检查点，每次结束自动上传这次对话：

{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup", "hooks": [ { "type": "command", "command": "python3 ~/.kernelvibe/kv.py checkpoint --hook" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "python3 ~/.kernelvibe/kv.py upload-session --claude-hook" } ] }
    ]
  }
}

• 这两个钩子只处理远程地址在 code.kernelvibe.com 的仓库，在别的目录（比如公司 GitLab 或 GitHub 上的项目）里开会话什么都不做，也不提示。
• 没联网时检查点先存在你电脑上，下次开会话会自动补传。令牌、钥匙这类设置有问题、检查点太大、上次有东西没传上去，会在 Claude Code 里提示你。
• 对话记录在后台上传，结果记在 ~/.config/kernelvibe/kv.log；没传上去的，下次你在终端里运行 kv.py 时会提醒，flush 会再传一次。
• Windows：把两处 python3 换成 python。Windows 上还没在真机上完整测过，遇到问题请告诉管理员。

Codex、Grok Build 等其他工具：做完后在仓库目录里手动上传一次。--latest 只找在这个仓库里聊的最新一次。Codex：

python3 ~/.kernelvibe/kv.py upload-session --latest codex

Claude Code 没装上面的钩子时：

python3 ~/.kernelvibe/kv.py upload-session --latest claude

其他工具，指定对话记录文件：

python3 ~/.kernelvibe/kv.py upload-session --file 对话记录文件路径

Codex 默认的沙盒不让联网：让 Codex 自己跑这些命令时，要你批准它在沙盒外运行；也可以做完后你自己在终端里跑。

列出你上传过的（这个仓库的会标出来），以及下载解密一份、显示在屏幕上：

python3 ~/.kernelvibe/kv.py sessions

python3 ~/.kernelvibe/kv.py show-session 版本号

7. 提交说明写「AI 改动档案」

在提交说明最后一段写几行「尾注」，网站会把它显示成「AI 改动档案」卡片，更改记录里也会出现「AI」标记和「为什么」：

首页：公开仓库列表加载失败时给出提示

AI-Agent: Claude Opus 5.5 (Claude Code)
AI-Intent: 用户反馈断网时首页一直显示「正在加载」
AI-Verified: 跑了全部测试；断网情况下手动试过
AI-Reviewed: 队友 alice 看过
AI-Risk: 低；有问题回退这一次提交即可
Co-Authored-By: Claude Opus 5.5 <[email protected]>

合并请求的说明里也写一份：用「压缩合并」时，各个提交里的尾注默认不会带进合并后的提交。事后想补（比如复核结论），可以在提交页的「Git 注释」里写同样格式的尾注，卡片会合并显示。

8. 安全守则

• 一个工具一个令牌，权限够用就好；不用了就到「设置 → 应用」删除，怀疑泄露立刻「重新生成」。
• 令牌只放在环境变量或密码管理器里，不写进仓库里的任何文件（代码、配置、提交说明都不行）。
• 不要让 AI 提交 .env、私钥、钱包助记词、cookie、截图里的账号信息。先把它们写进 .gitignore。
• 对 git push --force、删除分支、删除仓库这类操作，让 AI 每次都先问你。
• 私有代码只交给你信任的 AI 服务；能关的上传和遥测选项就关掉。
• 检查点和对话记录只用 kv.py 存（会先加密）；不要把对话原文、没提交的半成品直接传到软件包或推进仓库的隐藏引用——你名下的软件包登录的人都能看到，仓库里的任何引用能读这个仓库的人都能拉到。

9. 常见问题

10. AGENTS.md 模板

放在仓库根目录。Codex、Grok Build、opencode 会自动读；Claude Code 在 CLAUDE.md 里写一行 @AGENTS.md 引用它。

# 给 AI 助手的说明

- 代码托管在 https://code.kernelvibe.com ，只用 HTTPS 推拉（不支持 SSH）。
- 不要直接推送到 main：新建分支 → 提交 → 推送 → 开合并请求（用 kernelvibe MCP 或 tea pr create）。
- 没有写权限的仓库，用：git push origin HEAD:refs/for/main/<主题> -o title="…" -o description="…"
- 每个提交说明最后一段写尾注，合并请求的说明里也写一份：
  AI-Agent: <你是谁，例如 Claude Opus 5.5 (Claude Code)>
  AI-Intent: <这次为什么改>
  AI-Verified: <跑了哪些测试 / 检查>
  AI-Risk: <风险和回滚办法>
- 开始改代码前先存检查点：python3 ~/.kernelvibe/kv.py checkpoint --note "<这次要做的事>"
- 做完后上传这次对话（会先加密）：Codex 用 python3 ~/.kernelvibe/kv.py upload-session --latest codex；
  其他工具用 python3 ~/.kernelvibe/kv.py upload-session --file <这次的对话记录文件>（Claude Code 装了钩子就不用管）
- 在沙盒里不能联网、跑不了这两条命令时，告诉我，由我手动运行；看到「⚠ 上次…没做成」的提醒，原样转告我。
- 不要提交密钥、令牌、.env、私钥、助记词；不要把令牌写进仓库里的任何文件。
- 强推、删分支、删仓库之前先问我。
- 调接口不要循环轮询；遇到 HTTP 429 等 10 秒再试。