DingTalk Workspace CLI (dws)

dws

— 사람과 AI 에이전트를 위해 구축된 명령줄 기반의 DingTalk Workspace.

중국어판 · English · Reference · Changelog

Important

Co-creation Phase: 이 프로젝트는 DingTalk 엔터프라이즈 데이터를 사용하며 엔터프라이즈 관리자 승인이 필요합니다. 지원 및 업데이트를 받으려면 DingTalk DWS 공동 창작 그룹에 참여하십시오. 아래 Getting Started를 참조하십시오.

Table of Contents

사람을 위한 기능—--help

사용법, 요청 미리 보기는 --dry-run, 출력 형식은 -f table/json/raw를 사용합니다.AI 에이전트를 위한 기능—구조화된 JSON 응답 + 내장 Agent Skills가 즉시 사용할 수 있도록 준비되어 있습니다.엔터프라이즈 관리자를 위한 기능—제로 트러스트 아키텍처: OAuth device-flow 인증 + 도메인 허용 목록(allowlisting) + 최소 권한 범위 지정(least-privilege scoping).어떤 바이트도 인증 및 감사 과정을 우회할 수 없습니다.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

Linux 바이너리는 glibc(기준선 2.17)에 연결되어 있습니다. Alpine과 같은 musl 기반 배포판은 지원되지 않으며, 설치 프로그램은 이를 감지하고 실행할 수 없는 바이너리를 설치하는 대신 중단됩니다.

Windows (PowerShell):

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

Skill 모드: mono 대 multi

설치 프로그램은 두 가지 레이아웃 중 하나로 스킬을 배포합니다. CLI 명령어(dws aitable ..., dws calendar ...)는 두 모드 모두에서 동일하며, 에이전트 측의 스킬 레이아웃만 다릅니다.

설치 및 업그레이드는 기본적으로 multi로 설정됩니다.

.mono는 DWS_SKILL_MODE=mono 또는 dws skill setup --mode mono를 통해 사용할 수 있습니다. 문제가 발생하면 파일을 확인하십시오.

선택 방법:

빠른 설치(위의 한 줄 명령어): 비대화형이며, multi를 설치합니다.

TTY 설치 (다운로드 후 실행):
`curl -O .../install.sh && bash install.sh``

— 프롬프트: `1) multi 2) mono``

(기본값 1). 환경 변수를 통한 재정의: `curl -fsSL ... | DWS_SKILL_MODE=mono sh``

.나중에 전환하기: `dws skill setup --mode mono``

(또는 --mode multi)
— 나열된 경로를 검토하고 대화식으로 확인합니다.

기타 설치 방법

npm (Node.js (npm/npx) 필요):

`npm install -g dingtalk-workspace-cli``

최신 베타 버전 설치:

`npm install -g dingtalk-workspace-cli@beta``

Homebrew (macOS / Linux):

brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
brew install dingtalk-workspace-cli

Formula는 이 저장소에 있으므로, 첫 번째 tap 명령어에는 명시적인 저장소 URL이 포함되어야 합니다. 그 후에는 평소처럼 brew upgrade dingtalk-workspace-cli를 사용합니다.

안정적인 Formula를 대체하지 않고 keg-only Homebrew 베타 설치:

