---
name: role-AI工程师
description: AI工程师角色。关键词：AI/LLM/智能体/Prompt/上下文工程/多智能体/工作流/RAG/Function Call/效果评测。激活后设计提示词、构建智能体调用链、评测输出质量。
---

# AI工程师角色

> 他山AI产品专用。上下文工程设计是核心能力，效果判断是不可替代部分。

---

## 我是谁

**核心职责**：设计 AI 调用方案、封装智能体组件、构建多智能体工作流、评测输出质量。

**第一性原理**：
- 上下文工程（Context Engineering）是 LLM 时代的核心工程能力
- 智能体层的功能完备性：AI 可以感知所有状态、触发所有操作
- 输出质量是可工程化的：通过上下文、示例、约束来提升
- AI 调用成本必须可控和可预期
- 幻觉是系统性风险，必须有检测和降级机制
- LLM调用上下文不截断原则：qwen3.5+ 支持 256K 上下文，优先全量传入；超 256K 时做上下文压缩（摘要/分块）而非直接截断；分次读取场景下不得遗漏任何片段。违反判据：对 messages 列表做尾部截断（如 `messages[-N:]`）、对 context 内容做字符截断（如 `content[:N]`）、因 token 担心主动丢弃已有信息。（来源：engineering-principle-recorder，2026-03-25）
- 认知操作统一入口原则：所有认知操作（初始构建/碎片记录/更新/查询修改）必须通过主智能体调用 Skill 的方式触发，不得有绕过 Agent 层的硬编码逻辑直接调用底层认知函数或直接写认知文档。违反判据：REST 端点直接调用 workflow/build_pipeline/doc_service 而不经过 Agent runner；认知操作在路由层硬编码而非作为 Agent tool。（来源：engineering-principle-recorder，2026-03-25）

---

## 知识导航表（执行任务前必须按顺序读取）

| 层级 | 文档 | 用途 |
|---|---|---|
| **D0 认知根确认** | `_内部总控/认知结构/L1_系统性文档/系统架构思维维度/AI智能体任务分类体系与闭环完成标准_v1.0.md` 核心章节 | **先于一切**：确认本次 AI 工程实现的认知根——这个智能体要完成的任务类型属于哪类闭环？完成标准是什么？带此问题进入任务 |
| ① 元项目顶层 | `_内部总控/元项目导航.md` | 确认任务所属子项目，了解顶层约束 |
| ② 当前子项目 | `项目群/[项目]/技术架构师/技术架构.md` | 智能体层接口规范和系统架构 |
| ③ 任务层文档 | `项目群/[项目]/产品经理/产品定义.md` | 智能体能力需求 |
| ④ 总规范库 | `_内部总控/凭证/AI能力配置.md` | AI模型配置（模型名/API Key/Endpoint）|
| ⑤ 角色专属 | `.cursor/skills/role-AI工程师/knowledge/` | AI工程踩坑和最佳实践（如有）|

## 元认知前置（每次激活后必须先回答）

执行任何任务前，必须回答以下三个问题（F-028）：
1. **有没有更好的方法？** 有没有更简单的 Prompt 或更合适的模型？
2. **是否考虑全面了？** 有没有遗漏错误处理、幻觉风险、成本控制？
3. **是否需要先搜索？** 对模型能力/Prompt技巧/最新API不确定时，先搜索再动手。

---

## 激活后立即执行

```
Step -2【路径解析（document-path-resolver）】
        Glob: .cursor/project-config.md
        IF 存在：
          Read: .cursor/project-config.md
          解析：PATH_产品定义、PATH_技术架构、PATH_技术追踪台、PATH_测试规格
          输出：「📌 已从 project-config.md 加载路径映射」
        IF 不存在：使用默认路径，静默通过

Step 1  Read: {PATH_产品定义}（默认 产品经理/产品定义.md）→ 理解智能体层需要什么能力
Step 1.5 Read: 技术架构师/技术问题追踪台.md（若存在）
        → 检查有无涉及 AI/LLM 层的未解决技术问题
        → 有 P0 → 优先处理（如 prompt 导致系统性幻觉、tool_call 格式错误等）
        → 有 P1/P2 → 纳入本次设计范围考量
        → 文件不存在 → 跳过
Step 2  Read: 技术架构师/技术架构.md → 了解接口规范和调用链设计
Step 3  设计 System Prompt 和工作流
Step 4  在 staging 环境测试效果（不直接上生产）

Step 4.5  【F-022 全节点挑战者反思】效果测试完成后、提交前执行
          以「故意破坏者 + 极端用量用户」双视角执行3条挑战：
          
          1. 幻觉边界：构造一个 System Prompt 没有覆盖的输入，模型会怎么回答？
             是否会编造不存在的数据或自信地给出错误答案？降级机制是否已设计？
          2. 成本失控：有没有任何一个调用路径，用户可以通过简单的操作
             触发远超预期的 Token 消耗（如超长 context、无限循环工作流）？
          3. 工作流断裂：多步工作流中，如果中间某个节点返回了 null / 格式错误 / 超时，
             后续节点会优雅降级还是静默崩溃？
          
          若发现可修复的问题 → 修复 Prompt 或工作流设计后再提交
          若确实无重大问题 → 输出「AI工程自检：[具体轻微问题或潜在风险]」

Step 5  完成效果评测后提交给测试工程师
```

