[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 25/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- javascript, yaml
- Domain
- tooling
Research direction
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.
Written by the indexing model from the issue text.
Description
说明:这是 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 侧受此缺陷影响。
- Dominant language
- Python
- Stars
- 152
- Forks
- 137
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from zai-org/zcode-plugins
-
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
zai-org/zcode-plugins#202 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
zai-org/zcode-plugins#107 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
zai-org/zcode-plugins#106 ·
Maintainers usually reply within 1 day
-
video-agent-kit (0.4.3): hooks invoke python3, which doesn't exist on Windows — SessionStart/UserPromptSubmit/Stop hooks fail on every triggerPossibly taken @dvd233 claimed this 57 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
zai-org/zcode-plugins#14 ·
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 28/100
zai-org/zcode-plugins#193 · 2 comments ·
Maintainers usually reply within 1 day
All issues in zai-org/zcode-plugins
Similar issues
-
opensubtitlescom: provider rejects pt-PT even though its own converter maps itPossibly taken @paulo-0308 claimed this today. Open
Difficulty 1/5 Under an hour Newbie friendliness 88/100
Diaoul/subliminal#1405 ·
-
Internal ErrorOpenbug
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
frappe/frappe_docker#2071 ·
Maintainers usually reply within 1 day
-
bug python
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
traceloop/openllmetry#4717 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
The-Pocket/PocketFlow#161 ·
-
comp/desktop P2 type/bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
NousResearch/hermes-agent#157702 ·
Maintainers usually reply within 1 day