企业官网建设流程全解析

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务

FIT Framework（ModelEngine/fit-framework）在仓库.opencode/目录中内置了一套完整的 OpenCode 配置与自定义命令体系：通过 oh-my-opencode 插件扩展能力，将「需求分析 → 技术方案 → 代码实现 → 代码审查 → 提交合并」的全流程封装为一组 Slash Commands，并配合.ai-agents/多 AI 协作体系实现任务跟踪与上下文共享。读完本文你将掌握：如何安装插件、理解每条命令的职责与参数、掌握!Shell 注入 /@文件引用 /$1与$ARGUMENTS占位符语法，以及如何按照仓库自带规范编写新的自定义命令。

一、.opencode目录是什么

.opencode/是 FIT Framework 项目的 OpenCode 配置目录，集中存放自定义命令与相关说明。OpenCode 支持以 Markdown 文件 + YAML frontmatter 的形式定义 Slash Commands，本文档即围绕这套命令体系展开：

说明：.opencode/README.md中的目录树列出的是 18 个命令文件，而当前仓库实际包含 20 个命令文件（额外包含create-release-note.md、release.md、test-integration.md，且plan-task.md、implement-task.md、review-task.md、refine-task.md、check-task.md、block-task.md、complete-task.md为完整命名，README 中对应简写为plan.md、implement.md等）。下文以.opencode/commands/目录中实际存在的文件为准。

二、插件安装

本项目通过 oh-my-opencode 插件（npm 包名为@opencode-ai/plugin）扩展自定义命令能力。clone 项目后执行一次依赖安装：

cd .opencode && bun install

如未安装 Bun，也可使用npm install或pnpm install。

从 package.json 可以看到插件的精确版本声明：

{ "dependencies": { "@opencode-ai/plugin": "1.2.0" } }

bun.lock锁定了该插件的传递依赖链：@opencode-ai/plugin@1.2.0依赖@opencode-ai/sdk@1.2.0与zod@4.1.8，保证不同开发者、不同环境安装出的依赖版本一致。

三、可用命令总览

1. 任务管理工作流命令

完整任务管理流程共 10 个命令，覆盖从创建任务到归档的整个生命周期：

2. Git 和 PR 管理命令

3. 依赖和安全管理命令

4. 测试与发布命令

其中/test与/test-integration的完整实现可参考 test.md 与 test-integration.md：/test会依次执行mvn -f framework/pom.xml clean install -pl '!ohscript' -DskipITs构建、加载.ai-agents/scripts/fit-service.sh公共脚本、启动 FIT 服务并等待健康检查（最多 60 秒）、执行verify_all验证健康检查/插件列表/Swagger 文档等接口，最后清理环境——整个过程约 15-20 分钟；/test-integration则要求先存在build/目录，仅做服务启动与接口验证（约 1-2 分钟）。

四、任务管理核心工作流详解

命令的具体实现均位于.opencode/commands/下，以下是各阶段命令的执行要点：

1. 创建与分析阶段

/create-task <description>（create-task.md）：将用户自然语言描述视为「待办事项」而非「立即执行的指令」，严格只产出task.md与analysis.md两个文件，禁止编写任何业务代码。执行时会校验参数非空、获取时间戳、创建.ai-workspace/active/TASK-$(date +%Y%m%d-%H%M%S)/任务目录，并从描述中推断任务类型（包含「添加/新增/支持」→ feature，包含「修复/解决/Bug」→ bugfix，包含「重构/优化/改进」→ refactor，包含「文档/Javadoc/注释」→ docs，其他 → chore）及对应工作流。

/analyze-issue <issue-number>（analyze-issue.md）：通过gh issue view $1 --json number,title,body,labels拉取 Issue 信息，同样创建任务目录与analysis.md需求分析文档。与create-task的区别在于：前者从自然语言描述创建（相关 Issue 标记为「无」），后者从 Issue 创建。

/analyze-security <alert-number>（analyze-security.md）：通过gh api repos/{owner}/{repo}/dependabot/alerts/<alert-number>获取 Dependabot 安全告警，提取 GHSA ID、CVE ID、严重程度（critical/high/medium/low）、受影响版本范围、首个修复版本等关键信息，在analysis.md中完成受影响范围分析与可利用性风险评估。该命令只做信息收集与风险评估，不制定具体修复方案——修复方案留给/plan-task阶段。

