跳到主要内容

故障排查

先确认精确命令、完整错误文本，以及你使用的是 managed checkout 还是 source checkout。多数入门失败来自 Node.js 版本问题、runtime-home drift、缺少 provider secrets、无效 YAML 或意外的 workspace。

对于 managed install，请把 uv run demiurge 替换成：

~/.demiurge/demiurge-agent/.venv/bin/demiurge

确认命令入口​

不带 subcommand 运行 demiurge 会启动 TUI。顶层 subcommands 是：

  • init
  • doctor
  • package
  • update
  • setup
  • gateway

不带其他 setup subcommand 运行 demiurge setup 会打开 setup wizard。

TUI 无法启动​

TUI 要求 Node.js 20 或更新版本：

node --version

如果缺少 Node 或版本太旧，请安装 Node.js 20 或更新版本后重试：

uv run demiurge --provider fake

找不到命令​

对于 managed install，请使用 managed command path：

~/.demiurge/demiurge-agent/.venv/bin/demiurge --provider fake

对于 source checkout，请在仓库内通过 uv 运行命令：

uv run demiurge --provider fake

Runtime drift 或缺少 runtime files​

不写入文件，只检查：

uv run demiurge init --check
uv run demiurge doctor

只有在你确实想更新 runtime files 时才刷新 templates：

uv run demiurge init --refresh assistant

init --refresh global 只用于 global fallback config；只有当你确实想刷新所有 runtime templates 时才使用 init --refresh all。

Runtime 权限检查失败​

demiurge doctor 是只读命令。在 POSIX 上，如果 runtime home、.env、config.yaml、 SQLite file、log、state 或 artifact 不满足 Host 的 0700/0600 policy，它会报告 runtime.permissions.insecure。

先停止正在运行的 Demiurge process，检查 finding 中列出的每条 path，并确认不存在意外的 symbolic link 或 owner 变化。普通会写入的 startup/init 会只收紧 mode，不重写 file content：

uv run demiurge init
uv run demiurge doctor

如果 init 无法收紧某条 path，请先在 Demiurge 外修复其 owner/permission 再重试。不要把 列出的 runtime path 替换成 symlink；private write path 会拒绝 symlink。Windows 使用平台 ACL semantics，因此不会产生数字 POSIX mode finding。

Provider 或 API Key 失败​

检查 setup state：

uv run demiurge setup status

使用 fake provider 区分 runtime 问题和 live provider 问题：

uv run demiurge --provider fake

如果 fake 可用，请检查：

  • 选中的 provider profile 存在。
  • provider profile 有 base URL。
  • 配置的 api_key_env 已 export，或已写入 ~/.demiurge/.env。
  • 选中 core model 使用了预期 provider 和 <model-name>。

Provider resolution order 是 CLI override、core manifest、global fallback、host default，然后是 fake。

Core 或 Slot 无法加载​

运行：

uv run demiurge init --check

然后检查受影响文件：

  • agent.yaml
  • agent/pipelines.yaml
  • slot 的 slot.yaml
  • slot 的 module.py
  • tool 加载失败时，检查 authored tool tool.yaml

对照 ../reference/contracts/slot-modules.md。

Workspace 错误或 Tools 被拒绝​

在 TUI 内运行：

/status

Workspace resolution order 是 --workspace、DEMIURGE_WORKSPACE、TUI launch directory、core runtime.workspace，然后是 ~/.demiurge/workspace。

带明确 workspace 运行：

uv run demiurge --workspace /path/to/project --provider fake

Workspace 内仍然会应用 approvals 和 sensitive-path checks。

Package 安装失败​

先 preview：

uv run demiurge package install <package_id> --core assistant --preview

检查 repository 是否有：

repository.yaml
packages/<package_id>.yaml

External repositories 必须先被 trust，才能安装本地 Agent Slot code。

Telegram 不响应​

检查：

  • channels.telegram.enabled: true
  • DEMIURGE_TELEGRAM_BOT_TOKEN 已设置
  • allowed_users 或 allowed_chats 包含调用者
  • gateway 使用预期 core 运行
uv run demiurge gateway --core assistant --provider fake

手册链接损坏​

构建站点：

cd website
npm run build

Docusaurus 配置为：broken regular links 会报错，broken Markdown links 会警告。