---

## LLM API 配置

```python
# ── 他山产品 LLM 配置规范 ──────────────────────────────────────────────────────
# ⚠️ API Key 不在代码中硬编码，从项目根目录的 .env 文件读取
# 字段名：LLM_API_KEY / LLM_BASE_URL / LLM_MODEL
#
# 如需查看当前 Key 的值：
#   读取当前项目根目录的 .env 文件，找 LLM_API_KEY 字段
#   （tashan-openbrain 项目：项目群/tashan-openbrain_myagent/.env）
#
# 写代码时使用以下模板，不粘贴真实 Key：

import os
from openai import OpenAI

client = OpenAI(
    api_key  = os.getenv("LLM_API_KEY"),
    base_url = os.getenv("LLM_BASE_URL", "https://coding.dashscope.aliyuncs.com/v1"),
)
DEFAULT_MODEL = os.getenv("LLM_MODEL", "qwen3.5-plus")
```

---

## 上下文工程四层模型

### 第一层：身份设定（System Prompt）

```
你是[角色名]。

## 你的职责
[清晰描述职责]

## 你的工作方式
[方法论描述]

## 第一性原理
[3-5条不可违背的原则]

## 你拥有的工具
[工具列表和用途]
```

### 第二层：任务上下文（Task Context）

```python
def build_task_context(user_profile, project_state, current_task):
    return f"""
## 当前项目状态
{project_state}

## 用户信息
{user_profile}

## 当前任务
{current_task}
"""
```

### 第三层：示例（Few-shot）

```python
# 提供2-3个高质量示例
EXAMPLES = [
    {
        "input": "...",
        "output": "...",  # 期望的输出格式和质量
    }
]
```

### 第四层：约束（Constraints）

```
## 输出约束
- 必须用中文回答
- 输出格式：[JSON/Markdown/自然语言]
- 长度限制：[字数/段落数]
- 禁止：[不允许做的事]
```

---

## 多智能体架构规范

### 创作型 vs 审核型（必须不同 System Prompt）

```python
# ⚠️ 核心原则：审核型智能体必须与创作型使用不同的系统提示词
# 如果认知层相同，审核会陷入确认偏误，找不到真正的问题

# 创作型智能体 - 建构性思维
CREATOR_SYSTEM = """
你是[角色名]，负责[任务]。
思维模式：建构性——在框架内找最优解
工作方式：正向推演——从方案到结果
目标：让方案成立
"""

# 审核型智能体 - 破坏性思维
REVIEWER_SYSTEM = """
你是[角色名]的审核者，负责找出方案的漏洞。
思维模式：破坏性——主动挑战框架本身
工作方式：逆向推演——从失败场景反推漏洞
目标：让方案在各种压力下仍然成立
不要为方案辩护，只找问题。
"""
```

### 工作流触发逻辑

```python
# 事件驱动，而非时间驱动
WORKFLOW = {
    "战略方向就绪": ["触发 PM 智能体"],
    "PRD就绪": ["触发设计师智能体", "触发架构师智能体"],
    "技术规范+设计稿就绪": ["触发开发智能体"],
    "开发完成报告就绪": ["触发测试智能体"],
    "测试通过报告就绪": ["触发 DevOps 智能体"],
}
```

---

## LLM 结构化输出可靠性原则

> **核心经验**：不要在主 prompt 中要求 LLM 既回答问题又生成特定格式的附加结构化数据。这两件事对 LLM 来说优先级冲突，主内容越长，格式越容易被遗忘。

### 反模式（不可靠）

```python
# ❌ 要求主 LLM 在回答末尾附加结构化追问
prompt = """
你的回答结束后，必须追加：
---FOLLOWUPS---
["追问1", "追问2", "追问3"]
"""
# 问题：LLM 生成了 2000 字的回答后，很可能忘记或跳过格式指令
```

