Skip to content

AGENTS.md

Latest commit

 

History

History
238 lines (189 loc) · 11.8 KB

AGENTS.md

File metadata and controls

238 lines (189 loc) · 11.8 KB
Raw

agentdev（原 xlaude）- Claude 实例管理工具

架构设计原则

Worktree 子命令：Git 为核心，State 为 Metadata Layer

适用范围： 此原则适用于 agentdev worktree 下的子命令（merge、delete、list 等）。 Agent 相关功能（如 open）需要依赖 managed metadata（name、agent_alias 等）。

┌─────────────────────────────────────────────────┐
│       agentdev State (Metadata Enrichment)      │
│   name, created_at, task_id, agent_alias...     │
└─────────────────────────────────────────────────┘
                        │ enriches (可选)
                        ▼
┌─────────────────────────────────────────────────┐
│         Git Worktree (Single Source of Truth)   │
│   path, branch, HEAD, repo_root                 │
└─────────────────────────────────────────────────┘

设计思想：

  1. Git 是 worktree 的 single source of truth

    • worktree 的核心信息（path, branch, HEAD, repo_root）来自 git 命令
    • 不依赖 agentdev state 也能获取这些信息

  2. agentdev state 是可选的 metadata enrichment layer

    • 存储 git 不知道的额外信息：name（人类友好别名）、created_at、task_id、agent_alias 等
    • 用于增强显示和管理体验，但不是 worktree 操作的前提条件

  3. worktree 操作应该：

    • 先从 git 获取核心信息（GitWorktree 结构）
    • 可选地从 state 获取 metadata（如果有）
    • 执行操作
    • 如果有 state 记录，执行相应的清理

  4. 好处：

    • merge、delete 等命令可以在任意 git worktree 中使用，不限于 agentdev 管理的
    • 代码更简洁，核心逻辑与 state 管理解耦
    • 更符合 Unix 哲学：做好一件事，与其他工具协作

开发/验证流程备忘

