Intent-Engine
中文 | English
Intent-Engine 是一个极简的、项目专属的战略意图追踪系统，专为人机协作设计。
它不是又一个待办事项列表，而是连接人类战略思维与 AI 执行能力的桥梁——帮助回答"我们要去哪里"和"为什么要去那里"这两个关键问题。
🎯 这是什么？
Intent-Engine 是一个命令行工具 + 数据库系统，用于记录、追踪和回顾战略意图。它为人类与 AI 的协作提供了一个共享的、可追溯的"意图层"。
核心特点：
- 📝 战略级任务管理：关注 What（做什么）和 Why（为什么），而不仅仅是 How（怎么做）
- 🧠 AI 的外部长时记忆：跨会话持久化决策历史和上下文
- 🌳 层级化问题分解：支持无限层级的父子任务关系
- 📊 结构化决策追踪：每个关键决策都被记录为事件流
- 🔄 JSON 原生接口：完美适配 AI 工具集成
👥 为谁设计？
主要用户
- 人类开发者：设定战略目标，记录项目意图
- AI Agent：理解目标、执行任务、记录决策过程
- 人机协作团队：在长期项目中保持上下文同步
使用场景
- ✅ 需要 AI 在多个会话间持续工作的复杂项目
- ✅ 需要追溯"为什么做这个决策"的技术项目
- ✅ 需要分解大型任务为子任务树的系统工程
- ✅ 需要 AI 自主管理工作优先级的自动化流程
💡 解决什么痛点？
对人类的价值
传统任务管理工具（Jira/Linear）的问题：
- ❌ 聚焦于战术执行（Sprint、Story Points），缺少战略层
- ❌ 需要大量手动维护（状态更新、评论）
- ❌ 不适合 AI 集成（Web UI 为主）
Intent-Engine 的解决方案：
- ✅ 战略意图层：每个任务包含完整的 规格说明（spec） 和 决策历史（events）
- ✅ 自动化友好：AI 可以自主创建、更新、切换任务
- ✅ CLI + JSON：完美的 AI 工具链集成
对 AI的价值
Claude Code TodoWrite 的局限性：
- ❌ 会话级：仅存在于当前对话，会话结束即消失
- ❌ 无历史：无法追溯之前的决策和思考过程
- ❌ 平铺结构：缺少层级关系，难以管理复杂任务
Intent-Engine 的优势：
- ✅ 项目级：持久化到 SQLite 数据库，跨会话永久保存
- ✅ 可追溯：完整的事件流记录每个决策的上下文
- ✅ 层级化：任务树结构，强制完成子任务才能完成父任务
- ✅ 原子操作：
start、pick-next、spawn-subtask、switch等复合命令节省 60-70% Token
📊 与其他工具的本质区别
| 维度 | Intent-Engine | Claude Code TodoWrite | Jira/Linear |
|---|---|---|---|
| 核心哲学 | 战略意图层：What + Why | 战术执行层：What (临时) | 任务追踪层：What + When |
| 主要用户 | 人类 ↔ AI（双向协作） | AI 内部使用（单向） | 人类团队（协作） |
| 生命周期 | 项目级（跨会话、持久化） | 会话级（临时、易失） | 项目级（持久化） |
| 数据结构 | 任务树 + 事件流 + 规格说明 | 平铺列表（无层级） | 工作流 + 字段 + 评论 |
| 历史追溯 | ✅ 完整决策历史（events） | ❌ 无历史记录 | ⚠️ 有评论但无结构化决策 |
| 交互模式 | CLI + JSON（AI友好） | Tool Call（AI专用） | Web UI（人类友好） |
| 粒度定位 | 粗粒度（战略里程碑） | 细粒度（当前步骤） | 中粒度（Sprint任务） |
| 核心价值 | AI的外部长时记忆 | AI的工作记忆（短期） | 团队的工作协调 |
典型使用场景对比
Intent-Engine： "实现用户认证系统"（包含完整的技术规格、决策历史、子任务树）
- 生命周期：数天到数周
- AI 可以在任何时候通过
task start --with-events恢复上下文并继续工作
TodoWrite： "修改 auth.rs 文件"（当前会话的临时步骤）
- 生命周期：当前会话
- 会话结束后消失，无法恢复
Jira： "PROJ-123: 添加 OAuth2 支持"（团队分配的具体任务）
- 生命周期：一个 Sprint（1-2周）
- 需要手动更新状态和进度
🚀 快速开始
1. 安装
# 方式 1: Cargo Install（推荐）
# 方式 2: 下载预编译二进制
# 访问 https://github.com/wayfind/intent-engine/releases
# 验证安装
📖 详细安装指南：查看 INSTALLATION.md 了解所有安装方式、故障排除和集成选项。
2. 5 分钟体验核心功能
# 1. 添加一个战略任务
| \
# 2. 开始任务并查看上下文
# 3. 在工作中发现子问题？创建子任务并自动切换
# 4. 记录关键决策
| \
# 5. 完成子任务
# 6. 切回父任务并完成
# 7. 生成工作报告
💡 更详细的教程：参见 QUICKSTART.md
✨ 核心特性
- 项目感知：自动向上查找
.intent-engine目录，感知项目根目录 - 惰性初始化：写入命令自动初始化项目，无需手动 init
- 任务树管理：支持无限层级的父子任务关系
- 决策历史：完整的事件流记录（decision、blocker、milestone 等）
- 智能选择：
pick-next基于优先级和复杂度自动选择任务 - 原子操作：
start、switch、spawn-subtask等复合命令节省 60-70% Token - 🔍 FTS5 搜索引擎：GB 级任务量下毫秒级响应，独特的 snippet 函数用
**高亮匹配词，对 Agent 上下文极度友好 - JSON 输出：所有命令输出结构化 JSON，完美集成 AI 工具
📚 文档导航
🚀 新用户入门
- QUICKSTART.md - 5 分钟快速上手
- The Intent-Engine Way - 设计哲学和协作模式（强烈推荐）
- Installation Guide - 详细安装指南和故障排除
🤖 AI 集成
- AI Quick Guide - AI 客户端速查手册
- MCP Server - 集成到 Claude Code/Desktop
- Claude Skill - 轻量级 Claude Code 集成
📖 深度学习
- Command Reference - 完整命令参考
- Task Workflow Analysis - Token 优化策略详解
- Performance Report - 性能基准测试
- Security Testing - 安全性测试报告
👥 贡献者
- Contributing Guide - 如何贡献代码
- Release Process - 发布流程
🌟 Intent-Engine 的独特价值
1. 人机协作的记忆共享层
- 人类设定战略意图（What + Why）
- AI 执行战术任务（How）
- Intent-Engine 记录整个过程
2. 跨会话的上下文恢复
- AI 可以随时通过
task start --with-events恢复完整上下文 - 无需人类重复解释背景
3. 决策可追溯性
- 每个关键决策都被记录（
event add --type decision） - 未来可以回顾"为什么当时选择了方案 A 而不是方案 B"
4. 层级化的问题分解
- 支持无限层级的父子任务
- 强制完成所有子任务才能完成父任务
🛠️ 技术栈
- 语言：Rust 2021
- CLI：clap 4.5
- 数据库：SQLite with sqlx 0.7
- 异步运行时：tokio 1.35
- 全文搜索：SQLite FTS5
🔧 开发设置
首次克隆项目后（贡献者必读）
为了避免 CI 格式检查失败，请立即运行：
这会安装 git pre-commit hooks，在每次提交前自动运行 cargo fmt，确保代码格式符合规范。
开发工具命令
项目提供了 Makefile 简化常用操作：
📖 详细说明：查看 scripts/README.md 了解完整的开发工作流和自动化工具。
🧪 测试
Intent-Engine 包含完整的测试体系：
# 运行所有测试
# 运行性能测试
# 查看测试覆盖率
测试统计：116 个测试全部通过 ✅
- 47 个单元测试
- 22 个 CLI 集成测试
- 10 个特殊字符安全性测试
- 37 个性能测试
📄 许可证
本项目采用 MIT 或 Apache-2.0 双许可证。
- MIT License - 详见 LICENSE-MIT
- Apache License 2.0 - 详见 LICENSE-APACHE
🤝 贡献
欢迎提交 Issue 和 Pull Request！
🔗 相关链接
下一步：阅读 The Intent-Engine Way 深入理解设计哲学，或直接查看 QUICKSTART.md 开始使用。