cc-viewer 1.6.182 → 1.6.183

package/concepts/ko/Tool-Skill.md

@@ -1,56 +1,47 @@
 # Skill
 
-## 정의
+현재 대화 내에서 명명된 스킬을 호출합니다. 스킬은 사전 패키지된 기능 번들 — 도메인 지식, 워크플로, 때로는 도구 접근 — 이며 하니스가 시스템 알림을 통해 어시스턴트에게 노출합니다.
 
-메인 대화 내에서 스킬(skill)을 실행합니다. 스킬은 사용자가 slash command (예: `/commit`, `/review-pr`)로 호출할 수 있는 전용 기능입니다.
+## 사용 시점
 
-## 파라미터
+- 사용자가 `/review`나 `/init`과 같은 슬래시 명령을 입력합니다 — 슬래시 명령은 스킬이며 이 도구를 통해 실행되어야 합니다.
+- 사용자가 광고된 스킬의 트리거 조건과 일치하는 작업을 설명합니다 (예: 반복적인 권한 프롬프트에 대한 기록을 스캔하도록 요청하는 것은 `fewer-permission-prompts`와 일치).
+- 스킬의 명시된 목적이 현재 파일, 요청, 또는 대화 컨텍스트와 직접 일치합니다.
+- 전문화되고 반복 가능한 워크플로가 스킬로 제공되며, 임시 접근 방식보다 표준 절차가 선호됩니다.
+- 사용자가 "어떤 스킬을 사용할 수 있나요"라고 묻습니다 — 광고된 이름을 나열하고 확인할 때만 호출하십시오.
 
-| 파라미터 | 타입 | 필수 | 설명 |
-|----------|------|------|------|
-| `skill` | string | 예 | 스킬 이름 (예: "commit", "review-pr", "pdf") |
-| `args` | string | 아니오 | 스킬 인수 |
+## 매개변수
 
-## 사용 시나리오
+- `skill` (string, 필수): 현재 available-skills 시스템 알림에 나열된 스킬의 정확한 이름. 플러그인 네임스페이스 스킬의 경우 정규화된 `plugin:skill` 형식을 사용하십시오 (예: `skill-creator:skill-creator`). 앞에 슬래시를 포함하지 마십시오.
+- `args` (string, 선택): 스킬에 전달되는 자유 형식 인수. 형식과 의미는 각 스킬의 자체 문서에 의해 정의됩니다.
 
-**적합한 경우:**
-- 사용자가 `/<skill-name>` 형식의 slash command를 입력한 경우
-- 사용자의 요청이 등록된 스킬의 기능과 매칭되는 경우
+## 예시
 
-**적합하지 않은 경우:**
-- 내장 CLI 명령 (예: `/help`, `/clear`)
-- 이미 실행 중인 스킬
-- 사용 가능한 스킬 목록에 없는 스킬 이름
+### 예시 1: 현재 브랜치에서 리뷰 스킬 실행
 
-## 주의사항
+```
+Skill(skill="review")
+```
 
-- 스킬이 호출되면 완전한 프롬프트로 확장됨
-- 완전 한정 이름 지원 (예: `ms-office-suite:pdf`)
-- 사용 가능한 스킬 목록은 system-reminder 메시지에서 제공
-- `<command-name>` 태그가 보이면 스킬이 이미 로드된 것이므로, 이 도구를 다시 호출하지 말고 직접 실행해야 함
-- 실제로 도구를 호출하지 않고 스킬을 언급하지 말 것
+`review` 스킬은 현재 기본 브랜치에 대해 풀 리퀘스트를 리뷰하는 단계를 패키지화합니다. 호출하면 하니스 정의 리뷰 절차가 턴에 로드됩니다.
 
-## 원문
+### 예시 2: 인수가 있는 플러그인 네임스페이스 스킬 호출
 
-<textarea readonly>Execute a skill within the main conversation
+```
+Skill(
+  skill="skill-creator:skill-creator",
+  args="create a skill that summarizes git log for a given date range"
+)
+```
 
-When users ask you to perform tasks, check if any of the available skills match. Skills provide specialized capabilities and domain knowledge.
+오쳐링 워크플로가 시작되도록 `skill-creator` 플러그인의 진입점을 통해 요청을 라우팅합니다.
 
