[Bug] [ZCode Desktop 3.14.4] Agent scanner reads node_modules under ~/.zcode/agents — 170 false "agent_missing_frontmatter" warnings per session start

[cpero139]

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

UI / 界面体验 · UI / UX

涉及的 Agent 框架 · Agent framework

ZCode Agent（自研）

严重程度 · Severity

阻塞使用 · Blocking (无法使用核心功能 / core function unusable)

复现频率 · Reproducibility

必现 · Always

问题描述 · Description

环境

• ZCode Desktop 3.14.4.7912，Windows 11 x64 (build 26100)

复现步骤

1. ZCode 会在 ~/.zcode/agents/ 下安装外部 agent 运行时（claude-code、codex、gemini-cli、opencode 四个子目录），其中 claude-code/node_modules/、gemini-cli/node_modules/ 由 ZCode 自动安装管理（含 @anthropic-ai/claude-agent-sdk、@google/gemini-cli 等）。
2. 启动任意新会话（每次子代理 spawn 也会触发）。

实际行为

subagent bootstrap（模块 bootstrap.subagents）扫描 ~/.zcode/agents/ 下所有 .md 文件时没有排除 node_modules，把 npm 包的 README/LICENSE/CHANGELOG 当作 agent 定义，逐文件发出 agent_missing_frontmatter 警告。

日志示例（~/.zcode/cli/log/zcode-<date>.jsonl）：

{"level":"warn","module":"bootstrap.subagents","message":"Agent profile diagnostic","context":{"code":"agent_missing_frontmatter","path":"C:\\Users\\<user>\\.zcode\\agents\\claude-code\\node_modules\\@anthropic-ai\\sdk\\README.md"}}

本机实测：170 个唯一文件全部位于 node_modules 内，0 个是用户编写的 agent 文件；每次会话启动重复整批（单日日志中该批警告重复出现 21 次）。

期望行为

扫描 agent 定义时跳过 node_modules（以及 .bin 等依赖目录）。注意：用户无法自行移走这些运行时——~/.zcode/agents/<tool>/node_modules 是 ZCode 为外部 agent（ACP）集成自动创建和管理的。

影响

仅日志噪音（约 170 条/每次会话启动），不影响功能；但会污染日志，让真正的 agent 配置告警难以被发现。

复现步骤 · Steps to reproduce

1. ZCode 会在 ~/.zcode/agents/ 下安装外部 agent 运行时（claude-code、codex、gemini-cli、opencode 四个子目录），其中 claude-code/node_modules/、gemini-cli/node_modules/ 由 ZCode 自动安装管理（含 @anthropic-ai/claude-agent-sdk、@google/gemini-cli 等）。
2. 启动任意新会话（每次子代理 spawn 也会触发）。

期望表现 · Expected behavior

扫描 agent 定义时跳过 node_modules（以及 .bin 等依赖目录）。注意：用户无法自行移走这些运行时——~/.zcode/agents/<tool>/node_modules 是 ZCode 为外部 agent（ACP）集成自动创建和管理的。

实际表现 · Actual behavior

subagent bootstrap（模块 bootstrap.subagents）扫描 ~/.zcode/agents/ 下所有 .md 文件时没有排除 node_modules，把 npm 包的 README/LICENSE/CHANGELOG 当作 agent 定义，逐文件发出 agent_missing_frontmatter 警告。

ZCode 版本 · ZCode version

3.14.4.7912

设备 / 系统 / 浏览器 · Device / OS / Browser

Windows 11 x64 (build 26100)

截图 / 录屏 / 日志 · Screenshots / Recordings / Logs

日志样例（~/.zcode/cli/log/zcode-2026-10-04.jsonl，module bootstrap.subagents）：

{"timestamp":"2026-10-04T08:36:26.638Z","level":"warn","module":"bootstrap.subagents","message":"Agent profile diagnostic","context":{"code":"agent_missing_frontmatter","path":"C:\Users\\.zcode\agents\claude-code\node_modules\@Anthropic-AI\sdk\README.md"}}

统计：单日日志中 170 个唯一被警告文件 100% 位于 node_modules 内（npm 包 README/LICENSE/CHANGELOG），0 个为用户编写的 agent 定义；同一批警告随每次会话启动重复出现 21 次。

[github-actions]

👋 感谢你的反馈，我们已经收到。

• 维护者看到后会尽快回复你。
• 状态保持为 status: 待评估，你可以随时补充信息。
• 信息不全时我们会打上 needs: 更多信息 标签并 @ 你。

---

👋 Thanks — we've received your issue.

• A maintainer will get back to you as soon as we can.
• Status stays at status: 待评估 (Triage); feel free to add context.
• If we need more details, we'll add needs: 更多信息 and ping you.