toki
a43a9f66fa
agent-ops 공통 규칙/스킬/스크립트, 진입 파일(CLAUDE.md, GEMINI.md 등), AI 도구별 ignore 정책을 추가해 워크스페이스 공통 운영 체계를 적용한다.
124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# agent-shell
|
|
|
|
`agent-shell`은 Flutter 앱들이 공통으로 가져다 쓰는 embeddable agent interaction package다.
|
|
제품 앱이 아니며, IOP, NomadCode, OTO 같은 host가 각자의 capability pack을 붙일 수 있는 채팅형 agent shell과 domain model만 제공한다.
|
|
|
|
## 현재 상태
|
|
|
|
- Flutter package `agent_shell` scaffold가 준비되어 있다.
|
|
- `AgentShell`, message list, composer, tool call card, approval prompt 위젯을 제공한다.
|
|
- `AgentMessage`, `AgentToolCall`, `AgentCapability`, `AgentCommand`, `AgentEvent` 같은 제품 비종속 interface/model을 제공한다.
|
|
- backend transport, auth, endpoint, persistence, navigation, product-specific capability는 host 앱 책임이다.
|
|
|
|
## 빠른 시작
|
|
|
|
```bash
|
|
flutter pub get
|
|
flutter test
|
|
flutter analyze --no-fatal-infos
|
|
```
|
|
|
|
Host app에서 local path dependency로 사용할 때:
|
|
|
|
```yaml
|
|
dependencies:
|
|
agent_shell:
|
|
path: ../agent-shell
|
|
```
|
|
|
|
기본 사용 예:
|
|
|
|
```dart
|
|
AgentShell(
|
|
messages: messages,
|
|
busy: isRunning,
|
|
onSubmit: (text) => agentRuntime.send(text),
|
|
onToolAction: (action) => agentRuntime.handleToolAction(action),
|
|
)
|
|
```
|
|
|
|
## 주요 명령
|
|
|
|
| 목적 | 명령 | 비고 |
|
|
|------|------|------|
|
|
| 의존성 설치 | `flutter pub get` | `pubspec.yaml` 기준 |
|
|
| 테스트 | `flutter test` | widget test 포함 |
|
|
| 분석 | `flutter analyze --no-fatal-infos` | `analysis_options.yaml` 기준 |
|
|
| 포맷 확인 | `dart format --set-exit-if-changed lib test` | package 소스와 테스트 |
|
|
|
|
## 구조
|
|
|
|
| 경로 | 역할 |
|
|
|------|------|
|
|
| `lib/agent_shell.dart` | public export entrypoint |
|
|
| `lib/src/domain/` | 제품 비종속 message, tool call, command, event, capability model |
|
|
| `lib/src/widgets/` | embeddable agent UI primitives |
|
|
| `test/` | Flutter widget/model tests |
|
|
| `agent-ops/rules/project/rules.md` | 프로젝트 작업 규칙과 domain mapping |
|
|
| `agent-ops/rules/project/domain/` | domain별 작업 규칙 |
|
|
|
|
## 조립 경계
|
|
|
|
```text
|
|
agent_shell
|
|
AgentShell widget
|
|
AgentMessage / AgentToolCall models
|
|
AgentCapability / AgentCommand / AgentEvent interfaces
|
|
tool call and approval UI primitives
|
|
|
|
iop_console_flutter
|
|
IOP-specific capability pack
|
|
IOP Control Plane / Edge / Node integration
|
|
|
|
nomadcode_app
|
|
NomadCode workbench shell
|
|
NomadCode WebView/workflow capability pack
|
|
optional IOP composition package
|
|
```
|
|
|
|
IOP standalone:
|
|
|
|
```text
|
|
iop/apps/client
|
|
-> iop_console_flutter
|
|
-> agent_shell
|
|
```
|
|
|
|
NomadCode without IOP:
|
|
|
|
```text
|
|
nomadcode/apps/client
|
|
-> nomadcode workbench shell
|
|
-> agent_shell
|
|
```
|
|
|
|
NomadCode with IOP:
|
|
|
|
```text
|
|
nomadcode optional composition layer
|
|
-> nomadcode workbench shell
|
|
-> iop_console_flutter
|
|
-> agent_shell
|
|
```
|
|
|
|
IOP import는 optional composition layer에만 있어야 한다.
|
|
NomadCode 기본 빌드는 IOP package 없이도 성공해야 한다.
|
|
|
|
## 작업 맥락
|
|
|
|
- `lib/` 안에는 `runApp`, `MaterialApp`, Firebase/SystemChrome bootstrap을 넣지 않는다.
|
|
- 제품별 package를 import하지 않는다. IOP/NomadCode 연결은 각 제품의 capability pack 또는 optional composition layer에서 구현한다.
|
|
- Public API를 추가하면 `lib/agent_shell.dart` export와 이 README 예시를 함께 확인한다.
|
|
- UI는 좌측 rail, 우측 rail, center content, modal 등 다양한 host layout에 embedded될 수 있어야 한다.
|
|
- 자세한 작업 규칙은 `agent-ops/rules/project/rules.md`와 관련 domain rule을 먼저 확인한다.
|
|
|
|
## 환경 변수
|
|
|
|
이 package 자체가 요구하는 환경 변수는 없다.
|
|
endpoint, token, auth, persistence 설정은 host app이 주입한다.
|
|
|
|
## 참고 문서
|
|
|
|
- `agent-ops/rules/project/rules.md`
|
|
- `agent-ops/rules/project/domain/domain-model/rules.md`
|
|
- `agent-ops/rules/project/domain/widgets/rules.md`
|