-When users reference a "slash command" or "/<something>" (e.g., "/commit", "/review-pr"), they are referring to a skill. Use this tool to invoke it.
+## 참고사항
 
-How to invoke:
-- Use this tool with the skill name and optional arguments
-- Examples:
-  - `skill: "pdf"` - invoke the pdf skill
-  - `skill: "commit", args: "-m 'Fix bug'"` - invoke with arguments
-  - `skill: "review-pr", args: "123"` - invoke with arguments
-  - `skill: "ms-office-suite:pdf"` - invoke using fully qualified name
-
-Important:
-- Available skills are listed in system-reminder messages in the conversation
-- When a skill matches the user's request, this is a BLOCKING REQUIREMENT: invoke the relevant Skill tool BEFORE generating any other response about the task
-- NEVER mention a skill without actually calling this tool
-- Do not invoke a skill that is already running
-- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
-- If you see a <command-name> tag in the current conversation turn, the skill has ALREADY been loaded - follow the instructions directly instead of calling this tool again
-</textarea>
+- 이름이 available-skills 시스템 알림에 그대로 나타나거나 사용자가 메시지에서 직접 `/name`으로 입력한 스킬만 호출하십시오. 메모리나 학습 데이터에서 스킬 이름을 추측하거나 발명하지 마십시오 — 스킬이 광고되지 않으면 이 도구를 호출하지 마십시오.
+- 사용자의 요청이 광고된 스킬과 일치하면 `Skill` 호출은 차단 전제 조건입니다: 작업에 대한 다른 응답을 생성하기 전에 호출하십시오. 스킬이 무엇을 할지 설명하지 마십시오 — 실행하십시오.
+- 실제로 호출하지 않고 스킬을 이름으로 언급하지 마십시오. 도구를 호출하지 않고 스킬을 발표하는 것은 오해의 소지가 있습니다.
+- `/help`, `/clear`, `/model`, `/exit`와 같은 내장 CLI 명령에 `Skill`을 사용하지 마십시오. 이들은 하니스에 의해 직접 처리됩니다.
+- 현재 턴에서 이미 실행 중인 스킬을 다시 호출하지 마십시오. 현재 턴에서 `<command-name>` 태그를 보면 스킬이 이미 로드되었습니다 — 도구를 다시 호출하는 대신 지시사항을 그대로 따르십시오.
+- 여러 스킬이 적용될 수 있다면 가장 구체적인 것을 선택하십시오. 권한이나 후크 추가와 같은 구성 변경의 경우 일반 설정 접근 방식보다 `update-config`를 선호하십시오.
+- 스킬 실행은 턴의 나머지 동안 새로운 시스템 알림, 도구, 또는 제약 조건을 도입할 수 있습니다. 스킬이 완료된 후 진행하기 전에 대화 상태를 다시 읽으십시오.

package/concepts/ko/Tool-TaskCreate.md

@@ -1,78 +1,56 @@
 # TaskCreate
 
-## 정의
+현재 팀의 작업 목록 (또는 팀이 활성화되지 않은 경우 세션의 작업 목록)에 새 작업을 생성합니다. 나중에 추적, 위임, 또는 재방문해야 할 작업 항목을 캡처하는 데 사용합니다.
 
-구조화된 태스크 리스트 항목을 생성하여 진행 상황 추적, 복잡한 태스크 정리, 사용자에게 작업 진행 상황 표시에 사용합니다.
+## 사용 시점
 
-## 파라미터
+- 사용자가 명시적인 추적으로부터 이점을 얻는 다단계 작업을 설명합니다.
+- 큰 요청을 별도로 완료 가능한 작은 단위로 분할하고 있습니다.
+- 작업 중간에 후속 작업이 발견되었으며 잊지 말아야 합니다.
+- 팀원이나 서브에이전트에게 작업을 넘기기 전에 의도에 대한 영속적인 기록이 필요합니다.
+- 계획 모드에서 작동 중이며 각 계획 단계를 구체적인 작업으로 표현하려고 합니다.
 
-| 파라미터 | 타입 | 필수 | 설명 |
-|----------|------|------|------|
-| `subject` | string | 예 | 짧은 태스크 제목, 명령형 사용 (예: "Fix authentication bug") |
-| `description` | string | 예 | 상세 설명, 컨텍스트와 수락 기준 포함 |
-| `activeForm` | string | 아니오 | 진행 중 표시할 현재 진행형 텍스트 (예: "Fixing authentication bug") |
-| `metadata` | object | 아니오 | 태스크에 첨부할 임의의 메타데이터 |
+사소한 일회성 작업, 순수 대화, 또는 두세 번의 직접 도구 호출로 완료 가능한 작업에는 `TaskCreate`를 건너뛰십시오.
 
