@bicorne/task-flow 0.1.0

package/references/AI-CONVERSATION-TUTORIAL.md

@@ -0,0 +1,270 @@
+# 人类与 AI 对话教程
+
+本文档描述人类用户如何通过与预装 task-flow skill 的 AI 对话来完成开发任务。
+
+---
+
+## 前置条件
+
+1. AI 已预装 `task-flow` skill
+2. 项目已初始化：`task-flow init`
+3. AI 可访问项目代码库
+
+---
+
+## 场景一：新功能开发
+
+### 步骤 1：描述需求
+
+**人类**：
+> 我想给项目添加 OAuth 登录功能，支持 Google 和 GitHub 登录。
+
+**AI 行为**：
+1. 分析项目结构和现有代码
+2. 调用 `task-flow analyze` 生成 context
+3. 调用 `task-flow extract` 生成 PRD 文档
+
+**AI 回复**：
+> 我已分析项目并生成了 PRD 文档。请确认以下需求：
+> 
+> **功能清单**：
+> 1. Google OAuth 登录
+> 2. GitHub OAuth 登录
+> 3. 用户信息存储
+> 4. 登录状态管理
+> 
+> 是否需要调整？
+
+### 步骤 2：确认需求
+
+**人类**：
+> 还需要支持微信登录，并且登录后跳转到用户仪表盘。
+
+**AI 行为**：
+1. 更新 PRD 文档
+2. 调用 `task-flow design` 生成技术设计
+
+**AI 回复**：
+> 已更新需求并生成技术设计。技术方案：
+> 
+> - 使用 Passport.js 作为 OAuth 中间件
+> - 用户信息存储在 PostgreSQL
+> - JWT 作为会话管理
+> 
+> 是否继续生成任务？
+
+### 步骤 3：确认技术方案
+
+**人类**：
+> 可以，继续。
+
+**AI 行为**：
+1. 调用 `task-flow tasks` 生成任务文件
+2. 调用 `task-flow worktree` 创建隔离工作区
+
+**AI 回复**：
+> 已生成任务文件并创建隔离工作区：
+> 
+> ```
+> Phase 1: 基础设施
+>   - Task 1.1: 安装依赖
+>   - Task 1.2: 配置 OAuth Provider
+> 
+> Phase 2: 核心功能
+>   - Task 2.1: 实现 Google 登录
+>   - Task 2.2: 实现 GitHub 登录
+>   - Task 2.3: 实现微信登录
+> 
+> Phase 3: 集成测试
+>   - Task 3.1: E2E 测试
+> ```
+> 
+> 开始实现吗？
+
+### 步骤 4：开始实现
+
+**人类**：
+> 开始。
+
+**AI 行为**：
+1. 进入 worktree 目录
+2. 按任务顺序编码实现
+3. 运行测试验证
+
+**AI 回复**：
+> 正在实现...
+> 
+> ✅ Task 1.1: 安装依赖 - 完成
+> ✅ Task 1.2: 配置 OAuth Provider - 完成
+> ✅ Task 2.1: 实现 Google 登录 - 完成
+> ...
+> 
+> 所有任务已完成，测试通过。是否合并到主分支？
+
+### 步骤 5：合并
+
+**人类**：
+> 合并。
+
+**AI 行为**：
+1. 创建审查报告
+2. 调用 `task-flow merge` 合并代码
+
+**AI 回复**：
+> ✅ 代码已合并到主分支
+> ✅ worktree 已清理
+> 
+> OAuth 登录功能开发完成！
+
+---
+
+## 场景二：Bug 修复
+
+### 步骤 1：描述问题
+
+**人类**：
+> 用户反馈登录后有时会自动退出，怀疑是 token 过期问题。
+
+**AI 行为**：
+1. 分析认证相关代码
+2. 调用 `task-flow extract --type fix` 生成修复 PRD
+
+**AI 回复**：
+> 我分析了认证模块，发现问题：
+> 
+> 1. JWT 刷新逻辑在并发请求时存在竞态条件
+> 2. Token 过期时间未正确设置时区
+> 
+> 建议修复方案：
+> 1. 添加分布式锁防止并发刷新
+> 2. 使用 UTC 时间计算过期时间
+> 
+> 是否继续？
+
+### 步骤 2：确认并修复
+
+**人类**：
+> 继续。
+
+**AI 行为**：
+1. 生成修复任务
+2. 创建隔离 worktree
+3. 实现修复
+
+**AI 回复**：
+> ✅ 修复完成，已添加单元测试
+> ✅ 测试通过
+> 
+> 是否合并？
+
+---
+
+## 场景三：技术咨询
+
+### 步骤 1：提问
+
+**人类**：
+> 这个项目的架构是什么样的？
+
+**AI 行为**：
+1. 读取 SKILL.md 了解项目规范
+2. 分析代码结构
+3. 生成架构说明
+
+**AI 回复**：
+> 根据 SKILL.md 和代码分析：
+> 
+> **项目架构**：
+> - 类型：CLI 工具 + Skill 包
+> - 技术栈：TypeScript + Node.js 22
+> - 构建工具：tsc
+> - 测试框架：Node.js 内置测试
+> 
+> **核心模块**：
+> 1. `src/commands/` - CLI 命令实现
+> 2. `src/lib/` - 核心工具库
+> 3. `src/hooks/` - 生命周期钩子
+> 
+> **工作流**：
+> ```
+> extract → design → tasks → worktree → implement → review → merge
+> ```
+
+---
+
+## 场景四：跳过技术设计
+
+### 步骤 1：简单需求
+
+**人类**：
+> 给 README 添加一个安装说明章节。
+
+**AI 行为**：
+1. 判断需求简单，无需技术设计
+2. 直接调用 `task-flow extract` 和 `task-flow tasks`
+3. 跳过 `task-flow design`
+
+**AI 回复**：
+> 这是一个简单任务，我将跳过技术设计直接实现。
+> 
+> ✅ 已更新 README.md
+> 
+> 完成！
+
+---
+
+## 常见对话模式
+
+### 提供额外上下文
+
+**人类**：
+> 这个功能需要兼容 IE11。
+
+**AI 行为**：
+调用命令时添加 `--context` 参数：
+```bash
+task-flow design --change <name> --context "兼容性: IE11"
+```
+
+### 指定优先级
+
+**人类**：
+> 这个是紧急需求。
+
+**AI 行为**：
+```bash
+task-flow extract --change <name> --priority high
+```
+
+### 强制覆盖
+
+**人类**：
+> 重新生成 PRD。
+
+**AI 行为**：
+```bash
+task-flow extract --change <name> --force
+```
+
+---
+
+## AI 调用命令速查
+
+| 场景 | AI 调用的命令 |
+|------|--------------|
+| 分析项目 | `task-flow analyze --output context.json` |
+| 生成 PRD | `task-flow extract --change <name> --context-file context.json` |
+| 生成技术设计 | `task-flow design --change <name> --context-file context.json` |
+| 生成任务 | `task-flow tasks --change <name> --yes` |
+| 创建工作区 | `task-flow worktree --change <name> --yes` |
+| 查看状态 | `task-flow status` |
+| 合并代码 | `task-flow merge <name>` |
+
+---
+
+## 注意事项
+
+1. **AI 主动确认**：在关键步骤（需求确认、技术方案、合并）AI 会主动询问人类
+2. **透明执行**：AI 会告知正在执行的命令和结果
+3. **错误处理**：如果命令失败，AI 会解释原因并建议解决方案
+4. **上下文传递**：AI 会自动维护 context.json，确保信息一致性

