// 约定
copilot-instructions.md
Copilot 在这个代码仓库里该如何表现。
面向 GitHub Copilot CLI 用户
Copilot 每次会话都从一无所知开始。
自定义指令告诉 Copilot 该如何行事，却没有告诉它你的代码库里有什么。Maguyva 会对代码库建立索引，并通过 MCP 提供回来，让 GitHub Copilot CLI 编辑时就像已经读过代码一样。
Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。
用指令来约束行为，用 Maguyva 来获取当前代码库的真实情况。分层的技术栈
四个概念，各司其职。
自定义指令是一份工作约定，请善用它。
# .github/copilot-instructions.md
- 优先遵循现有的模块边界。
- 在提出合并之前运行仓库的测试命令。
- 不要臆造文件路径。创建新包前先确认。持久性指令应该放在 .github/copilot-instructions.md中。这是存放以下内容的合适位置：
- Copilot 应运行的构建、测试和 lint 命令。
- 仅适用于本仓库的“始终做 X／绝不做 Y”护栏规则。
- 命名规范和评审偏好。
- 指向决策日志的指针——而不是每个符号的堆砌。
那份文件从来都不是仓库可查询的索引。它告诉 Copilot 该如何工作，但不会告诉它仓库里有什么。
自定义指令在规模扩大后失效的地方
Copilot 无法仅凭一个 markdown 文件解决的四种失效模式。
// 指令不是索引
Telling Copilot how to behave does not tell it which class owns parseConfig, or which package actually implements the public API. 在陌生代码树上的第一次编辑，只是对文件结构的一种猜测。
// 文档会过时，代码不会
描述上一季度身份验证流程的指令块，会在有人拆分会话存储的那天彻底出错。 Copilot will prefer the file you committed over the code that shipped.
// 依赖关系不在 markdown 里
“是什么导入了这个？” is a graph question. 指令无法列出每一个调用者，而你其实也不会想要那样。
// 上下文窗口是有预算的
把更多仓库内容塞进指令，等于用推理 token 换取一份过时的快照。超过几 KB 之后，你付出的代价就是一份更差的地图。
作为附加层的 Maguyva
Copilot 已经在用指令和工具进行思考。
copilot-instructions.md
约定
Copilot 如何表现
MCP
通道
如何访问
Maguyva
代码库事实
它能看到什么
- 可查询的仓库地图 作为远程 streamable-HTTP 服务器通过 MCP 提供。
- 11 个面向客户的工具 涵盖语义、结构（AST）、图和文本搜索，外加符号、依赖方和文件检索。
- 带有文件路径和行号的排序结果 覆盖 284+ 种语言和基于文本的技术。
- 一份配置 同一个工作区在 Copilot、Claude Code、Cursor、Codex 以及任何其他兼容 MCP 的客户端中给出相同的回答。
自定义指令告诉 Copilot 该如何表现。
Maguyva 给 Copilot 提供一份可查询的代码地图。
三种工作流
在接受差异之前先向地图提问。
// workflow 01
找到真正的实现，而不是测试桩
copilot> normalizePhoneNumber 是如何处理 E.164 的？ semantic::query("normalize phone E.164") src/util/phone.ts:88 normalizePhoneNumber() ← 真实实现 test/util/phone.spec.ts:14 jest.mock(...) ← 桩代码 → Copilot 打开的是真实实现，而不是 mock。 [exit 0]
名字会骗人。Mock 会掩盖真实代码。Maguyva 会把真实实现排在测试 mock 之上。
// workflow 02
重构前检查影响范围
copilot> 什么调用了 QueueDispatcher.publish？ graph::callers(QueueDispatcher.publish) src/billing/* 中有 3 处 src/audit/* 中有 1 处 src/notifications/* 中有 1 处 → diff 以真实的导入者为依据。 [exit 0]
跨包调用点会直接内联显示出来。diff 以真实的导入者为依据，而不是 Copilot 的 grep 结果。
// workflow 03
重命名共享类，先找出每一个依赖方
copilot> rename PaymentClient → BillingClient graph::callers(PaymentClient) 7 个包中共 12 处引用 graph::importers(src/payments/client.ts) 9 个导入者 graph::extends(PaymentClient) 2 个子类（RetryClient、MockClient） → Copilot 提出的迁移方案中已内联包含文件列表。 [exit 0]
Copilot 会在开始编辑之前先向 Maguyva 询问依赖方。迁移列表返回时以真实的依赖图为依据，而不是 Copilot 的记忆。
在 GitHub Copilot CLI 中设置
三个步骤。Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。
// step 01
在 maguyva.ai 上为一个仓库建立索引
选择一个你已经熟悉的仓库，这样你就能评估答案的准确性。免费注册、连接 GitHub，然后等待索引完成。
// step 02
在 Copilot 中把 Maguyva 添加为远程 MCP 服务器
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp~/.copilot/mcp-config.json{ "mcpServers": { "maguyva": { "type": "http", "url": "https://maguyva.tools/mcp", "headers": { "Authorization": "Bearer mgv_xxxx" } } } }// step 03
提出一个你已经知道答案的问题
不要一开始就问整个公司范围的问题。先提出一个你已经知道答案的问题，然后打开被引用的文件。