144 lines
3.6 KiB
Markdown
144 lines
3.6 KiB
Markdown
# 代理指引（playbook）
|
||
|
||
> 关于 playbook 仓库的特殊性：
|
||
>
|
||
> - 在 playbook 仓库中：规则集模板位于 `rulesets/`
|
||
> - 在目标项目中：同步后规则集位于 `.agents/`
|
||
> - AI 代理读取目标项目根目录的 `.agents/`（由 playbook.py 的 `[sync_standards]` 生成）
|
||
>
|
||
> 本文适用于目标项目。playbook 仓库自身没有源代码，不需要 AI 代理规则。
|
||
|
||
以 `.agents/` 下规则为准：
|
||
|
||
- 入口：`.agents/index.md`
|
||
- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、
|
||
`.agents/python/index.md`、`.agents/markdown/index.md`
|
||
|
||
---
|
||
|
||
## 三层架构（分层知识库）
|
||
|
||
本仓库将代理规则与知识分为三层：
|
||
|
||
### Layer 1: `.agents/`（最小硬规则，每种语言 ≤ 50 行）
|
||
|
||
- 加载：自动，始终在上下文中
|
||
- 内容：硬约束与安全红线
|
||
- 作用：快速判断能做/不能做
|
||
- 规模控制：TSL 44 行 | Python 45 行 | C++ 47 行 | Markdown 31 行
|
||
|
||
### Layer 2: `codex/skills/`（按需加载，每个 skill 100-1000 行）
|
||
|
||
- 加载：由 `$<skill-name>` 触发或由代理判定
|
||
- 内容：操作指南、最佳实践、工作流
|
||
- 作用：指导具体怎么做
|
||
|
||
关键技能：
|
||
|
||
- `$tsl-guide` - TSL 渐进式语法训练（基础/高级/函数/最佳实践）
|
||
- `$commit-message` - 提交信息规范
|
||
- `$style-cleanup` - 格式与风格整理
|
||
- `$bulk-refactor-workflow` - 安全批量重构流程
|
||
|
||
### Layer 3: `docs/`（权威静态文档）
|
||
|
||
- 加载：按需读取特定章节
|
||
- 内容：完整语言手册、代码风格、工具链配置
|
||
- 作用：最终权威
|
||
- 冲突处理：规则冲突时以 `docs/` 为准
|
||
|
||
注：函数库拆分在 `docs/tsl/syntax_book/function/` 下。
|
||
不要加载整个目录，只加载需要的片段。
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
### 场景 1：编写简单的 TSL 函数
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 SKILL.md（192 行）
|
||
3. 生成代码
|
||
|
||
Token 消耗：~6,000 tokens
|
||
```
|
||
|
||
### 场景 2：编写 TSL 类
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 SKILL.md + references/advanced.md
|
||
3. 生成代码
|
||
|
||
Token 消耗：~10,000 tokens
|
||
```
|
||
|
||
### 场景 3：查询 TSL 函数库条目
|
||
|
||
```text
|
||
1. 自动读取 .agents/tsl/index.md（44 行）
|
||
2. 触发 $tsl-guide，加载 references/functions_index.md
|
||
3. 使用 rg 定位函数片段
|
||
4. 返回答案
|
||
|
||
Token 消耗：~8,000 tokens
|
||
```
|
||
|
||
---
|
||
|
||
## 性能指标
|
||
|
||
| 指标 | 之前 | 现在 | 改善 |
|
||
| --------------- | ------- | ------- | ---- |
|
||
| .agents 规模 | ~500 行 | 168 行 | -66% |
|
||
| 持久化 tokens | ~12,500 | ~4,200 | -66% |
|
||
| 场景平均 tokens | ~12,500 | ~10,500 | -16% |
|
||
|
||
---
|
||
|
||
## 维护原则
|
||
|
||
### .agents/ 修改规则
|
||
|
||
可做：
|
||
|
||
- 增加新的安全漏洞类型
|
||
- 更新核心约定（文件名、格式规则）
|
||
- 添加不可妥协的硬性约束
|
||
|
||
不可做：
|
||
|
||
- 添加推荐型最佳实践（放到 skill）
|
||
- 添加详细语法解释（放到 skill 或 docs）
|
||
- 超过 50 行限制（拆分为 skill）
|
||
|
||
### Skills 创建规则
|
||
|
||
可做：
|
||
|
||
- 增加新流程（如 code-review）
|
||
- 从零教授新语言（如 tsl-guide）
|
||
- 添加跨语言通用知识（如 style-cleanup）
|
||
|
||
---
|
||
|
||
## FAQ
|
||
|
||
Q：为什么 .agents 这么小？
|
||
A：因为它会在每次对话加载。控制在 50 行内可减少约 71% 的持久 token 消耗。
|
||
|
||
Q：为什么 TSL 需要专门的 tsl-guide？
|
||
A：TSL 非预训练语言，需要从零教学。
|
||
|
||
Q：如果项目有自定义约定怎么办？
|
||
A：将 playbook 以 git subtree 方式引入项目，并修改项目的 `.agents/`。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- Skills 使用指南：`SKILLS.md`
|
||
- 开发规范：`docs/index.md`
|
||
- 项目 README：`README.md`
|