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

为什么即使 contains 断言不正确,mdcode 场景测试仍然会通过?

Accepted Answer

`tests/libts/scenarios.ts` 中的断言运行器仅处理裸字符串或带有 `contains` 键的对象。但是，以列表形式编写的 YAML 条目会被解析为数组，例如 `[{ contains: "..." }]`。由于数组不满足对象检查条件，`contains` 断言会被跳过，只有 `fs.existsSync` 会执行。

临时解决方案：将断言写为映射（mapping）而不是列表：

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

永久修复：更新 `tests/libts/scenarios.ts` 以处理数组，例如添加一个 `Array.isArray(condition)` 分支并执行其中包含的每个断言。然后运行：

```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 作用域写入 catalog 条目？

Accepted Answer

这是由 `CatalogSync.push` 中的一个 bug 引起的：它接受 `validateOnly`（以及 `force`）参数，但在非 semantic-model 作用域上并不会读取它们。因此，对于 `entryGroup`、`bq-dataset` 和 `kb` 作用域，`kcmd push --validate-only` 仍会创建/更新条目并以退出码 0 退出。请升级到包含修复 "honor --validate-only in CatalogSync.push on non-semantic scopes" 的版本，或应用该补丁。在受影响的版本上，不要对这些作用域将 `--validate-only` 当作安全的 dry run；在打补丁之前，请使用临时 catalog 或只读凭证。该标志在 semantic-model 作用域上已经能正常工作。

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
```

该错误发生的原因是：当 `--target` 不带值时，CLI 解析器会为其返回布尔值 `true`，随后 `resolveTargets()` 对其调用 `.toLowerCase()`。该问题已在针对 mdcode issue #311 的 PR 中修复；请升级到包含该修复的版本，以获得正确的验证/错误处理。

Question 5

如何修复 OKF viewer 中像 /concepts/b.md 这样 bundle 相对绝对链接缺失 graph 边的问题？

Accepted Answer

这是由 `okf/src/reference_agent/viewer/generator.py` 中的 `_extract_links` 跳过所有以 `/` 开头的目标造成的，尽管此类路径是 bundle 内部的相对链接。作为变通方法，可以使用诸如 `./b.md` 这样的相对链接，它们能够正确生成边。要修复该 viewer，请停止跳过以斜杠开头的目标，并基于 `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 预览

常见问题 (5)

同类型项目

rust

ponytail

agency-agents

obsidian-skills