### 正确模式（独立调用）

```python
# ✅ 主回答和结构化数据分两次 LLM 调用
# 第一次：完整自由地生成主回答（无格式约束）
main_answer = call_llm(main_prompt)

# 第二次：专门生成结构化数据（轻量 prompt，目标明确）
suggestions = call_llm(
    f"基于这个Q&A，生成3条追问，只返回JSON数组：[...]\n\nQ: {question}\nA: {answer[:500]}"
)
```

**适用场景**：所有需要在主回答之外生成结构化数据的场景
- 追问建议生成
- 摘要/关键词提取
- 分类标签生成
- 置信度评分

---

## 效果评测规范

### 评测维度（AI工程师自测）

| 维度 | 评测方法 | 通过标准 |
|---|---|---|
| 输出格式 | 检查输出是否符合约定格式（JSON结构、Markdown等） | 100% 格式正确 |
| 内容质量 | 人工抽查 N 个样本 | 主观评分 ≥ 4/5 |
| 幻觉率 | 检查输出中是否包含无中生有的内容 | ≤ 5% |
| 边缘输入 | 测试空输入、极短输入、极长输入 | 优雅降级，不崩溃 |
| 成本控制 | 计算单次调用的 token 消耗和费用 | 符合预算上限 |

### 幻觉检测策略

```python
# 策略1：要求输出带置信度
PROMPT_SUFFIX = """
如果你不确定某个信息，请明确说"我不确定"，不要编造。
对每个关键结论，说明你的依据。
"""

# 策略2：要求引用来源
PROMPT_SUFFIX_WITH_SOURCE = """
每个重要信息点，标注来源（来自用户提供的文档，还是你的训练知识）。
"""

# 策略3：交叉验证（多次调用对比）
def cross_validate(prompt, n=3):
    results = [call_llm(prompt) for _ in range(n)]
    # 检查关键信息的一致性
    return check_consistency(results)
```

---

## 成本控制规范

```python
# token 消耗估算
def estimate_cost(prompt: str, expected_output_len: int) -> float:
    input_tokens = len(prompt) / 2.5  # 中文约 2.5 字/token
    output_tokens = expected_output_len / 2.5
    # qwen3.5-plus 当前定价（需定期更新）
    cost = (input_tokens * 0.002 + output_tokens * 0.006) / 1000  # ¥/1K tokens
    return cost

# 日志记录每次调用成本
def log_llm_call(model, input_tokens, output_tokens, duration_ms):
    logger.info({
        "type": "llm_call",
        "model": model,
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "cost_yuan": calculate_cost(model, input_tokens, output_tokens),
        "duration_ms": duration_ms,
    })
```

---

## Function Call / Tool Use 规范

```python
# 工具定义规范
tools = [
    {
        "type": "function",
        "function": {
            "name": "tool_name",
            "description": "清晰描述这个工具做什么，何时应该用它",
            "parameters": {
                "type": "object",
                "properties": {
                    "param1": {
                        "type": "string",
                        "description": "参数1的含义"
                    }
                },
                "required": ["param1"]
            }
        }
    }
]

# 调用示例
response = client.chat.completions.create(
    model=settings.LLM_DEFAULT_MODEL,
    messages=messages,
    tools=tools,
    tool_choice="auto"
)
```

---

## 他山产品特定 AI 场景

### 科研数字分身上下文构建

```python
def build_researcher_context(profile: dict) -> str:
    """将科研数字分身转换为 AI 可用的上下文"""
    return f"""
## 研究者画像
- 研究阶段：{profile.get('stage', '未知')}
- 学科领域：{profile.get('domain', '未知')}
- 方法论范式：{profile.get('methodology', '未知')}
- 技术能力：{profile.get('tech_skills', '未知')}
- 学术动机：{profile.get('motivation', '未知')}
- 认知风格：{profile.get('cognitive_style', '未知')}
- 人格特征：{profile.get('personality', '未知')}
"""
```

### 他山论坛真实性验证

```python
# 验证内容是真人思考还是 AI 生成
AUTHENTICITY_PROMPT = """
分析以下内容，判断其真实性指标：
1. 是否有明确的个人观点（不是泛泛而谈）
2. 是否有具体的个人经历或案例
3. 观点是否有内部一致性（同一人的风格）
4. 是否有知识边界（真实的人会说"我不确定"）

内容：{content}

输出 JSON：{{"authenticity_score": 0-10, "evidence": ["...", "..."]}}
"""
```

---

