# https://github.com/s4b7-ai/s4b7-ai-skills 项目说明书

生成时间：2026-05-14 11:20:31 UTC

## 目录

- [项目概览](#overview)
- [安装指南](#installation)
- [技能文件结构](#skill-structure)
- [技能分类体系](#skill-categories)
- [LangGraph Agent技能](#langgraph-agent)
- [AI SDK Core技能](#ai-sdk-core)
- [Agent-Cryst技能](#agent-cryst)
- [编写技能指南](#write-a-skill)
- [Crystallize技能](#crystallize)
- [模型身份管理](#model-identity)

<a id='overview'></a>

## 项目概览

### 相关页面

相关主题：[安装指南](#installation), [技能分类体系](#skill-categories)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)
- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)
- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)
- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)
- [skills/codex-latex/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-latex/SKILL.md)
- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)
- [skills/patent-queue/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/patent-queue/SKILL.md)
- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
- [skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)
- [skills/shadow-continuity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-continuity/SKILL.md)
- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)
- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)
</details>

# 项目概览

## 项目简介

`s4b7-ai-skills` 是一个模块化的 AI 技能库集合，为多种 AI Agent 系统（Codex、Claude、Gemini、Shadow 等）提供可复用的工作流模式、技能定义和工具链集成。该项目采用技能即服务（Skill-as-a-Service）架构，通过标准化的 `SKILL.md` 模板实现跨平台的能力复用。

**核心特性：**
- 多 Agent 平台兼容（Codex、Claude、OpenAI、Gemini、Ollama）
- 标准化技能描述格式
- 模式结晶（Crystallization）机制
- MCP（Model Context Protocol）协议集成
- 跨模型委托路由

资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)

## 系统架构

### 架构分层

```mermaid
graph TD
    subgraph "用户层"
        U[用户请求]
    end
    subgraph "Agent 层"
        C[Codex Agent]
        CL[Claude Agent]
        G[Gemini Agent]
        S[Shadow Agent]
    end
    subgraph "技能层"
        SK[技能注册表]
        CR[结晶模式]
        RT[运行时配置]
    end
    subgraph "工具层"
        MCP[MCP 服务器]
        OLL[Ollama 本地模型]
        API[外部 API]
    end
    U --> C & CL & G & S
    C & CL & G & S --> SK
    SK --> RT
    RT --> MCP & OLL & API
```

### 技能分类体系

| 技能类别 | 功能范围 | 代表技能 |
|---------|---------|---------|
| 代码工程 | 代码分析、重构、调试 | `shadow-refactor`、`codex-context` |
| 记忆管理 | 持久化记忆、上下文提取 | `qmd-memory`、`shadow-mcp-gadgets` |
| 文档生成 | LaTeX 论文、技术文档 | `codex-latex` |
| 知识合成 | 多模型查询、观点整合 | `multi-model-query` |
| 知识产权 | 专利队列、发明挖掘 | `patent-queue` |
| 工程情报 | 汽车行业竞品分析 | `shadow-engg` |
| 代理编排 | 自动委托、路由决策 | `acp-delegate-auto` |

资料来源：[skills/shadow-engg/SKILL.md](skills/shadow-engg/SKILL.md)

## 核心组件详解

### 1. 技能定义规范

每个技能通过标准化的 `SKILL.md` 文件定义，采用 YAML frontmatter + Markdown 结构：

```yaml
---
name: skill-name
description: 技能描述. Use when [触发关键词].
---
```

**描述要求：**
- 最大 1024 字符
- 第三人称撰写
- 首句说明功能
- 第二句包含触发条件

**技能文档结构：**
- Quick Start（快速开始）
- Workflows（工作流程）
- Advanced features（高级特性）
- 参考文档链接

资料来源：[skills/write-a-skill/SKILL.md](skills/write-a-skill/SKILL.md)

### 2. MCP 工具生态系统

`shadow-mcp-gadgets` 技能提供统一的 MCP 工具路由：

| 工具 | 功能 | 触发词 |
|-----|------|-------|
| ARC | 记忆存储与检索 | `arc.store`, `arc.search` |
| ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |
| ANT | Tailscale 网络健康检查 | `ant.mesh` |
| TAP | Chrome 浏览器标签与执行 | `tap.tabs`, `tap.execute` |
| OWL | Bee AI 环境信息提取 | `owl.brief`, `owl.extract` |
| ORB | macOS 语音合成 | `orb.say`, `orb.voices` |
| DEN | 物理环境传感器 | `den.environment` |
| factory | 专利草稿生成 | `factory.new`, `factory.draft` |

**工具管线流程：**

```
Input (触发词)
  ↓
路由到对应 Gadget
  ↓
执行 MCP 工具调用
  ↓
生成制品 (记忆条目/上下文状态/内联响应)
```

资料来源：[skills/shadow-mcp-gadgets/SKILL.md](skills/shadow-mcp-gadgets/SKILL.md)

### 3. 结晶机制（Crystallization）

`crystallize` 技能从会话中提取可复用模式：

**结晶流程：**

```mermaid
graph LR
    A[任务完成] --> B{应该重复吗?}
    B -->|是| C[审查会话]
    B -->|否| Z[完成]
    C --> D[提取模式]
    D --> E{有重叠技能?}
    E -->|有| F[更新现有技能]
    E -->|无| G[创建新技能]
    F --> H[记录结晶元数据]
    G --> H
```

**模式分类：**
- **Key steps**：产生结果的最少步骤序列
- **Heuristics**：判断规则和经验法则
- **Gotchas**：常见错误和失败假设
- **Decision points**：方案选择决策点

**提升级别：**
| 级别 | 存储位置 | 说明 |
|-----|---------|------|
| Level 1 | `docs/plans/` | 有用但非权威 |
| Level 2 | YAML/JSON | 机器可读真理 |
| Level 3 | 技能库 | 可复用操作模式 |
| Level 4 | 运行时文件 | 系统实际消费 |

资料来源：[skills/crystallize/SKILL.md](skills/crystallize/SKILL.md)

### 4. 多模型委托路由

`acp-delegate-auto` 技能实现智能模型选择：

**路由启发式规则：**

| 提示词包含... | 路由目标 |
|-------------|---------|
| `write`, `implement`, `refactor`, `debug code` | codex |
| `research`, `summarize`, `find`, `compare` | gemini |
| `translate`, `JP`, `Japanese` | Codex |
| `local`, `private`, `no cloud` | ollama |
| `review`, `architect`, `design` | Codex |
| 文件路径、diffs、PRs | codex |

**模型层级体系：**

| 层级 | 来源 | 成本 | 特点 |
|-----|------|-----|------|
| Tier 1 | Ollama (本地) | 免费 | 快速、本地隐私 |
| Tier 2 | OpenRouter API | 按量计费 | 多模型聚合 |
| Tier 3 | Web 浏览器 | 间接成本 | 实时信息获取 |
| Tier 4 | Codex 自身 | 总会话可用 | 固有能力 |

**qwen3 模型特殊处理：**
- 需在提示前添加 `/no_think`
- 或设置 `options.think = false`

资料来源：[skills/acp-delegate-auto/SKILL.md](skills/acp-delegate-auto/SKILL.md)

## 工作流集成

### Shadow 连续性管理

`shadow-continuity` 技能管理工件的生命周期：

```mermaid
graph TD
    A[Stream 输入] --> B[分类层]
    B --> C{层类型判断}
    C -->|架构| D[architecture]
    C -->|配置| E[config/map]
    C -->|脚手架| F[scaffold]
    C -->|技能| G[skill]
    C -->|报告| H[report]
    D & E & F & G & H --> I[推送到仓库]
    I --> J{稳定性检查}
    J -->|稳定| K[提升到技能/canonical]
    J -->|不稳定| L[保留在 plan/note]
    K --> M[运行时消费]
```

**输出规则：**
- 用户文档：简洁结构化
- 机器文档：YAML/JSON 优先
- 运行时脚手架：最小但真实
- 技能：仅可复用模式

资料来源：[skills/shadow-continuity/SKILL.md](skills/shadow-continuity/SKILL.md)

### 代码重构工作流

`shadow-refactor` 技能提供结构化重构：

```mermaid
graph TD
    A[扫描目标代码库] --> B[识别模式]
    B --> C{发现重复?}
    C -->|是| D[标记重复]
    C -->|否| E{复杂度热点?}
    E -->|是| F[标记热点]
    E -->|否| G[分析测试覆盖]
    D & F --> H[生成修复计划]
    H --> I[TDD 循环]
    I --> J{验证通过?}
    J -->|否| K[自修复]
    J -->|是| L[信号工具]
    K --> I
    L --> M[继续下一个问题]
```

**Fallback 链：**
1. 完整 SCAN → TDD 循环 → 验证 → 信号
2. Ollama 不可用：静态分析
3. 无测试套件：扫描并脚手架测试
4. 修复耗尽：回滚并记录

资料来源：[skills/shadow-refactor/SKILL.md](skills/shadow-refactor/SKILL.md)

## 记忆系统

`qmd-memory` 提供多层次记忆管理：

### 记忆类型

| 类型 | 用途 | 示例 |
|-----|------|------|
| `fact` | 永久事实 | "TypeScript 是主要语言" |
| `commitment` | 承诺事项 | "周五前完成设置" |
| `decision` | 决策记录 | "决定使用本地优先" |
| `preference` | 偏好设置 | "喜欢使用 vim" |
| `context` | 上下文信息 | 当前会话状态 |

### CLI 命令

```bash
# 存储记忆
qmd-memory store "内容" --kind fact --tag work

# 检索记忆
qmd-memory recall --kind fact --limit 5

# 从文本提取
qmd-memory extract notes.md --source-id "file:notes.md"
```

### Profile 层

| 层 | 特性 | 持久性 |
|---|------|--------|
| static | 永久事实（身份、偏好、工具、关系） | 长期 |
| dynamic | 近期上下文（当前焦点、最近操作） | 会话 |

资料来源：[skills/qmd-memory/SKILL.md](skills/qmd-memory/SKILL.md)

## 配置与集成

### Codex CLI 配置

| 配置项 | 值 | 说明 |
|-------|-----|------|
| Model | `gpt-5.5` | reasoning effort: low |
| Sandbox | `danger-full-access` | 完整访问权限 |
| Approval policy | `never` | 全自动模式 |
| Token limit | 25,000 | 工具输出限制 |
| Features | multi_agent, memories, chronicle, js_repl, apps | 启用特性 |

**Caveman 模式：**
- 简洁智能通信风格
- 模式：`[事物] [动作] [原因]. [下一步].`
- 企业区例外：Astemo/Honda/fh4s 保持正常散文

资料来源：[skills/codex-context/SKILL.md](skills/codex-context/SKILL.md)

### MCP 服务器

| 服务器 | 路径/URL |
|--------|---------|
| RepoPrompt | `/Users/sdluffy/RepoPrompt/repoprompt_cli` |
| chrome_devtools | `/Users/sdluffy/bin/chrome-devtools-mcp-work` |
| notion | `https://mcp.notion.com/mcp` |
| openevidence | `node .../openevidence-mcp/dist/server.js` |
| playwright | `/Users/sdluffy/bin/playwright-mcp-work` |

## 专利与文档生成

### 专利队列管理

| 命令 | 功能 | 触发词 |
|-----|------|--------|
| `new` | 创建新专利草稿 | `patent new` |
| `mine` | 挖掘发明候选 | `patent mine` |
| `queue` | 查看候选队列 | `patent queue` |
| `export <ID>` | Obsidian 导出 | `patent obsidian` |
| `synthesize` | 组合概览输出 | `patent synthesize` |

### LaTeX 论文生成

`codex-latex` 支持多种模板：

| 模板类型 | 适用场景 |
|---------|---------|
| IEEE Conference | 会议论文 |
| ACM | 学术论文 |
| Patent Specification | 专利规范 (SP-001/002/003) |
| Engineering Report | 工程报告 |
| Research Paper | 研究论文 |

**构建流程：**
```bash
latexmk -pdf paper.tex  # 自动处理多次编译
```

资料来源：[skills/codex-latex/SKILL.md](skills/codex-latex/SKILL.md)

## 设计系统

### 配色方案

| 系统 | 主色 | 辅色 | 背景 |
|------|------|------|------|
| Shadow Enterprise | `#4a9eff` (蓝) | `#8b5cf6` (紫) | `#09090b` (深) |
| Astemo/Honda | `#B6001A` (红) | Arial 字体 | 白色/浅色表面 |

### 文件路由规范

| 制品类型 | 存储路径 | 用途 |
|---------|---------|------|
| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复结果 |
| 重构报告 | `ShadowArchive/80-reports/refactor-*.md` | 会话摘要 |
| 扫描报告 | `ShadowArchive/80-reports/mesh-*.md` | 网络扫描结果 |
| 专利草稿 | `docs/patents/SP-NNN/` | 规范、权利要求、提交指南 |
| 专利队列 | `ShadowArchive/10-projects/patent-queue/` | 候选队列 JSON |

## 总结

`s4b7-ai-skills` 项目构建了一个全面的 AI Agent 技能生态系统，通过标准化技能定义、多层次记忆系统、智能路由委托和模式结晶机制，实现了跨平台的 AI 能力复用。项目的模块化设计使得各个技能可以独立演进，同时通过统一的架构规则保持整体一致性。

---

<a id='installation'></a>

## 安装指南

### 相关页面

相关主题：[项目概览](#overview), [技能文件结构](#skill-structure)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)
- [distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)
- [scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)
</details>

# 安装指南

本页面详细介绍 s4b7-ai-skills 项目的安装流程、环境配置及常见问题的解决方案。

## 系统要求

在开始安装之前，请确保您的系统满足以下要求：

| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|----------|----------|------|
| Node.js | 18.0.0 | 20.x LTS | 支持 ES 模块和现代 JavaScript 特性 |
| npm | 9.0.0 | 10.x | 包管理工具 |
| git | 2.30.0 | 最新版 | 用于版本控制和依赖拉取 |
| 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | - | 跨平台支持 |

资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)

## 安装方式

### 方式一：npm 全局安装（推荐）

使用 npm 进行全局安装是最简便的方式：

```bash
npm install -g s4b7-ai-skills
```

安装完成后，可以通过以下命令验证：

```bash
s4b7-ai-skills --version
```

资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)

### 方式二：本地项目安装

将 s4b7-ai-skills 作为项目依赖安装：

```bash
# 创建项目目录
mkdir my-agent-project && cd my-agent-project

# 初始化 npm 项目
npm init -y

# 安装为项目依赖
npm install s4b7-ai-skills

# 或安装最新预发布版本
npm install s4b7-ai-skills@next
```

资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)

### 方式三：从源码构建

适合需要自定义或参与开发的用户：

```bash
# 克隆仓库
git clone https://github.com/s4b7-ai/s4b7-ai-skills.git
cd s4b7-ai-skills

# 安装依赖
npm install

# 构建项目
npm run build

# 链接到全局（开发模式）
npm link
```

资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)

## 安装流程图

以下流程图展示了完整的安装过程：

```mermaid
graph TD
    A[开始安装] --> B{检查 Node.js 版本}
    B -->|版本过低| C[升级 Node.js]
    B -->|版本符合| D[检查 npm 版本]
    C --> D
    D --> E{安装方式选择}
    E -->|全局安装| F[npm install -g]
    E -->|本地安装| G[npm install]
    E -->|源码构建| H[git clone + npm install]
    F --> I[验证安装]
    G --> I
    H --> I
    I --> J{验证成功?}
    J -->|是| K[安装完成]
    J -->|否| L[排查错误]
    L --> I
```

## 环境配置

### 配置文件位置

安装后，配置文件位于用户主目录：

| 平台 | 配置文件路径 |
|------|--------------|
| macOS/Linux | `~/.s4b7-ai-skills/config.json` |
| Windows | `%USERPROFILE%\.s4b7-ai-skills\config.json` |

### 基本配置

创建或编辑配置文件：

```json
{
  "model": "qwen3:8b",
  "ollamaEndpoint": "http://localhost:11434",
  "skillsDirectory": "~/.agents/skills/",
  "logLevel": "info",
  "autoUpdate": true
}
```

资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)

