Repository navigation
[feat] 支持 ZCode（skills/subagents/hooks/MCP 自动分发） #461
Description
Problem（问题）
ZCode（Z.ai 的 agent 编码工具）已在我们团队实际使用，但 teamai-cli 尚未将其作为内置工具目标：
teamai status/teamai doctor/teamai hooks list无法识别 ZCode- 不会向 ZCode 注入生命周期 hooks → 会话启动无法自动
teamai pull，团队资源更新依赖成员手动同步 - skills / subagents / MCP 均无法自动分发
ZCode 实测结论（供实现参考）
我们逆向并实测了 ZCode 桌面版（Windows）的资源约定：
- 用户级 skills：
~/.zcode/skills/（同时读取中央~/.agents/skills/，该目录已被现有agentscentral 条目覆盖） - 用户级 subagents：
~/.zcode/agents/*.md（Claude 风格 frontmatter Markdown；项目级为<project>/.zcode/agents/）。桌面端「子智能体」设置页读写的就是这些文件，已实测双向确认 - 用户级 MCP：
~/.agents/mcp.json（mcpServers键，Claude 兼容结构，桌面端 MCP 设置页读取） - Hooks：与 Claude Code 几乎同构（
SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/Stop等事件同名，模板变量兼容${CLAUDE_PROJECT_DIR}），但有三个关键差异：- 用户级配置在
~/.zcode/cli/config.json（与插件状态共享的文件），钩子嵌套于hooks.events，且被hooks.enabled门控——配置文件钩子默认禁用，写入方必须强制置true - 钩子条目支持
process类型（argv 向量，不走 shell）。Windows 下若用 shell 字符串bash -lc ...，PATH 解析可能命中 WSL 的bash.exe而非 Git Bash，导致钩子静默失效——应优先process类型 - matcher 是大小写敏感正则：
*是非法模式永不匹配，通配必须省略 matcher
- 用户级配置在
Proposed Solution（建议方案）
我们已在 fork 实现并内部试用通过（分支 feat/zcode-support，13 个文件 +324/-5，结构与 #420 Qoder 支持同构）：
KNOWN_AGENTS/ 默认toolPaths注册zcode：skills →.zcode/skills，agents →.zcode/agents，settings →.zcode/cli/config.json，mcp →.agents/mcp.json- 新增 zcode hook format：merge 进共享 config.json（保留插件状态等无关键）、强制
hooks.enabled: true、process 类型条目、通配省略 matcher - coauthor 排除 zcode（无文档化 attribution 配置项）
- rules 暂不接（ZCode 无用户级 rules 目录约定）
- 双语文档 + 6 个专项测试
如果维护者认可这个方向，我们即刻发起 PR（分支已就绪）。
Alternatives Considered（考虑过的替代）
- 仅依赖中央
agents条目同步 skills：skills 可达，但 hooks 无法注入（自动同步缺失），subagents / MCP 同样无法分发——不满足「One Harness」目标 - 团队仓库
teamai.yaml自定义toolPaths过渡：我们当前临时如此使用，可让 skills 到达 ZCode；但整体替换默认表有维护成本，且 hooks 格式仍无法适配
Additional Context
- 环境：teamai-cli 0.23.1 / Windows 10-11 / ZCode 桌面版
- 团队在 Claude Code、Cursor、Codex、Qoder、OpenCode、ZCode 多工具环境下使用 teamai 分发团队 skills 与知识库，愿意配合后续迭代
Activity
linezuhaichao-debug commentedon Sep 21, 2026
问题：windows系统使用zcode，开了新会话，teamai没有自动拉取最新的团队资源。
以下答案为glm5.3flash产出
结论先说：teamai 的自动拉取机制本身没坏，坏的是 ZCode 根本启动不了它的钩子进程——从 9-20 装上那天起，自动 pull 就一次都没成功过（ZCode 日志里两天累计 800 次 hook.run.failed）。
根因
teamai 给 ZCode 注入的钩子用的是裸命令名 bash，靠启动时的 PATH 解析。而 ZCode 桌面进程的 PATH 里只有 Git\cmd（没有 bash），bash 被解析到了 C:\Windows\system32\bash.exe——那是 WSL 的占位符，你机器上没装 WSL 发行版，所以钩子进程一启动就报错退出（~90ms）。之前手动测试一直正常，是因为在 Git Bash 终端里 bash 解析到的是 Git 自己的 bash——环境不同，测不出问题。
修了什么
钩子命令改为绝对路径：~/.zcode/cli/config.json 里 6 个 teamai 钩子的 command 从 bash 改成 C:/Program Files/Git/bin/bash.exe。
给 teamai CLI 打了补丁（防它自动 reconcile 时改回去）：npm 全局包里 toZcodeEntry 现在读取 TEAMAI_BASH_PATH 环境变量生成钩子命令，托管识别逻辑也同步放宽。已验证 teamai pull 后钩子格式保持不变（幂等）。
持久化：setx TEAMAI_BASH_PATH "C:\Program Files\Git\bin\bash.exe" 写入了用户环境变量。
顺带把 hooks inject 重新写进 claude/codex 的死钩子又摘掉了（你之前手动清过，那个命令会绕过 enabledAgents）。
hc-tec commentedon Sep 24, 2026
The hooks you're hitting are the pre-0.25.0 entries: teamai ≤ 0.24.0 rendered ZCode hooks as a bare
bash, which Windows resolves to System32's WSL launcher before any PATH entry — inside WSL there's no npm-global teamai, so every dispatch fails silently (your 800hook.run.failed). This was fixed in #596: on Windows the hooks now launch through a hidden wscript VBS launcher (no console flash, STDIN preserved), andpullreconciles the entries on first run.npm i -g teamai-cli@latest(v0.25.0) and runteamai pullonce — the old bash entries get replaced automatically. Verified on a live Windows box: auto-pull on session start has been running daily without a single failure since the fix.