企业官网建设流程全解析

• 桌面应用
• AI 应用
• AI Agent

opcode 是一款为 Claude Code 打造的 GUI 工具与工具包，其CC Agents（Claude Code Agents）模块允许用户创建、管理并后台执行自定义 AI Agent。本指南以仓库cc_agents/目录中的三个预置智能体及配套文档为核心，完整讲解智能体的导入、导出、.opcode.json文件格式，并结合 src-tauri/src/commands/agents.rs 与 src/components/CCAgents.tsx 等源码，深入剖析其底层的存储、校验、去重、执行与实时监控实现，帮助你既能开箱即用地运行这些智能体，也能理解并自行编写可贡献的高质量智能体。

📦 预置智能体一览

cc_agents/目录存放了三个开箱即用的预置智能体，全部由 Claude Code 驱动，覆盖开发中最常见的自动化场景：

三个智能体的系统提示词分别封装在 git-commit-bot.opcode.json、security-scanner.opcode.json 和 unit-tests-bot.opcode.json 中，均可直接在 opcode 中导入运行，也可作为你编写自定义智能体的参考模板。

可用的图标选项

创建智能体时可以从以下图标中选择，帮助你在网格界面中快速辨识：

• bot- 🤖 通用用途
• shield- 🛡️ 安全相关
• code- 💻 开发相关
• terminal- 🖥️ 系统/CLI
• database- 🗄️ 数据操作
• globe- 🌐 网络/Web
• file-text- 📄 文档
• git-branch- 🌿 版本控制

在前端实现中，图标定义于 src/components/IconPicker.tsx 的ICON_MAP，并由 src/components/CCAgents.tsx 导出为AGENT_ICONS；渲染时若图标名未命中会回退到bot（CCAgents.tsx 第 252-255 行）。

智能体模型选型指南

• Haiku：适合简单任务，响应快、成本低；
• Sonnet：通用任务首选（Git Commit Bot 即采用该模型）；
• Opus：复杂推理任务（Security Scanner 与 Unit Tests Bot 均采用该模型，因为它们需要多阶段推理与子代理编排）。

📥 导入智能体（两种方式）

方式一：从 GitHub 导入（推荐）

1. 在 opcode 中进入CC Agents界面；
2. 点击Import下拉按钮；
3. 选择From GitHub；
4. 浏览官方仓库中可用的智能体；
5. 预览智能体详情后点击Import Agent。

该流程由 GitHubAgentBrowser.tsx 实现：界面提供搜索框可按名称过滤，点击某个智能体后通过fetchGitHubAgentContent拉取其download_url内容进行预览，再调用importAgentFromGitHub完成导入。

方式二：从本地文件导入

1. 从本仓库下载一个.opcode.json文件（例如cc_agents/下的三个预置智能体）；
2. 在 opcode 中进入CC Agents；
3. 点击Import下拉按钮；
4. 选择From File；
5. 选中下载的.opcode.json文件。

前端通过 Tauri 原生文件对话框（@tauri-apps/plugin-dialog的open）选择文件后，调用api.importAgentFromFile完成导入（CCAgents.tsx 第 219-245 行）。

导入的后端校验与去重逻辑

无论哪种方式，最终都会汇聚到 Rust 端的import_agent命令（agents.rs 第 1702-1777 行），其处理流程如下：

1. 解析 JSON：将文件内容解析为AgentExport结构，格式错误直接报 "Invalid JSON format"；
2. 版本校验：仅支持version == 1，否则返回 "Unsupported export version"；从本地文件导入时还会先剥离 BOM 并 trim 首尾空白（import_agent_from_file）；
3. 自动去重：按name查询已存在的智能体，若重名则在原名后追加(Imported)后缀，避免命名冲突；
4. 写入数据库：以enable_file_read=1、enable_file_write=1、enable_network=0的默认权限入库（与agents表的列默认值一致，见 agents.rs 第 229-244 行）。

从 GitHub 导入时，fetch_github_agents调用 GitHub API 拉取cc_agents目录内容，并只保留*.opcode.json且类型为file的条目（agents.rs 第 1826-1868 行）；import_agent_from_github则会先下载内容并做同样的版本校验后复用上述导入逻辑。

📤 导出智能体

导出你的自定义智能体

1. 在 opcode 中进入CC Agents；
2. 在网格中找到目标智能体；
3. 点击Export按钮；
4. 选择保存.opcode.json文件的路径。

前端会先弹出原生保存对话框（save），默认文件名由智能体名转换而来（小写、空格替换为连字符，如Git Commit Bot→git-commit-bot.opcode.json，见 CCAgents.tsx 第 190-217 行），再调用 Tauri 命令export_agent_to_file写入磁盘。

导出格式与内部实现