### 环境变量

支持通过环境变量进行配置：

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `S4B7_SKILLS_DIR` | 技能目录路径 | `~/.agents/skills/` |
| `S4B7_MODEL` | 默认模型 | `qwen3:8b` |
| `S4B7_OLLAMA_URL` | Ollama 服务地址 | `http://localhost:11434` |
| `S4B7_LOG_LEVEL` | 日志级别 | `info` |
| `S4B7_API_KEY` | API 密钥（可选） | 空 |

## 依赖组件

### Ollama 本地模型服务

s4b7-ai-skills 优先使用本地 Ollama 模型：

```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取默认模型
ollama pull qwen3:8b

# 验证 Ollama 运行状态
curl -s http://localhost:11434/api/tags | head -1
```

资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

### ShadowArchive 存储卷（可选）

用于高级功能和技能同步：

```bash
# 确保 ShadowArchive 卷已挂载
ls /Volumes/☯Duality/

# 或使用本地模式（功能受限）
S4B7_LOCAL_MODE=true s4b7-ai-skills
```

资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)

## 安装验证

### 完整性检查

安装完成后，运行以下命令进行验证：

```bash
# 检查 CLI 可用性
s4b7-ai-skills --help

# 检查技能加载
s4b7-ai-skills skills list

# 测试模型连接
s4b7-ai-skills doctor
```

### 常见验证命令

| 命令 | 用途 |
|------|------|
| `s4b7-ai-skills --version` | 显示版本号 |
| `s4b7-ai-skills skills list` | 列出已安装的技能 |
| `s4b7-ai-skills doctor` | 运行诊断检查 |
| `s4b7-ai-skills update` | 检查并安装更新 |

资料来源：[scripts/install.js](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/scripts/install.js)

## 技能目录结构

安装后，技能目录结构如下：

```
~/.agents/skills/
├── write-a-skill/          # 技能编写指南
│   └── SKILL.md
├── shadow-refactor/        # 代码重构工具
│   └── SKILL.md
├── qmd-memory/             # 记忆管理系统
│   └── SKILL.md
├── codex-latex/            # LaTeX 文档生成
│   └── SKILL.md
├── codex-context/          # 上下文管理
│   └── SKILL.md
├── ai-sdk-core/            # AI SDK 核心
│   └── references/
│       └── v5-breaking-changes.md
├── multi-model-query/      # 多模型查询
│   └── SKILL.md
├── patent-queue/           # 专利队列管理
│   └── SKILL.md
├── command-center/         # 命令中心
│   └── SKILL.md
├── shadow-continuity/      # 连续性管理
│   └── SKILL.md
├── shadow-patent-factory/  # 专利工厂
│   └── SKILL.md
├── acp-delegate-auto/      # 自动委托
│   └── SKILL.md
├── shadow-engg/            # 工程辅助
│   └── SKILL.md
└── shadow-mcp-gadgets/     # MCP 小工具
    └── SKILL.md
```

资料来源：[distribution.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/distribution.json)

## 卸载

如需卸载 s4b7-ai-skills：

```bash
# 全局卸载
npm uninstall -g s4b7-ai-skills

# 清除配置（可选）
rm -rf ~/.s4b7-ai-skills/

# 清除链接
npm unlink s4b7-ai-skills
```

## 故障排除

### 安装失败

| 问题 | 解决方案 |
|------|----------|
| `EACCES` 权限错误 | 使用 sudo 或配置 npm 路径 |
| Node.js 版本不兼容 | 升级到推荐版本 |
| 网络超时 | 配置国内镜像：`npm config set registry https://registry.npmmirror.com` |

### 运行时问题

| 问题 | 诊断步骤 |
|------|----------|
| 技能加载失败 | 检查 `~/.agents/skills/` 目录存在性 |
| 模型连接失败 | 确认 Ollama 服务运行：`curl http://localhost:11434` |
| 权限不足 | 检查配置文件写入权限 |

资料来源：[skills/shadow-engg/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-engg/SKILL.md)

## 更新升级

### 检查更新

```bash
s4b7-ai-skills update --check
```

### 执行更新

```bash
# npm 全局更新
npm update -g s4b7-ai-skills

# 源码更新
git pull origin main
npm run build
npm link
```

资料来源：[package.json](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/package.json)

---

<a id='skill-structure'></a>

## 技能文件结构

### 相关页面

相关主题：[技能分类体系](#skill-categories), [编写技能指南](#write-a-skill)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)
- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)
- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)
- [skills/shadow-mind/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mind/SKILL.md)
</details>

# 技能文件结构

## 概述

技能（Skill）是 AI Agent 系统中的可复用能力单元，用于封装特定领域的任务处理逻辑、工作流和最佳实践。技能文件结构定义了这些能力单元的标准化组织方式，确保 Agent 能够在需要时准确识别、加载并执行相应的技能。

技能文件结构的核心目标是：

- **可发现性**：通过标准化的描述格式，使 Agent 能够根据用户请求的关键词和上下文自动匹配最合适的技能
- **可维护性**：提供清晰的组织规范，便于技能创建、更新和审计
- **可组合性**：支持技能的模块化拆分和引用，便于构建复杂的任务处理流程
- **可追溯性**：记录技能的创建来源和使用历史，支持持续优化

## 技能文件基本结构

### 标准目录布局

```
~/.agents/skills/<skill-name>/
├── SKILL.md              # 主技能文件（必需）
├── scripts/              # 工具脚本目录（可选）
│   ├── helper.js
│   └── validator.sh
├── docs/                 # 文档目录（可选）
│   ├── plans/
│   │   └── crystallization-log.md
│   └── reference/
└── reference.md          # 参考文档（可选）
```

资料来源：[skills/write-a-skill/SKILL.md:1-15]()

### SKILL.md 文件结构

SKILL.md 是每个技能的入口文件，必须包含以下组成部分：

| 组成部分 | 必需性 | 说明 |
|---------|-------|------|
| YAML Frontmatter | 是 | 包含技能名称和描述 |
| H1 标题 | 是 | 技能名称 |
| Quick start | 是 | 最小可运行示例 |
| Workflows | 是 | 复杂任务的步骤清单 |
| Advanced features | 否 | 指向独立参考文件的链接 |

```markdown
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
```

资料来源：[skills/write-a-skill/SKILL.md:18-32]()

## YAML Frontmatter 规范

### Description 字段规则

description 字段是 Agent 在决定加载哪个技能时看到的唯一信息，它会与所有已安装技能的描述一起出现在系统提示中。因此，description 的编写质量直接影响技能的触发准确性。

**格式要求**：

- 最大 1024 字符
- 使用第三人称书写
- 第一句：描述技能提供的功能
- 第二句：以 "Use when..." 开头，说明触发条件

**编写示例**：

```
# 正确示例
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

```
# 错误示例
Helps with documents.
```

错误示例的问题在于：它没有给 Agent 提供区分该技能与其他文档技能的方式。

资料来源：[skills/write-a-skill/SKILL.md:38-55]()

## 技能拆分策略

### 何时拆分文件

当满足以下条件时，应将内容拆分到独立文件：

| 条件 | 说明 |
|------|------|
| SKILL.md 超过 100 行 | 主文件变得难以阅读和维护 |
| 内容具有不同领域 | 如财务和销售数据模式 |
| 高级功能很少被使用 | 将其隔离减少日常加载开销 |

### 何时添加 Scripts 目录

在以下情况下，应添加 scripts/ 目录并放置工具脚本：

- 操作是确定性的（验证、格式化）
- 相同的代码会被重复生成
- 错误需要显式处理

脚本可以节省 token 消耗并提高可靠性，因为它们是经过验证的预编译代码，而非每次动态生成。

资料来源：[skills/write-a-skill/SKILL.md:76-88]()

## 技能分类与放置

### 分类标准

技能按照其适用范围进行分类：

| 分类 | 路径 | 说明 |
|------|------|------|
| 通用模式 | `~/.agents/skills/<skill-name>/` | 适用于所有场景的通用技能 |
| 企业特定模式 | `~/.agents/skills/` 的适当子目录 | 针对特定企业或领域的专用技能 |

资料来源：[skills/crystallize/SKILL.md:112-117]()

### 企业特定技能的放置

企业特定技能应放置在 `~/.agents/skills/` 下的适当子目录中，遵循组织结构层级。例如：

- Astemo 相关技能 → `~/.agents/skills/astemo/`
- 特定项目相关 → `~/.agents/skills/projects/<project-name>/`

## 技能创建工作流

### 标准工作流图

```mermaid
graph TD
    A[任务完成] --> B{应该复用吗?}
    B -->|是| C[回顾会话]
    B -->|否| Z[完成]
    C --> D[提取模式]
    D --> E[检查范围]
    E --> F{存在重叠?}
    F -->|是| G[更新现有技能]
    F -->|否| H[创建新技能]
    G --> I[记录结晶化]
    H --> I
    I --> Z
