@aipper/aiws

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

它负责把真值文件、变更工件、门禁和跨工具入口落到仓库里，让 Claude Code、OpenCode、Codex 可以共享同一套项目约束，而不是每个工具各写一份 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
• aiws codex install-skills/status-skills/uninstall-skills

支持工具：

• Claude Code
• OpenCode
• Codex

说明：

• ws-dev-lite 是当前推荐的小改动入口

安装

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

快速开始

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 入口：.agents/skills/、.claude/skills/、.claude/commands/、.opencode/skills/、.opencode/commands/
• 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 内：

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

CLI 速查

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>]
aiws codex install-skills
aiws codex status-skills
aiws codex uninstall-skills

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 . 会把入口投影到：

• Codex：.agents/skills/*
• Claude：.claude/skills/* + .claude/commands/*
• OpenCode：.opencode/skills/* + .opencode/commands/* + .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）
• .claude/settings.json.example 提供 hook 兼容层示例
• .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