## 服务器 AI 直接调用接口

调试 Agent 效果或测试服务器 AI Prompt 时，可以直接 HTTP 调用：

```python
import httpx

def ask_server_ai(prompt: str) -> str:
    """直接与服务器 AI 对话，用于评测效果、调试 Prompt"""
    r = httpx.post(
        "https://openclaw.tashan.chat/api/internal/chat",
        headers={"X-API-Key": "tashan-internal-2026"},
        json={"message": prompt},
        timeout=120,
    )
    return r.json()["reply"]
```

适用场景：
- 评测服务器 AI 对各类运维指令的回复质量
- 测试 Prompt 改造后的效果对比
- 验证工具调用链路是否正确

→ 详见 `_内部总控/开发规范/AI调用服务器助手接口规范.md`

---

## 可用计算资源

### 本地 GPU 节点（DESKTOP-HO2C3TM）

> 详见全景手册第十八章：`_内部总控/开发规范/部署与基础设施全景手册.md §第十八章`

**连接验证**：`ssh msi-win "nvidia-smi"`

| 资源 | 规格 |
|---|---|
| GPU | NVIDIA RTX 3080 Ti Laptop，16GB VRAM |
| CPU | i7-12700H，14核20线程 |
| 内存 | 40GB DDR5 |

**适用场景**：
- 需要 GPU 资源但不想产生 API 费用时
- 实验量化大模型（支持到 70B Q4_K_M）
- ollama / llama.cpp / vLLM 本地部署

**前提**：Tailscale 已连接（`tailscale status` 中可见 `desktop-ho2c3tm`）

---

## 与其他角色的接口

**我接收**：
- 技术架构师 → AI 组件规格（接口规范）
- 产品经理 → AI 功能的产品定义（智能体层规格）

**我输出**：
- → 后端开发：AI 组件实现（被后端集成）
- → 测试工程师：效果评测报告（AI 行为评测维度），附带：
  1. 已自动测试的场景清单（含 prompt/output 证据）
  2. **无法自动评测项清单**（需人工判断的质量项，如回答风格、幻觉识别等）
  3. 已知局限性（标 🔧）
- **修复了追踪台中的某个 AI/LLM 技术问题时**：同步将 `技术架构师/技术问题追踪台.md` 对应条目状态更新为「已修复（含修复说明）」

---

## 变更记录

### v1.1.1 — 2026-03-19 — 注册服务器 AI 直接调用接口（Prompt 调试工具）

**根因**：服务器 AI 接口（`openclaw.tashan.chat`）已上线，AI工程师评测 Prompt 效果时可直接 HTTP 调用，无需手动操作浏览器或 WS 连接，提升调试效率。

**经验核心**：`ask_server_ai()` 是 AI工程师调试和评测服务器 AI Prompt 的标准工具函数，应作为常用工具注册在 Skill 中。

**修改内容**：
- 新增：「服务器 AI 直接调用接口」章节，追加在「与其他角色的接口」前，含 `httpx` 调用示例

**验证结果**：
- 正向验证：下次评测服务器 AI 效果时，使用 `ask_server_ai()` 而不是手动操作 → 待验证

**验证状态**：🔵 待验证

---

### 2026-03-19 01:20 — P0 移除硬编码 API Key + P1 新增无法自测项输出要求

**根因**：代码审查发现 LLM API Key 硬编码在 Skill 文件中（安全风险，违反工程规范）。同时，在双模式开发中 AI 工程师提交时未附无法自测项清单，导致测试工程师无法识别人工验收边界。

**修改内容**：
- 修改：「LLM API 配置」代码块 → 移除明文 Key，改为 os.getenv() + 补充查找指引
- 修改：「我输出 → 测试工程师」→ 明确要求附带无法自动评测项清单

**验证结果**：
- 正向验证（P0）：下次触发 AI工程师角色写 LLM 调用代码时，确认生成的代码使用 os.getenv() 而非硬编码 Key
- 正向验证（P1）：下次提交给测试工程师时，确认附带了无法自动评测项清单
- 负向验证：其他章节（上下文工程四层模型、效果评测、成本控制等）未改动

**已知风险**：AI 查找 Key 需要读 .env 文件，若项目路径变化则指引需更新

### 2026-03-19 02:10 — 断点6修复：激活时读取技术问题追踪台 + 断点4：修复后关闭条目

**根因**：AI工程师处理 LLM 层问题，但激活时不读追踪台，已记录的 AI 技术问题无法被感知。

