Lorenzo Feng

给 OpenCode 换个 Logo —— TUI 插件开发入门

Tue, 02 Jun 2026 00:00:00 GMT

最近给 OpenCode 换了个启动 Logo，把默认的 OpenCode 字样换成了自己的品牌名「LorenzoFeng」。整个过程踩了几个坑，记录一下完整的 TUI 插件开发流程。

为什么不能用配置文件

直觉上，换个 Logo 应该是配置项的事。OpenCode 确实有过一个 PR（#12017）试图在 opencode.jsonc 里加 "logo" 字段，但被维护者关了，理由是：

"You can customize it with tui plugins."

也就是说，OpenCode 的 TUI 定制走的是插件机制而非配置项。Logo、侧边栏、底部状态栏都通过 slot 机制暴露给插件。

TUI 插件的 Slot 机制

OpenCode 的 TUI 界面由一系列 slot（插槽） 组成，插件可以注册到其中进行替换或追加：

Slot 名称	位置	说明
`home_logo`	首页 Logo	我们要替换的目标
`home_prompt`	首页输入框	可替换为自定义输入组件
`home_bottom`	首页底部	OS / Provider 信息
`home_footer`	页脚	状态栏下方
`sidebar_title`	侧边栏标题	会话标题
`sidebar_content`	侧边栏内容	文件变更 / MCP / LSP 状态

注册方式分两种模式："replace" 替换整个 slot，不传 mode 则添加进去。

插件目录结构

关键踩坑点：TUI 插件必须有 package.json 并声明 exports["./tui"]，光放一个 .tsx 文件不生效。正确的结构：

~/.config/opencode/plugins/custom-logo/
├── package.json
└── tui.tsx

package.json 长这样：

{
  "name": "custom-logo",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    "./tui": "./tui.tsx"
  },
  "peerDependencies": {
    "@opencode-ai/plugin": "*",
    "@opentui/core": "*",
    "@opentui/solid": "*",
    "solid-js": "*"
  }
}

OpenCode 通过 exports["./tui"] 来定位 TUI 入口，没有这个声明插件就不会被加载。

插件代码

插件基于 Solid.js 和 @opentui/solid 渲染。把「Lorenzo」和「Feng」拆成两个独立数组，用 flex 布局左右排列，分别上蓝色和正文色：

/** @jsxImportSource @opentui/solid */
import type { TuiPlugin, TuiPluginModule, TuiThemeCurrent } from "@opencode-ai/plugin/tui"

const LORENZO = [
`
██╗      ██████╗ ██████╗ ███████╗███╗   ██╗███████╗ ██████╗ 
██║     ██╔═══██╗██╔══██╗██╔════╝████╗  ██║╚══███╔╝██╔═══██╗
██║     ██║   ██║██████╔╝█████╗  ██╔██╗ ██║  ███╔╝ ██║   ██║
██║     ██║   ██║██╔══██╗██╔══╝  ██║╚██╗██║ ███╔╝  ██║   ██║
███████╗╚██████╔╝██║  ██║███████╗██║ ╚████║███████╗╚██████╔╝
╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝╚══════╝ ╚═════╝ 
`
]

const FENG = [
`
███████╗███████╗███╗   ██╗ ██████╗ 
██╔════╝██╔════╝████╗  ██║██╔════╝ 
█████╗  █████╗  ██╔██╗ ██║██║  ███╗
██╔══╝  ██╔══╝  ██║╚██╗██║██║   ██║
██║     ███████╗██║ ╚████║╚██████╔╝
╚═╝     ╚══════╝╚═╝  ╚═══╝ ╚═════╝ 
`
]

const SUBTITLE = "Web Site: https://lorenzofeng.top/"

function HomeLogo(props: { theme: TuiThemeCurrent }) {
  const lorenzoColor = props.theme.info      // 蓝色
  const fengColor = props.theme.text          // 正文色
  const muted = props.theme.textMuted
  const gap = "    "

  return (
    <box flexDirection="column" alignItems="center">
      <box flexDirection="row">
        {/* LORENZO —— 蓝色 */}
        <box flexDirection="column">
          {LORENZO.map((line) => (
            <text fg={lorenzoColor}>{line}</text>
          ))}
        </box>
        {/* 间距 */}
        <box flexDirection="column">
          {LORENZO.map(() => (
            <text fg={muted}>{gap}</text>
          ))}
        </box>
        {/* FENG —— 正文色 */}
        <box flexDirection="column">
          {FENG.map((line) => (
            <text fg={fengColor}>{line}</text>
          ))}
        </box>
      </box>
      <text> </text>
      <box flexDirection="row" gap={1}>
        <text fg={muted}>━</text>
        <text fg={muted} bold>{SUBTITLE}</text>
        <text fg={muted}>━</text>
      </box>
      <text> </text>
    </box>
  )
}

const tui: TuiPlugin = async (api) => {
  api.slots.register({
    mode: "replace",
    slots: {
      home_logo(ctx) {
        return <HomeLogo theme={ctx.theme.current} />
      },
    },
  })
}

export default { id: "custom-logo", tui }

几个要点：

/** @jsxImportSource @opentui/solid */ 声明 JSX 编译目标，这句不能丢
Logo 拆成两个数组 → <box flexDirection="row"> 横向排列 → 左边的 map 遍历 LORENZO，右边的 map 遍历 FENG
slots.register() 接受 { mode, slots } 对象，"replace" 表示完全替换 OpenCode 默认 Logo
slot 渲染函数接收 ctx 上下文，通过 ctx.theme.current 拿到当前主题色

颜色配置

变量	用途
`theme.primary`	主色
`theme.accent`	强调色
`theme.info`	蓝色系
`theme.success`	绿色系
`theme.warning`	黄色系
`theme.error`	红色系

也可以用硬编码色值 fg="#ff6b6b"，但不会随主题切换。

ASCII 艺术字生成

Logo 用的字体风格是 ANSI Shadow，生成工具推荐 patorjk.com/software/taag，有上百种字体可选。推荐几个适合终端显示的：

字体	效果
`ANSI Shadow`	带阴影的块状字
`Big`	简洁大方
`Block`	实心方块
`Doom`	游戏风格
`Graffiti`	涂鸦风

注册插件

插件写好后需要注册。有两种方式：

方式一——自动发现：把插件放在 ~/.config/opencode/plugins/ 目录下，OpenCode 启动时自动扫描加载。

方式二——显式声明：在 opencode.jsonc 或 tui.json 的 plugin 数组中加绝对路径：

{
  "plugin": [
    "~/.config/opencode/plugins/custom-logo"
  ]
}

两种方式我都用了，确保万无一失。插件支持热更新，改 tui.tsx 后重进 TUI 即可生效，不需要重启 OpenCode。

总结

OpenCode 的 TUI 插件系统比预期灵活很多——slot 机制让几乎所有界面元素都可替换。虽然 Logo 不能通过配置文件直接改，但写一个十几行的插件就能搞定，而且能做的事情远不止换 Logo：侧边栏、输入框、状态栏都能深度定制。

AgentEnv 路线图——从包管理器到完整环境管理，寻找合作者

Tue, 26 May 2026 00:00:00 GMT

::github{repo="7emotions/agentenv"}

AgentEnv 是什么

AgentEnv 是一个 AI Agent 的环境管理器——把它想象成 conda，但管理的是 skills、MCP 服务器、agent 定义、tools、hooks 和 prompts。六种包类型、四种框架适配器（Claude Code、OpenCode、Cursor、Codex）、六种源协议——声明式 agent.yaml + PubGrub 依赖解析 + 锁文件。

目前它能做什么：

agentenv create my-project --agent opencode
agentenv add skill code-reviewer --source github:myorg/code-reviewer
agentenv lock && agentenv install && agentenv activate my-project

但它缺了最关键的一步——框架版本管理。

缺失的拼图

假设你的团队用 OpenCode 开发 Agent。你在 agent.yaml 里声明了 skills 和 MCPs，agentenv lock 锁定了所有依赖的版本。你的同事 clone 了项目，agentenv activate 激活了环境。

但你们的 OpenCode 版本可能不一样。 你的 agent.yaml 不定义框架版本——框架版本是隐式的，取决于每个人本地装了什么。如果 OpenCode 0.8 的某个 MCP 行为变了，你的环境在同事的机器上可能表现不一致。

类比 conda：conda 不只管 numpy 的版本，也管 Python 本身的版本。environment.yml 里的 python=3.10 是环境定义的核心部分。AgentEnv 也应该管框架版本。

解决方案——框架版本管理

核心思路非常简单：在 agent.yaml 中声明框架及其版本约束。

name: my-project
framework:
  type: opencode
  version: ">=0.7.0"

skills:
  code-reviewer:
    source: github:myorg/code-reviewer
    version: "^1.0"

agentenv activate 时检查本地安装的 OpenCode 版本是否满足约束。如果不满足，直接报错告诉你需要哪个版本。

这和 conda 的 python=3.10 一模一样——AgentEnv 管框架版本，OpenCode/Cursor/Claude Code 仍然是激活目标，开发者仍然用自己熟悉的工具。

实现计划

完整的实现计划在 docs/superpowers/plans/2026-05-26-runtime-management.md。核心是 8 个任务，约 300 行新增代码：

任务	变更	说明
Types	+15 行	`FrameworkSpec` 类型 + `Environment.Framework` 字段
Envfile	+60 行	reader/writer/validator 支持 `framework` 字段
Create	+10 行	`--agent opencode` 写入 `agent.yaml`（不只是 `state.json`）
Adapter	+30 行	新增 `GetInstalledVersion()` 方法，检查本地框架版本
Activate	+30 行	激活时校验框架版本是否满足约束
Info	+15 行	`agentenv info` 显示框架声明
Tests	+80 行	framework 字段 round-trip + create 集成测试
Docs	+30 行	README + agent-yaml.md 更新

不做的事情：

不造 AgentMini 或内置任何运行时。激活目标仍然是 OpenCode/Cursor/Claude Code/Codex。
不加 deploy 命令。环境管理不变成部署工具。
不把 gocode 特殊对待。如果将来有人想用 gocode——写一个适配器就行，和 OpenCode 完全对等。

为什么这个方向是正确的

经过几轮架构讨论，我意识到之前"部署给甲方"的思路把 AgentEnv 带偏了。AgentEnv 的价值不是让非开发者跑 Agent——而是让开发者之间的环境可复现。

conda → 管 Python 版本 + numpy 版本
AgentEnv → 管 OpenCode 版本 + skill/MCP 版本

同一个类比，同一个抽象层。框架版本管理是这个类比的最后一环——补上它，AgentEnv 的环境模型就完整了。

寻找合作者

这个项目目前是我一个人在维护。路线图上的事情比我一个人能干的多。我在找对这些方向感兴趣的人：

核心需求（Go 后端）：

适配器扩展（实现各框架的 GetInstalledVersion）
agentenv activate 的版本校验逻辑完善
agentenv lock 对框架版本的支持（将 framework 纳入锁文件）
新增 Aider、Gemini CLI 等框架适配器

锦上添花（全栈）：

agentenv doctor 健康检查命令（并行检查 runtime + adapters + store）
无参运行时的信息面板（TTY 检测 + 环境状态概览）
Golden 测试基础设施
下一步提示（create 后提示 add，lock 后提示 install）

如果你对以上任何方向感兴趣，欢迎：

在 GitHub Issues 里开 discussion
直接提 PR——路线图上的每一项都有详细的实现计划
发邮件给我：lorenzo@lorenzofeng.top

