02-候选方案深度分析

2.1 方案 A：嵌入式知识管理

2.1.1 定义与实现方式

嵌入式知识管理指将领域知识（架构、接口、数据库 Schema 等）直接写入 SKILL.md 文件。SKILL.md 不仅是 Agent 的调用入口，也是知识的唯一或主要载体。

典型目录结构：

project/
├── src/
│   ├── api/
│   │   ├── routes.py       # 实际 API 实现
│   │   └── models.py       # 数据模型
│   └── db/
│       └── schema.sql      # 数据库 Schema
├── docs/                   # 传统文档目录（可选）
│   └── architecture.md
└── .opencode/skills/
    └── api-developer/
        └── SKILL.md        # 包含完整 API 和数据库知识

SKILL.md 内容示例：

# API Developer Skill

## 架构概览

本项目采用分层架构：
- **Controller Layer**: FastAPI routes，处理 HTTP 请求
- **Service Layer**: 业务逻辑封装
- **Data Layer**: SQLAlchemy ORM 访问 PostgreSQL

## API 接口规范

### 用户管理

**GET /api/v1/users**
- 描述：获取用户列表
- 参数：
  - `page` (int, optional): 页码，默认 1
  - `limit` (int, optional): 每页数量，默认 20，最大 100
- 响应：UserList 对象

**POST /api/v1/users**
- 描述：创建新用户
- 请求体：CreateUserRequest
  - `username` (str, required): 用户名，3-50 字符
  - `email` (str, required): 邮箱格式
  - `role` (enum): admin|editor|viewer，默认 viewer

### 内容管理

**GET /api/v1/posts**
...

## 数据库 Schema

### users 表
| 字段 | 类型 | 约束 | 说明 |
|-----|------|-----|-----|
| id | UUID | PK | 主键 |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| email | VARCHAR(255) | UNIQUE, NOT NULL | 邮箱 |
| role | VARCHAR(20) | DEFAULT 'viewer' | 角色 |
| created_at | TIMESTAMP | DEFAULT NOW() | 创建时间 |

### posts 表
...

## 编码规范

1. 所有 API 返回统一包装格式：`{ "code": 0, "data": ..., "message": "ok" }`
2. 错误码范围：
   - 1000-1999: 通用错误
   - 2000-2999: 用户相关错误
   - 3000-3999: 内容相关错误

2.1.2 实际案例分析

案例 1：Vibe-Research 项目

该项目使用嵌入式 SKILL.md 管理研究内容生成流程：

# Research Skill

## 工作流程

1. **Plan Phase**: 分析用户需求，选择模板
2. **Create Phase**: 生成研究内容
3. **Commit Phase**: 自动提交到 Git

## 模板系统

位于 `templates/metadata.yaml`，定义了以下模板：
- **tech-solution**: 技术方案研究
- **financial-report**: 财务报告研究
- **academic-paper**: 学术论文研究

每个模板包含：
- 适用场景描述
- 关键词匹配规则
- 模块结构定义

## Mermaid 图表规范

**重要**: 生成图表前必须阅读 `templates/mermaid-bad-cases.md`

常见错误：
- 中文标签未加引号: `[中文, 标签]` ❌ 应改为 `["中文", "标签"]` ✅
- bar 语法错误: `bar [id] "label" [1, 2, 3]` ❌ 应改为 `bar [1, 2, 3]` ✅

## 质量标准

每个模块必须满足：
- 子章节密度: ≥3 个子章节
- 内容长度: 每子章节 ≥200 字
- 数据点密度: 每 300 字 1+ 数据点
- 可视化: 每模块 ≥1 个 Mermaid 图表

分析：

• ✅ 所有知识集中在 SKILL.md，Agent 一次读取即可开始工作
• ✅ 模板规则、图表规范等相对稳定的知识适合嵌入
• ⚠️ 如果模板频繁变更，SKILL.md 需要同步更新

案例 2：Claude Code 内置 Skills

Claude Code 的默认 skills 普遍采用嵌入式知识：

# git-master Skill

## 原子提交原则

1. **单一职责**: 每个 commit 只做一件事
2. **完整功能**: 提交必须是可工作的状态
3. **清晰描述**: commit message 说明"为什么"而非"做了什么"

## 常用命令模式