```

### 工作流详细步骤

#### 1. 回顾（Review）

回答以下问题：

- 任务是什么？
- 解决了什么问题？
- 学到了什么？
- 下次会重复哪些步骤？

#### 2. 模式提取（Pattern Extraction）

识别可复用模式，包括：

| 模式类型 | 说明 |
|---------|------|
| **关键步骤** | 产生结果的最简序列 |
| **启发式规则** | 需要判断的决策点、经验法则 |
| **常见错误** | 什么出了问题或差点出问题、哪些假设失败 |
| **决策点** | 在哪里选择了不同方法、什么决定了选择 |

资料来源：[skills/crystallize/SKILL.md:78-96]()

#### 3. 探索模式扩展

当操作者请求"更多结晶化"或引用 `--exploratory-mode` 时，不要止步于第一个本地修复。应向外扩展一圈，检查相邻表面是否存在相同的过时假设。

扩展检查范围：

1. 从刚修复的确切内容开始
2. 检查可能携带相同过时假设的最近相邻表面

资料来源：[skills/crystallize/SKILL.md:98-112]()

## 结晶化模式与模式

### 结晶化与 SP-006 的关系

SP-006（潜在技能观察器）从工具调用序列自动检测模式。结晶化技能通过从推理中有意提取模式来补充 SP-006——这些模式源自对问题的理解，而不仅仅是观察工具使用。两种机制向相同的技能命名空间提供输入。

资料来源：[skills/crystallize/SKILL.md:119-125]()

### 结晶化模式

| 模式 | 输出 | 触发场景 |
|------|------|---------|
| `default` | 完整结晶化：回顾→提取→范围→去重→创建/更新 | `crystallize`, `capture this as a skill` |
| `quick` | 快速捕获到最小技能存根（后续完善） | `quick crystallize`, 任务中模式发现 |
| `exploratory` | 从修复向外扩展一圈；检查相邻表面 | `--exploratory-mode`, `more crystallization` |
| `drag-response` | 由操作者挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |
| `correction` | 由操作者更正触发的即时更新 | 操作者更正身份/路径/边界 |
| `audit` | 检查应该结晶化但没有的内容 | `what patterns did we miss` |

资料来源：[skills/crystallize/SKILL.md:127-142]()

## 技能路由机制

### 关键词检测路由

Agent 可以根据提示中的关键词自动路由到合适的技能：

| 提示包含... | 路由到 |
|-----------|-------|
| `write`, `implement`, `refactor`, `debug code` | codex |
| `research`, `summarize`, `find`, `compare` | gemini |
| `translate`, `JP`, `Japanese` | Codex |
| `local`, `private`, `no cloud` | ollama |
| `review`, `architect`, `design` | Codex |
| `file paths`, `diffs`, `PRs` | codex |

资料来源：[skills/acp-delegate-auto/SKILL.md:45-59]()

### 描述触发机制

技能的 description 字段是 Agent 决策加载哪个技能的主要依据。Agent 读取所有已安装技能的描述，然后根据用户的请求选择最相关的技能。

**触发检测要素**：

1. 功能能力 - 技能提供什么功能
2. 触发关键词 - 具体何时/为什么使用
3. 文件类型关联 - 与哪些文件类型相关

## 技能审计与验证

### 技能审查清单

创建或更新技能后，验证以下要点：

- [ ] description 包含触发条件（"Use when..."）
- [ ] SKILL.md 不超过 100 行
- [ ] 没有时间敏感信息
- [ ] 术语一致
- [ ] 包含具体示例
- [ ] 引用深度仅一层（避免深层嵌套引用）

资料来源：[skills/write-a-skill/SKILL.md:92-100]()

### 技能手术规则

技能审计和研究开发（Skill Surgery R&D）遵循以下规则：

| 规则 | 说明 |
|------|------|
| **不删除规则** | 在探索性手术期间不删除技能，先重定向；删除需要操作者明确批准 |
| **不编辑历史** | 除非仍作为活跃触发问题出现，否则不编辑已归档历史 |
| **不创建巨型集合技能** | 优先创建一个规范路由器加专注子技能 |
| **先研究后创造** | 未经验证不结晶过时版本号、价格或 API 形状 |
| **保留边界** | 整合 Astemo/企业技能时保留特定操作者边界 |
| **外部化规则** | 所有手术报告进入报告目录，而非嵌入技能文件 |

资料来源：[skills/skill-surgery-rd/SKILL.md:25-36]()

### 错误处理

| 故障场景 | 恢复策略 |
|---------|---------|
| 脚本执行失败（语法错误） | 运行手动 `find + grep` 清单；在报告中记录脚本失败 |
| 技能文件 YAML frontmatter 格式错误 | 标记在清单中；不自动修复；建议手动修复 |
| 检测到循环重定向（A → B → A） | 阻止重定向；报告循环；需要手动解决 |
| 合并目标有冲突的 gotchas | 保留两组 gotchas；标记供操作者审查 |
| 技能数量过多（>500） | 优先活跃+非废弃的；抽样检查归档以进行陈旧车道检查 |
| 技能目录权限被拒绝 | 报告；跳过；仅审计可访问的目录 |

资料来源：[skills/skill-surgery-rd/SKILL.md:38-50]()

## 人工制品路由

每个技能生成的人工制品按照标准化路径存储：

| 人工制品类型 | 路径 | 用途 |
|------------|------|------|
| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |
| 更新技能 | 现有技能相同路径 | 扩展能力 |
| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |
| 企业特定技能 | `~/.agents/skills/` 适当子目录 | 领域范围能力 |

资料来源：[skills/crystallize/SKILL.md:145-153]()

## 技能与记忆系统集成

### 上下文保存流程

在每次产生决策或发现的会话后：

1. 将会话锚点写入 `ShadowArchive/80-reports/`
2. 将关键决策追加到 `.shadow-kernel/esp-context.md` 的相应主题下
3. 如果发现模式 → 结晶化到技能
4. 如果是项目特定的 → 写入 `<program>/90_Astemo_Config/session-log.jsonl`

资料来源：[skills/shadow-mind/SKILL.md:55-60]()

### 记忆召回置信度

| 置信度级别 | 含义 | 来源 |
|-----------|------|------|
| **Confirmed** | 在持久人工制品中找到（锚点、内核、Dropbox） | 文件匹配 |
| **Likely** | 在训练对或提炼经验中找到 | 模式匹配 |
| **Inferred** | 从上下文重构但无明确人工制品 | 推理 |
| **Unknown** | 未找到证据 | 无匹配 |

必须始终标注召回置信度。永远不要将推断的召回呈现为已确认的。

资料来源：[skills/shadow-mind/SKILL.md:62-70]()

## 完整技能示例

### 示例：crystallize 技能结构

```markdown
---
name: crystallize
description: Extract reusable patterns from problem-solving sessions into structured skills. Use when finishing a complex task that might recur, or when explicitly asked to capture a pattern.
---

# Crystallize

One-line description. Use when [trigger phrases].

## When to Use
- [trigger 1]
- [trigger 2]
- [trigger 3]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Key Decisions
- [Decision point 1]: [default choice + why]
- [Decision point 2]: [default choice + why]

## Gotchas
- [Common mistake 1]
- [Common mistake 2]

## Crystallized From
- Session: [date/context]
- Original task: [what was being solved]
```

资料来源：[skills/crystallize/SKILL.md:20-43]()

## 最佳实践总结

### 技能设计原则

1. **简洁性优先**：保持 SKILL.md 在 100 行以内
2. **描述精确化**：description 必须包含具体触发条件
3. **示例具体化**：包含最小可运行示例而非抽象描述
4. **分层设计**：高级内容通过引用独立文件实现
5. **模式优先**：将确定性操作提取为脚本

### 避免的反模式

| 反模式 | 问题 | 替代方案 |
|-------|------|---------|
| 模糊描述 | Agent 无法区分技能 | 包含具体触发关键词 |
| 巨型单文件 | 难以维护 | 拆分到 reference.md |
| 时间敏感信息 | 信息快速过时 | 避免版本号、价格等 |
| 深层嵌套引用 | 增加加载复杂度 | 限制引用深度为一层 |

### 持续改进流程

技能文件结构是一个持续迭代的系统：

```mermaid
graph LR
    A[创建技能] --> B[使用验证]
    B --> C{效果如何?}
    C -->|良好| D[归档最佳实践]
    C -->|需改进| E[识别问题]
    E --> F{范围局限?}
    F -->|是| G[探索性扩展]
    F -->|否| H[局部优化]
    G --> A
    H --> A
    D --> I[技能库成熟]
```

通过遵循本文档定义的技能文件结构规范，可以构建一个可维护、可发现、可组合的技能生态系统，使 AI Agent 能够高效地处理各类复杂任务。

---

<a id='skill-categories'></a>

## 技能分类体系

### 相关页面

相关主题：[LangGraph Agent技能](#langgraph-agent), [编写技能指南](#write-a-skill), [模型身份管理](#model-identity)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)
- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)
- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)
- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)
- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)
- [skills/command-center/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/command-center/SKILL.md)
</details>

# 技能分类体系

## 概述

技能分类体系（Skill Taxonomy）是 s4b7-ai-skills 项目中的核心架构概念，旨在对 AI Agent 的技能（Skills）进行系统化组织、标准化定义和自动化路由。该体系通过统一的模板结构、关键词触发机制和层级分类，实现了对复杂任务处理的精准匹配与高效执行。

技能分类体系的核心目标包括：

- 为 Agent 提供清晰的技能选择依据
- 实现任务到技能的自然映射
- 支持技能的持续迭代与模式提取
- 提供完善的回退机制确保系统韧性

资料来源：[write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)

---

## 技能分类层级

技能体系按照功能域和触发场景分为多个层级，每个层级承担不同的职责：

### 按功能域分类

```mermaid
graph TD
    A[技能分类体系] --> B[核心能力类]
    A --> C[业务领域类]
    A --> D[工具集成类]
    A --> E[推理决策类]
    
    B --> B1[write-a-skill]
    B --> B2[crystallize]
    B --> B3[multi-model-query]
    
    C --> C1[command-center]
    C --> C2[patent-queue]
    C --> C3[shadow-patent-factory]
    
    D --> D1[shadow-mcp-gadgets]
    D --> D2[acp-delegate-auto]
    D --> D3[codex-context]
    
    E --> E1[codex-policy-steering]
    E --> E2[shadow-refactor]
```

### 技能功能域对照表

| 类别 | 描述 | 代表技能 |
|------|------|----------|
| 核心能力类 | 技能开发、模式提取、知识合成的基础能力 | write-a-skill, crystallize, multi-model-query |
| 业务领域类 | 特定业务场景的垂直能力 | command-center, patent-queue, shadow-engg |
| 工具集成类 | 与外部系统、API、MCP 服务集成的技能 | shadow-mcp-gadgets, acp-delegate-auto |
| 推理决策类 | 策略分析、代码推理、上下文理解 | codex-policy-steering, shadow-refactor |

资料来源：[crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)

---

## 技能模板规范

所有技能遵循统一的 SKILL.md 模板规范，确保一致性和可维护性：

### 标准化模板结构

```markdown
---
name: skill-name
description: 技能描述. Use when [触发关键词].
---

# 技能名称

