内容
# 电源 BI 主导 MCP 服务器
允许 AI 代理作为 — 或在 — **电源 BI 主导** 下工作，
驱动八代理交付管道在
[`pbi-github-copilot-rag`](../pbi-github-copilot-rag) 知识库上。
它将该存储库的现有资产作为一流的 MCP 接口公开：
| MCP 接口 | 它承载的内容 |
|---|---|
| **资源** (39+) | RAG 语料库 — 聊天模式、技能指令、模板、主题、治理规则、工具注册表 — 加上实时工作流、审批和审计状态 |
| **提示** (11) | 每个代理（0–7）的委派合同，加上主导启动、发布审查和故障排除 |
| **工具** (32) | 知识搜索、六个可执行技能工具、脚手架、十二阶段工作流控制和人工审批门 |
针对 [`pbi-agentic-repos.md`](pbi-agentic-repos.md) 中的模型实现：
```
知识（RAG）+ 计划代理 + MCP 服务器 + 报告设计代理
+ 报告创作代理 + 桌面桥 + 报告管理代理
+ 人工审批门
```
---
## 安装
```bash
py -m pip install -r requirements.txt # 唯一依赖：mcp>=1.9.0
cp .env.example .env # 然后编辑路径
```
使用您的 MCP 客户端注册它 - 请参阅 [`mcp.json`](mcp.json) 以获取现成的区块：
```json
{
"mcpServers": {
"pbi-lead": {
"command": "py",
"args": ["-m", "pbi_lead_mcp"],
"env": {
"PYTHONPATH": "D:/PBI Agent/pbi-microsoft-mcp/src",
"PBI_RAG_ROOT": "D:/PBI Agent/pbi-github-copilot-rag",
"PBI_WORKSPACE_ROOT": "D:/PBI Agent/workspace"
}
}
}
}
```
验证：
```bash
py tests/smoke_test.py # 46 次检查：接口、门、脚手架、实时工具运行
```
---
## 八个代理
每个都是 MCP 提示 (`agent-<n>-<key>`) 和一个工具 (`pbi_agent_brief`)。简介是
委派合同：任务、RAG 阅读清单、允许的工具、输出文件夹、审批
门和硬规则。
| # | 代理 | 编写到 | 将要命中的门 |
|---|---|---|---|
| 0 | 计划器 | `plan/` | — |
| 1 | 语义模型 | `model/` | `write_tmdl`, `replace_semantic_model`, `delete_table`, `delete_measure` |
| 2 | 报告设计 | `design/` | — |
| 3 | 报告创作 | `report/` | — |
| 4 | 验证（桌面桥） | `screenshots/` | — |
| 5 | 性能 | `perf/` | — |
| 6 | 安全和合规 | `audit/` | — |
| 7 | 部署 | `releases/` | `publish_semantic_model`, `publish_report`, `deploy_production`, `refresh_dataset`, `modify_rls` |
---
## 十二阶段工作流
状态保存在 `<workspace>/.pbi-lead/workflow.json` 中。完成一个阶段会自动打开
下一个阶段。标记为 ✅ 的阶段无法在没有主导审批的情况下完成。
| # | 阶段 | 所有者 | 主导审批 |
|---|---|---|---|
| 1 | 需求收集 | 计划器 | ✅ |
| 2 | STTM 分析 | 计划器 | |
| 3 | 语义建模 | 语义模型 | ✅ |
| 4 | DAX 开发 | 语义模型 | |
| 5 | 报告设计 | 报告设计 | |
| 6 | PBIR 生成 | 报告创作 | |
| 7 | 桌面验证 | 验证 | |
| 8 | 性能优化 | 性能 | |
| 9 | 安全审查 | 安全 | ✅ |
| 10 | Fabric 部署 | 部署 | ✅ |
| 11 | 生产治理 | 安全 | |
| 12 | 持续知识扩展 | 计划器 | |
---
## 工具
### 发现
`pbi_server_info` · `pbi_knowledge_search` · `pbi_knowledge_get` · `pbi_knowledge_list` ·
`pbi_knowledge_reindex` · `pbi_tool_scan` · `pbi_list_agents` · `pbi_agent_brief` · `pbi_get_theme`
### 可执行技能 — RAG 存储库的 Python 工具的包装器
`pbi_extract_semantic_model` · `pbi_extract_report` · `pbi_parse_sttm` ·
`pbi_validate_dax` · `pbi_scan_secrets` · `pbi_check_governance`
### 脚手架
`pbi_scaffold_repository` · `pbi_scaffold_plan` · `pbi_scaffold_pbip` ·
`pbi_desktop_bridge_plan` · `pbi_deployment_plan` · `pbi_knowledge_contribute`
### 工作流
`pbi_workflow_start` · `pbi_workflow_status` · `pbi_workflow_stage` · `pbi_workflow_set_stage`
### 审批门
`pbi_list_gated_actions` · `pbi_request_approval` · `pbi_decide_approval` ·
`pbi_list_approvals` · `pbi_check_approval`
### 审计
`pbi_audit_log` · `pbi_audit_tail`
---
## 安全模型
RAG 存储库的 `copilot-instructions.md` 中的规则 **G-A1..G-A6** 被带入每个
代理简介并在结构上强制执行，而不仅仅是提示：
- **没有凭证表面。** 此服务器中的任何工具都无法读取、铸造、存储或
传输令牌。`.env` 中没有可以容纳令牌的字段。
- **关闭失败的门。** 十个操作 — 连接、发布、部署、删除表/度量、
替换模型、写入 TMDL、刷新、修改 RLS — 在没有签名的门的情况下被阻止。
门户范围为 `(action, target)`，单次使用，60 分钟后过期。
- **只有人类签名。** `pbi_decide_approval` 需要 `PBI_LEAD_APPROVAL_TOKEN`。
如果它未设置，则 *nothing* 可以在频带中签名 - 缺失的令牌永远不会降低到“允许”。
- **默认审计。** 每个工具运行、门决策和阶段转换都会追加到
`docs/audit-trail.log`。输入 *keys* 被记录，而非值。
- **知识库不能用机密污染。** `pbi_knowledge_contribute`
拒绝匹配机密模式的内容 - 语料库被重新提供给每个代理。
- **桌面桥是计划的，而不是驱动的。** `pbi_desktop_bridge_plan` 为主导的工作站生成验证运行。
一个无人值守的代理控制一个身份验证的桌面会话将绕过 G-A3。
---
## 设计笔记
**子进程，而不是导入。** 六个 RAG 工具都无条件打印到 stdout，
其中两个 (`secrets_scanner`, `governance_checker`) 硬编码 `Path(".")` 作为其输出
根目录。进程内导入它们将损坏 stdio JSON-RPC 流，并使输出
位置依赖于一个有竞争力的 `os.chdir`。每个都在子进程中运行，具有明确的 `cwd`
和捕获的 stdout。三个工具还对 *findings* 执行 `sys.exit(1)` - 桥接器
将其视为“存在发现”，而不是失败。
**词汇 RAG，而不是向量。** 语料库是 ~250 个精选文档。BM25-ish 索引超过
标题分割块的击败矢量存储在延迟、确定性和可审计性方面 -
并且每个命中都引用确切的路径、标题和行，这是治理审查者
需要的。`pbi_knowledge_reindex` 重新构建它。
**具体资源，而不是 URI 模板。** FastMCP 编译 `{param}` 到 `[^/]+`，因此模板
永远无法匹配嵌套路径，如 `.github/instructions/<agent>/<file>.md`。
精选文档单独注册，这也使得语料库可以通过 `resources/list` 发现。
~200 个 `LearningSample` 数据文件被排除在资源列表之外，并且可以通过 `pbi_knowledge_get` 访问。
---
## 已知上游问题
`pbi-github-copilot-rag/LearningSample/` 下的所有 11 个 `.pbix` 文件都是 33–93 字节的存根，
不是真正的存档（`zipfile.is_zipfile` 对于每个文件都是 `False`）。`pbi_extract_semantic_model`
和 `pbi_extract_report` 无法针对它们进行练习 - 烟雾测试断言一个干净
错误并验证桥接器针对存在的 208 个真实 `.tmdl` 文件。替换
这些存根与真正的 PBIX 文件以端到端测试提取。
---
## 布局
```
pbi-microsoft-mcp/
├── README.md · mcp.json · pyproject.toml · requirements.txt · .env.example
├── pbi-agentic-repos.md ← 本规范的实现
├── src/pbi_lead_mcp/
│ ├── server.py ← FastMCP 组件：资源、提示、工具
│ ├── config.py ← 路径 + 环境解析（无凭证字段）
│ ├── rag.py ← 词汇知识索引 + 注册表扫描
│ ├── tools_bridge.py ← 六个技能工具的子进程执行
│ ├── agents.py ← 八个代理的名册和简介
│ ├── workflow.py ← 十二阶段管道与门强制执行
│ ├── approvals.py ← 人工审批门
│ ├── scaffold.py ← 存储库 / 计划 / PBIP / 桥 / 部署生成器
│ └── audit.py ← 追加审计轨迹
└── tests/smoke_test.py ← 46 个端到端检查在一个真正的 MCP 会话中
```
