传化代码助手 (TransfarCode)

传化集团 AI 编码助手 — 基于 OpenCode 构建，支持多轮对话、代码编辑、Figma 设计转代码。

功能概览

• AI 多轮对话 — 直接在 VS Code 侧边栏与 AI 对话，编码、调试、重构一站式
• 整文件编辑 — AI 可读写工作区文件，支持安全的增量修改
• 终端工具执行 — AI 可执行 Shell 命令（需用户审批），运行构建、测试等
• page-builder 技能 — 项目自适应页面生成，自动检测框架和代码风格
• 项目自定义 SKILL — 项目根目录 transfarcode.md 自动识别为项目级技能，支持外部自定义 SKILL 路径
• 多项目支持 — 自动识别 VS Code 工作区，动态切换项目上下文
• 主题自适应 — 自动跟随 VS Code 亮色/暗色主题
• 跨平台兼容 — macOS / Windows / Linux 全平台支持

前提条件

必须提前安装 OpenCode CLI，本插件依赖 opencode 作为 AI 推理后端。

# macOS / Linux
curl -fsSL https://opencode.ai/install.sh | bash

# Windows (PowerShell 管理员模式)
irm https://opencode.ai/install.ps1 | iex

# 验证安装
opencode --version
# 应显示 >= v1.15.0

如未安装 opencode，插件启动后侧边栏将无法正常加载。

安装

方式一：本地 .vsix 安装

1. 下载 transfarcode-x.x.x.vsix
2. VS Code → 扩展面板 → ... → "从 VSIX 安装..."
3. 选择下载的 .vsix 文件
4. 安装后点击侧边栏「传化代码助手」图标启动

方式二：开发模式安装

cd packages/extensions/vscode
npx @vscode/vsce package --no-dependencies
# 安装生成的 .vsix

环境要求

• VS Code >= 1.85.0
• OpenCode CLI >= v1.15.0（全局安装）
• Node.js >= 18（推荐 Node 22）

架构

VS Code 侧边栏 WebView (vscode-webview://)
    │
    ├── iframe: http://127.0.0.1:PROXY → opencode serve
    │       │
    │       ├── HTML 注入：主题适配 + 剪贴板桥接
    │       └── Web UI (SolidJS SPA)
    │
扩展进程
    ├── HTTP 代理（剪贴板注入 + 透传）
    ├── opencode serve 子进程管理
    ├── Skill 自动安装（→ {workspace}/.opencode/skills/）
    ├── opencode.jsonc 权限 + skills.paths 同步
    ├── transfarcode.md 项目 SKILL 自动发现
    └── 跨平台缓存目录保障

关键技术点：

page-builder 技能 (Skill)

概述

page-builder 是一个项目自适应页面生成技能。它通过深度分析当前工作区的技术栈、目录结构、UI 组件库和现有代码风格，生成与项目完全一致的页面代码。

实现原理

1. 项目自动分析（Step 1 — 必须先行）

在生成任何代码前，Skill 会完整扫描工作区：

技术栈检测：读取 package.json，识别框架/UI库/构建工具
├── 框架：React / Vue / SolidJS / Taro / uni-app / Next.js / Nuxt
├── UI 库：Ant Design / TDesign / Element Plus / Vant / NutUI / Tailwind
├── 语言：TypeScript / JavaScript
├── 样式：CSS Modules / Less / Sass / Tailwind / Styled-Components
└── 路由：React Router / Vue Router / 约定式路由

目录结构分析：扫描 src/、pages/ 等目录
├── 页面位置：src/pages/ | src/views/ | src/routes/
├── 组件位置：src/components/ | src/widgets/
├── API 位置：src/api/ | src/services/ | src/request/
└── 状态管理：src/store/ | src/composables/

代码风格取样：读取 2-3 个现有页面
├── 组件写法（Hooks / Composition API）
├── 导入路径别名（@/ ~/ @components/）
├── 错误处理模式（try/catch / Error Boundary）
├── Loading / Empty / Error 三态写法
└── 命名约定（PascalCase / camelCase）

2. 框架识别速查

3. UI 组件库速查

4. 生成流程

Step 1: 项目分析 → Step 2: 需求确认 → Step 3: Figma 集成 → Step 4: 代码生成 → Step 5: 路由注册 → Step 6: 迭代优化

• Step 3 (Figma)：若用户提供 Figma 链接，通过 MCP 获取设计上下文，提取颜色/间距/字体 token，映射到项目已有的 Design Token
• Step 4 (代码生成)：按项目风格生成页面文件（主组件 + 类型定义 + API 服务 + 样式），严格禁止 any 类型，处理 loading/error/empty 三态
• Step 5 (路由注册)：不直接修改路由文件，仅输出配置片段并告知插入位置
• Step 6 (迭代优化)：生成后主动询问样式/逻辑/联动调整需求

5. 小程平台特殊规则

检测到 Taro / uni-app / 原生小程序时自动适配：

• 使用 Taro.navigateTo / Taro.showToast，禁止 window/document
• 样式使用 rpx，图片使用 <Image>，链接使用 <Navigator>
• 自动读取 app.config.ts 了解页面注册格式和 tabBar 页面

6. Skill 分发机制

插件内置了 page-builder Skill（skills/page-builder/ 目录），激活时自动执行：

1. 将 SKILL.md + FRAMEWORK_DETECTION.md 安装到工作区 {workspace}/.opencode/skills/page-builder/
2. 写入 .transfarcode-version 版本标记，后续版本升级时自动覆盖
3. 自动清理 ~/.config/opencode/skill/page-builder/ 等全局路径上的旧版残留，避免同名冲突
4. 自动在 opencode.jsonc 中注册 skill 权限（allow）+ 配置 skills.paths

对于同事：只需安装 .vsix，无需手动配置 Skill。

7. 项目自定义 SKILL

方式一：transfarcode.md 自动发现（推荐）

在项目根目录放置 transfarcode.md，插件激活时自动识别为项目级 Skill：

---
name: my-project-skill
description: 本项目的 AI 编码规范
---

# 项目约定
- 使用 TypeScript 严格模式
- 组件放在 src/components/

插件会检测文件是否有 YAML frontmatter，无则自动包装（首行作为 description）。

方式二：transfarcode.skillPaths 手动配置

在项目 .vscode/settings.json 中配置自定义 SKILL 目录：

{
  "transfarcode.skillPaths": [
    "docs/custom-skills",
    "/Users/shared/team-skills"
  ]
}

• 相对路径：相对于工作区根目录
• 绝对路径：直接使用
• 插件启动时自动合并到 opencode.jsonc 的 skills.paths 配置

使用方法

在 AI 对话中输入以下类型的提示词即可触发：

触发词：帮我做一个 XX 页面、根据设计稿生成代码、新建一个列表页 等。

命令

开发

调试

在 VS Code 中按 F5 启动扩展开发主机（Extension Development Host），可在其中测试插件。

设置环境变量 TRANSFARCODE_DEV=/path/to/monorepo 可从源码运行 opencode（无需编译二进制）：

export TRANSFARCODE_DEV=/Users/xxx/Desktop/git/transfaropencode
code --enable-proposed-api transfarcode.transfarcode

打包

cd packages/extensions/vscode
PATH="$HOME/.nvm/versions/node/v22.15.0/bin:$PATH" npx @vscode/vsce package --no-dependencies

生成 transfarcode-x.x.x.vsix。

版本历史

License

内部使用 — Transfar Group