Question 1

为什么我的 SKILL.md 在 skills API 中显示空的名称和描述（UTF-8 BOM 问题）？

Accepted Answer

文件被保存为"UTF-8 with BOM"——这在 Windows 记事本或 PowerShell 5.1 的 `Set-Content -Encoding UTF8` 中很常见。位于起始 `---` 分隔符之前的不可见 BOM 字符（U+FEFF）导致 frontmatter 解析器无法检测到 YAML 块，因此整个文件被当作正文处理，name/description 显示为空。

修复方法：该问题已在 `develop` 分支上解决。共享的 frontmatter 辅助函数（`src/octop/infra/utils/frontmatter.py::parse_frontmatter`）现在会在扫描 `---` 分隔符之前先去除单个开头的 U+FEFF，并且 skills 路由器（`src/octop/api/routers/skills.py`）已整合为使用此共享解析器，而不再使用其本地的 `_parse_frontmatter`。

旧版本的临时解决方法：将 SKILL.md 重新保存为*不带* BOM 的 UTF-8（例如，在 VS Code 的状态栏编码菜单中选择"UTF-8"而不是"UTF-8 with BOM"），或者在解析之前使用 `text.lstrip('\ufeff')` 以编程方式移除 BOM。

Question 2

如何修复 Octop LDAP 错误 "enabling LDAP over ldap:// requires StartTLS; otherwise use an ldaps:// URL"？

Accepted Answer

这是 Octop（`infra/auth/ldap/config.py`）中一项有意设置的安全限制，而不是 bug：明文 `ldap://` 被阻止，以避免密码以明文形式传输，并且安全设置中没有用于禁用该限制的开关。解决方法：1) 将服务器 URL 更改为 `ldaps://`（例如 `ldaps://192.168.1.1:636`），并在你的 Windows AD 域控制器上启用 LDAPS；或者 2) 在 AD 服务器上启用 StartTLS，并在 Octop 的 LDAP 配置中打开 StartTLS 选项，同时保持使用 `ldap://192.168.1.1:389`。如果你需要一个明确的“允许不安全明文”的应急出口，请提交功能请求。

Question 3

如何修复当 agent 在未使用 ripgrep 的情况下运行文件系统搜索时出现的 octop 内存溢出（OOM）问题？

Accepted Answer

这是 octop 1.0.1（deepagents 0.7.9）中的一个已知 bug：当 PATH 上没有 ripgrep（`rg`）时，未限定作用域的 grep 搜索会回退到纯 Python 搜索，从 `/` 开始遍历，并以无上限的 `readline()` 读取 `/proc/<pid>/pagemap` 之类的伪文件，最终耗尽宿主机内存。修复与缓解措施：

1. **升级到 octop v1.0.2+** —— 由 PR #2116 修复：官方镜像现在自带 ripgrep（以可被终止的子进程方式运行），并且 `OctopServer.start()` 会对 deepagents 的 `_python_search` 打补丁，跳过 `/proc`、`/sys`、`/dev`，并限制每行/每个文件的读取大小。

2. **在容器中安装 ripgrep** —— 将静态 `rg` 二进制文件加入 PATH，这样就不会再走 Python 回退路径。

3. **设置容器内存限制** —— 例如 `docker run --memory=4g ...`，这样内核 OOM 时只会终止容器，而不会波及整个宿主机。

4. **限制 `backend.root_dir`** —— 避免使用默认的 `root_dir='/'`，因为它会让 agent shell 访问整个宿主机文件系统。

Question 4

如何修复在 langgraph Postgres checkpointer 中使用 psycopg ConnectionPool 时出现的 "AdminShutdown: terminating connection due to administrator command" 错误？

Accepted Answer

该错误发生的原因是 psycopg_pool 的 `ConnectionPool` 默认为 `check=None`（无活性探测），因此当 `max_lifetime`（默认 3600 秒）回收与并发的 `getconn()` 调用恰好同时发生时，一个已终止的连接会被交给调用者，导致 `execute()` 发生致命失败。修复方法：使用显式的活性检查和显式的 max_lifetime 来构建连接池。

```python
from psycopg_pool import ConnectionPool

def _check_conn(conn):
    conn.execute("SELECT 1")

pool = ConnectionPool(
    conninfo=dsn,
    min_size=1,
    max_size=4,
    check=_check_conn,        # 在分发连接之前探测并丢弃失效连接
    max_lifetime=3600,        # 显式设置；考虑使其低于 PG/服务器端超时时间
    kwargs={"autocommit": True, "prepare_threshold": 0, "row_factory": dict_row},
    open=True,
)
```

`check` 回调会在连接被分发出去之前运行 `SELECT 1`；失效的连接会被检测到、丢弃并以透明方式重建。作为额外的加固措施，可在 `PostgresSaver`/`get_tuple` 的执行路径上包装针对 `psycopg.errors.AdminShutdown`（或 `OperationalError`）的重试逻辑，这样单个失效连接就不会对任务造成致命影响。此问题影响在并发类 cron 工作负载下使用 langgraph Postgres checkpointer 的 psycopg 3.x / psycopg_pool 3.3.x 环境。

Question 5

如何修复 Octop 回复以 {"matches":...} 记忆 JSON 开头导致 WeChat 发送失败（ret=-2 prepare failed）的问题？

Accepted Answer

根本原因：当 cron 提示要求 agent 调用 memory_save 时，模型首先尝试编辑 MEMORY.md，被 FilesystemGuard 阻止，随后回退到 memory 工具链。内部协调 JSON（来自 octop_memory/operations/retention.py 的 {"matches":[{"atom_id",...}]}）进入主对话上下文，模型在最终回复开头原样复述了它（已在 glm-5.3-flash 和 glm-4.6 上复现，与模型无关）。膨胀的内容（最多约 ~220k 字符）被 WeChat 渠道拆分成约 ~2000 字符的分段，触发限流 'ret=-2, errmsg=prepare failed' 并导致消息丢失。已验证的变通方案（自托管）：1）在 agent 配置中设置 "memory_recall_inject_enabled": false，禁用自动 <memory-context> 注入，该注入还会向渠道泄露 atom_id 和 recall 元数据。2）重写 cron/自动化提示以避免使用 memory_* 工具；改为在普通工作区文件中记录历史（例如读写 dinner-log.md）。完成这两项更改后，同一 cron 任务产生干净的输出（400 字符以内的标准格式，单段发送）。长期修复需要 reconcile JSON 保留在 memory 服务内部、recall 注入渲染为不含 atom_id 的纯摘要，以及渠道层对注入的块和异常长的内容进行过滤/截断。

Octop

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