[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Aptitud para principiantes
- 25/100
- Tipo de issue
- Error
- Claridad
- Bien especificado
- Estado de actividad
- Activo
- Stack tecnológico
- javascript, yaml
- Área
- tooling
Línea de trabajo
The bug lives in the platform build, not in this repo: the reporter points at parseLooseFrontmatter (byte offset 1085045 in zcode.cjs) and parseScalarValue (1086508), where a description: >- value is unquoted to the literal >- and the indented lines fall through both the list-item and key:value regexes. Start by reproducing with a user-level agent file such as ~/.zcode/agents/repro.md containing the sample frontmatter, then locate the same functions by name in the platform source, since offsets shift between builds. Done means |/> indicators are collected per YAML semantics (or the embedded YAML parser at offset ~7395989 is used), plus the empty-value-plus-indented-lines case no longer raising agent_missing_required_frontmatter. Because the fix belongs to zai-org/ZCode, this issue mostly needs a maintainer hand-off first.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
说明:这是 ZCode 平台 bug(非本仓插件问题)。主仓 zai-org/ZCode 的 issue 区已关闭,故投此处,烦请维护者转交平台团队。
环境
- ZCode 桌面版 3.18.2 / CLI 0.17.1(Windows)
- 影响范围:用户级 agent 定义(
~/.zcode/agents/*.md)与插件自带 agent 定义(agents/*.md)均受影响
现象
agent 定义文件的 frontmatter 使用 YAML 块标量写法时:
---
name: my-agent
description: >-
Delegates to this agent when the user asks about X,
or needs help with Y.
tools: [Read]
---
新会话的可用 agent 列表中,该 agent 的 description 显示为字面量 >-(| 写法同理显示 |),后续缩进行的实际内容全部丢失。模型无法基于 description 做自动委派路由,该 agent 仅能点名调用。
单行 description(包括双引号单行字符串)显示正常。
根因(逆向定位,附证据)
zcode.cjs 中 agent 定义不走 YAML 库,走自写的逐行宽松解析器(函数自标注名 parseLooseFrontmatter,本机构建 zcode.cjs 字节偏移 1085045;偏移随构建变化,可按函数名搜索):
| minified 名 | 代码内自标注名 | 本机偏移 |
|---|---|---|
| sLr | splitMarkdownFrontmatter | 1084515 |
| mPs | parseLooseFrontmatter | 1085045 |
| iLr | parseScalarValue | 1086508 |
| yie | parseAgentProfileFromMarkdown | 1087927 |
mPs 的 key:value 正则(偏移 1085447 起):
let h=u.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/u);
...
o[_]=iLr(v,_==="mcpServers")
description: >- 中 >- 作为 v 传入 iLr,非引号/数组/布尔/数字,gfn(unquoteScalar)原样返回 ">-";块标量的后续缩进行既不匹配列表项也不匹配 key:value 正则,被静默跳过。
用户级 agent 注册与插件 agent 加载汇入同一解析器(loadAgentDefinitions,本机偏移 14788011),两种来源同时受影响。
另:zcode.cjs 偏移 7395989 附近存在完整内嵌 YAML 解析器(%YAML/%TAG directive、版本校验),但不在 agent 解析链上。
最小复现
~/.zcode/agents/repro.md写入上述 frontmatter(块标量 description)- 新开 ZCode 会话,让主模型引用可用 agent 列表中 repro 的 description
- 实际得到
>-/|字面量;期望得到折叠后的完整描述文本
期望行为
按 YAML 规范解析块标量:> 系折叠为空格连接,| 系保留换行;或至少识别到块指示符时告警,而非静默丢弃内容。
修复建议
mPs 的 key:value 分支识别值为 |/|-/|+/>/>-/>+ 时进入块标量收集模式(消费后续更深缩进行,按 folded/literal 语义拼接);或 agent 解析链改用已有的内嵌 YAML 解析器。
次生 case:description: 空值后换行缩进(无块指示符)时,description 被解析为空数组并触发 agent_missing_required_frontmatter 报错——块标量收集模式可一并覆盖。
临时规避(已验证)
把 description 改写为单行双引号标量即可正常解析,内容可零漂移转换(YAML round-trip 等价验证)。官方插件 plugin-dev / pr-review-toolkit 自带的 agent 定义(agent-creator、plugin-validator、skill-reviewer、code-simplifier)使用块标量写法,同样受影响——它们在 Claude Code 侧解析正常,只有 ZCode 侧受此缺陷影响。
- Lenguaje dominante
- Python
- Estrellas
- 152
- Forks
- 137
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Preparar el entorno
- Sin Dockerfile ni archivo de Docker Compose
- Tiene una plantilla de pull request
- Leer la guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de zai-org/zcode-plugins
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 83/100
zai-org/zcode-plugins#202 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
zai-org/zcode-plugins#107 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 1/5 Menos de una hora Aptitud para principiantes 85/100
zai-org/zcode-plugins#106 ·
Los mantenedores suelen responder en 1 día
-
video-agent-kit (0.4.3): hooks invoke python3, which doesn't exist on Windows — SessionStart/UserPromptSubmit/Stop hooks fail on every triggerPosiblemente ocupada @dvd233 la tomó hace 57 días. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 85/100
zai-org/zcode-plugins#14 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 4/5 3-5 días Aptitud para principiantes 28/100
zai-org/zcode-plugins#193 · 2 comentarios ·
Los mantenedores suelen responder en 1 día
Todos los issues de zai-org/zcode-plugins
Issues similares
-
opensubtitlescom: provider rejects pt-PT even though its own converter maps itPosiblemente ocupada @paulo-0308 la tomó hoy. Abierto
Dificultad 1/5 Menos de una hora Aptitud para principiantes 88/100
Diaoul/subliminal#1405 ·
-
Internal ErrorAbiertobug
Dificultad 2/5 1-3 horas Aptitud para principiantes 66/100
frappe/frappe_docker#2071 ·
Los mantenedores suelen responder en 1 día
-
bug python
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
traceloop/openllmetry#4717 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
The-Pocket/PocketFlow#161 ·
-
[Bug]: Webapp workspace fails to render in Safari — "Can't find variable: requestIdleCallback"Abiertocomp/desktop P2 type/bug
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
NousResearch/hermes-agent#157702 ·
Los mantenedores suelen responder en 1 día