Agent 开发正在从"每个人在自己机器上调配置"的阶段走向工程化。AgentEnv 想成为 conda 对 Python 生态做的事——让 Agent 开发环境可以被声明、版本化、复现。如果你认同这个方向，一起来做。

AgentEnv —— 当 AI 智能体也需要「conda 环境」

Sun, 24 May 2026 00:00:00 GMT

这几个月我在不同项目间频繁切换时发现一个尴尬的问题：每个项目需要的 skill、MCP 服务器、agent 配置都不一样。给项目 A 装了某个 skill，项目 B 不兼容；在 Claude Code 里配好的 MCP 服务器，切到 OpenCode 又要重新来一遍。我管这个叫「AI 智能体的依赖地狱」。

AgentEnv 就是为了解决这个问题而生的。

问题的本质

::github{repo="7emotions/agentenv"}

AI 编码工具的生态正在爆炸式增长。Claude Code、OpenCode、Cursor、Codex 各有各的配置格式和路径。skill、MCP 服务器、agent 定义、hook、prompt 模板——这些「智能体依赖」混在一起，没有隔离、没有版本管理、没有可重现性。

Python 社区有 conda 和 virtualenv 来解决环境隔离；Node.js 有 npm workspace；Go 有 go modules。但 AI 智能体的环境管理，一直是一个手工拷贝配置文件的原始状态。

AgentEnv 要做的就是这件事：像 conda 管理 Python 环境一样，管理 AI 智能体的依赖环境。

设计哲学

声明式，不拼凑

AgentEnv 的核心是 agent.yaml —— 一个声明式的环境定义文件：

name: my-ai-env
description: "我的 AI 开发环境"

skills:
  code-reviewer:
    source: github:myorg/code-review-skill
    version: ">=0.5"

mcps:
  filesystem:
    source: npm:@modelcontextprotocol/server-filesystem
    version: "0.6.0"
    config:
      root: /home/user/projects

你只需要声明想要什么，AgentEnv 负责找到、下载、安装、激活。这跟 package.json + npm install 的思路一脉相承，但适配的是 AI 编码工具的生态。

可重现，版本锁定

声明之后执行 agentenv lock，它会跑一个 PubGrub CDCL 解析器——就是 Dart/Flutter 用那个算法——来求解依赖图：

自动发现传递依赖（skill A 依赖 skill B，B 又依赖 C）
处理语义化版本约束（^1.0、>=2.0、~3.5.1）
检测冲突并给出精确的冲突报告

error: conflict detected
  code-reviewer@>=1.0 requires lint-helper@^2.0
  my-other-skill@>=0.5 requires lint-helper@^1.0
  lint-helper@^2.0 and lint-helper@^1.0 are incompatible

解析完成后生成 agent.lock，包含每个包的 SHA-256 校验、解析版本、来源——这是你在另一台机器上得到完全相同环境的保证。

六种源，不分来源

AgentEnv 支持 6 种包来源协议：

协议	示例
`github:`	`github:myorg/code-review-skill`
`npm:`	`npm:@modelcontextprotocol/server-filesystem`
`local:`	`local:./vendor/my-tool`
`git:`	`git:https://github.com/org/repo.git`
`file:`	`file:/home/user/packages/skill.tar.gz`
`url:`	`url:https://example.com/pkg.tar.gz`

也就是说，你可以把一个 GitHub 上的 skill、一个 npm 上的 MCP 服务器、一个本地开发中的 hook 脚本，扔进同一个环境管理。这对「正在开发 skill 同时又在用别人的 MCP」这种常见场景极其友好。

六种包，各司其职

AgentEnv 中，「包」（package）是一个抽象概念，覆盖了 AI 智能体生态中所有需要版本管理和环境隔离的东西。目前支持六种包类型：

类型	含义	典型场景
`skill`	可安装的技能	代码审查 skill、文档生成 skill、Git 操作 skill
`mcp`	MCP 服务器配置	文件系统访问、浏览器自动化、数据库查询
`agent`	智能体定义	自定义 agent 的行为描述和系统提示词
`tool`	工具包	代码格式化工具、lint 工具配置
`hook`	生命周期钩子	激活前校验脚本、停用后清理脚本
`prompt`	提示词模板	代码审查提示词、提交信息生成模板

每种包在 agent.yaml 中的声明格式完全一致，只需要三个字段：

# 必填：source —— 从哪里获取这个包
source: github:owner/repo

# 可选：version —— 语义化版本约束（默认 *，即任意版本）
version: ">=0.5"

# 可选：config —— 包专属的配置项，由包的消费者自行解读
config:
  root: /home/user/projects

一个包含所有六种类型的完整 agent.yaml 长这样：

name: my-ai-env
description: "我的全栈 AI 开发环境"

# 技能（skill）：可复用的智能体能力模块
skills:
  code-reviewer:
    source: github:myorg/code-review-skill
    version: ">=0.5"

# MCP 服务器：连接外部工具的桥梁
mcps:
  filesystem:
    source: npm:@modelcontextprotocol/server-filesystem
    version: "0.6.0"
    config:
      root: /home/user/projects

# 智能体（agent）：自定义 agent 的完整规格
agents:
  senior-dev:
    source: github:myorg/agents
    version: "~1.2"

# 工具（tool）：辅助工具和配置
tools:
  formatter:
    source: url:https://example.com/tools/formatter.tar.gz

# 钩子（hook）：生命周期事件触发脚本
hooks:
  pre-activate:
    source: file:/home/user/hooks/check-env.sh
  post-deactivate:
    source: local:./hooks/cleanup.sh

# 提示词（prompt）：可复用的提示词模板
prompts:
  code-review:
    source: git:https://github.com/myorg/prompts.git
    version: ">=2.0"

同一个环境可以混用任意类型的包，不限制种类和数量。同一个类型下包名必须唯一，但不同类型之间可以重名（比如可以同时有一个叫 code-reviewer 的 skill 和一个叫 code-reviewer 的 prompt）。

这种设计的妙处在于——不论是 GitHub 上的开源 skill、npm 上的 MCP 包、还是本地开发中的 hook 脚本，对 AgentEnv 来说都是「包」，都走同一套解析、下载、安装、激活的流水线。 你不用为不同种类的东西学不同的命令，也不用操心它们的存储路径和配置格式。

四个框架，一套流程

不管你用的是 Claude Code、OpenCode、Cursor 还是 Codex，AgentEnv 的命令都一样：

agentenv create --agent opencode my-env
agentenv add skill code-reviewer --source github:myorg/reviewer
agentenv lock
agentenv install
agentenv activate my-env

框架切换只是一个 --agent 参数的区别。每个框架适配器知道自己的配置路径、格式（JSON、JSONC、TOML）、以及如何正确地读写而不破坏已有配置。

特别值得一提的是 OpenCode 适配器的 JSONC 支持：OpenCode 的配置文件是带注释的 JSON（JSONC），AgentEnv 用了 tailscale/hujson 来做注释保留的读写，不会像 encoding/json 那样把注释全部吃光。

事务性激活，不留下残局

激活环境时，AgentEnv 做的不是简单「往配置文件里塞几行」：

备份（backup）→ 校验（validate）→ 应用（apply）→ 失败回滚（rollback）

如果校验失败或者任何步骤出错，它会自动恢复到变更前的状态。不会出现「配置改了一半 agent 跑不起来了」的情况。

内容寻址存储

所有下载的包存在一个内容寻址的本地仓库里。两个环境都用到 lint-helper@1.2.0？只存一份。某个包不再被任何环境引用？垃圾回收可以清理。跨文件系统的话，symlink 降级为文件复制。

快速上手

# 一行安装
curl -fsSL https://raw.githubusercontent.com/7emotions/agentenv/main/install.sh | sh

# 创建一个环境
agentenv create --agent opencode my-ai-setup

# 加几个包
agentenv add skill code-reviewer --source github:myorg/code-review-skill
agentenv add mcp filesystem \
  --source npm:@modelcontextprotocol/server-filesystem \
  --command npx --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg /tmp

# 解析依赖
agentenv lock

# 下载并激活
agentenv install
agentenv activate my-ai-setup

# 搞定——你的 agent 现在有完整的运行环境了

所有命令都支持 --json 输出，方便脚本化集成。

技术栈

AgentEnv 本身是一个 Go 项目（Go 1.26），单二进制发布，支持 macOS / Linux（amd64 / arm64）。核心依赖：

CLI 框架：cobra（14 条命令）
依赖解析：contriboss/pubgrub-go（CDCL 算法）
Git 操作：go-git
版本约束：Masterminds/semver
配置格式：YAML（gopkg.in/yaml.v3）、TOML（BurntSushi/toml）、JSONC（tailscale/hujson）

28 个测试文件覆盖所有包，CI 跑 go test -race 在 ubuntu 和 macOS 上。

几条设计红线

做这个项目时我给自己画了几条硬线：

零遥测——不上报、不追踪、不联网发 ping。环境管理器碰触的是最敏感的本地配置文件，信任是第一位的。
无插件系统——所有适配器在编译时注册（init()），不搞运行时动态加载。
无 Windows 支持——AI 编码工具的生态集中在 macOS 和 Linux，Windows 不在范围内。
不破坏 JSONC——这点值得再强调一遍：OpenCode 用户的配置文件里的注释一个字都不会丢。

在生态中的位置

AI agent 环境管理 / 配置管理这个方向，已经有不少开发者在探索。这里介绍几个我关注的代表性项目——它们和 AgentEnv 解决的问题各有侧重，不存在谁更「好」，更像是在同一个大方向上填补不同的空白。

agenv（combinatrix-ai） 定位为「nvm for AI agents」——管理的是 agent 二进制本身的版本和 profile 隔离。你可以用 agenv install claude 安装 Claude Code，再用 agenv run 启动，不同 profile 之间二进制、配置、权限完全隔离。这是一个非常实用的运行时版本管理工具，和 AgentEnv 的「包依赖管理」是问题的上下游——可以先用 agenv 管理 agent 本身的版本，再用 AgentEnv 管理 agent 内部的环境依赖。

agenv-cli（npm） 走的是配置生成路线：从一个 ai-workspace.json manifest 出发，自动检测项目类型、框架、已有配置，然后生成 Claude Code、Copilot、Codex、Cursor、Windsurf 等多个工具的配置文件。交互式的 agenv init 和自动化的 agenv generate，对于「想让多个工具共享一套配置规则」的场景是一个简洁高效的选择。

agentctl（OrgLoop） 是 agent session 监控面板，提供启动、监控、恢复、终止、对比 agent 会话的完整运维能力。它带有守护进程、目录锁、webhook 和 Prometheus 指标，做得非常专业——关注的是「同时跑多个 agent 会话怎么可靠管理」这一运维层面的问题。

agentctl（iheanyi） 的定位和 AgentEnv 最接近——跨框架配置管理，覆盖了 Claude Code、Codex、OpenCode、Cursor、Cline、Windsurf、Zed、Continue、Gemini 等 10 个框架。它可以从各框架的原生配置目录中发现已有资源（MCP 服务器、rules、commands、skills），再同步到其他框架，还提供一个交互式 TUI，使用体验很流畅。

这些项目从不同角度推动着同一件事：让 AI 智能体的配置管理从「手工拷贝文件」走向「工具化、自动化」。AgentEnv 选择的角度是声明式包管理与依赖解析——把 PubGrub 求解器、确定性锁文件、内容寻址存储这套成熟的包管理范式，带到 AI 智能体的世界。没有哪个项目是「唯一正确答案」，每个都解决了一类真实的痛点，也在互相启发。

下一步

