Question 1

markitdown 파서가 Markdown, 텍스트 및 JSON 파일 시작 부분에 UTF-8 BOM (U+FEFF)을 유지하는 문제를 해결하는 방법?

Accepted Answer

버그는 `hindsight_api/engine/parsers/markitdown.py`의 `MarkitdownParser._utf8_stream_info` 메서드에 있습니다. 이 메서드는 markitdown에 `StreamInfo(charset="utf-8")`을 전달하는데, Python의 `utf-8` 코덱이 바이트 순서 표시(BOM)를 그대로 유지하기 때문에 markitdown 자체의 BOM 제거 감지 로직이 우회됩니다. 수정 방법: BOM이 있는 경우 charset 힌트를 `utf-8-sig`로 변경합니다:

```python
StreamInfo(charset="utf-8-sig" if data.startswith(codecs.BOM_UTF8) else "utf-8")
```

여기서 `data`는 UTF-8 탐지에 이미 사용된 `bytes(file_data)`입니다. BOM이 없는 파일은 기존과 동일한 `utf-8` 힌트를 유지합니다. CSV, HTML 및 `.ipynb` 파일은 해당 변환기가 이미 이 표시를 제거하므로 영향을 받지 않습니다. 수정 사항과 `tests/test_markitdown_parser.py`의 테스트 네 개가 포함된 준비된 커밋은 github.com/L4XB/hindsight/commit/49ac70ea56e0a862a2cec69d77accfb624422f78에서 확인할 수 있습니다.

Question 2

왜 각 MCP 도구 호출이 Hindsight에서 중복된 audit_log 행 두 개를 기록하나요?

Accepted Answer

이것은 FastMCP 3.x와 함께 사용되는 Hindsight v1.1.0의 알려진 버그입니다: `_apply_audit_logging`(hindsight_api/mcp_tools.py)이 FastMCP 인스턴스의 `call_tool`을 대체하지만, FastMCP 3.2.0의 미들웨어 체인이 내부적으로 `self.call_tool`(감사가 적용된 래퍼)을 다시 호출하여 두 번째 중첩 `AuditEntry`를 엽니다. 이로 인해 도구 자체는 한 번만 실행되지만 `destructive_op` 및 `mcp tool=…` 로그 라인이 두 배로 출력됩니다. 수정 방법: PR #6142가 포함된 빌드로 업그레이드하세요(`main`에서 수정됨, 커밋 1e3a4841a7ee) — 동시성 환경에서도 호출당 정확히 1개의 행이 생성되는 것이 확인되었습니다. 패치된 버전을 유지 관리하는 경우 해결 방법은 다음과 같습니다: (1) 미들웨어가 없는 내부 호출이 감사 없이 통과하도록 허용: `if kwargs.get("run_middleware") is False: return await original_call_tool(name, arguments, **kwargs)`; 또는 (2) `call_tool`을 대체하는 대신 감사를 FastMCP 미들웨어로 구현합니다. 수정 확인: 단일 MCP 호출 후 `GET /v1/default/banks/<bank>/audit-logs?transport=mcp`로 확인하세요.

Question 3

OpenCode 2만 설치되어 있을 때 Hindsight survey가 실행되지 않는 이유는 무엇인가요 (surveyDocs가 0으로 유지됨)?

Accepted Answer

근본 원인: `@vectorize-io/hindsight-coding-agents` 0.8.2에서 `src/core/survey.ts`의 survey fallback 버전 probe가 `Number(/(\d+)\./.exec(out)?.[1] ?? 0) >= 1`을 사용하므로, 안정 버전의 OpenCode 2(예: `opencode v2.1.2`)가 survey 수행이 가능한 runner로 잘못 허용됩니다. OpenCode 2 어댑터는 의도적으로 `hindsight-survey` 에이전트를 등록하지 않으므로, survey가 `AgentNotFoundError: hindsight-survey`로 실패하고 구조적 findings가 전혀 수집되지 않습니다. 수정 방법: 조건식을 엄격한 `major === 1`로 변경합니다(이렇게 하면 `1.18.9` / `opencode v1.18.9`는 계속 대상으로 유지되고 `2.1.2`와 `0.0.0-beta-*`는 제외됩니다). 그러면 lease가 획득되기 전에 OpenCode 2가 건너뛰어지고 fallback 루프가 다음 지원 CLI를 선택할 수 있습니다. `src/core/survey.test.ts -t 'reads `opencode --version`'`으로 검증했습니다(5개 통과). 패치 없이 우회하는 방법: (1) Claude Code, Codex 또는 Antigravity CLI와 같은 지원되는 V1 survey runner를 PATH에 설치합니다. (2) 읽기 전용 survey 에이전트를 수동으로 구성하고 survey를 단독으로 실행하여 네 개의 survey 문서를 수집합니다.

