TongyiDai/agent-value-ledger

시간은 돈이다｜AI's time is money

로컬 Excel 워크북 하나로 Agent가 완료한 작업의 가치 장부를 유지합니다. Agent가 발견, 중복 제거, 추정 및 업데이트를 담당하고, 사용자는 비정상 항목만 검토합니다. 수동으로 한 줄씩 입력할 필요가 없습니다.

설계 경계

• 로컬 Excel에만 의존합니다. Feishu, Base, 데이터베이스 또는 외부 동기화 서비스에 의존하지 않습니다.
• 장부는 '감사 가능한 시간 대체 가치'를 기록하며, 추정 금액을 현금 수익, 이익 또는 확정된 수익으로 표현하지 않습니다.
• 기본적으로 외부에는 보수적인 저값 saved_minutes_low와 saved_cny_low를 표시하고, 중간값과 고값은 Excel의 참조 구간에만 보관합니다.
• 명확한 완료 상태나 결과물이 있는 작업만 기록합니다. 요구 사항 논의, 선호도 기록, 실패한 시도, 반복 유지 보수, 제안만 있고 산출물이 없는 대화는 기본적으로 건너뜁니다.
• 전체 채팅, 민감 원문, 자격 증명, 비공개 재무 세부 정보 또는 불필요한 개인 데이터를 저장하지 않습니다. 증거는 짧은 제목, 날짜, 출처 ID, 로컬 경로 또는 결과물 유형만 저장합니다.

워크북 구조

Skill과 함께 제공되는 assets/agent-value-ledger-template.xlsx를 우선 사용합니다. 사용자가 이미 워크북을 가지고 있는 경우, 먼저 읽고 그 구조를 유지합니다. 필요한 워크시트가 없는 경우에만 새로 만듭니다.

• 요약: 저값 주요 결론, 주/월별 요약, 참조 구간, 낮은 신뢰도 및 검토 대기 수량. 전부 수식으로 구동됩니다.
• 작업 상세: 한 줄에 하나의 완료된 작업입니다. 시간, 가치, 신뢰도, 증거 및 가정이 별도 열에 저장됩니다.
• 규칙: 시급, 기본 비용, 분류, 신뢰도 및 추정 경계입니다. 규칙 변경 시 업데이트 시간을 보존해야 합니다.
• 실행 상태: 최근 스캔 시간, 스캔 기간, 처리된 출처 수, 최근 오류 및 검토 대기 설명입니다. 재스캔을 지원하며 별도의 state 파일에 의존하지 않습니다.
• 실행 로그: 짧은 이벤트, 결과 및 오류 요약만 기록하며 전체 원문은 기록하지 않습니다.

필수 필드와 수식은 references/workbook-schema.md를 참조하세요. 추정 기준은 references/estimation-policy.md를, 비식별화 및 증거 경계는 references/redaction-and-evidence.md를 참조하세요.

표준 절차

1. 워크북 및 규칙 읽기

1. 사용자가 지정한 .xlsx 파일을 찾습니다. 지정되지 않은 경우 현재 작업 디렉토리 또는 설정 디렉토리에서 agent-value-ledger.xlsx를 찾습니다.
2. 먼저 규칙, 실행 상태, 작업 상세 및 요약을 읽어 수식, 필드 및 최근 실행 상태를 확인합니다.
3. 워크북이 없으면 템플릿을 사용자가 명시한 로컬 경로에 복사합니다. 개인 디렉토리에 조용히 쓰지 않습니다.
4. 현재 날짜, 시간대, 시급 및 보고 정책을 읽습니다. Skill 내의 예시 시급을 사용자의 실제 시급으로 사용해서는 안 됩니다.

2. 스캔 및 재스캔

1. 사용 가능한 로컬 세션 요약, 작업 기록, 프로젝트 로그, 결과물 디렉토리 및 버전 기록을 스캔합니다.
2. 기본적으로 최근 7일을 재스캔하여 '요약이 세션 완료 시간보다 늦게 저장되는' 경우를 포괄합니다. 매번 작업ID, 출처 ID 및 결과물 지문을 기준으로 중복을 제거합니다.
3. 먼저 후보 목록을 만든 다음 완료 상태를 판단합니다. 스캔하면서 직접 Excel에 쓰지 않습니다.
4. 각 후보에 대해 accepted, skipped 또는 needs_review를 표시하고 사유를 한 줄씩 남깁니다.

3. 작업 기록 형성

