项目简介

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

系统架构

架构分层

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

技能分类体系

资料来源：skills/shadow-engg/SKILL.md

核心组件详解

1. 技能定义规范

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

系统要求

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

资料来源：package.json

安装方式

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

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

npm install -g s4b7-ai-skills

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

s4b7-ai-skills --version

资料来源：scripts/install.js

方式二：本地项目安装

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

# 创建项目目录
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

方式三：从源码构建

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

# 克隆仓库
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

安装流程图

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

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

环境配置

配置文件位置

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

基本配置

创建或编辑配置文件：

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

资料来源：distribution.json

环境变量

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

依赖组件

Ollama 本地模型服务

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

# 安装 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

ShadowArchive 存储卷（可选）

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

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

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

资料来源：skills/codex-context/SKILL.md

安装验证

完整性检查

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

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

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

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

常见验证命令

资料来源：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

卸载

如需卸载 s4b7-ai-skills：

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

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

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

故障排除

安装失败

运行时问题

资料来源：skills/shadow-engg/SKILL.md

更新升级

检查更新

s4b7-ai-skills update --check

执行更新

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

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

资料来源：package.json

概述

技能（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 是每个技能的入口文件，必须包含以下组成部分：

概述

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

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

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

资料来源：write-a-skill/SKILL.md

概述

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

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

核心概念

什么是"结晶"（Crystallization）

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

资料来源：skills/crystallize/SKILL.md:1-30

与其他模式的关系

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

资料来源：skills/crystallize/SKILL.md:70-85

结晶工作流

标准流程（default模式）

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模式）

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

资料来源：skills/crystallize/SKILL.md:50-65

模式提取方法论

关键步骤提取

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

启发式规则识别

在判断过程中产生的经验规则。例如：

• "当遇到 X 类型错误时，首先检查 Y 配置"
• "对于 A 类任务，使用 B 工具比 C 工具更高效"

陷阱记录

记录容易出错的地方和失败假设：

• 什么操作导致问题或差点导致问题
• 哪些假设在实际执行中失败了
• 环境或上下文的特殊依赖条件

决策点文档化

记录选择过程：

• 在哪个环节做出了选择？
• 选择的原因是什么？
• 替代方案有哪些，为什么没有选择？

资料来源：skills/crystallize/SKILL.md:30-40

探索模式扩展

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

扩展检查范围：

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

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

资料来源：skills/crystallize/SKILL.md:45-50

技能结构规范

技能文件模板

# 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

描述规范

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

良好示例：

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

文件拆分原则

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

脚本添加原则

以下情况应添加工具脚本：

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

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

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

产物路由

结晶产物存储

企业级技能

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

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

资料来源：skills/crystallize/SKILL.md:60-65

记忆系统集成

记忆提取流程

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

# 从文件提取
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

记忆类型

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

MCP工具集成

Shadow MCP架构

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

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 专利流水线]

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

重构与模式检测

模式提取分析

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

本地 LLM 模式分析

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

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 技能实现了完整的回退链，确保在各种环境条件下都能正常工作：

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

审查清单

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

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

最佳实践

何时使用结晶

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

何时避免结晶

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

结晶质量标准

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

总结

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

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

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

概述

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

技能的设计原则：

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

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

SKILL.md 模板结构

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

概述

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

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

资料来源：skills/crystallize/SKILL.md:1-20

技能定位

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

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

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

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

资料来源：skills/crystallize/SKILL.md:20-30

工作流程

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

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）

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

资料来源：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

步骤五：创建或更新技能

创建新技能

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

更新现有技能

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

记录结晶化元数据

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

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

如果使用了探索模式，还需记录：

• 检查了哪些相邻表面
• 故意保留未检查的表面

资料来源：skills/crystallize/SKILL.md:45-58

技能模式

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

资料来源：skills/crystallize/SKILL.md:34-45

探索模式扩展规则

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

扩展检查清单：

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

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创建的技能都应遵循统一模板：

概述

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

资料来源：skills/acp-delegate-auto/SKILL.md

架构设计

核心组件

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

多模型路由机制

路由决策流程

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

路由启发式规则

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

资料来源：skills/acp-delegate-auto/SKILL.md

模型版本管理

版本追踪机制

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

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 核心技能模块处理模型变更的兼容性：

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

关键变更点：

资料来源：skills/ai-sdk-core/references/v5-breaking-changes.md

Provider 特异性配置

各 Provider 的模型标识

Provider 特定准备

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

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

上下文与状态管理

多层上下文架构

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

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

会话状态持久化

资料来源：skills/codex-context/SKILL.md

检索与查询能力

多模型查询管道

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

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

查询输出模式

资料来源：skills/multi-model-query/SKILL.md

角色引擎与身份切换

角色身份配置

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

身份切换流程

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[返回结果]

错误处理与降级策略

故障恢复链

降级执行顺序

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

资料来源：skills/acp-delegate-auto/SKILL.md

最佳实践

模型选择指南

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

配置验证

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

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

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

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

模型能力映射表

相关技能模块

总结

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

Pitfall Log / 踩坑日志

项目：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