Question 1

왜 `kcmd init`은 403으로 실패하는데도 종료 코드 0으로 종료되나요?

Accepted Answer

이 문제는 `src/tool/main.ts`가 `commands.init()`이 반환하는 종료 코드를 무시하기 때문에 발생합니다. `await commands.init(options);`를 다음과 같이 교체하세요:

```ts
const exitCode = await commands.init(options);
process.exit(exitCode);
```

이는 `pull`과 `push`가 이미 종료 코드를 처리하는 방식과 일치합니다. 수정 후에는 `Error: failed to create entry group ...: 403`과 같은 실패가 발생하면 상태 `1`로 종료되므로, `kcmd init && kcmd push`와 같은 CI 명령이 계속 진행되지 않고 중단됩니다. 수정 사항이 포함된 릴리스로 업데이트하거나 위의 패치를 적용하세요.

Question 2

왜 mdcode 시나리오 테스트에서 `contains` 어설션이 잘못되었는데도 통과하는 건가요?

Accepted Answer

`tests/libts/scenarios.ts`의 assertion runner는 단일 문자열 또는 `contains` 키를 가진 객체만 처리합니다. 그러나 목록 형태로 작성된 YAML 항목은 배열로 파싱됩니다(예: `[{ contains: "..." }]`). 배열은 객체 검사를 통과하지 못하므로 `contains` assertion이 건너뛰어지고 `fs.existsSync`만 실행됩니다.

즉시 적용 가능한 해결 방법: assertion을 목록 대신 매핑으로 작성하세요:

```yaml
catalog/e1.yaml:
  contains: "name: e1"
```

영구적인 수정: `tests/libts/scenarios.ts`가 배열을 처리하도록 업데이트하세요. 예를 들어 `Array.isArray(condition)` 분기를 추가하여 포함된 각 assertion을 실행합니다. 그런 다음 실행하세요:

```bash
npm test
```

일시적으로 불가능한 기대값을 설정하여 수정을 확인하세요. 이제 테스트는 통과하는 대신 실패해야 합니다. 이러한 검사를 활성화하면 기존의 잘못된 기대값도 드러나는데, 예를 들어 `pull_bq.yaml`은 실제 값이 `name: p.d/t1`인데 `name: p.d.t1`을 기대하고 있습니다. 이러한 fixture 기대값은 별도로 수정해야 합니다.

Question 3

`kcmd push --validate-only`가 entryGroup, bq-dataset 또는 kb 스코프에 대한 카탈로그 항목을 여전히 작성하는 이유는 무엇인가요?

Accepted Answer

이 문제는 `CatalogSync.push`의 버그로 인해 발생합니다: 이 함수는 `validateOnly`(및 `force`)를 받아들이지만 비시맨틱 모델 스코프에서는 이를 읽지 않습니다. 따라서 `kcmd push --validate-only`는 `entryGroup`, `bq-dataset`, `kb` 스코프에서도 여전히 항목을 생성/업데이트하고 종료 코드 0으로 끝납니다. "honor --validate-only in CatalogSync.push on non-semantic scopes" 수정이 포함된 릴리스로 업그레이드하거나 해당 패치를 적용하세요. 영향을 받는 버전에서는 이러한 스코프에 대해 `--validate-only`를 안전한 드라이 런으로 간주하지 마세요. 패치가 적용될 때까지 스크래치 카탈로그 또는 읽기 전용 자격 증명을 사용하세요. 이 플래그는 시맨틱 모델 스코프에서는 이미 올바르게 작동합니다.

Question 4

`kcmd push --target` 실행 시 "(target ?? DEFAULT_TARGET).toLowerCase is not a function" 오류를 해결하는 방법

Accepted Answer

플래그만 단독으로 사용하는 대신 유효한 target 값을 전달하세요:

```bash
kcmd push --target <target>
```

또는 `--target`을 생략하여 기본 target을 사용하세요:

```bash
kcmd push
```

이 오류는 CLI 파서가 값이 없는 `--target`에 대해 boolean `true`를 반환하고, 이어서 `resolveTargets()`가 해당 값에 대해 `.toLowerCase()`를 호출하기 때문에 발생합니다. 이 문제는 mdcode issue #311에 대한 PR에서 수정되었습니다. 올바른 유효성 검사/오류 처리를 위해 해당 수정 사항이 포함된 릴리스로 업그레이드하세요.

Question 5

OKF viewer에서 /concepts/b.md와 같은 번들 기준 절대 링크의 누락된 그래프 엣지를 어떻게 수정하나요?

Accepted Answer

이는 `okf/src/reference_agent/viewer/generator.py`의 `_extract_links`가 `/`로 시작하는 모든 대상을 건너뛰기 때문에 발생합니다. 이러한 경로는 내부 번들 상대 링크임에도 불구하고 말입니다. 임시 해결 방법으로 `./b.md`와 같은 상대 링크를 사용하면 엣지가 올바르게 생성됩니다. 뷰어를 수정하려면 선행 슬래시 대상을 건너뛰는 것을 중단하고 `bundle_root`를 기준으로 해석하세요:

```python
if "://" in target:
    continue
if target.startswith("/"):
    resolved = (bundle_root / target.lstrip("/")).resolve()
else:
    resolved = (doc_dir / target).resolve()
```

`bundle_root`가 `_extract_links`에서 사용 가능한지 확인하세요. 필요한 경우 함수에 전달하세요. `"://"` 검사는 여전히 외부 URL을 제외합니다.

knowledge-catalog

개요

README 미리보기

FAQ (5)

同类型项目

rust

ponytail

agency-agents

obsidian-skills