Skip to content

fix: auto-discover KNOWN_AGENTS for resource injection during pull - #394

Open
jeff-r2026 wants to merge 3 commits into
mainfrom
fix/pull-auto-discover-agents
Open

fix: auto-discover KNOWN_AGENTS for resource injection during pull#394
jeff-r2026 wants to merge 3 commits into
mainfrom
fix/pull-auto-discover-agents

Conversation

@jeff-r2026

Copy link
Copy Markdown
Collaborator

Summary

  • pullItem() in skills/rules/agents handlers only iterated scopedToolPaths() (= teamai.yaml toolPaths), missing tools like tclaude/tcodex that are in KNOWN_AGENTS and installed on disk
  • Added effectiveToolPaths() in types.ts that merges scopedToolPaths() with auto-discovered KNOWN_AGENTS entries whose install root (e.g. .tclaude/) exists
  • Updated all pull/sync call sites (skills, rules, builtin-skills, builtin-rules, builtin-agents, pull.ts) to use effectiveToolPaths()
  • Added tclaude and tcodex to SELF_MODE_AGENT_CHOICES for teamai init single-repo mode detection

Test plan

  • npx tsc --noEmit passes (no new type errors)
  • npx vitest run — all previously-passing tests still pass, updated 3 test files for new SELF_MODE_AGENT_CHOICES size
  • E2E: mkdir -p /root/gpu/.tclaude && teamai pull --force → skills/rules injected into .tclaude/skills/ and .tclaude/rules/
  • Build succeeds

🤖 Generated with Claude Code

The pull flow (skills, rules, agents, builtin resources) only iterated
over tools explicitly listed in teamai.yaml toolPaths via scopedToolPaths().
Tools like tclaude/tcodex that are registered in KNOWN_AGENTS and installed
on disk (.tclaude/ exists) were silently skipped — seedProjectAgentRoot()
created their root directory, but pullItem() never wrote resources into it.

Add effectiveToolPaths() that merges scopedToolPaths() with auto-discovered
KNOWN_AGENTS entries whose install root exists on disk. Convention-based
paths (skills, rules, agents, claudemd) are derived from the agent's
skillsPath. Use this in all pull/sync call sites so any installed tool
receives team resources without requiring explicit teamai.yaml config.

Also add tclaude and tcodex to SELF_MODE_AGENT_CHOICES so they are
detected during `teamai init` in single-repo mode.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jeff-r2026 jeff-r2026 mentioned this pull request Sep 2, 2026
3 tasks
@jeff-r2026

Copy link
Copy Markdown
Collaborator Author

建议把这个问题提升为更明确的产品模型:不再由 teamai.yaml 决定支持哪些 Agent,而以当前作用域中实际安装的 Agent 为同步目标。

建议的职责划分:

  • user scope 扫描 HOME,project scope 扫描项目根目录,自动发现所有已安装的已知 Agent;
  • KNOWN_AGENTS / Agent Registry 只负责安装检测、资源能力声明,以及经过验证的 user/project 路径;
  • toolPaths 不再作为 Agent 白名单,可逐步废弃,或仅保留为企业内部发行版、自定义安装目录的 path override;
  • 新增 Agent 时只更新 Registry,不要求每个团队修改 teamai.yaml

当前 PR 的 auto-discovery 方向符合这个目标,但实现上建议补齐几个边界:

  1. 不要只从 skillsPath 推导 ${root}/rules${root}/agents${root}/CLAUDE.md。Registry 当前只保证 skills 路径,这些额外路径需要逐 Agent 验证并声明能力,不支持的资源应跳过。
  2. pull 可以面向所有检测到的有效 Agent;push 应单独定义边界,避免把 Agent 自带或个人 Skill 自动纳入团队候选。
  3. remove 只应删除 TeamAI 有管理记录的资源,不能仅因名称相同就在所有检测到的 Agent 中删除。
  4. enabledAgents / disabledAgents 需要同步简化:如果不再提供“选择支持哪些 Agent”的能力,可以只保留本地排除机制,或明确迁移语义。