## 快速开始
[最小工作示例]

## 工作流
[带检查清单的逐步流程]

## 高级特性
[链接到独立文件]
```

### 描述字段规范

技能描述是 Agent 选择技能时的唯一依据，编写规范如下：

| 要求 | 说明 |
|------|------|
| 字符限制 | 最多 1024 个字符 |
| 人称 | 使用第三人称 |
| 格式 | 首句描述功能，次句描述触发条件 |
| 触发词 | 必须包含 "Use when" 引导的触发场景 |

**规范示例**：
```
Extract text and tables from PDF files, fill forms, merge documents. 
Use when working with PDF files or when user mentions PDFs, forms, 
or document extraction.
```

**不规范示例**：
```
Helps with documents.
```

资料来源：[write-a-skill/SKILL.md:32-52](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)

---

## 关键词路由机制

### 路由决策流程

技能分类体系通过关键词匹配实现任务的自动路由：

```mermaid
graph TD
    A[用户请求] --> B{关键词检测}
    B -->|write/implement/refactor/debug| C[codex]
    B -->|research/summarize/find/compare| D[gemini]
    B -->|translate/JP/Japanese| E[Codex]
    B -->|local/private/no cloud| F[ollama]
    B -->|review/architect/design| G[Codex]
    B -->|quickly/fast/brief| H[ollama]
    B -->|file paths/diffs/PRs| I[codex]
    
    C --> J[执行目标技能]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

### 关键词与技能映射表

| 请求关键词 | 路由目标 |
|------------|----------|
| `write`, `implement`, `refactor`, `debug code` | codex |
| `research`, `summarize`, `find`, `compare` | gemini |
| `translate`, `JP`, `Japanese` | Codex |
| `local`, `private`, `no cloud` | ollama |
| `review`, `architect`, `design` | Codex |
| `quickly`, `fast`, `brief` | ollama |
| 文件路径, diffs, PRs | codex |