brew install dingtalk-workspace-cli-beta
$(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version

베타 dws를 현재 셸의 기본값으로 설정하려면, $(brew --prefix dingtalk-workspace-cli-beta)/bin을 PATH 앞에 추가합니다.

사전 빌드된 바이너리: GitHub Releases에서 다운로드합니다.

macOS 사용자:

오직 스텁 빌드(stub build)가 의도된 경우에만 사용합니다. make package를 사용하세요.

Docker를 사용하여 저장소의 고정 크로스 컴파일 도구 체인(cross-compilation toolchain)을 통해 여섯 가지 릴리스 타겟 전체를 빌드할 수 있습니다.

중국 본토 사용자들을 위해 다음 채널들은 GitHub 네트워크 문제를 우회합니다. 기본적으로 (이 환경 변수들을 설정하지 않으면) 설치 프로그램은 GitHub에서 가져옵니다.

1. 설치 스크립트 + 사전 빌드 바이너리 (Gitee 미러):

저장소 미러: https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli

curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install.sh | DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli sh

DWS_GITEE_REPO가 설정되면, 설치 프로그램은 GitHub 대신 Gitee API에서 최신 버전과 모든 릴리스 에셋(바이너리, 체크섬, 스킬)을 가져옵니다. 이 변수가 설정되지 않으면, 설치는 기본적으로 GitHub를 사용합니다.

2. npm 패키지 (npmmirror 미러):

npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com

npmmirror는 공개 npm 레지스트리에서 공개 패키지를 자동으로 동기화하므로, 중국에서도 직접 작동합니다.

3. 스킬 전용 (Gitee 미러):

curl -fsSL https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli/raw/main/scripts/install-skills.sh | DWS_GITEE_REPO=DingTalk-Real-AI/dingtalk-workspace-cli sh

DWS_GITEE_REPO가 설정되면, install-skills.sh는 Gitee에서 버전과 스킬 패키지를 가져오며; GitHub에 연결할 수 없을 때도 Gitee 미러로 자동 폴백(auto-falls back)합니다.

v1.0.7 이상이 필요합니다. 이전 버전의 경우, 설치 스크립트를 다시 실행하여 업그레이드해 주세요.

dws는 내장된 자체 업그레이드 기능(self-upgrade capability)을 가지고 있습니다. 업데이트는 SHA256 무결성 검증과 자동 백업을 통해 GitHub Releases에서 직접 가져옵니다.

dws upgrade # 최신 버전으로 대화형 업그레이드
dws upgrade --check # 설치 없이 새 버전 확인
dws upgrade --list # 안정 릴리스 버전 목록 표시
...

기본적으로, dws upgrade는 안정 릴리스 트랙(stable release track)을 따릅니다. --beta를 사용하세요.

오직 최신 GitHub 프리릴리스 빌드를 명시적으로 원할 때만 해당됩니다.

유지 관리자 및 릴리스 검증자는 curl, PowerShell, npm stable, npm beta, Homebrew, 그리고 dws upgrade에 대한 릴리스 품질 스모크 테스트를 실행할 수 있습니다.

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git /tmp/dws-verify
cd /tmp/dws-verify/verify
bash verify-all-channels.sh

이 검증기는 격리된 디렉토리를 사용하며 현재 PATH에 있는 dws를 대체하지 않습니다. 이는 PASS, FAIL, 그리고 SKIP을 보고합니다. 플랫폼 스킵은 패스가 아니며 일치하는 호스트에서 처리되어야 합니다. 플랫폼 매트릭스는 verify/README.md를 참조하십시오.

작동 방식

업그레이드 프로세스는 일관성을 보장하기 위해 2단계의 원자적 흐름(atomic flow)을 따릅니다:

준비(Prepare) — 플랫폼별 바이너리와 스킬 패키지를 임시 디렉토리에 다운로드하고, SHA256 체크섬을 검증하며, 모든 파일을 추출/유효성 검사합니다. 어느 단계에서든 실패하면 기존 설치를 수정하지 않고 업그레이드가 중단됩니다.적용(Apply) — 모든 준비가 성공한 후에만 바이너리가 교체되고 스킬이 표준 ~/.agents/skills 루트로 평탄화(flattened)됩니다. 핀 호환성 레지스트리(pinned compatibility registry)에 의해 범용 루트를 지원하는 것으로 분류된 에이전트는 이를 직접 읽고; 다른 감지된 에이전트는 링크를 받으며, 링크가 사용할 수 없을 때는 직접 복사 대체(direct-copy fallback)를 사용합니다. 이전 DWS 관리 에이전트별 사본은 백업되고 폐기되어 동일한 스킬이 두 번 발견되는 것을 방지합니다.

각 업그레이드 전에 현재 버전의 백업이 자동으로 생성됩니다. 필요하면 dws upgrade --rollback을 사용하여 이전 버전을 복원하십시오.

dws auth login # 브라우저가 자동으로 열림
dws auth login --device # 헤드리스 환경(Docker, SSH, CI)용

조직을 선택하고 승인하면 됩니다. 끝입니다.

만약 조직에서 CLI 접근이 활성화되지 않았다면, 관리자에게 접근 요청을 보내라는 메시지가 표시됩니다. 승인이 완료되면 다시 실행하세요:

dws auth login

조직에서 CLI 접근을 활성화하지 않았나요?

• 조직 선택 후

비즈니스 명령어는 필요할 때 로컬 OAuth 자격 증명을 자동으로 확인하고 새로 고치므로, 요청 전에 auth status를 실행할 필요가 없습니다. auth status는 새로 고침(refresh), 마이그레이션(migration) 및 복구(repair) 동작을 유지하며 인증 잠금(authentication lock)을 기다릴 수 있습니다.
동시 폴링(concurrent polling)에는 dws auth status --readonly --format json (선택적으로 --profile과 함께 사용)를 사용하십시오. 이는 인증 잠금, 네트워크 유효성 검사, 새로 고침, 마이그레이션 또는 자격 증명 쓰기 없이 로컬 스냅샷을 읽습니다. 시스템 키체인(System Keychain) 읽기는 여전히 기다릴 수 있습니다. 두 모드 모두 동일한 출력 필드를 사용합니다. 비어있지 않은 reason을 가진 읽기 전용 결과는 결정적이지 않으며 확정된 로그아웃으로 간주해서는 안 됩니다. local_state_requires_repair는 마이그레이션/복구를 나타내고, local_state_unreadable는 로컬 읽기 실패를 나타냅니다. 새로 고침 또는 복구를 위해 --readonly 없이 auth status를 동일한 프로필로 사용하십시오. 읽기 전용 모드는 절대 새로 고침을 보고하지 않으며, 일반 모드에서 새로 고칠 액세스 토큰이 만료되었다고 보고할 수 있습니다. 동시 업데이트는 이전 스냅샷이나 결정적이지 않은 결과를 제공할 수 있습니다. 두 모드 모두 authenticated가 참인 경우는 액세스 자격 증명 또는 새로 고침 자격 증명 중 하나라도 유효한 경우입니다. token_valid은 액세스 토큰 사용 가능성을 별도로 설명합니다.

dws auth login # 계정 추가 또는 새로 고침
dws profile list # 로그인된 모든 계정 목록 표시
dws profile switch <corpId:userId> # 영구적으로 전환; -를 사용하여 다시 토글
...

셀렉터는 corpId:userId, corpId:userName, corpName:userId, 및 corpName:userName을 지원합니다. 사용자 친화적인 이름은 입력 별칭일 뿐이므로, 자동화를 위해서는 profile list에서 반환되는 안정적인 profile 값을 사용하십시오. 중복된 조직 또는 계정 이름은 명시적인 corpId:userId 후보와 함께 실패합니다. 조직에 여러 계정이 있지만 기록된 현재 계정이 없는 경우, --profile <corpId>는 첫 번째 또는 가장 최근에 사용된 계정을 선택하는 대신 실패합니다.

currentProfile, previousProfile, 및 조직별 기본값은 정확한 ID로 저장됩니다. primaryProfile

호환성을 위해 JSON 형식으로만 유지되며 선택에 사용되지 않습니다. profile list

각 실제 ID 토큰에서 상태와 만료일을 읽지만 새로고침하지는 않습니다. auth logout --profile <corpId>

해당 조직의 모든 로컬 계정을 제거합니다. 정확한 셀렉터 또는 로컬 프로필 이름은 하나의 계정을 제거합니다.

조직 간(Cross-org) 읽기는 내장된 --all-orgs 대신 에이전트가 조정합니다.

: list profiles, corpId로 그룹화하고, 각 조직에 대해 고유한 isOrgCurrent=true 계정을 사용합니다. 다중 계정 조직에 기본값이 없는 경우, 사용자에게 먼저 계정을 선택하도록 요청합니다. 쓰기는 현재 계정에 기본값을 설정합니다 — 조직과 계정을 모두 확인한 후에만 조직 간 쓰기를 수행합니다.

macOS에서는 임시적이거나 분류되지 않은 Keychain 읽기 실패가 혼합된 Keychain/파일-DEK 상태를 위험에 빠뜨리기보다는 새로운 OAuth 로그인 시도를 차단합니다. 확정적으로 누락된 DEK 또는 암호문/DEK 불일치는 인증 과정을 통해 유지되며, 새 로그인이 대상으로 하는 슬롯에 대해서만 대체됩니다. DWS_DISABLE_KEYCHAIN=1을 사용하는 샌드박스에서 정상적인 터미널 명령이 여전히 로그인 정보를 읽을 수 있는 경우