2. 方案设计阶段

/plan-task <task-id>（plan-task.md）：按active → blocked → completed优先级查找任务目录（{task-id}格式为TASK-{yyyyMMdd-HHmmss}，如TASK-20260205-202013），读取analysis.md后设计技术方案，输出plan.md，必须包含方案决策、技术方案、实施步骤、文件清单、验证策略、影响评估、风险控制、回滚方案、预期产出等章节。这是一个必须的人工检查点：方案设计完成后等待人工审查，审查通过才能进入实施阶段。

3. 代码实现阶段

/implement-task <task-id>（implement-task.md）：验证task.md与plan.md存在后，严格按照方案分步实现代码、编写单元测试、本地运行测试（mvn test -pl :{module-name}/npm test/pytest），输出implementation.md实现报告（含已修改文件列表、关键代码说明、测试结果、待审查事项、已知问题）。注意：不要自动执行 git commit，实现完成后等待代码审查。

4. 代码审查与修复阶段

/review-task <task-id> [--pr-number]（review-task.md）：读取implementation.md后按 CLAUDE.md 规范审查代码质量、Bug、测试覆盖、错误处理、性能与安全，输出review.md审查报告。问题按 🔴 必须修复（Blocker）/ 🟡 建议修改（Major）/ 🟢 优化建议（Minor）分级，最后给出批准/修改后批准/需要重大修改的结论。可选--pr-number参数调用/code-review:code-review或/pr-review-toolkit:review-pr做更深度的并行代理审查。

/refine-task <task-id>（refine-task.md）：当审查发现需要修改时，使用 TodoWrite 规划修复清单，按「先 Blocker → 再 Major → 最后 Minor」的优先级逐项修复，运行测试验证后创建refinement-report.md修复报告，并更新current_step: refinement。修复完成后可重新/review-task或直接/commit。

5. 状态管理与归档阶段

/check-task <task-id>（check-task.md）：读取任务文件并检查analysis.md/plan.md/implementation.md/review.md上下文文件，输出结构化的任务状态报告（基本信息、当前状态、工作流进度、上下文文件清单、下一步建议），并依据所处阶段自动推荐下一个命令。

/complete-task <task-id>（complete-task.md）：有严格的前置条件检查——所有工作流步骤完成、代码审查通过（review.md 显示批准）、代码已提交、测试全部通过等，全部满足才执行：更新status: completed、在 task.md 末尾添加「任务完成总结」章节、mv归档到.ai-workspace/completed/并验证移动成功。

/block-task <task-id>（block-task.md）：适用于编译失败无法修复、测试失败原因不明、依赖库存在 Bug、需求不明确、等待外部依赖、需要架构决策等场景（注意：代码审查发现问题应使用/refine-task而非阻塞）。执行时记录阻塞类型/根本原因/尝试的解决方案/需要的帮助/解除阻塞条件，更新status: blocked并移动到.ai-workspace/blocked/。

6. 完整功能开发流程示例

# 0. 从自然语言描述创建任务（无 Issue 时使用） /create-task 给 fit-runtime 添加优雅停机功能 # 1. 或者从 Issue 创建任务 /analyze-issue 207 # 2. 设计技术方案 /plan-task TASK-20260120-104654 # 3. 实施功能 /implement-task TASK-20260120-104654 # 4. 代码审查 /review-task TASK-20260120-104654 # 5. 如果有问题需要修复 /refine-task TASK-20260120-104654 # 6. 提交代码 /commit # 7. 创建 PR /create-pr # 8. 标记任务完成 /complete-task TASK-20260120-104654

7. 依赖升级流程

# 1. 升级依赖 /upgrade-dependency swagger-ui 5.30.0 5.30.2 # 2. 提交变更 /commit

/upgrade-dependency（upgrade-dependency.md）会先grep在pom.xml/package.json/build.gradle/requirements.txt中定位依赖声明，更新版本号后同步更新静态资源引用（CDN 链接、文档版本说明），随后按项目类型执行编译验证（Maven/Node.js/Gradle 各有对应的构建命令与日志落盘）并运行测试，最后输出变更摘要。注意：升级后不要自动 git commit，等待人工检查，且一次只升级一个依赖。

8. 安全告警处理流程

