Tools

UI / UX Design: pen.dev https://www.pen.dev/
需求管理 & Roadmap: Github Issues & Project
IDE / Editor: Zed w/ Vim https://zed.dev/
Terminal: Ghostty https://ghostty.org/
Agent Multiplexer: Runner (个人 Dogfooding 的项目), Orca (开源项目 https://github.com/stablyai/orca)

UI & UX

这里需要重点介绍的是 pen.dev (之前叫 pencil) 这个工具，目前这是完全免费的。这个工具在 claude opus 以上的模型表现非常完美，尤其如果有一定前端和 UI 设计经验的同学，使用起来非常顺手。从这个工具上，我也学习到了 mcp 在 agent 时代 app 上的正确使用方式，app 更多的展现的是一种 view ，data 的数据格式一定要对 agent 友好，agent 可以通过 mcp 工具来操作底层的 data 结构从而实现 app 上的一些操作。例如，在 pen.dev 上，整体应用的底层数据结构是完全开放的，且 UI 的设计相比 3d 建模，在数据结构上要简单很多，这样开放性的 json 数据结构 + mcp 就能让 agent 更直观的进行设计。

e.g. Runner 项目上的 .pen 设计图: https://github.com/yicheng47/runner/blob/main/design/runner.pen （下载后用 pen.dev 打开；runner-mvp-design.pen 是 MVP 时期的历史画布，runner.pen 是现在的主画布）

IDE / Editor / Terminal

开发工具上，我经历了一次全面的调整。之前开发比较依赖 Jetbrain 的软件，尤其因为大厂的一些工作经验时间比较长，Goland 用的比较多。所以之前整套快捷键都完全习惯了 Jetbrain 生态的编辑器。但是 Zed 1.0 的版本和最近 ai agent 的大幅飞跃让我重新思考了下我应该用什么样的工具来更好的帮助我进行个人项目的开发。

Zed 的以下几个功能是让我最后选择它的原因:

Github Worktree 的解决方案：目前市面上新一代的 editor 上，zed 可能是在 worktree 的支持上做的比较早的，对于多 agent 开发上，worktree 的支持和切换速度非常重要，这也是我 switch 的一个重要原因
轻量化: 在 Agent 时代，debugger 仍然很重要，但是 agent 用 cli 的 debugger 并不比人差，甚至在最新的模型上，agent 的 debug 能力我觉得已经完全超过了我，所以我对
极致的性能和 GPU 渲染: 个人在这个方面有些偏执，对于 editor 的速度要求比较高，且整个项目开源的 GPUI 框架也让我在开发 Runner 项目的过程有很大的收益。
配置的简易程度：这点和 vscode 类似，而且因为现在 agent 可以直接帮我迁移所有的 key mapping json 配置，这一块非常轻松。

Terminal 的选择上我从之前的 iTerm 迁移到了 Ghostty ，这里主要的原因是我对与 Mitchell Hashimoto 和 Zig 语言创始人 Andrew Kelley 的一些崇拜，希望能够支持下。本质上除了渲染性能上的优秀，我觉得核心还是配置的简易化，在 agent 时代一个能够让 agent 编辑的 config 文件是远远优于 UI 上的操作的。

Agent Multiplexer / Orchestrator

Warning: 这里我会打一些 Runner 这个项目的广告

Agent Orchestrator 是最近几个月非常火的一类开源工具，我印象里能想到的就有 cmux, herdr, orca 等，这里所有的工具都在解决多 Agent 并行时代，如何能够更好管理多个 agent 的需求。这里为什么我会再做一个 Runner 的工具呢？主要我想是我能够更加定制化我的整个 workflow ，我希望我的工具和我的 workflow 是完全贴合的，而且我希望能够做一款跨 Agent 的协作工具，可以让开发者可以尝试不同平台的 agent 能力，在日常工作中非常简单的切换 agent runtime ，让整体的工作是 Agent Agnostic 的，不会被一个大的 AI provider 公司所捆绑，这也是我一直以来坚持的一些理想。

那么 Runner 的功能主要有哪些呢：

Multi-Agent Tab Management

这个我其实借鉴的是 Arc Browser 的 tab 页面管理，在我还在大厂的时候，需要处理的琐碎的事情非常多，每个 agent 窗口可能在做很多不同的事情。有几个在 coding ，有几个可能在跑一些 sql 给业务拉数，而且这些长时任务很容易被忘记放在哪里，所以一开始主要支持的是这个能力。

Agent collaboration

在实际的开发过程中，我发现用不同厂商的模型做 peer coding 往往结果是最好的，因为不同模型思考问题的 angle 可能不一样，而且一个全新的 context 在 review 的过程中往往能发现更多的问题。所以我需要一个能力可以对不同 agent 进行组队，合作完成一个 loop ，这个可能就是最近比较火的 loop / graphic engineering 的概念。

在 Runner 里面，我们会先定义一些 worker ，再将这些 worker 进行编队组成一个 crew ，crew 中每个 worker 之间的沟通会通过一个内置的 cli 写入一个本地的 NDJSON 文件，每个 agent 会自己维护一个 offset 来记录自己独到哪里了。这样就基本实现了跨 session 的 agent 沟通，有了这个机制以后，agent 的本地合作链路就被打通了，后续 crew 的编队就主要靠使用者的想象力了。

MCP Self Drive

使用过程中，我发现每次手动去编辑队员和组队会非常麻烦，所以参考了 pen.dev 的概念，我给整个 app 加了 mcp server ，这样就可以让一个主要的 agent 来用 mcp 创建 crew ，针对队伍发起任务，这样 Runner 这个软件更多变成了一个 agent sandbox ，给这些 agent 创造了一个合作的环境，并且给人更好的可视化体验，之前 TUI 里面的 sub agent 有一个很大的问题，我觉得就是在 TUI 的可视化上有比较多的局限，让人很难明白每个 subagent 在做什么。

Project Structure

Repo: https://github.com/yicheng47/runner

runner/
├── AGENTS.md            # 所有 coding agent 共用的 repo 指南； CLAUDE.md 只是指向它的 symlink
├── CLAUDE.md -> AGENTS.md
├── README.md
├── LICENSE              # GPL-3.0
├── Cargo.toml           # workspace
├── Makefile / make.cmd  # make run / verify / fmt / clippy ； Windows 用 make.cmd
├── rust-toolchain.toml
├── crates/
│   ├── runner-app/      # GPUI 应用本体：终端渲染、sidebar 、mission 界面、平台 UI (macOS / Windows)
│   ├── runner-backend/  # UI 无关的核心：SQLite 、session manager 、event bus 、router 、MCP server
│   ├── runner-core/     # 共享的 event-log 原语
│   └── runner-terminal/ # 终端模型 (alacritty_terminal)、输入编码、fixture 语料
├── cli/                 # 内置的 `runner` CLI ，spawn 出来的 agent 用它读写 NDJSON 事件
├── design/              # Pencil 设计源文件，runner.pen 是当前主画布
├── docs/                # 见下文
├── examples/            # 示例 crew：peer-coding 、dev-crew 、docs-crew 、werewolf…
├── assets/              # 图标、字体、README 截图
├── packaging/           # Sparkle / Windows updater 公钥
├── script/              # bundle-mac 、bundle-windows.ps1 、nightly 校验脚本
├── tests/               # 集成测试 fixtures
└── .github/workflows/   # ci.yaml 、nightly.yml 、release.yml

几个原则：AGENTS.md 是唯一的 agent 指南，CLAUDE.md 只做 symlink ，避免两份规则漂移；后端 runner-backend 完全不依赖 UI ，所以上一次前端整体重写时它一行没动；cli/ 和 runner-core 是 app 和 agent 之间的协议层，两边共用。

项目结构上比较关键的是 doc directory 的结构，这里我分享下我的，非常类似 wiki 的管理，主要的目的还是尽量给 Agent 减少不需要的 token 消耗

docs/
├── README.md               # 目录约定：什么放哪、什么时候归档
├── product/
│   └── vision.md           # 为什么做、哪些 surface 重要
├── arch/
│   ├── arch.md             # 系统现在是怎么工作的；能沉淀的决策都在这里
│   └── windows.md
├── features/               # 进行中的 feature spec ；文件名前缀 = GitHub issue 号
│   ├── README.md           # 索引：每个 spec 一句话 + issue 链接 + Dropped 列表
│   ├── 73-runner-skills.md
│   ├── 403-mission-worktree-isolation.md
│   ├── 510-remote-ssh-session.md
│   ├── …
│   └── archive/            # 已上线的 spec (01-archived-tab.md … 505-…)，文件名不变
├── impls/                  # 实现计划：spec 说 what ，impl 说 how + 怎么验证
│   ├── README.md           # Active / Archive 索引
│   ├── gpui-rewrite/       # 技术栈迁移的 program record
│   │   ├── README.md       # 压缩后的记录：时间线、仍然生效的决策、GPUI 规则、教训
│   │   └── m6-remainder.md
│   ├── local-skills/
│   │   ├── README.md
│   │   ├── plan.md
│   │   └── impl_log.md
│   └── archive/            # 已完成的 plan 、mission brief
│       ├── 0001-v0-mvp.md … 0045-codex-trust-preseed.md
│       └── gpui-rewrite/{plan.md, impl_log.md, m4-surface-inventory.md, briefs/…}
└── tests/                  # 人工 smoke test 清单

这套结构里省 token 的几个点：

目录本身就是状态。 features/ 和 impls/ 里只放还在生效的文档，上线或者被取代就整体移进 archive/，文件名不变。Agent 只需要 ls 一下就知道现在什么是活的，不用读完每一篇再判断。归档前把还有价值的决策先挪进 arch/，历史文档就不需要再被翻。
每个目录一个 README 当索引。 features/README.md 每条一句话加 issue 链接，agent 先读索引再决定要不要打开正文，大部分时候索引就够了。
编号 = GitHub issue 号。 spec 先开 issue 再命名，文件名、issue 、PR 三边互相能找到，agent 不需要额外的映射表。
impl 里有"Current state"和"standing rules"。 像 gpui-rewrite/README.md 这种长期项目的记录，开头永远是一段最新状态，中间是仍然生效的决策和踩过的坑（ GPUI 的几条硬规则）。每次开新 mission ，brief 只引用这一段，不用把整个 log 喂给 agent 。

Workflow

这里就拿我最近做的一个"Agent Orchestrator / Multiplexer" 项目为例

普通需求迭代 (Agent 完全闭环)

这类需求非常类似在大厂工作做的日常需求，整体需求完全能够 agent 自闭环。如果涉及到一些小的 UI 调整，需要人工在 .pen 的设计稿上进行确认，后续在人工 smoke test 上进行 confirm 。

大型需求 (e.g. 技术栈迁移)

Example：Tauri → GPUI 的前端重写，program record 在 https://github.com/yicheng47/runner/blob/main/docs/impls/gpui-rewrite/README.md ，完整的 plan.md / impl_log.md / mission brief 在 https://github.com/yicheng47/runner/tree/main/docs/impls/archive/gpui-rewrite

这一类大型的项目重构非常依赖前期的项目规划，需要保证在每个 phase 阶段都可以有人工的 checkpoint 来保证项目不会走歪，所以对于 planning 的要求比较高，在拆解完之后，可以并行的任务就可以提交到 Runner 的 peer coding 队伍进行执行，一个单独的 agent 负责解决 merge conflict 和多个 mission 之间合作的问题。

总结

以上就是我最近几个月 Agent 使用的一些心得啦，大家如果觉得有用的话，可以支持下我的个人项目 https://github.com/yicheng47/runner , 感谢

Agent 时代的独立开发经验分享