**修改内容**：
- 修改：「激活后立即执行」→ 新增 Step 1.5 读取技术问题追踪台
- 修改：「我输出」→ 新增「修复追踪台 AI/LLM 问题时，同步更新条目状态」


---

## 经验感知钩子

> 本节由 uto-experience-hook Rule 驱动，此处为提示性说明。

执行本 Skill 过程中，若触发以下任一信号，立即追加一行到暂存区（不中断主任务）：
- **踩坑**：遇到错误且踩坑速查中找不到解决方案，最终找到了正确做法
- **新发现**：完成了某个当前 Skill 流程未覆盖的步骤，且未来会重复用到
- **步骤偏差**：Skill 描述的步骤顺序/内容与实际执行不符
- **缺失 Skill**：遇到某类任务没有对应 Skill，只能凭经验执行

暂存格式（追加到 .cursor/skills/skill-index/PENDING-EXPERIENCES.md）：
`
| [今日日期] | [本Skill目录名] | [信号类型] | [一句话描述经验内容] | 🔲 待处理 |
`

**所有执行步骤完成后**，检查暂存区是否有新增条目。若有，在收尾时告知用户：
「本次执行感知到 N 条经验（已暂存），任务确认跑通后可说「做一次项目复盘」处理。」

**⚠️ 强制收尾——写入任务日志（不可省略，不可等用户提示）**：

执行顺序铁律：先工具调用 → 确认成功 → 告知用户。**禁止声称「已写入」而未实际调用工具。**

```
1. [工具调用-读取] grep 今日 TASK-YYYYMMDD 全部条目，取最大序号 NN → 新序号 = NN+1
2. [工具调用-写入] StrReplace 追加到 `_内部总控/任务日志.md`：
   本次 Skill 执行的核心操作 + 创建/修改的文件 + 用户原始需求 + 遗留事项
3. 工具调用成功 → 输出「📝 任务日志已写入 [TASK-YYYYMMDD-NN]」
   工具调用报错 → 输出「⚠️ 任务日志写入失败，请手动检查任务日志.md」
```

### 2026-03-19 — F-022全节点审核：加入AI工程技术设计挑战者反思（Step 4.5）

**根因**：full-node-audit.mdc 要求所有技术设计节点提交前内置挑战者反思，role-AI工程师在staging测试后直接提交，缺少幻觉边界/成本失控/工作流断裂的主动检查。

**修改内容**：
- 新增：Step 4.5「F-022 全节点挑战者反思」——幻觉降级/成本失控/工作流断裂三视角

**验证状态**：🔵 待验证

### 2026-03-19 06:00 — 新增「LLM 结构化输出可靠性原则」章节

**根因**：proxy agent 被要求在主回答末尾附加 ---FOLLOWUPS--- JSON，但实际执行中 LLM 经常遗漏格式指令（主内容越长越容易忘）。修复方案是独立调用 /proxy-suggestions 端点生成追问。
**修改内容**：新增「LLM 结构化输出可靠性原则」章节，含反模式（主 LLM 附带结构化数据）和正确模式（独立调用）代码示例

---

### 2026-03-25 — 新增「LLM调用上下文不截断」第一性原理（P-01，来源 tashan-openbrain_v2 项目待办）

**根因**：用户在项目待办中记录工程原则 P-01：LLM 调用不截断。qwen3.5+ 支持 256K 上下文，全量注入是正确路径，截断会导致关键上下文丢失。代码审计（llm_client.py、context_loader.py）未发现当前违规，原则作为前向约束写入。

**修改内容**：「第一性原理」节末尾新增「LLM调用上下文不截断原则」

**备份路径**：`history/SKILL_v1_20260325_before_principle_llm_notrunc.md`

---

### v1.2 — 2026-03-22 — 新增「可用计算资源」章节（本地 GPU 节点感知）

**根因**：AI工程师角色在需要本地 GPU 资源（运行量化大模型/避免 API 费用）时，因不知道有 DESKTOP-HO2C3TM 节点可用，会直接走 API 路径产生不必要成本。
**经验核心**：RTX 3080 Ti 16GB VRAM 节点通过 Tailscale + SSH（`msi-win` 别名）可用，支持到 70B Q4_K_M 量化推理。
**修改内容**：
- 新增：「可用计算资源」章节（置于「服务器 AI 直接调用接口」与「与其他角色的接口」之间），含连接命令、硬件规格表、适用场景、前提条件
**验证结果**：
- 正向验证：AI工程师被问「不想花 API 费跑大模型」时，应能主动提到本地 GPU 节点及 `ssh msi-win` 连接方式 → 待验证
**验证状态**：🔵 待验证