agent自我诊断

技能文档

---
description: agent自我诊断skill。对目标智能体目录执行全面健康度诊断，输出百分制评分报告（含缺失、矛盾、冗余、隐私泄漏、Harness成熟度等六类检测+一类评估）。当用户提到'智能体诊断'、'Agent健康检查'、'智能体自检'、'诊断报告'、'健康度评估'、'agent diagnose'时务必使用此技能。即便用户未明确提到诊断，只要涉及智能体质量评估、配置检查、Agent健壮性审查也应主动触发。
version: 1.9.3
files:
  - SKILL.md
  - diagnostic/
  - rules/
  - templates/
  - scripts/
name: agent-self-diagnose
x-source: aone-open
install_source: aone-kit
install_method: cli
name_zh: agent-self-diagnose
---

# 智能体自我诊断引擎

## 概述

对任意智能体目录执行**诊断先行**的全面健康检查，输出结构化诊断报告。核心原则：先诊断 → 出报告 → 自动推荐改造策略 → 用户确认 → 逐项执行。

> **Windows 运行提示**：诊断脚本在 QoderWork 的 bash 环境中须用 `py -X utf8 scripts/diagnose.py ...` 调用（`python` / `python3` 不在 PATH，直接调用会报 EXIT=127），完整命令见步骤2。

## 框架位置

诊断引擎代码随本 SKILL 一起分发，位于 SKILL 目录内：

```
agent-self-diagnose/
├── SKILL.md            # 本文件
├── scripts/
│   └── diagnose.py     # 诊断入口脚本
├── diagnostic/         # 诊断引擎（12个检查器 + 报告生成器）
├── rules/              # 诊断规则库（common.yaml + 平台专属规则）
└── templates/          # 目录结构参考（qoderwork-agent / devix-agent）
```

## 资源文件使用指引

### rules/ — 诊断规则库

| 文件 | 内容 | 何时阅读 |
|------|------|----------|
| common.yaml | 通用规则：Harness成熟度五维度定义、七大模块缺失检测项、矛盾检测模式、冗余识别模式、命名规范、评分权重 | 需要向用户解释某项评分的判定标准时；需要核对或调整检测逻辑时 |
| qoderwork.yaml | QoderWork 平台专属规则：MCP 工具检查、本地数据安全规则 | 目标为 QoderWork 智能体且需要平台专属检测细节时 |
| devix.yaml | Devix 平台专属规则：CLI 工具检查、多用户隔离规则 | 目标为 Devix 智能体且需要平台专属检测细节时 |