AgentEnv 还远没有完成。接下来计划：

依赖图可视化：agentenv graph 画依赖关系
环境对比：agentenv diff env-a env-b
远程锁文件共享：团队里一份 agent.lock 就能复现全队环境
更多的适配器：Windsurf、Aider、Continue

如果你每天在多个 AI 编码工具之间切换，或者在维护多个项目的不同配置，欢迎试试 AgentEnv。

git clone https://github.com/7emotions/agentenv.git
cd agentenv
make build && ./dist/agentenv --help

Star、Issue、PR 都欢迎。让 AI 智能体的环境管理，走上正轨。

为什么 AI Agent 总说「用 CloakBrowser」却偷偷调了 Playwright？—— 一次跨层排障与开源贡献

Sun, 24 May 2026 00:00:00 GMT

事情开始于一个简单的测试：「测试一下 cloakbrowser 能不能用。」

一个诡异的退化

::github{repo="CloakHQ/cloakbrowser"}

CloakBrowser 是一个防检测浏览器——它在 Chromium 源码层面打了 48 个 C++ 补丁，能通过 reCAPTCHA v3、Cloudflare Turnstile、FingerprintJS 等几乎所有 bot 检测。npm 安装后，API 长这样：

import { launch } from 'cloakbrowser';
const browser = await launch();

这是它 README 的第一行代码。

但 OpenCode 里的 agent 写了这个：

import { chromium } from 'playwright';
const browser = await chromium.launch({
  executablePath: '~/.cloakbrowser/chromium-.../chrome'
});

它把 cloakbrowser 当成了 Playwright 的 drop-in 二进制，而不是一个有自己 API 的包。 完全跳过了 cloakbrowser 自己的 launch() 函数，直接把它当原始 Chromium 喂给 Playwright。

第一步：我以为问题在 agent 身上

我的第一反应很自然：「agent 没读文档。」

cloakbrowser 有 package.json，有 README，有 exports 字段。只要读了其中任何一个，都不会犯这个错。问题是 agent 没读——它看到 cloakbrowser info 输出一个二进制路径，就直接模式匹配到了 chromium.launch({executablePath})。

这看起来是一个可以通过规则约束解决的问题。我花了相当的时间做了一个 docs-before-code skill，按照完整的 RED-GREEN-REFACTOR 方法论：

阶段	测试	结果
RED 基线	agent 用 listr2 写代码（不读文档）	暴露了「我知道这个库」的合理化
GREEN 验证	agent 用 vitest 程序化 API（按 skill 规则）	先查 `vitest/node` 子路径，再写代码 ✅
REFACTOR 压力	agent 用 execa v9（2 分钟限制 + 旧记忆）	发现 tagged template 新语法，避免写旧 API ✅

这个 skill 本身是有效的。它的 Gate Function（五个步骤：IDENTIFY → LOCATE → VERIFY → CONFIRM → 写代码）能在 agent 写 import 语句之前拦下它，强制它先去读 package.json 的 exports 字段和 README 的第一段代码。execa v9 的压力测试证明了这一点——即使 agent 的记忆里是 execa('cmd', [args]) 的旧 API，skill 也强迫它先查了文档，发现了 v9 的 tagged template 新语法。

但我很快就发现，cloakbrowser 的问题完全没有被解决。

第二步：发现 skill 完全没用

我回去翻其他会话记录。三个不同的 session 里，用户明确说了「用 cloakbrowser」，agent 全都退化到了 Playwright MCP 工具。

其中一个 session 的转写特别刺眼：

User:  "设置界面和你说的不一样，你用 cloakbrowser 配置"
Agent: → 加载 dev-browser skill
Agent: → 加载 playwright skill
Agent: → 调用 playwright MCP 的 browser_navigate
Agent: → 完全没用 cloakbrowser

agent 根本没走到写 import 那一步。 它没有写 Node.js 脚本、没有 npm install、没有 import 语句。它直接调了 Playwright MCP 的 browser_navigate、browser_click 这些现成的工具。

我花了两天写的 docs-before-code skill，在真实场景里一次都没触发过。不是它写错了，是它的触发条件（写 import 语句）和故障场景（MCP 工具选择）根本不在同一层。

这就好比你给司机装了一个「开车前检查后视镜」的提醒，但他连车都没上——他在车库门口就被导航系统指引到另一辆车上了。

第三步：追到 OMO 源码

如果 agent 是在「工具选择」阶段被拐走的，那一定有什么东西在系统 prompt 里告诉它「浏览器任务必须用 Playwright」。

我开始翻系统配置。OpenCode 的 opencode.jsonc 里没有 Playwright MCP 配置。AGENTS.md 里也没有写死 Playwright。那这个偏好是哪里来的？

答案在 OMO（Oh-My-OpenCode）插件里。在其缓存安装目录 oh-my-openagent/dist/ 的源码中，我找到了这段：

var playwrightSkill = {
  name: "playwright",
  description: "MUST USE for any browser-related tasks. Browser automation via Playwright MCP ...",
};

"MUST USE for any browser-related tasks" —— 这是一条注入到 agent 系统 prompt 里的死命令。当用户说「用 cloakbrowser」时，agent 的语义解析是这样的：

"cloakbrowser" → 包含 "browser" → 这是 browser-related task → "MUST USE playwright"

系统级指令（skill description）的优先级比用户消息更高。用户的 cloakbrowser 被语义压缩成了 browser，然后被 MUST USE 抢占了。

进一步分析确认了 OMO 有一个 browser_automation_engine 配置项：

export const BrowserAutomationProviderSchema = z.enum([
  "playwright",
  "agent-browser",
  "dev-browser",
  "playwright-cli",
  // 没有 "cloakbrowser"
])

provider: BrowserAutomationProviderSchema.default("playwright")

可选值只有四个，默认是 playwright。cloakbrowser 不在选项里。

这意味着：即使用户完全不配置任何东西，agent 看到的系统 prompt 里也会有一行 playwright: MUST USE for any browser-related tasks。这不是 OMO 故意排斥 cloakbrowser——它只是还没被适配进去。

但这件事揭示了一个更深的问题：当框架有一个「强制指定工具」的机制时，不在名单里的工具根本就没有被正确使用的可能性。 无论你写多少 skill、优化多少 prompt，agent 都会被上游的「MUST USE」指令拖走。

修框架本身

理解了根因之后，修复就很清晰了：把 cloakbrowser 加进 browser_automation_engine 的 provider 选项。

我 fork 了 OMO 仓库，在 feat/cloakbrowser-provider 分支上改了 4 个文件，总共 +126 行：

文件	改动
`src/config/schema/browser-automation.ts`	添加 `"cloakbrowser"` 到 provider enum
`src/features/builtin-skills/skills/cloakbrowser.ts`	新建，119 行的 skill 模板，覆盖完整 API
`src/features/builtin-skills/skills/index.ts`	导出 `cloakbrowserSkill`
`src/features/builtin-skills/skills.ts`	在 `createBuiltinSkills` 里添加 cloakbrowser 分支

新增的 cloakbrowser skill 包含了完整的 API 参考：三种启动方式（launch、launchContext、launchPersistentContext）、配置选项（headless、proxy、timezone、geoip、humanize）、CLI 工具、reCAPTCHA 优化技巧、与原生 Playwright 的关键差异。

合并后，用户只需在 oh-my-openagent.json 里加一行：

{ "browser_automation_engine": { "provider": "cloakbrowser" } }

agent 就不会再看到 playwright: MUST USE for any browser-related tasks，而是看到 cloakbrowser 的 skill，知道什么时候用它、怎么用它。

PR 已提交

::github{repo="code-yeongyu/oh-my-openagent"}

PR #4337：feat: add cloakbrowser as browser automation engine provider

TypeScript 类型检查：✅ 零错误
browser_automation_engine schema 测试：✅ 3/3 通过
构建：✅ 成功

反思

这件事最反直觉的地方在于：你以为是 agent 没读文档，最后发现是文档根本不在 agent 的视野里。

我花了两天写了一个精心测试过的 skill，它确实能解决它设计要解决的问题（agent 写 import 之前先查 API），但它对 cloakbrowser 的退化问题毫无作用——因为那个问题根本不在代码编写层。

docs-before-code 在工厂流水线的「组装」环节装了一个质检站，但我真正需要修的是「零件进料口」——工具选择那一层。错误不在 agent 怎么写代码，而在 agent 一开始就被给了错误的工具。

这也是一条给 AI agent 框架开发者的原则：如果你的框架有一个「强制指定工具」的机制，确保新工具能平等地接入它。 否则，你的框架就不是助推器，而是壁垒。

为 CodeGraph 修复 inotify 耗尽问题：从 fs.watch 到 chokidar

Sat, 23 May 2026 00:00:00 GMT

前几天我在使用 CodeGraph 时发现了一个问题：改完代码后 watcher 不总是能自动更新索引。深入排查后发现这与一个已知的 Linux inotify 内核限制有关，于是动手修了并提交了 PR。

::github{repo="colbymchenry/codegraph"}

背景：CodeGraph 是什么

CodeGraph 是一个用 tree-sitter 解析代码、构建语义知识图谱的工具，18 天冲到 17k Star。它为 Claude Code、Cursor、Codex CLI、OpenCode 等 AI Agent 提供毫秒级的代码符号搜索——谁调用了这个函数、这个变量定义在哪、改了这个类会影响什么——都是预建的索引直接返回。

Agent 用 CodeGraph 能 减少 50% 以上的 token 消耗和 80% 以上的工具调用。它自带文件监听器，代码改了就自动增量同步索引。

问题：改代码后索引不自动刷新

在用 OpenCode 对话时，我发现了一个现象：Agent 改了代码，然后用 CodeGraph 去查新写的函数，查不到。只有手动跑 codegraph sync 后才能搜到。

我开始以为是 watcher 压根没有自动同步功能，但翻源码后发现，watcher 是有的——src/sync/watcher.ts 里用 fs.watch(root, {recursive: true}) 监听文件变更，检测到 .ts / .py 等源文件改动后就触发增量 sync。

那为什么我的项目里不生效？

根因：inotify 被 node_modules 吃光了

翻 GitHub Issues，找到了 #276：

fs.watch(root, {recursive: true}) 在 Linux 上为每个目录注册一个 inotify watch —— 包括 node_modules/、.git/、.next/、dist/ 等目录。过滤逻辑写在回调里，此时 watch 早已注册完成。

Linux 内核默认允许一个用户最多持有 65536 个 inotify watch。而 node_modules/ 下面动辄几千个小包目录，每个包里又有自己的 node_modules/——一个中等规模的 monorepo 很容易就跑出几万甚至十几万个目录。

CodeGraph 的递归 watcher 会为每个目录注册 watch，哪怕回调里会把这些目录的事件扔掉。结果是：

单个 codegraph serve --mcp 实例占掉大半的 inotify 预算
同一仓库开两个 agent 会话 → 直接触顶
其他工具报错：ENOSPC: System limit for number of file watchers reached
更糟的是，PR #286 发现 agent 会话结束时子进程可能变成孤儿继续跑，积压的僵尸进程带着全部 watch 赖着不走

根本原因是 "先注册，再过滤"。正确的做法应该是 "先过滤，再注册"。

方案：用 chokidar 替代 fs.watch

Issue 里提出了两个修复方向：

遍历树，手动过滤目录，对通过过滤的目录注册非递归 fs.watch —— 等于自己写一个 mini chokidar
直接用 chokidar，它的 ignored 回调在注册 watch 之前过滤

