file-save-protocol-stock

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

파일 저장 프로토콜 (주식/ETF 분석용)

股票/ETF分析用文件存储协议

Overview

概述

이 스킬은 주식/ETF 분석 에이전트가 결과를 파일로 저장할 때 따라야 하는 규칙을 정의합니다.

핵심 목표: 분석 결과의 영속성 보장 및 환각 방지

本Skill定义了股票/ETF分析Agent在将结果保存为文件时必须遵循的规则。

核心目标：确保分析结果的持久性并防止幻觉问题

1. 파일 저장 필수 규칙 (CRITICAL)

1. 文件存储强制规则（CRITICAL）

환각 방지의 핵심: 분석 결과를 반드시 파일로 저장해야 합니다. 프롬프트로만 반환하면 데이터 손실 및 환각 발생 위험이 있습니다.

防止幻觉的核心：分析结果必须保存为文件。仅通过返回提示内容会存在数据丢失和产生幻觉的风险。

왜 파일 저장이 필수인가?

为什么文件存储是强制要求？

문제	설명
컨텍스트 손실	긴 대화에서 이전 분석 결과가 잘릴 수 있음
재현 불가	파일 없이는 분석 결과를 재검증할 수 없음
환각 위험	저장 없이 "저장됨"이라고 응답하면 환각
워크플로우 중단	다음 에이전트가 입력 파일을 찾지 못함

问题	说明
上下文丢失	在长对话中，之前的分析结果可能会被截断
无法重现	没有文件就无法重新验证分析结果
幻觉风险	未保存却回复“已保存”会产生幻觉
工作流中断	后续Agent无法找到输入文件

필수 사항 (MUST)

必须遵守事项（MUST）

모든 분석 결과는
```
Write
```
도구로 파일 저장
저장 경로는 coordinator가 제공하는
```
output_path
```
사용
저장 성공 여부 확인 후 응답
저장 실패 시 명시적 FAIL 응답

所有分析结果使用
```
Write
```
工具保存为文件
存储路径使用coordinator提供的
```
output_path
```
确认存储成功后再回复
存储失败时返回明确的FAIL响应

금지 사항 (NEVER)

禁止事项（NEVER）

파일 저장 없이 분석 결과 "완료" 응답
저장 실패를 무시하고 진행
```
output_path
```
무시하고 임의 경로 사용

未保存文件就回复分析结果“已完成”
忽略存储失败继续执行
无视
```
output_path
```
使用任意路径

1.5 Markdown 저장 규칙 (MANDATORY)

1.5 Markdown存储规则（MANDATORY）

JSON 저장은 항상 필수이며, 사람이 읽기 위한 Markdown 요약도 반드시 저장합니다.

JSON存储始终是强制要求，同时还必须保存供人类阅读的Markdown摘要。

필수 규칙

强制规则

JSON과 MD 모두 저장 (둘 중 하나라도 누락 시 FAIL)
MD는 JSON 내용을 요약/정리만 수행 (새 수치/새 출처 추가 금지)
파일명은 번호 접두어 고정:
- ```
{output_path}/{NN}-{base}.md
```
  (base = JSON 파일명에서
```
.json
```
  제거)

同时保存JSON和MD文件（两者缺一即判定为FAIL）
MD仅对JSON内容进行摘要/整理（禁止添加新数据或新来源）
文件名固定使用编号前缀:
- ```
{output_path}/{NN}-{base}.md
```
  （base = JSON文件名去掉
```
.json
```
  ）

2. 저장 프로세스

2. 存储流程

Step-by-Step

分步指南

Step 1: 분석 완료 후 JSON 객체 생성

Step 2: Write 도구로 파일 저장
        Write(
          file_path="{output_path}/{filename}.json",
          content=JSON.stringify(analysis_result, null, 2)
        )

Step 3: 저장 성공 확인
        └─ 성공: 정상 응답 반환
        └─ 실패: FAIL 응답 반환 (환각 데이터 생성 금지)

Step 1: 分析完成后生成JSON对象

Step 2: 使用Write工具保存文件
        Write(
          file_path="{output_path}/{filename}.json",
          content=JSON.stringify(analysis_result, null, 2)
        )

Step 3: 确认存储成功
        └─ 成功：返回正常响应
        └─ 失败：返回FAIL响应（禁止生成幻觉数据）

저장 경로 컨벤션

存储路径约定

coordinator(stock-consultant)가 제공하는