-## 사용 시나리오
+## 매개변수
 
-**적합한 경우:**
-- 복잡한 다단계 태스크 (3단계 이상)
-- 사용자가 여러 할 일 항목을 제공한 경우
-- 계획 모드에서 작업 추적
-- 사용자가 명시적으로 todo 리스트 사용을 요청
+- `subject` (string, 필수): 짧은 명령형 제목, 예를 들어 `Fix login redirect on Safari`. 대략 80자 미만으로 유지하십시오.
+- `description` (string, 필수): 상세한 컨텍스트 — 문제, 제약 조건, 수락 기준, 향후 독자가 필요할 파일이나 링크. 팀원이 이것을 차갑게 집어 드는 것처럼 작성하십시오.
+- `activeForm` (string, 선택): 작업이 `in_progress`일 때 표시되는 현재 진행형 스피너 텍스트, 예를 들어 `Fixing login redirect on Safari`. `subject`를 미러링하지만 -ing 형태로.
+- `metadata` (object, 선택): 작업에 첨부된 임의의 구조화된 데이터. 일반적인 용도: 레이블, 우선순위 힌트, 외부 티켓 ID, 또는 에이전트별 구성.
 
-**적합하지 않은 경우:**
-- 단일 간단한 태스크
-- 3단계 이내의 간단한 작업
-- 순수 대화 또는 정보 조회
+새로 생성된 작업은 항상 상태 `pending`으로 시작하며 소유자가 없습니다. 의존성 (`blocks`, `blockedBy`)은 생성 시점에 설정되지 않습니다 — 나중에 `TaskUpdate`로 적용하십시오.
 
-## 주의사항
+## 예시
 
-- 모든 새 태스크의 초기 상태는 `pending`
-- `subject`는 명령형 ("Run tests"), `activeForm`은 현재 진행형 ("Running tests") 사용
-- 생성 후 TaskUpdate로 의존 관계 (blocks/blockedBy) 설정 가능
-- 생성 전 TaskList를 호출하여 중복 태스크가 없는지 확인해야 함
+### 예시 1
 
-## 원문
+사용자가 방금 제출한 버그 보고서를 캡처합니다.
 
-<textarea readonly>Use this tool to create a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
-It also helps the user understand the progress of the task and overall progress of their requests.
+```
+TaskCreate(
+  subject: "Repair broken PDF export on Windows",
+  description: "Users on Windows 11 report the export button produces a 0-byte file. Reproduce with sample doc in test/fixtures/export/, then fix the code path in src/export/pdf.ts. Acceptance: export writes a valid PDF and the existing export test suite passes.",
+  activeForm: "Repairing broken PDF export on Windows"
+)
+```
 
-## When to Use This Tool
+### 예시 2
 
-Use this tool proactively in these scenarios:
+세션 시작 시 에픽을 추적된 단위로 분할합니다.
 
-- Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
-- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
-- Plan mode - When using plan mode, create a task list to track the work
-- User explicitly requests todo list - When the user directly asks you to use the todo list
-- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
-- After receiving new instructions - Immediately capture user requirements as tasks
-- When you start working on a task - Mark it as in_progress BEFORE beginning work
-- After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+```
+TaskCreate(
+  subject: "Draft migration plan for auth service",
+  description: "Produce a written plan covering rollout stages, rollback strategy, and monitoring. Output: docs/auth-migration.md.",
+  activeForm: "Drafting migration plan for auth service",
+  metadata: { "priority": "P1", "linearId": "AUTH-214" }
+)
+```
 
-## When NOT to Use This Tool
+## 참고사항
 
