148 lines
3.6 KiB
Markdown
148 lines
3.6 KiB
Markdown
# 03-白板同步检查提示词
|
||
|
||
> 校验白板与实际代码的一致性
|
||
|
||
## 使用场景
|
||
|
||
- PR/MR 合并前检查白板是否需要更新
|
||
- 定期审计架构文档准确性
|
||
- 发现代码中的隐式依赖
|
||
|
||
## 提示词
|
||
|
||
```markdown
|
||
你是一个代码与架构一致性检查专家。请对比以下白板和代码，找出不一致之处。
|
||
|
||
## 输入
|
||
|
||
Canvas 白板 JSON：
|
||
```json
|
||
{CANVAS_JSON}
|
||
```
|
||
|
||
项目代码路径：{PROJECT_PATH}
|
||
|
||
## 检查项
|
||
|
||
1. **节点完整性**
|
||
- 白板中的节点是否都有对应的代码文件/类？
|
||
- 代码中是否有白板未记录的重要模块？
|
||
|
||
2. **连线准确性**
|
||
- 白板连线是否反映真实的 import/调用关系？
|
||
- 代码中是否有白板未标注的依赖？
|
||
|
||
3. **分组正确性**
|
||
- 白板分组是否与目录结构一致？
|
||
- 是否有跨分组的异常依赖？
|
||
|
||
## 输出格式
|
||
|
||
### 🔴 严重不一致（必须修复）
|
||
| 类型 | 白板 | 代码 | 建议 |
|
||
|:---|:---|:---|:---|
|
||
| 缺失节点 | - | UserService.py | 添加到白板 |
|
||
| 错误连线 | A→B | A不调用B | 删除连线 |
|
||
|
||
### 🟡 轻微不一致（建议修复）
|
||
| 类型 | 白板 | 代码 | 建议 |
|
||
|:---|:---|:---|:---|
|
||
| 命名不一致 | user_service | UserService | 统一命名 |
|
||
|
||
### 🟢 一致性良好
|
||
- 节点覆盖率：{X}%
|
||
- 连线准确率：{Y}%
|
||
|
||
### 📋 修复建议
|
||
1. {具体修复步骤}
|
||
2. {具体修复步骤}
|
||
```
|
||
|
||
## 自动化脚本（可选）
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
"""
|
||
canvas_sync_check.py - 白板与代码一致性检查脚本
|
||
|
||
用法：python canvas_sync_check.py project.canvas /path/to/project
|
||
"""
|
||
|
||
import json
|
||
import ast
|
||
import os
|
||
from pathlib import Path
|
||
|
||
def load_canvas(canvas_path):
|
||
with open(canvas_path) as f:
|
||
return json.load(f)
|
||
|
||
def extract_imports(py_file):
|
||
"""提取 Python 文件的 import 关系"""
|
||
with open(py_file) as f:
|
||
tree = ast.parse(f.read())
|
||
imports = []
|
||
for node in ast.walk(tree):
|
||
if isinstance(node, ast.Import):
|
||
for alias in node.names:
|
||
imports.append(alias.name)
|
||
elif isinstance(node, ast.ImportFrom):
|
||
if node.module:
|
||
imports.append(node.module)
|
||
return imports
|
||
|
||
def check_consistency(canvas, project_path):
|
||
"""对比白板节点与实际文件"""
|
||
canvas_nodes = {n['text'].split('\n')[0].strip('# ')
|
||
for n in canvas.get('nodes', [])}
|
||
|
||
actual_files = set()
|
||
for py_file in Path(project_path).rglob('*.py'):
|
||
actual_files.add(py_file.stem)
|
||
|
||
missing_in_canvas = actual_files - canvas_nodes
|
||
missing_in_code = canvas_nodes - actual_files
|
||
|
||
return {
|
||
'missing_in_canvas': missing_in_canvas,
|
||
'missing_in_code': missing_in_code,
|
||
'coverage': len(canvas_nodes & actual_files) / len(actual_files) * 100
|
||
}
|
||
|
||
if __name__ == '__main__':
|
||
import sys
|
||
if len(sys.argv) != 3:
|
||
print("用法: python canvas_sync_check.py <canvas_file> <project_path>")
|
||
sys.exit(1)
|
||
|
||
canvas = load_canvas(sys.argv[1])
|
||
result = check_consistency(canvas, sys.argv[2])
|
||
|
||
print(f"覆盖率: {result['coverage']:.1f}%")
|
||
if result['missing_in_canvas']:
|
||
print(f"白板缺失: {result['missing_in_canvas']}")
|
||
if result['missing_in_code']:
|
||
print(f"代码缺失: {result['missing_in_code']}")
|
||
```
|
||
|
||
## CI/CD 集成
|
||
|
||
```yaml
|
||
# .github/workflows/canvas-check.yml
|
||
name: Canvas Sync Check
|
||
|
||
on:
|
||
pull_request:
|
||
paths:
|
||
- '**.py'
|
||
- '**.canvas'
|
||
|
||
jobs:
|
||
check:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- name: Check canvas consistency
|
||
run: python scripts/canvas_sync_check.py docs/architecture.canvas src/
|
||
```
|