前面四篇都能跑了，怎么把它收成一个可维护的工程？哪些该做成 Skill？

前面四篇我们搭了一个项目助理 Agent：

• 01：接入系统智能入口
• 02：A2A Server 能力暴露
• 03：长任务状态机
• 04：消息、鉴权和 Artifact

现在能跑了。但问题是：代码都堆在一起，功能越来越多，怎么整理成一个可维护的工程？哪些能力该做成 Skill？

一、先想清楚：Skill 和 Agent 有什么区别

先把最基础的问题想明白。

对比	Agent	Skill
粒度	一个完整的智能体	一个具体的能力
入口	系统智能入口调用	Agent 内部调用
生命周期	长，管对话	短，执行一个任务

Agent 是"人"，Skill 是"技能"。一个 Agent 有多个 Skill。

二、skillProfiles 是什么

skillProfiles 就是应用技能的描述。你在模块配置里声明你的应用有哪些 Skill，每个 Skill 关联哪个 Ability、需要什么权限。

这段代码解决什么问题： 声明应用技能。
文件： module.json5
用途： Skill 化改造
接入位置： 模块配置

{
  "skillProfiles": [
    {
      "name": "analyze_project",
      "abilityName": "ProjectAssistantAbility",
      "srcEntries": "./skills/analyze_project.js",
      "permissions": ["ohos.permission.READ_FILE"]
    },
    {
      "name": "generate_report",
      "abilityName": "ReportAbility",
      "srcEntries": "./skills/generate_report.js",
      "permissions": []
    }
  ]
}

三、什么功能适合做成 Skill

不是什么功能都做成 Skill。

适合做 Skill	不适合做 Skill
独立的具体能力	核心业务逻辑
可能被多次复用	内部状态管理
输入输出清晰	UI 交互逻辑
权限边界明确	和业务强耦合的

判断标准：这个能力是不是独立的？能不能单独调用？输入输出是不是清晰？

四、Agent 协议层为什么不能和业务硬耦合

这里有个很重要的工程经验：Agent 协议层不要和业务逻辑硬耦合。

为什么？因为 Agent API 还在变。Beta 阶段接口调整很正常：早期的 AgentOperation 被删了，OnDataCallback 参数改成字符串类型。

层	内容	稳定性
协议层	A2A、TaskState、AgentCard	可能变
业务层	项目分析、报告生成	稳定

如果硬耦合，API 一变，业务代码全得改。要分开：协议层只管通信，业务层管逻辑。

五、工程收口怎么收

最后把前面四篇整理一下：

1. 业务层：项目分析、报告生成，和 Agent 无关；
2. 协议层：AgentController、A2A Server、TaskState，管通信；
3. Skill 层：把独立能力抽成 Skill，声明权限；
4. 入口层：系统智能入口、普通页面，两个入口复用业务逻辑。

六、几个容易踩的坑

第一个坑：什么功能都做成 Skill。Skill 太多，维护不过来。

第二个坑：Skill 直接访问内部数据库实现。权限边界没管好。

第三个坑：权限声明过宽。用不到的权限也声明了。

第四个坑：Skill 名称和业务版本强绑定。版本一变，名称就不对了。

第五个坑：Agent 和 Skill 重复实现一套逻辑。两边都写了一遍。

第六个坑：升级 API 后不检查 A2A 接口变化。API 变了，代码就挂了。

这次做工程收口最大的体会是：Agent 应用不只是"能跑就行"。要分层、要解耦、要把协议层和业务层分开。

真正做的时候，最容易忽略的不是怎么实现功能，而是怎么管好边界。哪些是业务、哪些是协议、哪些是 Skill，分清楚了，后面维护才不会乱。