-Skip using this tool when:
-- There is only a single, straightforward task
-- The task is trivial and tracking it provides no organizational benefit
-- The task can be completed in less than 3 trivial steps
-- The task is purely conversational or informational
-
-NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
-
-## Task Fields
-
-- **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
-- **description**: Detailed description of what needs to be done, including context and acceptance criteria
-- **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
-
-**IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status `pending`.
-
-## Tips
-
-- Create tasks with clear, specific subjects that describe the outcome
-- Include enough detail in the description for another agent to understand and complete the task
-- After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
-- Check TaskList first to avoid creating duplicate tasks
-</textarea>
+- 작업이 `in_progress`로 전환될 때 UI가 자연스럽게 읽히도록 `subject`는 명령형 어조로, `activeForm`은 현재 진행형으로 작성하십시오.
+- 중복을 피하기 위해 생성 전에 `TaskList`를 호출하십시오 — 팀 목록은 팀원 및 서브에이전트와 공유됩니다.
+- `description`이나 `metadata`에 비밀이나 자격 증명을 포함하지 마십시오. 작업 기록은 팀에 접근할 수 있는 모든 사람에게 보입니다.
+- 생성 후 `TaskUpdate`로 작업을 수명 주기를 통해 이동시키십시오. `in_progress`에 작업을 조용히 방치하지 마십시오.

package/concepts/ko/Tool-TaskGet.md

@@ -1,56 +1,47 @@
 # TaskGet
 
-## 정의
+ID로 단일 작업의 전체 기록을 가져옵니다. 설명, 현재 상태, 소유자, 메타데이터, 의존성 에지를 포함합니다. `TaskList`에서 반환된 요약이 작업에 대해 행동하기에 충분하지 않을 때 사용합니다.
 
-태스크 ID로 태스크의 전체 상세 정보를 가져옵니다.
+## 사용 시점
 
-## 파라미터
+- `TaskList`에서 작업을 선택했고 시작하기 전에 전체 설명이 필요합니다.
+- 작업을 `completed`로 표시하려고 하며 수락 기준을 다시 확인하고 싶습니다.
+- 이 작업이 `blocks`하거나 `blockedBy`인 작업을 검사하여 다음 조치를 결정해야 합니다.
+- 기록을 조사하고 있습니다 — 누가 소유하는지, 어떤 메타데이터가 첨부되었는지, 언제 상태가 변경되었는지.
+- 팀원이나 이전 세션이 작업 ID를 참조했고 컨텍스트가 필요합니다.
 
-| 파라미터 | 타입 | 필수 | 설명 |
-|----------|------|------|------|
-| `taskId` | string | 예 | 가져올 태스크 ID |
+고수준 스캔만 필요할 때는 `TaskList`를 선호하십시오. `TaskGet`은 주의 깊게 읽거나 수정하려는 특정 기록에 예약하십시오.
 
-## 반환 내용
+## 매개변수
 
-- `subject` — 태스크 제목
-- `description` — 상세 요구사항과 컨텍스트
-- `status` — 상태: `pending`, `in_progress` 또는 `completed`
-- `blocks` — 이 태스크에 의해 차단된 태스크 목록
-- `blockedBy` — 이 태스크를 차단하는 선행 태스크 목록
+- `taskId` (string, 필수): `TaskCreate`나 `TaskList`에서 반환된 작업 식별자. ID는 작업의 수명 동안 안정적입니다.
 
-## 사용 시나리오
+## 예시
 
-**적합한 경우:**
-- 작업 시작 전 태스크의 전체 설명과 컨텍스트 획득
-- 태스크의 의존 관계 이해
-- 태스크를 할당받은 후 전체 요구사항 획득
+### 예시 1
 
-## 주의사항
+방금 목록에서 본 작업을 조회합니다.
 
-- 태스크 획득 후 작업 시작 전에 `blockedBy` 목록이 비어 있는지 확인해야 함
-- TaskList로 모든 태스크의 요약 정보 확인
+```
+TaskGet(taskId: "t_01HXYZ...")
+```
 
-## 원문
+일반적인 응답 필드: `id`, `subject`, `description`, `activeForm`, `status`, `owner`, `blocks`, `blockedBy`, `metadata`, `createdAt`, `updatedAt`.
 
-<textarea readonly>Use this tool to retrieve a task by its ID from the task list.
+### 예시 2
 
-## When to Use This Tool
+시작하기 전에 의존성을 해결합니다.
 
-- When you need the full description and context before starting work on a task
-- To understand task dependencies (what it blocks, what blocks it)
-- After being assigned a task, to get complete requirements
+```
+TaskGet(taskId: "t_01HXYZ...")
+# Inspect blockedBy — if any referenced task is still pending
+# or in_progress, work on the blocker first.
+```
 