Rust 端export_agent从数据库读取name、icon、system_prompt、default_task、model、hooks六个字段，组装为带版本与时间戳的 JSON 结构（agents.rs 第 1529-1562 行）：

{ "version": 1, "exported_at": "2025-01-23T14:29:58.156063+00:00", "agent": { "name": "Your Agent Name", "icon": "bot", "model": "opus|sonnet|haiku", "system_prompt": "Your agent's instructions...", "default_task": "Default task description" } }

exported_at使用 RFC 3339 时间戳（chrono::Utc::now().to_rfc3339()），version固定为 1。对照仓库中的三个真实导出文件可发现，实际导出可能额外包含hooks字段（用于挂载 Claude Code hooks 配置，与 api.ts 中的 AgentExport 类型 一致）。

🔧 技术实现：导入/导出如何工作

智能体的导入/导出体系构建在 Tauri（Rust 后端）+ React/TypeScript（前端）架构之上。

后端（Rust/Tauri）

• 存储：SQLite 数据库（agents.db，位于应用数据目录）存储智能体配置；agents表包含id、name、icon、system_prompt、default_task、model、enable_file_read、enable_file_write、enable_network、hooks、created_at、updated_at等字段，并建有agent_runs表记录每次执行（含status：pending/running/completed/failed/cancelled），两表通过外键agent_id关联、ON DELETE CASCADE（agents.rs 第 216-346 行）；
• 导出：将智能体数据序列化为带版本控制的 JSON；
• 导入：解析、校验版本并自动去重；
• GitHub 集成：通过 GitHub API 拉取官方仓库中的智能体清单与内容。

前端（React/TypeScript）

• UI 组件：
  • CCAgents.tsx - 智能体管理主界面（网格展示、分页每页 9 个、执行/编辑/导出/删除操作）；
  • GitHubAgentBrowser.tsx - GitHub 仓库浏览器（搜索、预览、导入）；
  • CreateAgent.tsx - 智能体创建/编辑表单；
• 文件操作：使用 Tauri 原生文件对话框完成导入/导出；
• 实时更新：通过agent-output:{run_id}、agent-error:{run_id}、agent-complete:{run_id}等事件通道实时推送执行状态与输出（agents.rs 第 948-952 行、第 1126-1127 行）。

关键特性

1. 版本控制：每次导出都包含版本元数据，导入时强制校验（仅支持 v1）；
2. 重复预防：重名智能体自动追加(Imported)后缀；
3. 模型选择：在 Opus、Sonnet、Haiku 之间自由切换；
4. GitHub 集成：可直接从官方仓库导入。

🚀 执行机制：智能体如何跑起来

虽然 README 未展开执行细节，但源码清晰地展示了智能体执行的完整链路，对理解"预置智能体"的实际运行至关重要（agents.rs 第 679-785 行）：

1. execute_agent读取智能体配置，若配置了hooks会在项目目录生成.claude/settings.json；
2. 以claude二进制启动进程，参数包括-p <task>（默认任务）、--system-prompt <system_prompt>（智能体指令）、--model <model>、--output-format stream-json、--verbose与--dangerously-skip-permissions；
3. 从 stdout 的 JSONL 输出中提取session_id并实时写回数据库；
4. 前端通过AgentExecution.tsx与AgentRunsList.tsx实时展示进度，运行结束后从 Claude 的.claude/projects/<encoded-project>/<session_id>.jsonl读取会话内容，并解析出时长、Token 用量与成本等指标（AgentRunMetrics::from_jsonl，agents.rs 第 99-167 行）。

例如，在目标仓库执行Git Commit Bot的默认任务 "Push all changes."，智能体会读取本地 git 状态、分析 diff、生成 Conventional Commits 格式的提交信息并推送远程；执行Unit Tests Bot的 "Generate unit tests for this codebase." 则会按六个阶段产出测试文件与覆盖率报告。

🧠 深度剖析：三个预置智能体的提示词工程

Git Commit Bot：把 Git 工作流变成智能体任务

git-commit-bot.opcode.json 采用结构化提示词：<task>声明角色目标，<instructions>规定操作顺序，<notes>给出兜底策略。其核心指令流程为：

1. 先git fetch检查本地是否落后于远程，若存在未同步提交则git pull，冲突时按"保守优先、保持既有行为"的原则手动解决；
2. 分析git diff与git status，识别增删改文件、变更性质（修复/新功能/重构）与影响范围；
3. 按 Conventional Commits 规范撰写提交信息：类型从feat、fix、docs、style、refactor、perf、test、chore中选取，必要时加(scope)，描述用一般现在时，可附加多行说明、破坏性变更与关联 issue；
4. 最终推送到远程；无法确定分支名时默认使用main。

Security Scanner：子代理编排的六阶段 SAST

