Lorenzo Feng

用手机指纹批准 sudo —— 自建 PAM 认证工具 FingerKey

Fri, 11 Sep 2026 00:00:00 GMT

在Agent请求sudo的时候，我之前一直让他使用pkexec，但是这样每天都要重复几十次的操作。密码冗长、容易输错，在 sudo -S 脚本里处理密码管道也需要格外谨慎。我一直希望有一个像手机解锁一样流畅的方案：手机在手边，指纹一按，命令即放行。

于是我写了 FingerKey：一个 PAM 认证模块 + 本地 daemon + Android app。安装之后，sudo、pkexec、SSH 登录，乃至任何经过 PAM 的认证，都会把请求推送到手机，用 BiometricPrompt 弹出指纹验证，批准则放行，拒绝则回退到密码。整个过程不依赖任何云服务。

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

动机：为什么要再写一个认证工具

Linux 桌面上想免密码提权，现有的方案我都不太满意：

硬件密钥（YubiKey 一类）需要额外购买、随身携带，遗失后恢复成本高；
fprintd 依赖笔记本内置的指纹传感器，桌面台式机大多不具备，驱动兼容性也参差不齐；
云端方案 意味着认证请求要离开内网、经过厂商服务器，这是我难以接受的。

手机几乎是人人都有、随身携带的设备，指纹识别技术也已经相当成熟。它和电脑通常处于同一个局域网。把"批准"这个动作放到手机上，等于免费得到了一台"第二因子"设备，无需购买任何新硬件。

工作原理：一条请求的旅程

FingerKey 由三个部分组成：

组件	语言	作用
`fingerkeyd`	Go	本地 daemon，持有待批准会话、签发 nonce、校验签名
`pam_fingerkey.so`	C	PAM 认证模块，创建会话并等待手机决策
FingerKey app	Flutter	扫码配对、钉住证书指纹、弹出指纹验证

三个组件之间的连接关系：

flowchart LR
    sudo[pkexec / sudo] -->|PAM| PAM[pam_fingerkey.so]
    PAM -->|unix socket| D[fingerkeyd daemon]
    CLI[fingerkey CLI] -->|unix socket| D
    D -->|TLS / mDNS| App[FingerKey app]

一次 sudo 的完整流程如下：

sequenceDiagram
    participant PAM as PAM 模块
    participant D as daemon (fingerkeyd)
    participant Ph as 手机 app

    PAM->>D: 创建会话 (root-only unix socket)
    Note over D: 32 字节随机 nonce + user/service/tty
    D-->>Ph: 推送 pending (TLS 4443)
    Ph->>Ph: BiometricPrompt 指纹验证
    Ph->>D: decision (Ed25519 签名)
    D->>D: 校验签名
    D-->>Ph: decision-result
    D-->>PAM: 成功 / 失败

PAM 配置中，auth sufficient pam_fingerkey.so 这一行放在 @include common-auth 之前。sufficient 的语义是：批准即跳过后续认证；其他任何结果（拒绝、超时、手机不可达）都会自动回退到正常的密码流程。因此 FingerKey 永远不会把系统锁死。

安全设计：凭什么信任手机

这是整个项目里我投入最多精力的部分。核心原则是：不信任网络，只信任密码学。

证书指纹 pinning，而不是 CA。 daemon 持有一张自签名的 ECDSA P-256 证书，手机在配对时记录这张证书的 SHA-256 指纹（小写十六进制）。此后每次连接，手机都会拒绝任何指纹不符的服务器。没有 CA 可以被攻破，也没有公网 DNS 可以被劫持——局域网内不持有私钥的机器无法冒充 daemon。

决策使用 Ed25519 签名，且不可重放。 手机签名的字节序列是：

"phone-fprint-auth/v1" || 0x00 || action || 0x00
  || u8len(user) || user || u8len(service) || service || u8len(tty) || tty
  || nonce

nonce 是一次性的 32 字节随机数，会话 60 秒后过期，且用户/服务/终端上下文都被绑定在签名中。因此即使攻击者截获了某个批准报文，也无法用它重放给另一个请求。

密码永不传输。 认证的三个环节——PAM 模块、daemon、手机——都不会接触你的密码。daemon 上只保存公钥，手机私钥留在手机本地。即便 daemon 被攻破，也无法获得任何能签出"批准"的凭据。

默认快速回退。 如果没有已配对的手机、或手机未连接，daemon 直接返回 503，PAM 立即回退到密码提示，而不是等待 60 秒。这条设计从一开始就确定了：宁可回退到密码，也不把系统锁死。

几个有意思的取舍

不依赖任何云。 电脑和手机通过局域网 TCP/TLS 直连，服务发现使用 mDNS（_phonefprint._tcp），由 daemon 内置，无需 Avahi 之类的额外依赖。整个系统没有出网流量。
用 PAM 而非 hook sudo。 PAM 是 Linux 认证的统一入口，一个模块即可覆盖 sudo、pkexec、su、login、sshd、桌面登录管理器等所有 PAM 服务，无需为每个工具单独打补丁。
daemon 运行在非 root 用户下。 它以 phonefprint 系统用户运行（无 home、nologin），unix socket 为 root-only 的 0700，只有 root 或 setuid-root 的 PAM 模块能够创建会话。

现状与用法

项目已经开源（MIT），首个版本 v0.1.0 已发布。CI 使用 GitHub Actions：推送一个 v* 的 tag，即自动编译 Linux 二进制和 Android APK，并发布到 Release 页面。

安装非常直接：

# 从源码装（Ubuntu/Debian）
sudo ./scripts/install.sh

# 打印配对二维码
sudo fingerkey pair-qr my-phone

# 手机装 app-release.apk，扫码配对，然后随便跑个 sudo 试试
sudo true

配对之后，每次提权手机都会弹出指纹验证框，显示请求来自哪个用户、哪个服务、哪个终端。批准则放行，拒绝或超时则回退到密码。

结语

这个项目的意义在于，它把三个截然不同的技术栈结合在了一起：C 编写的 PAM 模块、Go 编写的并发 daemon、Flutter 编写的安卓 app，中间通过一条自定义的 TLS 帧协议衔接。如果它对你有用，欢迎 star、试用、提交 issue；如果你对某个设计细节感兴趣，仓库里的 README 和 threat model 有详细的说明，代码也配备了完整的单元测试和一套无需真机的端到端测试脚本。

afk —— 通过邮件回复 opencode，人不在电脑前也能让 agent 继续干活

Sat, 05 Sep 2026 00:00:00 GMT

一句话核心

afk（Away From Keyboard，离开键盘）是一个 OpenCode 插件。它的用法可以概括成一句：在终端输入 /afk 表示「我离开屏幕了」，此后运行中的 agent 一旦遇到需要你拍板的决策，就会把问题通过邮件发给你；你在任何地方回复邮件，会话就会自动唤醒继续——全程不需要回到终端。