-## Output
+## 참고사항
 
-Returns full task details:
-- **subject**: Task title
-- **description**: Detailed requirements and context
-- **status**: 'pending', 'in_progress', or 'completed'
-- **blocks**: Tasks waiting on this one to complete
-- **blockedBy**: Tasks that must complete before this one can start
-
-## Tips
-
-- After fetching a task, verify its blockedBy list is empty before beginning work.
-- Use TaskList to see all tasks in summary form.
-</textarea>
+- `TaskGet`은 읽기 전용이며 반복적으로 호출해도 안전합니다. 상태나 소유권을 변경하지 않습니다.
+- `blockedBy`가 비어 있지 않고 `completed`가 아닌 작업을 포함하는 경우 이 작업을 시작하지 마십시오 — 먼저 블로커를 해결하거나 (또는 소유자와 협력하십시오).
+- `description` 필드가 길 수 있습니다. 행동하기 전에 완전히 읽으십시오. 훑어보는 것은 놓친 수락 기준으로 이어집니다.
+- 알 수 없거나 삭제된 `taskId`는 오류를 반환합니다. 현재 ID를 선택하려면 `TaskList`를 다시 실행하십시오.
+- 작업을 편집하려고 한다면 팀원이 방금 변경한 필드를 덮어쓰지 않도록 먼저 `TaskGet`을 호출하십시오.

package/concepts/ko/Tool-TaskList.md

@@ -1,56 +1,62 @@
 # TaskList
 
-## 정의
+현재 팀 (또는 세션)의 모든 작업을 요약 형태로 반환합니다. 미결 작업을 조사하고, 다음에 무엇을 선택할지 결정하고, 중복 생성을 피하는 데 사용합니다.
 
-태스크 리스트의 모든 태스크를 나열하여 전체 진행 상황과 사용 가능한 작업을 확인합니다.
+## 사용 시점
 
-## 파라미터
+- 세션 시작 시 이미 추적되는 것을 보기 위해.
+- `TaskCreate`를 호출하기 전에 작업이 이미 캡처되지 않았는지 확인하기 위해.
+- 팀원이나 서브에이전트로서 다음에 어떤 작업을 주장할지 결정할 때.
+- 팀 전반의 의존성 관계를 한눈에 확인하기 위해.
+- 긴 세션 동안 주기적으로 작업을 주장, 완료, 또는 추가한 팀원과 재동기화하기 위해.
 
-파라미터 없음.
+`TaskList`는 읽기 전용이며 저렴합니다. 개요가 필요할 때마다 자유롭게 호출하십시오.
 
-## 반환 내용
+## 매개변수
 
-각 태스크의 요약 정보:
-- `id` — 태스크 식별자
-- `subject` — 짧은 설명
-- `status` — 상태: `pending`, `in_progress` 또는 `completed`
-- `owner` — 담당자 (agent ID), 비어 있으면 미할당
-- `blockedBy` — 이 태스크를 차단하는 미완료 태스크 ID 목록
+`TaskList`는 매개변수를 받지 않습니다. 항상 활성 컨텍스트의 전체 작업 집합을 반환합니다.
 
-## 사용 시나리오
+## 응답 형식
 
-**적합한 경우:**
-- 사용 가능한 태스크 확인 (상태가 pending, owner 없음, 차단되지 않음)
-- 프로젝트 전체 진행 상황 확인
-- 차단된 태스크 검색
-- 태스크 완료 후 다음 태스크 검색
+목록의 각 작업은 전체 기록이 아닌 요약입니다. 대략 다음을 기대하십시오:
 
-## 주의사항
+- `id` — `TaskGet` / `TaskUpdate`와 함께 사용할 안정적인 식별자.
+- `subject` — 짧은 명령형 제목.
+- `status` — `pending`, `in_progress`, `completed`, `deleted` 중 하나.
+- `owner` — 에이전트나 팀원 핸들, 또는 주장되지 않은 경우 비어 있음.
+- `blockedBy` — 먼저 완료되어야 하는 작업 ID 배열.
 
-- ID 순서대로 태스크를 처리하는 것을 우선 (최소 ID 우선). 초기 태스크가 보통 후속 태스크에 컨텍스트를 제공하기 때문
-- `blockedBy`가 있는 태스크는 의존이 해제될 때까지 인수할 수 없음
-- TaskGet으로 특정 태스크의 전체 상세 정보 획득
+특정 작업의 전체 설명, 수락 기준, 또는 메타데이터의 경우 `TaskGet`으로 후속 작업을 진행하십시오.
 