# 1. 分析安全告警 /analyze-security 23 # 2. 设计修复方案 /plan-task TASK-20260120-110000 # 3. 实施修复 /implement-task TASK-20260120-110000 # 4. 代码审查 /review-task TASK-20260120-110000 # 5. 提交修复 /commit # 6. 创建 PR /create-pr # 7. 标记任务完成 /complete-task TASK-20260120-110000 # 或者如果是误报 /close-security 23

/close-security <alert-number>（close-security.md）在关闭 Dependabot 告警前强制要求用户确认并提供合理理由，理由选项包括：误报（not_used）、无法利用（tolerable_risk）、已有缓解措施（tolerable_risk）、无修复版本且风险可接受（tolerable_risk）、测试或开发依赖（not_used）。最终通过gh api --method PATCH ... -f state=dismissed执行关闭，并要求用户输入至少 20 个字符的详细说明。文档明确提醒：关闭应是最后选择，优先考虑修复，且谨慎关闭 Critical/High 高危告警。

五、命令语法核心：参数占位符、Shell 注入与文件引用

1. 参数占位符

$1vs$ARGUMENTS的区别（这是最容易踩坑的地方）：

当用户输入/create-task 给 fit-runtime 添加优雅停机功能时：

• $1=给（仅第一个词）
• $ARGUMENTS=给 fit-runtime 添加优雅停机功能（完整字符串）

因此，自由文本参数（如任务描述）必须使用$ARGUMENTS，否则只能拿到第一个词。

可选参数处理：未提供的参数会被替换为空字符串。对于可选参数，应使用「声明 + 判空」的写法，例如 create-pr.md 中的目标分支推断逻辑：

1. 确定目标分支: 用户指定的目标分支: $1 如果上述值为空,自动推断目标分支: !`git branch --show-current` !`git log --oneline --decorate --first-parent -20` 根据当前分支类型和 log 中的分支标记推断目标

2. Shell 输出注入（!符号）

OpenCode 支持使用!符号注入 bash 命令输出：

!`date +%Y` # 注入当前年份 !`git status` # 注入 git 状态 !`gh issue view $1 --json title` # 注入 Issue 信息

