Agent Skills › zts212653/clowder-ai › workspace-navigator

workspace-navigator

GitHub

解析模糊导航意图，通过搜索定位工作区内的文件或目录路径，调用MCP工具自动在Hub右侧面板打开或展开目标资源，辅助用户快速访问代码、日志及文档。

cat-cafe-skills/workspace-navigator/SKILL.md zts212653/clowder-ai

Trigger Scenarios

用户要求打开日志、设计图、特定文档或功能相关代码用户提及文件关键词、Feature编号或描述需查看的内容

Install

npx skills add zts212653/clowder-ai --skill workspace-navigator -g -y

More Options

Non-standard path

npx skills add https://github.com/zts212653/clowder-ai/tree/main/cat-cafe-skills/workspace-navigator -g -y

Use without installing

npx skills use zts212653/clowder-ai@workspace-navigator

指定 Agent (Claude Code)

npx skills add zts212653/clowder-ai --skill workspace-navigator -a claude-code -g -y

安装 repo 全部 skill

npx skills add zts212653/clowder-ai --all -g -y

预览 repo 内 skill

npx skills add zts212653/clowder-ai --list

SKILL.md

Frontmatter

{
    "name": "workspace-navigator",
    "triggers": [
        "打开文件",
        "看看代码",
        "看日志",
        "帮我打开",
        "一起看看",
        "打开设计图",
        "看看这个文档",
        "打开 discussion",
        "看看 feature",
        "打开审计日志",
        "看看 spec",
        "帮我找到",
        "打开那个"
    ],
    "description": "猫猫可编程导航 Workspace 面板：operator说模糊意图，猫猫找到路径，自动打开文件\/目录。 Use when: operator说\"打开日志\"\"看看代码\"\"打开设计图\"\"帮我打开那个文档\"等模糊指令。 Not for: 打开 localhost 前端页面（用 browser-preview）、纯代码编写（不涉及展示给operator看）。 Output: Hub 右侧 Workspace 面板自动打开并导航到目标文件\/目录。\n"
}

Workspace Navigator

operator说"帮我打开XXX"时，你要自己找到路径，然后用 cat_cafe_workspace_navigate 让 Hub 右面板自动导航到那里。operator不会给你精确路径——这是你的活。

核心工作流（三步走）

Step 1: 意图解析 — operator想看什么？
  "帮我打开日志" → 日志文件/目录
  "看看 F131 的设计图" → F131 相关的 .pen 文件
  "打开那个 discussion" → 讨论文档

Step 2: 路径搜索 — 用你的工具找到精确路径
  用 glob/grep/read 找到文件的相对路径（相对于 worktree 根目录）

Step 3: 调 typed MCP — 让 Hub 前端导航
  cat_cafe_workspace_navigate({
    path: "找到的相对路径",
    action: "open",
    worktreeId: "目标worktree",
    threadId: "当前 threadId（有就传）"
  })

Step 2 详解：意图→路径匹配策略

这是本 skill 的核心硬实力。不同意图用不同搜索策略：

场景速查表

operator说的	搜索策略	示例命令
"打开日志" / "看日志"	快捷方式：右侧状态面板底部「运行日志 → 查看日志」按钮。也可用 `cat_cafe_workspace_navigate`	按钮会自动打开最新 .log 文件
"看审计日志"	审计日志在 `packages/api/data/audit/` 下	`glob("packages/api/data/audit/**")`
"打开 F131 的文档"	Feature 文档在 `docs/features/` 下	`glob("docs/features/F131*")`
"看看 F131 的设计图"	Pencil 设计文件	`glob("*/F131.pen")` 或 `glob("designs/F131*")`
"打开那个 discussion"	讨论文档在 `feature-discussions/` 下	`glob("feature-discussions/*")`
"看看 chatStore"	源码文件名搜索	`glob("*/chatStore*")`
"打开 BACKLOG"	已知位置	直接用 `docs/ROADMAP.md`
"看看 plans"	计划目录	直接用 `feature-specs/`
"打开那个 skill"	Skill 文档	`glob("cat-cafe-skills/*/SKILL.md")`
"看看 spec" + 上下文	从对话上下文推断是哪个 Feature	推断 Feature ID → `glob("docs/features/Fxxx*")`

搜索策略优先级