到 v0.1.2，它已经不止「一个决策工具」这么简单了。除 request_decision 之外，还多出了三样东西：

notify_user：agent 达成关键结论时主动单向邮件同步给你，不打断它的工作；
/new：回复邮件派发一个全新任务，在项目目录里开出新会话；
停顿自动通知：agent 停下一段时间后自动邮件告知进展，不再依赖它「记得」发通知。

仓库：7emotions/afk，MIT 协议，npm 包名 opencode-afk。

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

项目里到底有什么

仓库的入口和分层很清晰，先看根目录文件：

文件	作用
`index.js`	插件入口（轻量客户端）：确保守护进程运行、启动 SSE 订阅、暴露 `request_decision` / `notify_user` / `set_email_mode`
`daemon.js`	每台机器一个的监听守护进程
`request-decision.js`	`request_decision` 工具的实现
`notify.js`	`notify_user` 单向结论通知工具的实现
`mailer.js`	共享邮件内核：root 会话解析、`[omo:…]` 路由令牌打标、SMTP 发送
`config.js` / `messages.js`	配置加载（含环境变量覆盖）/ 可见文案 i18n 表
`install.js`	一键安装器
`core/`	`watcher.js`（IMAP IDLE）、`process.js`（扫描→解析→持久化）、`reply-parse.js`、`new-session.js`（`/new` 派发）、`pause-notify.js`（停顿通知）、`inject.js`、`subscribe.js`
`store/`	`pending-store.js`、`mode-store.js`、`registry.js`、`uid-cursor.js`
`command/`	`/afk` 与 `/back` 命令模板
`test/`	单元测试套件 + 连真实邮箱的集成脚本

依赖只有五个：@opencode-ai/plugin、@opencode-ai/sdk、imapflow、mailparser、nodemailer（外加 node ≥18）。没有 MCP、没有外部服务。

使用方式

插件给 agent 暴露了两个邮件工具，外加一个模式开关：

request_decision(subject, question, { context, options, recommendation })
notify_user(subject, message)

request_decision：需要人类决策时调用。仓库自带的 AGENTS.md 写明了契约——如果返回「邮件模式已关闭」的消息，说明人正在屏幕前，改用 OpenCode 内置的 question 工具在对话里问；否则邮件已发出，agent 应当停下并结束当前回合，等回复被注入。
notify_user：agent 达成关键结论（任务完成、重大发现、里程碑）时调用。它是单向 FYI，不暂停 agent 的工作，也不占「每会话一个未决决策」的槽位；邮件同样带路由令牌，你回复它也会作为反馈注入回会话。

关键设计是默认不发邮件：是否发邮件由一个持久化的全局开关控制（守护进程里的 mode.json，默认 "off"）。用户通过两条命令切换：

命令	作用
`/afk`	调用 `set_email_mode(mode: "on")` —— 打开邮件模式，之后 agent 的决策会发邮件
`/back`	调用 `set_email_mode(mode: "off")` —— 关闭邮件模式，恢复在对话里提问

语义上是一个人要么在屏幕前、要么不在：这个状态全局唯一，不按会话区分。模式改动会立刻通过 SSE 的 mode 事件推送给所有已连接的实例。

从邮件派发新任务（`/new`）

这是 v0.1.2 之前完全没有的能力。回复任意一封 afk 邮件（决策或通知均可），正文以 /new 开头：

/new 修复登录页在 Safari 上的样式错位

效果是：它不会把这段文字注入你回复的那个会话，而是在那个会话所在的项目目录里开出一个全新的会话，以 /new 后的文字作为首个任务。同一目录若开着多个 opencode 实例，先抢到广播的那个创建；你会收到一封带新会话 token 的确认邮件，回复它就相当于直接跟新会话对话。一个裸 /new（没有任务文字）则会被当作普通回复注入原会话。

停顿自动通知

这是「防漏通知」的机制保障：core/pause-notify.js 监听 opencode 的 turn-end 事件，当 agent 完成一波工作、安静下来一段时间后，会自动发一封邮件告诉你当前进展——不再依赖 agent 自己记得调用 notify_user。这封邮件同样带 [omo:…] 令牌，回复它就能让 agent 继续。

安装

推荐走 npm：在 ~/.config/opencode/opencode.jsonc 的 plugin 数组里加一行：

"plugin": [
  "opencode-afk@latest"
]

重启 opencode 时会自动从 npm 安装 @latest。首次安装后，把 config.example.json 复制成稳定的用户级配置：

mkdir -p ~/.config/opencode
cp <插件目录>/config.example.json ~/.config/opencode/afk.json

配置放在 opencode 配置目录（而非插件目录），这样每次 @latest 更新重装插件后配置依然存活。维护者发新版后，你只需重启 opencode，@latest 自动跟进。

README 顶部也提供了一种「复制粘贴给 LLM」的安装方式：

Install and configure the afk plugin by following the instructions here:
https://raw.githubusercontent.com/7emotions/afk/main/INSTALLATION.md

手动/源码安装则是：

git clone https://github.com/7emotions/afk
cd afk
node install.js
# 然后编辑 ~/.config/opencode/plugins/afk/config.json，填上 imap/smtp 凭据和 recipient

node install.js 会完成五件事：把源码复制到 ~/.config/opencode/plugins/afk/（跳过 node_modules、.git 和密钥/运行时文件）；跑 npm install --omit=dev；由 config.example.json 生成 config.json（绝不覆盖已有配置）；在 ~/.config/opencode/opencode.jsonc 中注册插件（注释保留式文本插入，不做 JSON.parse）；把 /afk、/back 命令复制到 ~/.config/opencode/command/。

需要填写的配置字段：

字段	含义
`imap.host/port/secure`	读取回复的 IMAP（默认 `imap.qq.com:993`）
`imap.user/password`	IMAP 凭据（QQ 邮箱用授权码当密码）
`smtp.host/port/secure`	发送决策邮件的 SMTP（默认 `smtp.qq.com:465`）
`smtp.user/password`	SMTP 凭据
`recipient`	决策邮件收件人，默认 `smtp.user`
`allowList`	允许注入其回复的发件人白名单，默认 `[smtp.user]`
`folder`	监听的邮箱文件夹，默认 `INBOX`

配置解析的优先级是：AFK_CONFIG 环境变量 → ~/.config/opencode/afk.json（稳定用户级配置）→ 插件目录下的 config.json（旧路径兜底）。所有连接相关字段也都可以用 AFK_* 环境变量覆盖（AFK_IMAP_HOST、AFK_SMTP_PASSWORD、AFK_RECIPIENT 等，优先级高于配置文件）。注意：早期版本这些变量叫 EMAIL_WAKE_*，仓库重命名后统一改成了 AFK_* 前缀。

核心架构：单一监听守护进程 + PUSH 投递