Question 4

codex가 codex.exe로 설치된 경우 Hindsight codebaseSurvey가 Windows에서 시작되지 않는 이유는 무엇이며, 어떻게 해결할 수 있나요?

Accepted Answer

`@vectorize-io/hindsight-coding-agents` v0.8.1에서 `binOnPath`/`resolveAgentBin()`은 POSIX 시맨틱을 가정합니다: (1) 단독 명령어 이름은 `PATHEXT`를 적용하지 않고 `join(dir, bin)`으로만 검사되므로, `codex.exe`만 제공하는 Windows 설치는 절대 발견되지 않습니다; (2) forward-slash 경로만 경로로 인식되므로(`bin.includes("/")`), `HINDSIGHT_CODEX_BIN`에 지정된 `C:\...\codex.exe`와 같은 backslash 절대 경로는 단독 이름으로 처리되어 실패합니다; (3) `accessSync(..., X_OK)`는 디렉터리도 허용합니다. 다른 하네스(`claude-code`, `antigravity-cli`, `opencode`)를 사용할 수 없는 경우 `startCodebaseSurvey()`가 조용히 false를 반환하고 survey가 시작되지 않습니다. 우회 방법: FORWARD slash를 사용하여 `HINDSIGHT_CODEX_BIN`을 실제 실행 파일로 설정하세요. 예: `setx HINDSIGHT_CODEX_BIN "C:/Users/<you>/AppData/Roaming/npm/codex.exe"` — backslash 경로는 탐지에 실패할 뿐만 아니라 codex `-c` TOML 값에 그대로 삽입되어 `codex exec`가 ~137ms 만에 exit 1로 종료됩니다. 또는 지원되는 다른 하네스를 설치하거나 단독 `codex`를 PATH에 추가하세요. 참고: upstream도 `shell:false`로 spawn하므로 `.cmd`/`.bat` shim은 EINVAL로 실패합니다 — `.exe`를 직접 지정하세요.

Question 5

OpenCode v2.1.0에서 @vectorize-io/hindsight-coding-agents v0.8.1을 로드할 때 발생하는 'failed to load plugin' SchemaError(Expected object at "default")를 해결하는 방법은?

Accepted Answer

OpenCode v2.1.0의 플러그인 호스트는 `Bun.resolveSync`를 통해 패키지 디렉터리를 해석하는데, 이 과정에서 `package.json`의 `exports`/`main`을 따라 `dist/index.js`(v1 함수 엔트리포인트)를 로드하며, v2 객체 스키마가 이를 거부합니다. 해결 방법: `~/.hindsight/coding-agents/package.json`을 편집하여 `"main"`과 `"exports"."."`를 모두 `./index.js`(`{id, setup}`를 내보내는 v2 객체 엔트리포인트)를 가리키도록 수정합니다. `Bun.resolveSync(<dir>)`로 확인하세요 — `index.js`로 해석되어야 하며 기본 내보내기는 `{id, setup}`이어야 합니다. 변경 후 플러그인이 로드되고 도구(`hindsight_recall`, `hindsight_retain`, `hindsight_reflect`)를 등록합니다. 참고: 이 패치는 다음 `npx` 업데이트 시 덮어씌워지므로, 패키지 유지관리자가 업스트림에서 엔트리포인트 exports를 수정할 때까지의 임시 조치입니다.

hindsight

주요 기능

할 수 없는 것

사용 사례

태그

시작하기

유사한 프로젝트