moai-workflow-jit-docs

快速参考（30 秒）

目的：根据用户意图和上下文，按需加载相关文档。

主要工具：

• WebSearch：在线查找最新文档和资源
• WebFetch：获取特定文档页面
• Context7 MCP：访问官方库文档（如有）
• Read、Grep、Glob：搜索本地项目文档

触发模式：

• 用户提出具体技术问题
• 在对话中检测到技术关键词
• 完成任务需要领域专业知识
• 需要实施指导

实施指南

意图检测

系统通过多种模式识别文档需求：

基于问题的触发条件：

• 用户提出具体实施问题时（例如：“如何实现 JWT 身份验证？”）
• 用户寻求最佳实践或优化指导时
• 出现故障排查问题时

特定技术触发条件：

• 检测框架名称：FastAPI、React、PostgreSQL、Docker、Kubernetes
• 检测库名称：pytest、TypeScript、GraphQL、Redis
• 检测工具名称：npm、pip、cargo、maven

特定领域触发条件：

• 身份验证和授权主题
• 数据库和数据建模讨论
• 性能优化咨询
• 安全相关问题

基于模式的触发条件：

• 实施请求：“implement”“create”“build”
• 架构讨论：“design”“structure”“pattern”
• 故障排查：“debug”“fix”“error”“not working”

文档来源

系统按优先级顺序从多个来源获取文档：

本地项目文档（最高优先级）：

• 检查 .moai/docs/ 中是否有项目专属文档
• 检查 .moai/specs/ 中是否有需求和规格说明
• 检查 README.md 了解项目概况
• 检查 docs/ 目录中的完整文档

官方文档来源：

• 使用 WebFetch 获取官方框架文档
• 如有可用的库文档，则使用 Context7 MCP 工具
• 访问特定技术的官方网站

社区资源：

• 使用 WebSearch 查找优质教程
• 搜索高赞的 Stack Overflow 解决方案
• 查找针对特定问题的 GitHub 讨论

实时网络研究：

• 使用 WebSearch 并指定当前年份，以获取最新信息
• 搜索近期最佳实践和更新
• 查找新功能和弃用通知

加载策略

意图分析流程：

• 识别用户请求中提及的技术
• 确定与问题相关的领域
• 对问题类型进行分类（实施、故障排查、概念）
• 评估复杂度，以确定所需的文档深度

来源优先级：

• 如果存在本地文档：先加载项目专属文档
• 如果有官方文档：获取权威来源
• 如果需要实施示例：搜索社区资源
• 如果需要最新信息：进行网络研究

上下文感知缓存：

• 在会话中缓存获取的文档
• 根据当前对话上下文保持相关性
• 上下文发生变化时移除过时内容
• 优先使用频繁访问的文档

质量评估

内容质量评估：

• 权威性：官方来源的可信度最高
• 时效性：对于快速发展的技术，优先选择 12 个月内的内容
• 完整性：包含示例的文档排名更高
• 相关性：内容与用户意图的匹配程度

相关性排名：

• 计算文档内容与用户问题的匹配度
• 按权威性（30%）、时效性（25%）、完整性（25%）、相关性（20%）赋予权重
• 优先返回得分最高的文档
• 标明检索信息的置信度

实用工作流

身份验证实现工作流：

• 当用户询问身份验证时：检测所用技术（例如，FastAPI、JWT）
• 确定领域：身份验证、安全
• 通过 WebFetch 加载 FastAPI 安全文档
• 通过 WebSearch 搜索 JWT 最佳实践
• 提供全面的指导并注明来源

数据库优化工作流：

• 当用户询问查询性能时：检测数据库技术
• 确定领域：性能、优化
• 加载数据库官方文档
• 搜索优化指南和教程
• 提供可执行的建议并注明来源

采用新技术工作流：

• 当用户引入不熟悉的技术时：检测技术名称
• 加载官方入门文档
• 如果适用，搜索迁移指南
• 查找与现有技术栈的集成模式
• 提供采用策略指导

错误处理

网络故障：

• 如果网页搜索失败：回退到缓存内容
• 如果 WebFetch 失败：使用本地文档（如果有）
• 如果部分来源无法访问：说明结果不完整

内容质量问题：

• 如果检索到的内容似乎已过时：搜索较新的来源
• 如果相关性不明确：请用户澄清
• 如果发现信息冲突：列出多个来源及其日期

相关性不匹配：

• 如果初次搜索结果不理想：优化搜索查询
• 如果用户上下文不明确：加载文档前请求澄清
• 如果存在文档缺口：说明这一限制

性能优化

缓存策略：

• 为频繁访问的文档维护会话级缓存
• 将项目专属文档保留在内存中
• 根据访问时间清除过期内容

高效加载：

• 仅在明确需要时加载文档
• 避免预加载所有可能的文档
• 使用有针对性的搜索，而非宽泛查询

批处理：

• 尽可能合并相关搜索
• 按技术对文档请求分组
• 适当时并行处理多个来源

高级模式

多来源聚合：

• 将官方文档与社区示例结合
• 交叉参考多个权威来源
• 综合不同材料，形成全面的答案

上下文持久化：

• 记住对话中先前加载的文档
• 避免重复加载相同文档
• 在会话中逐步积累知识

主动加载：

• 根据对话进展预测文档需求
• 讨论复杂功能时预加载相关主题
• 在用户询问前推荐相关文档

---

配合使用效果良好

Agent：

• workflow-docs：文档生成
• core-planner：文档规划
• workflow-spec：SPEC 文档

技能：

• moai-docs-generation：文档生成
• moai-workflow-docs：文档验证
• moai-library-nextra：Nextra 文档

命令：

• /moai:3-sync：文档同步
• /moai:9-feedback：文档改进