# @aipper/aiws

`@aipper/aiws` 是面向 AI coding workflow 的 CLI。

它负责把真值文件、变更工件、门禁和工具入口落到仓库里，让 OpenCode 可以使用同一套项目约束，而不是每个工具各写一份 prompt。

## 当前能力

- `aiws init` / `aiws update`：初始化或升级 workspace 模板
- `aiws validate`：校验模板漂移与门禁，可选 `--stamp`
- `aiws rollback`：从 `.aiws/backups/` 回滚
- `aiws change ...`：变更工件工作流
- `aiws dashboard serve`：本地 change/dashboard API
- `aiws hooks install/status`
- `aiws opencode status/supervise`

支持工具：
- OpenCode

说明：
- `ws-dev-lite` 是当前推荐的小改动入口

## 安装

```bash
npm i -g @aipper/aiws
# 或
npx @aipper/aiws --help
```

## 快速开始

```bash
aiws init .
aiws hooks install .

aiws change start demo-change --no-design --hooks
aiws change validate demo-change --strict
aiws validate . --stamp
```

初始化后会生成：
- 真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`
- 工件目录：`changes/`
- AI 入口：`.opencode/skills/`、`.opencode/command/`
- hooks：`.githooks/`

## 推荐用法

AI 工具内：
- 不确定该从哪里开始：`$using-aiws`
- simple/local 单点修复：`$ws-dev-lite`
- 常规实现：`$ws-dev`
- 中大型任务：`$ws-plan` → `$ws-plan-verify` → `$ws-dev`
- OpenCode/oMo 自动 bootstrap：`/ws-auto`
- OpenCode/oMo 自主协作实验：`/ws-autonomy`
- 提交前：`$ws-review` / `$ws-commit`
- 交付前：`$ws-deliver` / `$ws-finish`

shell 内：

```bash
aiws change start <change-id> --no-design
aiws change validate <change-id> --strict
aiws validate . --stamp
```

## CLI 速查

```bash
aiws init [path] [--template <id>]
aiws update [path]
aiws validate [path] [--stamp]
aiws rollback [path] <timestamp|latest>

aiws change new <change-id> [--no-design]
aiws change start <change-id> [--switch|--no-switch]
aiws change status [change-id]
aiws change next [change-id]
aiws change sync [change-id]
aiws change validate [change-id] [--strict] [--check-evidence] [--check-scope]
aiws change evidence [change-id]
aiws change archive [change-id]

aiws dashboard serve [--host 127.0.0.1] [--port 3456]
aiws hooks install [path]
aiws hooks status [path]
aiws opencode status [path]
aiws opencode auto [path] [--session <name>] [--window <name>] [--once] [--poll-ms <ms>] [--no-update]
aiws opencode supervise [path] [--session <name>] [--window <name>] [--once] [--poll-ms <ms>]

```

## Dashboard

`aiws dashboard serve` 会显示：
- change phase
- strict blockers
- review gates
- scope gate
- collaboration 统计
- next advice

本地 API：
- `/api/changes`
- `/api/workflow-stages`
- `/api/change/<id>/validate?strict=1`

## 跨工具入口

`aiws init .` 会把入口投影到：
- OpenCode：`.opencode/skills/*` + `.opencode/command/*`

目标是统一 workflow 入口，不保证工具自动发现或自动加载。

OpenCode/oMo 补充：
- `.opencode/oh-my-opencode.json.example` 提供 autonomy 示例配置（`prompt_append` / `backgroundTasks` / `experimental.auto_resume`）
- 同一份 oMo 示例配置还会声明 approval whitelist policy（只读命令 + evidence 写路径；宿主权限保持 `manual-only`）
- `.opencode/helpers/approval-whitelist-check.sh` 把 whitelist policy 转成 `allow/deny/manual` 判定，并落审计日志
- `.opencode/helpers/approval-whitelist-run.sh` 在 `allow` 时执行简单命令，并落执行摘要
- `.opencode/helpers/approval-whitelist-watchdog.sh` 轮询队列并调用 runner，适合外部蜂群/守护进程接入
- `/ws-auto` 会先触发 `aiws opencode auto .`：必要时刷新托管内容，再按条件确保 watchdog 已在 tmux 中运行
- `aiws opencode auto .` 会在需要时自动执行 `aiws update .`；若 oMo 已启用且 tmux 可用，再继续启动 watchdog
- `aiws opencode supervise .` 会显式确保 tmux 中已有一个 watchdog window；若当前不在 tmux，则会为该工作区起一个 detached session
- `.opencode/helpers/tmux-swarm-scan.sh` / `tmux-swarm-rescue.sh` 提供可选的 tmux 巡检与安全救援 helper

## 运行要求

- Node.js >= 20
- `aiws validate` 需要 `python3`

更多仓库级说明见根 README：[`../../README.md`](../../README.md)