darkhipo/sharethought

sharethought은(는) 무엇을 하나요?

sharethought 파일은 이미지와 함께 텍스트 섹션을 운반하는 유효한 PNG입니다. 어디서나 일반 이미지처럼 열리고 렌더링됩니다. 이미지 뒤에는: 렌더링된 SVG 소스와 마크다운 문서가 있습니다. 운반된 데이터의 앞부분에 있는 매니페스트는 모든 것을 색인하고 파일 자체 내부에 언패킹/재패킹 지침을 담고 있습니다.

섹션은 두 가지 캐리어 중 하나로 운반될 수 있습니다: IEND 청크 뒤에 추가되거나(간단한 바이트 정확 전송 전용), PNG 보조 청크 내부에 위치합니다(이미지 파이프라인에서 생존). 캐리어를 참조하세요.

레퍼런스 구현 사용

이 저장소의 sharethought.py는 테스트된 표준 라이브러리 전용 구현입니다. 직접 만든 파싱보다 이를 선호하세요. 모든 재구현은 새로운 버그 표면입니다.

python3 sharethought.py pack   --png base.png --svg s.svg --doc d.md -o out.png --what "한 줄"
python3 sharethought.py unpack out.png [--out-dir DIR]
python3 sharethought.py repack --text out.png --set doc=new.md -o out2.png
python3 sharethought.py verify out.png
python3 -m unittest -q test_sharethought    # 테스트 스위트

pack은 한 번의 빌드로 두 캐리어를 모두 씁니다(서로 다를 수 없음). unpack은 청크를 우선하고 트레일러로 폴백하며, 두 캐리어가 모두 존재하지만 불일치하는 경우 큰 소리로 오류를 발생시킵니다. pack은 그런 상황을 만들 수 없으므로 불일치는 외부 변조를 의미합니다. verify는 서명, IEND, 두 캐리어, 섹션 이름 문법, 그리고 매니페스트↔섹션 일관성을 확인합니다.

형식 (정확)

[ PNG 바이트 ... IEND 청크 ]
SHARETHOUGHT-v1\n
[ JSON 매니페스트 — 하나의 UTF-8 객체, 스키마 참조 ]\n
<<<SECTION:이름>>>\n
[ 섹션 내용 — 기본 원시 UTF-8, "enc":"base64"인 경우 base64 ]\n
<<<END:이름>>>\n
... (추가 섹션, 동일한 프레임)

마커 SHARETHOUGHT-v1은 PNG의 IEND 청크 바로 뒤에서 시작하며 개행 문자로 종료됩니다. (그 앞의 바이트는 IEND 청크의 CRC 꼬리이지 개행 문자가 아닙니다. 따라서 바이트 단위로 찾고 줄 단위로 찾지 마세요.) 마커부터 EOF까지의 모든 것이 트레일러입니다. 표준 섹션: svg (이미지 소스, image/svg+xml) 및 doc (마크다운, text/markdown). 임의의 추가 섹션이 허용됩니다. 모든 텍스트 유형입니다.

섹션 이름은 [A-Za-z0-9_]+와 일치해야 합니다. 이 문법을 벗어나는 이름은 패킹 시 거부되고 언팩 시 명명된 오류로 플래그 지정됩니다. 결코 조용히 사라지지 않습니다.

캐리어

동일한 매니페스트와 섹션을 두 가지 방법으로 운반할 수 있습니다. 전송 방식에 따라 선택하세요.

A. 트레일러 — IEND 청크 뒤에 추가됨 (위의 기본값).

• 수동으로 쓰기 쉬움: cat trailer.txt >> file.png. CRC, 청크 프레임, 라이브러리 없음.
• 바이트 정확 전송만 생존: git, zip, curl -O, 직접 파일 복사.
• 이미지를 재직렬화하거나 재인코딩하는 모든 파이프라인에서 생존하지 않음. PNG→JPEG 트랜스코드는 완전히 제거합니다. 많은 채팅 및 드라이브 파이프라인이 수행하는 청크 수준 재작성은 모든 IDAT 바이트를 유지하지만 IEND 이후의 모든 것을 폐기합니다.

B. 보조 청크 — PNG 청크 스트림 내부의 iTXt.

• 청크 목록 내부에 있으므로 청크 수준 재작성과 PNG를 유지하는 이미지 파이프라인에서 생존합니다.
• CRC 및 청크 프레임 비용이 들며, 큰 섹션은 압축이 필요합니다.
• PNG→JPEG 트랜스코드에서 생존하지 않음 — 픽셀 외에는 어떤 것도 생존하지 않습니다.

권장: 둘 다 작성 (pack이 수행함). 동일한 페이로드, 하나의 빌드, 발산 불가능. 리더는 먼저 청크를 찾고 트레일러로 폴백하므로 파일은 채팅 파이프라인과 바이트 정확 전송 모두에서 작동합니다. 비용은 페이로드의 대략 한 번의 추가 복사본입니다.

