@aipper/aiws

AI Workspace CLI：把 Claude Code / OpenCode / Codex / iFlow 对齐到同一套“真值文件 + 可审计工作流”，降低规则漂移。

核心能力：

• 初始化/更新模板：aiws init / aiws update
• 强门禁校验：aiws validate（可选证据落盘 --stamp）
• 回滚：aiws rollback（从 .aiws/backups/ 恢复）
• 变更工件工作流（脱离 dotfiles）：aiws change ...
• Git hooks：aiws hooks install/status
• Codex：repo skills（推荐）+ 可选全局 skills 安装

真值来源（SSOT）：@aipper/aiws-spec（模板与契约）。

安装

二选一：

• 全局安装（推荐，适合长期使用）：npm i -g @aipper/aiws
• 临时运行（不污染全局版本）：npx @aipper/aiws <command>

快速开始

在任意 git 仓库根目录：

aiws init .
aiws hooks install .

# 建议：用 change 工作流生成可审计工件并切分支
aiws change start demo-change --no-design --hooks

# 提交前门禁（并落盘证据）
aiws validate . --stamp

CLI 速查

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

aiws change <list|new|start|status|next|sync|validate|archive|templates>
aiws hooks <install|status>
aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status|uninstall-prompts>

Codex（repo skills 优先）

• aiws init . 会生成 .agents/skills/（随仓库共享），在 Codex 中可显式调用（示例）：$ws-preflight / $ws-plan / $ws-dev / $ws-review / $ws-commit
• 交付收尾（submodules+superproject 分步提交 + 安全合并）：$ws-deliver
• 收尾（安全合并回目标分支）：$ws-finish（底层调用 aiws change finish，默认 fast-forward）
• 可选：安装全局 skills 到 ~/.codex/skills/（或 $CODEX_HOME/skills）：
  • aiws codex install-skills
  • aiws codex status-skills
  • aiws codex uninstall-skills
• legacy prompts（deprecated，仅兼容）：aiws codex install-prompts

证据落盘与协作

• aiws validate --stamp 会写入：.agentdocs/tmp/aiws-validate/*.json（默认被 .gitignore 忽略）
• $ws-review 会落盘：.agentdocs/tmp/review/codex-review.md（默认被 .gitignore 忽略）
• 建议把“可协作/可审计”的内容放进 changes/<change-id>/（proposal/tasks/design）并提交；.agentdocs/tmp/ 作为本地缓存更稳

运行要求

• Node.js：>= 20
• aiws validate：需要 python3（用于执行 tools/ws_change_check.py 与 tools/requirements_contract.py）