clickvibe
DSH web 插件:右侧面板先选择已配置的 GitHub repo,再按依赖、状态和里程碑浏览全部 open issue；每个 issue 由 git/GitHub 硬事实推导唯一下一步动作,可创建独立 worktree 并启动 Codex/Claude 开发。
功能
- 侧栏底部 ClickVibe 按钮(窄栏显示 "CV")开关右侧面板
- 项目选择器读取
~/.clickvibe/config.yaml 的全部 repo 映射,路径不在本机的跨机器配置也保留在列表
- 选中项目后展示全部 open issue,支持按里程碑或依赖状态分组、按依赖就绪/阻塞过滤
- 每行展示状态徽章、约定分支、落后提示、milestone、blockedBy 与唯一动作；点开后进入完整详情
- blockedBy 门槛:有 OPEN 依赖时,「开始/恢复开发」替换为「被 #N 阻塞」(禁用);review/返工/合并等已开发流程不受影响
- 就绪优先排序:组内按 就绪(未开发+依赖OK)→ 开发中 → 阻塞 → 已交付 排列,同档按编号;一眼看到能下什么单
- Host 半通过
gh issue view / gh pr view 抓取,返回结构化 JSON
- Client 半渲染:
- 状态徽章(Open / Closed / Merged)、编号、作者、创建/更新/关闭/合并时间
- labels、assignees、milestone
- PR 额外:分支
base ← head、变更统计、提交数、合并状态
- 正文与评论:轻量 Markdown 渲染器(标题/粗斜体/代码块/列表/引用/链接),评论默认展开
- 整块内容区一个滚动条(GitHub 风格)
- 权威状态视图(#5):每次请求实时推导
- 三方对比:worktree / main / 远端(origin/main、远端同名分支)的哈希与 ahead/behind
- worktree 落后远端时提示「需要同步」并提供 /sync 动作(fetch + merge origin/main,冲突自动回滚)
- review 结论标注它审查的 HEAD;HEAD 变化后自动显示「结论已过期」,不冒充当前状态
- 任意时刻只有一个「下一步动作」按钮(开发/恢复/同步/创建 PR/Review/返工/合并),由 git 事实推导,workflow 文件只做增强
- PR 状态每次从 GitHub 查询；merged 立即进入已交付终态,查询失败则 fail-closed,不沿用旧的合并按钮
- Open issue 一键开发:
Codex 开发 / Claude 开发:在 issue worktree 中启动非交互 agent安全演练:走完整 worktree/任务/轮询链路,只执行 pwd、当前分支和 git status- 真实 Agent 启动只接受本机回环、同源且带专用请求头的请求；服务端冻结面板已展示的完整 Issue 快照,签发两分钟内一次性授权,启动时不再重新抓取 Issue
- 日志按完整行、cursor 增量轮询；服务端与面板最多保留 2000 行,持久日志也有大小上限,超出时明确提示截断
- Agent 最长运行 10 分钟,面板可主动停止；完成任务延迟回收,任务表本身有总量上限
- 已有正确 worktree/分支会复用；缺分支、缺 worktree 或 detached 等半完成状态会安全恢复
- 创建或修复缺失分支前先
git fetch origin --prune,并显式从 origin/HEAD(兼容回退 origin/main)创建,不继承配置仓库当前 HEAD
- 冲突分支或未注册的非空目录不会被覆盖
架构
| 半侧 | 文件 | 职责 |
|---|
| Host | src/index.ts | 注册 /clickvibe/api 前缀路由,处理 GitHub 抓取、开发任务和 cursor 日志轮询 |
| 开发内核 | src/develop.ts | agent/URL 校验、shell 参数转义、有界行日志和 worktree 恢复决策 |
| 状态视图 | src/state-view.ts | 纯函数 deriveNextAction:由 git 事实 + 事件历史推导唯一下一步动作 |
| Client | src/client/index.tsx | shell.overlay 项目优先面板 + sidebar.footer.action 开关按钮；项目 issue 列表、筛选/分组、详情和唯一动作 |
| 构建 | tsdown.config.ts | host → lib/index.js(ESM),client → lib/client.js(CJS 闭包,window.__ModuleLoader__.load 注册) |
Client→Host 走 HTTP API 路由(正式插件没有动态插件的 harness.handle),这是与原型最大的结构差异。
设计文档
核心设计原则:判断只依赖 git/GitHub 硬事实(客观、保证存在),workflow 文件与 comment meta 只是增强器——允许缺失,缺失时走降级链,永不因缺 meta 卡死,也永不因缺判据瞎猜。
Agent 启动参数(显式,不依赖机器配置)
ClickVibe 启动 agent 的命令行按次显式传参,不读取也不假设目标机器的全局配置(#11 跨机器可移植):
- claude:
--dangerously-skip-permissions
- codex:
-c approval_policy=never -s danger-full-access(新会话)/ -c 'sandbox_mode="danger-full-access"'(resume 子命令无 -s,用 -c 覆盖)
进行中(open issues)
- #16 实时输出 TUI 化 + detach 放大 + 运行时长 + token 用量
- #17 超时/中断后会话恢复(会话 id 捕获 + resume 命令形式)
- #18 任务超时上限可配置,支持小时级长任务
- #20 提示词统一:各阶段自带需求快照
- #22 review 结论解析器支持 JSON 格式
- #23 合并后清理(worktree/分支/issue/workflow)
开发
pnpm install
pnpm run build # tsc 声明 + tsdown 双 bundle
pnpm test # Host 纯逻辑回归测试
pnpm run watch # client 热更新
一键开发配置
配置文件固定为 ~/.clickvibe/config.yaml：
repos:
ai-daming/clickvibe: /Users/me/work/clickvibe
worktreeRoot: ~/.clickvibe/worktrees
仓库按 owner/repo 精确匹配。目标路径为 <worktreeRoot>/<仓库目录名>/<仓库目录名>-issue-<N>，分支名为 <仓库目录名>-issue-<N>。
安装到 profile
dsh plugin --profile web add link:/Users/yinwm/work/clickvibe
- client 半改动:硬刷新浏览器(⌘⇧R)即可
- host 半改动:重启
dsh web
验证
# host 路由
curl -X POST http://127.0.0.1:3080/clickvibe/api/projects \
-H 'content-type: application/json' -d '{}'
curl -X POST http://127.0.0.1:3080/clickvibe/api/repo/issues \
-H 'content-type: application/json' \
-d '{"repoKey":"ai-daming/clickvibe"}'
curl -X POST http://127.0.0.1:3080/clickvibe/api/fetch \
-H 'content-type: application/json' \
-d '{"url":"https://github.com/cli/cli/issues/100"}'
# client bundle
curl http://127.0.0.1:3080/plugins/clickvibe/client.js
# 启动无代码副作用的 dry-run
curl -X POST http://127.0.0.1:3080/clickvibe/api/develop \
-H 'content-type: application/json' \
-d '{"url":"https://github.com/ai-daming/clickvibe/issues/1","agent":"dryrun"}'
# 同步 worktree 到远端基线(fetch + merge origin/main,冲突自动回滚)
curl -X POST http://127.0.0.1:3080/clickvibe/api/sync \
-H 'content-type: application/json' \
-H 'origin: http://127.0.0.1:3080' \
-H 'x-clickvibe-request: 1' \
-d '{"url":"https://github.com/ai-daming/clickvibe/issues/5"}'
# 用启动响应中的 taskId 和 poll 响应中的 cursor 增量轮询
curl -X POST http://127.0.0.1:3080/clickvibe/api/develop/poll \
-H 'content-type: application/json' \
-d '{"taskId":"dev-...","cursor":0}'
任务状态只保存在当前 Host 进程内,重启后旧 taskId 失效。真实 Agent 必须从面板发起:面板先把当前显示的完整 Issue 快照交给服务端比对,再展示 Agent、更新时间、评论数和快照摘要供确认；确认后的授权只能使用一次且会过期。dryrun 不需要高权限授权、不启动 Agent,适合用 curl 验证配置、worktree 恢复和增量轮询。
不要把 ClickVibe 暴露到局域网或公网。服务端会拒绝非回环来源的 Agent 操作,但同一操作系统账号下的恶意进程本来就可能读取代码、配置和开发凭据,本工具不把同账号进程隔离当作安全边界。