命令编写规范（见 COMMAND_STYLE_GUIDE.md）强制要求：所有 Shell 命令、Git 操作、GitHub CLI 调用、动态值获取、文件系统操作、构建测试命令都必须使用!标记；```bash代码块仅用于展示示例代码（不执行）；解释性说明、指导 AI 使用工具、条件判断逻辑则使用自然语言。

3. 文件引用（@符号）

使用@符号引用文件内容：

@src/components/Button.tsx # 引用文件内容

六、自定义命令格式（如何编写新命令）

所有命令文件使用 Markdown 格式，带有 YAML frontmatter：

--- description: 命令描述 agent: general # 使用的 agent (general/explore/build) subtask: false # 是否作为子任务运行 model: anthropic/claude-3-5-sonnet-20241022 # 可选：指定模型 --- 命令的 prompt template 内容... 可以使用: - !`shell command` 注入命令输出 - @file-path 引用文件 - $1, $2 访问参数

frontmatter 字段含义：

七、命令编写规范要点（COMMAND_STYLE_GUIDE 精要）

COMMAND_STYLE_GUIDE.md 是这套命令体系沉淀出的编写规范（基于 17 个命令的优化经验总结），核心要求包括：

1. 错误处理规范——所有关键命令都应添加执行状态检查：

# ❌ 不好 - 无错误检查 !`git status` # ✅ 好 - 基本错误检查 !`git status || echo "ERROR: Git status failed"` # ✅ 更好 - 详细错误提示 !`git status && echo "✅ Git status OK" || echo "❌ ERROR: Git status failed, is this a git repository?"`

文件/目录操作前必须验证存在性（test -f/test -d并输出友好提示），搜索命令提供「未找到」容错，API 调用捕获2>&1错误输出。

2. 参数验证规范——命令开始时验证必需参数：

0. 参数验证: !`test -n "$1" || (echo "❌ ERROR: 任务ID不能为空，用法: /command <task-id>" && exit 1)` !`echo "任务ID: $1"`

3. 时间戳处理规范——始终通过!date '+%Y-%m-%d %H:%M:%S'`` 获取，绝对不要硬编码，且不要在 YAML/Markdown 代码块中使用!（代码块中的!不会被执行）。

4. GitHub API 路径规范——使用gh cli的占位符（repos/{owner}/{repo}/...）而非硬编码仓库路径。

5. 可读性规范——使用 Emoji 增强反馈可读性（✅/❌/⚠️/📋），长命令拆分说明，复杂逻辑抽取为独立脚本（如./.ai-agents/scripts/update-copyright.sh），步骤编号连续清晰。

6. 不要做的事——不要在 YAML/Markdown 代码块中使用!；不要硬编码动态值；不要忽略错误处理（静默失败）；不要在执行意图不明的地方使用bash代码块。

八、与.ai-agents多 AI 协作体系的关系

.opencode/命令体系不是孤立的，它与 .ai-agents/README.md 描述的多 AI 协作机制深度联动：

• 任务工作区共享：所有命令读写.ai-workspace/{active|blocked|completed}/{task-id}/下的task.md、analysis.md、plan.md、implementation.md、review.md等文件，这些文件构成任务的完整上下文，任何 AI 都可以通过读取它们接手任务。
• 任务模板：命令创建task.md时基于 .ai-agents/templates/task.md 模板，包含 YAML frontmatter（id、type、workflow、status、created_at、current_step、assigned_to等）、工作流进度、交接信息、状态更新检查清单。
• 工作流定义：命令执行时严格遵循 .ai-agents/workflows/feature-development.yaml 等工作流定义。例如 feature-development 工作流定义了requirement-analysis → technical-design → implementation → code-review → refinement → finalize六个步骤，每个步骤声明能力要求、推荐 AI、任务清单、输入输出文件；/plan-task对应technical-design步骤，/implement-task对应implementation步骤，/review-task对应code-review步骤，/refine-task对应refinement步骤。
• 人工检查点：工作流明确标注了必须的人工检查点——technical-design（技术方案设计后）与finalize（最终提交前）为required: true，这与命令文档中「方案设计完成后等待人工审查」的设计一致。
• Git 与协作：/commit（commit.md）提交前会先检查用户本地修改（git status --short+git diff，禁止覆盖用户实现）、检查并更新版权头年份（如Copyright (C) 2024-2025→Copyright (C) 2024-2026，绝不要硬编码年份），生成 Conventional Commits 格式的提交消息（<type>(<scope>): <subject>+ body +Co-Authored-By签名）并使用 HEREDOC 执行多行提交；/sync-issue与/sync-pr则分别面向项目管理者和代码审查者，将任务进度摘要（已完成步骤、当前进展、下一步、相关文件）通过gh issue comment/gh pr comment同步到评论区。

九、最佳实践与使用建议

1. 使用完整工作流：按照 analyze → plan → implement → review → commit 的顺序执行，不要跳过阶段；
2. 人工检查点：在 plan 和 review 步骤后进行人工审查，这是工作流定义中required: true的必经环节；
3. 任务状态管理：使用/check-task随时查看任务进度，所有命令执行后必须更新current_step/updated_at/assigned_to字段（违反将导致任务状态追踪失败）；
4. 及时同步：使用/sync-issue和/sync-pr保持沟通，建议在完成一个完整阶段后同步，避免频繁评论；
5. 阻塞处理：遇到无法解决的问题及时使用/block-task标记，记录详细阻塞原因、需要的帮助与解除阻塞条件；
6. 区分创建来源：/create-task面向自然语言描述（Issue 标记为「无」），/analyze-issue面向 GitHub Issue，按场景选择；
7. 版本发布：/release负责 SNAPSHOT 替换、Release commit、Tag、发布分支与下一 SNAPSHOT 的完整流程，且明确排除.ai-agents/、.ai-workspace/、.opencode/等 AI 工具配置目录免受版本替换影响；/create-release-note则从 PR/commit 自动生成结构化 Release Notes 并创建 GitHub Draft Release（x.y.0 版本走合并路径聚合前一 minor 系列的已发布 notes）。

十、相关文档

• OpenCode 官方文档
• FIT Framework AI 协作指南
• AI 协作快速开始
• OpenCode 命令编写规范

如需添加新命令或修改现有命令：在.opencode/commands/目录创建.md文件，按照「YAML frontmatter + prompt template」格式编写，测试命令是否正常工作，最后更新本 README 文档。

• 人工智能
• 大模型
• AI 应用
• 后端
• AI Agent
• RAG
• 流程编排
• 微服务