-## 원문
+## 예시
 
-<textarea readonly>Use this tool to list all tasks in the task list.
+### 예시 1
 
-## When to Use This Tool
+빠른 상태 확인.
 
-- To see what tasks are available to work on (status: 'pending', no owner, not blocked)
-- To check overall progress on the project
-- To find tasks that are blocked and need dependencies resolved
-- After completing a task, to check for newly unblocked work or claim the next available task
-- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones
+```
+TaskList()
+```
 
-## Output
+`owner` 없는 `in_progress` (오래된 작업)와 `blockedBy`가 비어 있는 `pending` (선택 가능)을 출력에서 스캔하십시오.
 
-Returns a summary of each task:
-- **id**: Task identifier (use with TaskGet, TaskUpdate)
-- **subject**: Brief description of the task
-- **status**: 'pending', 'in_progress', or 'completed'
-- **owner**: Agent ID if assigned, empty if available
-- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)
+### 예시 2
 
-Use TaskGet with a specific task ID to view full details including description and comments.
-</textarea>
+다음 작업을 선택하는 팀원.
+
+```
+TaskList()
+# Filter to: status == pending AND blockedBy is empty AND owner is empty.
+# Among those, prefer the lower ID (tasks are typically numbered in
+# creation order, so lower IDs are older and usually higher priority).
+TaskGet(taskId: "<chosen id>")
+TaskUpdate(taskId: "<chosen id>", status: "in_progress", owner: "<your handle>")
+```
+
+## 참고사항
+
+- 팀원 휴리스틱: 여러 `pending` 작업이 차단되지 않고 소유되지 않은 경우 가장 낮은 ID를 선택하십시오. 이것은 작업을 FIFO로 유지하고 두 에이전트가 동일한 주목받는 작업을 잡는 것을 방지합니다.
+- `blockedBy`를 존중하십시오: 블로커가 여전히 `pending`이나 `in_progress`인 작업을 시작하지 마십시오. 먼저 블로커를 작업하거나 소유자와 협력하십시오.
+- `TaskList`는 작업을 발견하는 유일한 메커니즘입니다. 검색이 없습니다. 목록이 길면 구조적으로 (상태별, 그다음 소유자별) 스캔하십시오.
+- 삭제된 작업은 추적 가능성을 위해 상태 `deleted`로 목록에 여전히 나타날 수 있습니다. 계획 목적으로 무시하십시오.
+- 목록은 팀의 실시간 상태를 반영하므로 팀원이 호출 간에 작업을 추가하거나 주장할 수 있습니다. 시간이 경과한 경우 주장 전에 다시 나열하십시오.

package/concepts/ko/Tool-TaskOutput.md

@@ -1,40 +1,50 @@
 # TaskOutput
 
-## 정의
+실행 중이거나 완료된 백그라운드 작업 — 백그라운드 셸 명령, 로컬 에이전트, 또는 원격 세션 — 의 누적된 출력을 가져옵니다. 장시간 실행되는 작업이 지금까지 생성한 것을 검사해야 할 때 사용합니다.
 
-실행 중이거나 완료된 백그라운드 태스크의 출력을 가져옵니다. 백그라운드 셸, 비동기 agent, 원격 세션에 적용됩니다.
+## 사용 시점
 
-## 파라미터
+- 원격 세션 (예: 클라우드 샌드박스)이 실행 중이며 stdout이 필요합니다.
+- 로컬 에이전트가 백그라운드에서 디스패치되었고 반환되기 전에 부분적인 진행 상황을 원합니다.
+- 백그라운드 셸 명령이 충분히 오래 실행되어 중지하지 않고 확인하고 싶습니다.
+- `TaskStop`을 호출하기 전에 백그라운드 작업이 실제로 진행 중인지 확인해야 합니다.
 
-| 파라미터 | 타입 | 필수 | 설명 |
-|----------|------|------|------|
-| `task_id` | string | 예 | 태스크 ID |
-| `block` | boolean | 예 | 태스크 완료까지 블로킹 대기 여부, 기본값 `true` |
-| `timeout` | number | 예 | 최대 대기 시간 (밀리초), 기본값 30000, 최대 600000 |
+반사적으로 `TaskOutput`에 손을 뻗지 마십시오. 대부분의 백그라운드 작업에는 더 직접적인 경로가 있습니다 — 아래 참고사항을 참조하십시오.
 
