管理指令文件

什么是指令文件

指令文件是一个 Markdown 格式的文本文件，包含 AI Agent 的操作指引和规范。创建新任务时，Sink 会自动读取并注入指令文件内容，帮助 Agent 理解你的工作流程、项目规范和期望行为。

指令文件的常见用途包括：

• 定义代码风格和命名规范
• 说明项目架构和核心概念
• 指定特定工具或库的使用方式
• 列出禁用或限制的操作
• 提供项目特定的 AI Agent 工作流程

指令文件位置

Sink 支持两个层级的指令文件：

用户层指令文件

全局指令文件，适用于所有工作区。位置：

~/.sink/SINK.md

Workspace 层指令文件

针对特定工作区的指令文件，优先级更高。位置：

<workspace>/.sink/SINK.md

若同时存在两个文件，内容会按如下顺序合并：

1. Workspace 层内容（最高优先级）
2. 用户层内容（次之）
3. Builtin 层内容（最低优先级；发行版预配置）

创建和编辑指令文件

通过文本编辑器编辑

使用你喜欢的文本编辑器直接编辑指令文件：

# 编辑用户层指令文件（全局）
nano ~/.sink/SINK.md

# 编辑 workspace 层指令文件（项目特定）
cd /path/to/workspace
nano .sink/SINK.md

保存后，新创建的任务会自动使用更新后的指令。

在 Web UI 中查看指令文件

在 Web UI 中查看合并后的指令文件：

1. 打开 Web UI
2. 在左侧菜单点击”Instructions”（指令）
3. 可以查看：
   • Effective 视图：合并后的最终指令（workspace + user）
   • Workspace 视图：仅 workspace 层内容
   • User 视图：仅 user 层内容

每一层的来源路径也会显示在 UI 中。

指令文件最佳实践

内容结构

建议将指令文件组织为清晰的章节：

# 项目指引

## 概述

项目名称、目标和核心概念说明。

## 代码规范

- 编程语言和版本要求
- 代码风格（缩进、命名约定等）
- 必须遵守的最佳实践

## 架构设计

- 项目目录结构
- 核心模块说明
- 依赖关系和数据流

## 工具和库

- 关键依赖包及其版本
- 相关工具的配置方式
- 推荐的插件或扩展

## 工作流程

- 如何创建新功能
- 如何运行测试
- 提交前的检查清单

## 限制和禁止事项

- 不允许修改的文件或目录
- 禁止使用的依赖或做法
- 安全相关的限制

长度控制

• 保持指令文件在 10,000 字符以内
• 过长的指令可能降低 Agent 的处理效率
• 优先提供最关键的信息，细节可通过代码注释补充

明确和具体

使用清晰的语言和具体的例子：

好的例子：

使用 TypeScript 进行开发。必须安装类型定义（@types/*）。
禁止使用 any 类型，除非有特殊说明。

不好的例子：

遵守最佳实践。做合理的事情。

更新频率

• 定期更新指令文件，保持与项目状态同步
• 添加新的规范或限制后立即更新
• 移除已过时的信息

故障排除

问题: 指令文件未被 Agent 加载

解决方案:

• 确认文件存在于正确位置：~/.sink/SINK.md 或 <workspace>/.sink/SINK.md
• 检查文件名是否完全正确：SINK.md（区分大小写）
• 确保文件是纯 Markdown 格式（无 YAML frontmatter）
• 新创建的任务会使用最新的指令；已存在的任务不会受影响

问题: 修改指令文件后，已创建的任务不更新

解决方案:

• 指令文件仅对新创建的任务生效
• 已创建的任务的指令是固定的，修改不会使其改变
• 如需应用新指令，请创建新任务

问题: 多个指令文件冲突或内容重复

解决方案:

• 检查是否同时定义了用户层和 workspace 层指令
• 使用 Web UI 的”Effective”选项卡查看最终合并结果
• 考虑将通用指令移至用户层，项目专用指令移至 workspace 层

后续步骤

配置完指令文件后，你可以：

1. 管理 Profile — 定义 Agent 的人格和能力
2. 快速开始 — 创建你的第一个任务并观察 Agent 的行为