### 查看变更
```bash
git status                    # 查看工作区状态
git diff                      # 查看未暂存变更
git diff --cached            # 查看已暂存变更

提交变更

git add <file>               # 暂存特定文件
git add -p                   # 交互式选择 hunks
git commit -m "message"      # 提交

禁忌操作

• ❌ NEVER: git push --force to main/master
• ❌ NEVER: git commit --amend after push
• ❌ NEVER: git reset --hard on shared branches

**分析**：
- ✅ Git 知识**通用且稳定**，适合嵌入
- ✅ 命令模式是**使用指南**而非项目特定知识
- ✅ 一次编写，长期复用

### 2.1.3 优势分析

| 优势 | 详细说明 | 适用场景 |
|-----|---------|---------|
| **单次读取** | 所有知识在 SKILL.md 中，一次 I/O 即可获取全部信息 | 启动阶段 |
| **零依赖** | 不需要维护额外的知识库文件，降低项目复杂度 | 小型项目 |
| **版本一致** | SKILL.md 与知识同步版本化，不会出现引用失效 | 版本控制 |
| **离线可用** | 不依赖外部文件，单个文件即可完整描述领域知识 | 分发场景 |
| **原子更新** | 知识变更与 SKILL.md 更新是原子操作 | 简单变更 |

### 2.1.4 局限性与风险

| 局限/风险 | 具体表现 | 影响程度 |
|----------|---------|---------|
| **知识重复** | 与 docs/ 目录的文档重复，易不一致 | 🔴 高 |
| **更新负担** | 每次知识变更需修改 SKILL.md | 🟡 中 |
| **文件膨胀** | 大型项目的 SKILL.md 可能数千行 | 🟡 中 |
| **协作冲突** | 多人修改 SKILL.md 易产生 merge conflict | 🟡 中 |
| **粒度固定** | 无法按需加载知识子集 | 🟢 低 |
| **测试困难** | SKILL.md 内容难以单元测试 | 🟡 中 |

**知识不一致的恶性循环**：

```mermaid
flowchart TD
    A[API 变更] --> B[更新 src/api/routes.py]
    B --> C{更新文档?}
    C -->|是| D[更新 docs/api.md]
    C -->|否| E[文档滞后]
    D --> F{更新 SKILL.md?}
    F -->|是| G[SKILL.md 同步]
    F -->|否| H[SKILL.md 滞后]
    E --> I[AI 基于错误知识生成代码]
    H --> I
    I --> J[生成代码错误]
    J --> K[调试时间增加]
    K --> L[开发效率下降]
    
    style E fill:#FFB6C1
    style H fill:#FFB6C1
    style I fill:#FFB6C1

2.2 方案 B：引用式知识管理

2.2.1 定义与实现方式

引用式知识管理指 SKILL.md 仅包含如何获取知识的描述，实际知识存储在独立的 Markdown 文件中。SKILL.md 作为”目录”或”索引”，引导 Agent 读取外部知识库。

典型目录结构：

project/
├── src/
│   ├── api/
│   │   ├── routes.py
│   │   └── models.py
│   └── db/
│       └── schema.sql
├── docs/
│   ├── architecture.md      # 架构文档
│   ├── api-reference.md     # API 完整文档
│   └── database-schema.md   # 数据库文档
└── .opencode/skills/
    └── api-developer/
        └── SKILL.md         # 引用外部文档

SKILL.md 内容示例：

# API Developer Skill

## 知识库索引

在协助 API 开发时，你需要参考以下文档：

### 必读的架构文档
- `@docs/architecture.md` - 系统架构概览和分层设计
  - 重点阅读 "Controller-Service-Data 分层" 章节
  - 了解各层职责边界

### API 开发参考
- `@docs/api-reference.md` - 完整 API 文档
  - 包含所有端点定义、请求/响应格式
  - 错误码规范在 "Error Handling" 章节

### 数据库规范
- `@docs/database-schema.md` - 数据库 Schema
  - 表结构定义
  - 索引和约束说明
  - 迁移规范

## 快速参考

### 项目结构

src/ ├── api/routes.py # 路由定义 ├── services/ # 业务逻辑 └── models/ # ORM 模型

### 常用命令
- 启动开发服务器: `make dev`
- 运行测试: `make test`
- 数据库迁移: `alembic upgrade head`

2.2.2 实际案例分析

案例 1：OpenCode 框架自身

OpenCode 的 skills 目录展示了引用式管理的实践：

.opencode/skills/
├── research/
│   └── SKILL.md              # 引用 content-plan, content-create
├── content-plan/
│   └── SKILL.md              # 读取 templates/metadata.yaml
├── content-create/
│   └── SKILL.md              # 生成内容到 content/ 目录
└── content-commit/
    └── SKILL.md              # Git 操作指南

research/SKILL.md 节选：

# Research Skill