-## 사용 시나리오
+## 매개변수
 
-**적합한 경우:**
-- Task (`run_in_background: true`)로 시작한 백그라운드 agent의 진행 상황 확인
-- 백그라운드 Bash 명령의 실행 결과 획득
-- 비동기 태스크 완료를 기다리고 출력 획득
+- `task_id` (string, 필수): 백그라운드 작업이 시작되었을 때 반환된 작업 식별자. 작업 목록 `taskId`와 동일하지 않습니다. 이것은 특정 실행의 런타임 핸들입니다.
+- `block` (boolean, 선택): `true` (기본값)인 경우 작업이 새 출력을 생성하거나 완료될 때까지 기다린 후 반환합니다. `false`인 경우 버퍼링된 것과 함께 즉시 반환합니다.
+- `timeout` (number, 선택): 반환 전에 차단할 최대 밀리초. `block`이 `true`일 때만 의미가 있습니다. 기본값 `30000`, 최대 `600000`.
 
-**적합하지 않은 경우:**
-- 포그라운드 태스크 — 포그라운드 태스크는 직접 결과를 반환하므로 이 도구가 불필요
+## 예시
 
-## 주의사항
+### 예시 1
 
-- `block: true`는 태스크 완료 또는 타임아웃까지 블로킹
-- `block: false`는 논블로킹으로 현재 상태 확인
-- 태스크 ID는 `/tasks` 명령으로 검색 가능
-- 모든 태스크 타입에 적용: 백그라운드 셸, 비동기 agent, 원격 세션
+차단하지 않고 원격 세션을 엿봅니다.
 
-## 원문
+```
+TaskOutput(task_id: "sess_01HXYZ...", block: false)
+```
 
-<textarea readonly>- Retrieves output from a running or completed task (background shell, agent, or remote session)
-- Takes a task_id parameter identifying the task
-- Returns the task output along with status information
-- Use block=true (default) to wait for task completion
-- Use block=false for non-blocking check of current status
-- Task IDs can be found using the /tasks command
-- Works with all task types: background shells, async agents, and remote sessions</textarea>
+작업이 시작된 이후 (또는 런타임에 따라 마지막 `TaskOutput` 호출 이후) 생성된 stdout/stderr를 반환합니다.
+
+### 예시 2
+
+로컬 에이전트가 더 많은 출력을 생성할 때까지 잠시 기다립니다.
+
+```
+TaskOutput(
+  task_id: "agent_01ABCD...",
+  block: true,
+  timeout: 10000
+)
+```
+
+## 참고사항
+
+- 백그라운드 bash 명령: `TaskOutput`은 이 사용 사례에서 사실상 폐기되었습니다. 백그라운드 셸 작업을 시작할 때 결과에는 이미 출력 파일에 대한 경로가 포함되어 있습니다 — `Read` 도구로 직접 그 경로를 읽으십시오. `Read`는 랜덤 접근, 줄 오프셋, 안정적인 보기를 제공합니다. `TaskOutput`은 그렇지 않습니다.
+- 로컬 에이전트 (백그라운드에서 디스패치된 `Agent` 도구): 에이전트가 완료되면 `Agent` 도구 결과에 이미 최종 응답이 포함되어 있습니다. 그것을 직접 사용하십시오. 심볼릭 링크된 기록 파일을 `Read`하지 마십시오 — 전체 도구 호출 스트림을 포함하고 컨텍스트 창을 넘칠 것입니다.
+- 원격 세션: `TaskOutput`은 출력을 다시 스트림하는 올바른 방법이며 종종 유일한 방법입니다. 긴 폴링 루프 대신 적당한 `timeout`과 함께 `block: true`를 선호하십시오.
+- 알 수 없는 `task_id`, 또는 출력이 가비지 수집된 작업은 오류를 반환합니다. 여전히 필요하면 작업을 다시 디스패치하십시오.
+- `TaskOutput`은 작업을 중지하지 않습니다. 종료하려면 `TaskStop`을 사용하십시오.

package/concepts/ko/Tool-TaskStop.md

@@ -1,32 +1,45 @@
 # TaskStop
 