注意：诊断引擎（diagnostic/）已内嵌了 rules/ 中的规则逻辑，**正常运行诊断时 agent 无需手动读取 rules/**。仅当用户追问"为什么这么判"或"评分标准是什么"时，才需要打开对应 YAML 向用户展示具体规则。

### templates/ — 目录结构参考

| 路径 | 内容 | 何时阅读 |
|------|------|----------|
| qoderwork-agent/ | QoderWork 智能体的标准目录骨架 + harness/constraints.yaml 示例 | 用户确认改造项后，需要为 QoderWork 智能体补充缺失模块时 |
| devix-agent/ | Devix 智能体的标准目录骨架 + harness/constraints.yaml 示例 | 用户确认改造项后，需要为 Devix 智能体补充缺失模块时 |

使用场景：步骤4用户确认改造后，agent 参考 templates/ 中对应平台的目录结构，在目标智能体目录中创建缺失的目录和基础配置文件。**仅参考结构和示例文件，不覆盖目标已有内容。**

## 执行流程

### 步骤1：获取目标Agent路径

向用户确认要诊断的智能体目录路径。如果用户未提供，主动询问。

### 步骤2：运行诊断脚本

在 SKILL 目录下执行：

```bash
# Windows（QoderWork bash 环境无 python 命令，须用 py 启动器）
py -X utf8 scripts/diagnose.py <目标Agent目录路径> --format markdown

# macOS / Linux
python3 scripts/diagnose.py <目标Agent目录路径> --format markdown
```

**Windows 注意**：QoderWork 的 bash shell 中 `python` / `python3` 不在 PATH（EXIT=127），必须使用 Windows Python Launcher `py`。`-X utf8` 确保中文路径和报告输出不乱码。

支持 `--format text`（纯文本）或 `--format markdown`（默认）。

脚本会自动完成：平台检测 → 目录扫描 → 9个检查器逐项运行 → 风险评估 → 生成报告。

### 步骤3：解读报告

报告输出后，向用户解释：
- **总体健康度**：百分制得分 + 等级（优秀/良好/待优化/严重不足）
- **各模块得分**：哪些模块强、哪些弱
- **关键问题**：按优先级排序，重点标红
- **改造建议**：区分"安全改造"和"需谨慎改造"

### 步骤4：用户确认改造项

让用户逐项确认：
- 哪些**立即执行**
- 哪些**调整后执行**
- 哪些**暂不动**

报告会自动推荐改造策略（增量补充 / 先清理再补充 / 瘦身清理 / 紧急修复），
用户逐项确认后，Agent 按策略生成具体改造内容并执行。

**「QoderWork数据出端风险」误报判定规则（2026-09-03 实证）**：该检查器为关键词模式匹配（扫到上传/同步/PUT OSS 等词即报🔴），**不解析 AGENTS.md 白名单语义**——即使目标已在「数据出端边界」写明渠道级白名单+用户确认+可审计声明，复跑仍会报🔴且不影响百分制得分。处置规程：①先核查出端操作是否均为用户显式指令的交付通道（dws 发送/钉钉文档 OSS 托管/签名链等）；②是→在 AGENTS.md 隐私章节具名白名单并记变更记录，向用户说明"引擎关键词误报、已按白名单闭环"，**不要**为消警而删除业务通道或反复改文档；③否→真风险，按紧急修复处理。

## 评分体系（百分制）

| 模块 | 满分 |
|------|------|
| 智能体.md完整性 | 18 |
| Harness成熟度 | 13 |
| Prompt工程 | 11 |
| 隐私防泄漏 | 11 |
| 工具集成 | 9 |
| 任务编排 | 8 |
| 记忆系统 | 8 |
| 知识管理 | 8 |
| 可观测性 | 7 |
| 自我总结迭代 | 5 |
| 命名规范 | 2 |

等级：>=90 优秀 / 70-89 良好 / 50-69 待优化 / <50 严重不足

## 双轨制说明

引擎自动检测平台类型（QoderWork / Devix），加载对应规则：
- **QoderWork**：本地桌面/通义模型/MCP协议 → 重点关注数据不出端、本地日志
- **Devix**：云端/Claude Code/CLI工具链 → 重点关注多用户隔离、内网数据安全

## 六类检测 + 一类评估

1. **缺失检测**：七大模块逐项扫描，标记缺失项
2. **矛盾检测**：Prompt内部矛盾、跨模块冲突、平台不适配
3. **冗余检测**：死工具、死知识、重复Skill、僵尸编排
4. **Agent.md诊断**：定义文件完整性、与实现一致性
5. **Skill沉淀**：识别可抽取为独立Skill的散落内容
6. **隐私防泄漏**：硬编码凭证、动态泄漏路径、防护机制
7. **Harness成熟度评估**：约束优先/可验证性/渐进信任/故障假设/状态管理（L1-L5等级）

## 诊断报告输出示例（精简版）

以下为报告的核心结构示例，实际输出包含更多细节：

```
# 智能体诊断报告

| 属性 | 值 |
|------|----|
| 诊断目标 | /path/to/my-agent |
| 平台类型 | QoderWork |
| 诊断时间 | 2026-07-07 22:00:00 |

## 总体健康度
得分：62.5 / 100
等级：待优化

## 模块得分明细
| 模块 | 得分 | 满分 |
|------|------|------|
| 智能体.md完整性 | 8.0 | 18 |
| Prompt工程 | 7.5 | 11 |
| Harness成熟度 | 4.0 | 13 |
...

## 诊断发现
### 缺失项
- 🔴 缺少 memory/ 目录（记忆系统未配置）
- 🟠 缺少 knowledge/ 目录（知识管理未配置）

### 矛盾项
- 🟠 Prompt中声明了工具调用能力但 tools/ 未注册对应工具

## 改造策略建议
推荐策略：增量补充
判定依据：诊断发现中 65% 为缺失项，主要问题是模块不完整
行动建议：
1. 优先补充高优先级缺失项
2. 每次补充后重跑诊断验证得分提升
3. 现有配置无需改动，只做加法
```

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。