[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失
Maintainer antworten meist innerhalb von 1 Tag
Dieses Issue hat noch niemand übernommen.
Bewertung
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Anfängerfreundlichkeit
- 25/100
- Issue-Typ
- Bug
- Klarheit
- Klar beschrieben
- Aktivitätsstatus
- Aktiv
- Tech-Stack
- javascript, yaml
- Bereich
- tooling
Rechercherichtung
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.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
说明:这是 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 侧受此缺陷影响。
- Vorherrschende Sprache
- Python
- Sterne
- 152
- Forks
- 137
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Entwicklungsumgebung
- Kein Dockerfile und keine Docker-Compose-Datei
- Hat eine Pull-Request-Vorlage
- Beitragsleitfaden lesen
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus zai-org/zcode-plugins
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 83/100
zai-org/zcode-plugins#202 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 76/100
zai-org/zcode-plugins#107 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 85/100
zai-org/zcode-plugins#106 ·
Maintainer antworten meist innerhalb von 1 Tag
-
video-agent-kit (0.4.3): hooks invoke python3, which doesn't exist on Windows — SessionStart/UserPromptSubmit/Stop hooks fail on every triggerEvtl. vergeben @dvd233 hat das vor 57 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 85/100
zai-org/zcode-plugins#14 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 4/5 3-5 Tage Anfängerfreundlichkeit 28/100
zai-org/zcode-plugins#193 · 2 Kommentare ·
Maintainer antworten meist innerhalb von 1 Tag
Alle Issues in zai-org/zcode-plugins
Ähnliche Issues
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 77/100
mozilla-ai/cq#601 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 68/100
Maintainer antworten meist innerhalb von 1 Tag
-
intcomma returns exponential notation for large floatsEvtl. vergeben @Omarinho12345 hat das heute übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 72/100
python-humanize/humanize#521 ·
Maintainer antworten meist innerhalb von 1 Tag
-
LUCJ pass manager raises NoEdgeBetweenNodes when an edge is bad for two two-qubit gatesEvtl. vergeben @hat-im hat das heute übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 76/100
Maintainer antworten meist innerhalb von 1 Tag
-
opensubtitlescom: provider rejects pt-PT even though its own converter maps itEvtl. vergeben @paulo-0308 hat das heute übernommen. Offen
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 88/100
Diaoul/subliminal#1405 ·