[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 新手友好度
- 25/100
- Issue 類型
- 缺陷
- 描述清晰度
- 描述清楚
- 活躍度
- 活躍
- 技術堆疊
- javascript, yaml
- 領域
- tooling
研究方向
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.
由索引模型根據 Issue 內容生成。
描述
说明:这是 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 侧受此缺陷影响。
- 主要語言
- Python
- 星號
- 152
- 分支
- 137
- PR 合併指標
- 30 天內沒有已合併 PR
環境準備
- 沒有 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
zai-org/zcode-plugins 的其他 Issue
-
難度 2/5 1-3 小時 新手友好度 83/100
zai-org/zcode-plugins#202 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 76/100
zai-org/zcode-plugins#107 ·
維護者通常 1 天內回覆
-
難度 1/5 1 小時以內 新手友好度 85/100
zai-org/zcode-plugins#106 ·
維護者通常 1 天內回覆
-
video-agent-kit (0.4.3): hooks invoke python3, which doesn't exist on Windows — SessionStart/UserPromptSubmit/Stop hooks fail on every trigger可能已有人在做 @dvd233 於 57 天前認領。 未關閉
難度 2/5 1-3 小時 新手友好度 85/100
zai-org/zcode-plugins#14 ·
維護者通常 1 天內回覆
-
難度 4/5 3-5 天 新手友好度 28/100
zai-org/zcode-plugins#193 · 2 則留言 ·
維護者通常 1 天內回覆
查看 zai-org/zcode-plugins 的全部 Issue
相似的 Issue
-
CI flake: test-windows times out spawning Node in tests/test_antigravity_node_hooks.py (develop red)未關閉area/ci P2
難度 2/5 1-3 小時 新手友好度 68/100
維護者通常 2 天內回覆
-
benchmark
難度 1/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 79/100
-
難度 2/5 1-3 小時 新手友好度 77/100
mozilla-ai/cq#601 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 68/100
維護者通常 1 天內回覆