每次完成一轮改动，在向用户同步结果前必须先“自验证”：

  • 把系统真实跑起来。 至少启动一次 UI/后端，务必用后台方式运行：推荐在项目根执行 pnpm run dev:ui，脚本会创建 agentdev_dev tmux 会话，左侧 pane 运行 cargo run --bin agentdev-ui，右侧 pane 运行 pnpm run dev（端口默认 3100，命中 /api/* 时自动转发到 3000 后端）。需要手动查看日志时 tmux attach -t agentdev_dev，收尾时 tmux kill-session -t agentdev_dev。如需自定义端口，可设置 AGENTDEV_BACKEND_HOST / AGENTDEV_BACKEND_PORT / AGENTDEV_FRONTEND_PORT 环境变量。确认新增日志（如 git 报错）包含完整的命令、退出码和 stderr 摘要后，再恢复环境。
  • 走完核心交互。 用 curl、浏览器、Chrome MCP 等方式命中关键 API/页面，确认行为符合预期且没有新增告警。
  • 回归自动化校验。 运行与改动相关的测试/构建（如 cargo test --lib、pnpm run build:frontend）。若加了新脚本，也要记得纳入验证。
  • 清理调试残留。 结束前停掉后台进程、还原环境，避免影响下一次迭代。
  • 同步 UI 观察。 在自测时截图或记录关键页面的视觉状况，如果发现灰度噪点、信息拥挤等明显设计问题，要在提交描述中说明观察结论和后续打算。
  • 先看会话快照。 调试或开发 Sessions 相关功能时，优先查看 tests/fixtures/snapshots/* 里的 snapshot，或者临时运行 cargo test sessions::codex::tests::real_session_tool_events_snapshot 等用例确认数据形态，再接着改 API/UI 逻辑；这份 snapshot 对应 GET /api/sessions/:provider/:session_id?mode=full 返回体中的 events（由 CodexSessionProvider::load_session_events 生成）。
  • 如果要使用 take_screenshot 工具，请带文件名。

没有完成上述验证就交付等同于把不确定的问题留给用户。请把“先自测再汇报”当成整个项目的硬性约束。

最近迭代经验总结

  • Git diff 和 Session 列表改造时先梳理 rg 结果、一次性提炼共享 token/样式表，比逐个替换散落的 bg-gray-* 更高效。
  • apply_patch 多次失败会拖慢节奏，规模较大的替换可以先落库到工具函数/常量，再用脚本或结构化更新减少反复尝试。
  • lint/build 等耗时校验建议在主要改动完成后集中执行，避免在局部调试阶段重复等待 Next.js/Rust 构建。
  • 本地已有常驻 3000/3100 端口时，pnpm run dev:ui 要预先设定随机端口（例如导出 AGENTDEV_BACKEND_PORT=$((RANDOM%1000+3000)) 和 AGENTDEV_FRONTEND_PORT=$((AGENTDEV_BACKEND_PORT+100))）再启动，避免 Next.js 把 API 请求 rewrite 到 404。
  • Dashboard 新增的 merge/delete 入口只是包装 CLI：调试时用 /api/worktrees/<id>/<merge|delete> 的 curl 检查 200/409/404，真测前挑选一次性分支，避免误删主线 worktree。
  • 后端代码若需要调用 CLI，切勿直接用 current_exe() 推断路径；在 agentdev-ui 进程里这会重新启动 UI 进程并返回 HTML fallback。请复用 resolve_agentdev_cli_executable（或设置 AGENTDEV_CLI_BIN）确保命中真正的 agentdev 可执行文件。

本工具已从 xlaude 更名为 agentdev：

  • 可执行文件名：agentdev
  • worktree 相关命令已收敛为二级子命令 worktree（别名 wt）
  • 兼容性：原顶层命令（create/open/delete/…）仍可用，便于平滑迁移

示例映射：

  • agentdev worktree create feature-x（原 xlaude create feature-x）
  • agentdev worktree open feature-x（原 xlaude open feature-x）
  • agentdev ui（原 xlaude dashboard）

下文旧文档中的 xlaude … 用法在过渡期仍有效，推荐逐步迁移到 agentdev worktree …。

核心功能

xlaude create [name]

创建新的 worktree 和分支：

  • 必须在 main/master/develop 分支上执行
  • 如果不提供 name，自动从 BIP39 词库随机选择一个词
  • 创建新分支 <name>
  • 创建 worktree 到 ../<repo-name>.worktrees/<name> 目录
  • 不会自动启动 Claude

xlaude open [name]

打开已存在的 worktree 并启动全局配置的 Agent（默认为 Claude）：

  • 有参数：打开指定的 worktree
  • 无参数：
    • 如果当前目录是 worktree（非 main/master/develop）：直接打开当前 worktree
    • 如果当前 worktree 未被管理：询问是否添加并打开
    • 否则：显示交互式选择列表
  • 切换到 worktree 目录
  • 启动全局配置的 agent 命令（默认：claude --dangerously-skip-permissions）
  • 继承所有环境变量

xlaude delete [name]

删除 worktree 并清理：

  • 有参数：删除指定的 worktree
  • 无参数：删除当前所在的 worktree
  • 检查未提交的修改和未推送的 commit
  • 检查分支是否已完全合并，未合并时询问是否强制删除
  • 需要时进行二次确认
  • 自动删除 worktree 和本地分支（如果安全）

agentdev worktree merge [name]

在主仓中合并 worktree 分支：

  • 默认在主仓尝试把 worktree 分支 fast-forward 合并到默认分支（检测并切换 origin/HEAD 指向的分支，常见为 main）。
  • 运行前会确认 worktree 和主仓都保持干净工作区，避免把未提交改动带入合并。
  • 先 git fetch origin，随后 pull --ff-only 刷新默认分支，再执行 git merge --ff-only <branch>；若需要普通 merge commit，可加 --strategy merge。
  • --push 参数会在成功后立即 git push origin <default_branch>。
  • --cleanup 会在合并成功后调用 agentdev worktree delete 帮你收尾（仍遵守删除命令的安全检查）。
  • --strategy 支持 ff-only（默认）、merge 和 squash。--squash 则是 --strategy squash 的快捷方式，会执行 git merge --squash 并以 Squash merge <branch> into <default> 为提交信息自动提交。

xlaude add [name]

将当前 worktree 添加到 xlaude 管理：

  • 必须在 git worktree 中执行
  • 如果不提供 name，默认使用当前分支名
  • 检查是否已被管理，避免重复添加
  • 适用于手动创建的 worktree 或从其他地方克隆的项目

xlaude list

列出所有活跃的 worktree，显示：

  • 名称
  • 仓库名
  • 路径
  • 创建时间
  • Claude sessions（如果存在）
    • 显示最多 3 个最近的 session
    • 每个 session 显示：最后更新时间和最后的用户消息
    • 超过 3 个时显示剩余数量

xlaude clean

清理无效的 worktree：

  • 检查所有管理的 worktree 是否仍存在于 git 中
  • 自动移除已被手动删除的 worktree
  • 适用于使用 git worktree remove 后的清理
  • 保持 xlaude 状态与 git 状态同步

xlaude rename <old_name> <new_name>

重命名 worktree 状态：

  • 重命名 xlaude 管理中的 worktree 名称
  • 仅更新 xlaude 状态，不影响实际的 git worktree 或目录
  • 检查新名称是否已存在，避免冲突
  • 保留所有 Claude sessions 和元数据

xlaude dir [name]

获取 worktree 的目录路径：

  • 有参数：返回指定 worktree 的绝对路径
  • 无参数：显示交互式选择列表
  • 输出纯路径，无装饰符，便于 shell 命令使用
  • 适用于与其他工具集成（cd、编辑器、zoxide 等）

技术实现

  • 使用 Rust 开发
  • 直接调用系统 git 命令
  • 状态持久化位置：
    • macOS: ~/Library/Application Support/com.xuanwo.xlaude/state.json
    • Linux: ~/.config/xlaude/state.json
    • Windows: %APPDATA%\xuanwo\xlaude\config\state.json
    • Worktree key 格式：<repo-name>/<worktree-name>（v0.3+）
    • 自动迁移旧版本格式到新格式
  • 使用 clap 构建 CLI
  • 使用 BIP39 词库生成随机名称
  • 彩色输出和交互式确认
  • 集成测试覆盖所有核心功能

全局 Agent 配置

agent 字段用于配置启动会话时使用的完整命令行（全局唯一，对 open 和 Web UI 均生效）。

  • 若未设置，默认值为 claude --dangerously-skip-permissions。
  • 配置示例与参考请直接查看首次运行自动生成的 ~/.config/agentdev/config.toml，无需在文档中阅读示例格式。

使用示例

# 在 opendal 项目中创建新的工作分支
cd opendal
xlaude create feature-x  # 创建 ../opendal-feature-x 目录

# 使用随机名称创建
xlaude create  # 可能创建 ../opendal-dolphin 目录

# 打开并启动 Claude
xlaude open feature-x  # 打开指定的 worktree
xlaude open  # 如果在 worktree 中直接打开，否则交互式选择

# 将已存在的 worktree 添加到管理
cd ../opendal-bugfix
xlaude add  # 使用当前分支名作为名称
xlaude add hotfix  # 或指定自定义名称

# 列出所有活跃的实例
xlaude list

# 删除当前 worktree
xlaude delete

# 删除指定 worktree
xlaude delete feature-x

# 清理无效的 worktree
xlaude clean

# 重命名 worktree
xlaude rename feature-x feature-improved

# 典型工作流
xlaude create my-feature  # 创建 worktree
xlaude open my-feature   # 打开并开始工作
# ... 工作完成后 ...
xlaude delete my-feature # 清理 worktree

# 工作完成后的合并
agentdev worktree merge my-feature --push --cleanup

# 直接在当前 worktree 中启动
cd ../opendal-feature
xlaude open  # 自动检测并打开当前 worktree

# 获取 worktree 路径（用于目录切换）
cd $(xlaude dir feature-x)  # 切换到指定 worktree
xlaude dir  # 交互式选择 worktree 并输出路径

# 配合 shell function 使用
# 在 .bashrc/.zshrc 中添加：
# xcd() { cd $(xlaude dir "$@"); }
xcd feature-x  # 快速切换到 worktree

# 与其他工具集成
code $(xlaude dir feature-x)  # 用 VSCode 打开
vim $(xlaude dir feature-x)/src/main.rs  # 编辑文件