[平台bug] Agent 定义 YAML 块标量 description 不被解析:注册表显示字面量 |/>-,多行内容静默丢失
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 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 ファイルなし
- プルリクエストのテンプレートあり
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- 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
-
opensubtitlescom: provider rejects pt-PT even though its own converter maps it対応中かも @paulo-0308 が今日担当しました。 オープン
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
Diaoul/subliminal#1405 ·
-
Internal Errorオープンbug
難易度 2/5 1〜3時間 初心者へのやさしさ 66/100
frappe/frappe_docker#2071 ·
メンテナーはふだん 1 日以内に返信
-
bug python
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
traceloop/openllmetry#4717 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
The-Pocket/PocketFlow#161 ·
-
comp/desktop P2 type/bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
NousResearch/hermes-agent#157702 ·
メンテナーはふだん 1 日以内に返信