flowchart TB
    subgraph instances["opencode instances — thin client plugins"]
        A["instance A<br/>ensure daemon · SSE subscriber · request_decision"]
        B["instance B<br/>ensure daemon · SSE subscriber · request_decision"]
        dots["... N instances"]
    end

    subgraph daemon_box["afk DAEMON — one process (atomic single-instance)"]
        D["HTTP endpoints<br/>/health · /events · /claim · /ack · /pending · /register · /mode"]
        W["the only IMAP IDLE watcher<br/>+ catch-up scan"]
        P["pending-store<br/>durable replies (pending.json)"]
        M["mode-store<br/>durable global mode (mode.json)"]
    end

    A --> D
    B --> D
    D --> W
    D --> P
    D --> M
    D -. SSE push .-> A
    D -. SSE push .-> B

这张架构图把整体结构画得很清楚：一台机器上只运行一个守护进程（daemon.js），它持有共享邮箱唯一的 IMAP IDLE 监听器；每个 OpenCode 实例只加载轻量客户端插件（index.js），插件负责确保守护进程在跑、并建立一条 SSE 流。守护进程解析邮件、持久化、通过 SSE 推送给实例；实例自检属主、抢占 claim，在进程内完成注入。

守护进程提供这些 HTTP 端点：/health、/events、/claim、/ack、/pending、/register、/mode。它绑定固定端口（默认 4100），端口绑定本身就是原子的单实例锁：两个实例同时启动守护进程时只有一个能 bind 成功，输家拿到 EADDRINUSE 安静退出。插件探测 /health 无响应时，会启动一个分离的守护进程并轮询直到它健康就绪。

完整流程用 README 里的时序图可以看得更细：

sequenceDiagram
    participant Agent
    participant Plugin
    participant Daemon
    participant Human

    Agent->>Plugin: request_decision(subject, question)
    Plugin->>Daemon: GET /mode
    alt mode is "off"
        Plugin-->>Agent: refuse → "use the question tool"
    else mode is "on"
        Plugin->>Daemon: POST /register {rootSessionID}
        Plugin->>Human: SMTP "[omo:rootSessionID] subject"
        Note over Agent: STOPS and ends its turn (pauses)
        Human->>Daemon: reply email (reply prefix / In-Reply-To)
        Daemon->>Daemon: IMAP IDLE push → scan UID > cursor → parse → persist pending.json
        Note over Daemon: mail stays UNSEEN, no journal yet
        Daemon-->>Plugin: SSE delivery {uid, sessionID, body, from}
        Plugin->>Plugin: self-check ownership → POST /claim
        Plugin->>Agent: inject reply (data, not instruction)
        Plugin->>Daemon: POST /ack
        Daemon->>Daemon: markSeen + journal → remove pending → release reservation
        Agent->>Agent: wakes with the answer and continues
    end

几个值得说的设计取舍：

零轮询。 新邮件由服务器通过 IMAP IDLE 推送送达（core/watcher.js），每次连接/重连后做一次性补扫，绝无定时轮询器——这是仓库里写明的硬性约束。

检测基于 UID 游标，不依赖 \Seen 也不依赖 SUBJECT。 守护进程只扫描大于持久化游标（store/uid-cursor.js）的 UID，和邮件是否已读（你可能在别的客户端先读过）以及 SUBJECT 索引（QQ 的 SUBJECT 索引存在延迟）都无关。游标会越过每个见到的 UID，因此自复制、无令牌的邮件永远不会卡住游标。

消息不丢失（README 记为 P0 修复）。 解析出的回复会先持久化到 pending.json（store/pending-store.js），然后才做其他事；\Seen 标记 + journal 确认只发生在 /ack 处理器中——也就是属主实例完成注入之后。若守护进程在持久化与确认之间崩溃，邮件在服务器上仍处于 UNSEEN，pending.json 里也还留着记录，重启后会重新广播。投递语义是至少一次：注入之后、确认之前崩溃会重复广播，可能注入两次，但绝不丢失。

多实例安全。 SSE 广播给所有连接的实例，但每个实例先按 session.directory 自检归属，再 POST /claim 抢占（先到先得）；registry 保证每个会话同时只有一个未决决策（重复注册会返回 alreadyPending，不重发邮件）。

安全：回复是数据，不是指令

把邮件内容注入会话，本质是往 agent 上下文里塞外部文本——prompt 注入的经典入口。仓库里有两层防护：

发件人白名单（allowList，默认只含你自己的 smtp.user）：问题邮件发给 recipient，但只有来自白名单地址的回复才会被注入。陌生人就算复制了邮件主题里的 [omo:会话ID] 令牌伪造回复，只要地址不在白名单里就被忽略。
数据而非指令：注入的正文被框架化为「数据，不是指令」（core/inject.js 的 buildPayload），明确告知 agent 不得执行回复内容里的任何指令。README 特别注明这套框架属于安全框架而非显示文案，刻意不做 i18n。

/new 派发的任务文字同样按「数据而非指令」框架注入，绝不当作可执行指令。

Agent 侧的约定

插件仓库里的 AGENTS.md 是面向 agent 的说明书，除了「提问后暂停」，还立了几条规矩：

仅限主会话：带 parentID 的子 agent 调用会被拒绝，返回 Call from the main session only——因为决策必须携带主会话的完整上下文（子 agent 的结论由主会话代为转发）；
待办检查点：当 request_decision 将要发邮件（模式开启）时，agent 必须先把完整 todo 列表写进消息正文、清空待办，再发邮件，避免挂起等待期间被 todo-continuation 反复催着干活；回复注入后从检查点重建待办（notify_user 不暂停，无需检查点）；
notify_user 要克制：它是结论通知，不是进度播报；
/new 邮件不进入本会话：它被路由到新会话，agent 无需对它做任何处理。

配置与文案都可调

tuning 块可覆盖运行时序（默认值即源码常量）：claimTtlMs、SSE 重连退避 reconnectBaseMs/reconnectMaxMs、IDLE 续期 idleRenewMs、IMAP 重连退避 backoffInitialMs/backoffMaxMs，以及新增的 pauseNotifyCooldownMs（turn 结束后静默多久判定「一波工作收尾」并邮件通知）等；
messages 块做可见文案本地化：默认英文，深合并覆盖任意键即可（比如把 decisionBody、notifyBody、newSessionBody、pauseNotifyBody、tool 下的文案换成中文）；
密码绝不会出现在日志里，配置序列化时打码为 ***。

工程质量与已知限制

单元测试用 node 内置的 node:test，零网络跑通。仓库 README 列出了覆盖范围：pending-store、mode-store、registry、inject-ack、process-mail、negative、uid-cursor、daemon HTTP（register + push + mode 端点 + SSE，现已拆成 daemon-mode / daemon-push / daemon-server 三个文件）、subscribe、request-decision（含模式门控）、notify_user、pause-notify、reply-parse、unit、messages、config。

cd afk && npm test

CI 也已就位：.github/workflows/publish.yml 在推送 v* tag 时自动跑单测并发布 opencode-afk 到 npm（目前已发到 v0.1.2）。