资料来源：[acp-delegate-auto/SKILL.md:1-24](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

---

## 技能触发与工作流

### 触发模式分类

技能根据触发场景分为不同的工作模式：

```mermaid
graph LR
    A[触发源] --> B{技能类型}
    
    B --> C[显式触发]
    B --> D[隐式触发]
    B --> E[模式检测]
    
    C --> C1[关键词匹配]
    C --> C2[命令调用]
    
    D --> D1[上下文推断]
    D --> D2[记忆关联]
    
    E --> E1[SP-006 观察]
    E --> E2[行为序列分析]
```

### shadow-refactor 技能工作流

shadow-refactor 是技能体系中的代码推理专家，其工作流程如下：

```mermaid
graph TD
    A[启动 refactor] --> B[执行 SCAN]
    B --> C{发现问题?}
    C -->|是| D[创建 TDD 循环]
    C -->|否| E[equilibrium 模式]
    
    D --> F[编写测试]
    F --> G[执行修复]
    G --> H{测试通过?}
    H -->|是| I[verify 验证]
    H -->|否| J[自修复尝试]
    J --> K{尝试次数<3?}
    K -->|是| G
    K -->|否| L[回滚更改]
    
    I --> M[signal 工具信号]
    M --> N[下一个问题]
    N --> C
    
    E --> O[报告当前状态]
```

### 代码分析检查项

| 检查类型 | 方法 | 工具/命令 |
|----------|------|----------|
| 导入一致性 | `import-sort | sort` 对比 | grep -rn |
| 重复代码检测 | 3+ 行相同的代码块 | 跨文件比对 |
| 复杂度热点 | 函数>50行、文件>500行 | AST 分析 |
| 测试覆盖缺口 | 源文件无对应测试 | 文件匹配扫描 |

资料来源：[shadow-refactor/SKILL.md:1-40](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)

---

## MCP 工具分类

MCP（Model Context Protocol）工具通过 Gadget 技能进行统一封装：

### Gadget 工具映射表

| 触发模式 | Gadget | 功能 | 使用示例 |
|----------|--------|------|----------|
| `memory` | ARC | 记忆存储与检索 | `arc.store`, `arc.search` |
| `context` | ESP | 统一上下文组装 | `esp.assemble`, `/renew-ctx` |
| `mesh` | ANT | 网格健康监控 | `ant.mesh` |
| `browser` | TAP | Chrome 标签页+JS执行 | `tap.tabs`, `tap.execute` |
| `ambient` | OWL | Bee AI 信息提取 | `owl.brief`, `owl.extract` |
| `voice` | ORB | macOS TTS | `orb.say`, `orb.voices` |
| `environment` | DEN | 物理传感器 | `den.environment` |
| `patent` | Factory | 专利流水线 | `factory.new`, `factory.draft` |

资料来源：[shadow-mcp-gadgets/SKILL.md:1-20](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)

---

## 模式提取与技能结晶

### 技能结晶工作流

技能可通过两种途径产生：

```mermaid
graph TD
    A[技能来源] --> B{产生方式}
    
    B --> C[主动结晶]
    B --> D[自动检测]
    
    C --> C1[理解问题本质]
    C1 --> C2[识别模式]
    C2 --> C3[编写 SKILL.md]
    C3 --> C4[记录元数据]
    
    D --> D1[SP-006 观察]
    D1 --> D2[行为序列分析]
    D2 --> D3[模式归档]
```

### 结晶元数据记录

每个技能底部应记录结晶来源：

```markdown
## Crystallized From
- Session: [日期/上下文]
- Original task: [解决的问题]
- What pattern was extracted: [提取的模式]
- Adjacent surfaces checked: [检查的相邻表面]
- Surfaces intentionally left untouched: [故意不触碰的表面]
```

### 与 SP-006 的关系

- **SP-006**（潜在技能观察器）：自动检测工具调用序列中的模式
- **crystallize 技能**：通过理解问题本质进行主动模式提取

两者互为补充，共同充实技能命名空间。

资料来源：[crystallize/SKILL.md:1-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)

---

## 回退机制

技能体系设计了完善的回退链，确保系统在各种异常情况下仍能提供能力：

### 通用回退原则

| 优先级 | 场景 | 回退行为 |
|--------|------|----------|
| 1 | 主服务可用 | 执行完整功能 |
| 2 | 服务不可用 | 使用本地替代方案 |
| 3 | 依赖缺失 | 降级到简化模式 |
| 4 | 完全失败 | 生成报告并说明限制 |

### shadow-refactor 回退链

1. **主要路径**：完整 SCAN → TDD 循环 → verify → signal → 下一问题
2. **Ollama 不可用**：仅使用静态分析（grep、AST、文件指标）
3. **测试套件未找到**：扫描测试文件；如不存在，先生成最小测试结构
4. **自修复耗尽 3 次尝试**：回滚该问题的所有更改；记录为不可恢复；继续下一问题
5. **后台代理不可用**：以内联方式运行（阻塞用户）；报告后台模式不可用
6. **最后手段**：报告问题而不修复；生成仅扫描输出

### shadow-mcp-gadgets 回退链

1. **主要**：通过 MCP 协议连接到 shadow-mcp 联邦服务器
2. **MCP 服务器未运行**：通过 `bun run` 启动服务
3. **后续回退**：根据各 Gadget 类型确定具体降级策略

资料来源：[shadow-refactor/SKILL.md:50-60](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [shadow-mcp-gadgets/SKILL.md:25-35](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)

---

## 制品路由

技能执行后的输出通过标准化的路径进行路由：

### 制品路径规范

| 制品类型 | 路径 | 用途 |
|----------|------|------|
| 工具信号 | `tools/integrate/tool-signals.jsonl` | 每次修复的 JSONL 结果 |
| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 会话摘要 |
| 记忆存储 | ARC 记忆存储（gadget 管理） | 持久化 Agent 记忆 |
| 上下文状态 | ESP 程序集输出（会话范围） | 当前会话的统一上下文 |
| 专利草案 | `docs/patents/` | 归档轨道草案 |
| 技能开发 | `~/.agents/skills/<skill-name>/` | 通用模式 |
| 企业技能 | `~/.agents/skills/<category>/` | 企业特定模式 |

资料来源：[shadow-refactor/SKILL.md:45-50](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md), [crystallize/SKILL.md:70-75](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)

---

## 技能开发检查清单

创建新技能时应遵循以下检查流程：

### 编写检查项

| 检查项 | 状态 |
|--------|------|
| 描述包含触发词（"Use when..."） | ☐ |
| SKILL.md 控制在 100 行以内 | ☐ |
| 无时间敏感信息 | ☐ |
| 术语一致性 | ☐ |
| 包含具体示例 | ☐ |
| 引用层级深度不超过 1 层 | ☐ |

### 文件拆分原则

在以下情况下应拆分为独立文件：

- SKILL.md 超过 100 行
- 内容具有不同领域（如财务 vs 销售模式）
- 高级特性很少需要

### 脚本添加原则

在以下情况下应添加脚本：

- 操作是确定性的（验证、格式化）
- 相同代码会被重复生成
- 需要明确的错误处理

资料来源：[write-a-skill/SKILL.md:90-120](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)

---

## 总结

技能分类体系是 s4b7-ai-skills 项目的核心组织框架，通过以下机制实现高效的任务处理：

1. **统一模板**：所有技能遵循标准化 SKILL.md 格式
2. **关键词路由**：基于触发词的任务自动分发
3. **Gadget 封装**：MCP 工具通过统一接口暴露
4. **模式结晶**：支持主动和自动两种技能生成方式
5. **回退机制**：确保系统在各种异常情况下的韧性
6. **制品路由**：标准化的输出路径管理

该体系使 Agent 能够根据用户请求的语义自动选择最合适的技能，同时保持良好的可扩展性和维护性。

---

<a id='langgraph-agent'></a>

## LangGraph Agent技能

### 相关页面

相关主题：[AI SDK Core技能](#ai-sdk-core), [Agent-Cryst技能](#agent-cryst)

Error with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e2052901c7e32982c8a82663eaab'}

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

---

<a id='ai-sdk-core'></a>

## AI SDK Core技能

### 相关页面

相关主题：[LangGraph Agent技能](#langgraph-agent)

Error with Openai API: Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'Token Plan 主要面向个人开发者的交互式使用场景。当前请求量较高，请稍后重试；如需支持更高并发或自动化任务，建议升级至更高级别套餐，或使用按量付费 API。 (2062)', 'http_code': '429'}, 'request_id': '0654e20df587a09b65b212207d578114'}

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

---

<a id='agent-cryst'></a>

## Agent-Cryst技能

### 相关页面

相关主题：[Crystallize技能](#crystallize)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)
- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)
- [skills/qmd-memory/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/qmd-memory/SKILL.md)
- [skills/shadow-mcp-gadgets/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-mcp-gadgets/SKILL.md)
</details>

# Agent-Cryst技能

## 概述

Agent-Cryst（代理结晶）是一种将智能体工作过程中的知识、工作流程和决策模式进行结构化提取、沉淀并复用的技能体系。其核心理念是将隐性的解决问题的方法转化为显性的、可存储的、可复用的技能资产。

这一技能与 SP-006（潜在技能观察器）形成互补关系：SP-006 自动检测工具调用序列中的模式，而 Agent-Cryst 则专注于从推理过程中主动提取有意义的模式。这两种机制共同为智能体提供持续学习和能力扩展的能力。

## 核心概念

### 什么是"结晶"（Crystallization）

"结晶"是将会话中产生的有价值的工作模式提取为标准化技能的过程。这个过程不仅捕获工具使用的序列，更关注捕获理解问题和解决问题的思维过程。

资料来源：[skills/crystallize/SKILL.md:1-30]()

### 与其他模式的关系

Agent-Cryst 与智能体生态中的多个组件相互协作：

| 组件 | 关系 | 作用 |
|------|------|------|
| SP-006 | 互补 | 自动观察工具调用序列，检测潜在模式 |
| 记忆系统 | 下游 | 结晶后的技能存储到持久化记忆 |
| 技能注册表 | 目标 | 结晶产物成为可索引的技能条目 |
| MCP工具 | 扩展 | 通过MCP协议实现技能的分布式调用 |

资料来源：[skills/crystallize/SKILL.md:70-85]()

## 结晶工作流

### 标准流程（default模式）

```mermaid
graph TD
    A[任务完成] --> B{应该复用吗?}
    B -->|是| C[回顾会话]
    B -->|否| Z[完成]
    C --> D[提取模式]
    D --> E{检查范围}
    E --> F[搜索现有技能]
    F --> G{发现重叠?}
    G -->|是| H[更新现有技能]
    G -->|否| I[创建新技能]
    H --> J[记录结晶日志]
    I --> J
```

标准流程包含以下步骤：

1. **回顾（Review）**：明确任务、解决的问题、学到的内容，以及需要重复的步骤
2. **模式提取（Pattern Extraction）**：识别可复用的模式，包括关键步骤、启发式规则、陷阱和决策点
3. **范围检查（Scope Check）**：确定结晶产物的适用边界
4. **去重检查（Deduplication）**：搜索现有技能，避免重复创建
5. **创建/更新技能**：生成新的技能文件或更新现有技能
6. **记录结晶日志**：保存元数据到技能文件的 `## Crystallized From` 部分

资料来源：[skills/crystallize/SKILL.md:40-70]()

### 快速模式（quick模式）

当需要在任务中途快速捕获发现的模式时使用此模式，输出为最小化的技能存根，后续再进行完整优化：

| 模式 | 输出 | 触发词 |
|------|------|--------|
| `default` | 完整结晶流程 | `crystallize`, `capture this as a skill` |
| `quick` | 最小技能存根 | `quick crystallize`, 任务中模式发现 |
| `exploratory` | 向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |
| `drag-response` | 立即结晶 | `this took too long`, `why aren't you...` |
| `correction` | 立即更新 | 操作员修正时 |
| `audit` | 检查遗漏的模式 | `what patterns did we miss` |

资料来源：[skills/crystallize/SKILL.md:50-65]()

## 模式提取方法论

### 关键步骤提取

最小化产生结果所需的动作序列。通过分析会话中的决策点，识别哪些步骤是必须的，哪些是可选的。

### 启发式规则识别

在判断过程中产生的经验规则。例如：
- "当遇到 X 类型错误时，首先检查 Y 配置"
- "对于 A 类任务，使用 B 工具比 C 工具更高效"

### 陷阱记录

记录容易出错的地方和失败假设：
- 什么操作导致问题或差点导致问题
- 哪些假设在实际执行中失败了
- 环境或上下文的特殊依赖条件

### 决策点文档化

记录选择过程：
- 在哪个环节做出了选择？
- 选择的原因是什么？
- 替代方案有哪些，为什么没有选择？

资料来源：[skills/crystallize/SKILL.md:30-40]()

## 探索模式扩展

当使用探索模式时，结晶过程会向外扩展一圈，检查可能携带相同陈旧假设的相邻表面。

扩展检查范围：
1. 从精确修复的问题开始
2. 检查最近的相邻表面
3. 识别可能携带相同问题的其他区域
4. 捕获更广泛的复用规则

```mermaid
graph TD
    A[精确修复] --> B[检查相邻表面]
    B --> C{发现相同问题?}
    C -->|是| D[扩展修复范围]
    C -->|否| E[记录该区域安全]
    D --> F[捕获广泛规则]
    E --> G[继续检查下一个表面]
    F --> G
```

资料来源：[skills/crystallize/SKILL.md:45-50]()

## 技能结构规范

### 技能文件模板

```markdown
# Skill Name

One-line description. Use when [trigger phrases].

## When to Use
- [trigger 1]
- [trigger 2]
- [trigger 3]

## Workflow
1. [Step 1]
2. [Step 2]
3. [Step 3]

## Key Decisions
- [Decision point 1]: [default choice + why]
- [Decision point 2]: [default choice + why]

## Gotchas
- [Common mistake 1]
- [Common mistake 2]

## Crystallized From
- Session: [date/context]
- Original task: [what was being solved]
```

资料来源：[skills/write-a-skill/SKILL.md:1-20]()

### 描述规范

技能描述是智能体决定加载哪个技能时看到的唯一信息，必须清晰准确：

| 要求 | 说明 |
|------|------|
| 最大长度 | 1024字符 |
| 视角 | 第三人称 |
| 第一句 | 功能描述 |
| 第二句 | 触发条件（Use when...） |

**良好示例：**
```
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**不良示例：**
```
Helps with documents.
```

资料来源：[skills/write-a-skill/SKILL.md:30-50]()

### 文件拆分原则

| 条件 | 行动 |
|------|------|
| SKILL.md 超过 100 行 | 拆分为多个文件 |
| 内容跨越不同领域 | 拆分为独立文件 |
| 高级功能很少使用 | 分离到 REFERENCE.md |

资料来源：[skills/write-a-skill/SKILL.md:60-70]()

### 脚本添加原则

以下情况应添加工具脚本：
- 操作是确定性的（验证、格式化）
- 相同代码会被重复生成
- 错误需要显式处理

脚本可以节省 token 消耗并提高可靠性。

资料来源：[skills/write-a-skill/SKILL.md:55-60]()

## 产物路由

### 结晶产物存储

| 产物类型 | 路径 | 用途 |
|----------|------|------|
| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |
| 更新技能 | 现有技能相同路径 | 扩展能力 |
| 结晶日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |

### 企业级技能

对于特定企业场景的模式，应放在适当的企业子目录下：

```
~/.agents/skills/<enterprise>/<skill-name>/
```

资料来源：[skills/crystallize/SKILL.md:60-65]()

## 记忆系统集成

### 记忆提取流程

Agent-Cryst 与 qmd-memory 系统集成，支持从会话内容中提取知识：

```bash
# 从文件提取
qmd-memory extract notes.md --source-id "file:notes.md"

# 从标准输入提取（如 Bee 对话）
bee conversations get <id> --json | jq -r '.summary' | qmd-memory extract - --source-id "bee:conv:<id>"

# 干运行（预览将要提取的内容）
qmd-memory extract notes.md --dry-run
```

### 记忆类型

| 类型 | 用途 | 示例 |
|------|------|------|
| `fact` | 事实性知识 | "TypeScript 是主要语言" |
| `commitment` | 承诺事项 | "周五前完成设置" |
| `decision` | 决策记录 | "决定使用本地优先方案" |
| `preference` | 偏好设置 | "喜欢使用 vim" |
| `context` | 上下文信息 | "当前聚焦 bee 设置" |

资料来源：[skills/qmd-memory/SKILL.md:1-30]()

## MCP工具集成

### Shadow MCP架构

Agent-Cryst 通过 MCP 协议与各种工具集成：

```mermaid
graph TD
    A[Agent] --> B[Shadow MCP Federation]
    B --> C[ARC 记忆存储]
    B --> D[ESP 上下文组装]
    B --> E[ANT 网格健康]
    B --> F[TAP 浏览器控制]
    B --> G[OWL 环境信息]
    B --> H[ORB 语音输出]
    B --> I[Factory 专利流水线]
```

| 触发词 | 工具 | 功能 |
|--------|------|------|
| `arc.store`, `arc.search` | ARC | 记忆存储和检索 |
| `esp.assemble`, `/renew-ctx` | ESP | 统一上下文组装 |
| `ant.mesh` | ANT | 网格健康状态 |
| `tap.tabs`, `tap.execute` | TAP | Chrome 标签页控制 |
| `owl.brief`, `owl.extract` | OWL | 环境信息提取 |
| `orb.say`, `orb.voices` | ORB | macOS TTS 语音输出 |

资料来源：[skills/shadow-mcp-gadgets/SKILL.md:1-30]()

## 重构与模式检测

### 模式提取分析

Agent-Cryst 可以与 shadow-refactor 技能协作，通过多种方式进行模式检测：

| 方法 | 说明 | 适用场景 |
|------|------|----------|
| 重复代码检测 | 查找 3 行以上相同的代码块 | 发现复制粘贴模式 |
| 复杂度热点 | 函数超过 50 行、文件超过 500 行 | 识别需要重构的区域 |
| AST 分析 | 抽象语法树分析 | 深度代码结构检查 |
| 本地 LLM 辅助 | 使用 Ollama 进行模式分析 | 当 Ollama 可用时 |

### 本地 LLM 模式分析

当 Ollama 服务可用时，可以使用 qwen3:8b 等模型进行智能模式检测：

```python
import httpx
resp = httpx.post("http://localhost:11434/api/generate", json={
    "model": "qwen3:8b",
    "prompt": f"Analyze this code for refactoring opportunities. Be specific:\n\n{code}",
    "stream": False,
})
suggestions = resp.json()["response"]
```

当 Ollama 不可用时，使用静态分析方法（grep、AST、文件指标）。

资料来源：[skills/shadow-refactor/SKILL.md:20-45]()

## 回退链

Agent-Cryst 技能实现了完整的回退链，确保在各种环境条件下都能正常工作：

| 优先级 | 条件 | 行为 |
|--------|------|------|
| 1 | MCP 服务器可用 | 使用 Shadow MCP 联合服务器 |
| 2 | MCP 服务器未运行 | 通过 `bun run` 启动服务 |
| 3 | Ollama 可用 | 启用智能模式分析 |
| 4 | Ollama 不可用 | 纯静态分析 |
| 5 | 记忆系统可用 | 存储到 ARC 记忆 |
| 6 | 记忆系统不可用 | 降级到文件存储 |

资料来源：[skills/shadow-mcp-gadgets/SKILL.md:45-55]()

## 审查清单

创建或更新技能后，应验证以下项目：

| 检查项 | 说明 |
|--------|------|
| 描述包含触发词 | 必须包含 "Use when..." 部分 |
| SKILL.md 行数 | 应在 100 行以内 |
| 无时间敏感信息 | 避免使用具体日期或临时状态 |
| 术语一致性 | 与其他技能保持统一术语 |
| 包含具体示例 | 提供可运行的示例代码 |
| 引用深度一级 | 相关文件使用相对路径引用 |

资料来源：[skills/write-a-skill/SKILL.md:75-85]()

## 最佳实践

### 何时使用结晶

- 工作流程是确定性的且会重复
- 相同的代码会被反复生成
- 错误需要显式处理和预防
- 存在需要记录的重要决策点

### 何时避免结晶

- 工作流是一次性的
- 存在太多例外情况无法标准化
- 结晶成本超过复用收益

### 结晶质量标准

1. **可执行性**：技能描述的步骤应能直接执行
2. **边界清晰**：明确技能的适用范围和限制
3. **自包含**：技能应包含所有必要的上下文
4. **可发现**：描述和触发词应便于智能体检索

## 总结

Agent-Cryst 技能是智能体能力持续演进的核心机制。通过系统化的知识结晶过程，智能体能够：

- 将会话中获得的经验转化为可复用资产
- 建立与 SP-006 的互补关系，实现主动和被动模式检测
- 通过 MCP 工具集成实现分布式能力扩展
- 与记忆系统深度集成，支持知识的持久化和检索

这一技能遵循"边做边学"的原则，确保每次有价值的交互都能成为未来工作的基础。

---

<a id='write-a-skill'></a>

## 编写技能指南

### 相关页面

相关主题：[Crystallize技能](#crystallize)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/write-a-skill/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/write-a-skill/SKILL.md)
- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
- [skills/skill-surgery-rd/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/skill-surgery-rd/SKILL.md)
- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)
- [skills/shadow-refactor/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/shadow-refactor/SKILL.md)
</details>

# 编写技能指南

本指南介绍如何在 s4b7-ai-skills 项目中创建、编写和维护技能（Skill）。技能是模块化的能力单元， agents 可以根据任务需求动态加载和使用。

## 概述

技能（Skill）是一种结构化的知识封装形式，用于将重复性任务的执行模式固化为可复用的指南。每个技能通常包含以下组成部分：

| 组成部分 | 说明 |
|---------|------|
| `SKILL.md` | 核心技能定义文件，包含描述、工作流程、高级特性引用 |
| `scripts/` | 工具脚本目录（可选），用于确定性操作、格式化、错误处理 |
| `docs/` | 文档目录（可选），包含参考文档、计划、变更日志 |
| `REFERENCE.md` | 高级特性参考文档（可选） |

技能的设计原则：

- **Token 节约**：脚本和工具脚本可以节省 token 消耗，提高可靠性
- **可复用性**：通过结构化的工作流程和清单，确保任务执行的一致性
- **分层组织**：基本信息在 SKILL.md 中，高级特性拆分到独立文件

资料来源：[skills/write-a-skill/SKILL.md:1-20]()

## SKILL.md 模板结构

SKILL.md 是技能的入口文件，其标准模板结构如下：

```markdown
---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
```

### Frontmatter 配置

Frontmatter 部分定义了技能的基本元数据：

```yaml
---
name: skill-name          # 技能唯一标识符
description: 简短描述    # 用于 agent 识别的触发条件说明
---
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 技能的唯一标识符，应使用 kebab-case 命名 |
| `description` | string | 是 | 简短描述，用于 agent 在系统提示中识别何时加载此技能 |

资料来源：[skills/write-a-skill/SKILL.md:22-40]()

## Description 编写规范

Description 是 agent **唯一能看到的信息**，用于在系统提示中决定是否加载该技能。

### 格式要求

| 要求 | 说明 |
|------|------|
| 最大字符数 | 1024 characters |
| 人称 | 第三人称 |
| 句子结构 | 第一句描述功能，第二句描述触发条件（"Use when..."） |

### 编写示例

**正确示例**：
```
Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**错误示例**：
```
Helps with documents.
```

错误示例的问题在于：没有给 agent 提供足够的区分信息，无法将此技能与其他文档相关技能区分开来。

### 触发条件设计

Description 应明确列出触发关键词和场景：

| 触发类型 | 示例 |
|---------|------|
| 文件类型 | `PDF`, `Markdown`, `JSON`, `YAML` |
| 操作类型 | `write`, `refactor`, `debug`, `translate` |
| 领域关键词 | `patent`, `engineering`, `automotive` |
| 上下文 | `local`, `private`, `no cloud` |

资料来源：[skills/write-a-skill/SKILL.md:42-65]()

## 目录结构规范

### 基础结构

```
skill-name/
├── SKILL.md          # 必需：技能入口文件
├── scripts/          # 可选：工具脚本目录
│   └── helper.js
├── docs/             # 可选：文档目录
│   ├── plans/        # 计划文档
│   └── REFERENCE.md  # 参考文档
```

### Crystallize 模式下的结构

当使用 crystallize 模式创建技能时，可能包含以下附加结构：

```
skills/
└── <name>/
    ├── SKILL.md      # 新建或更新的技能
    └── docs/plans/crystallization-log.md  # 可选：结晶化历史记录
```

资料来源：[skills/crystallize/SKILL.md:50-65]()

## 脚本使用规范

### 何时添加脚本

添加工具脚本的判断标准：

| 判断标准 | 说明 |
|---------|------|
| 操作确定性 | 操作是确定性的（验证、格式化）而非探索性的 |
| 代码重复 | 相同代码会被反复生成 |
| 错误处理 | 需要显式的错误处理逻辑 |

使用脚本的优势：
- 节省 token 消耗
- 提高执行可靠性
- 避免每次生成可能产生的错误

### 脚本类型

| 脚本类型 | 示例用途 |
|---------|---------|
| 验证脚本 | 语法检查、schema 验证 |
| 格式化脚本 | 代码格式化、文件规范化 |
| 生成脚本 | 模板填充、代码生成 |
| 集成脚本 | API 调用、数据转换 |

资料来源：[skills/write-a-skill/SKILL.md:67-78]()

## 文件拆分规范

### 拆分时机

| 条件 | 触发操作 |
|------|---------|
| SKILL.md 超过 100 行 | 考虑拆分到 REFERENCE.md |
| 内容领域差异明显 | 按领域拆分（如 finance vs sales schemas） |
| 高级特性使用频率低 | 拆分到独立文件，按需加载 |

### 拆分策略

- **一级引用**：SKILL.md 仅引用一层深度的文件
- **避免过度拆分**：保持技能的完整性，避免碎片化
- **保持可导航性**：拆分后的文件结构应保持清晰的导航路径

资料来源：[skills/write-a-skill/SKILL.md:80-95]()

## 技能工作流程

### Crystallize 模式工作流程

Crystallize 是一种从会话经验中提炼技能模式的方法，其标准工作流程如下：

```mermaid
graph TD
    A[任务完成] --> B{是否需要重复?}
    B -->|是| C[回顾会话]
    B -->|否| Z[完成]
    C --> D[提取模式]
    D --> E[检查范围]
    E --> F[搜索现有技能]
    F --> G{发现重叠?}
    G -->|是| H[更新现有技能]
    G -->|否| I[创建新技能]
    H --> J[记录结晶化]
    I --> J
```

### Crystallize 模式类型

| 模式 | 输出 | 适用场景 |
|------|------|---------|
| `default` | 完整结晶：审查→提取→范围检查→去重→创建/更新 | `crystallize`, `capture this as a skill` |
| `quick` | 快速捕获到最小技能存根 | `quick crystallize`, 任务中模式发现 |
| `exploratory` | 向外扩展一圈，检查相邻表面是否具有相同模式 | `--exploratory-mode`, `more crystallization` |
| `drag-response` | 立即结晶，由操作员挫败感触发 | `this took too long`, `why aren't you using...` |
| `correction` | 立即更新，基于操作员纠正 | 操作员纠正身份/路径/边界 |
| `audit` | 检查应该结晶但没有结晶的内容 | `what patterns did we miss` |

### 结晶化步骤详解

#### 1. 回顾（Review）

回答以下问题：
- 任务是什么？
- 解决了什么问题？
- 学到了什么？
- 下次会重复哪些步骤？

#### 2. 模式提取（Pattern Extraction）

识别可复用模式：

| 模式要素 | 说明 |
|---------|------|
| **关键步骤** | 产生结果的最简序列是什么？ |
| **启发式规则** | 需要哪些判断？出现了哪些经验法则？ |
| **陷阱** | 什么出错了或差点出错？哪些假设失败了？ |
| **决策点** | 在哪里选择不同方法？什么因素决定了选择？ |

#### 3. Exploratory-Mode 扩展

当操作员要求 "more crystallization" 或使用 `--exploratory-mode` 时：

1. 从修复的确切位置开始
2. 检查最近的相邻表面是否有相同的过时假设
3. 捕获更广泛的复用规则

资料来源：[skills/crystallize/SKILL.md:15-50]()

## 技能审核清单

创建或更新技能后，使用以下清单进行自检：

| 检查项 | 说明 |
|-------|------|
| Description 包含触发条件 | 包含 "Use when..." 格式的触发条件描述 |
| SKILL.md 行数控制 | 保持在 100 行以内 |
| 无时间敏感信息 | 避免硬编码日期、价格等会过时的信息 |
| 术语一致性 | 全文使用统一的术语命名 |
| 包含具体示例 | 提供可直接使用的代码示例 |
| 引用层级控制 | 仅引用一层深度的文件 |

资料来源：[skills/write-a-skill/SKILL.md:97-110]()

## 技能路由与上下文集成

### 与 SP-006 的关系

SP-006（潜在技能观察器）从工具调用序列自动检测模式。Crystallize 技能通过**有意的结晶**补充 SP-006——这些模式从问题理解中产生，而非仅从工具使用观察中产生。两种机制共享相同的技能命名空间。

### 上下文引用

技能应引用相关的上下文文件：

```markdown
## 上下文引用

- 技能花园（skills garden）
- Mesh 上下文技能
- 全局架构规则（来自 `GLOBAL_AGENT_RULES.md`）
```

### 关键路径参考

| 路径类型 | 用途 |
|---------|------|
| 第一方技能 | `~/.agents/skills/<skill-name>/SKILL.md` |
| 供应商技能 | `~/.agents/skills/` |
| 企业特定技能 | 适当的 `~/.agents/skills/` 子目录 |
| 项目技能 | 项目级别 `skills/` 目录 |

资料来源：[skills/codex-context/SKILL.md:1-25]()

## 技能手术与维护

### Skill Surgery 工具

`s4b7-ai-skills` 提供了技能维护相关的脚本：

| 脚本 | 功能 |
|------|------|
| `audit-skills.mjs` | 审计技能完整性 |
| `cluster-skill-triggers.mjs` | 聚类技能触发条件 |
| `redirect-deprecated-skill.mjs` | 重定向已弃用技能 |

### 维护操作类型

| 操作 | 说明 |
|------|------|
| 创建（Create） | 新建技能定义 |
| 更新（Update） | 扩展或修改现有技能 |
| 合并（Merge） | 合并重叠技能 |
| 重定向（Redirect） | 将旧技能重定向到新位置 |
| 审核（Audit） | 检查技能健康状态 |

### 维护原则

- **禁止在探索性手术期间删除技能**，先重定向，删除需操作员明确批准
- **不编辑归档历史**，除非仍作为活动触发问题浮现
- **不创建大型综合技能**，优先使用一个规范路由器加专注子技能
- **研究后再发明**，不结晶过时版本号、价格或 API 形状

资料来源：[skills/skill-surgery-rd/SKILL.md:1-30]()

## 产物路由规范

技能执行后的产物应路由到指定路径：

| 产物类型 | 路径 | 用途 |
|---------|------|------|
| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |
| 更新技能 | 现有技能路径 | 扩展能力 |
| 结晶日志 | `docs/plans/crystallization-log.md` | 所有结晶化历史记录（可选） |
| 扫描报告 | `ShadowArchive/80-reports/` | 跨域探索结果 |
| 重构报告 | `ShadowArchive/80-reports/refactor-<target>-YYYY-MM-DD.md` | 重构会话摘要 |

### 产物格式

| 格式 | 使用场景 |
|------|---------|
| JSONL | 机器可读的日志、信号数据 |
| Markdown | 人类可读的文档、报告 |
| YAML | 配置文件、元数据 |

资料来源：[skills/crystallize/SKILL.md:65-80]()

## 常见陷阱与注意事项

### SKILL.md 编写陷阱

| 陷阱 | 问题 | 解决方案 |
|------|------|---------|
| Description 过于笼统 | Agent 无法区分技能 | 使用具体触发关键词 |
| 包含时间敏感信息 | 信息会过时失效 | 避免硬编码日期/价格 |
| 过度拆分 | 碎片化降低可导航性 | 保持合理引用层级 |
| 缺少示例 | 用户无法快速上手 | 提供具体代码示例 |

### Crystallize 模式陷阱

| 陷阱 | 问题 | 解决方案 |
|------|------|---------|
| 过早停止 | 未发现相邻模式 | 使用 exploratory-mode |
| 假设验证缺失 | 结晶了错误模式 | 在结晶前验证假设 |
| 范围过大 | 创建了巨型技能 | 检查范围，控制技能边界 |

### 维护操作陷阱

| 陷阱 | 问题 | 解决方案 |
|------|------|---------|
| 循环重定向检测失败 | A→B→A 循环 | 阻止循环，要求手动解决 |
| 合并冲突未处理 | 合并目标有冲突的 gotchas | 保留双方 gotchas，标记供操作员审查 |
| 权限问题未报告 | 无法访问技能目录 | 报告并跳过，仅审计可访问目录 |

资料来源：[skills/write-a-skill/SKILL.md:97-110](); [skills/skill-surgery-rd/SKILL.md:25-40]()

## 最佳实践总结

### 设计原则

1. **最小化描述**：Description 应简洁明了，最大 1024 字符
2. **明确的触发条件**：让 agent 能准确判断何时加载技能
3. **层级组织**：基本信息在主文件，高级特性在引用文件
4. **可验证性**：提供清单和验收标准

### 执行原则

1. **确定性优先**：使用脚本处理确定性操作
2. **Token 效率**：脚本比每次生成代码更高效可靠
3. **可追踪性**：记录所有变更的来源和理由

### 维护原则

1. **不破坏性修改**：优先重定向而非删除
2. **持续审计**：定期检查技能健康状态
3. **模式复用**：跨技能识别和提取复用模式

---

本指南基于 s4b7-ai-skills 项目的实际源码编写，涵盖了从技能创建到维护的完整生命周期。遵循本指南可以确保技能的可用性、可维护性和可扩展性。

---

<a id='crystallize'></a>

## Crystallize技能

### 相关页面

相关主题：[Agent-Cryst技能](#agent-cryst), [编写技能指南](#write-a-skill)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/crystallize/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/crystallize/SKILL.md)
</details>

# Crystallize技能

## 概述

Crystallize（结晶化）技能是一种从AI代理会话中提取和固化可复用模式的方法论。其核心目标是将隐性的问题解决方案转化为显性的、结构化的技能文档，使AI代理能够在未来的类似场景中快速调用经过验证的最佳实践。

该技能与SP-006（潜在技能观察器）形成互补关系：SP-006通过自动观察工具调用序列来检测模式，而Crystallize则通过有意识的推理来提取模式——这些模式源于对问题的理解，而不仅仅是工具使用的观察。两者共同服务于同一个技能命名空间。

资料来源：[skills/crystallize/SKILL.md:1-20]()

## 技能定位

Crystallize技能专注于以下类型的模式提取：

- 需要人类判断力的复杂决策流程
- 跨会话累积的专业知识
- 难以从工具调用序列自动推断的启发式规则
- 需要解释"为什么这样做"的推理链

以下类型的模式不适合通过Crystallize提取：

- 代码库本身显而易见的操作
- 纯确定性的自动化任务
- 单一会话内完成且不再复发的临时需求

资料来源：[skills/crystallize/SKILL.md:20-30]()

## 工作流程

Crystallize技能采用结构化的工作流程来确保提取的模式具有高质量和可复用性。

```mermaid
graph TD
    A[任务完成] --> B{是否应该复用?}
    B -->|是| C[回顾会话]
    B -->|否| Z[完成]
    C --> D[提取模式]
    D --> E[检查范围]
    E --> F{发现重叠?}
    F -->|是| G[更新现有技能]
    F -->|否| H[创建新技能]
    G --> I[记录结晶化日志]
    H --> I
```

### 步骤一：回顾（Review）

在回顾阶段，需要回答以下关键问题：

- **任务是什么？** 明确本次会话要解决的原始问题
- **解决了什么问题？** 描述最终达成的结果
- **学到了什么？** 提取本次获得的关键知识
- **下次会重复哪些步骤？** 识别可复用的工作流

资料来源：[skills/crystallize/SKILL.md:76-82]()

### 步骤二：模式提取（Pattern Extraction）

从回顾中识别可复用模式，包含四个维度：

| 维度 | 描述 | 示例 |
|------|------|------|
| **关键步骤** | 产生结果的最少必要序列 | 读取配置 → 验证格式 → 解析数据 → 输出结果 |
| **启发式规则** | 需要判断力的经验法则 | 文件超过500行应考虑拆分 |
| **常见陷阱** | 容易出错或差点出错的点 | 忘记处理空输入导致崩溃 |
| **决策点** | 需要在备选方案中做选择的地方 | 选择A/B方案时的判断依据 |

资料来源：[skills/crystallize/SKILL.md:83-97]()

### 步骤三：检查范围（Check Scope）

在创建技能前，需要明确该模式的适用范围：

- **通用模式** → 放置在 `~/.agents/skills/<skill-name>/SKILL.md`
- **企业特定模式** → 放置在 `~/.agents/skills/` 下的适当子目录

同时需要评估模式是否会与其他现有技能产生重叠。如果发现重叠，应扩展现有技能而非创建新技能。

资料来源：[skills/crystallize/SKILL.md:59-65]()

### 步骤四：搜索现有技能（Search Existing Skills）

在创建或更新技能前，必须检查是否已存在相关技能：

- 扫描现有技能目录
- 检查是否有相似的触发短语或描述
- 评估模式重叠程度

如果发现重叠，优先更新现有技能的结构，而非创建重复的技能文档。

资料来源：[skills/crystallize/SKILL.md:66-70]()

### 步骤五：创建或更新技能

**创建新技能**

```markdown
~/.agents/skills/<slug>/SKILL.md
```

**更新现有技能**

将新模式作为新章节添加，或扩展现有工作流程。保留技能原有结构。

**记录结晶化元数据**

在技能文件底部添加 `## Crystallized From` 章节：

```markdown
## Crystallized From
- Session: [日期/上下文]
- Original task: [正在解决的任务]
- Pattern extracted: [提取的模式描述]
```

如果使用了探索模式，还需记录：
- 检查了哪些相邻表面
- 故意保留未检查的表面

资料来源：[skills/crystallize/SKILL.md:45-58]()

## 技能模式

Crystallize技能支持六种不同的模式，以适应不同的使用场景。

| 模式 | 输出 | 触发条件 |
|------|------|----------|
| `default` | 完整结晶化：回顾 → 提取 → 范围检查 → 去重 → 创建/更新 | `crystallize`, `capture this as a skill` |
| `quick` | 快速捕获到最小技能存根（稍后完善） | `quick crystallize`, `mid-task pattern discovery` |
| `exploratory` | 从修复点向外扩展一圈，检查相邻表面 | `--exploratory-mode`, `more crystallization` |
| `drag-response` | 由操作员挫败感触发的即时结晶化 | `this took too long`, `why aren't you using...` |
| `correction` | 由操作员纠正触发的即时更新 | 操作员纠正身份/路径/边界 |
| `audit` | 检查应该结晶化但未结晶化的内容 | `what patterns did we miss` |

资料来源：[skills/crystallize/SKILL.md:34-45]()

### 探索模式扩展规则

当操作员请求"更多结晶化"或引用 `--exploratory-mode` 时，不应在本地修复处停止。应该向外扩展一圈并捕获更广泛的可用规则。

扩展检查清单：

1. 从被修复的具体内容开始
2. 检查可能包含相同陈旧假设的最近相邻表面
3. 对每个相邻表面执行相同模式检查

```mermaid
graph LR
    A[精确修复点] --> B[相邻表面 1]
    A --> C[相邻表面 2]
    A --> D[相邻表面 3]
    B --> E{存在相同模式?}
    C --> E
    D --> E
    E -->|是| F[扩展规则到相邻表面]
    E -->|否| G[记录为已检查]
```

资料来源：[skills/crystallize/SKILL.md:98-112]()

## SKILL.md 模板

每个通过Crystallize创建的技能都应遵循统一模板：

```markdown
---
name: skill-name
description: 简短描述功能。当 [触发短语] 时使用。
---

# Skill Name

## Quick start

[最小可用示例]

## Workflows

[复杂任务的分步流程，包含检查清单]

## Advanced features

[链接到单独文件：参见 REFERENCE.md]

## Key Decisions
- [决策点 1]: [默认选择 + 原因]
- [决策点 2]: [默认选择 + 原因]

## Gotchas
- [常见错误 1]
- [常见错误 2]

## Crystallized From
- Session: [日期/上下文]
- Original task: [正在解决的任务]
```

资料来源：[skills/crystallize/SKILL.md:2-25]()

### 描述撰写规范

技能的描述是代理决定加载哪个技能时看到的唯一信息，因此描述撰写至关重要：

**要求**

- 最多1024个字符
- 使用第三人称
- 第一句：功能是什么
- 第二句：`Use when [具体触发条件]`

**良好示例**

```
Extract text and tables from PDF files, fill forms, merge documents. 
Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**不良示例**

```
Helps with documents.
```

**触发条件示例**

| 触发类型 | 示例短语 |
|----------|----------|
| 文件类型 | `PDF`, `Excel`, `CSV`, `Markdown` |
| 操作类型 | `translate`, `refactor`, `debug`, `review` |
| 领域特定 | `patent`, `automotive`, `sourcing` |
| 上下文 | `local only`, `no cloud`, `private data` |

资料来源：[skills/crystallize/SKILL.md:90-115]()

## 工件路由

Crystallize技能产出的工件遵循明确的路由规则：

| 工件类型 | 路径 | 用途 |
|----------|------|------|
| 新技能 | `~/.agents/skills/<slug>/SKILL.md` | 可复用能力 |
| 更新技能 | 现有技能相同路径 | 扩展能力 |
| 结晶化日志 | `docs/plans/crystallization-log.md` | 历史记录（可选） |
| 企业特定技能 | `~/.agents/skills/` 下适当子目录 | 领域限定能力 |

资料来源：[skills/crystallize/SKILL.md:46-52]()

## 回退链

当主要路径不可用时，Crystallize技能遵循预定义的回退策略：

1. **主要路径**：完整工作流 — 回顾 → 提取 → 范围检查 → 去重 → 创建/更新
2. **回退选项**：检查是否有其他可用的模式提取入口
3. **最小化回退**：如果所有自动路径都失败，至少记录需要手动处理的待办事项

资料来源：[skills/crystallize/SKILL.md:71-75]()

## 与其他技能的关系

Crystallize技能不是孤立存在的，它与多个相关技能形成协作网络：

### 与SP-006（潜在技能观察器）的关系

| 方面 | SP-006 | Crystallize |
|------|--------|-------------|
| 模式来源 | 自动观察工具调用序列 | 有意识的推理和理解 |
| 适用场景 | 重复性操作模式 | 需要判断力的复杂决策 |
| 模式深度 | 浅层操作模式 | 深层推理链和启发式规则 |
| 自动化程度 | 完全自动 | 半自动，需要人类参与 |

两者共同服务于同一个技能命名空间，可以相互补充。

资料来源：[skills/crystallize/SKILL.md:21-24]()

### 与write-a-skill技能的关系

Crystallize负责从会话中提取模式，而 `write-a-skill` 负责将模式格式化为符合规范的技能文档。两者形成"提取 → 格式化"的流水线。

资料来源：[skills/write-a-skill/SKILL.md:1-30]()

## 最佳实践

### 何时使用Crystallize

- 同一类型的问题出现了多次
- 发现了可复用的工作流程或启发式规则
- 操作员表达了挫败感（"这花了太长时间"）
- 复杂的决策过程值得记录

### 何时不使用Crystallize

- 单次性、不再复发的任务
- 代码库本身显而易见的操作
- 纯确定性的自动化任务
- 模式过于具体，无法泛化

### 模式质量标准

一个好的结晶化模式应该：

1. **可独立理解**：不依赖会话上下文就能理解
2. **具体且可操作**：提供清晰的步骤或决策指导
3. **包含陷阱警告**：帮助新手避免常见错误
4. **标注决策点**：说明在何处需要判断力
5. **有触发条件**：明确何时应该使用该技能

资料来源：[skills/crystallize/SKILL.md:75-112]()

## 总结

Crystallize技能是构建可持续、可复用AI代理知识库的核心机制。通过结构化的"回顾 → 提取 → 检查 → 路由"流程，它将散落在各个会话中的隐性知识转化为显性的、可被代理系统自动加载的技能文档。六种模式（default、quick、exploratory、drag-response、correction、audit）确保了该机制能够适应从主动提炼到被动捕获等各种使用场景。

---

<a id='model-identity'></a>

## 模型身份管理

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)
- [skills/ai-sdk-core/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/SKILL.md)
- [skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)
- [skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)
- [skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)
- [skills/persona-engine/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/persona-engine/SKILL.md)
- [skills/model-identity/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-identity/SKILL.md)
- [skills/model-change-detector/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/model-change-detector/SKILL.md)

</details>

# 模型身份管理

模型身份管理是 AI Agent 系统中的核心能力，负责在不同模型提供商、版本和配置之间建立统一的身份标识、路由策略和状态管理机制。该系统通过标准化的接口和抽象层，使上层应用能够在多种 AI 模型之间透明切换，同时保持一致的行为特性和上下文连续性。

## 概述

在多模型 AI 生态系统中，模型身份管理解决以下核心问题：

| 问题域 | 描述 |
|--------|------|
| **身份标识** | 为每个模型实例建立唯一标识，包含提供商、模型名称、版本等元数据 |
| **版本追踪** | 监控模型变化，检测 breaking changes，维护兼容性信息 |
| **路由决策** | 根据任务类型、模型能力、成本和延迟等因素智能选择目标模型 |
| **状态保持** | 在模型切换时维护对话上下文和会话状态的一致性 |
| **配置管理** | 集中管理不同模型的 API 配置、认证信息和端点 |

资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

## 架构设计

### 核心组件

```mermaid
graph TD
    subgraph "模型身份管理层"
        MI[模型身份注册表]
        MV[模型版本追踪器]
        MC[模型能力映射]
    end
    
    subgraph "路由决策层"
        RH[路由启发式引擎]
        RP[Provider特定准备器]
        RT[令牌成本计算器]
    end
    
    subgraph "执行层"
        AE[AI SDK执行器]
        CT[Claude集成]
        GT[Gemini集成]
        OT[Ollama集成]
    end
    
    subgraph "上下文管理层"
        CM[上下文管理器]
        SS[会话状态]
        CTX[历史上下文]
    end
    
    MI --> RH
    MV --> MC
    MC --> RH
    RH --> RP
    RP --> AE
    AE --> CT
    AE --> GT
    AE --> OT
    CM --> SS
    SS --> CTX
```

### 模型身份注册表

模型身份注册表维护所有可用模型的元数据信息，包括：

- **Provider 标识**：OpenAI、Anthropic、Google、Ollama 等
- **模型 ID**：如 `gpt-4o`、`claude-sonnet-4-6`、`gemini-2.0-flash-001`
- **版本信息**：stable、beta、latest 等
- **能力标签**：文本生成、代码补全、函数调用、视觉识别等

资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)

## 多模型路由机制

### 路由决策流程

```mermaid
graph LR
    A[用户请求] --> B{关键词检测}
    B -->|write, refactor, debug| C[Codex]
    B -->|research, summarize| D[Gemini]
    B -->|local, private| E[Ollama]
    B -->|translate, JP| F[Codex]
    
    C --> G[执行并返回]
    D --> G
    E --> G
    F --> G
```

### 路由启发式规则

根据请求类型自动选择最优模型：

| 请求特征 | 路由目标 | 理由 |
|----------|----------|------|
| `write`, `implement`, `refactor`, `debug code` | codex | 代码能力强 |
| `research`, `summarize`, `find`, `compare` | gemini | 搜索和总结能力 |
| `translate`, `JP`, `Japanese` | Codex | 语言处理 |
| `local`, `private`, `no cloud` | ollama | 隐私保护 |
| `review`, `architect`, `design` | Codex | 深度分析 |
| `quickly`, `fast`, `brief` | ollama | 低延迟 |
| 文件路径、diffs、PRs | codex | 代码上下文 |

资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

## 模型版本管理

### 版本追踪机制

模型版本追踪器持续监控各 Provider 的模型变更：

```mermaid
graph TD
    A[定期检查] --> B{发现新版本?}
    B -->|是| C[更新版本信息]
    B -->|否| D[保持现有状态]
    C --> E{Breaking Change?}
    E -->|是| F[触发告警]
    E -->|否| G[标记为兼容更新]
    F --> H[更新迁移指南]
    G --> I[记录变更日志]
    H --> J[通知相关组件]
    I --> J
```

### AI SDK v5/v6 变更管理

AI SDK 核心技能模块处理模型变更的兼容性：

```mermaid
graph TD
    A[检测 SDK 版本] --> B{v5 或 v6?}
    B -->|v4 迁移| C[执行迁移检查清单]
    B -->|v5| D[使用 CoreMessage 类型]
    B -->|v6 Beta| E[Agent 抽象模式]
    
    C --> F[验证 API 兼容性]
    D --> G[使用 convertToCoreMessages]
    E --> H[使用新版 Agent]
    
    F --> I[生成迁移报告]
    G --> J[运行时验证]
    H --> J
```

**关键变更点：**

| 变更项 | v4 | v5/v6 |
|--------|-----|-------|
| 消息类型 | `CoreMessage` | `ModelMessage` |
| UI消息 | `Message` | `UIMessage` |
| 工具错误 | `ToolExecutionError` | 普通 Error 对象 |
| 结果字段 | `args`/`result` | `input`/`output` |

资料来源：[skills/ai-sdk-core/references/v5-breaking-changes.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/ai-sdk-core/references/v5-breaking-changes.md)

## Provider 特异性配置

### 各 Provider 的模型标识

| Provider | 模型标识 | 默认模型 | 深度任务模型 |
|----------|----------|----------|--------------|
| **Codex (via ACP)** | `Codex-sonnet-4-6` | 默认选择 | `Codex-opus-4-6` |
| **Gemini (via OpenRouter)** | `google/gemini-2.0-flash-001` | 速度优先 | `google/gemini-2.5-pro` |
| **Ollama** | `qwen3:8b` | 本地默认 | - |
| **Tier 1 API** | Provider 特定 | - | - |

### Provider 特定准备

在委托任务前，系统会自动应用 Provider 特定的转换：

```mermaid
graph TD
    A[原始请求] --> B{目标 Provider?}
    B -->|qwen3 (Ollama)| C[/no_think 前缀]
    B -->|Codex (mcp__codex)| D[设置 workdir]
    B -->|Gemini (OpenRouter)| E[选择模型]
    
    C --> F[执行请求]
    D --> F
    E --> F
```

**Ollama qwen3 模型特殊处理：**
```
→ 在提示前添加 /no_think
→ 或设置 options.think = false
```

资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

## 上下文与状态管理

### 多层上下文架构

模型身份管理依赖多层上下文系统确保状态一致性：

```mermaid
graph TD
    subgraph "上下文读取顺序"
        A[AGENTS.md] --> B[SHADOW-CONTEXT.md]
        B --> C[ARCHITECTURE.md]
        C --> D[SHADOW-ARCHITECTURE-SPEC.md]
        D --> E[VERIFIABILITY.md]
    end
    
    subgraph "关键路径"
        F[ShadowArchive] 
        G[Agent roots]
        H[Skills registry]
        I[Reports]
    end
    
    A --> F
    A --> G
    A --> H
    A --> I
```

### 会话状态持久化

| 文件 | 用途 | 位置 |
|------|------|------|
| Codex config | 模型、沙箱、MCP、插件配置 | `~/.codex/config.toml` |
| Codex memories | 跨会话持久记忆 | `~/.codex/memories/MEMORY.md` |
| Codex rules | Caveman 模式规则 | `~/.codex/rules/*.md` |
| Claude CLAUDE.md | 机器标识、本地覆盖 | `~/.claude/CLAUDE.md` |
| Claude AGENTS.md | Agent 开发规则 | `~/.claude/AGENTS.md` |
| Hermes SOUL.md | Shadow 角色默认配置 | `~/.hermes/SOUL.md` |

资料来源：[skills/codex-context/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/codex-context/SKILL.md)

## 检索与查询能力

### 多模型查询管道

系统提供多模型并行查询能力以获取多角度答案：

```mermaid
graph TD
    A[意图解析] --> B[扫描 Mesh 节点]
    B --> C[收集数据]
    C --> D[分析结果]
    D --> E[生成报告]
    
    subgraph "查询层级"
        T1[Tier 1: 快速并行查询]
        T2[Tier 2: 可用 API]
        T3[Tier 3: Web 检索]
        T4[Tier 4: Codex 自评]
    end
    
    T1 --> D
    T2 --> D
    T3 --> D
    T4 --> D
```

### 查询输出模式

| 模式 | 输出 | 使用场景 |
|------|------|----------|
| `default` | 摘要报告 | 常规扫描 |
| `full` | 完整转储 | 深度分析 |
| `json` | 原始数据 | 程序化处理 |

资料来源：[skills/multi-model-query/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/multi-model-query/SKILL.md)

## 角色引擎与身份切换

### 角色身份配置

角色引擎管理系统中不同 AI 角色的身份配置：

| 角色 | 配置文件 | 用途 |
|------|----------|------|
| Hermes (Shadow) | `~/.hermes/SOUL.md` | 默认 Shadow 角色 |
| Red (M3 Enterprise) | `~/.hermes/profiles/astemo/SOUL.md` | 企业级角色 |
| Gemini | `~/.gemini/GEMINI.md` | YOLO 模式 + 全局规则 |
| Duality | `/Volumes/☯Duality/AGENTS.md` | 主控平面 |

### 身份切换流程

```mermaid
graph TD
    A[请求到达] --> B{目标角色?}
    B -->|Shadow| C[加载 Hermes SOUL]
    B -->|Enterprise| D[加载 Red SOUL]
    B -->|Gemini| E[加载 GEMINI]
    B -->|Duality| F[加载 AGENTS.md]
    
    C --> G[应用角色配置]
    D --> G
    E --> G
    F --> G
    
    G --> H[执行任务]
    H --> I[返回结果]
```

## 错误处理与降级策略

### 故障恢复链

| 故障场景 | 恢复策略 |
|----------|----------|
| Mesh 不可达 | 跳过 Mesh 健康检查；继续本地分析 |
| Caresoft API 不可用 | 报告；跳过工程情报模式 |
| Skills 目录为空 | 报告；检查 `~/.agents/skills/` |
| 特定模型不可用 | 自动降级到备选模型 |
| 会话历史不可读 | 使用默认上下文重新初始化 |

### 降级执行顺序

1. **主链路**：完整扫描 → TDD 循环 → 验证 → 信号 → 下一任务
2. **Ollama 不可用**：仅静态分析（grep、AST、文件指标）
3. **测试未找到**：扫描测试；如不存在则搭建最小测试结构
4. **自修复耗尽**：回滚更改；标记为不可恢复；继续下一问题

资料来源：[skills/acp-delegate-auto/SKILL.md](https://github.com/s4b7-ai/s4b7-ai-skills/blob/main/skills/acp-delegate-auto/SKILL.md)

## 最佳实践

### 模型选择指南

```mermaid
graph TD
    A[新任务] --> B{任务类型?}
    B -->|代码生成| C[Codex - 代码能力强]
    B -->|创意写作| D[Gemini - 多样性高]
    B -->|隐私敏感| E[Ollama - 本地处理]
    B -->|快速原型| F[Ollama - 低延迟]
    B -->|深度分析| G[Codex Opus - 深度思考]
    
    C --> H[执行]
    D --> H
    E --> H
    F --> H
    G --> H
```

### 配置验证

使用以下命令验证模型配置：

```bash
# 检查 Ollama 是否运行
curl -s http://localhost:11434/api/tags | head -1

# 验证 AI SDK 模型 ID 和定价
npm run verify:portable

# 检查技能目录
find ~/.agents/skills/ -name "*.md" | wc -l
```

### 模型能力映射表

| 能力需求 | 推荐模型 | 备选模型 |
|----------|----------|----------|
| 实时代码补全 | Codex | Ollama qwen3 |
| 长文本生成 | Gemini 2.5 Pro | Codex Opus |
| 多语言翻译 | Codex | Gemini Flash |
| 本地隐私处理 | Ollama qwen3 | - |
| 函数调用 | AI SDK v5/v6 | Provider 原生 |

## 相关技能模块

| 技能名称 | 功能描述 |
|----------|----------|
| `model-identity` | 模型身份标识与注册 |
| `model-change-detector` | 模型变更检测与告警 |
| `persona-engine` | 角色身份与切换管理 |
| `multi-model-query` | 多模型并行查询 |
| `ai-sdk-core` | AI SDK 核心集成 |
| `acp-delegate-auto` | 自动委托与路由 |

## 总结

模型身份管理是整个 AI Agent 系统的基础设施层，通过标准化的接口、智能路由和状态管理，使系统能够在多个 AI 模型提供商之间灵活切换，同时保持一致的用户体验和上下文连续性。该系统支持版本追踪、故障恢复、角色切换等高级功能，为构建复杂的多模型 AI 应用提供了坚实的技术基础。

---

---

## Doramagic 踩坑日志

项目：s4b7-ai/s4b7-ai-skills

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `s4b7-ai-skills` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx skills`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | repo=s4b7-ai-skills; install=skills

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | last_activity_observed missing

## 4. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1238156052 | https://github.com/s4b7-ai/s4b7-ai-skills | release_recency=unknown

<!-- canonical_name: s4b7-ai/s4b7-ai-skills; human_manual_source: deepwiki_human_wiki -->