这是研究任务的统一入口，采用**纯 Skill 架构**。

## 内部 Skills 调用规范

所有子任务必须通过 `skill()` 调用：

| 任务 | 调用方式 |
|------|---------|
| 规划 | `skill(name="content-plan", user_message="...")` |
| 生成 | `skill(name="content-create", user_message="...")` |
| 提交 | `skill(name="content-commit", user_message="...")` |

## 工作流程

```mermaid
flowchart LR
    A[调用方] -->|"/research 主题"| B[research skill]
    B -->|skill()| C[content-plan]
    B -->|skill()| D[content-create]
    B -->|skill()| E[content-commit]

重要参考

• @templates/metadata.yaml - 模板定义
• @templates/mermaid-bad-cases.md - Mermaid 语法指南

**分析**：
- ✅ SKILL.md 保持简洁（约 150 行），详细规范在外部文件
- ✅ templates/ 目录可以独立更新，无需修改 skill
- ✅ 多个 skills 可以引用相同的模板文件
- ✅ 模板文件的变更历史独立追踪

**案例 2：AGENTS.md 实践（Claude Code）**

Claude Code 项目根目录的 AGENTS.md 是引用式的典型：

```markdown
# AI Agent Guidelines for vibe-research

## Template System

This project uses a template-based research content generation system 
defined in `templates/metadata.yaml`.

### Important References

Before generating content with **Mermaid diagrams**, especially experimental 
chart types (radar-beta, xychart-beta), **MUST READ**:

📋 **templates/mermaid-bad-cases.md** - Common syntax errors and correct 
examples for Mermaid experimental charts

### Directory Rules

**CRITICAL**: When "硅基写手" is detected:
- Output directory: `content/silicon_writer/YYYY-MM-DD_<topic>/`
- Title format: `# [硅基写手] <Topic>`
- This is MANDATORY for correct file routing.

## Build Commands

```bash
npm run dev      # Development server
npm run build    # Production build
npm run preview  # Preview build

**分析**：
- ✅ AGENTS.md 作为项目级"元 SKILL"，引用具体技术文档
- ✅ 目录结构和命令等可能变更的信息外置
- ✅ 关键约束（MANDATORY 规则）仍然在 AGENTS.md 中强调

### 2.2.3 优势分析

| 优势 | 详细说明 | 适用场景 |
|-----|---------|---------|
| **单一事实来源** | 知识只在 docs/ 中维护，避免重复 | 所有场景 |
| **独立演进** | 知识库和 SKILL.md 可以独立版本化 | 频繁变更 |
| **团队协作** | 不同角色维护不同文件，减少冲突 | 大团队 |
| **粒度控制** | 可以按需加载知识子集 | 复杂项目 |
| **专业工具** | 可以使用专门的文档工具（如 Swagger、DBML） | 生成文档 |
| **测试友好** | 知识库文件可以被测试验证 | 质量保障 |

### 2.2.4 局限性与风险

| 局限/风险 | 具体表现 | 影响程度 |
|----------|---------|---------|
| **多次读取** | 需要读取 SKILL.md + 知识库文件 | 🟡 中 |
| **引用失效** | 如果文件路径变更，引用可能失效 | 🟡 中 |
| **上下文管理** | Agent 需要决定读取哪些文件 | 🟡 中 |
| **一致性成本** | SKILL.md 中的引用必须与文件系统保持一致 | 🟢 低 |
| **学习成本** | 新开发者需要理解引用关系 | 🟢 低 |

**引用失效的预防措施**：

```mermaid
flowchart LR
    A[文件重命名] --> B{更新 SKILL.md?}
    B -->|是| C[同步更新引用路径]
    B -->|否| D[引用失效]
    D --> E[Agent 读取失败]
    
    F[CI 检查] --> G[验证 SKILL.md 引用]
    G -->|发现失效| H[阻断提交]
    G -->|全部有效| I[允许提交]
    
    style D fill:#FFB6C1
    style H fill:#FFD700

2.3 方案对比表

2.4 小结

本章深入分析了两种方案的实现方式、实际案例和优劣势：

嵌入式知识适合：

• 知识相对稳定的场景（如编码规范、工作流程）
• 小型项目或单一开发者
• 需要快速启动、离线使用的场景
• 通用知识而非项目特定知识

引用式知识适合：

• 知识频繁变更的场景（如 API 接口、数据库 Schema）
• 中大型项目或多人协作
• 需要严格一致性和版本追溯的场景
• 项目特定知识而非通用知识

在下一章中，我们将基于这些分析，构建量化的对比矩阵和决策框架。