# opencode-rules

**Repository Path**: hivedark/opencode-rules

## Basic Information

- **Project Name**: opencode-rules
- **Description**: opencode创建自定义agent和知识库时，懒加载文档文件防止上下文很大，只在使用的时候通过read工具读取
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Opencode Rules 项目

本项目是公交调度系统的 opencode 规则仓库，定义了 Agent 的业务知识、行为准则和懒加载文档规范。

---

## 项目结构

```
opencode-rules/
├── .opencode/
│   ├── agents/               # Agent 定义
│   │   └── test.md           # 测试 Agent
│   ├── business_rules/       # 业务知识库
│   │   ├── 公交知识.md       # 主索引文件
│   │   └── 公交知识/         # 子文档目录
│   │       ├── 概述.md
│   │       ├── 线路.md
│   │       ├── 智能排班.md
│   │       └── ...
│   └── rules/                # 规则定义
│       ├── 基本准则.md       # Agent 基础行为准则
│       ├── 懒加载文档规则.md  # 文档懒加载规范
│       └── 用户禁止规则.md   # 用户权限边界规则
└── README.md
```

---

## 目录说明

### agents/ - Agent 定义

存放所有 Agent 的配置文件，定义 Agent 的描述、工具权限和引用规则。

| 文件 | 说明 |
|------|------|
| test.md | 测试用 Agent，用于验证业务规则上下文 |

### business_rules/ - 业务知识库

公交调度系统的业务知识主索引，包含公交运营管理的核心业务领域知识。

| 目录/文件 | 说明 |
|-----------|------|
| 公交知识.md | 主索引文件，汇总各子主题文档 |
| 公交知识/ | 子文档目录，包含详细的业务知识 |

**业务领域覆盖**：概述、线路、站点、车辆、司机、行车计划、智能排班、运营调度、统计分析、地图监控、附录

### rules/ - 规则定义

opencode Agent 必须遵守的规则文件。

| 文件 | 说明 |
|------|------|
| 基本准则.md | 欢迎用语、对话准则、Agent 通用职责 |
| 懒加载文档规则.md | 文档的懒加载组织方式和引用规范 |
| 用户禁止规则.md | 用户权限边界和安全约束 |

---

## 懒加载文档规范

### 核心原则

**【强制】当遇到文件引用（例如 @rules/general.md）时，仅在实际需要时使用读取工具加载，只加载与当前具体任务相关的文件。**

### 文件引用格式

| 格式 | 说明 | 示例 |
|------|------|------|
| `@子目录/文件名.md` | 引用同级别子目录的文件 | `@公交知识/行车计划.md` |
| `@../目录/文件名.md` | 引用上级目录的文件 | `@../rules/general.md` |
| `@.opencode/路径` | 从 .opencode 根目录开始的绝对路径 | `@.opencode/business_rules/公交知识.md` |

### 加载时机判断

```
接收文件引用请求
    ↓
是否在 Agent 启动配置中直接指定？
    ├── 是 → 立即加载
    └── 否 → 进入懒加载判断
            ↓
        是否为当前任务直接相关的索引文件？
            ├── 是 → 立即加载
            └── 否 → 懒加载（按需加载）
```

### 使用示例

**场景：用户询问"什么是智能排班？"**

```
处理流程：
1. 加载主索引文件 @.opencode/business_rules/公交知识.md（立即加载）
2. 发现引用 @公交知识/智能排班.md
3. 用户询问的主题与该子文档相关 → 加载该文件（按需懒加载）
4. 如果用户继续问"智能排班的算法原理"
   → 才加载 @公交知识/智能排班（续）.md（继续懒加载）
```

---

## 规则体系

### 基本准则

定义 Agent 的基础行为规范：
- 欢迎用语统一格式
- 对话结束主动询问
- 通用职责说明

### 懒加载文档规则

定义文档的组织和引用方式：
- 目录结构规范
- 主索引文件职责
- 懒加载使用规则
- 最佳实践建议

### 用户禁止规则

定义用户在业务系统中的权限边界：
- 禁止假设角色
- 禁止假设线路权限
- 禁止绕过权限校验
- 禁止数据越权访问
- 禁止使用非本人身份创建会话
- 禁止指定访问目录或文件

---

## 版本记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-07-24 | 初始版本 |