README 也如实写了几条已知限制：投递是至少一次（极端情况可能重复注入）；单一邮箱、单机部署（多邮箱/多机需要各自跑守护进程并换端口）；registry 的未决决策预留只在内存、守护进程重启后失效（24 小时 TTL 是唯一清理机制）；IMAP/SMTP 默认值面向 QQ 邮箱，其他服务商要自己配 host/port。

小结

afk 解决的问题很具体：agent 异步化之后，人不在屏幕前，它该怎么问决策问题、怎么汇报进展。答案是把它邮件化，再用「单守护进程 + IMAP IDLE 零轮询 + UID 游标 + SSE 推送 + pending 持久化 + ack 确认」这一套组合把「人回复 → 会话唤醒」这条链路做得可靠，同时用白名单和数据非指令框架堵住邮件注入这个安全口子。

短短几个版本，它从一个「决策邮件工具」长成了一个更完整的离屏协作入口：决策靠 request_decision，进展靠 notify_user 和停顿自动通知，派活靠 /new。如果读者经常让 agent 挂后台跑、自己又不在电脑前，可以试一下：输入 /afk 出门，回来时 agent 往往已经带着你的邮件答复把活干完了。

仓库地址：7emotions/afk，欢迎试用和提 issue。

打断后台 Subagent 后，如何找回它的输出 —— 开发 recovering-subagent-output

Fri, 28 Aug 2026 00:00:00 GMT

一句话核心

在使用 OpenCode 派发后台 subagent 时有个经典痛点：如果我打断了后台任务，前台的 primary agent 就看不到 subagent 的输出。我在排查这个问题的过程中发现了一个反直觉的事实——subagent 的输出从来没有丢过，它一直在 OpenCode 的 SQLite 数据库里，只是前台的 agent 没去查。

于是我把这个发现做成了一键恢复的技能：

::github{repo="7emotions/recovering-subagent-output"}

背景：后台任务协议

OpenCode（以及基于它的 OhMyOpenCode）的后台任务有一个标准协议：

launch bg_xxx → 结束回合 → 等 <system-reminder> → background_output(bg_xxx) 取回结果

这个协议在不被干扰时工作得很好。但一旦打断，链路就断了：

回合被 abort——新回合的上下文里没有上一回合派发的 bg_ 任务 ID；
通知协议断裂——primary agent 不知道"有结果待取"；
即使拿到 ID 调 background_output，被取消的任务也只返回元数据（状态表 + 原始 prompt），没有内容。

结果就是：后台 subagent 明明跑出了东西（甚至在你打断前已经产出了一大段），前台却表现为"看不见"。

调查：输出到底存哪了

直觉告诉我：UI 上能看到 subagent 的输出，说明它一定被持久化了。顺着这个思路，我在 ~/.local/share/opencode/ 里找到了主存储 opencode.db（一个 11GB 的 SQLite）。

数据结构非常清晰：

表	作用
`session`	所有会话；`parent_id` 列把 subagent 挂到主会话下
`message`	每个会话的消息
`part`	每条消息的每个部分：`text` / `reasoning` / `tool` / `step-start` / `step-finish`

关键在 part 表：工具调用（type=tool）的完整输出存在 state.output 里，即使命令被用户中止，中止元数据也在。我实测了一个被打断的 bash 调用：

{
  "type": "tool",
  "tool": "bash",
  "state": {
    "status": "completed",
    "input": { "command": "sleep 30" },
    "output": "(no output)\n\n<shell_metadata>\nUser aborted the command\n</shell_metadata>"
  }
}

所以真相是：打断不丢数据，一切都在库里。真正的问题是前台 agent 不知道去哪查、用什么 ID 查。

顺带挖出的 opencode task 机制

在开发这个技能的过程中，我读了 OpenCode 1.18.25 的源码（packages/opencode/src/tool/task.ts），发现两种派发模式有完全不同的打断语义——这也解释了之前观察到的所有"矛盾"。

前台 vs 后台：两种模式

	前台 `run_in_background=false`	后台 `run_in_background=true`
行为	阻塞等待 subagent 完成，返回最终结果	立即返回，完成后 system-reminder 通知
打断前台时 subagent	被取消	继续运行
取消机制	`ctx.abort → ops.cancel(subagent)`	无 abort 连线

前台模式的核心源码——这就是"打断前台也会打断 subagent"的原因：

// 前台等待期间，前台 abort 信号直接取消 subagent
function onAbort() {
  runCancel.fork(cancel)
}
// 释放阶段：若前台被中断，显式取消任务
if (Exit.hasInterrupts(exit))
  yield* Effect.all([cancel, background.cancel(nextSession.id)])

而后台模式没有这套连线——subagent 是解耦的独立任务（BackgroundJob），前台中断与它无关，它会一直跑到完成。要真正停掉后台任务，只能走 UI 的取消按钮或 background.cancel。

注：bg_ 任务 ID 和 background_output / background_cancel 工具是 oh-my-openagent 插件层在 OpenCode 原生 BackgroundJob（job ID 即 session ID）之上的包装。后台模式需要 OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true。

实测对照

我做了四组对照实验验证这套语义：

派发模式	前台中断后	最终结果
后台 · tick 循环（180 tick）	无人打断	跑完 180 tick（3m3s）
后台 · 长作文（8000 字）	打断前台	继续跑完 10,860 字
后台 · tick 循环（300 tick）	打断前台	继续跑完 300 tick（5m4s）
前台 · 长作文（8000 字）	打断前台	立即停住，断在句子中间，部分输出完整可读

最有力的一次是前台模式的长作文测试：作文断在"人类对秩序的需要植根于存在"——一个未写完的句子，证明打断确实在写作中途掐断了它，而前面的约 1600 字全部可以通过技能完整读回。

解决方案：恢复技能

理解了存储结构，解决方案就很简单了：不需要预先记住任务 ID——subagent 会话通过 parent_id 天然挂在主会话下，打断后按 parent_id 一查就能枚举出自己派发的全部 subagent。

-- 1. 枚举我的所有 subagent
SELECT id, title FROM session WHERE parent_id = '<我的会话ID>';

-- 2. 读某个 subagent 的完整输出（含工具调用）
SELECT data FROM part WHERE session_id = '<subagent ID>' ORDER BY time_created;

技能封装了四个命令：

S=~/.agents/skills/recovering-subagent-output/scripts/recover-subagent.py

python3 $S list                          # 当前会话的全部 subagent + 状态标记
python3 $S read <session_id>             # 完整 transcript，含每次工具调用的 stdout/stderr
python3 $S search <关键字>               # 按标题找会话
python3 $S --session <parent_id> list    # 指定父会话

状态检测逻辑：工具输出含 User aborted → aborted（被中止）；会话无 step-finish 收尾 → cut-off（中途截止）；正常结束 → completed。

使用场景