已知位置直达 — 日志、BACKLOG、SOP 等有固定位置的，不需要搜
Feature ID 匹配 — operator提到 F 编号，直接 glob("**/F{num}*")
文件名 glob — operator提到文件名关键词，glob("**/*关键词*")
内容 grep — operator描述的是文件内容而非文件名，用 grep("内容关键词")
目录浏览 — 不确定时先 reveal 目录，让operator自己挑

多结果处理

如果搜索返回多个匹配：

≤ 3 个：列出让operator选，或者按上下文判断最可能的那个打开
> 3 个：缩小搜索范围（加更多关键词），或者 reveal 到父目录让operator浏览

路径格式要求

必须是相对路径（相对于 worktree 根目录），不要传绝对路径
例：packages/api/data/logs/api/2026-03-21.log，不是 /home/user/.../2026-03-21.log
目录路径末尾带不带 / 都行

Step 3 详解：调用 `cat_cafe_workspace_navigate`

工具参数

参数	必填	说明
`path`	是	目标文件或目录的相对路径
`action`	否	`reveal`（展开目录树到目标，默认）或 `open`（打开文件查看器）
`worktreeId`	是	指定在哪个 worktree 里导航。API 需要此字段来解析路径
`threadId`	建议传	当前 thread ID，用于防止多 tab 串扰。传了只有对应 tab 响应

action 选择

目标	用什么 action	效果
目录（如 `packages/api/data/logs/`）	`reveal`	展开文件树到该目录，不打开任何文件
文件（如 `docs/features/F131-workspace-navigator.md`）	`open`	打开文件查看器显示文件内容
不确定	`reveal`	安全默认——展开到那里让operator自己看

调用示例

场景	调用
打开日志目录	`cat_cafe_workspace_navigate({ path: "packages/api/data/logs/api/", action: "reveal", worktreeId: "cat-cafe-runtime" })`
打开 Feature 文档	`cat_cafe_workspace_navigate({ path: "docs/features/F131-workspace-navigator.md", action: "open", worktreeId: "cat-cafe" })`
打开到某一行	`cat_cafe_workspace_navigate({ path: "packages/web/src/stores/chatStore.ts", action: "open", worktreeId: "cat-cafe", line: 1273 })`

如果 MCP 工具不可用，先说明工具面缺失并按 F223 追踪；不要把手写第一方 curl localhost 当主路径。

什么时候主动用

operator说"帮我打开XXX" → 立刻搜索 + 导航，不要只回复路径让operator自己找
operator说"一起看看这个日志" → 打开日志目录
讨论 Feature 时提到 spec → 主动打开 spec 文档
Debug 时提到某个文件 → 主动打开让operator和你一起看
operator说"看看设计图" → 找到 .pen 文件并打开

面板快捷入口（F130）

右侧状态面板底部有内置快捷按钮，不需要走 cat_cafe_workspace_navigate：

按钮	位置	效果
运行日志 → 查看日志	右侧状态面板，AuditExplorerPanel 下方	自动展开到 `packages/api/data/logs/api/` 并打开最新 `.log` 文件

operator说"看日志"时，告诉operator点右侧面板的按钮比你调工具更快。你也可以用 cat_cafe_workspace_navigate 代替。

不要做的事

不要只回复路径让operator自己去点 — 你的价值是「帮operator打开」，不是「告诉operator路径」
不要问operator要精确路径 — 你自己能搜到，这是你的活
不要和 browser-preview 混淆 — workspace-navigator 打开文件/目录；browser-preview 打开 localhost 网页
不要传绝对路径 — API 只接受相对路径
不要瞎猜路径不验证 — 先 glob/grep 确认文件存在，再调 API

和其他 skill 的区别

Skill	关注点
workspace-navigator（本 skill）	帮operator在 Hub Workspace 面板打开文件/目录
`browser-preview`	在 Hub Browser 面板预览 localhost 前端页面
`tdd`	写代码的测试驱动纪律
`quality-gate`	开发完成后的自检

常见问题

现象	原因	修法
右侧无反应	Hub/API 没跑 / 路径不存在 / MCP callback 未配置	检查工具返回错误；确认路径存在
打开了错误的文件	glob 匹配到了多个，选了错的	列出所有匹配让operator确认
worktree 切换失败	worktreeId 不存在	查看当前 Workspace worktree 列表或改传正确 worktreeId
面板没自动打开	Socket 连接可能断了	刷新 Hub 页面重试