建议增加以下回归测试:

  • 未配置 toolPaths 时,已安装的 .gemini.tclaude 等能够自动收到资源;
  • 每个 Agent 只收到 Registry 明确声明支持的资源类型;
  • 自定义安装路径仍可通过 override 工作;
  • 自动发现不会导致个人 Skill 被无提示上传或删除。

这样可以彻底解决“新增 Agent 需要更新团队配置”的问题,同时避免把路径猜测和双向同步安全边界混在一起。

…anaged tools

Address PR review feedback:

1. Replace convention-based path derivation (deriveToolPaths) with a lookup
   into DEFAULT_TOOL_PATHS — a verified per-tool registry extracted from
   the schema defaults. Agents without a registry entry (e.g. gemini) receive
   only their skills path; rules/agents/claudemd are never guessed.

2. Restrict push (scanLocalForPush) and remove (removeItem) to
   scopedToolPaths() — only team-managed tools. This prevents personal
   skills in auto-discovered tool dirs from being silently uploaded, and
   ensures remove only deletes resources teamai has management records for.

3. Pull and sync paths (pullItem, pullAllRules, builtin-*) continue using
   effectiveToolPaths() so installed tools receive team resources.

4. Add regression tests covering: auto-discovery with verified paths,
   skills-only fallback for unregistered agents, custom path override
   precedence, disabledAgents, codebuddy CODEBUDDY.md preservation, and
   scopedToolPaths isolation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jeff-r2026

Copy link
Copy Markdown
Collaborator Author

复查最新提交 531eabc:之前提到的 push 扫描越界和未验证路径推导已经修复,但仍有一个可本地稳定复现的 P1。

[P1] pull 的 tombstone 清理仍会删除自动发现目录中的个人 Skill

SkillsHandler.removeItem() 虽然已经恢复使用 scopedToolPaths(),但 pullForScope() 的 tombstone 清理仍遍历 effectiveToolPaths()src/pull.ts 约 600 行),然后仅凭资源名称删除目录。

本地复现:

  1. teamConfig.toolPaths 只配置 Claude;
  2. 创建未由 TeamAI 管理的 ~/.gemini/skills/private-skill/SKILL.md
  3. 团队仓库的 skills/.removed 包含 private-skill
  4. 执行 pull({})
  5. ~/.gemini/skills/private-skill 整个目录被删除。

也就是说,直接调用 removeItem() 暂时保留了自动发现目录,但下一次 pull 仍会通过 tombstone 删除它。这里需要 managed-resource 记录,或者 tombstone 清理继续限制在明确可证明由 TeamAI 管理的路径,不能仅凭同名删除。

另外还有两个 auto-discovery 功能遗漏:

  • OpenCode user scope 的实际安装根是 ~/.config/opencode,但 effectiveToolPaths() 使用 KNOWN_AGENTS.skillsPath 的首段检测 ~/.opencode,因此当 team config 没有 OpenCode 条目时,正常用户级安装无法被自动发现;即使发现,registry 路径也没有经过 user-scope override。
  • AgentsHandler.pullItem()pullLegacyMd() 仍使用 scopedToolPaths()。例如 team config 只包含 Claude、但本地存在 .tclaude 时,skills/rules/builtin-agent 会自动下发,团队自定义 agent 却不会下发到 TClaude。

建议在合并前至少修复 tombstone 删除问题,并为“自动发现目录中存在同名个人 Skill”加入回归测试。

…ull path

Address second round of PR review:

1. [P1] Tombstone cleanup and stale-skill cleanup in pull.ts now use
   scopedToolPaths() instead of effectiveToolPaths(). A personal skill
   in an auto-discovered dir (e.g. ~/.gemini/skills/private-skill) that
   shares a name with a tombstoned team skill is no longer deleted.
   Same fix applied to stale-rule cleanup in rules.ts.

2. OpenCode user-scope detection: effectiveToolPaths() now resolves the
   install-detection root from userScope paths when in user scope, so
   ~/.config/opencode is correctly detected (not just ~/.opencode).
   userScope path overrides are also applied to the returned paths.

3. AgentsHandler.pullItem() and pullLegacyMd() now use effectiveToolPaths()
   so auto-discovered tools (e.g. tclaude) receive team agent definitions.

4. Added regression tests for OpenCode user-scope auto-discovery.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant