w workspace-cli

需求开发空间 · 多 repo · git worktree

workspace-cli

把一个需求涉及的多个 Git 仓库集中到同一个 workspace 中，用统一 feature 分支完成跨仓库开发，再把多个 ready 需求集成到 release 分支并发布到 base branch。

查看源码 一键安装 
$ workspace req create "支付链路优化" \
  --key pay-flow \
  --repo backend \
  --repo frontend

pay-flow  ~/.workspace-cli/work/requirements/pay-flow

$ workspace dev pay-flow --tool codex
$ workspace ide pay-flow
$ workspace req finish pay-flow -m "feat: complete pay-flow"
$ workspace release create "2026-07-01 发布" --key 2026-07-01 --req pay-flow
$ workspace release integrate 2026-07-01
$ workspace release publish 2026-07-01 --tested

为跨仓库需求开发而生

workspace-cli 的 workspace 不是单个代码仓库，而是围绕一个需求临时组织起来的开发空间。它负责把多个 repo 拉进同一个目录，保持统一 feature 分支，在需求完成时进入 ready 状态，并把多个 ready 需求集成到 release 分支后发布到 base branch。

多 repo
一个需求绑定多个仓库
统一分支
默认 feature/<req-slug>
本地优先
SQLite + Git worktree

install

复制一行命令安装最新版本

安装脚本会识别 macOS/Linux 和 CPU 架构，从 GitHub latest release 下载对应包，校验 checksum 后安装 `workspace`。 

curl -fsSL https://idefav.github.io/workspace-cli/install.sh | sh

默认安装到 /usr/local/bin。用户态安装可使用 INSTALL_DIR="$HOME/.local/bin"。

completion

启用 Shell 自动补全

workspace-cli 可以为 bash、zsh、fish 和 PowerShell 生成补全脚本。安装后执行对应命令，把脚本写入 shell 的 completion 目录。

zsh

mkdir -p "$HOME/.zsh/completions"
workspace completion zsh \
  > "$HOME/.zsh/completions/_workspace"
exec zsh

fish

mkdir -p "$HOME/.config/fish/completions"
workspace completion fish \
  > "$HOME/.config/fish/completions/workspace.fish"

workflow

从需求开发到 Release 发布

01

注册仓库

把需要管理的 Git repo clone 为本地 bare repo，记录 remote、base branch 和 URL。

02

创建需求

选择多个 repo，创建统一 feature 分支，并把 worktree 集中到同一个需求目录。

03

进入开发

使用 Codex、Claude Code 或 IDE 从需求 workspace 启动，围绕同一个需求修改多个仓库。

04

完成为 ready

全部 repo feature 分支 push 成功后再删除需求 worktree，失败时保留现场并允许 finish 重试。

05

集成测试

选择多个 ready 需求，删除并重建 release 分支，按顺序合入 feature 分支后测试。

06

发布归档

测试确认后把 release 合并到每个 repo 的 base branch，发布成功的需求进入 completed 并归档。

AI Native workflow

从需求到发布的自主研发闭环

主 Agent 负责和用户对话、分配专业 Agent 并观察全局状态；分析、Coding、测试 Worker 在受控 workspace 中自主执行。所有过程写入状态事件、Run 和 Artifact，遇到需求澄清、方案定稿、权限提升、测试命令或发布确认时暂停等待用户决定。

协调

主 Agent

理解用户目标，分配 Agent 和 Review policy，汇总状态并发起人工确认。

执行

专业 Worker

分析、Coding、测试 Agent 按角色 claim Job；不同需求可并行，同一 worktree 串行。

控制

用户

实时查看事件，补充需求，选择方案终稿，处理阻塞并确认最终发布。

可靠性

daemon

维护队列、lease、heartbeat、重试和异常收敛，主 Agent 退出后仍可继续调度。

待采纳→ 分析循环→ 分析定稿→ 开发循环→ 集成测试→ Bug 修复→ 发布
01

pending_acceptance → pending_analysis

提交、采纳与分配

用户用 req submit 登记目标、验收标准、优先级和涉及仓库。主 Agent 检查信息是否足够，为需求选择分析、Coding、测试 Agent 及 Review 门槛；口径不明确时创建 approval，用户回复后原 Job 原子恢复。

自动动作
观察新需求、校验配置、分配专业 Agent
人工门禁
采纳、范围澄清、风险与验收标准确认
02

analyzing → analysis_completed

需求分析与方案 Review Loop

分析 Agent 生成需求设计和技术设计，随后独立 Review；不满足 no_findings 或最高严重级别门槛时继续修订。每轮都是新版本并保留证据，达到最大轮次仍未通过则停止等待人工处理。

核心产物
requirement_design、technical_design、analysis_review
人工门禁
从候选版本中指定需求设计和技术设计终稿
03

pending_development → development_completed

分步开发与 Review Loop

Coding Agent 在需求 feature worktree 中生成 implementation plan，按顺序一次实施一步。每一步都产生独立 Review，发现问题就在当前步骤修复并重新 Review；方案失效时请求用户选择继续、重新规划或阻塞。

核心产物
implementation_plan、step review、implementation report
完成条件
所有步骤通过，最终实现报告和 Review 已入库
04

pending_testing → testing

多需求 Release 与不可变测试快照

