Skip to content

FAQ.md

Latest commit

 

History

History
180 lines (107 loc) · 5.62 KB

FAQ.md

File metadata and controls

180 lines (107 loc) · 5.62 KB
Raw

常见问题 (FAQ)

安装问题

安装完成后 /yu-help 不响应 / 技能不可用

Claude Code 需要重载才能识别新安装的技能。关掉当前会话，重新打开 Claude Code（或在 IDE 插件里点「重启」）。

技能安装在哪里？

~/.claude/skills/yu-*/    ← yu-* 技能
~/.claude/skills/bmad-*/  ← bmad-* 底层技能（自动安装）

可以用 ls ~/.claude/skills/ 确认安装结果。

npm update 后自定义的覆盖区丢了

~/.claude/skills/ 下的源文件每次 install 都会刷新。直接修改源文件的改动会丢失。

正确做法：把自定义写到 _bmad/custom/yu-xxx.toml（项目级）或 _bmad/custom/yu-xxx.user.toml（个人级），这两个位置 npm 永远不会碰。详见 自定义指南。

运行时错误

/yu-dev-story 说找不到 _bmad/ 或 Story 文件

两个可能原因：

  1. 没有初始化项目：进入 repo 后先运行一次：

    npx yu-method init

  2. Story 文件路径不对：Story 文件默认放在 _bmad-output/stories/，文件名格式 story-{number}.md。调用时指定文件名：

    /yu-dev-story story-1

/yu-dev-story 能跑但总是忽略我们的编码规范

在 _bmad/custom/yu-agent-dev.toml 里注入规范文档：

[agent]
persistent_facts = [
  "file:{project-root}/docs/coding-standards.md",
]

Agent 每次激活都会把这份文档加载为底层上下文，不需要每次手动提醒。

bmad-method 技能找不到 / 调用 /yu-xxx 时说底层命令不存在

postinstall 会自动安装 bmad-method，但偶尔因网络问题会失败。手动补装：

npm install -g bmad-method

然后重载 Claude Code。

/yu-prd 说这个需求规模太小，建议用 /yu-quick-dev

这是正常行为：/yu-prd 内置了误路由检测，识别到"快速实现"意图时会主动提示更合适的入口。接受建议，换用 /yu-quick-dev；或者明确告诉它"我确实需要完整 PRD"，它会继续。

yu-gbrain 知识库

yu-brain-setup 运行后重启 Claude Code，MCP 仍然提示未连接

检查顺序：

  1. 确认 .mcp.json 存在：cat .mcp.json，看是否有 yu-gbrain 条目
  2. 确认 GBRAIN_HOME 路径正确：~/.yu/gbrain 目录是否存在（ls ~/.yu/gbrain）
  3. 手动验证 gbrain 可以启动：GBRAIN_HOME=~/.yu/gbrain gbrain serve，看是否报错
  4. 重启整个 Claude Code 应用（不是关窗口，是退出重开），MCP 连接在进程级初始化

macOS 26 上 yu-gbrain 启动失败

macOS 26（Darwin 25.x 内核）的 PGLite WASM 有已知 bug，表现为 gbrain 启动时崩溃。

yu-brain-setup 会自动检测并安装 PostgreSQL@17 作为后端，完全绕过此问题。如果之前的安装没有触发这个分支，重新运行一次：

yu-brain-setup

脚本是幂等的，不会清除已有数据。

运行 /yu-brain-setup 时，个人知识库目录默认显示的是旧的 ~/Documents/yu/personal

说明 ~/.yu/config.json 里保存了旧路径。当前方案固定使用 ~/Documents/yu/brain/personal，重新运行 yu-brain-setup 会写入新路径。

往 ~/Documents/yu/brain/personal/ 放了 Markdown 文件，但知识库检索不到

yu-gbrain 不实时监听目录，需要手动触发向量化：

/yu-brain-sync

同步完成后才能被 /yu-gbrain:query 检索到。/yu-brain-sync 会自动完成向量化和链接/时间线抽取，无需额外操作。建议定期（每天或每周）运行一次。

想用已有的 Obsidian vault 作为个人知识库

运行 yu-brain-setup，选择从已有 Obsidian vault 复制 Markdown 到固定个人库：

~/Documents/yu/brain/personal

原始 vault 不会被修改。之后建议在 Obsidian 中打开新的个人库目录，或继续维护原 vault 并定期复制/同步到固定目录。

yu-gbrain 查询和系统默认 gbrain 会互相干扰吗？

不会。yu-gbrain 使用独立的 GBRAIN_HOME=~/.yu/gbrain，MCP 注册名为 yu-gbrain，与系统默认的 ~/.gbrain 和 gbrain MCP 完全隔离，两者可以并存。

使用问题

什么时候用 Agent，什么时候直接用技能？

场景 推荐
知道要做什么，直接执行 直接调用 /yu-xxx
不确定用哪个技能 激活对应阶段的 Agent（/yu-agent-pm、/yu-agent-dev 等）
需要多轮交互、深度调研 激活 Agent
跨多个阶段的大需求 /yu-team
完全不知道从哪开始 /yu-help

上下文太长导致技能效果变差

每个技能建议在新会话窗口中运行。上下文积累会稀释技能的系统指令权重，影响输出质量。如果遇到 Agent 开始"跑偏"或忽略约束，新开一个窗口重新激活即可。

怎么把 yu-method 用于 Codex？

  • 技能安装时会同时写入 ~/.codex/skills/，Codex 识别该目录下的技能。
  • yu-brain-setup 会自动把 yu-gbrain MCP 写入 ~/.codex/config.toml（[mcp_servers.yu-gbrain] 段），重启 Codex 后知识库工具即可用。
  • 如遇兼容问题，参考各技能的 SKILL.md，手动把核心提示词复制到 Codex 的系统提示。

卸载后重装，之前的知识库数据还在吗？

在。卸载 yu-method 只清除 ~/.claude/skills/yu-* 下的技能文件，不会碰 ~/.yu/gbrain/（知识库数据库）和 ~/Documents/yu/（知识库内容目录）。重装后运行 yu-brain-setup 重新注册 MCP，数据完整保留。

还有问题？