청크 레이아웃:

[ IHDR ] [ IDAT ... ] [ iTXt sharethought:manifest ] [ iTXt sharethought:<이름> ] ... [ IEND ]

섹션당 하나의 iTXt: 매니페스트의 경우 키워드 sharethought:manifest, 각 섹션 본문의 경우 sharethought:<이름> (원시 본문, 구분 기호 없음). 표준 iTXt 프레임 — 키워드 \0, 압축 플래그 (1바이트, 1 = zlib), 압축 메서드 (0), 언어 태그 \0, 번역된 키워드 \0, 그 다음 텍스트.

매니페스트 스키마

{
  "v": 1,
  "what": "이 아티팩트를 설명하는 한 줄",
  "how": {
    "unpack": "존재하는 경우 sharethought:*라는 이름의 iTXt 청크를 읽습니다(매니페스트는 sharethought:manifest입니다). 그렇지 않으면 SHARETHOUGHT-v1 마커부터 EOF까지의 바이트를 읽습니다. JSON 매니페스트를 파싱한 다음, <<<SECTION:이름>>>과 <<<END:이름>>> 구분 기호 사이의 각 섹션을 파싱합니다. base64 섹션을 디코딩합니다.",
    "repack_text_only": "마커까지의 원본 PNG 바이트를 유지하고 업데이트된 매니페스트 및 섹션으로 트레일러를 다시 씁니다. 재렌더링이 필요 없습니다. 또는 실행: python3 sharethought.py repack --text FILE --set doc=new.md",
    "repack_visual": "이미지를 변경하려면: svg 섹션을 편집하고, PNG로 렌더링한 다음(rsvg-convert -w 1200 in.svg > out.png, 또는 cairosvg, 또는 resvg, 또는 Playwright를 통한 Chromium과 같은 헤드리스 브라우저), 다시 pack합니다."
  },
  "sections": [
    { "name": "svg",  "type": "image/svg+xml", "enc": "utf8",    "summary": "이미지에 대한 한 줄 설명" },
    { "name": "doc",  "type": "text/markdown", "enc": "utf8",    "summary": "문서에 대한 한 줄 설명" }
  ]
}

how 필드는 필수이며 작동 지침을 포함해야 합니다. 파일은 모든 새로운 리더에게 이를 여는 방법을 가르칩니다.

언팩

최선: python3 sharethought.py unpack file.png. 수동, 트레일러 캐리어:

raw = open("file.png", "rb").read()
# 실제 IEND까지 PNG 청크를 탐색합니다. 압축된 IDAT 바이트에 마커가 우연히 포함될 수 있으므로 raw.index()를 사용하지 마십시오.
off = 8
while True:
    import struct
    ln, typ = struct.unpack(">I", raw[off:off+4])[0], raw[off+4:off+8]
    if typ == b"IEND": break
    off += 12 + ln
trailer = raw[off + 12:].decode("utf-8")
import json
manifest, _ = json.JSONDecoder().raw_decode(trailer[trailer.index("\n")+1:])
import re
for m in re.finditer(r"<<<SECTION:(\w+)>>>\n(.*?)\n<<<END:\1>>>", trailer, re.DOTALL):
    name, body = m.group(1), m.group(2)
    # enc가 base64인 경우: import base64; body = base64.b64decode(body)

수동, 청크 캐리어 (먼저 확인):

import struct, zlib, json
raw = open("file.png", "rb").read()
off, chunks = 8, {}
while off + 8 <= len(raw):
    ln = struct.unpack(">I", raw[off:off+4])[0]
    typ = raw[off+4:off+8]
    data = raw[off+8:off+8+ln]
    if typ == b"IEND": break
    if typ == b"iTXt":
        key, _, rest = data.partition(b"\x00")
        flag = rest[0]
        rest = rest[2:]
        _, _, rest = rest.partition(b"\x00")   # 언어 태그
        _, _, rest = rest.partition(b"\x00")   # 번역된 키워드
        if flag == 1:
            rest = zlib.decompress(rest)
        chunks[key.decode()] = rest.decode("utf-8")
    off += 12 + ln
manifest = json.loads(chunks["sharethought:manifest"])
sections = {k[len("sharethought:"):]: v
            for k, v in chunks.items()
            if k.startswith("sharethought:") and k != "sharethought:manifest"}

셸만 사용: tail -c +$(( $(grep -abo 'SHARETHOUGHT-v1' file.png | head -1 | cut -d: -f1) + 1 )) file.png는 트레일러를 텍스트로 출력합니다(트레일러가 전송에서 생존한 경우에만 작동).

생성