-## 정의
+런타임 핸들로 실행 중인 백그라운드 작업 — 셸 명령, 디스패치된 에이전트, 또는 원격 세션 — 을 중지합니다. 리소스를 회수하고, 더 이상 유용하지 않은 작업을 취소하거나, 작업이 멈춘 경우 복구하는 데 사용합니다.
 
-실행 중인 백그라운드 태스크를 중지합니다.
+## 사용 시점
 
-## 파라미터
+- 백그라운드 셸 명령이 예상보다 오래 실행되었고 더 이상 결과가 필요하지 않습니다.
+- 로컬 에이전트가 반복되거나 정체되어 있고 단절해야 합니다.
+- 사용자가 방향을 바꾸었고 이전 방향에 대한 백그라운드 작업을 버려야 합니다.
+- 원격 세션이 곧 타임아웃되거나 필요한 리소스를 보유하고 있습니다.
+- 동일한 작업의 새 실행을 시작하기 전에 깨끗한 상태가 필요합니다.
 
-| 파라미터 | 타입 | 필수 | 설명 |
-|----------|------|------|------|
-| `task_id` | string | 아니오 | 중지할 백그라운드 태스크 ID |
-| `shell_id` | string | 아니오 | 더 이상 사용되지 않음, `task_id`를 대신 사용 |
+단기 백그라운드 작업은 스스로 완료되도록 두는 것을 선호하십시오. `TaskStop`은 계속 실행이 가치가 없거나 적극적으로 해로운 경우를 위한 것입니다.
 
-## 사용 시나리오
+## 매개변수
 
-**적합한 경우:**
-- 더 이상 필요 없는 장시간 실행 태스크 종료
-- 잘못 시작한 백그라운드 태스크 취소
+- `task_id` (string, 필수): 백그라운드 작업이 시작되었을 때 반환된 런타임 핸들. 이것은 `TaskOutput`에 의해 수락되는 동일한 식별자이며, 작업 목록 `taskId`가 아닙니다.
 
-## 주의사항
+## 예시
 
-- 성공 또는 실패 상태를 반환
-- `shell_id` 파라미터는 더 이상 사용되지 않으며, `task_id`를 사용해야 함
+### 예시 1
 
-## 원문
+폭주하는 백그라운드 셸 명령을 중지합니다.
 
-<textarea readonly>
-- Stops a running background task by its ID
-- Takes a task_id parameter identifying the task to stop
-- Returns a success or failure status
-- Use this tool when you need to terminate a long-running task
-</textarea>
+```
+TaskStop(task_id: "bash_01HXYZ...")
+```
+
+명령은 종료 신호를 받습니다. 지금까지 작성된 버퍼링된 출력은 출력 경로에서 읽을 수 있는 상태로 남아 있습니다.
+
+### 예시 2
+
+사용자의 경로 수정 후 디스패치된 에이전트를 취소합니다.
+
+```
+TaskStop(task_id: "agent_01ABCD...")
+```
+
+## 참고사항
+
+- `TaskStop`은 종료를 요청합니다. 즉각적인 종료를 보장하지 않습니다. 잘 동작하는 작업은 신속하게 종료되지만, 차단 I/O를 수행하는 프로세스는 풀리는 데 시간이 걸릴 수 있습니다.
+- 작업 중지는 출력을 삭제하지 않습니다. 백그라운드 셸 작업의 경우 디스크의 출력 파일이 보존되며 `Read`로 여전히 읽을 수 있습니다. 에이전트와 세션의 경우 중지 전에 캡처된 모든 출력은 `TaskOutput`을 통해 여전히 접근 가능합니다.
+- 알 수 없는 `task_id`, 또는 이미 완료된 작업은 오류나 no-op를 반환합니다. 이것은 안전합니다 — 상태를 먼저 확인하지 않고도 방어적으로 `TaskStop`을 호출할 수 있습니다.
+- 동일한 작업을 다시 시작하려는 경우, 공유 리소스 (파일, 포트, 데이터베이스 행)에서 경쟁하는 두 병렬 실행을 피하기 위해 새 것을 디스패치하기 전에 이전 작업을 중지하십시오.
+- `TaskStop`은 팀 작업 목록의 항목에 영향을 미치지 않습니다. 추적된 작업을 취소하려면 `TaskUpdate`로 상태를 `deleted`로 업데이트하십시오.