[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失

Offen
#194 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

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 解析链上。

最小复现

  1. ~/.zcode/agents/repro.md 写入上述 frontmatter(块标量 description)
  2. 新开 ZCode 会话,让主模型引用可用 agent 列表中 repro 的 description
  3. 实际得到 >- / | 字面量;期望得到折叠后的完整描述文本

期望行为

按 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

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus zai-org/zcode-plugins

Alle Issues in zai-org/zcode-plugins

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.