# MiAW

**Minimal Agentic Workflow**：为编码 Agent 的工作保存项目内的状态与证据。

MiAW 让 Agent 从已记录的任务继续工作，不必仅凭聊天历史重建项目上下文。它与现有编码 Agent 和 Git 配合使用，本身不是模型、IDE 或托管执行服务。

[English](https://www.npmjs.com/package/@direal/miaw)

## 整体设计

```text
人的决策
   ↓
编码 Agent + skills ── aw CLI ── 项目记录（.aw/）
                         ├── Agent Server → 委派的 worker
                         └── Project Index → 源码检索
```

宿主 Agent 负责推理和调用工具，skills 说明工作程序，CLI 校验记录与状态转换。Agent Server 执行有明确边界的委派工作，Project Index 帮助定位源码证据。worker 的报告或检索结果本身都不等于验收结论。

| 记录 | 回答的问题 |
| --- | --- |
| Project 与 Blueprint | 要做什么，设计应遵守哪些约束？ |
| Roadmap | 下一步优先考虑哪些工作？ |
| Task | 提出了什么需求，如何计划、修改和验证？ |
| Agent evidence | 每个委派的 worker 实际做了什么？ |
| Knowledge | 哪些已接受的经验值得后续任务保留？ |

任务按记录推进：

```text
意图 → 分析 → 计划 → 执行 → 验证 → 提交 → 归档
```

需要时使用 Brainstorm、Review 和 Consolidate；跳过可选步骤须记录理由。受阻的工作可以通过 task ID 恢复。验证结果、风险接受和提交批准是不同的决策，Agent 报告“完成”并不会自动关闭任务。

持久的设计与执行记录保存在 `.aw/`，Git 记录源码变化。可丢弃的服务状态和索引缓存保存在 `.aw/.runtime/`，不进入 Git 或同步目录。只有相同 workflow owner、相同宿主平台的 worktree 才共享 worker 池；WSL 与原生 Windows 使用独立的运行时池。

## 开始使用

需要 **Node.js 18+**，支持 Linux x64（glibc 2.28+）、Windows x64 和 macOS Apple Silicon。npm 安装对应平台的二进制，不需要 Rust。提交和隔离 worktree 需要 Git；不使用 Git 的项目可配置 `vcs = "none"`。

```bash
npm install -g @direal/miaw
aw --version
cd your-project
aw init "Short project summary"
aw install --target agents
aw status
```

`agents` 将技能安装到 `.agents/skills/`。Claude Code 使用 `--target claude-code`；需要 `.codex/skills/` 的宿主使用 `--target codex`。Pi 用户还可通过 `pi install npm:@direal/miaw` 安装可选的状态集成。

在当前项目中打开已认证的编码 Agent，通过宿主支持的方式调用技能。例如：

```text
$aw-init 明确项目目标与约束
$aw-task 为 API 增加限流
$aw-resume <task-id>
```

初始化和查看记录不需要模型账户。委派执行还需配置 Provider 并通过就绪检查。Linux/WSL worker 需要 Bubblewrap；原生 Windows 执行需要明确同意无沙箱运行。角色和允许写入的路径不能替代操作系统隔离。

## 查看与维护

- `aw status` 查看任务状态，`aw tui` 提供交互式视图。
- `aw docs getting-started --lang zh` 说明 Provider 配置和宿主接入。英文使用 `--lang en`；手册随 npm 包分发，无需源码 checkout。
- `aw update status` 查看已安装版本，`aw update` 在首次更新前请求授权。不同宿主分别更新。
- 如果 `aw --version` 仍显示旧构建，在 Linux/WSL 执行 `type -a aw`，在 PowerShell 执行 `Get-Command aw -All`，检查命令优先级。Cargo 版可能排在 npm 版之前。

通过 CLI 或 skills 管理工作流状态，不直接编辑任务 JSON。共享 `.aw/` 前检查提示词、响应和日志；持久证据可能包含项目隐私。

采用 MIT 许可证。模型账户与 Provider 凭据由用户自行管理。