导航器任务管理技能
创建和管理任务文档 - 实施计划，记录构建内容、方式和原因。
何时调用
当用户：
- 说“记录这个特性”、“归档这个任务”
- 说“为…创建任务文档”、“记录我构建的内容”
- 完成特性并提到“完成”、“结束”、“完成”
- 开始新特性并说“创建实施计划”
不要调用如果：
- 用户询问现有任务（使用阅读，而不是创建）
- 创建SOPs（那是nav-sop技能）
- 更新系统文档（不同技能）
执行步骤
第1步：确定任务ID
如果用户提供任务ID（例如，“TASK-01”、“GH-123”）：
- 直接使用他们的ID
如果没有提供ID：
- 读取
.agent/.nav-config.json中的task_prefix - 检查现有任务：
ls .agent/tasks/*.md - 生成下一个编号：
{prefix}-{next-number} - 示例：上一个任务是TASK-05，创建TASK-06
第2步：确定操作（创建与归档）
创建新任务（开始特性）：
用户：“为OAuth实现创建任务文档”
→ 操作：CREATE
→ 生成空的实施计划模板
归档完成的任务（特性完成）：
用户：“记录我刚刚构建的OAuth特性”
→ 操作：ARCHIVE
→ 从对话中生成实施计划
第3A步：创建新任务（如果开始特性）
从模板生成任务文档：
# TASK-{XX}: {特性名称}
**状态**：🚧 进行中
**创建**：{YYYY-MM-DD}
**指派人**：{来自PM工具或“手动”}
---
## 上下文
**问题**：
[这个解决什么问题？]
**目标**：
[我们正在构建什么？]
**成功标准**：
- [ ] [具体的可衡量结果]
- [ ] [另一个结果]
---
## 实施计划
### 第1阶段：{名称}
**目标**：[这个阶段完成的内容]
**任务**：
- [ ] [具体任务]
- [ ] [另一个任务]
**文件**：
- `path/to/file.ts` - [目的]
### 第2阶段：{名称}
...
---
## 技术决策
| 决策 | 考虑的选项 | 选择 | 理由 |
|----------|-------------------|--------|-----------|
| [什么] | [选项A、B、C] | [选择] | [为什么] |
---
## 依赖项
**需要**：
- [ ] {先决任务或设置}
**阻塞**：
- [ ] {等待此任务的任务}
---
## 验证
运行这些命令以验证实现：
```bash
# 运行测试
[此特性的测试命令]
# 类型检查
[类型检查命令]
# 构建
[构建命令]
完成
可观察的结果证明完成：
- [ ] [特定文件/API存在并导出预期接口]
- [ ] [测试通过 - 指定计数或覆盖目标]
- [ ] [构建成功无错误]
- [ ] [用户可观察行为按指定工作]
笔记
[任何额外的上下文、链接、参考资料]
完成清单
标记完成前：
- [ ] 实现完成
- [ ] 测试编写并通过
- [ ] 文档更新
- [ ] 代码审查（如果团队）
- [ ] 部署/合并
最后更新：{YYYY-MM-DD}
保存到：`.agent/tasks/TASK-{XX}-{slug}.md`
### 第3B步：归档完成的任务（如果特性完成）
从对话中生成任务文档：
1. **分析对话**（最后30-50条消息）：
- 构建了什么？
- 如何实现的？
- 做出了什么决策？
- 修改了哪些文件？
2. **生成实施计划**：
```markdown
# TASK-{XX}: {特性名称}
**状态**：✅ 已完成
**创建**：{YYYY-MM-DD}
**完成**：{YYYY-MM-DD}
---
## 构建内容
[1-2段落总结特性]
---
## 实施
### 第1阶段：{实际完成的阶段}
**完成**：{日期}
**更改**：
- 创建`src/auth/oauth.ts` - OAuth提供程序集成
- 修改`src/routes/auth.ts` - 添加登录/登出端点
- 更新`src/config/passport.ts` - Passport配置
**关键代码**：
```typescript
// 示例关键实现
export const oauthLogin = async (req, res) => {
// 实现细节
};
第2阶段：{下一阶段}
…
技术决策
| 决策 | 选项 | 选择 | 理由 |
|---|---|---|---|
| 认证库 | next-auth, passport.js, auth0 | passport.js | 更好的OAuth流程控制，更小的捆绑包 |
| 令牌存储 | localStorage, cookies, sessionStorage | httpOnly cookies | XSS保护，自动传输 |
| 会话存储 | 内存，Redis, PostgreSQL | Redis | 快速，可扩展，与数据库分开 |
修改的文件
src/auth/oauth.ts（创建）- OAuth集成src/routes/auth.ts（修改）- 添加认证端点src/config/passport.ts（创建）- Passport设置tests/auth.test.ts（创建）- 认证测试README.md（更新）- OAuth设置说明
挑战与解决方案
挑战：OAuth回调URL不匹配
- 问题：生产中的重定向失败
- 解决方案：添加环境特定的回调URL
- 提交：abc1234
挑战：会话跨重启持久性
- 问题：服务器重启后用户注销
- 解决方案：Redis会话存储
- 提交：def5678
测试
- ✅ 单元测试：
src/auth/*.test.ts（15测试，100%覆盖率） - ✅ 集成测试：OAuth流程端到端
- ✅ 手动测试：与Google、GitHub提供商测试
文档
- ✅ README更新OAuth设置说明
- ✅ 环境变量在
.env.example中记录 - ✅ API端点在
docs/api.md中记录
验证
执行的命令以验证：
# 实际验证期间运行的命令
npm test src/auth
npm run type-check
npm run build
结果：全部通过✅
完成
确认的结果：
- [x]
src/auth/oauth.ts导出OAuth提供程序集成 - [x] 所有测试通过（15测试，100%覆盖率）
- [x] 构建成功无错误
- [x] OAuth登录/登出流程正确工作
相关
创建的SOPs：
.agent/sops/integrations/oauth-setup.md
更新的系统文档：
.agent/system/project-architecture.md（添加认证部分）
完成：{YYYY-MM-DD} 实施时间：{X小时/天}
保存到：`.agent/tasks/TASK-{XX}-{slug}.md`
### 第3.5步：验证解释（ToM检查点 - 仅归档模式）[执行]
**重要**：这一步在归档任务时必须执行（不创建新任务）。
**在提交归档文档前，与用户确认解释**。
**显示验证**（仅对ARCHIVE操作）：
我从我们的会话中提取了这些： ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
构建内容：
- {FEATURE_SUMMARY}
捕获的关键决策：
- {DECISION_1}：{REASONING_1}
- {DECISION_2}：{REASONING_2}
修改的文件：{COUNT}总计
- {FILE_1} ({ACTION}：{PURPOSE})
- {FILE_2} ({ACTION}：{PURPOSE})
解决的挑战：
- {CHALLENGE_1}：{SOLUTION_1} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需要更正吗？[输入以继续/输入更正]
**始终验证ARCHIVE**，因为：
- 从对话中提取是基于推理的
- 用户可能做出了没有明确说明的决策
- 有些文件可能在对话之外被修改
- 确保准确的历史记录
**跳过CREATE的验证**，因为：
- 模板大多是空的
- 用户自己填写细节
- 没有推理风险
### 第4步：更新导航器索引
编辑`.agent/DEVELOPMENT-README.md`以将任务添加到索引：
```markdown
## 活跃任务
- **TASK-{XX}**：{特性名称}（状态：进行中/已完成）
- 文件：`.agent/tasks/TASK-{XX}-{slug}.md`
- 开始：{日期}
- [完成：{日期}]
保持索引组织（活跃任务首先，完成后下方）。
第4.5步：同步到知识图谱（v6.0.0+）
如果存在知识图谱，将任务同步到图谱：
if [ -f ".agent/knowledge/graph.json" ]; then
python3 skills/nav-graph/functions/task_to_graph.py \
--action add \
--task-path ".agent/tasks/TASK-{XX}-{slug}.md" \
--graph-path .agent/knowledge/graph.json
fi
这做什么：
- 从任务内容（auth, api, testing等）中提取概念
- 将任务节点添加到图谱，状态和概念
- 创建
implements边从任务到概念 - 对于已完成的任务：将技术决策作为
decision记忆提取
输出：
添加任务：TASK-XX
标题：{特性名称}
状态：已完成
概念：auth, api, testing
提取的决策：2
这使得任务可以通过“我们对auth了解什么？”进行查询，并将架构决策作为持久记忆保存。
第5步：更新PM工具（如果配置）
如果PM工具是Linear：
create_comment({
issueId: "TASK-XX",
body: "📚 实施计划记录：.agent/tasks/TASK-XX-feature.md"
})
如果PM工具是GitHub：
gh issue comment {ISSUE-NUMBER} -b "📚 实施计划：.agent/tasks/TASK-XX-feature.md"
如果PM工具没有： 跳过PM更新。
第6步：确认成功
显示完成消息：
✅ 任务文档创建！
任务：TASK-{XX} - {特性名称}
文件：.agent/tasks/TASK-{XX}-{slug}.md
大小：{X} KB（~{Y}令牌）
📋 包含：
- 实施阶段
- 技术决策
- 修改的文件
- [如果归档：挑战与解决方案]
- [如果归档：测试与文档]
🔗 导航器索引已更新
[如果PM工具：PM工具评论已添加]
以后参考：
阅读 .agent/tasks/TASK-{XX}-{slug}.md
任务文档模板结构
对于新任务（计划）
- 上下文（问题/目标）
- 实施计划（阶段）
- 技术决策（待定）
- 依赖项
- 完成清单
对于已完成的任务（归档）
- 构建内容（摘要）
- 实施（实际阶段）
- 技术决策（选择）
- 修改的文件
- 挑战与解决方案
- 测试与文档
常见用例
开始新特性
用户：“为支付集成创建任务文档”
→ 生成TASK-07-payments.md
→ 计划的空模板
→ 用户工作时填写
完成特性
用户：“记录我刚刚完成的认证特性”
→ 分析对话
→ 生成TASK-06-auth.md
→ 完整的实施记录
→ 归档以供将来参考
中间特性更新
用户：“更新TASK-05的OAuth决策”
→ 读取现有的TASK-05-auth.md
→ 添加到技术决策部分
→ 保留文档其余部分
错误处理
导航器未初始化：
❌ 未找到.agent/tasks/目录
运行/nav:init以设置导航器结构。
任务ID已存在（创建时）：
⚠️ TASK-{XX}已存在
选项：
1. 读取现有任务
2. 使用不同的ID
3. 归档/覆盖现有
您的选择[1-3]：
上下文不足以归档：
⚠️ 对话上下文不足以生成实施计划
考虑：
- 提供更多关于构建内容的详细信息
- 手动创建任务文档
- 跳过归档
继续使用模板？[y/N]：
成功标准
任务文档成功时：
- [ ] 在
.agent/tasks/中创建任务文件 - [ ] 文件名遵循约定：
TASK-{XX}-{slug}.md - [ ] 包含所有必需部分
- [ ] 导航器索引已更新
- [ ] PM工具已更新（如果配置）
- [ ] 用户以后可以引用任务
脚本
generate_task.py：从对话中创建任务文档
- 输入：对话历史，任务ID
- 输出：格式化的任务标记
update_index.py：更新DEVELOPMENT-README.md任务索引
- 输入：新任务信息
- 输出：更新的索引
最佳实践
好的任务slugs：
oauth-implementation（描述性）stripe-payment-flow（清晰目的）user-profile-page（特定特性）
坏的任务slugs：
feature（太模糊）fix（不描述性）task1（无意义）
何时创建任务文档：
- ✅ 开始主要特性（> 1天工作）
- ✅ 完成任何特性（归档）
- ✅ 复杂实现（捕获决策）
- ❌ 小型错误修复（使用SOPs代替）
- ❌ 探索性工作（等待方向明确）
注释
任务文档是活文档：
- 开始特性时创建（模板）
- 实施期间更新（决策）
- 完成后完成（归档）
它们作为：
- 计划工具（实施前）
- 进度跟踪器（实施期间）
- 历史记录（完成后）
- 知识库（团队/未来）
这个技能提供与/nav:doc feature命令相同的功能，但具有自然语言调用。