# koala-workspace-cli

**Repository Path**: flying_red_pig/koala-workspace-cli

## Basic Information

- **Project Name**: koala-workspace-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# koala-workspace-cli

`koala-workspace-cli` 是 Koala 的本地 workspace 控制工具，负责 Sprint item 级别的 worktree、端口、数据、compose 服务和运行态。

日常主入口：

- `prepare`：准备好 workspace，包括 worktree、端口、compose 配置和数据库数据
- `start`：准备并启动所有服务
- `restart`：重启所有服务，保留 worktree 和数据
- `stop`：退出所有服务，保留 worktree 和数据
- `destroy`：销毁 workspace，移除服务、数据卷、worktree、生成物和端口分配

高级接口仍保留给排障和细粒度操作：

- `plan/db/logs/worktree/reserve/doctor`

兼容命令仍可执行，但从默认 help 隐藏，新文档和 skill 不应作为日常入口使用：

- `init/up/down/release`

## 使用方式

当前建议从 Koala state root `/Users/xuzinan/Desktop/research/aiyou-ai-manager` 目录运行；安装全局入口后，可直接使用 `koala-workspace`：

```bash
koala-workspace prepare A-091
koala-workspace start A-091
koala-workspace start A-091 --private-deps aiyou-service
koala-workspace logs A-091 --service aiyou-service.http --tail 200
koala-workspace restart A-091
koala-workspace stop A-091
koala-workspace destroy A-091
koala-workspace worktree list A-091
koala-workspace worktree path A-091 --project aiyou-service
```

开发时可以在本项目目录运行：

```bash
pnpm install
pnpm build
pnpm test
```

慢速真实 e2e 需要显式开启，默认测试不会启动 Docker workspace：

```bash
KOALA_WORKSPACE_E2E=1 \
KOALA_WORKSPACE_FIXTURE=A-174 \
KOALA_MANAGER_ROOT=/Users/xuzinan/Desktop/research/aiyou-ai-manager \
npm run test:e2e
```

这条 e2e 会启动并销毁 A-174 workspace，验证真实服务 health、容器环境变量、Postgres 可查询和 destroy 后容器/volume/network 清理。运行前必须确认 `projects/A-174/workspace` 不存在，且磁盘空间满足 `koala-workspace start` 的 10 GiB 硬水位线。

## 设计原则

- CLI 核心逻辑保持确定性，不在执行层调用 LLM
- Docker Compose 负责服务运行，CLI 负责编排 item、worktree、端口、数据准备和运行态
- 说明文档使用简体中文
- 对外主流程只暴露 workspace 生命周期，高级接口用于排障和细粒度操作
- `init/up/down/release` 仅作为兼容层保留；日常入口使用 `prepare/start/restart/stop/destroy`

## 当前边界

`prepare` 会写入：

- `/Users/xuzinan/Desktop/research/aiyou-ai-manager/projects/.koala-workspace/registry.json`
- `/Users/xuzinan/Desktop/research/aiyou-ai-manager/projects/{itemId}/workspace/manifest.json`
- `/Users/xuzinan/Desktop/research/aiyou-ai-manager/projects/{itemId}/workspace/docker-compose.yml`
- `/Users/xuzinan/Desktop/research/aiyou-ai-manager/projects/{itemId}/workspace/run/workspace.json`
- `/Users/xuzinan/Desktop/research/aiyou-ai-manager/projects/{itemId}/workspace/worktrees/{projectKey}`

其中 `manifest.json` 会区分：

- `projects`：完整代码项目矩阵，都会有 worktree
- `services`：需要端口和 env 的运行单元，例如后端 HTTP、Postgres、AI 服务
- `dataSetup`：数据库数据准备说明，例如 `aiyou-service.postgres` 通过 Docker 工具容器执行 `yarn prod-db:pull/reset/init-empty`
- `dependencies`：各项目依赖模式；默认共享 Docker 依赖 volume，需要试装第三方依赖时用 `--private-deps <project>` 切到 item 私有依赖
- `compose`：item-scoped `docker-compose.yml` 的项目名、文件路径和服务映射

`manifest.json` 只保存声明，不保存执行结果。运行态写入：

```text
projects/{itemId}/workspace/run/workspace.json
```

`prepare/start` 默认按 `dataSetup` 在 Docker 内执行 `db pull`。`db reset/init-empty` 作为高级接口保留。
`doctor/start` 会检查宿主机可用磁盘空间；低于硬水位线时直接失败，先释放 workspace 或 Docker 缓存后再重试。

## AI 操作顺序

AI 进入某个 Sprint item 开发时，推荐固定顺序：

```bash
koala-workspace prepare A-091
koala-workspace worktree list A-091
koala-workspace worktree path A-091 --project aiyou-service
```

需要启动服务时：

```bash
koala-workspace start A-091
koala-workspace logs A-091 --service aiyou-service.http --tail 200
koala-workspace stop A-091
```

任务完成且确认要清理整个 workspace 后：

```bash
koala-workspace destroy A-091
```

不要由开发层自行创建 `.worktrees`。workspace 创建权属于：

```bash
koala-workspace prepare A-091
```