用户选择多个开发完成的需求创建 release，workspace-cli 从 feature 分支重建 release worktree。测试启动时冻结成员、feature SHA、release SHA、仓库和测试命令，旧报告不能证明变化后的代码仍然可发布。

测试命令
显式、release 默认、全局默认、Agent 推断或人工补充
安全约束
测试 Agent 只读 release workspace，不在 release 分支修代码
05

testing ↔ bugfix → testing_completed

集成测试与 Bug 修复 Loop

测试 Agent 做整体 Review、单测和集成测试并生成 test report。缺陷关联到具体需求和 test run，Coding Agent 回到对应 feature worktree 修复并生成 bugfix report；重新集成后创建新快照并重新测试，直到全部通过。

循环边界
Bug 修复只发生在 feature 分支，release 分支保持可重建
通过条件
当前快照测试通过且没有未关闭 Bug
06

pending_release → releasing → released

发布确认与可恢复发布

系统重新校验测试快照、feature/release SHA 和目标分支后请求用户确认。确认后逐 repo 发布到 main/master；中途失败进入 publish_in_progress 并保留已发布 SHA，修复失败仓库后可幂等重试。

人工门禁
查看状态、报告和 Bug 后明确确认发布
漂移保护
任何代码或快照变化都会标记 stale 并要求重测

Live execution

用户始终看得到 Agent 在做什么

workspace req watch REQ-001 --follow
workspace release watch 2026-07-15 --follow
workspace job watch <job-key> --follow
workspace run tail <run-id> --raw --follow
workspace approval list --status pending

需求、Release、Job 和 Run 四层事件都可持续跟随。出现 waiting_user_input 时，approval 会带上原任务和实体上下文，回复后状态、事件与后续 Job 在同一事务中更新。

Safety and recovery

自主执行不等于放弃边界

  • Worker 只能访问数据库登记的 feature/release worktree。
  • 权限提升不能开放 SQLite、配置、socket 或其他任务 runtime。
  • MCP capability 绑定 role、实体、Job 和 Run，终态立即撤销。
  • lease 过期不可被迟到 heartbeat 复活，孤儿 Run 由 daemon 收敛。
  • release workspace 不允许 Agent 直接改代码，Bug 必须回 feature 修复。
阅读完整开发流程 需求与验收标准 技术实现方案 Web 使用指南 Web 操作需求 Web 技术方案

commands

v1 命令面

Repo 管理

  • workspace repo add <name> <url>
  • workspace repo list --all
  • workspace repo sync [name]
  • workspace repo update <name>
  • workspace repo remove <name>

需求管理

  • workspace req create <title> --repo <name>
  • workspace req list [--all]
  • workspace req show <key>
  • workspace req update <key> --title <title>
  • workspace req add-repo <key> <repo>
  • workspace req archive <key>
  • workspace req finish <key> -m <message>
  • workspace req reopen <key>
  • workspace req watch <key> --follow
  • workspace dev <key> --tool codex|claude
  • workspace ide <key> --tool vscode

Release 管理

  • workspace release create <name> --req <key>
  • workspace release list [--all]
  • workspace release show <key>
  • workspace release status <key>
  • workspace release watch <key> --follow
  • workspace release add-req <release> <req>
  • workspace release remove-req <release> <req>
  • workspace release integrate <key>
  • workspace release publish <key> --tested

工具

  • workspace update --check
  • workspace completion zsh

AI Native Agent

  • workspace agent add <name> --provider codex|claude --role analysis
  • workspace agent list
  • workspace agent show <name>
  • workspace agent update <name> --model <model>
  • workspace agent health <name>
  • workspace agent remove <name>
  • workspace agent daemon start --once
  • workspace agent daemon status
  • workspace agent daemon stop

AI Native Worker

  • workspace worker add <name> --role coding --agent <agent>
  • workspace worker list
  • workspace worker show <name>
  • workspace worker update <name> --parallelism 2 --max-workers 4
  • workspace worker enable <name>
  • workspace worker disable <name>

AI Native Job

  • workspace job list --status running
  • workspace job show <job-key>
  • workspace job watch <job-key> --follow
  • workspace run tail <run-id> --raw
  • workspace job cancel <job-key> --reason <text>
  • workspace job retry <job-key>

AI Native Approval

  • workspace approval list --status pending
  • workspace approval show <approval-key>
  • workspace approval respond <approval-key> --choice approve --response-json '{}'
  • workspace approval respond <approval-key> --choice approve --scope <scope> --expires-at <time> --sandbox <mode> --approval-policy <policy>
  • workspace mcp serve --capability-token <token>

design

保守、可恢复、只管开发流程

01

SQLite 状态库

业务状态、执行事件和失败记录统一落库，让 CLI、Web 和 Agent 始终读取同一份事实。

02

Git worktree 编排

托管 repo 使用 bare clone，需求与 Release 使用隔离 worktree，避免重复 clone 和分支串扰。

03

两阶段完成体验

需求完成研发后进入 ready；只有 Release 测试与发布成功，需求才会 completed 并归档。

AI Native

从需求到发布，全流程可观察、可恢复

主 Agent 负责协调，专业 Worker 分析、开发和测试；MCP capability、人工 Approval、持久化 Job 与操作队列共同守住边界。

主 Agent 协同 专业 Worker Web 控制台 安全发布门禁
工程记录 实施步骤 实施日志 完成度审计 Review 加固 Runtime 加固