slivingdoc

테스트 커버리지: 83.7% 😍👌

기능

• Git과 유사한 의미론: slivingdoc는 우리(와 에이전트)가 모두 알고 있는 용어를 사용하며, 사용 편의성을 위해 설계되었습니다.

• 자동 충돌 해결: 두려움 없이 커밋하세요. 모든 충돌이 수락되기 전에 반드시 해결되어야 함을 신뢰하세요.

• 고속 처리: 솔루션은 개념적으로 매우 간단하여, 매우 높은 확장성과 병렬 처리를 가능하게 합니다.

• 플러그 앤 플레이: 버킷을 설정하고, 그것을 가리키고, 노트 동기화를 시작하세요!

docs/slivingdoc-v1.md는 이러한 보장 뒤에 있는 완전히 수락된 계약서입니다.

Related MCP server: Cellar

시작하기

에이전트 하네스에 추가하세요:

{
  "mcpServers": {
    "slivingdoc": {
      "command": "npx",
      "args": [
        "-y",
        "slivingdoc",
        "serve",
        "--bucket",
        "my-notes",
        "--workspace-root",
        "/srv/notes"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your-access-key-id>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-access-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

버킷이 존재해야 하며, 자격 증명은 일반 AWS 체인에서 가져옵니다. 아직 S3 계정이 없으신가요? examples/seaweedfs/는 단계별 안내와 함께 로컬 SeaweedFS 컨테이너를 실행합니다. 또한 GitHub 릴리스에서 네이티브 바이너리를 직접 다운로드하여 (slivingdoc-v<semver>-<os>-<arch>) 그 자리에서 실행할 수 있습니다.

지원 플랫폼: Linux (amd64, 32-bit ARMv7, arm64), macOS (amd64, arm64), Windows (amd64). 32비트 Linux ARM 아티팩트는 Raspberry Pi OS armhf를 지원합니다.

작동 방식

서버는 stdio를 통해 두 개의 MCP 도구를 노출합니다:

notes_pull은 현재 노트북을 디렉토리에 씁니다. notes_commit은 변경 사항을 게시하고 동시에 충돌하지 않는 변경 사항을 통합합니다. 호출 사이에는 프로토콜이 전혀 없습니다. 에이전트는 이미 가지고 있는 도구로 파일을 편집하고, 인간은 모든 편집기로 동일한 디렉토리에 쓸 수 있습니다. 다음 커밋은 그들의 변경 사항도 전달합니다.

인간은 MCP 호스트 없이도 두 작업을 직접 수행할 수 있습니다. 상대 경로는 작업 디렉토리를 기준으로 확인됩니다:

slivingdoc pull notes
# edit UTF-8 text files under notes/
slivingdoc commit notes -m "meeting summary"

성공 시 통합 결과 보고서가 출력됩니다: OK 상태, 수락된 원격 생성, 파일별 삽입 및 삭제 수, 총계 요약. 도메인 오류는 0이 아닌 종료 코드와 함께 솔직한 보고서를 출력합니다: 오류 범주, 재시도 가능 여부, 충돌이 발생한 각 파일과 해당 라인 범위. 색상은 실제 터미널에서만 나타나며, 비어 있지 않은 NO_COLOR에 의해 비활성화됩니다.

Git 부분

모든 에이전트가 동시에 쓰도록 두면 작동하겠지만, 경쟁 조건에 압도될 것입니다. 따라서 slivingdoc는 libgit2를 통해 내장된 Git을 가지고 있으며, 효과적으로 다음을 수행합니다:

1. git pull

2. (잠재적 충돌 해결 로컬에서)

3. git add .

4. git commit -m "<agent message>"

5. git push

6. (잠재적 충돌 해결 로컬에서)

이 모든 Git 작업은 노트 디렉토리의 개인 미러 내에서 로컬로 처리되어 "간소화된" Git 시퀀스를 남깁니다. 이는 두 가지 절충 덕분에 작동합니다. 첫째, 로컬 노트 디렉토리는 notes_pull 시 변경되기 쉬우며, 원격 상태에 우선권이 있어 충돌 표시를 남깁니다. 둘째, 시스템은 텍스트(깨끗한 UTF-8)에만 작동합니다.

구성

serve, pull, commit은 동일한 플래그와 환경 변수를 읽습니다. --bucket은 필수입니다. 가장 일반적인 플래그:

slivingdoc serve -h는 전체 참조를 출력하며, docs/running.md는 운영자에게 필요한 모든 것을 다룹니다: 모든 플래그, 정확한 S3 권한, 로깅(stderr의 LOG_LEVEL), 노트북 규칙, 충돌 복구, 체크포인트 보존. terraform/의 Terraform 모듈은 하나의 노트북을 위한 버킷과 최소 권한 IAM 사용자를 프로비저닝합니다.

개발

• AGENTS.md — 개발자 및 에이전트 가이드: 패키지 맵, 작업 흐름, 규칙, QA 게이트.

• docs/slivingdoc-v1.md — 수락된 아키텍처 계약서.

• docs/build.md — 고정된 libgit2 소스부터 종속성 검사까지의 네이티브 빌드.

• docs/testing.md — 테스트 명령, 테스트 계층, 라이브 AWS 없음 규칙.

• docs/releasing.md — 릴리스 아티팩트, npm 신뢰할 수 있는 게시, make release.

make qa #lint plus the full Go and npm test suites

라이선스

MIT — LICENSE를 참조하세요. 정적으로 링크된 libgit2에 대한 타사 고지는 NOTICE에 있습니다.

Paris Hilton과 관련 없음.