security-scanner.opcode.json 是最复杂的预置智能体，采用"编排者 + 子代理"模式，通过Task工具派生子代理依次执行六个阶段：

1. 代码库情报收集（Codebase Intelligence Analyzer）：提取语言/框架/依赖、架构模式、认证机制、数据存储、外部集成、输入校验、加密实现、会话管理与已知 CVE；
2. 威胁建模（Threat Modeling Specialist）：识别资产、信任边界、入口点，并对每个组件做 STRIDE（伪装、篡改、否认、信息泄露、拒绝服务、权限提升）分析；
3. 漏洞扫描（Vulnerability Scanner）：针对注入、认证与会话、访问控制、数据暴露、密码学问题、业务逻辑与配置错误七大清单逐项扫描，并要求从 source 到 sink 追踪完整数据流、映射 CWE；
4. 利用开发与验证（Exploit Developer）：为每个漏洞编写最小 PoC，验证可复现性与真实性、排除误报；
5. 修复设计（Security Architect）：给出即时修复、长期方案与纵深防御（主修复 + 补偿控制 + 检测机制 + 应急响应）；
6. 报告生成（Security Report Writer）：产出包含执行摘要、技术摘要、HackerOne 格式详细发现、修复路线图（<1 天 / 1-7 天 / >7 天）与附录的专业报告。

该智能体还内嵌了完整的漏洞报告模板（含 CVSS 3.1 评分、CWE/OWASP 映射、数据流分析、PoC、影响与修复代码示例）与严重级别分类标准（Critical/High/Medium/Low/Informational），并设有一份质量保证清单：可验证性、source-to-sink 确认、修复已测试、无误报、业务上下文考量、CWE/OWASP 映射准确。

Unit Tests Bot：六阶段自动化测试流水线

unit-tests-bot.opcode.json 同样采用子代理编排，分六阶段推进：

1. 代码库分析：确认语言/框架、既有测试框架与模式、代码风格约定、目录结构与测试文件位置；
2. 测试规划：识别全部可测模块并按优先级分类（critical/high/medium/low），定义各模块场景、边界条件与覆盖率目标；
3. 测试生成：为每个模块派发 Test Writer，要求遵循既有测试约定、含正/负/边界场景、合理 mock 外部依赖、保证测试独立可重复；
4. 测试验证：执行测试套件、捕获失败项、检查 flaky 测试、度量覆盖率、验证隔离性与无副作用；
5. 覆盖率优化：针对未覆盖路径与分支补测，兼顾变异测试（mutation testing）抵抗性；
6. 文档生成：产出测试套件总览、覆盖率汇总、运行与维护指南、CI/CD 集成说明。

此外该智能体还固化了风格一致性规则（命名/结构/导入/断言/注释风格与主代码库保持一致）、测试质量准则（单一目的、命名含预期结果、可任意顺序运行、失败要有意义、关注行为而非实现细节）与最终检查清单（所有源文件有对应测试、覆盖率达标、测试稳定通过、无硬编码与环境依赖、文档完整、CI/CD 已配置）。

🤝 贡献你的智能体

欢迎向仓库贡献新的智能体，官方推荐的流程如下：

1. 创建智能体：在 opcode 中设计并测试你的智能体，确保用途清晰、聚焦；
2. 导出智能体：导出为.opcode.json文件，取一个描述性名称；
3. 提交 Pull Request：
   • Fork 本仓库；
   • 将.opcode.json文件放入cc_agents目录；
   • 更新本 README，补充你的智能体信息；
   • 提交 PR 并说明智能体功能。

智能体编写指南

• 单一职责：每个智能体只专精于一个特定任务；
• 文档清晰：编写完整的系统提示词（参考上面三个预置智能体的<task>/<instructions>/<notes>分层结构）；
• 模型选择：简单任务用 Haiku，通用任务用 Sonnet，复杂推理用 Opus；
• 命名规范：使用能清晰表明功能的描述性名称。

从源码可进一步印证：system_prompt是智能体的灵魂，它会被完整注入 Claude Code 的--system-prompt参数（agents.rs 第 756-768 行），因此提示词质量直接决定智能体行为表现；同时default_task会在网格卡片点击执行时作为默认任务传入。

📜 许可证

这些智能体与 opcode 项目采用相同的许可证，详见仓库根目录的 LICENSE。

总而言之，cc_agents/目录既是三个可直接投入使用的 AI 智能体（Git Commit Bot、Security Scanner、Unit Tests Bot），也是一套完整的"智能体分发格式 + 导入导出 + 执行调度 + 实时监控"工程实践范本。借助.opcode.json这一带版本控制的交换格式，任何人都可以低成本地复用、改写并反向贡献智能体，这正是 opcode CC Agents 设计的核心价值所在。

• 桌面应用
• AI 应用
• AI Agent