打断后台任务后捞回部分输出——前台 agent 在全新回合（没有 bg_ ID）里，用 list 枚举 → read 拉回打断前的全部内容；
审计 subagent 干了什么——任何 subagent 会话的完整工具调用记录（含命令和输出）都在库里，可离线排查；
多任务协调——派发多个后台任务后按 parent_id 统一枚举、逐个取回，不依赖完成通知；
调试 OpenCode 自身行为——part 表里存了 reasoning、step 生命周期，可用于理解 Agent 的决策过程。

小结

这个技能的开发过程本身也是一次"Agent 调试 Agent"的实践：问题出在 agent 的上下文协议上，答案藏在 agent 自己的数据存储里，最终用一把 SQLite 查询把它变成了一键恢复的能力。如果你也遇到过"后台任务输出不见了"的困惑，希望这个技能和这份 task 机制分析能帮到你。

仓库地址：7emotions/recovering-subagent-output，MIT 协议，欢迎使用和提 issue。

agent-sudo v2 —— 从 Python 到 C++ 的全量重写

Wed, 24 Jun 2026 00:00:00 GMT

昨天用 Python + PySide2 发布了 agent-sudo 的初始版本。queue + flush 模式跑通了，一个下午从零到能用的原型，挺有成就感。

但今天再回头看，代码组织、性能、分发都存在明显的天花板。于是我通宵把它全量重写了一遍。

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

为什么重写

v1 用 Python 做原型是刻意的选择——半天写完、能跑、能演示。但在昨天发完博客后，几个问题开始变得明显：

依赖地狱。用户需要安装 PySide2，而这个包在某些发行版上根本装不上（Qt5 的 Python binding 与系统 Qt 版本不兼容、PyPI wheel 不覆盖某些架构）。一个"零配置"的工具，安装第一步就先卡住。

分发沉重。Python 脚本意味着用户必须有一个完整的 Python 运行时，且路径需要符号链接到 /usr/local/bin。Agent 调用时可能切换了虚拟环境或者 PATH 混乱，导致 agent-sudo 根本找不到。

GUI 组件拼凑。PySide2 的 API 是命令式的，每增加一个组件都要在 __init__ 里塞一大堆 QPushButton、QLineEdit、connect 语句。随着 60 秒倒计时、LLM 输入区、主题切换、危险标注这些功能加进来，main.py 膨胀到了六百多行，维护成本直线上升。

Python 自身的限制。ctypes.memset 清零密码是一个运行时操作，编译器无法静态保证它一定被执行。多线程的密码管道读写（写入 sudo 的 stdin 后关闭写端让 sudo 读到 EOF）在 Python 里需要精心处理 QThread 和 closeWriteChannel 的时序关系，容易写出竞态。

重写目标

目标	说明
零运行时依赖	编译成单个 ELF 二进制，不依赖 Python 或任何解释器
类型安全	C++ 编译期类型检查，消除 category 错配、信号/槽类型不对等 bug
声明式 UI	用 creeper-qt 声明式组件库替代命令式 PySide2，UI 结构即代码结构
模块化	拆分 main.cc（511 行）与 gui/ 下的独立模块，每个模块职责单一
Qt6 原生	使用 Qt6 的 Widgets、Network、Svg、Multimedia 模块，不再受 Qt5 兼容限制
可审计	编译选项可见、构建脚本可复现、产物可校验

架构变化

v1 是一个 main.py 单文件。v2 拆分成了清晰的模块结构：

src/
├── main.cc                  # argv[0] 分派 + creeper-qt 声明式 UI
├── gui/
│   ├── command_card.{h,cc}  # 命令卡片构建器（含危险检测）
│   ├── ring_countdown.{h,cc}# 36×36 环形倒计时
│   ├── icon.{h,cc}          # Material Icons + 应用 SVG
│   ├── sound.{h,cc}         # QSoundEffect 声音管理器
│   ├── theme_transition.{h,cc} # ColorScheme 平滑插值
│   ├── queue_io.{h,cc}      # JSON 队列/历史 I/O
│   ├── executor.{h,cc}      # sudo 子进程执行器
│   └── tr.h                 # JSON 驱动 i18n

UI 层没有从零手写 Qt6 Widget 代码，而是基于一个优秀的声明式组件库：

::github{repo="creeper5820/creeper-qt"}

creeper-qt 把 Qt 的命令式 Widget 构建转换为声明式的嵌套组件树——窗口、卡片、按钮、输入框的层级关系直接对应代码的嵌套结构。主题系统（3 套预设 + 亮暗模式切换）和 MixerMask 展开动画也直接由 creeper-qt 的 ThemeManager 和 TransitionValue 驱动，不需要自己写一帧帧的过渡逻辑。

感谢 @creeper5820 的优秀工作，src/gui/creeper-qt/ 为 vendored 源码，遵循 MIT 许可。

单二进制通过 argv[0] 检测实现分派：调用 agent-sudo 走入队逻辑，调用 agent-sudo-flush 走弹窗逻辑，两者是同一个 ELF 的符号链接。Agent 不需要关心这是 Python 还是 C++ —— agent-sudo --reason "..." -- <cmd> 的行为完全不变。

新技术栈

维度	v1 (Python)	v2 (C++23)
语言	Python 3.8+	C++23 (GCC 14+)
GUI	PySide2 (Qt5)	creeper-qt + Qt6
构建	`pip install`	CMake 3.22+
依赖	PySide2, Python	Qt6, Eigen3, CMake
产物	`.py` 脚本 + 符号链接	单个 ELF 二进制
密码清零	`ctypes.memset`	`std::fill` + `clear()`
i18n	硬编码中文	8 语言 JSON 驱动

v2 新增功能

在重写过程中，借着架构的灵活性顺手加了不少新功能：

危险检测。每条命令自动分析字符串内容并标注安全等级：常规 apt install 标绿色 ✓，systemctl stop/kill/chmod 标黄色 ⚠，rm -rf/dd if=/mkfs 标红色 ✕。纯字符串匹配，不需要 Shell 解析，但 Agent 无法绕过标注。

主题系统。3 套预设配色（BlueMiku/GoldenHarvest/Green）+ 亮/暗模式。切换时 ColorScheme 平滑插值动画，不是硬切。点击窗口右上角的调色板图标就能轮换，设置自动写入 ~/.config/agent-sudo/theme.conf。

声音反馈。4 种事件音效（窗口打开/10 秒警告/执行成功/审批拒绝），每个事件可独立设为 default/none/自定义 WAV。QSoundEffect 实现，不依赖外部播放器。

多语言。8 种语言（zh/en/ja/ko/fr/de/es/pt），JSON 驱动。中文为内置默认，其余通过 Qt 资源文件加载。翻译条目覆盖所有 UI 文案，包括危险检测的等级标签和按钮文字。

Material Icons。用 Material Icons Round 字体渲染所有图标（codepoint 引用），不再依赖系统图标主题。自定义应用 SVG 图标用于窗口标题栏和任务栏。

倒计时暂停。60 秒倒计时增加暂停/恢复按钮，人在来不及操作时可以暂停计时器。