output_path

를 사용합니다:

consultations/{session_folder}/{filename}

예시:
consultations/2026-01-14-TSLA-abc123/
├── index-data.json               # index-fetcher 출력
├── rate-analysis.json            # rate-analyst 출력
├── sector-analysis.json          # sector-analyst 출력
├── risk-analysis.json            # risk-analyst 출력
├── leadership-analysis.json      # leadership-analyst 출력
├── material-summary.md           # material-organizer 출력 (옵셔널)
├── macro-outlook.json            # macro-synthesizer 출력
├── 00-macro-outlook.md           # macro-synthesizer 출력
├── 00-materials-summary.md       # 자료 정리 (materials_path 제공 시)
├── 01-stock-screening.json       # stock-screener 출력
├── 02-valuation-report.json      # stock-valuation 출력
├── 03-bear-case.json             # bear-case-critic 출력
├── 04-final-verification.json    # stock-critic 출력
└── 05-consultation-summary.md    # 최종 상담 보고서

使用coordinator(stock-consultant)提供的

output_path

：

consultations/{session_folder}/{filename}

示例:
consultations/2026-01-14-TSLA-abc123/
├── index-data.json               # index-fetcher输出
├── rate-analysis.json            # rate-analyst输出
├── sector-analysis.json          # sector-analyst输出
├── risk-analysis.json            # risk-analyst输出
├── leadership-analysis.json      # leadership-analyst输出
├── material-summary.md           # material-organizer输出（可选）
├── macro-outlook.json            # macro-synthesizer输出
├── 00-macro-outlook.md           # macro-synthesizer输出
├── 00-materials-summary.md       # 资料整理（提供materials_path时）
├── 01-stock-screening.json       # stock-screener输出
├── 02-valuation-report.json      # stock-valuation输出
├── 03-bear-case.json             # bear-case-critic输出
├── 04-final-verification.json    # stock-critic输出
└── 05-consultation-summary.md    # 最终咨询报告

에이전트별 출력 파일

各Agent输出文件

에이전트	출력 파일	필수
stock-screener	`01-stock-screening.json`	O (포트폴리오 요청 시)
stock-valuation	`02-valuation-report.json`	O
bear-case-critic	`03-bear-case.json`	O
stock-critic	`04-final-verification.json`	O

Agent	输出文件	是否必填
stock-screener	`01-stock-screening.json`	是（请求投资组合时）
stock-valuation	`02-valuation-report.json`	是
bear-case-critic	`03-bear-case.json`	是
stock-critic	`04-final-verification.json`	是

거시경제 분석 출력 파일 (macro-analysis 재사용)

宏观经济分析输出文件（复用macro-analysis）

에이전트	출력 파일	필수
index-fetcher	`index-data.json`	O
rate-analyst	`rate-analysis.json`	O
sector-analyst	`sector-analysis.json`	O
risk-analyst	`risk-analysis.json`	O
leadership-analyst	`leadership-analysis.json`	O
material-organizer	`material-summary.md`	X (옵셔널)
macro-synthesizer	`macro-outlook.json` , `00-macro-outlook.md`	O

Agent	输出文件	是否必填
index-fetcher	`index-data.json`	是
rate-analyst	`rate-analysis.json`	是
sector-analyst	`sector-analysis.json`	是
risk-analyst	`risk-analysis.json`	是
leadership-analyst	`leadership-analysis.json`	是
material-organizer	`material-summary.md`	否（可选）
macro-synthesizer	`macro-outlook.json` , `00-macro-outlook.md`	是

3. 저장 실패 시 응답

3. 存储失败时的响应

저장이 실패하면 절대 "저장됨"으로 응답하지 않습니다:

json

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "{filename} 저장 실패",
  "attempted_path": "{output_path}/{filename}",
  "action": "재시도 필요"
}

存储失败时绝对不能回复“已保存”：

json

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "{filename} 保存失败",
  "attempted_path": "{output_path}/{filename}",
  "action": "需要重试"
}

실패 유형별 대응

按失败类型对应处理

실패 유형	코드	대응
경로 없음	`PATH_NOT_FOUND`	coordinator에 경로 확인 요청
권한 오류	`PERMISSION_DENIED`	경로 권한 확인
디스크 공간	`DISK_FULL`	공간 확보 후 재시도
알 수 없음	`UNKNOWN_ERROR`	에러 메시지 포함하여 보고