package/references/CLI-TUTORIAL.md

@@ -0,0 +1,447 @@
+# 人类 CLI 使用教程
+
+本文档描述人类开发者如何直接使用 `task-flow` CLI 命令完成开发任务。
+
+---
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @bicorne/task-flow
+
+# 或使用 pnpm
+pnpm add -g @bicorne/task-flow
+
+# 验证安装
+task-flow --version
+```
+
+---
+
+## 快速开始
+
+### 1. 初始化项目
+
+```bash
+# 在项目根目录执行
+task-flow init
+
+# 强制重新初始化（覆盖现有配置）
+task-flow init --force
+```
+
+初始化后创建的目录结构：
+```
+project/
+├── .harness/
+│   ├── state.json          # 运行状态
+│   ├── hooks.json          # Hooks 配置
+│   └── archive/            # 归档目录
+├── spec/
+│   └── changes/            # 变更目录
+└── .harnessrc              # 配置文件
+```
+
+### 2. 创建新功能
+
+```bash
+# 步骤 1: 分析项目（可选，生成上下文骨架）
+task-flow analyze --output context.json
+
+# 步骤 2: 编辑 context.json，补充项目理解
+# ...
+
+# 步骤 3: 生成 PRD
+task-flow extract --change my-feature --context-file context.json
+
+# 步骤 4: 编辑 PRD 文档
+# 文件位置: spec/changes/my-feature/product-requirement.md
+
+# 步骤 5: 生成技术设计（可选）
+task-flow design --change my-feature --context-file context.json
+
+# 步骤 6: 编辑技术设计文档
+# 文件位置: spec/changes/my-feature/design.md
+
+# 步骤 7: 生成任务文件
+task-flow tasks --change my-feature --yes
+
+# 步骤 8: 创建隔离工作区
+task-flow worktree --change my-feature --yes
+
+# 步骤 9: 在工作区中开发
+cd .worktrees/harness-feat-my-feature
+# 编码...
+
+# 步骤 10: 验证
+pnpm build && pnpm test && pnpm lint
+
+# 步骤 11: 合并
+cd ../..  # 回到主仓库
+task-flow merge my-feature
+```
+
+---
+
+## 命令详解
+
+### `task-flow init`
+
+初始化项目配置。
+
+```bash
+task-flow init [--force]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--force` | 强制覆盖现有配置 |
+
+---
+
+### `task-flow analyze`
+
+自动扫描项目，生成上下文 JSON。
+
+```bash
+task-flow analyze                    # 输出到 stdout
+task-flow analyze --output ctx.json  # 输出到文件
+```
+
+**扫描内容**：
+- `package.json`：项目名称、描述、依赖
+- `tsconfig.json`：TypeScript 配置
+- 目录结构：src/、tests/、docs/ 等
+- 技术栈推断：框架、构建工具、测试框架
+
+---
+
+### `task-flow extract`
+
+生成产品需求文档（PRD）。
+
+```bash
+task-flow extract --change <name> [options]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--change <name>` | 变更名称（必需） |
+| `--context-file <path>` | 上下文 JSON 文件路径 |
+| `--input <text>` | 直接输入内容 |
+| `--type <type>` | 任务类型：feat/fix/refactor/test/docs/chore |
+| `--priority <level>` | 优先级：high/medium/low |
+| `--force` | 覆盖现有文件 |
+
+**输入优先级**：`--input` > `--context-file` > stdin > 模板
+
+**示例**：
+```bash
+# 基本用法
+task-flow extract --change add-oauth
+
+# 带上下文
+task-flow extract --change add-oauth --context-file context.json
+
+# 指定类型和优先级
+task-flow extract --change fix-login --type fix --priority high
+
+# 从 stdin 读取
+echo '{"projectName": "my-app"}' | task-flow extract --change add-oauth
+```
+
+---
+
+### `task-flow design`
+
+生成技术设计文档。
+
+```bash
+task-flow design --change <name> [options]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--change <name>` | 变更名称（必需） |
+| `--context-file <path>` | 上下文 JSON 文件路径 |
+| `--context <text>` | 直接传入上下文信息 |
+| `--input <text>` | 直接输入设计内容 |
+| `--force` | 覆盖现有文件 |
+| `--skip-prompt` | 非 TTY 环境跳过交互 |
+
+**示例**：
+```bash
+# 基本用法
+task-flow design --change add-oauth
+
+# 带上下文
+task-flow design --change add-oauth --context-file context.json
+
+# 直接传入上下文
+task-flow design --change add-oauth --context "技术栈: React, 架构: 微前端"
+
+# 跳过交互（生成空模板）
+task-flow design --change add-oauth --skip-prompt
+```
+
+---
+
+### `task-flow tasks`
+
+生成任务文件。
+
+```bash
+task-flow tasks --change <name> [options]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--change <name>` | 变更名称（必需） |
+| `--yes` | 跳过确认 |
+| `--input <text>` | 直接输入任务 JSON |
+
+**生成文件**：
+- `spec/changes/<name>/tasks.md` - 任务清单
+- `spec/changes/<name>/tasks/PHASE-*.json` - 任务文件
+- `spec/changes/<name>/manifest.json` - 执行配置
+
+---
+
+### `task-flow worktree`
+
+创建隔离的 git worktree 工作区。
+
+```bash
+task-flow worktree --change <name> [options]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--change <name>` | 变更名称（必需） |
+| `--yes` | 跳过确认 |
+
+**工作区位置**：`.worktrees/harness-feat-<name>/`
+
+---
+
+### `task-flow status`
+
+显示当前状态。
+
+```bash
+task-flow status
+```
+
+输出示例：
+```
+Current Task: add-oauth
+Phase: 2 (Implementation)
+Status: in_progress
+
+Active Tasks:
+  - PHASE-2-1-1: Implement OAuth callback
+  - PHASE-2-1-2: Add user session management
+```
+
+---
+
+### `task-flow merge`
+
+合并完成的 worktree。
+
+```bash
+task-flow merge <task-id> [options]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<task-id>` | 任务 ID 或变更名称 |
+| `--dry-run` | 模拟执行，不实际合并 |
+| `--skip-review-check` | 跳过审查检查 |
+
+**示例**：
+```bash
+# 先检查
+task-flow merge add-oauth --dry-run
+
+# 实际合并
+task-flow merge add-oauth
+```
+
+---
+
+### `task-flow archive`
+
+归档任务状态。
+
+```bash
+task-flow archive --task-id <id> --event <event>
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--task-id <id>` | 任务 ID |
+| `--event <event>` | 事件类型：completed/abandoned/blocked |
+
+---
+
+### `task-flow sync`
+
+同步任务状态到 spec 文档。
+
+```bash
+task-flow sync --task-id <id>
+```
+
+---
+
+## 完整工作流示例
+
+### 场景：添加用户认证功能
+
+```bash
+# 1. 初始化（首次）
+task-flow init
+
+# 2. 分析项目
+task-flow analyze --output /tmp/context.json
+
+# 3. 编辑 context.json（可选）
+# 补充项目理解、风险分析等
+
+# 4. 生成 PRD
+task-flow extract --change add-auth --context-file /tmp/context.json
+
+# 5. 编辑 PRD
+vim spec/changes/add-auth/product-requirement.md
+
+# 6. 生成技术设计
+task-flow design --change add-auth --context-file /tmp/context.json
+
+# 7. 编辑技术设计
+vim spec/changes/add-auth/design.md
+
+# 8. 生成任务
+task-flow tasks --change add-auth --yes
+
+# 9. 创建工作区
+task-flow worktree --change add-auth --yes
+
+# 10. 开发
+cd .worktrees/harness-feat-add-auth
+pnpm install
+# ... 编码 ...
+
+# 11. 验证
+pnpm build && pnpm test && pnpm lint
+
+# 12. 提交
+git add .
+git commit -m "feat: add user authentication"
+
+# 13. 回到主仓库并合并
+cd ../..
+task-flow merge add-auth --dry-run  # 先检查
+task-flow merge add-auth            # 实际合并
+
+# 14. 查看状态
+task-flow status
+```
+
+---
+
+## 配置文件
+
+### `.harnessrc`
+
+项目配置文件：
+
+```json
+{
+  "projectRoot": ".",
+  "specRoot": "spec",
+  "worktreeDir": ".worktrees",
+  "hooks": {
+    "enabled": true,
+    "configPath": ".harness/hooks.json"
+  }
+}
+```
+
+### `.harness/hooks.json`
+
+Hooks 配置：
+
+```json
+{
+  "version": "1.0",
+  "hooks": {
+    "pre-design": [
+      {
+        "name": "check-prd-exists",
+        "script": "src/hooks/check-prd-exists.js",
+        "enabled": true,
+        "timeout": 5000
+      }
+    ],
+    "post-task-complete": [
+      {
+        "name": "phase-gate-validator",
+        "script": "src/hooks/phase-gate-validator.js",
+        "enabled": true,
+        "timeout": 30000
+      }
+    ]
+  }
+}
+```
+
+---
+
+## 故障排除
+
+### 命令执行失败
+
+```bash
+# 检查状态
+task-flow status
+
+# 查看日志
+cat .harness/state.json
+
+# 强制重新初始化
+task-flow init --force
+```
+
+### Worktree 冲突
+
+```bash
+# 检查现有 worktree
+git worktree list
+
+# 删除冲突的 worktree
+git worktree remove .worktrees/harness-feat-xxx
+```
+
+### 合并失败
+
+```bash
+# 跳过审查检查
+task-flow merge <name> --skip-review-check
+
+# 手动合并
+cd .worktrees/harness-feat-xxx
+git checkout main
+git merge feat-xxx
+```
+
+---
+
+## 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `TASK_FLOW_DEBUG` | 启用调试模式 |
+| `TASK_FLOW_CONFIG` | 自定义配置文件路径 |
+| `TASK_FLOW_NO_COLOR` | 禁用彩色输出 |