최선: SVG를 렌더링한 다음 python3 sharethought.py pack --png out.png --svg diagram.svg --doc notes.md -o artifact.png를 실행합니다. 수동:

1. SVG를 작성합니다(사람이 보는 그림 또는 다이어그램).
2. PNG로 렌더링: rsvg-convert -w 1200 diagram.svg > out.png (또는 cairosvg diagram.svg -o out.png, 또는 resvg diagram.svg out.png, 또는 헤드리스 브라우저 — Playwright를 통한 Chromium — 종종 유일하게 설치된 SVG 렌더러).
3. 마크다운 문서를 작성합니다.
4. 트레일러를 추가하고(cat trailer.txt >> file.png 형태), 더 나은 방법으로 iTXt 청크도 작성합니다. pack은 한 번의 빌드로 둘 다 수행합니다.

출력은 일반 PNG로 렌더링됩니다. 확인: 이미지 뷰어에서 열고(이미지 표시), strings artifact.png | grep SHARETHOUGHT (트레일러가 존재함을 표시), 또는 python3 sharethought.py verify artifact.png (두 캐리어가 일치하는지 포함하여 모든 것을 확인).

재패킹

최선: python3 sharethought.py repack --text artifact.png --set doc=new.md -o out.png — 두 캐리어를 다시 쓰며 렌더러가 필요하지 않습니다.

텍스트 전용 편집 (문서 변경, 이미지 변경 없음): 원본 PNG 바이트 재사용(SHARETHOUGHT-v1 이전의 모든 것), 편집된 섹션과 업데이트된 매니페스트 요약으로 새 트레일러를 씁니다. 파일이 청크도 운반하는 경우 청크도 다시 씁니다. 레퍼런스 구현은 하나의 소스에서 둘 다 재구축하며, 이것이 일관성을 유지하는 유일한 안전한 방법입니다.

시각적 편집 (svg 변경): 수정된 SVG를 새 PNG로 렌더링한 다음 새 svg 섹션 + doc + 매니페스트로 다시 pack합니다. 모든 SVG 렌더러가 작동하며 헤드리스 브라우저도 포함됩니다.

왕복 규칙: 재패킹된 파일은 sharethought 파일입니다. 동일한 형식, 동일한 마커, 업데이트된 매니페스트.

구분 기호 안전

섹션 구분 기호는 자체 줄에 있는 <<<SECTION:이름>>> 및 <<<END:이름>>>입니다. 내용에 이러한 줄이 포함될 수 있는 경우 매니페스트에서 해당 섹션에 대해 "enc":"base64"를 설정하고 본문을 base64로 인코딩합니다. pack은 본문에 자체 종료 구분 기호 또는 마커 문자열이 포함된 경우 자동으로 이 작업을 수행합니다.

실제로 문제를 일으키는 충돌: 다른 섹션의 구분 기호를 포함하는 본문은 무해합니다. 자체 <<<END:이름>>> 줄을 포함하는 본문은 비탐욕적 정규식에 의해 잘립니다. 해당 줄 이후의 모든 것은 유실됩니다. 레퍼런스 구현은 자동으로 잘라내는 대신 이를 감지합니다(유실된 콘텐츠 및 불균형 구분 기호 오류). 확실하지 않은 경우 base64를 사용하세요.

페이로드 유지

페이로드는 PNG의 픽셀 데이터의 일부가 아니므로 이미지를 재인코딩하는 모든 도구는 페이로드를 자동으로 삭제하고 깊이가 없는 완전히 정상적인 PNG를 남길 수 있습니다. 여기에는 Pillow의 Image.open(f).save(g), 이미지 편집기, CDN 최적화 도구가 포함됩니다. 렌더링된 파일을 다시 저장하는 대신 원본 바이트에서 재패킹하세요.

IEND 이후의 트레일러는 바이트 정확 전송에서만 생존합니다. 파일이 이미지 파이프라인(채팅 첨부 파일, 썸네일러, 트랜스코더)을 통과해야 하는 경우 청크 캐리어를 사용하고(pack이 수행), PNG가 JPEG로 트랜스코딩되지 않도록 인라인 이미지가 아닌 파일로 업로드하세요.

인간과 협업

인간은 PNG — 단순화된 시각적 레이어 — 를 봅니다. 모든 깊이(SVG 소스, 문서, 매니페스트)는 캐주얼한 보기에는 보이지 않지만 완전히 존재합니다. 인간이 이미지에 대해 물으면 언팩하고 문서를 읽어 컨텍스트를 확인하세요. 인간이 그림 변경을 원하면 svg를 편집하고 시각적으로 재패킹하세요. 인간이 깊이 추가를 원하면 문서를 편집하고 텍스트 전용으로 재패킹하세요. 파일은 전체 교환입니다. 하나의 아티팩트, 두 가지 양식, 사이드 채널 없음.