失败类型	代码	对应措施
路径不存在	`PATH_NOT_FOUND`	请求coordinator确认路径
权限错误	`PERMISSION_DENIED`	检查路径权限
磁盘空间不足	`DISK_FULL`	释放空间后重试
未知错误	`UNKNOWN_ERROR`	包含错误信息上报

4. Write 도구 사용법

4. Write工具使用方法

기본 사용법

基本用法

Write(
  file_path="consultations/{session_folder}/02-valuation-report.json",
  content="{\"status\": \"PASS\", \"ticker\": \"005930\", ...}"
)

Write(
  file_path="consultations/{session_folder}/02-valuation-report.json",
  content="{\"status\": \"PASS\", \"ticker\": \"005930\", ...}"
)

JSON 포맷팅

JSON格式化

python

undefined

python

undefined

들여쓰기 2칸으로 포맷팅

使用2空格缩进格式化

JSON.stringify(analysis_result, null, 2)

undefined

JSON.stringify(analysis_result, null, 2)

undefined

파일 확장자 규칙

文件扩展名规则

데이터 유형	확장자
구조화된 분석 데이터	`.json`
마크다운 보고서	`.md`
원시 텍스트	`.txt`

数据类型	扩展名
结构化分析数据	`.json`
Markdown报告	`.md`
原始文本	`.txt`

5. 저장 확인 체크리스트 (MANDATORY)

5. 存储确认检查表（MANDATORY）

저장 전 확인

存储前确认

```
output_path
```
가 coordinator로부터 전달되었는가?
저장할 데이터가 완전한가 (모든 필수 필드 포함)?
JSON 형식이 올바른가?

是否已从coordinator获取
```
output_path
```
？
待存储数据是否完整（包含所有必填字段）？
JSON格式是否正确？

저장 후 확인

存储后确认

Write 도구가 에러 없이 완료되었는가?
저장 경로를 응답에 포함했는가?
저장 실패 시 FAIL 응답을 반환했는가?

Write工具是否无错误完成？
响应中是否包含存储路径？
存储失败时是否返回了FAIL响应？

절대 금지

绝对禁止

파일 저장 실패 시 "저장된 것처럼" 응답하지 않았는가?
저장 없이 분석 "완료"로 응답하지 않았는가?

存储失败时是否没有伪装成“已保存”回复？
是否没有未存储就回复分析“已完成”？

6. 응답 템플릿

6. 响应模板

성공 시 응답

成功时响应

json

{
  "status": "PASS",
  "output_file": "{output_path}/{filename}.json",
  "summary": {
    // 분석 결과 요약
  }
}

json

{
  "status": "PASS",
  "output_file": "{output_path}/{filename}.json",
  "summary": {
    // 分析结果摘要
  }
}

실패 시 응답

失败时响应

json

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "02-valuation-report.json 저장 실패",
  "attempted_path": "consultations/2026-01-14-TSLA-abc123/02-valuation-report.json",
  "action": "재시도 필요"
}

json

{
  "status": "FAIL",
  "error": "FILE_SAVE_FAILED",
  "detail": "02-valuation-report.json 保存失败",
  "attempted_path": "consultations/2026-01-14-TSLA-abc123/02-valuation-report.json",
  "action": "需要重试"
}

메타 정보

元信息

yaml

version: "1.0"
created: "2026-01-20"
purpose: "파일 저장 프로토콜 통합 - 코드 중복 제거"
based_on: "investments-portfolio/skills/file-save-protocol"
consumers:
  - stock-screener
  - stock-valuation
  - bear-case-critic
  - stock-critic
extracted_from:
  - "파일 저장 필수 섹션 (investments-portfolio)"
  - "저장 프로세스 섹션"
  - "저장 실패 시 응답 형식"
dependencies:
  - Write
output_path_pattern: "consultations/{YYYY-MM-DD}-{ticker}-{session_id}/"

yaml

version: "1.0"
created: "2026-01-20"
purpose: "整合文件存储协议 - 消除代码重复"
based_on: "investments-portfolio/skills/file-save-protocol"
consumers:
  - stock-screener
  - stock-valuation
  - bear-case-critic
  - stock-critic
extracted_from:
  - "文件存储强制章节 (investments-portfolio)"
  - "存储流程章节"
  - "存储失败时响应格式"
dependencies:
  - Write
output_path_pattern: "consultations/{YYYY-MM-DD}-{ticker}-{session_id}/"