我选了方案 2。chokidar 是一个周下载 4000 万+ 的纯 JS 库，早把目录遍历、过滤、watch 管理、跨平台兼容这些 edge case 踩平了。而且它是纯 JavaScript，零 native 编译——不破坏 CodeGraph "self-contained，零编译" 的卖点。

核心改动不到 100 行：

// 之前：先注册所有 watch，回调里再过滤（太晚）
this.watcher = fs.watch(this.projectRoot, { recursive: true }, (_eventType, filename) => {
    if (!isSourceFile(filename)) return;  // 过滤在注册之后
});

// 之后：用 chokidar 的 ignored 回调，先过滤再注册
this.watcher = chokidar.watch(this.projectRoot, {
    ignored: (testPath) => {
        // .gitignore 规则 + .codegraph/ + .git/
        // 返回 true 的路径不会被注册 inotify watch
    },
});

this.watcher.on('all', (_event, filePath) => {
    if (!isSourceFile(filePath)) return; // 防御性过滤仍然保留
    // ... 触发 debounced sync
});

过滤逻辑：从项目根目录向上遍历，加载所有 .gitignore 文件（跟 git 的行为一致），用已有的 ignore npm 包做匹配，同时硬编码排除 .codegraph/ 和 .git/。

改动量：

文件	改动
`package.json`	加 `chokidar` 依赖（v4，CommonJS 兼容）
`src/sync/watcher.ts`	+90 行：`.gitignore` 加载 + `ignored` 回调 + 事件处理重构

