# Components Agent Guide

适用于本目录及其子目录，同时遵循 [Frontend Agent Guide](../../../../AGENTS.md)。

## 视图层边界

- 本目录只承载可复用的 UI 展示与交互，当前包括目录树、文件预览、TUI、作用域选择与 Agent 接入视图。组件的归属由职责决定。
- 通过 props 接收渲染所需的数据及加载、空态、错误等状态，通过事件回调表达展开、搜索、保存、重试等用户意图。回调可以返回组件渲染所需的输入（例如编辑前取回的完整正文），但不得返回任一宿主接口的数据结构；组件不能依赖某个宿主既定的接口格式。上层执行数据操作后，业务状态仍以 props 传入。
- 不自行调用 fetch、Axios 或业务 SDK，不创建业务 WebSocket/SSE 连接，也不通过私有 Hook、工具或 Store 间接引入数据获取逻辑。请求参数、响应适配、分页请求、流式连接和取消由上层负责。
- 组件内可做格式化等展示计算，可维护折叠、焦点、输入草稿等实例内交互状态。业务数据处理、权限判断、账号作用域、持久化和请求缓存由上层负责；组件接收处理后的数据与可操作状态。
- 组件不依赖业务模块、应用路由或业务服务。上层 [modules](../modules/AGENTS.md) 或宿主通过 Hook 获取和处理数据，再组合这些组件；组件仍可由宿主直接使用。

## 新增与迁移

- 每个组件独占一个 kebab-case 目录，入口文件与目录同名；组件私有的子组件、Hook、类型和样式就近放置。
- 迁入代码时先拆出数据获取和业务编排，组件仅保留视图、交互和必要的公开接口。示例使用固定公开数据，由示例外层模拟状态更新；组件在没有后端连接时也应能独立展示和操作。
- 组件公开入口为 `components/<模块>`，样式入口为 `components/<模块>/style.css`，并纳入 `components/style.css` 和整包 `style.css`。单组件 CSS 必须可独立消费，JS 入口不隐式加载 CSS。不提供 `components` 聚合 JS 入口。
- 更新公开入口时同步维护包导出、Rslib 入口、声明路径及示例；验证要求沿用 Frontend Agent Guide。