10 秒警告。倒计时最后 10 秒触发警告音效，提醒人尽快操作。

认证失败处理。自动检测中文和英文的 sudo 密码错误提示，失败后清空队列并返回退出码 126，不重试。

输出过滤。执行结果自动过滤 [sudo] 和 sudo: 噪音行，Agent 收到的输出更干净。

构建与安装

cmake -S . -B build && cmake --build build
sudo cp build/agent-sudo-flush /usr/local/bin/
sudo ln -sf /usr/local/bin/agent-sudo-flush /usr/local/bin/agent-sudo

编译依赖 GCC 14+、Qt6（Widgets/Network/Svg/Multimedia）、Eigen3、CMake 3.22+。产物是单个约 490KB 的二进制文件，无动态链接的 Python 依赖。

对于不想自己编译的用户，INSTALL.md 提供了预编译二进制下载和安装步骤。

结语

v2 重写熬了一整夜，核心动机不是"Python 不够好"，而是"这个工具已经到了需要独立分发的阶段"。C++ 的单二进制分发、编译期类型安全、以及 creeper-qt 的声明式 UI 模式，让代码的组织和维护都上了一个台阶。

Python 原型仍然有价值——它在半天内验证了 queue + flush 模式的可行性。没有这个原型，v2 不可能在一个通宵内完成。但到了需要独立安装、独立运行、独立交付的阶段，C++ 是更自然的选择。

项目以 MIT 协议开源在 GitHub，欢迎试用和反馈。

agent-sudo —— AI Agent 特权命令的批量审批工具

Tue, 23 Jun 2026 00:00:00 GMT

在日常使用 OpenCode 等 AI Agent 平台时，Agent 经常需要执行需要 root 权限的操作：安装依赖包、管理系统服务、修改系统配置文件。这些操作无法由 Agent 直接完成，需要人类介入审批。

Linux 桌面环境的标准方案是 pkexec，它通过 PolicyKit 为每条特权命令弹出独立的确认对话框。这个机制在手动执行单条命令时没有问题，但在 Agent 工作流的场景下存在明显的效率问题：Agent 的一个任务可能需要五条甚至更多的 sudo 命令，而 pkexec 会为每条命令弹一次对话框，每次都需要人类查看、判断、输入密码。重复的打断不仅拖慢了工作进度，也增加了人在多条相似对话框中做出错误判断的风险。

为此我写了 agent-sudo。

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

设计

agent-sudo 采用 queue + flush 模式。Agent 在需要特权时将命令逐条排入队列，所有命令收集完毕后，一次性提交给人类审批。

# Agent 将需要的特权命令排入队列，每条附带理由
agent-sudo --reason "安装编译工具链" -- apt install -y gcc make cmake
agent-sudo --reason "创建 /opt/app 目录并设权限" -- install -m 0755 -d /opt/app
agent-sudo --reason "启动 nginx 服务" -- systemctl enable --now nginx

# 全部排完后，一次性提交审批
agent-sudo-flush

agent-sudo-flush 会弹出一个 PySide2 原生 Qt5 窗口，集中展示队列中的所有命令。每条命令旁标注了 Agent 添加的 --reason，人类可以在一个窗口中查看全部待审批命令的上下文，勾选需要执行的，取消不需要的，然后输入密码一次执行。

工作流时序：

sequenceDiagram
    participant Agent
    participant agent-sudo
    participant Human

    Agent->>agent-sudo: agent-sudo --reason "..."
    Note over agent-sudo: 写入 queue.json
    Agent->>agent-sudo: agent-sudo --reason "..."
    Note over agent-sudo: 追加 queue.json

    Agent->>agent-sudo: agent-sudo-flush
    Note over agent-sudo: 读取 queue.json
    agent-sudo->>Human: 弹出 PySide2 GUI
    Note over Agent: [阻塞等待]

    Note over Human: 查看命令、勾选/取消
    Note over Human: 输入 sudo 密码
    Human->>agent-sudo: 点击执行

    Note over agent-sudo: 执行 sudo 命令
    Note over agent-sudo: 写入 history.json
    agent-sudo-->>Agent: 退出码
    Note over Agent: 继续工作

与 pkexec 的对比

	agent-sudo	pkexec
审批模式	所有命令集中在一个窗口	每条命令独立弹窗
命令上下文	每条命令附带 `--reason` 说明	仅显示命令本身
选择性执行	支持，可单独取消不需要的命令	逐条只能接受或拒绝
历史记录	`history.json` 记录每次审批详情	仅 syslog
超时处理	60 秒无操作自动拒绝，有暂停按钮	PolicyKit 默认超时机制
配置要求	零配置，能运行 sudo 即可	依赖 DBus + PolicyKit
密码处理	通过 stdin 传递，内存中用完即清零	由 PolicyKit agent 管理

sudoers 白名单方案则需要预先用 root 权限编辑 /etc/sudoers 文件，将允许的命令列表写入。Agent 的需求是动态的，每次新增命令类别都需要修改 sudoers，且语法错误可能导致 sudo 不可用。对于 Agent 工作流中频繁变化的权限需求，白名单的维护成本较高。

安装

git clone https://github.com/7emotions/agent-sudo.git ~/agent-sudo
pip install PySide2
sudo ln -sf ~/agent-sudo/src/main.py /usr/local/bin/agent-sudo
sudo ln -sf ~/agent-sudo/src/main.py /usr/local/bin/agent-sudo-flush

依赖 Python 3.8+、PySide2，需要有图形会话环境（$DISPLAY 非空）。完整步骤见 INSTALL.md。

结语

agent-sudo 解决的是 AI Agent 工作流中一个具体的效率问题：将多条特权命令的审批从多次中断合并为一次集中决策。它不替代 sudo，而是在 Agent 和 root 权限之间增加一层全局视角的审批环节。

项目以 MIT 协议开源，欢迎试用和反馈。

三个开源项目，同一套骨架 —— open-design、open-slide、OpenMontage 的架构分析

Tue, 23 Jun 2026 00:00:00 GMT

最近我花了两天时间，把 GitHub 上三个名字带「Open」的项目——open-design、open-slide、OpenMontage——的仓库、文档、commit 历史和外部评论翻了个遍。它们表面上看毫不相干：一个做设计原型，一个做幻灯片，一个做视频制作。但剖开来看，它们的底层架构几乎是同一套骨架。

更值得注意的是，这套骨架在不到半年的时间里，被至少六个独立项目以不同形式重新发明了一遍。这不是巧合——这是问题空间的结构性约束导致的必然收敛。

三个项目，同一套骨架

先把这三个主角摆出来：

项目	GitHub	Stars	领域	创建时间
open-design	`nexu-io/open-design`	69k+	设计原型 / UI / 幻灯片 / 视频	2026.4.28
open-slide	`1weiho/open-slide`	5.4k+	React 幻灯片框架	2026.4.26
OpenMontage	`calesthio/OpenMontage`	6.5k+	端到端视频制作	2026.3.29