각 작업에 대해 최소한 다음을 기록합니다: 작업 ID, 작업 날짜, 작업 제목, 짧은 요약, 분류, 출처, 결과물, 신뢰도, 세 가지 추정 수동 시간, 세 가지 추정 사용자 투입 시간, 세 가지 추정 검토 재작업 시간, 시급, 분담 비용, 가정, 증거 상태 및 중복 제거 키.

계산 규칙:

saved_minutes = max(0, manual_minutes - user_active_minutes - review_minutes)
saved_cny = saved_minutes / 60 * hourly_rate_cny - allocated_cost_cny

Excel에는 수식을 유지하고 계산 결과를 하드코딩하지 않습니다. 구독/API 비용을 분담할 수 없는 경우 비용을 0으로 채우고 가정에 "구독/API 비용 미분담"이라고 명시합니다.

4. 쓰기 전 검사

• 작업 ID, 중복 제거 키 또는 결과물 지문이 이미 존재하는 경우: 증거를 업데이트하거나 건너뛰고 중복된 가치를 추가하지 않습니다.
• 완료 증거가 누락된 경우: needs_review 상태로 진입하며 주요 요약에 포함되지 않습니다.
• saved_minutes가 0보다 작은 경우: 0으로 처리하고 이상을 기록합니다.
• 저값이 중간값보다 높거나 중간값이 고값보다 높은 경우: 쓰기를 중단하고 추정을 수정합니다.
• 수동으로 입력된 "코드 줄 수, 파일 수, 실행 시간"은 증거로만 사용할 수 있으며 절약된 시간과 직접 동일시할 수 없습니다.

5. 업데이트 및 검증

1. 먼저 작업 상세에 쓰고 요약 수식이 다시 계산되도록 합니다.
2. 실행 상태와 실행 로그를 기록합니다. 스캔 기간, 후보 수, 추가 수, 건너뛴 수, 검토 대기 수 및 오류 요약을 포함합니다.
3. 추가된 행, 요약 주요 셀 및 수식 오류 스캔 결과를 다시 읽습니다.
4. 파일 읽기 불가, 수식 오류, 출처 접근 불가 또는 쓰기 실패가 발생하면 추측을 중단하고 실행 로그에 실패 및 검증되지 않은 범위를 표시합니다.
5. 사용자에게는 저값 주요 결론, 실제 추가된 작업 수, 검토 대기 항목 및 차단만 보고합니다. 원시 JSON이나 긴 로그를 출력하지 않습니다.

작업 분류

규칙 워크시트의 분류표를 사용합니다. 기본 분류는 다음과 같습니다:

• simple_lookup_or_command: 간단한 조회, 설명, 단일 명령
• feishu_lookup_or_schedule: 메시지, 일정, 작업 및 워크스테이션 조회
• doc_wiki_minutes_synthesis: 문서, Wiki, 회의록, 번역 및 구조 정리
• report_or_research: 조사, 분석, 계획 및 판단 프레임워크
• automation_or_workflow_setup: 자동화, 데이터 파이프라인, 배치 처리, 배포 및 워크플로우 구축
• coding_or_debugging: 코드 수정, 디버깅, 테스트, 릴리스 및 수리
• local_setup_or_cleanup: 로컬 설치, 정리, 마이그레이션 및 유지 보수

보안 및 배포 경계

• 비식별화 후에만 공개 저장소에 게시할 수 있습니다: 이름, 이메일, 전화번호, 경로의 사용자 이름, 토큰, Base URL, 내부 도메인, 회사 고객명 및 비공개 문서 제목을 제거합니다.
• 예시 워크북은 가상 작업과 예시 숫자만 사용해야 합니다. 사용자의 실제 장부에서 기록을 복사해서는 안 됩니다.
• GitHub 게시 전에 민감 정보 스캔, Excel 수식 오류 스캔, Skill 구조 검증 및 공개 내용 검토를 수행합니다.
• GitHub 게시는 이 Skill의 자동 부작용이 아닙니다. 사용자가 명시적으로 게시를 요청하고 검토를 완료한 경우에만 실행됩니다.

리소스

• references/workbook-schema.md: 워크북 필드, 수식 및 상태 값
• references/estimation-policy.md: 세 가지 추정, 가치 보정 및 안티 치트 경계
• references/redaction-and-evidence.md: 비식별화, 증거 최소화 및 공개 게시 검사
• scripts/build_template.mjs: 비식별화된 Excel 템플릿 생성 또는 재구축