feat(agent-adapter): Phase 3-4 migration (UFO-132)

Closes UFO-132

Author: WitMiao

docs/en/SUMMARY.md

@@ -22,6 +22,7 @@
 * [API Provider Presets](advanced/api-providers.md)
 * [Templates and Output Styles](advanced/templates.md)
 * [Internationalization and Language](advanced/i18n.md)
+* [Community Agent Adapters](advanced/community-adapters.md)
 * [Troubleshooting](advanced/troubleshooting.md)
 
 ## CLI Commands

docs/en/advanced/community-adapters.md

@@ -0,0 +1,118 @@
+# Community Agent Adapters
+
+ZCF uses an adapter-based architecture to support different coding agent CLIs. Built-in adapters are shipped with the package (`claude-code`, `codex`, `opencode`), but you can also write and load your own adapter without modifying ZCF.
+
+## Adapter Interface
+
+A community adapter must implement the `AgentAdapter` interface exported by `zcf`:
+
+```ts
+import type { AgentAdapter, AgentConfigFile, AgentContext, AgentSkillSpec, InstallOptions, UninstallOptions, UpdateOptions } from 'zcf'
+
+export default {
+  id: 'my-agent',
+  displayName: 'My Agent',
+  aliases: ['ma'],
+  homeDir: '/home/user/.my-agent',
+  templateDir: 'templates/my-agent',
+  configFiles: [
+    { id: 'settings', path: '/home/user/.my-agent/settings.json', format: 'json', mergeStrategy: 'merge' },
+  ],
+  skillSpec: {
+    skillsDir: '/home/user/.my-agent/skills',
+    manifestName: 'SKILL.md',
+    scopes: ['global', 'project'],
+  },
+
+  async isInstalled() { /* ... */ },
+  async install(options: InstallOptions, ctx: AgentContext) { /* ... */ },
+  async update(options: UpdateOptions, ctx: AgentContext) { /* ... */ },
+  async uninstall(options: UninstallOptions, ctx: AgentContext) { /* ... */ },
+  async backup(file: AgentConfigFile) { /* ... */ },
+} satisfies AgentAdapter
+```
+
+Key methods:
+
+- `isInstalled` — detect whether the target CLI is available.
+- `install` — render templates, write configuration, install skills.
+- `update` — refresh templates and skills without a full reinstall.
+- `uninstall` — remove ZCF-managed files and skills.
+- `backup` — create a timestamped backup before overwriting a config file.
+
+Use the `TemplateEngine` class from `zcf/core/template-engine` to render templates and skills consistently.
+
+## Loading from a Local TOML Manifest
+
+Place a TOML manifest in `~/.ufomiao/zcf/adapters/<id>.toml`:
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+aliases = ["ma"]
+main = "my-agent/adapter.mjs"
+```
+
+The `main` path is relative to `~/.ufomiao/zcf/adapters/`. The referenced module must export a valid `AgentAdapter` as its default export. You can also use a factory export:
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+main = "my-agent/adapter.mjs"
+export = "createAdapter"
+```
+
+```ts
+// my-agent/adapter.mjs
+export function createAdapter(manifest) {
+  return {
+    id: manifest.id,
+    // ...
+  }
+}
+```
+
+ZCF loads external adapters on startup. A broken adapter is logged and skipped so it cannot break the CLI.
+
+## Loading from an NPM Package
+
+Reference an NPM package in the manifest:
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+package = "zcf-adapter-my-agent"
+export = "adapter"
+```
+
+The package must be resolvable by Node (install it globally or in a parent project). The adapter is loaded via dynamic import.
+
+## Best Practices
+
+1. **Preserve user customizations** — use `mergeStrategy: 'merge'` for JSON/TOML files and back up before writing.
+2. **Scope skills** — put user-facing skills under `templates/<agent>/skills/user/` and project-internal skills under `templates/<agent>/skills/zcf/`.
+3. **Manual-only skills** — if a skill should only be triggered by the user, add `disable-model-invocation: true` to its `SKILL.md` frontmatter.
+4. **Use the template engine** — `renderConfigFile`, `renderCommon`, and `renderSkill` handle merge strategies, backups, and i18n-friendly rendering.
+5. **Test coverage** — adapters must have unit tests covering installation, update, uninstall, and edge cases. Maintain ≥80% coverage.
+
+## Example `SKILL.md`
+
+```markdown
+---
+name: my-skill
+description: A custom skill for my agent
+version: 1.0.0
+namespace: user
+disable-model-invocation: true
+---
+
+# My Skill
+
+Instructions for the agent when this skill is invoked.
+```
+
+## Troubleshooting
+
+- **Adapter not appearing in `zcf --help`**: check the manifest ID/aliases are unique and the module exports a valid adapter.
+- **`isInstalled` always false**: ensure the executable is on the user's `PATH`.
+- **Template not rendered**: verify `templateDir` points to a directory containing the expected files and `renderCommon` is called for shared resources.

docs/zh-CN/SUMMARY.md

@@ -22,6 +22,7 @@
 * [API 提供商预设](advanced/api-providers.md)
 * [模板与输出风格](advanced/templates.md)
 * [国际化与语言](advanced/i18n.md)
+* [社区 Agent Adapter](advanced/community-adapters.md)
 * [故障排除](advanced/troubleshooting.md)
 
 ## CLI 命令

docs/zh-CN/advanced/community-adapters.md

@@ -0,0 +1,118 @@
+# 社区 Agent Adapter
+
+ZCF 采用 adapter 架构来支持不同的 coding agent CLI。内置 adapter（`claude-code`、`codex`、`opencode`）随包发布，但你也可以编写并加载自定义 adapter，无需修改 ZCF 源码。
+
+## Adapter 接口
+
+社区 adapter 必须实现 `zcf` 导出的 `AgentAdapter` 接口：
+
+```ts
+import type { AgentAdapter, AgentConfigFile, AgentContext, AgentSkillSpec, InstallOptions, UninstallOptions, UpdateOptions } from 'zcf'
+
+export default {
+  id: 'my-agent',
+  displayName: 'My Agent',
+  aliases: ['ma'],
+  homeDir: '/home/user/.my-agent',
+  templateDir: 'templates/my-agent',
+  configFiles: [
+    { id: 'settings', path: '/home/user/.my-agent/settings.json', format: 'json', mergeStrategy: 'merge' },
+  ],
+  skillSpec: {
+    skillsDir: '/home/user/.my-agent/skills',
+    manifestName: 'SKILL.md',
+    scopes: ['global', 'project'],
+  },
+
+  async isInstalled() { /* ... */ },
+  async install(options: InstallOptions, ctx: AgentContext) { /* ... */ },
+  async update(options: UpdateOptions, ctx: AgentContext) { /* ... */ },
+  async uninstall(options: UninstallOptions, ctx: AgentContext) { /* ... */ },
+  async backup(file: AgentConfigFile) { /* ... */ },
+} satisfies AgentAdapter
+```
+
+核心方法：
+
+- `isInstalled` — 检测目标 CLI 是否已安装。
+- `install` — 渲染模板、写入配置、安装 skill。
+- `update` — 刷新模板与 skill，不执行完整重装。
+- `uninstall` — 移除 ZCF 管理的文件与 skill。
+- `backup` — 在覆盖配置文件前创建带时间戳的备份。
+
+使用 `zcf/core/template-engine` 中的 `TemplateEngine` 类可保持一致地渲染模板与 skill。
+
+## 通过本地 TOML Manifest 加载
+
+在 `~/.ufomiao/zcf/adapters/<id>.toml` 放置 TOML 清单：
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+aliases = ["ma"]
+main = "my-agent/adapter.mjs"
+```
+
+`main` 路径相对于 `~/.ufomiao/zcf/adapters/`。被引用的模块必须以默认导出形式提供有效的 `AgentAdapter`。也支持工厂导出：
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+main = "my-agent/adapter.mjs"
+export = "createAdapter"
+```
+
+```ts
+// my-agent/adapter.mjs
+export function createAdapter(manifest) {
+  return {
+    id: manifest.id,
+    // ...
+  }
+}
+```
+
+ZCF 在启动时加载外部 adapter。加载失败的 adapter 会被记录并跳过，不会影响整个 CLI。
+
+## 通过 NPM 包加载
+
+在清单中引用 NPM 包：
+
+```toml
+id = "my-agent"
+displayName = "My Agent"
+package = "zcf-adapter-my-agent"
+export = "adapter"
+```
+
+该包需要能被 Node 解析（全局安装或安装在父项目中）。adapter 通过动态导入加载。
+
+## 最佳实践
+
+1. **保留用户自定义内容** — JSON/TOML 文件使用 `mergeStrategy: 'merge'`，写入前进行备份。
+2. **划分 skill 作用域** — 面向用户的 skill 放在 `templates/<agent>/skills/user/`，项目内部 skill 放在 `templates/<agent>/skills/zcf/`。
+3. **手动触发 skill** — 仅希望用户手动触发的 skill，在 `SKILL.md` frontmatter 中加上 `disable-model-invocation: true`。
+4. **复用模板引擎** — `renderConfigFile`、`renderCommon`、`renderSkill` 已处理合并策略、备份与 i18n 友好渲染。
+5. **测试覆盖** — adapter 必须包含安装、更新、卸载及边界用例的单元测试，保持 ≥80% 覆盖率。
+
+## `SKILL.md` 示例
+
+```markdown
+---
+name: my-skill
+description: A custom skill for my agent
+version: 1.0.0
+namespace: user
+disable-model-invocation: true
+---
+
+# My Skill
+
+Instructions for the agent when this skill is invoked.
+```
+
+## 故障排查
+
+- **adapter 未出现在 `zcf --help` 中**：检查 manifest 的 ID/aliases 是否唯一，模块是否导出有效 adapter。
+- **`isInstalled` 始终返回 false**：确保可执行文件在用户 `PATH` 中。
+- **模板未渲染**：确认 `templateDir` 指向包含预期文件的目录，并调用 `renderCommon` 渲染共享资源。

src/adapters/index.ts

@@ -1,9 +1,11 @@
 import { claudeCodeAdapter } from './claude-code'
 import { codexAdapter } from './codex'
+import { loadExternalAdapters } from './loader'
 import { opencodeAdapter } from './opencode'
 import { listAgentIds, registerAgent } from './registry'
 
 export * from './adapter-interface'
+export * from './loader'
 export * from './registry'
 export { claudeCodeAdapter, codexAdapter, opencodeAdapter }
 
@@ -15,7 +17,7 @@ export { claudeCodeAdapter, codexAdapter, opencodeAdapter }
  * already registered, keeping setup idempotent in long-running or test
  * environments.
  */
-export function registerAllAgents(): void {
+export async function registerAllAgents(): Promise<void> {
   if (!listAgentIds().includes(claudeCodeAdapter.id)) {
     registerAgent(claudeCodeAdapter)
   }
@@ -25,4 +27,16 @@ export function registerAllAgents(): void {
   if (!listAgentIds().includes(opencodeAdapter.id)) {
     registerAgent(opencodeAdapter)
   }
+
+  try {
+    const external = await loadExternalAdapters()
+    for (const adapter of external) {
+      if (!listAgentIds().includes(adapter.id)) {
+        registerAgent(adapter)
+      }
+    }
+  }
+  catch {
+    // External adapters are best-effort; do not fail startup.
+  }
 }

src/adapters/loader.ts

@@ -0,0 +1,96 @@
+import type { AgentAdapter, AgentId } from './adapter-interface'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { join } from 'pathe'
+import { ZCF_CONFIG_DIR } from '../constants'
+import { parseToml } from '../utils/toml-edit'
+
+export interface ExternalAdapterManifest {
+  id: AgentId
+  displayName: string
+  aliases?: string[]
+  /** Absolute or relative path to the adapter implementation module */
+  main?: string
+  /** NPM package name that exports the adapter */
+  package?: string
+  /** Exported member to read from the module. Defaults to "default" or "adapter". */
+  export?: string
+}
+
+const EXTERNAL_ADAPTERS_DIR = join(ZCF_CONFIG_DIR, 'adapters')
+
+function isValidManifest(obj: unknown): obj is ExternalAdapterManifest {
+  if (!obj || typeof obj !== 'object')
+    return false
+  const o = obj as Record<string, unknown>
+  return typeof o.id === 'string' && typeof o.displayName === 'string'
+}
+
+async function resolveAdapterModule(manifest: ExternalAdapterManifest, manifestDir: string): Promise<AgentAdapter> {
+  let moduleUrl: string | undefined
+
+  if (manifest.package) {
+    moduleUrl = manifest.package
+  }
+  else if (manifest.main) {
+    const mainPath = manifest.main.startsWith('/')
+      ? manifest.main
+      : join(manifestDir, manifest.main)
+    moduleUrl = pathToFileURL(mainPath).href
+  }
+
+  if (!moduleUrl) {
+    throw new Error(`External adapter "${manifest.id}" must specify "main" or "package".`)
+  }
+
+  const mod = await import(moduleUrl)
+  const exportName = manifest.export || 'default'
+  const exported = exportName === 'default' ? mod.default : mod[exportName]
+  const adapter: AgentAdapter = typeof exported === 'function' ? exported(manifest) : exported
+
+  if (!adapter || typeof adapter.install !== 'function' || typeof adapter.isInstalled !== 'function') {
+    throw new Error(`External adapter "${manifest.id}" does not export a valid AgentAdapter.`)
+  }
+
+  return adapter
+}
+
+/**
+ * Load external adapter manifests from `~/.ufomiao/zcf/adapters/*.toml` and
+ * from NPM packages referenced by those manifests.
+ *
+ * This is intentionally lenient: a broken adapter is logged and skipped so
+ * that one bad community package cannot break the whole CLI.
+ */
+export async function loadExternalAdapters(adaptersDir: string = EXTERNAL_ADAPTERS_DIR): Promise<AgentAdapter[]> {
+  if (!existsSync(adaptersDir)) {
+    return []
+  }
+
+  const entries = readdirSync(adaptersDir)
+  const adapters: AgentAdapter[] = []
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.toml'))
+      continue
+
+    const manifestPath = join(adaptersDir, entry)
+    try {
+      const content = readFileSync(manifestPath, 'utf-8')
+      const manifest = parseToml<ExternalAdapterManifest>(content)
+
+      if (!isValidManifest(manifest)) {
+        console.warn(`[zcf] Skipping invalid adapter manifest: ${manifestPath}`)
+        continue
+      }
+
+      const adapter = await resolveAdapterModule(manifest, adaptersDir)
+      adapters.push(adapter)
+    }
+    catch (error) {
+      console.warn(`[zcf] Failed to load external adapter from ${manifestPath}: ${(error as Error).message}`)
+    }
+  }
+
+  return adapters
+}