对现有功能无影响：WSL2 /mnt/* 自动禁用、CODEGRAPH_NO_WATCH 环境变量、git hook 替代方案全部保持不变。

测试

单元测试

vitest __tests__/watcher.test.ts      → 9/9 ✅
vitest __tests__/watch-policy.test.ts → 8/8 ✅
tsc --noEmit                          → clean ✅

所有 watcher 单元测试原封不动通过——chokidar 的事件模型与 fs.watch 兼容，debounce 逻辑、过滤逻辑、lifecycle 全部保持一致。sync 测试因测试环境缺少 node:sqlite 而失败（已有问题）。

inotify watch 实测

策略

不能靠目录遍历估算——事后对比发现，fs.watch({recursive: true}) 注册的 watch 数远超肉眼可见的目录数（博客项目目录树 ~9,000 个，实测 watch 数 ~48,000，偏差 5 倍）。必须从内核的真实数据源读取。

测试方法：在同一进程内先后跑旧方案和新方案，各自从 /proc/self/fdinfo/ 读取内核分配的 inotify watch 计数：

1. fs.watch(root, {recursive: true})
2. 等待 3 秒 → 内核完成所有目录的 inotify 注册
3. 遍历 /proc/self/fd/* → 找到类型为 anon_inode:inotify 的 fd
4. 读对应 /proc/self/fdinfo/{fd} → 统计 inotify wd: 行数
5. → OLD 值

6. 关闭旧 watcher
7. 加载 .gitignore 规则链
8. chokidar.watch(root, { ignored: gitignoreFilter })
9. 等待 'ready' 事件 → 确保 watch 全部注册完毕
10. 再次读 /proc/self/fdinfo/*
11. → NEW 值

为什么不用 lsof、pgrep、spawn 子进程？

方法	问题
`lsof -p PID`	不显示单个 inotify 实例内的 watch 条目数
spawn 子进程 + 父进程读 `/proc/{child}`	stdout 管道捕获不可靠，子进程可能先于测量退出
目录遍历计数	严重低估——`fs.watch` 的内核行为比"每个目录一个 watch"复杂得多

结果

中等项目（博客，pnpm + Astro + Tailwind，~9,000 个目录）：

	修复前	修复后
inotify watch 数	48,368	175
节省	—	48,193（99.6%）

小型项目（codegraph 仓库本身，~250 个目录）：

	修复前	修复后
inotify watch 数	2,045	209
节省	—	1,836（90%）

测试环境内核限额：65,536。旧方案下，博客项目一个 agent 会话就吃掉限额的 74%——开两个会话直接触顶。issue #276 reporter 的 monorepo（~20 万文件）实测每实例 ~44 万个 watch，单项就把预算撑爆 6 次以上。

局限性

只测了两次，没算方差。 单次运行。如果 fs.watch 的异步注册在 3 秒内没走完，OLD 值可能偏低。
只有两个项目，规模跨度有限。 最大的也就 ~9,000 个目录、48k watch，远未达到 issue #276 reporter 的 44 万级别。更大规模项目上 OLD/NEW 的绝对差距会更大，但比例不一定线性。
每个项目只跑了一轮对比。 没有测多次取均值排除抖动。
没测并发。 单实例测试，没有验证两个 watcher 同时运行时是否有额外的资源竞争（虽然理论上不会，但没有实测）。
没测 macOS / Windows。 只测了 Linux。chokidar 在其他平台上使用 FSEvents / ReadDirectoryChangesW，行为可能不同——但对于这个 PR 来说，这两个平台不是问题域。
修复效果完全依赖 .gitignore 质量。 如果项目没写 node_modules/ 到 .gitignore，修复后 watch 数几乎不变。这不是 bug，但需要明确。

对维护者的建议

如果上游合并这个 PR，建议在 release notes 或 README 中补充一句提醒：

On Linux, the file watcher now respects .gitignore to avoid consuming inotify watches on excluded directories (e.g. node_modules/, dist/, .git/). Make sure your .gitignore covers these directories, or explicitly add CODEGRAPH_NO_WATCH=1 if the watcher still causes issues on very large repos.

同时，如果合并后有人报告 watch 数依然很高，第一反应应该是检查他们的 .gitignore 是否包含了 node_modules/、dist/、build/、.next/ 等常见构建输出目录。

提 PR

改动确认无误后，fork 了上游仓库，推送分支，提交了 PR：

::github{repo="colbymchenry/codegraph"}

PR #346 已链接到 issue #276，合并后自动关闭。CodeGraph 仓库目前有 60+ 个 open PR，维护者应该比较忙，等待 review 中。

从发现到修复的全过程：用户报 issue → 看代码怀疑 watcher 不工作 → 查 issues 发现是 inotify 预算问题 → 评估修复方案 → 选 chokidar → 改代码 → 跑测试 → 提 PR。整个过程下来，对 Linux inotify 机制、chokidar 的工作原理、以及 CodeGraph 的 watcher 架构有了更深的理解。

开源就是这样——你用一个工具，发现它的 bug，然后顺手把它修了。17k Star 的项目也不例外。

自建邮件服务器：Stalwart + 阿里云绕过 25 端口限制

Fri, 22 May 2026 00:00:00 GMT

我把自己搭建邮件服务器的过程整理成了一个 GitHub 仓库，包含完整的 Docker Compose 配置、Caddy 反向代理、部署前检查脚本和部署后验证脚本。本文是对整个方案的说明。

背景

在云服务器上自建邮件服务，最大的障碍不是安装配置，而是出站 25 端口被封锁。阿里云、腾讯云等国内厂商默认封锁 SMTP 出站端口，意味着服务器可以接收邮件，但无法直接投递到外部邮箱。

解决方案：通过阿里云邮件推送（DirectMail） 作为 SMTP 中继 — 邮件先提交到阿里云的 465 端口，再由阿里云代为投递到目标服务器。这也是生产环境的标准做法。

::github{repo="7emotions/email-server"}

为什么选 Stalwart？

市面上常见的自建邮局方案有 Mailu、Mailcow、iRedMail 等，它们功能完善但组件繁多（动辄 8-10 个容器），对 2GB 以下内存的服务器不友好。

Stalwart Mail Server 是一个用 Rust 从头编写的现代化邮件服务器，单个容器同时提供 SMTP、IMAP、JMAP 和 Web 管理面板，内存占用约 300MB。对比 Mailu 需要 9 个容器（Redis、Postfix、Dovecot、ClamAV、Rspamd 等），这在资源有限的 VPS 上是巨大的优势。

方案	容器数	内存占用	管理面板	JMAP
Mailu	9	~1.5 GB	✅	❌
Mailcow	~15	~4 GB	✅	❌
Stalwart	1	~300 MB	✅	✅

项目结构

仓库包含以下内容：

email-server/
├── compose.yaml           # Stalwart Docker Compose 配置
├── caddy/
│   └── Caddyfile.mail     # Caddy 反向代理配置
├── scripts/
│   ├── preflight.sh       # 部署前 8 项环境检查
│   └── verify.sh          # 部署后 14 项验证
└── README.md              # 完整部署指南

compose.yaml — 极简配置

核心的 compose.yaml 仅 31 行，一个 service、两个 volume、几行日志配置，干净利落。

# Stalwart Email Server — Docker Compose
# Domain: <YOUR_DOMAIN> | Image: ghcr.io/stalwartlabs/stalwart:v0.16
#
# Ports:
#   Mail: 25 (SMTP), 465 (SMTPS), 587 (Submission), 993 (IMAPS), 143 (IMAP)
#   Admin: 127.0.0.1:8080 (internal, behind Caddy reverse proxy)

services:
  stalwart:
    image: ghcr.io/stalwartlabs/stalwart:v0.16
    container_name: stalwart
    restart: unless-stopped
    ports:
      - "25:25"
      - "465:465"
      - "587:587"
      - "143:143"
      - "993:993"
      - "127.0.0.1:8080:8080"
    volumes:
      - stalwart-data:/opt/stalwart
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - TZ=Asia/Shanghai

volumes:
  stalwart-data:

部署只需要三条命令：

docker volume create email-server_stalwart-data
docker compose up -d
# 浏览器打开 http://<服务器IP>:8080/admin 完成初始配置

preflight.sh — 部署前环境检查

在 docker compose up -d 之前运行，自动检测 8 项环境前提：

Docker daemon 是否运行
Docker Compose 是否安装
端口 25/465/587/993/8080 是否被占用
iptables DOCKER 链是否正常
内存 ≥ 1 GiB
磁盘可用 ≥ 20 GB
Swap 是否配置
DNS 解析是否正常

核心检查逻辑：

# Check 1: Docker Daemon
docker info >/dev/null 2>&1

# Check 3: Required Ports Free (25, 465, 587, 993, 8080)
for port in 25 465 587 993 8080; do
    ss -tlnp "sport = :$port" | grep -q LISTEN && occupied=true
done

# Check 5: RAM >= 1.0 GiB
total_mib=$(free -m | awk '/Mem:/ {print $2}')
[ "$total_mib" -ge 1024 ]

# Check 6: Disk Space >= 20 GB Free
free_gb=$(df -BG / | awk 'NR==2 {print $4}' | sed 's/G//')
[ "$free_gb" -ge 20 ]

全部通过才建议继续部署，避免半路踩坑。

verify.sh — 部署后全面验证

docker compose up -d 完成后运行，14 项检查覆盖容器健康、端口连通性、服务响应和 DNS 解析：

所有容器是否正常运行
是否有容器在重启循环
SMTP/IMAP 端口是否可达
SMTP banner 是否返回
DNS 解析是否正常
磁盘使用率 < 80%

全部通过意味着邮件服务器部署成功。

架构总览

flowchart TB
    subgraph Internet["🌐 Internet"]
        Incoming["外部邮件服务器"]
        Recipient["收件人邮箱<br/>QQ / Gmail / Outlook"]
    end

    subgraph Aliyun["☁️ 阿里云 ECS"]
        subgraph Proxy["反向代理"]
            Caddy["Caddy<br/>:80 / :443"]
        end

        subgraph MailServer["Stalwart Mail Server"]
            SMTP["SMTP<br/>:25 :465 :587"]
            IMAP["IMAP<br/>:143 :993"]
            Admin["Admin Panel<br/>:8080 内网"]
            Storage[("RocksDB<br/>存储")]
        end
    end

    subgraph Relay["📡 阿里云 DirectMail"]
        DM["SMTP 中继<br/>smtpdm.aliyun.com:465"]
    end

    User["👤 管理员<br/>浏览器"] -->|"HTTPS"| Caddy
    Caddy -->|"反向代理"| Admin
    Client["📱 邮件客户端"] -->|"SMTP/IMAP"| SMTP
    Client -->|"SMTP/IMAP"| IMAP

    Incoming -->|"📥 收信 :25"| SMTP
    SMTP -->|"本地投递"| Storage

    SMTP -->|"📤 外发 :465"| DM
    DM -->|"阿里云代投"| Recipient

    style Aliyun fill:#f0f9ff,stroke:#0284c7
    style MailServer fill:#ecfdf5,stroke:#059669
    style Relay fill:#fef3c7,stroke:#d97706
    style Proxy fill:#fdf2f8,stroke:#db2777

关键配置点

1. DNS 记录

部署前需要在域名 DNS 配置 6 条记录：

MX — 收信路由，指向 mail.<DOMAIN>
SPF — 声明阿里云和自有服务器可代表域名发信
DKIM — 邮件签名，防止伪造（从 Stalwart 管理面板获取公钥）
DMARC — 收信方验证失败时的处理策略
SRV — 客户端自动发现（可选）

2. 阿里云 DirectMail 中继

在 Stalwart 的 Outbound Settings 中配置 Routing Strategy：

IF  is_local_domain(rcpt_domain)  →  本地投递
ELSE                               →  aliyun 中继外发

这样发往自己域名的邮件本地存储，发往外部的邮件走阿里云中继，互不干扰。

3. SSL 证书

Stalwart 支持挂载 certbot 证书。需要注意的是 Let's Encrypt 的 live 目录只有 root 可遍历，需要额外执行：

chmod o+x /etc/letsencrypt/live /etc/letsencrypt/archive
chmod 644 /etc/letsencrypt/archive/<DOMAIN>/privkey*.pem

客户端使用

配置完成后，可以用任意邮件客户端连接：

协议	服务器	端口	加密
SMTP	`mail.<DOMAIN>`	465	SSL/TLS
IMAP	`mail.<DOMAIN>`	993	SSL/TLS

用户名填完整邮箱地址，密码填 Stalwart 中设置的邮箱密码。

总结

这个仓库把「自建邮件服务器」这件事做成了一个可复现的方案：

一条 compose up 启动服务
preflight.sh 帮你检查环境，避免部署到一半才发现问题
verify.sh 帮你验证部署结果，不用自己逐项排查
README 记录每一步操作，包括常见的坑和解决方案

300MB 内存跑一个完整邮件服务器，比 Mailu/Mailcow 轻量得多，适合个人 VPS 自用。

仓库地址：github.com/7emotions/email-server

给 AI Agent 装上「嘴巴」和「耳朵」—— 让 OpenCode 真实打电话

Mon, 18 May 2026 00:00:00 GMT

背景

在使用 OpenCode 这样的 AI Agent 平台时，Agent 可以写代码、读文件、搜文档、部署服务，但有一个根本的能力空白：它不能打电话。

想象这些场景：

Agent 帮你完成了代码部署，需要通知王经理 —— 你只能自己拿起手机
Agent 从数据库里找到了一批欠费用户，需要逐一确认 —— 你手动拨号
Agent 检测到服务器宕机，想通知运维 —— 它只能发文字消息

Agent 不缺信息，缺的是触达真人的通道。电话仍然是最高优先级的通知方式 —— 微信可能静音，邮件可能淹没，但电话铃响，对方一定会接。

于是我写了

::github{repo="7emotions/phone-agent"}

功能

Phone Agent 是一个 MCP Server，跑在连接了 Android 手机的 Linux 机器上，向 OpenCode Agent 暴露 7 个工具：

MCP Tool	功能	典型场景
`phone_dial`	拨号 + 预生成开场白 TTS	任何电话的第一步
`phone_converse`	多轮自主对话（LLM 驱动）	确认出席、通知延期、收集信息
`phone_ask`	单轮：问 → 录 → 识别 → 提取	简单的是/否问题
`phone_speak`	单向 TTS 播放	纯通知，不需要回复
`phone_check`	查询通话状态	拨号前确认、挂断后确认
`phone_hangup`	挂断	结束时调用
`phone_filler`	播放预生成的垫话	桥接 TTS 生成延迟

Agent 只需要组合这些工具就可以完成完整的通话任务：

phone_dial(number, opening="您好，我是XX公司的AI助手...")
  → 拨号 + TTS 后台生成，接通瞬间播放

phone_converse(goal="确认明天评审会出席", skip_opening=true)
  → LLM 自主对话：录 → 识别 → 决策 → TTS → 回复 → 循环

phone_hangup()
  → 挂断，Agent 总结对话结果

架构设计

整体架构

┌──────────────────────────────────────────────────────┐
│                  OpenCode Agent                       │
│  phone_dial / hangup / check / speak / ask / converse │
└─────────────────────┬────────────────────────────────┘
                      │ MCP stdio (JSON-RPC)
┌─────────────────────▼────────────────────────────────┐
│              phone_call_mcp.py (688行)                │
│  ├─ 拨号调度    → ADB am start CALL                  │
│  ├─ 对话引擎    → DeepSeek API 方向盘                 │
│  ├─ 语音合成    → edge-tts (云端) / espeak-ng (本地)   │
│  ├─ 语音识别    → faster-whisper tiny                │
│  ├─ 录音控制    → WebRTC VAD + parecord               │
│  ├─ 回声管理    → 5次重试清除 loopback                │
│  └─ 蓝牙管理    → HSP 自动重连                        │
└──────┬──────────────────────────┬────────────────────┘
       │                          │
   ┌───▼────┐              ┌──────▼──────┐
   │  ADB   │              │  蓝牙 HSP    │
   │ (拨号) │              │ paplay 上行  │
   └────────┘              │ parecord 下行│
                           └─────────────┘

为什么是 MCP？

OpenCode 本身没有「打电话」的能力，但它有 MCP 扩展机制。我把整个电话能力包装成一个 MCP Server：

Agent 不需要知道蓝牙、ADB、PulseAudio 的存在 —— 它只需要调用工具
对话决策在远端 LLM 完成 —— Agent 只负责编排，不参与每轮决定
Skill 提供使用指南 —— phone-call Skill 告诉 Agent 什么时候用哪个工具、怎么组合

双引擎设计：API + 本地各司其职

对话决策 (方向盘)  → DeepSeek API  → 约 1 秒延迟，语义理解强
简单提取 (辅助)    → 本地 1.5B LM → 更快的结构化提取
TTS               → edge-tts      → 2-5 秒，后台并行生成
ASR               → whisper tiny  → 1-3 秒，速度优先

为什么不用纯本地？ 1.5B 的本地模型做多轮对话决策不稳定，容易陷入重复提问。DeepSeek API 做方向盘，本地模型做简单提取，各做自己擅长的。

为什么用 whisper tiny 而不是 small？ 实测 tiny 转写日常中文对话准确率 90% 以上，但比 small 快 3-5 倍。电话场景需要「够用就好」的转写速度，而不是精准字幕。

关键技术

四层停止机制

多轮对话最大的坑是「不知道什么时候停」。Phone Agent 实现了四层防御：

层	机制	触发条件
1. 模型 `done`	LLM 判断对话完成	信息收集完毕 / 对方拒绝 / 对话结束
2. 关键词	检测推脱/拒绝语	"帮你记"、"打错"、"稍后联系"、"尽快" 等 25 个以上关键词
3. 去重	连续两轮相同回复	"喂？" → "喂？"（对方不配合）
4. max_turns	硬上限	安全网，防止死循环

经过 184 条多场景模拟对话测试，停止准确率达到 98%。模型 done 是第一道线，关键词是安全网 —— 模型有时会被"我帮你记一下"这类委婉拒绝骗过去，关键词层补上这个缺口。

两段式开场：零延迟通话

一个容易被忽略但体验差距巨大的细节：TTS 生成需要 2-5 秒。如果接通后才开始生成 TTS，对方会听到 2-5 秒的沉默，以为是骚扰电话直接挂掉。

解决方案：

phone_dial(number, opening="您好，我是...")
    │
    ├── 拨号中 (ringing) ───→ 后台生成 opening TTS
    │
    └── 对方接听 ───→ 检测 state=ACTIVE ───→ 立即播放 TTS

开场白在拨号振铃期间后台生成，对方接通的瞬间就听到声音 —— 就像真人打电话一样自然。后续对话通过 phone_converse(skip_opening=true) 无缝衔接。

TTS 间隙填补

录音结束后，LLM 决策 + TTS 生成需要 3-8 秒。如果对方在这期间听不到任何声音，会以为断线。

解决：录音结束 2 秒后，如果 TTS 还没生成完，自动播放预录的垫话「请稍等，让我思考一下」。如果 TTS 在垫话期间完成，等垫话播完再切入 TTS —— 不抢话、不重叠、不断线。

第一轮永远不播垫话（对方刚接电话，垫话显得突兀）。

「不知道就说不知道」

LLM 最大的问题之一是幻觉——被问到不知道的信息时会编造答案。在电话场景里这尤其危险。

Phone Agent 在 System Prompt 里明确要求：

遇到你不知道的信息，诚实说"这个我不确定，我确认后再回复您"，返回 done，reason 写 "callback: 需要确认XXX后再回电"。

Agent 拿到 done_reason: "callback:..." 后会告知用户需要查证，然后带着确认后的信息重拨。

如何使用

1. 硬件准备

一台 Linux 电脑（蓝牙 + USB）
一台 Android 手机（已 root，已测试 Xiaomi 22041216C / Android 14 / MTK Dimensity 8100）
USB 数据线连接电脑和手机

2. 蓝牙配对 (HSP)

bluetoothctl pair F8:AB:82:92:08:76
bluetoothctl trust F8:AB:82:92:08:76
pactl list cards short | grep bluez  # 确认识别

HSP（Headset Profile）是关键——它能提供双向 8kHz 语音通路。A2DP 只能单向放音乐，不能录音。

3. 安装依赖

pip install mcp edge-tts webrtcvad
apt install pulseaudio pulseaudio-module-bluetooth ffmpeg
pip install faster-whisper  # ASR

4. 生成垫话音频

python3 gen_fillers.py

5. 配置 MCP Server

git clone https://github.com/7emotions/phone-agent.git

在 opencode.jsonc 中添加：

"phone-call": {
  "type": "local",
  "command": ["python3", "/path/to/phone_call_mcp.py"],
  "enabled": true,
  "timeout": 300000,
  "environment": {
    "PHONE_CONVERSE_BACKEND": "api",
    "PHONE_TTS_BACKEND": "edge",
    "PHONE_LLM_URL": "https://api.deepseek.com/chat/completions",
    "PHONE_LLM_KEY": "sk-xxx",
    "PHONE_LLM_MODEL": "deepseek-chat",
    "PHONE_LLM_CONTEXT": "你是XX公司的AI助手。",
    "PHONE_BT_MAC": "F8:AB:82:92:08:76",
    "PHONE_BT_CARD": "bluez_card.F8_AB_82_92_08_76",
    "PHONE_BT_SINK": "bluez_sink.F8_AB_82_92_08_76.headset_audio_gateway",
    "PHONE_BT_SOURCE": "bluez_source.F8_AB_82_92_08_76.headset_audio_gateway",
    "PHONE_ADB": "/path/to/adb"
  }
}

6. 安装 Agent Skill

将仓库里的 skill-phone-call.md 复制到 ~/.agents/skills/phone-call/SKILL.md，重启 OpenCode。

7. 使用

配置完成后，Agent 就获得了打电话能力。对它说：

"帮我打电话给 138xxxx，确认他明天下午能否参加评审会"

Agent 会自动：

调用 phone_dial 拨号，附带预生成的「你好，我是 XX 公司 AI 助手...」开场白
调用 phone_converse 进行多轮对话
在对话完成后挂断
从返回的 transcripts 中提取信息，用自然语言回复你

对话演示

一段真实通话记录（对方为某公司客服）：

Agent: 您好，我是南京青赋驭境的AI助手，想跟您确认一下
       明天下午的评审会您这边能参加吗？

Caller: 现上评审会是吧？请问具体是哪个部门或者项目的会议呢？

Agent: 是明天下午的线上评审会，具体是南京青赋驭境的项目评审会。

Caller: 嗯，收到了，我会尽快帮您确认一下是否能参加的。

→ 触发停止（关键词："尽快"）— 对方表达了帮忙意愿但未承诺

另一段成功回电流程：

Agent: 您好，刚才关于XXX的问题，我已经确认了，请问您现在方便吗？

Caller: 方便的，你说。

Agent: 根据我们的记录，您在系统中的状态是XXX，所以需要您...

Caller: 好的，明白了，我马上去处理。

→ 触发停止（模型 done）— 信息传达清楚，对方已承诺

局限与后续计划

当前局限：

需要 root 手机：ADB 拨号不要求 root，但蓝牙 HSP profile 管理在非 root 设备上有限制
仅限中文：whisper 支持多语言，但 System Prompt 和 filler 目前只写中文
Linux 单机部署：MCP 要求 stdio 通道，不能远程调用
单路通话：HSP 只能处理一路双向音频，不能同时打两个电话
需要 USB 连接：ADB over WiFi 也可以，但有线更稳定

计划中的改进：

[ ] 支持 ADB over WiFi，摆脱 USB 线
[ ] 多语言支持（英文 System Prompt + 英文 filler）
[ ] 回电调度：从 done_reason 提取待确认事项，自动创建回电任务
[ ] GPU 加速 whisper（CUDA / Apple Silicon）
[ ] 通话录音存档，供 Agent 回顾历史对话

结语

phone-agent 给 AI Agent 装上了一个真正的「嘴巴」和「耳朵」——不是模拟的，是真实能打通电话的。

它的核心价值不在于技术多么复杂（688 行 Python），而在于打通了 Agent 到真人之间的最后一公里。Agent 能写代码、能搜文档、能部署服务，但在此之前，它需要一个人类来替它打电话。现在不需要了。

如果你也在用 OpenCode 或其他支持 MCP 的 AI Agent 平台，欢迎尝试。项目开源在 GitHub，MIT 协议。

项目地址：github.com/7emotions/phone-agent

背景文章：Terminator-AI — 「普通人用 OpenClaw 实战：自动打电话」

让 AI Agent 也能「看」视频 —— 开发 video-transcript-skill

Sat, 16 May 2026 00:00:00 GMT

背景

在使用 AI 编程助手（如 OpenCode、Claude Code 等）时，有一个明显的痛点：AI Agent 本质上是文本模型，它无法「观看」视频。当我遇到一个技术视频想丢给它学习时，只能自己看一遍再做总结转述。而 OpenCode 的 Skill 机制恰好提供了扩展能力的接口——我可以写一个 Skill，让 Agent 在需要时自动调用，把视频转成它读得懂的文本。

于是有了

::github{repo="7emotions/video-transcript-skill"}

功能

这个 Skill 做的事情很直接：

收到视频链接 → 触发 Skill
尝试获取已有字幕 → 如果平台提供了字幕（B站、YouTube 通常有），几秒内返回结果
字幕不可用时 → 用 yt-dlp 下载音频 → ffmpeg 转码 → 本地 Whisper 转录 → 返回完整文本

支持的平台：Bilibili（B站）、YouTube、Vimeo、Twitch，以及 yt-dlp 支持的数百个视频网站。

架构设计

为什么是 MCP？

Skill 本身只是一份指令文件（SKILL.md），告诉 Agent 在什么场景下该做什么。真正的「能力」需要由外部的 MCP Server 提供。

这里依赖的是 video-toolkit MCP Server，它暴露了三个关键工具：

MCP Tool	功能	耗时
`get-transcript`	获取平台已有字幕	秒级
`generate-subtitles`	下载音频 + Whisper 转录	分钟级
`list-transcript-languages`	查询可用字幕语言	秒级

双轨策略：字幕优先，Whisper 兜底

视频链接
    │
    ├── 有字幕？──→ get-transcript ──→ 直接返回（秒级）
    │
    └── 无字幕？──→ yt-dlp 下载音频
                        │
                    ffmpeg 转 16kHz 单声道
                        │
                    faster-whisper 转录
                        │
                    返回带时间戳的完整文本

这个策略的好处是：

大多数视频走得通第一条路径，用户感知延迟很低
第二条路径是终极兜底，只要 yt-dlp 能下载音频，就一定能出文本

技术选型

yt-dlp — 通用视频下载

yt-dlp 是 youtube-dl 的活跃 fork，支持数百个视频平台。用它做音频下载层，意味着不需要为每个平台写适配代码。

# 只下载音频，转为 mp3
yt-dlp -x --audio-format mp3 "https://www.bilibili.com/video/BVxxxxxx"

faster-whisper — CPU 上也能用的转录

OpenAI 的 Whisper 效果很好，但原版在 CPU 上太慢。faster-whisper 是 CTranslate2 加速的 Whisper 实现，同样的模型在 CPU 上快 4 倍，内存占用更低。

实际测试数据（4 核 CPU，small 模型）：

视频时长	转录耗时	倍速
5 分钟	~1 分钟	5x
15 分钟	~3 分钟	5x
30 分钟	~6.5 分钟	4.6x
1 小时	~13 分钟	4.6x

对于日常使用的 10-20 分钟视频，等待 2-3 分钟完全在可接受范围内。

Whisper 包装脚本

MCP Server 需要调用 Whisper，但 faster-whisper 是 Python 库而非 CLI 工具。为了让 MCP Server 能像调用命令行工具一样使用它，我写了一个薄包装脚本（scripts/whisper）：

#!/usr/bin/env python3
"""Thin wrapper around faster-whisper for CLI usage."""
import sys
import json
from faster_whisper import WhisperModel

model_size = "small"
model = WhisperModel(model_size, device="cpu", compute_type="int8")

segments, info = model.transcribe(sys.argv[1])
result = [{"start": s.start, "end": s.end, "text": s.text} for s in segments]
print(json.dumps(result, ensure_ascii=False))

如何使用

1. 安装依赖

pip install yt-dlp faster-whisper
# ffmpeg 请根据系统自行安装
# Ubuntu/Debian: sudo apt install ffmpeg

2. 安装 Whisper 包装脚本

git clone https://github.com/7emotions/video-transcript-skill.git
cp video-transcript-skill/scripts/whisper ~/.local/bin/whisper
chmod +x ~/.local/bin/whisper

3. 配置 video-toolkit MCP Server

git clone https://github.com/JamesANZ/video-transcript-mcp.git
cd video-transcript-mcp
npm install && npm run build

在 opencode.jsonc 中添加：

"video-toolkit": {
  "type": "local",
  "command": ["node", "/path/to/video-toolkit-mcp/dist/index.js"],
  "enabled": true,
  "timeout": 600000,
  "environment": {
    "YT_DLP_PATH": "yt-dlp",
    "FFMPEG_PATH": "ffmpeg",
    "TRANSCRIPT_MCP_WHISPER_ENGINE": "local",
    "WHISPER_BINARY_PATH": "/home/ubuntu/.local/bin/whisper",
    "WHISPER_MODEL_PATH": "small"
  }
}

4. 安装 Skill

将 SKILL.md 放到 OpenCode 的 skills 目录，重启即可。

5. 使用

直接发视频链接给 Agent：

"帮我总结一下这个视频 https://www.bilibili.com/video/BVxxxxxx"

Agent 会自动调用 Skill，先尝试获取字幕，失败则用 Whisper 转录，最终返回完整的文本内容供你分析和总结。

6. 案例

我在Bilibili中找到了Terminator-AI的视频普通人用 OpenClaw 实战系列(6) ：自动打电话

::bilibili{bvid="BV1kvPnz9EcA"}

以下是Agent学习的结果

局限与后续计划

当前局限：

CPU 转录速度有上限：1 小时视频需要 ~13 分钟。如果有 GPU，速度可以提升 10 倍以上
部分平台需要认证：B站某些视频需要登录才能获取字幕，此时会自动走 Whisper 降级路径
长视频可能超出上下文窗口：超过 1 小时的视频转录文本可能超过 LLM 的上下文限制，需要分段处理

计划中的改进：

[ ] 支持 GPU 加速（CUDA / Apple Silicon）
[ ] 长视频自动分段 + 逐段总结
[ ] 缓存已转录视频，避免重复转录
[ ] 支持更多 Whisper 模型大小选择（tiny ~ large-v3）

结语

video-transcript-skill 本质上做了一件事：给基于文本的 AI Agent 装上一双「耳朵」。它不需要 Agent 理解视频画面，只需要让 Agent 听到视频里说了什么——而这已经覆盖了绝大多数技术教程、演讲、会议记录等场景。

如果你也在用 OpenCode 或其他支持 Skill/MCP 的 AI 编程工具，欢迎尝试。项目开源在 GitHub，MIT 协议，任何形式的贡献都欢迎。

项目地址：github.com/7emotions/video-transcript-skill

yolov10模型Docker训练环境搭建

Thu, 17 Apr 2025 00:00:00 GMT

环境

docker compose

代码克隆

使用git克隆仓库

git clone https://github.com/7emotions/robot-vision.git

::github{repo="7emotions/robot-vision"}

数据集标定

在yolo/文件夹下（后续都在该工作目录），新建dataset/images/与dataset/labels/。使用labelimg标定数据集，yolo支持的数据集格式为

<class_id> <x_center> <y_center> <width> <height>

[!NOTE] label文件的文件名需要与image 文件的文件名保持一致。

将图片文件与标签文件分别移动到dataset/images/与dataset/labels下。

数据集划分

运行split.py划分数据集

docker-compose run trainer python3 split.py

split.py会将数据集的80%划分为训练集，20%划分为验证集。对于缺失labels的负样本，会新建空白label。

划分后，dataset/的目录结构为

dataset/
├── images/
│   ├── train/
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── ...
│   └── val/
│       ├── image3.jpg
│       ├── image4.jpeg
│       └── ...
└── labels/
    ├── train/
    │   ├── image1.txt
    │   ├── image2.txt
    │   └── ...
    └── val/
        ├── image3.txt
        ├── image4.txt
        └── ...

数据配置文件

训练之前需要编写数据配置文件。修改conf.yml文件

train: dataset/images/train
val: dataset/images/val
nc: 7
names: ["red target", "blue area", "blue target", "starting point", "black target","yellow target","red area"]

其中，nc表示类别数目，names表示类别名称列表。

预训练权重文件

在yolov10仓库的Release中提供预训练权重文件。此处以yolov10s.pt为例。

::github{repo="THU-MIG/yolov10"}

[!NOTE] YOLOv10 系列通常会包含多个不同大小和复杂度的变体，以适应不同的计算资源和性能需求。这些变体通常会用后缀来区分，例如 -n（极小）、-s（小型）、-m（中型）、-l（大型）、-x（极大）等等。

[!NOTE] 若更换预训练权重文件，请在compose.yml中替换yolov10s.pt。

模型训练

启动容器进行训练

docker-compose up -d

查看日志

docker-compose logs trainer -f

模型将输出在runs/目录下，可查看到结果

模型导出

保存在yolo/runs/deteçt/train/weights/下的.pt文件可以通过以下命令导出为.onnx模型文件。

docker-compose run trainer yolo export model=runs/detect/train/weights/best.pt format=onnx

.onnx模型会保存在yolo/runs/detect/train/weights/目录下。

模型使用

以cpp为例，采用OpenCV导入.onnx模型。

#include <iostream>
#include <fstream>
#include <string>
#include <vector>
#include <opencv2/opencv.hpp>
#include <opencv2/dnn.hpp>
#include <format>

int main() {
    std::string onnx_model_path = "best.onnx";
    std::string classes_path = "classes.txt";
    std::string image_path = "test.jpg";

    float confidenceThreshold = 0.5;
    float nmsThreshold = 0.4;

    cv::Net net = cv::dnn::readNetFromONNX(onnx_model_path);
    if (net.empty()) {
        std::cerr << "Error: Could not load ONNX model: " << onnx_model_path << std::endl;
        return -1;
    }
    std::cout << "ONNX model loaded successfully." << std::endl;

    std::vector<std::string> classes;
    std::ifstream ifs(classes_path);
    std::string line;
    if (ifs.is_open()) {
        while (getline(ifs, line)) {
            classes.push_back(line);
        }
    } else {
        std::cerr << "Error: Could not open classes file: " << classes_path << std::endl;
        return -1;
    }
    std::cout << "Loaded " << classes.size() << " classes." << std::endl;

    cv::Mat frame = cv::imread(image_path);
    if (frame.empty()) {
        std::cerr << "Error: Could not read image: " << image_path << std::endl;
        return -1;
    }
    int frameWidth = frame.cols;
    int frameHeight = frame.rows;

    cv::Mat blob;
    cv::dnn::blobFromImage(frame, blob, 1 / 255.0, cv::Size(640, 640), cv::Scalar(0, 0, 0), true, false);
    net.setInput(blob);

    cv::Mat output = net.forward();

    std::vector<int> classIds;
    std::vector<float> confidences;
    std::vector<cv::Rect> boxes;

    int rows = output.size[2];
    int cols = output.size[3];

    for (int i = 0; i < rows; ++i) {
        float confidence = output.at<float>(0, 0, i, 4);

        if (confidence > confidenceThreshold) {
            cv::Mat scores = output.row(i).colRange(5, cols);
            cv::Point classIdPoint;
            double maxScore;
            cv::minMaxLoc(scores, 0, &maxScore, 0, &classIdPoint);
            int classId = classIdPoint.x;

            if (maxScore > confidenceThreshold) {
                float centerX = output.at<float>(0, 0, i, 0) * frameWidth;
                float centerY = output.at<float>(0, 0, i, 1) * frameHeight;
                float width = output.at<float>(0, 0, i, 2) * frameWidth;
                float height = output.at<float>(0, 0, i, 3) * frameHeight;
                cv::Rect box(cv::Point(cvRound(centerX - width / 2), cvRound(centerY - height / 2)),
                             cv::Size(cvRound(width), cvRound(height)));

                classIds.push_back(classId);
                confidences.push_back(confidence * maxScore);
                boxes.push_back(box);
            }
        }
    }

    std::vector<int> indices;
    cv::dnn::NMSBoxes(boxes, confidences, confidenceThreshold, nmsThreshold, indices);

    for (int idx : indices) {
        cv::Rect box = boxes[idx];
        int classId = classIds[idx];
        float confidence = confidences[idx];

        cv::rectangle(frame, box, cv::Scalar(0, 255, 0), 2);
        
  std::string label = classes[classId] + ": " + std::format("{:.2f}", confidence);
        cv::putText(frame, label, cv::Point(box.x, box.y - 10), cv::FONT_HERSHEY_SIMPLEX, 0.5, cv::Scalar(0, 255, 0), 2);
    }

    cv::imshow("Detected Objects", frame);
    cv::waitKey(0);
    cv::destroyAllWindows();

    return 0;
}

AtomGit Pages 使用自定义域名

Wed, 19 Mar 2025 00:00:00 GMT

前置条件

已经备案的域名
已经配置Docker的云服务器

域名解析配置

为域名添加A记录，解析值为云服务器的IP地址。

云服务器配置

为云服务添加出站规则，开放443端口与80端口。

`Caddy`配置

新建Caddyfile，并写入

yours.domain.com {
    reverse_proxy nginx:80
}

[!NOTE] 请修改yours.domain.com为你的域名。

`Nginx`配置

新建nginx.conf，并写入

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name yours.domain.com;

        location / {
            proxy_pass https://you.atomgit.net/your-blog/;
            proxy_set_header Host you.atomgit.net;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header User-Agent $http_user_agent;
            proxy_ssl_server_name on;
            proxy_ssl_protocols TLSv1.2 TLSv1.3;
            proxy_ssl_ciphers 'HIGH:!aNULL:!MD5';
        }
    }
}

[!NOTE] 请修改yours.domain.com为你的域名，you.atomgit.net为你的AtomGit Pages的域名，your-blog为你的博客的目录。

`Docker`配置

version: '3.8'

services:
    nginx:
        container_name: blog-nginx
        image: nginx:latest
        ports:
            - "80:80" 
        volumes:
            - ./nginx.conf:/etc/nginx/nginx.conf
        networks:
            - blognetwork

    caddy:
        container_name: blog-caddy
        image: caddy:latest
        ports:
            - "443:443"
        volumes:
            - ./Caddyfile:/etc/caddy/Caddyfile
        networks:
            - blognetwork

networks:
  blognetwork:

构建容器

运行以下指令构建容器

docker-compose up -d

访问https://yours.domain.com/以查看博客。

国内自动化静态博客搭建

Fri, 14 Mar 2025 00:00:00 GMT

前言

最近在搭建静态博客，发现国内访问Github Pages的速度很慢，于是想通过国内的服务器来部署静态博客。经过一番搜索，发现AtomGit是一个很好的选择，它支持Pages服务，并且在国内有较好的访问速度。

准备

AtomGit

AtomGit是国内由开放原子基金会运营的Git托管平台，它支持Pages服务，并且具有良好的访问速度。

你需要先在AtomGit上注册一个账号，并创建一个仓库，用于部署静态博客的站点构建文件。并且，该仓库需要开启Pages服务。参考AtomGit Pages。

[!NOTE] 开启Pages服务后，AtomGit会自动为你的仓库分配一个uri，例如https://<username>.atomgit.net/<repo-name>。你可以通过这个url来访问你的静态博客。

Github

你需要一个Github账号，并且需要创建一个仓库，用于存放静态博客的源文件。这个仓库不需要开启Pages服务。从该仓库中，你可以通过Github Action来生成静态博客的站点文件，并将其部署到AtomGit上。

Node.js （可选）

Fuwari从Node.js构建，你需要安装Node.js Version 20。你可以从Node.js官网下载并安装。

开始

1. Fork Fuwari

首先，你需要Fork Fuwari 到你的Github账号下。Fuwari是基于Astro的静态博客模板。

:sparkle: 功能特性

[x] 基于 Astro 和 Tailwind CSS 开发
[x] 流畅的动画和页面过渡
[x] 亮色 / 暗色模式
[x] 自定义主题色和横幅图片
[x] 响应式设计
[ ] 评论
[x] 搜索
[ ] 文内目录

2. 修改配置文件

你可以通过配置文件 src/config.ts 自定义博客。以我的配置文件为例。

import type {
  LicenseConfig,
  NavBarConfig,
  ProfileConfig,
  SiteConfig,
} from './types/config'
import { LinkPreset } from './types/config'

export const siteConfig: SiteConfig = {
  title: 'Lorenzo Feng',
  subtitle: 'Blog Site',
  lang: 'zh_CN',         // 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th'
  themeColor: {
    hue: 250,         // Default hue for the theme color, from 0 to 360. e.g. red: 0, teal: 200, cyan: 250, pink: 345
    fixed: false,     // Hide the theme color picker for visitors
  },
  banner: {
    enable: true,
    src: 'assets/images/demo-banner.png',   // Relative to the /src directory. Relative to the /public directory if it starts with '/'
    position: 'center',      // Equivalent to object-position, only supports 'top', 'center', 'bottom'. 'center' by default
    credit: {
      enable: false,         // Display the credit text of the banner image
      text: '',              // Credit text to be displayed
      url: ''                // (Optional) URL link to the original artwork or artist's page
    }
  },
  toc: {
    enable: true,           // Display the table of contents on the right side of the post
    depth: 2                // Maximum heading depth to show in the table, from 1 to 3
  },
  favicon: [    // Leave this array empty to use the default favicon
    // {
    //   src: '/favicon/icon.png',    // Path of the favicon, relative to the /public directory
    //   theme: 'light',              // (Optional) Either 'light' or 'dark', set only if you have different favicons for light and dark mode
    //   sizes: '32x32',              // (Optional) Size of the favicon, set only if you have favicons of different sizes
    // }
  ]
}

export const navBarConfig: NavBarConfig = {
  links: [
    LinkPreset.Home,
    LinkPreset.Archive,
    LinkPreset.About,
    {
      name: 'GitHub',
      url: 'https://github.com/7emotions/astro-blog/',     // Internal links should not include the base path, as it is automatically added
      external: true,                               // Show an external link icon and will open in a new tab
    },
  ],
}

export const profileConfig: ProfileConfig = {
  avatar: 'assets/images/demo-avatar.png',  // Relative to the /src directory. Relative to the /public directory if it starts with '/'
  name: 'Lorenzo Feng',
  bio: 'An algorithm engineer of Alliance, NJUST',
  links: [
    {
        name: 'Telegram',
        icon: 'logos:telegram',
        url: 'https://t.me/lorenzofeng'
    },
    {
      name: 'QQ',
      icon: 'mdi:qqchat',
      url: 'https://qm.qq.com/q/gszht217Fu',
    },
    {
      name: 'GitHub',
      icon: 'fa6-brands:github',
      url: 'https://github.com/7emotions',
    },
  ],
}

export const licenseConfig: LicenseConfig = {
  enable: true,
  name: 'CC BY-NC-SA 4.0',
  url: 'https://creativecommons.org/licenses/by-nc-sa/4.0/',
}

3. 创建文章

Astro框架是基于Markdown的，所以你可以在src/content/posts/目录中创建新的Markdown文件，编辑文章内容。你也可以在终端中执行 pnpm new-post <filename> 创建新文章，并在src/content/posts/目录中编辑。

文章头格式如下

---
title: My First Blog Post //文章标题
published: 2023-09-09 //文章发布日期
description: This is the first post of my new Astro blog.  //文章描述
image: ./cover.jpg  //这是文章封面，路径可以是相对路径，也可以是绝对路径
tags: [Foo, Bar] //文章标签
category: Front-end //文章分类
draft: false //是否为草稿
lang: jp      //仅当文章语言与 `config.ts` 中的网站语言不同时需要设置
---

4. 本地构建（可选）

安装依赖

npm install -g pnpm
pnpm install && pnpm add sharp

运行以下命令，可以在本地https://localhost:4321/预览博客

pnpm dev

构建博客

pnpm run build

5. 部署

修改在根目录下的 astro.config.mjs

export default defineConfig({
    site: "https://7emotions.atomgit.net", // <username>.atomgit.net
    base: "/blog", // <repo-name>
    trailingSlash: "always"
    // ...
})

将 base 修改为你的仓库名称，将 <username> 修改为你的用户名。例如，如果你的用户名是 lorenzofeng，仓库名称是 blog，那么 base 应该是 /blog，site 应该是 https://lorenzofeng.atomgit.net。

在根目录新建 .github/workflows/astro.yml，并写入以下内容

name: Deploy to AtomGit Pages

on:
  push:
    branches: [main] # 修改为Github源码仓库的分支名
  workflow_dispatch:

permissions:
  contents: read

jobs:
  deployment:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v4
        with:
          ref: main # 修改为Github源码仓库的分支名
      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install dependence
        run: |
          npm install -g pnpm
          pnpm install
          pnpm add sharp
      - name: Build dist
        run: pnpm run build
      - name: Publish branch
        uses: 7emotions/branch-pub@v4
        with:
          token: ${{ secrets.ATOM_TOKEN }} 
          user: 7emotions # 修改为你的AtomGit用户名
          repo: 7emotions/blog # 修改为AtomGit的仓库路径
          github_domain: atomgit.com
          branch: pages # 要部署的分支名称
          folder: dist

在AtomGit的访问令牌中创建个人令牌（Personal Access Token），权限为repo。

在Github仓库Settings中，找到Secrets and variables，选择Action。点击New repository secret，添加ATOM_TOKEN，值为你的AtomGit的Personal Access Token。

推送代码到Github仓库，等待Github Action执行完成，即可在AtomGit上看到新发布的分支。

在AtomGit的仓库中，点击设置->Pages，选择pages分支，即可在https://<username>.atomgit.net/<repo-name>访问你的博客。

参考

国内静态博客一键部署

Fri, 14 Mar 2025 00:00:00 GMT

前言

手动部署以及博客配置参考国内自动化静态博客搭建。

准备

AtomGit

AtomGit是国内由开放原子基金会运营的Git托管平台，它支持Pages服务，并且具有良好的访问速度。

一个账号与一个空仓库

你需要先在AtomGit上注册一个账号，并创建一个空仓库，用于部署静态博客的站点构建文件。

Pages服务申请

该仓库需要开启Pages服务。参考AtomGit Pages。

开启Pages服务后，AtomGit会自动为你的仓库分配一个uri，例如https://<username>.atomgit.net/<repo-name>。你可以通过这个url来访问你的静态博客。

访问令牌

你需要创建一个访问令牌（Personal Access Token，PAT），用于Github Action访问你的仓库。点击此处生成。

注意: 访问令牌需要勾选repo权限，否则Github Action无法访问你的仓库。

Github

一个账号 你需要一个Github账号，并且需要创建一个仓库，用于存放静态博客的源文件。这个仓库不需要开启Pages服务。从该仓库中，你可以通过Github Action来生成静态博客的站点文件，并将其部署到AtomGit上。

Github Action 部署

1. Fork 7emotions/Fuwari

首先，你需要Fork 我的Fuwari 到你的Github账号下。

如何Fork仓库

2. 配置Secret

在Fork后的仓库中，点击Settings，然后点击Secrets and variables，选择Actions，点击New repository secret，添加以下三个Secret。

TOKEN：AtomGit的访问令牌(PAT)，用于Github Action访问你的AtomGit仓库。
USER：AtomGit的用户名，用于Github Action访问你的AtomGit仓库。
REPO：AtomGit的仓库名，用于Github Action访问你的AtomGit仓库。

例如，我的AtomGit仓库的uri为https://atomgit.com/<username>/<repo-name>，那么USER为<username>，REPO为<repo-name>。

3. 启用Actions

在Github仓库中，点击Actions，选择Deploy Pages，点击Run workflow，选择分支为main，点击Run workflow。

刷新页面，可以看到Github Action正在运行。

约莫1分钟后，出现如下提示，说明Github Action运行完成。

当Github Action运行完成后，你可以访问https://<username>.atomgit.net/<repo-name>查看你的静态博客。

例如，我的AtomGit仓库的uri为https://atomgit.com/7emotions/blog，那么我的静态博客的访问地址为https://7emotions.atomgit.net/blog。

Docker 部署

1. Fork 7emotions/Fuwari

首先，你需要Fork 我的Fuwari 到你的Github账号下。

如何Fork仓库

2. Clone 仓库

在本地，使用git clone命令克隆你的Fork仓库。

git clone https://github.com/<username>/fuwari.git

3. 配置环境变量

在fuwari目录下，创建一个.env文件，并添加以下内容。

TOKEN=<AtomGit-Token>
USER=<username>
REPO=<repo-name>
GIT_DOMAIN=atomgit.com
BRANCH=pages

文中<AtomGit-Token>、<username>、<repo-name>分别代表AtomGit的访问令牌(PAT)、AtomGit的用户名、AtomGit的仓库名。

4. 构建与运行

在fuwari目录下，使用以下命令构建与运行。

docker-compose up -d

5. 访问博客

当Docker容器运行完成后，你可以访问https://<username>.atomgit.net/<repo-name>查看你的静态博客。

博文发布

无论是Github Action部署还是Docker部署，每次向远端推送博文，会自动触发Github Action，生成静态博客的站点文件，并将其部署到AtomGit上。

hello-world

Thu, 13 Mar 2025 00:00:00 GMT

你好世界

profile

Lorenzo Feng
C/C++
ROS2
Docker

URL 测试

Click Here

图片测试

代码块测试

def main(name:str="lorenzo")->int:
    print("hello, %s"%name)
    return len(name)

if __name__=="__main__":
    main()

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

::github{repo="Fabrizz/MMM-OnSpotify"}

Create a GitHub repository card with the code ::github{repo="<owner>/<repo>"}.

::github{repo="saicaca/fuwari"}

Admonitions

Following types of admonitions are supported: note tip important warning caution

:::note Highlights information that users should take into account, even when skimming. :::

:::tip Optional information to help a user be more successful. :::

:::important Crucial information necessary for users to succeed. :::

:::warning Critical content demanding immediate user attention due to potential risks. :::

:::caution Negative potential consequences of an action. :::

Basic Syntax

:::note
Highlights information that users should take into account, even when skimming.
:::

:::tip
Optional information to help a user be more successful.
:::

Custom Titles

The title of the admonition can be customized.

:::note[MY CUSTOM TITLE] This is a note with a custom title. :::

:::note[MY CUSTOM TITLE]
This is a note with a custom title.
:::

GitHub Syntax

[!TIP] The GitHub syntax is also supported.

> [!NOTE]
> The GitHub syntax is also supported.

> [!TIP]
> The GitHub syntax is also supported.

Simple Guides for Fuwari

Mon, 01 Apr 2024 00:00:00 GMT

Cover image source: Source

This blog template is built with Astro. For the things that are not mentioned in this guide, you may find the answers in the Astro Docs.

Front-matter of Posts

---
title: My First Blog Post
published: 2023-09-09
description: This is the first post of my new Astro blog.
image: ./cover.jpg
tags: [Foo, Bar]
category: Front-end
draft: false
---

Attribute	Description
`title`	The title of the post.
`published`	The date the post was published.
`description`	A short description of the post. Displayed on index page.
`image`	The cover image path of the post.<br/>1. Start with `http://` or `https://`: Use web image<br/>2. Start with `/`: For image in `public` dir<br/>3. With none of the prefixes: Relative to the markdown file
`tags`	The tags of the post.
`category`	The category of the post.
`draft`	If this post is still a draft, which won't be displayed.

Where to Place the Post Files

Your post files should be placed in src/content/posts/ directory. You can also create sub-directories to better organize your posts and assets.

src/content/posts/
├── post-1.md
└── post-2/
    ├── cover.png
    └── index.md

Markdown Example

Sun, 01 Oct 2023 00:00:00 GMT

An h1 header

Paragraphs are separated by a blank line.

2nd paragraph. Italic, bold, and monospace. Itemized lists look like:

this one
that one
the other one

Note that --- not considering the asterisk --- the actual text content starts at 4-columns in.

Block quotes are written like so.

They can span multiple paragraphs, if you like.

Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all in chapters 12--14"). Three dots ... will be converted to an ellipsis. Unicode is supported. ☺

An h2 header

Here's a numbered list:

first item
second item
third item

Note again how the actual text starts at 4 columns in (4 characters from the left side). Here's a code sample:

# Let me re-iterate ...
for i in 1 .. 10 { do-something(i) }

As you probably guessed, indented 4 spaces. By the way, instead of indenting the block, you can use delimited blocks, if you like:

define foobar() {
    print "Welcome to flavor country!";
}

(which makes copying & pasting easier). You can optionally mark the delimited block for Pandoc to syntax highlight it:

import time
# Quick, count to ten!
for i in range(10):
    # (but not *too* quick)
    time.sleep(0.5)
    print i

An h3 header

Now a nested list:

First, get these ingredients:
- carrots
- celery
- lentils
Boil some water.

Dump everything in the pot and follow this algorithm:

 find wooden spoon
 uncover pot
 stir
 cover pot
 balance wooden spoon precariously on pot handle
 wait 10 minutes
 goto first step (or shut off burner when done)

Do not bump wooden spoon or it will fall.

Notice again how text always lines up on 4-space indents (including that last line which continues item 3 above).

Here's a link to a website, to a local doc, and to a section heading in the current doc. Here's a footnote [^1].

[^1]: Footnote text goes here.

Tables can look like this:

size material color

9 leather brown 10 hemp canvas natural 11 glass transparent

Table: Shoes, their sizes, and what they're made of

(The above is the caption for the table.) Pandoc also supports multi-line tables:

keyword text

red Sunsets, apples, and other red or reddish things.

green Leaves, grass, frogs and other things it's not easy being.

A horizontal rule follows.

Here's a definition list:

apples : Good for making applesauce. oranges : Citrus! tomatoes : There's no "e" in tomatoe.

Again, text is indented 4 spaces. (Put a blank line between each term/definition pair to spread things out more.)

Here's a "line block":

| Line one | Line too | Line tree

and images can be specified like so:

Inline math equations go in like so: $\omega = d\phi / dt$. Display math should get its own line and be put in in double-dollarsigns:

$$I = \int \rho R^{2} dV$$

$$ \begin{equation*} \pi =3.1415926535 ;8979323846;2643383279;5028841971;6939937510;5820974944 ;5923078164;0628620899;8628034825;3421170679;\ldots \end{equation*} $$

And note that you can backslash-escape any punctuation characters which you wish to be displayed literally, ex.: `foo`, *bar*, etc.

Include Video in the Posts

Tue, 01 Aug 2023 00:00:00 GMT

Just copy the embed code from YouTube or other platforms, and paste it in the markdown file.

---
title: Include Video in the Post
published: 2023-10-19
// ...
---

<iframe width="100%" height="468" src="https://www.youtube.com/embed/5gIf0_xpFPI?si=N1WTorLKL0uwLsU_" title="YouTube video player" frameborder="0" allowfullscreen></iframe>

YouTube

Bilibili

::bilibili{bvid="BV1fK4y1s7Qf"}

NetEase Music

Just use ::music{id="songId"}:

::music{id="531065605"}

Playlist example:

::music{id="7232302652" type="playlist"}

Link Preview Card

::link{href="..."} automatically fetches OG metadata:

::link{href="https://github.com"}