intent-engine 0.1.7

# Intent-Engine 快速上手指南

**中文 | [English](QUICKSTART.en.md)**

**5 分钟从零开始体验 Intent-Engine 的核心功能。**

---

## 前提条件

需要安装：
- Rust 和 Cargo（[安装指南](https://rustup.rs/)）
- 或者已经下载了预编译二进制文件

---

## 第 1 步：安装（1 分钟）

```bash
# 方式 1: 使用 Cargo 安装（推荐）
cargo install intent-engine

# 方式 2: 下载预编译二进制
# 访问 https://github.com/wayfind/intent-engine/releases
# 下载适合你平台的版本

# 验证安装
intent-engine --version
```

> 💡 **提示**: 详细安装选项请参见 [INSTALLATION.md](docs/zh-CN/guide/installation.md)

---

## 第 2 步：创建第一个任务（1 分钟）

```bash
# 添加一个战略任务（包含规格说明）
echo "实现 JWT 认证功能
- 支持 token 生成和验证
- token 有效期 7 天
- 支持刷新 token
- 使用 HS256 算法" | \
  intent-engine task add --name "实现用户认证" --spec-stdin

# 输出示例：
# {
#   "id": 1,
#   "name": "实现用户认证",
#   "status": "todo",
#   ...
# }
```

**发生了什么？**
- ✅ Intent-Engine 自动在当前目录（或父目录）创建了 `.intent-engine/project.db`
- ✅ 任务被保存到 SQLite 数据库
- ✅ 规格说明（spec）被完整记录

---

## 第 3 步：开始任务并查看上下文（30 秒）

```bash
# 开始任务并获取完整上下文
intent-engine task start 1 --with-events

# 输出示例：
# {
#   "id": 1,
#   "name": "实现用户认证",
#   "spec": "实现 JWT 认证功能\n- 支持 token 生成和验证\n...",
#   "status": "doing",  # 状态已更新为 doing
#   ...
# }
```

**发生了什么？**
- ✅ 任务状态从 `todo` 变为 `doing`
- ✅ 任务被设置为"当前任务"
- ✅ 返回完整的规格说明和事件历史（如果有）

---

## 第 4 步：在工作中发现子问题（1 分钟）

```bash
# 在实现过程中发现需要先配置 JWT 密钥
intent-engine task spawn-subtask --name "配置 JWT 密钥存储"

# 输出示例：
# {
#   "id": 2,
#   "parent_id": 1,  # 自动设置父任务
#   "name": "配置 JWT 密钥存储",
#   "status": "doing",  # 自动开始
#   ...
# }
```

**发生了什么？**
- ✅ 创建了子任务（parent_id = 1）
- ✅ 子任务自动进入 `doing` 状态
- ✅ 当前任务自动切换到子任务

---

## 第 5 步：记录关键决策（30 秒）

```bash
# 记录你的决策过程
echo "决定将 JWT 密钥存储在环境变量中
原因：
1. 避免密钥硬编码到代码中
2. 便于不同环境使用不同密钥
3. 符合 12-Factor App 原则" | \
  intent-engine event add --task-id 2 --type decision --data-stdin

# 输出示例：
# {
#   "id": 1,
#   "task_id": 2,
#   "log_type": "decision",
#   "discussion_data": "决定将 JWT 密钥存储在环境变量中\n...",
#   "timestamp": "2025-11-08T..."
# }
```

**发生了什么？**
- ✅ 决策被记录到事件流
- ✅ 未来可以追溯"为什么做这个决定"
- ✅ AI 可以通过 `--with-events` 恢复完整上下文

---

## 第 6 步：完成子任务并切回父任务（30 秒）

```bash
# 完成子任务
intent-engine task done

# 切换回父任务
intent-engine task switch 1

# 输出包含父任务的完整上下文
```

---

## 第 7 步：完成父任务（30 秒）

```bash
# 完成父任务
intent-engine task done

# 如果还有未完成的子任务，系统会报错：
# Error: Cannot complete task 1: it has incomplete subtasks

# 全部子任务完成后，可以成功完成父任务
```

---

## 第 8 步：生成工作报告（30 秒）

```bash
# 生成简洁的工作摘要（推荐，节省 Token）
intent-engine report --since 1d --summary-only

# 输出示例：
# {
#   "summary": {
#     "total_count": 2,
#     "todo_count": 0,
#     "doing_count": 0,
#     "done_count": 2
#   }
# }

# 生成详细报告
intent-engine report --since 1d
```

---

## 🎉 恭喜！

你已经完成了 Intent-Engine 的核心工作流：

1. ✅ 创建战略任务（包含规格说明）
2. ✅ 开始任务并获取上下文
3. ✅ 发现子问题并创建子任务
4. ✅ 记录关键决策
5. ✅ 完成任务（强制子任务完成检查）
6. ✅ 生成工作报告

---

## 下一步

### 🚀 进阶功能

1. **智能任务选择**：批量处理多个任务
   ```bash
   # 创建多个任务
   intent-engine task add --name "任务 A"
   intent-engine task add --name "任务 B"
   intent-engine task add --name "任务 C"

   # 设置优先级和复杂度
   intent-engine task update 1 --priority 10 --complexity 3
   intent-engine task update 2 --priority 8 --complexity 7
   intent-engine task update 3 --priority 5 --complexity 2

   # 智能选择（按优先级降序、复杂度升序）
   intent-engine task pick-next --max-count 3
   ```

2. **全文搜索**：快速查找任务
   ```bash
   intent-engine report --filter-name "认证" --summary-only
   intent-engine report --filter-spec "JWT" --summary-only
   ```

3. **事件类型**：记录不同类型的事件
   - `decision` - 关键决策
   - `blocker` - 遇到的障碍
   - `milestone` - 里程碑
   - `discussion` - 讨论记录
   - `note` - 一般备注

### 📚 深入学习

- [**The Intent-Engine Way**](docs/zh-CN/guide/the-intent-engine-way.md) - 理解设计哲学和最佳实践
- [**AI Quick Guide**](docs/zh-CN/guide/ai-quick-guide.md) - AI 客户端速查手册
- [**完整命令参考**](docs/zh-CN/guide/command-reference-full.md) - 所有命令的详细文档

### 🔧 集成到 AI 工具

- [**MCP Server**](docs/zh-CN/integration/mcp-server.md) - 集成到 Claude Code/Desktop
- [**Claude Skill**](.claude-code/intent-engine.skill.md) - 轻量级集成方式

### 💻 贡献代码前的准备

如果你想为 Intent-Engine 贡献代码，请先安装 git hooks：

```bash
./scripts/setup-git-hooks.sh
```

这会在每次提交前自动格式化代码，避免 CI 检查失败。更多开发工具命令请查看 [scripts/README.md](scripts/README.md)。

---

## 常见问题

**Q: Intent-Engine 和普通待办事项工具有什么区别？**

A: Intent-Engine 关注**战略意图层**（What + Why），而不仅仅是战术执行层（What）。每个任务包含完整的规格说明、决策历史和层级关系，是 AI 的外部长时记忆。

**Q: 为什么需要 `--with-events`？**

A: 这会返回任务的事件历史，帮助 AI（或人类）快速恢复上下文，了解"之前做了什么决策"。

**Q: 什么时候使用 `spawn-subtask` vs `task add --parent`？**

A:
- `spawn-subtask`: 当你**正在处理一个任务**时发现子问题，一步完成"创建 + 开始 + 切换"
- `task add --parent`: 提前规划子任务，但不立即开始

**Q: 数据存储在哪里？**

A: `.intent-engine/project.db`（SQLite 数据库），位于项目根目录。

---

**现在开始使用 Intent-Engine，让 AI 成为你的战略执行伙伴！** 🚀