AI로 작업하기
오른쪽 Project Activity → AI에서 현재 Project와 Flow에 대한 도움을 요청합니다. AI는 별도 계산 모델을 만들지 않고 화면에 보이는 Project, Flow, Node, input, result, type, unit과 revision을 그대로 사용합니다.
Component Node와 AI의 현재 범위
현재 production Flow reader는 Component의 exact target, raw settings와 usage-derived 일부 port를 보존한 read-only unsupported Node를 표시합니다. 후속 V2 Canvas는 package UI를 마운트하지 않고 host-owned component.declarative@2만 사용하며 settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. rich surface는 RFC-016의 component-rich-surface-declaration@1이 소유하고, editor AI의 operation shape는 열지 않습니다. current V1에서 third-party Component activation은 구현된 exact ProjectScope data-path isolation에 Project authorization과 execution-trust closure가 더해질 때까지 차단하며 Validate/Run을 거부합니다. 향후 host presentation은 Node presentation과 third-party UI의 contract_only V2가 소유합니다.
공통 동선
| 경험 | 진입 위치 | 원본이 바뀌는 시점 |
|---|---|---|
| Project AI | 오른쪽 Project Activity → AI | 승인한 Apply 또는 Run |
| Flow 범위 AI | PXFLOW의 선택 Node·연결 → AI | 승인한 Apply |
| Component rich-surface AI | RFC-014 successor 전까지 미제공 | entry·message·operation 미정의 |
| 외부 AI client | 연결한 client의 Tool 화면 | exact 대상과 plan 승인 |
요청 예시
- “
girder_review의 공개 result와 단위를 설명해 줘.” - “
resistance_check.results.check_result를design_report.inputs.check_result에 연결할 계획을 보여 줘.” - “이 Flow에서 호환되는 input만 사용해 누락된 연결을 제안해 줘.”
- “Function version을 바꾸면 영향을 받는 Node와 Flow를 먼저 보여 줘.”
- “저장된 revision을 실행하고
utilizationResult를 요약해 줘.”
AI는 비슷한 이름을 자동 교정하거나 첫 번째 result port를 선택하지 않습니다.
AI가 대상을 찾는 방법
AI가 "어느 Project의 어느 Flow의 어느 Node의 어느 port"인지 정확히 지목하는 방식입니다. 같은 이름이 여러 개 있어도 이 경로로 하나를 확정합니다. 사용자는 breadcrumb와 Node inspector에서 같은 주소를 확인합니다. 이 주소의 SDK/API 기술 이름은 SemanticTarget입니다.
| 범위 | 화면에서 쓰는 곳 |
|---|---|
| Flow target | 설명·Validate·Run |
| Node target | Node 계약·setting·사용처 영향 |
| Port target | input/result 연결과 result read |
Label, canvas 좌표, Python local variable, file path와 내부 UUID로 target을 추측하지 않습니다. 같은 label이 여러 개면 exact Project·Flow path를 보여 주고 선택을 요청합니다.
변경 승인
다음 동작은 plan과 사용자 승인을 요구합니다.
- Node 또는 연결 추가·삭제
- Node target 또는 setting 변경
- input/result의
connection변경 - semantic key rename
- SDK-linked source 변경
- 계획된 Component editor의 document draft 변경
- 비용 또는 side effect가 있는 Run
- 외부 file, network와 secret 사용
Apply와 Run 시점에 revision, type, unit, package availability, 권한과 capability를 다시 검사합니다. 동시에 다른 변경이 저장됐으면 자동 덮어쓰지 않고 새 plan을 만듭니다.
SDK-linked Flow 수정
- semantic target으로 변경 계획을 만듭니다.
- Python source에 안전하게 표현할 수 있는지 확인합니다.
- source diff와 사용처 영향을 보여 줍니다.
- 사용자가 Apply하면 source를 수정합니다.
- 다시 materialize해 같은 Flow 계약인지 확인합니다.
안전한 source edit로 표현할 수 없으면 code를 직접 편집하거나 명시적인 PXFLOW-native copy를 만드는 선택지를 제공합니다. Canvas projection만 바꾸지 않습니다.
Project Function 만들기와 수정하기
AI에게 Function 생성을 요청하면 먼저 explicit functionKey, version, input/result와 계산 의미가 들어간 완전한 @px.function 후보를 보여 줍니다. 기존 Function을 수정할 때는 다음 순서로 진행합니다.
- Definitions → Functions의 exact Function과 현재 version을 찾습니다.
- 새 immutable version 후보와 source-safe diff를 만듭니다.
- 그 Function을 사용하는 모든 Node·Flow와 연결된 Report 영향을 보여 줍니다.
- 사용자가 승인하면 새 Function version과 승인한 reference를 한 번에 갱신합니다.
현재 Node만 다른 계산을 써야 하면 Branch Function for this Node를 선택합니다. AI는 새 functionKey의 Project Function을 만들고 선택한 Node의 target만 바꾸며 다른 사용처는 기존 Function을 유지합니다. 설치한 dependency의 Function·Component source는 이 Project에서 수정하지 않고 owning package 위치를 안내합니다.
Component rich-surface AI 경계
Component editor AI는 RFC-014 successor가 별도 admission을 승인한 뒤에 엽니다. 그 승인이 editor scope, context, operation, entry와 message shape를 함께 정의하며, package manual과 MCP registry는 승인된 Tool만 노출합니다.
Extension template이 SDK-linked이면 owning template definition의 source-safe diff를 제안하고 다시 materialize합니다. 현재 Node의 label, binding과 기존 V1 instance setting은 Flow revision에 저장합니다. V2 settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. preview는 두 authoring owner를 구분해 보여 줍니다.
외부 AI와 MCP
MCP(Model Context Protocol)는 외부 AI 프로그램이 다른 서비스에 연결해 그 기능을 사용하도록 정한 공개 연결 규격입니다. PipelineXLab이 이 규격으로 창구를 열어 두므로, MCP를 지원하는 AI client에서 이 Project의 Flow를 찾고 설명을 듣고 실행할 수 있습니다. 화면 안의 AI만 사용할 때는 이 절을 건너뜁니다.
연결한 client가 사용할 수 있는 작업은 다음으로 고정돼 있습니다.
- Project, Flow, Function과 Component search/describe
- Report search/describe와 typed plan/approved apply
- Project Function validate/plan/approved multi-target apply
- Flow validate, plan, approved apply
- Flow Run, 상태 조회와 cancel
- named Result와 permission-checked resource read
Function마다 실행 Tool을 늘리지 않습니다. pxflow_run은 현재 지원되는 Function과 product-built first-party Node가 있는 Flow에만 사용합니다. third-party Component가 포함된 Flow는 exact ProjectScope data-path isolation만으로는 열지 않으며 Project authorization과 execution-trust closure가 닫히기 전까지 Validate/Run을 거부합니다.
자세한 wire 계약은 AI와 MCP 연결, Function 변경의 exact Tool과 command는 AI·LLM 작성 계약을 참고하세요.
connection과 권한
connection=True는 다른 Flow와 AI가 찾을 수 있는 port입니다. V2 host discovery도 admitted declaration의 이 범위를 사용합니다.connection=False는 일반 discovery에서 숨깁니다.- 읽기·쓰기·실행·공유 권한은
connection과 별도로 관리합니다. - 실제 resource와 Result를 읽을 때 현재 Project 권한을 다시 검사합니다.
- package 설치는 외부 API, file과 secret 접근 권한을 자동 부여하지 않습니다.
AI context 범위
기본 context는 필요한 구조화 정보만 포함합니다.
- Flow, Function과 Component 설명·version
- Node·port key와 인접 binding
- type, unit, constraints, required/default/nullability
connection과 validation 상태
Python workspace 전체, secret, 전체 result history와 editor 내부 JSON을 기본으로 보내지 않습니다. 큰 Table, model, image, Report와 PDF는 schema·size·preview를 먼저 보여 주고 필요한 범위만 권한을 검사해 읽습니다.
오류와 복구
| 상황 | AI가 해야 할 일 |
|---|---|
| target이 여러 개 | exact 후보와 path를 보여 주고 선택 요청 |
| Component dependency 미설치 | 현재 exact target을 유지하고, 계획된 catalog에서는 package/version과 Add 동작 제시 |
| port 없음 | 가능한 exact input/result 목록 표시 |
| type·unit 불일치 | expected/current를 구조적으로 설명 |
| revision 충돌 | reload 뒤 새 plan 생성 |
| 권한 없음 | 필요한 접근 경로 설명; 우회하지 않음 |
| 큰 Result | summary와 resource link 반환 |
AI가 작업을 설명한 뒤 사용자가 Apply 또는 Run을 선택합니다. 두 동작은 PXFLOW UI와 같은 server-side validation과 authorization을 통과합니다.