zeyu-docs-retrieval

# zeyu-docs-retrieval Skill **统一文档检索接口 - 为 OpenClaw Agent 编排系统提供三合一检索方案** 本 Skill 为 ZeYu AI Brain 知识库提供统一的文档检索接口，支持： - **YAML Frontmatter 快速定位**：快速理解项目定位、状态、技术栈 - **文档索引精确导航**：获取项目仓库中核心文档的精确路径 - **Smart Connections 语义搜索**：查找相关文档、历史解决方案 --- ## 治理规范适配（v2.2） 当用于任务编排时，遵循以下最小治理约束： - 入站自动化只写 `08-RAW-CONTEXT/00-PENDING`，不直接创建 ACTIVE 任务。 - Pending 必须人工确认后再晋升到 `03-ACTIVE-TASKS`。 - Pending 超过 24h 未确认，执行 TTL 归档到废弃区。 - 任务发布时应维护 `00-CURRENT.md` 唯一入口，并输出 final 的 Before→After 一句话 diff 摘要。 ## 快速开始（2 分钟） ### 前置条件 - Obsidian REST API 已启动（端口 27123） - Smart Connections 插件已安装并完成索引 - Python 3.10+ - 已配置 `config.yaml`（参见 README.md） - 运行时优先级：`.venv` > `/Users/lizeyu/miniforge/bin/python` > `python3` ### 最常用 8 个命令 ```bash # 1. 获取最新上下文快照（OpenClaw 优先读取） zdr snapshot # 2. 获取泽宇的当前状态（今日焦点/决策队列） zdr zeyu-status # 3. 列出所有活跃项目 zdr list-projects --status=active # 4. 获取项目的文档索引 zdr docs-index DiveBuddy # 5. 语义搜索全库 zdr search "权限管理" # 6. 生成富上下文（用于 Agent 派发） zdr context DiveBuddy --task="添加收藏功能" # 7. 按任务ID读取原始上下文（证据链） zdr task-source TASK-20260226-RESEARCH-01 # 8. 浏览原始上下文（可按日期） zdr raw-context --date=2026-02 ``` ### 快速验证 ```bash # 测试 API 连接 zdr list-projects # 预期输出： # ✓ 找到 5 个项目 # - DiveBuddy (active, high) # - AIMBSE (active, high) # - Co-Todo (paused, medium) # ... ``` --- ## 命令速查表（3 分钟） ### OpenClaw 核心命令（优先使用） | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `snapshot` | 获取最新上下文快照 | `zdr snapshot` | [详见](#snapshot) | | `zeyu-status` | 获取泽宇当前状态 | `zdr zeyu-status` | [详见](#zeyu-status) | | `team-status` | 获取团队负载状态 | `zdr team-status` | [详见](#team-status) | | `schedule` | 获取本周排期 | `zdr schedule` | [详见](#schedule) | | `decisions` | 获取待决策事项 | `zdr decisions` | [详见](#decisions) | **使用场景**：OpenClaw 每日 briefing、任务派发前快速获取全局状态 ### 原始上下文命令（证据链） | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `task-source` | 按任务ID读取原始上下文 | `zdr task-source TASK-20260226-RESEARCH-01` | [详见](#task-source) | | `raw-context` | 浏览原始上下文仓 | `zdr raw-context --date=2026-02` | [详见](#raw-context) | | `find-raw` | 语义检索原文仓 | `zdr find-raw "沈阳发动机所"` | [详见](#find-raw) | | `verify` | 校验证据链完整性 | `zdr verify` | [详见](#verify) | **使用场景**：先读任务原文，再写摘要/拆解，确保可追溯。 ### 项目定位类命令 | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `list-projects` | 列出所有项目 | `zdr list-projects` | [详见](#list-projects) | | `project-info` | 获取项目元数据 | `zdr project-info DiveBuddy` | [详见](#project-info) | | `filter-projects` | 按条件筛选项目 | `zdr filter-projects --status=active --priority=high` | [详见](#filter-projects) | **使用场景**：编排层选择项目、判断优先级 ### 文档导航类命令 | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `docs-index` | 读取文档索引 | `zdr docs-index DiveBuddy` | [详见](#docs-index) | | `get-doc` | 获取特定文档 | `zdr get-doc DiveBuddy CLAUDE.md` | [详见](#get-doc) | | `list-docs` | 列出某类文档 | `zdr list-docs DiveBuddy --category=开发` | [详见](#list-docs) | **使用场景**：执行层读取开发规范、架构文档 ### 语义搜索类命令 | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `search` | 全库语义搜索 | `zdr search "权限管理"` | [详见](#search) | | `search-project` | 限定项目搜索 | `zdr search-project "行程匹配" --project=DiveBuddy` | [详见](#search-project) | | `similar-to` | 查找相似文档 | `zdr similar-to 02-PROJECTS/DiveBuddy.md` | [详见](#similar-to) | **使用场景**：查找类似问题的解决方案、跨项目知识复用 ### 上下文注入类命令 | 命令 | 功能 | 示例 | 详细文档 | |------|------|------|----------| | `context` | 生成富上下文 | `zdr context DiveBuddy --task="添加收藏功能"` | [详见](#context) | | `cross-project` | 跨项目知识复用 | `zdr cross-project ygagentlanggraphLZY DiveBuddy --topic="RAG"` | [详见](#cross-project) | | `history` | 查找历史方案 | `zdr history "权限管理实现"` | [详见](#history) | **使用场景**：Agent 派发前注入上下文、复用历史经验 --- ## 命令详解 ### 原始上下文类 #### task-source 按任务ID读取原始上下文文件（证据链优先）。 ```bash zdr task-source TASK-20260226-RESEARCH-01 ``` #### raw-context 浏览原始上下文仓，支持按任务或日期过滤。 ```bash # 按日期浏览 zdr raw-context --date=2026-02 # 直接按任务读取 zdr raw-context --task=TASK-20260226-RESEARCH-01 ``` #### find-raw 在原始上下文仓中进行语义检索。 ```bash # 基本用法 zdr find-raw "沈阳发动机所" # 限制结果数量 zdr find-raw "AIMBSE调研" --limit=5 # 按敏感度过滤 zdr find-raw "调研" --sensitivity=internal # 输出 JSON 格式 zdr find-raw "调研" --format=json ``` **输出示例**： ``` ✓ 找到 2 条相关原文 1. TASK-20260226-RESEARCH-01 (相关度: 0.95) 路径: 08-RAW-CONTEXT/2026/2026-02/TASK-20260226-RESEARCH-01.md 摘要: 沈阳发动机所 AIMBSE 调研需求，4 大方向... 敏感度: internal 2. TASK-20260220-RESEARCH-02 (相关度: 0.72) 路径: 08-RAW-CONTEXT/2026/2026-02/TASK-20260220-RESEARCH-02.md 摘要: ... ``` #### verify 校验证据链完整性，检查任务是否有对应的原始上下文。 ```bash # 基本用法 zdr verify # 只检查特定任务 zdr verify --task=TASK-20260226-RESEARCH-01 # 修复断链（自动创建占位原文） zdr verify --fix ``` **输出示例**： ``` ✓ 证据链校验完成 检查项： - 任务总数: 5 - 有原文链接: 4 - 断链任务: 1 断链详情： - TASK-20260220-DEV-01: 缺少原始上下文文件 建议： 运行 `zdr verify --fix` 自动创建占位原文 ``` ### 项目定位类 #### list-projects 列出所有项目及其元数据。 ```bash # 基本用法 zdr list-projects # 按状态筛选 zdr list-projects --status=active # 按优先级筛选 zdr list-projects --priority=high # 组合筛选 zdr list-projects --status=active --priority=high # 输出 JSON 格式 zdr list-projects --format=json ``` **输出示例**： ``` ✓ 找到 5 个项目 DiveBuddy 状态: active 优先级: high 技术栈: Java, Vue3, WeChat Mini Program 仓库: /Users/lizeyu/Documents/DiveBuddy 描述: 潜水社交平台 AIMBSE 状态: active 优先级: high 技术栈: Python, LangGraph, RAG 仓库: /Users/lizeyu/Documents/AIMBSE 描述: AI 驱动的 MBSE 知识库 ``` **详细文档**：[reference/commands.md#list-projects](reference/commands.md#list-projects) --- #### project-info 获取单个项目的详细元数据。 ```bash # 基本用法 zdr project-info DiveBuddy # 输出 JSON 格式 zdr project-info DiveBuddy --format=json # 包含文档索引路径 zdr project-info DiveBuddy --include-docs-index ``` **输出示例**： ```yaml name: DiveBuddy status: active priority: high tech_stack: - Java - Vue3 - WeChat Mini Program repository: /Users/lizeyu/Documents/DiveBuddy description: 潜水社交平台 tags: - 社交 - 潜水 - 小程序 created: 2025-01-15 updated: 2026-02-26 docs_index: 02-PROJECTS/DiveBuddy-docs-index.md ``` **详细文档**：[reference/commands.md#project-info](reference/commands.md#project-info) --- #### filter-projects 按多个条件筛选项目。 ```bash # 按状态筛选 zdr filter-projects --status=active # 按优先级筛选 zdr filter-projects --priority=high # 按技术栈筛选 zdr filter-projects --tech=Java # 组合筛选 zdr filter-projects --status=active --priority=high --tech=Java # 按标签筛选 zdr filter-projects --tag=社交 ``` **详细文档**：[reference/commands.md#filter-projects](reference/commands.md#filter-projects) --- ### 文档导航类 #### docs-index 读取项目的文档索引。 ```bash # 基本用法 zdr docs-index DiveBuddy # 按类别筛选 zdr docs-index DiveBuddy --category=开发 # 按子项目筛选 zdr docs-index DiveBuddy --subproject=Wechat # 输出 JSON 格式 zdr docs-index DiveBuddy --format=json ``` **输出示例**： ``` DiveBuddy 文档索引 核心文档（按重要性排序）： 1. .hidden/CLAUDE.md - 开发规范 2. DiveBuddyWechat/ARCHITECTUREForWechat.md - 架构设计 3. DiveBuddyWechat/tasks.md - 当前任务 4. PROMPT_FOR_P0_FIX.md - P0 修复指南 子项目文档： - Wechat: 小程序前端（5 个文档） - AdminBackEnd: 管理后台（3 个文档） - AIService: AI 服务（4 个文档） 按场景分类： - 开发: 3 个文档 - 测试: 2 个文档 - 部署: 2 个文档 - 架构: 2 个文档 ``` **详细文档**：[reference/commands.md#docs-index](reference/commands.md#docs-index) --- #### get-doc 获取项目中的特定文档。 ```bash # 基本用法 zdr get-doc DiveBuddy CLAUDE.md # 获取子项目文档 zdr get-doc DiveBuddy Wechat/ARCHITECTURE.md # 输出到文件 zdr get-doc DiveBuddy CLAUDE.md --output=/tmp/claude.md # 只显示路径（不读取内容） zdr get-doc DiveBuddy CLAUDE.md --path-only ``` **输出示例**： ``` 文档路径: /Users/lizeyu/Documents/DiveBuddy/.hidden/CLAUDE.md --- 文档内容 --- # DiveBuddy 开发规范 ## 项目定位 潜水社交平台，支持行程发布、匹配、预订... [文档内容...] ``` **详细文档**：[reference/commands.md#get-doc](reference/commands.md#get-doc) --- #### list-docs 列出项目中某类文档。 ```bash # 列出所有开发相关文档 zdr list-docs DiveBuddy --category=开发 # 列出所有测试相关文档 zdr list-docs DiveBuddy --category=测试 # 列出子项目的所有文档 zdr list-docs DiveBuddy --subproject=Wechat # 列出所有文档 zdr list-docs DiveBuddy ``` **详细文档**：[reference/commands.md#list-docs](reference/commands.md#list-docs) --- ### 语义搜索类 #### search 全库语义搜索。 ```bash # 基本用法 zdr search "权限管理" # 限制结果数量 zdr search "权限管理" --limit=10 # 按相关度排序 zdr search "权限管理" --sort=relevance # 输出 JSON 格式 zdr search "权限管理" --format=json # 只显示文件路径 zdr search "权限管理" --path-only ``` **输出示例**： ``` ✓ 找到 5 个相关文档 1. DiveBuddy-docs-index.md (相关度: 0.92) 路径: 02-PROJECTS/DiveBuddy-docs-index.md 摘要: ...权限管理模块位于 AdminBackEnd...