它们的描述里都有一个关键的共同句法——「把你的 AI 编程助手（Claude Code / Codex / Cursor）变成 X」：

open-design：把你的 coding agent 变成设计引擎
open-slide：把你的 coding agent 变成幻灯片作者
OpenMontage：把你的 coding agent 变成视频制作工作室

它们自己都不包含 AI。 它们是一个运行时、一组工具、一套指令——AI 是外部调用的，是用户自己选的。

这是一个根本性的架构选择。如果你在做一个「AI 设计工具」，你会在代码里调用 GPT-5 或者 Claude Opus。但这类项目的工作是给 agent 准备好画布、管线、质检关卡和领域知识，然后告诉它：「这里有一切你需要的，开始吧。」

三层知识体系：不是设计选择，是结构必然

把三个项目的目录结构叠在一起看，你会发现它们不约而同地把知识分成了三层：

Layer 1: 工具层（What exists）
  → 工具注册表、能力矩阵、成本、回退策略
  → OpenMontage: tools/tool_registry.py（52 tools）
  → open-slide: @open-slide/core（Vite 插件、canvas、present mode）
  → open-design: daemon + 16 个 CLI adapter

Layer 2: 领域层（How WE use it）
  → 管线约定、阶段定义、导演 skill、质量关卡
  → OpenMontage: skills/pipelines/*/（stage director skills）
  → open-slide: /slide-authoring（1920×1080 canvas、type scale、palette）
  → open-design: 259+ skills（可组合设计工作流）

Layer 3: 供应商层（How the TECHNOLOGY works）
  → 原始 API 规则、prompt engineering、参数优化
  → OpenMontage: .agents/skills/（供应商特定的 prompting）
  → open-slide: AGENTS.md 硬规则（不添加依赖、只用 React+Web API）
  → open-design: DESIGN.md 品牌系统（colors、typography、components）

这三层有一个严格的读取顺序依赖。Agent 必须先发现有什么工具（Layer 1），再理解这个项目怎么用它们（Layer 2），最后才能精确调用底层 API（Layer 3）。跳过任何一层，输出质量就会急剧下降。OpenMontage 的文档直接警告：

「Layer 3 不是可选的。每一个生成工具都有一个 agent_skills 字段指向它的 Layer 3 skill。一个通用 prompt 和一个 skill-informed prompt 之间的差距，就是『能用』和『电影级』之间的差距。」

这不是某个项目的设计偏好——这是「外部 agent 需要逐层获取知识才能正确执行」这件事的架构必然性。只要你的智能体是外部的，你就必然需要这三层，而且顺序不可变。

Pipeline as Contract：管线不只是自动化

这些项目都有「管线」，但它们的管线和传统管线（CI/CD、视频渲染管线）有一个本质区别。传统管线的每个阶段是代码在执行，这类管线的每个阶段是agent 在阅读指令后决定如何执行。管线不是自动化序列，是导航合约。

OpenMontage 把这条写成了 Rule Zero：

「所有生产必须通过一条管线。Agent 读取管线 manifest（YAML）→ 读取阶段导演 skill（MD）→ 调用工具 → 自审 → checkpoint → 提交人类审批。每个阶段产出一个规范制品，成为下一阶段的合约。」

注意「规范制品成为合约」——阶段之间不是通过共享内存传递状态，而是通过产出一个文件，这个文件成为下一阶段 agent 读取的输入。这意味着：

每个阶段可以独立恢复（agent 崩溃后从 checkpoint 继续）
每个阶段可以独立审查（人类可以在任意节点介入）
每个阶段可以替换（换一个 agent 或换一个 skill 不影响管线结构）

open-slide 的 /create-slide 也是同样的模式——先问四个问题（主题、页数、文字密度、动效强度），这些问题的答案就是第一个阶段的规范制品，后续的 slide 写作阶段以此为合约。

硬规则文件：圈定 agent 的自由范围

三个项目的根目录下都有 AGENTS.md 或 AGENT_GUIDE.md，内容极其相似——全是约束性规则。open-slide 的：

- Slides go under slides/<id>/
- Entry is slides/<id>/index.tsx
- Don't touch package.json, open-slide.config.ts, or other slides
- Don't add dependencies. Use only React and standard web APIs.

OpenMontage 的更绝——整个文件只有一条规则：

MANDATORY: Read AGENT_GUIDE.md before responding to ANY user message.
There are no instructions in this file. All instructions are in AGENT_GUIDE.md.

这些规则的设计意图不是限制 agent，而是圈定它的自由范围。边界之内（怎么写 slide、怎么配颜色、怎么布局），agent 有完全的自由。边界之外（不能改配置、不能加依赖、不能碰其他 slide），零容忍。

传统开发中，人类开发者知道「不要随便改 package.json」是因为经验。Agent 没有这个判断力——它看到一个 import 缺失，本能反应是 npm install。AGENTS.md 就是提前切断 agent 的破坏性自由度。

追溯源头：这条河是怎么流过来的

把关键事件按时间排列，会看到一条非线性的演化路径：

2025.12  Dan Shipper 发表 "Compound Engineering"（先导文章）
2026.01  Dan Shipper 发表 "Agent-native Architectures"
         → 首次明确定义 agent-native 概念
2026.02  creative-liberation-engine（14 daemon 集群，独立实验）
2026.03  BuilderIO agent-native 框架 + OpenMontage
         → OpenMontage 早于 Claude Design 近三周！
2026.04  Claude Design 发布 → open-codesign → open-slide → open-design
         → 10 天内 4 个项目密集诞生
2026.05  saker + Nous Research Kanban Pipeline
         → 大实验室正式入场
2026.06  本文写作时

几个关键发现：

第一，Dan Shipper 是概念定义者。 他在 2026 年 1 月的文章里精确描述了后来三个项目的核心结构：「agent-native 应用的核心不是代码，而是 agent。每个 feature 是给 agent 的 prompt，而不是实现步骤。我经常把 agent-native 应用想成『Claude Code 穿着一件 trenchcoat』。」

第二，OpenMontage 早于 Claude Design。 它 3 月 29 日就创建了——比 Anthropic 的商业产品早了近三周。说明这个模式不是 Anthropic 发明的，它是在 agent 能力到达临界点后自然涌现的。

第三，Claude Design 是商业引爆点。 它 4 月 17 日发布，次日 open-codesign 就出现了。10 天内，三个开源替代品（open-codesign、open-slide、open-design）密集诞生。这不是社区对 Anthropic 的模仿，这是社区对「封闭 + 单模型锁定」的结构性反弹。

第四，大实验室已经入场。 Nous Research 在 5 月发布了 Kanban Video Pipeline——一个基于 Hermes Agent 的多 agent 视频制作管线，Director/Cinematographer/Renderer/Editor 四个 profile 通过结构化 handoff 协作。架构上和 OpenMontage 完全同构，只是执行拓扑从单 agent 顺序变成了多 agent profile 并行。

市场正在验证：两个不可调和的分叉

在我翻阅的外部评论中，R2ClickThrough 的一篇分析（2026.4.29）意外地抓住了关键：

「两个克隆（open-codesign 和 open-design）的架构截然不同，这种差异就是整个故事。open-codesign 捆绑了一个特定的 AI 运行时；open-design 的 web app 和 daemon 只是一个薄的协调层，agent 是你 PATH 上已经有的任何东西。」

这标志着「捆绑派」和「委托派」的路线分裂：

	捆绑派（open-codesign）	委托派（open-design）
Agent 提供方式	内置固定	PATH 扫描，自适应 16 种 CLI
升级成本	等上游发布	零——新 CLI 出现即自动支持
调试难度	低（单一组合）	中（多 agent 兼容）
长期风险	agent 绑定	薄层可能被大厂吸收

R2ClickThrough 的判断：「当 Cursor 明天发布更好的模式，你免费获得。当 Gemini CLI 新增一个工具，OD 在下一次 daemon 启动时自动获取。没有 agent 需要升级，因为这个项目从未拥有过一个 agent。」

open-design 用 40k star 在三周内的增长曲线来支撑这个论断——市场显然认可「委托优于捆绑」。

六个正在形成的识别特征

把 open-design、open-slide、OpenMontage、saker、Noustiny、creative-liberation-engine 六个项目放在一起，可以提炼出一组识别特征。如果一个新项目同时满足这六条，它就在这个模式里：

Agent as Runtime — AI 是外部调用方，项目不内嵌模型。指令文件是第一公民，代码工具退居第二
Three-Layer Knowledge — 工具层 → 领域层 → 供应商层，顺序读取，Layer 3 不可跳过
Pipeline as Contract — 管线是 agent 的导航合约，阶段间通过规范制品传递状态
Shared Actions — UI 和 Agent 操作同一套 actions，对称而非叠床架屋
Built-in Self-Review — 质检内建在管线每个阶段，agent 不自审就无法 checkpoint
Hard Rules for Agent — AGENTS.md 定义 agent 的操作边界：边界内完全自主，边界外零容忍

生态已经在动了

过去两个月的几个信号：

Skill 可移植性成为现实：OpenClaw 发布了 OpenMontage 插件——纯 Markdown skill 包，零 JS 代码，跨 agent 平台运行
跨项目技能互操作协议出现：Skills Interoperability Protocol（SIP）定义了四种组合模式（Layered / Pipeline / Handoff / Advisory）和冲突解决优先级链
Figma 感受到压力：2026 年 5 月发布 Figma Design Agent on-canvas，首次把 agent 直接放进画布
a16z 的 2026 大预测：在 2025 年 12 月的 "Big Ideas 2026" 中，将 "Agent-native infrastructure becomes table stakes" 列为第一个预测

这个品类还缺一个共识的名字。Dan Shipper 叫它「agent-native architecture」，BuilderIO 叫它「agent-native application」，a16z 叫它「agent-native infrastructure」——共同的关键词是 agent-native。但它已经在六个项目、四篇文章、两家投资机构的论述中出现了，正在从现象变成共识。

接下来会发生什么

基于目前的分析，我做出四个预测，供半年后回来看：

第三波领域扩张：音频/音乐制作（"OpenStage"）和 3D/游戏资产（"OpenFrame"）是最自然的下一站。不是会不会出现，而是谁先出现。
跨 Runtime 的 Pipeline Manifest 标准：12 个月内会出现一套类似 Docker Compose 的管线描述语言，让一个 YAML 文件能在 OpenMontage、saker、open-design 之间迁移。
大厂的路线选择：Anthropic 和 OpenAI 目前都在做「单次调用优化」，离「12 阶段管线 + 自审 + checkpoint」有显著距离。但如果他们把 pipeline-level orchestration 做进 MCP 协议，独立 runtime 的架构优势可能被吸收。
平台与垂直的博弈：open-design 的 69k star 代表平台的势能，OpenMontage 的 12 条专业管线代表垂直的深度。最终大概率形成「一个平台 + 多个垂直 skill 生态」的结构——就像 VS Code 和它的扩展市场。

相关仓库：

::github{repo="nexu-io/open-design"}

::github{repo="1weiho/open-slide"}

::github{repo="calesthio/OpenMontage"}

::github{repo="BuilderIO/agent-native"}

::github{repo="NousResearch/hermes-agent"}

这是一篇分析文章，不是评测。如果你正在选择用哪个工具开始做 AI 驱动的创意生产，我建议从 open-design 开始（平台最全），然后用 OpenMontage 做视频（管线最深），用 open-slide 做技术演示（React 生态最顺滑）。三个都用同一个 coding agent，你的 agent 会自己学会切换上下文。

给 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上。

Lorenzo Feng

用手机指纹批准 sudo —— 自建 PAM 认证工具 FingerKey

动机：为什么要再写一个认证工具

工作原理：一条请求的旅程

安全设计：凭什么信任手机

几个有意思的取舍

现状与用法

结语

afk —— 通过邮件回复 opencode，人不在电脑前也能让 agent 继续干活

一句话核心

项目里到底有什么

使用方式

从邮件派发新任务（/new）

停顿自动通知

安装

核心架构：单一监听守护进程 + PUSH 投递

安全：回复是数据，不是指令

Agent 侧的约定

配置与文案都可调

工程质量与已知限制

小结

打断后台 Subagent 后，如何找回它的输出 —— 开发 recovering-subagent-output

一句话核心

背景：后台任务协议

调查：输出到底存哪了

顺带挖出的 opencode task 机制

前台 vs 后台：两种模式

实测对照

解决方案：恢复技能

使用场景

小结

agent-sudo v2 —— 从 Python 到 C++ 的全量重写

为什么重写

重写目标

架构变化

新技术栈

v2 新增功能

构建与安装

结语

agent-sudo —— AI Agent 特权命令的批量审批工具

设计

与 pkexec 的对比

更多细节

安装

结语

三个开源项目，同一套骨架 —— open-design、open-slide、OpenMontage 的架构分析

三个项目，同一套骨架

三层知识体系：不是设计选择，是结构必然

Pipeline as Contract：管线不只是自动化

硬规则文件：圈定 agent 的自由范围

追溯源头：这条河是怎么流过来的

市场正在验证：两个不可调和的分叉

六个正在形成的识别特征

生态已经在动了

接下来会发生什么

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

为什么不能用配置文件

TUI 插件的 Slot 机制

插件目录结构

插件代码

颜色配置

ASCII 艺术字生成

注册插件

总结

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

AgentEnv 是什么

缺失的拼图

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

实现计划

为什么这个方向是正确的

寻找合作者

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

问题的本质

设计哲学

声明式，不拼凑

可重现，版本锁定

六种源，不分来源

六种包，各司其职

四个框架，一套流程

事务性激活，不留下残局

从邮件派发新任务（`/new`）