AgentSkills Runtime ：AI驱动开发框架

项目简介

AgentSkills Runtime 是一个基于仓颉编程语言实现的 Agent Skills 标准运行时环境。它是对 AgentSkills 开放标准的国产技术栈实现，提供了安全、高效的 AI 智能体技能执行环境。旨在让 AgentSkills 能够在任何地方运行。同时提供了多语言SDK适配各种技术栈。开源项目地址：https://atomgit.com/uctoo/agentskills-runtime 和 https://github.com/UCTooCom/agentskills-runtime 。配套的AIAgent Dashboard开源项目 https://atomgit.com/UCToo/web-admin

产品截图

AI Builder 组织任务管理	开发者需求对接

组织管理	Token 用量仪表盘

PC 端桌面客户端——最快上手方式

对绝大多数只想”用起来”的用户，最快的方式是安装 PC 端桌面客户端，无需克隆源码、配置仓颉工具链或手动建库。桌面客户端把仓颉语言实现的 runtime 内核、内嵌 PostgreSQL、以及 web-admin 管理前端打包成一个”安装即用”的整体。

开源地址：https://atomgit.com/UCToo/agentskills-runtime-pc
技术栈：Electron 42 + Vue 3 + Vite 8
当前版本：0.1.0 · 应用 ID：com.uctoo.agentskills-runtime-pc · 产品名：AgentSkills Runtime
客户端职责：首次启动自动解压 runtime、初始化 PostgreSQL、生成 .env 配置；随后自动拉起 PostgreSQL → runtime → web-admin 服务链，进入 AI Builder 首页即可使用
附加能力：注册 agentskills:// 自定义协议、支持开机自启与系统托盘、内置 electron-updater 自动更新

操作步骤：

前往发布页下载对应平台安装包：https://atomgit.com/UCToo/agentskills-runtime-pc/releases
Windows 用户双击 AgentSkills Runtime-Windows-<version>-Installer.exe 走标准安装向导，或下载 ...-Portable.exe 免安装便携版
macOS 用户下载 AgentSkills Runtime-Mac-<version>-Installer.dmg
Linux 用户下载 AgentSkills Runtime-Linux-<version>.AppImage
安装完成后启动应用，首次运行会自动完成环境初始化，随后进入 AI Builder 首页即可使用

自动更新地址：https://atomgit.com/UCToo/agentskills-runtime-pc/releases/download/<version>/，客户端内置 electron-updater，新版本发布后会自动提示升级。

如果你希望直接从源码运行 runtime 内核（例如服务器部署或二次开发），请继续阅读下方的「概述」与「快速开始」章节。

概述

AgentSkills Runtime 是一个全面的框架，用于构建和执行 AI 智能体技能。它为遵循 agentskills 标准的 AI 智能体工具提供了安全、便携和智能的运行时环境。该框架基于仓颉编程语言构建，并融合了UCToo项目架构的先进特性。

该框架包括：

对 agentskills 标准的支持，包括 SKILL.md 文件的加载和验证
DSL 支持，包含 @skill、@tool 和 @agent 宏
清晰的关注点分离的整洁架构（领域层、应用层、基础设施层）
MCP（Model Context Protocol）支持，用于与 AI 智能体集成
技能到工具的适配器，实现技能与工具的兼容性
从可配置目录进行渐进式技能加载
基于 WASM 的安全沙箱，用于安全的技能执行
具有混合密集+稀疏搜索能力的高级 RAG 搜索
多格式技能支持（WASM 组件和 SKILL.md 文件）

🎯 项目愿景

打造国产自主可控的 AI 智能体技能运行时，推动 Agent Skills 标准在AI生态中的落地应用，构建开放、安全、高效的 AI 原生应用基础设施。旨在让 AgentSkills 能够在任何地方运行。

落地案例与价值说明书 (Business Case & Value Proposition)

参赛作品：金融行业应用 Agent 黑客松（2026/07/27 - 2026/08/08） 演示视频：智能投研助理 Demo 录屏 项目源码：https://atomgit.com/UCToo/agentskills-runtime 技术文档：本 README（产品文档 + 架构设计 + 核心模块 + 性能数据）

4.1 落地场景

本作品面向金融行业真实业务场景，以”智能投研助理（Investment Research Assistant）”为典型落地应用，实现金融行业 Agent 核心场景”自动抓取 → 数据清洗 → 要素提取 → 研报生成 → 结果落库 → 每日投资简报”的全流程自动化：

智能投研与每日投资简报：自动抓取行情/公告/新闻等多源数据，清洗去重，提取估值、财务、事件、情绪等关键投资要素，生成结构化每日投资简报，按公司写入 company 表、研报内容写入 tasks 表，通过 aibuilder 模块可视化呈现，替代人工整理研报的低效流程。
金融行业 Agent 基础设施：AgentSkills Runtime 提供标准化的技能运行环境（SKILL.md 加载校验、WASM 沙箱、RBAC 权限、MCP/WebMCP 集成、审计日志），金融业务 Agent 可在其上快速开发与安全运行，满足信创与合规要求。
金融业务系统集成：基于仓颉语言高性能应用服务器（HTTP/HTTPS、WebSocket、SSE），Agent 与传统金融 ICT 基础设施无缝集成，打通数据抓取、分析、落库、呈现的完整闭环。

4.2 目标客户

客户类型	典型场景	价值主张
券商/基金投研部门	每日投资简报、个股分析、行业研报	研报生产效率提升，标准化输出
银行/保险财富管理	客户持仓分析、市场资讯聚合	投顾内容自动化，提升服务覆盖面
金融科技公司	Agent 应用开发平台、投研数据服务	快速交付业务 Agent，降低开发成本
金融监管/研究机构	市场数据监测、舆情分析	数据合规留痕，审计可追溯
开发者/开源社区	Agent 技能开发、标准实践	开放标准、国产自主可控技术栈

4.3 商业模式

开源社区版（免费）：AgentSkills Runtime 以 MIT 协议开源，提供完整技能运行环境与智能投研助理技能（investment-research-assistant），吸引开发者生态共建。
企业私有化部署（License）：面向金融机构提供私有化部署版本，内置 PostgreSQL、RBAC 权限体系、审计日志、国产化技术栈（仓颉 + 昇腾算力），满足金融信创与数据安全要求，按年度 License 收费。
云服务订阅（SaaS）：提供托管式 Agent 运行平台与智能投研服务订阅，按席位/调用量计费，降低中小金融机构的 AI 应用门槛。可与公有云及大模型厂商等产业链上下游合作，开源项目已支持云原生部署和多渠道大模型接入。
增值服务：行业技能定制开发、数据源接入集成、系统部署运维、培训与技术支持等专业服务收入。

4.4 参赛作品：智能投研助理技能（investment-research-assistant）

本次参赛核心交付物为 skills/investment-research-assistant 技能，实现”自动抓取 → 数据清洗 → 要素提取 → 研报生成 → 结果落库 → 每日投资简报“六步全流程 SOP：

环节	实现	说明
1. 自动抓取	`scripts/fetch_market_data.py` + `web_fetch` / `http_request`	行情/公告/新闻/宏观多源合规数据抓取
2. 数据清洗	`scripts/clean_market_data.py`	去重、去噪、格式统一、无效数据剔除
3. 要素提取	`scripts/extract_factors.py`	估值/财务/事件/情绪等投资要素
4. 研报生成	昇腾 API（AtomGit）大模型	结构化每日投资简报（含结论/看点/风险提示）
5. 结果落库	`scripts/save_report_to_db.py`	公司写入 `company` 表、研报写入 `tasks` 表
6. 简报输出	`COMPOSITION.yaml` 声明式编排	通过 aibuilder 模块可视化呈现

输入参数：companies（如 600519,000858）、date、data_sources、output_dir
输出产物：output/raw/、output/clean/、output/factors/、output/brief/ + 数据库落库记录
算力底座：昇腾 AI（AtomGit 昇腾 API，OpenAI 兼容接口，通过 runtime .env 配置）

如何使用与复现：

# 方式一：通过 runtime 技能执行（推荐，走全流程编排）
skill run investment-research-assistant:generate-daily-brief companies="600519,000858"

# 方式二：直接运行脚本（逐步复现）
python3 scripts/fetch_market_data.py --companies "600519,000858"
python3 scripts/clean_market_data.py --input output/raw/2026-08-07.json
python3 scripts/extract_factors.py --input output/clean/2026-08-07.json
python3 scripts/save_report_to_db.py --report output/brief/2026-08-07.md

4.5 规范驱动开发方法论（评审指南）

本作品严格遵循规范驱动开发（Specification-Driven Development）方法论，全流程按”需求规格 → 技术设计 → 任务清单 → 编码落地 → 验证发布”的规范链路交付，全部工程文档位于 .codeartsdoer/specs/fintech-agent-hackathon/ 目录：

文档	定位（定义什么）	评审重点
`comp.md`	赛事要求（比赛规则 / 评审标准）	对照金融场景、必须能跑、解决真问题三个硬性要求
`spec.md`	需求规格（做什么）	功能范围、六步 SOP、合规与安全边界
`design.md`	技术设计（怎么做）	总体架构图、技术选型、数据流设计
`tasks.md`	编码任务清单（按什么顺序做）	阶段划分与完成状态（Phase 0-5）
`publish.md`	提交要求（交付什么）	交付件清单（可运行代码 + 录屏 + 技术文档 + 商业化说明）

评审建议：评委可先阅读 comp.md 对照赛事要求，再按 spec.md → design.md → tasks.md 顺序查阅工程文档理解设计链路；实际运行验证请参考 4.4 节”如何使用与复现”步骤，重点考察作品是否满足”金融场景、必须能跑、解决真问题”三个硬性要求，以及是否运行在昇腾 AI 算力底座之上。

4.6 演示视频

https://atomgit.com/UCToo/agentskills-runtime/blob/main/public/demo.mp4

也可下载演示视频本地观看。

架构设计

该实现遵循整洁架构原则，采用三层架构设计，具有清晰的关注点分离：

三层架构

Controller 层（表示层）：处理 HTTP 请求和响应，管理 API 端点
Service 层（应用层）：业务逻辑处理，协调用例（SkillManagementService、AgentSkillsService 等）
Repository 层（基础设施层）：数据访问和外部资源管理（数据库、文件系统等）

核心模块

magic.app：主应用模块，提供完整的 API 服务
magic.core：核心领域模型和业务逻辑
magic.skill：技能管理和执行引擎
magic.model：AI 模型集成和管理

技术栈

HTTP 框架：自定义 HTTP 框架（封装 stdx.net.http），支持中间件
ORM 框架：Fountain ORM（f_orm），支持多种数据库
认证：JWT 认证（jwt4cj）
日志：结构化日志（logcj）
字符编码：多语言支持（charset4cj）

功能特性

智能体互联国家标准（GB/Z 185-2026）支持

AgentSkills Runtime 已实现对《人工智能智能体互联》国家标准（GB/Z 185.1~185.7-2026）的支持，采用双模式分层架构：

本地模式（Local Mode）：面向同一系统内 Agent 间协作场景，复用现有 uctoo_user + RBAC 体系进行身份管理，复用 agent_messages + agent_tasks 进行消息传递，扩展国标数据模型（ACS 描述格式、交互消息/任务/会话结构）。系统默认运行在本地模式。
互联模式（Interconnection Mode）：面向需要与外部系统智能体互联的场景，在本地模式基础上完整实现 GB/Z 185.2~185.7 能力，对接 ACPs 注册服务、CA 服务、发现服务、MQ 服务，叠加 AIC 身份码、CAI 凭证、mTLS 认证等分布式能力。互联模式是本地模式的超集。

核心能力

国标部分	能力	本地模式	互联模式
GB/Z 185.2	智能体身份管理（AIC/CAI）	uctoo_user + RBAC	ACPs 注册服务 + AIC + CAI + mTLS
GB/Z 185.3	智能体可信注册（ATR）	本地自动创建	ACPs 注册服务完整流程
GB/Z 185.4	智能体能力描述（ACS）	agents + agent_skills 表扩展	同步到 ACPs 注册/发现服务
GB/Z 185.5	智能体发现（ADP）	本地 agents 表查询	ACPs 发现服务跨系统发现
GB/Z 185.6	智能体交互协议（AIP）	agent_messages + agent_tasks	MQ 消息分发 + mTLS 认证
GB/Z 185.7	工具调用	复用 MCP 工具体系	复用 MCP 工具体系

数据库扩展

agents 表新增 AIP 相关字段：

字段	类型	说明
`aic`	varchar(128)	智能体身份码(AIC)，符合GB/Z 185.2 OID格式
`identity_status`	varchar(20)	AIP身份状态：none/active/locked/revoked
`aip_registered_at`	timestamptz	AIP身份注册时间
`capabilities`	jsonb	辅助功能描述(ACS)，符合GB/Z 185.4
`default_input_types`	jsonb	默认输入类型(ACS)，符合GB/Z 185.4
`default_output_types`	jsonb	默认输出类型(ACS)，符合GB/Z 185.4
`discoverable`	bool	是否允许被智能体发现，符合GB/Z 185.5

AGENTS.md 格式扩展

AGENTS.md 的 YAML frontmatter 已扩展支持 AIP 字段：

---
name: MainAgent
agent_type: main
description: 主 Agent 描述
identity_status: none          # AIP身份状态
discoverable: true             # 是否允许被发现
capabilities: []               # 辅助功能描述(ACS)
default_input_types: []        # 默认输入类型
default_output_types: []       # 默认输出类型
---

MQ 消息分发适配器

互联模式下通过 AcpsMqAdapter 实现 GB/Z 185.6 群组交互消息的可靠分发，基于 activemq4cj（仓颉 ActiveMQ SDK，JMS 2.0 规范实现）封装，支持：

点对点和发布/订阅双模式消息通道
持久订阅与事务消息
Failover 自动重连
TLS 加密连接
MQ 鉴权服务 ACL 校验

详细设计文档参见 .codeartsdoer/specs/aip-implementation/ 和 .codeartsdoer/specs/aip-mq-adapter/。

AgentSkills 标准支持

根据 agentskills 规范从 SKILL.md 文件加载技能
带验证的 YAML 前置元数据解析
用于技能指令的 Markdown 正文处理
外部资源访问（scripts/、references/、assets/）

DSL 支持

@skill 宏用于声明式技能定义
@tool 宏用于工具定义
@agent 宏用于智能体定义

安全性

基于 WASM 的安全沙箱，支持组件模型
基于能力的访问控制（文件系统、网络等）
资源配额和执行限制
执行上下文隔离

搜索与发现

具有混合密集+稀疏搜索的高级 RAG 搜索（向量嵌入 + BM25 与 RRF 融合）
交叉编码器重排序以提高精度
带意图分类和实体提取的查询理解
用于令牌高效输出的上下文压缩

多格式技能支持

支持组件模型的 WASM 组件执行
遵循 agentskills 标准的 SKILL.md 文件解析和执行
格式无关的技能接口
动态格式检测和验证

MCP 集成

从技能清单动态发现工具
与 MCP 协议的语义搜索集成
大型技能目录的分页支持
带嵌入式 Web UI 的 HTTP 流模式

多语言生态系统支持

跨语言互操作性：支持不同编程语言编写的技能在同一运行时环境中协同工作
语言适配器：为不同编程语言提供标准化的技能接口适配器
统一 API 层：抽象底层实现细节，提供一致的编程接口
依赖管理：智能处理多语言项目的依赖关系和版本冲突

多语言 SDK 支持

JavaScript/TypeScript SDK：完整的 Node.js 和浏览器环境支持，用于 Web 应用和前端集成
Python SDK：集成流行的 Python AI 和数据科学库，适用于数据分析和 AI 模型集成
Java SDK：企业级应用和 Android 平台支持，适用于大型企业系统
Go SDK：高性能并发处理和云原生应用支持，适用于微服务架构
Rust SDK：系统级性能和内存安全保证，适用于对性能要求高的场景
C# SDK：.NET 生态系统和 Windows 平台集成，适用于企业内部系统

SDK 核心价值

传统系统 + AI：为现有数字系统快速集成 AI 能力，无需重构现有架构
技能市场对接：通过 SDK 轻松访问技能市场，实现能力无限扩展
标准化集成：提供统一的 API 接口，简化跨语言集成复杂度
开箱即用：内置运行时安装和管理功能，无需手动配置运行环境
跨平台支持：同一套 API 适配不同技术栈，降低学习成本

内置工具 v2.0

AgentSkills Runtime v2.0 提供了完整的内置工具集,支持CLI、HTTP和内部API三种调用方式,所有工具都集成了RBAC权限体系。

工具分类

文件系统工具 (9个)

file_read - 文件读取 (敏感级别: 低)
file_write - 文件写入 (敏感级别: 中)
file_edit - 文件编辑 (敏感级别: 中)
file_delete - 文件删除 (敏感级别: 高,需确认)
file_copy - 文件复制 (敏感级别: 低)
file_move - 文件移动 (敏感级别: 中)
file_search - 文件搜索 (敏感级别: 低)
directory_list - 目录列表 (敏感级别: 低)
directory_create - 创建目录 (敏感级别: 中)

网络工具 (4个)

http_request - HTTP请求 (敏感级别: 中)
web_fetch - 网页抓取 (敏感级别: 低)
firecrawl - Firecrawl爬虫 (敏感级别: 中)
browser_tool - 浏览器工具 (敏感级别: 中)

技能工具 (2个)

skill_initializer - 技能初始化 (敏感级别: 中)
skill_packager - 技能打包 (敏感级别: 中)

代码生成工具 (2个)

template_engine - 模板引擎 (敏感级别: 低)
code_snippet_generator - 代码片段生成 (敏感级别: 低)

CLI工具 (1个)

cli_execute - CLI命令执行 (敏感级别: 高,需确认)

HTTP接口

基础路径: /api/v1/tools

接口列表:

GET /api/v1/tools/list - 获取工具列表
GET /api/v1/tools/:toolName/info - 获取工具信息
POST /api/v1/tools/:toolName - 调用工具

使用示例:

# 获取工具列表
curl -X GET https://javatoarktsapi.uctoo.com/api/v1/tools/list \
  -H "Authorization: Bearer <token>"

# 调用文件读取工具
curl -X POST https://javatoarktsapi.uctoo.com/api/v1/tools/file_read \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"path": "./SKILL.md"}'

权限体系

所有工具调用都受RBAC权限体系保护:

敏感级别: 低(1)、中(2)、高(3)
权限检查: 每次调用都验证用户权限
审计日志: 所有操作记录到数据库
二次确认: 高敏感操作需要确认参数

详细文档: 内置工具文档

高性能应用服务器

AgentSkills Runtime 内置了高性能HTTP/HTTPS应用服务器,提供企业级的API服务能力。

服务器特性

HTTPS支持: 内置SSL/TLS加密,支持证书配置
高性能路由: 基于Trie树的高效路由匹配
中间件系统: 可扩展的中间件链
WebSocket支持: 实时双向通信
连接池: 数据库连接池管理
缓存系统: 内置缓存管理器

核心组件

HTTPServer

支持HTTP/HTTPS协议
可配置的线程池
请求/响应拦截器
静态文件服务

Router

RESTful路由支持
路径参数提取
路由分组
中间件挂载

Middleware

DeserializeUserMiddleware - JWT认证
RequirePermissionMiddleware - 权限检查
CORSMiddleware - 跨域支持
LoggingMiddleware - 请求日志

服务配置

# .env 配置
PORT=443
HOST=0.0.0.0
SSL_CERT=./ssl/server.crt
SSL_KEY=./ssl/server.key
DB_URL=postgresql://user:pass@host:port/db

启动服务

# 编译
cjpm build

# 启动HTTPS服务
cjpm run --skip-build --name magic.app

API端点

GET /hello - 健康检查
GET /api/v1/health - 服务状态
GET /api/v1/info - 应用信息
/api/v1/uctoo/* - UCToo业务API
/api/v1/tools/* - 工具管理API
/api/v1/skills/* - 技能管理API

性能指标

并发连接: 支持1000+并发连接
响应时间: 平均响应时间 < 50ms
吞吐量: > 10000 req/s
内存占用: 基础内存 < 100MB

核心特性

🚀 高性能执行

高性能: 基于仓颉编程语言的高性能运行时
强安全: WASM 沙箱安全执行环境 + 多层权限控制的安全架构
标准化: 完全兼容 AgentSkills 开放标准规范

🔒 安全可靠

执行隔离: 多层安全防护机制
权限控制: 细粒度的权限管理和资源访问控制
审计追踪: 完整的操作日志和安全审计机制

📦 标准兼容

完全兼容 AgentSkills 开放标准
支持 SKILL.md 文件格式
实现标准的 YAML 前置元数据规范

🔧 易用性

简单集成: 提供简洁的 API 接口
丰富示例: 多样化的使用示例和最佳实践
详细文档: 完善的中英文技术文档

🔧 灵活扩展

插件化架构设计
支持自定义技能开发
丰富的 API 接口和工具集

快速开始

最简单的使用方案（推荐）

如果您想快速体验 AgentSkills Runtime 的功能，无需下载本项目源码，只需克隆 UCToo 项目即可：

部署步骤

克隆 UCToo 项目

git clone https://atomgit.com/UCToo/web-admin.git

运行安装助手
- 双击运行 web-admin/start-installer.bat（Windows系统）
- 或在命令行中执行：
```
cd web-admin
start-installer.bat
```
跟随安装助手配置环境
- 安装助手会自动检查环境（Node.js、PostgreSQL、Redis等）
- 配置数据库连接信息
- 配置SSL证书（开发环境可选择自签名证书）
- 配置大模型API Key（支持 DeepSeek、OpenAI、华为云 MaaS 等）
- 创建管理员账号
使用 web-admin 中的 JavaScript SDK
- 安装完成后，web-admin 已内置 AgentSkills Runtime JavaScript SDK
- 在 web-admin 管理后台中通过安装向导或配置页面安装并启动 agentskills-runtime
登录使用智能体应用
- 打开 web-admin 管理后台（默认地址：http://localhost:3031）
- 使用创建的管理员账号登录
- 访问 AI 模块 -> 对话页面 使用智能体功能
- 使用自然语言与 AI 对话，实现对数据库的 CRUD 操作
- 示例对话：
  - “查询最近一周注册的用户列表”
  - “创建一个名为’张三’的新用户”
  - “统计本月订单总金额”

方案优势

零配置: 无需安装仓颉编程语言环境
即开即用: 一键启动安装助手，自动配置完整运行环境
功能完整: 支持内置的 uctoo-api-skill 技能，实现自然语言数据库操作
易于扩展: 可在 UCToo 框架基础上继续开发自定义技能
可视化配置: 通过 web-admin 图形界面轻松管理 runtime 和配置

从源码开始（开发者）

如果您需要对 runtime 进行二次开发或贡献代码，请参考以下步骤：

环境要求

仓颉编程语言环境 (https://cangjie-lang.cn/)
支持的操作系统: Windows/Linux/macOS
Windows 系统特别要求: 需要安装 OpenSSL 库以支持 WebSocket 通信
- 下载地址: https://slproweb.com/products/Win32OpenSSL.html
- 安装时选择 “Copy OpenSSL DLLs to: The OpenSSL binaries (/bin) directory”
- 确保 OpenSSL 的 bin 目录已添加到系统 PATH 环境变量

安装

# 确保已安装仓颉编程语言环境
cjpm --version

# 克隆项目
git clone https://atomgit.com/uctoo/agentskills-runtime.git
cd agentskills-runtime

运行示例

# 构建项目（Windows 需要配置CANGJIE_HOME、CANGJIE_STDX_PATH环境变量）
cjpm build

运行 API 服务

# 在默认端口 8080 上运行 API 服务
cjpm run --skip-build --name magic.app
# 或在指定端口上运行
cjpm run --skip-build --name magic.app 8081

有关运行 API 服务的详细说明，请参见 API 服务运行指南。

代码生成工具（crudgen / crudweb）

AgentSkills Runtime 内置了两个代码生成工具，可从数据库表结构自动生成后端 CRUD 模块和前端 Web 页面，实现代码定义规范（CDS）特性，确保架构稳定不腐化。

重要提示：必须使用 cjpm run 命令执行代码生成工具，不能直接运行 target 目录下的 exe 文件（会因 DLL 路径问题导致启动失败）。工作目录必须是 agentskills-runtime 项目根目录。

crudgen - 后端 CRUD 模块生成器

从数据库表结构自动生成仓颉后端标准模块（Model → DAO → Service → Controller → Route）。

# 生成指定表的后端 CRUD 模块
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db <数据库名> --table <表名>"

# 示例：生成 uctoo 数据库 point_transactions 表的后端模块
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db uctoo --table point_transactions"

# 生成指定数据库所有表的后端 CRUD 模块
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--db uctoo --all"

# 查看帮助信息
cjpm run --skip-build --name magic.app.tools.crudgen --run-args="--help"

生成内容：

PO（持久化对象）：src/app/po/uctoo/<table_name>PO.cj
Model（模型）：src/app/models/uctoo/<TableName>.cj
DAO（数据访问层）：src/app/dao/uctoo/<TableName>DAO.cj
Service（业务逻辑层）：src/app/services/uctoo/<TableName>Service.cj
Controller（控制器层）：src/app/controllers/uctoo/<table_name>/<TableName>Controller.cj
Route（路由层）：src/app/routes/uctoo/<table_name>/<TableName>Route.cj
自动更新 AutoRouteConfig.cj 注册路由

crudweb - 前端 Web 页面生成器

从数据库表结构自动生成 Vue 前端 CRUD 页面（列表、新增、编辑表单、数据表格）和 Pinia-ORM Store 模型。

# 生成指定表的前端 Web 页面
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db <数据库名> --table <表名>"

# 示例：生成 uctoo 数据库 point_transactions 表的前端页面
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --table point_transactions"

# 生成指定数据库所有表的前端 Web 页面
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --all"

# 指定输出目录（可选，默认通过 .env 中的 WEB_CRUD_OUTPUT_DIR 配置）
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--db uctoo --table <表名> --output <输出目录>"

# 查看帮助信息
cjpm run --skip-build --name magic.app.tools.crudweb --run-args="--help"

生成内容（输出到 WEB_CRUD_OUTPUT_DIR 配置的目录，追加 /web/src/ 路径）：

页面入口：views/database/<db_name>/<table_name>/index.vue
新增组件：views/database/<db_name>/<table_name>/components/add-<table_name>.vue
数据表格：views/database/<db_name>/<table_name>/components/<table_name>-table.vue
编辑表单：views/database/<db_name>/<table_name>/components/edit-form.vue
Store 模型：store/models/<db_name>/<table_name>.ts
自动更新 Store 的 index.ts 导出

环境变量配置（在 .env 文件中）：

# Web CRUD 代码输出根目录（crudweb 会自动追加 /web/src/ 子目录）
WEB_CRUD_OUTPUT_DIR=D:\path\to\web-admin

通用模块开发流程

按照 uctoo-v4 模块开发规范，新增数据库表后的标准开发流程：

执行 SQL 变更：在数据库中执行建表或表结构变更 SQL
刷新数据库信息：通过 Web 管理后台的”数据库信息”页面点击”加载数据库信息”，或调用 API
生成后端模块：使用 crudgen 生成后端标准 CRUD 模块
生成前端页面：使用 crudweb 生成前端 Web 页面
业务逻辑开发：在 AutoCreateCode 区域之外编写自定义业务逻辑
编译验证：执行 cjpm build 验证编译通过

发布打包

构建发布包

AgentSkills Runtime 提供了自动化打包脚本，可以从源码构建发布包。

构建步骤

# 1. 构建项目
cjpm build

# 2. 运行打包脚本（自动从 cjpm.toml 读取版本号）
cjpm run --skip-build --name magic.scripts.package_release

打包脚本功能

自动版本检测：从 cjpm.toml 文件自动读取版本号
自动平台检测：自动检测当前操作系统和架构
精简打包：自动排除 examples、tests 等非必要模块
完整依赖：包含所有运行时所需的 DLL 文件

输出文件

打包完成后，将在 release/ 目录生成发布包：

release/
├── agentskills-runtime-win-x64.tar.gz    # Windows x64 发布包
├── agentskills-runtime-linux-x64.tar.gz  # Linux x64 发布包
├── agentskills-runtime-darwin-arm64.tar.gz # macOS ARM64 发布包
└── .env.example                           # 环境变量配置模板

发布包目录结构

release/
├── bin/                    # 可执行文件和所有 DLL
│   ├── agentskills-runtime.exe  # 主入口程序
│   └── *.dll               # 所有依赖库
├── magic/                  # 运行时模块
├── commonmark4cj/          # Markdown 解析器
├── yaml4cj/                # YAML 解析器
├── VERSION                 # 版本信息
└── .env.example            # 配置模板

使用发布包

# 1. 解压发布包
tar -xzf agentskills-runtime-win-x64.tar.gz

# 2. 进入目录并配置环境变量
cd release
cp .env.example bin/.env
# 编辑 .env 文件配置 API 密钥

# 3. 运行服务
./bin/agentskills-runtime.exe 8080

版本发布流程

更新 cjpm.toml 中的版本号
更新 CHANGELOG.md 记录变更
运行 cjpm build 构建项目（自动执行打包）
上传发布包到 GitHub Releases 或 AtomGit Releases

注意: 从 v0.0.21 版本开始，cjpm build 完成后会自动执行打包脚本，生成的发布包位于 target/release 目录。

手动打包命令仍然可用（可选）：
cjpm run --name magic.scripts.package_release

API 端点

启动 API 服务后，以下端点将可用（所有 API 使用 /api/v1/uctoo 前缀）：

技能管理 API

GET /api/v1/uctoo/agent_skills - 获取可用技能列表
GET /api/v1/uctoo/agent_skills/:id - 获取特定技能的详细信息
POST /api/v1/uctoo/skills/install - 安装新技能
POST /api/v1/uctoo/agent_skills/edit - 编辑现有技能
POST /api/v1/uctoo/agent_skills/del - 删除技能
POST /api/v1/uctoo/skills/execute - 执行技能
POST /api/v1/uctoo/skills/search - 搜索技能

其他 API

GET /api/v1/uctoo/health - 健康检查端点
GET /api/v1/uctoo/mcp/stream - MCP 服务器流式接口
WS /api/v1/uctoo/ws/chat - WebSocket 聊天接口（支持 AI 对话和技能执行）

WebSocket 聊天接口

WebSocket 端点 /ws/chat 提供实时 AI 对话和技能执行功能：

连接地址

ws://127.0.0.1:8080/api/v1/uctoo/ws/chat

消息格式

发送聊天消息：

{
  "type": "chat",
  "content": "你好，请帮我分析这段代码"
}

执行技能：

{
  "type": "execute_skill",
  "skill_id": "skill-name",
  "parameters": {
    "param1": "value1"
  },
  "timeout": "60s"
}

获取技能列表：

{
  "type": "list_skills"
}

心跳检测：

{
  "type": "ping"
}

响应消息类型

welcome - 连接建立时的欢迎消息
chat_response - AI 对话响应
skill_result - 技能执行结果
skills_list - 技能列表
status - 状态更新
error - 错误消息
pong - 心跳响应

配置要求

WebSocket 聊天功能需要配置大模型 API Key。在 .env 文件中配置：

# 华为云 MaaS 配置
MAAS_API_KEY=your_api_key_here
MAAS_BASE_URL=https://api.modelarts-maas.com/v2

支持的模型提供商包括：maas、openai、deepseek、dashscope 等。

使用方法

使用 DSL 创建技能

import { Skill, Tool } from "agentskills-runtime";

@Skill(
  name = "hello-world",
  description = "一个简单的问候用户技能",
  license = "MIT",
  metadata = {
    author = "您的姓名",
    version = "1.0.0",
    tags = ["问候", "示例"]
  }
)
public class HelloWorldSkill {
    @Tool(
      name = "greet",
      description = "按姓名问候用户",
      parameters = [
        { name: "name", type: "string", required: true, description: "要问候的人的姓名" }
      ]
    )
    public String greet(String name) {
        return "你好，" + name + "!";
    }
}

从 SKILL.md 加载技能

创建一个 SKILL.md 文件：

---
name: example-skill
description: 演示 SKILL.md 格式的示例技能
license: MIT
metadata:
  author: 您的姓名
  version: "1.0"
---

# 示例技能

这是一个演示 SKILL.md 格式的示例技能。

## 提供的工具

### greet

按姓名问候用户。

**参数：**
- `name`（必需，字符串）：要问候的人的姓名

**示例：**
```bash
skill run example-skill:greet name=Alice


### 渐进式技能加载

```cangjie
let skillDir = "path/to/skill/directory"
let loader = ProgressiveSkillLoader(skillBaseDirectory: skillDir)
let skillManager = CompositeSkillToolManager()
let skills = loader.loadSkillsToManager(skillManager)

应用案例

🎯 自然语言查询数据库 - uctoo-api-skill 示例

uctoo-api-skill 是一个完整的后端 API 集成技能示例，展示了如何通过自然语言查询数据库。

功能特点

自然语言转 API 调用：用户可以用自然语言描述查询需求，技能自动转换为 API 调用
多数据库支持：配合 uctoo backend 项目，支持连接多种类型数据库（MySQL、PostgreSQL、MongoDB 等）
任意数据库结构：无需预先定义表结构，支持任意数据库结构的查询
通用查询能力：支持用户管理、产品管理、订单管理、登录认证等功能

使用示例

用户输入：*”请查询最近一周注册的用户列表”*

技能自动执行：

分析用户意图（查询用户）
确定时间范围（最近一周）
构造 API 请求：GET /api/uctoo/entity/10/0?filter={"created_at":{"gte":"2024-01-01"}}&sort=-created_at
返回格式化结果

API 规范说明：uctoo 遵循 RESTFul 风格 API，查询接口格式为 /api/{database}/{table}/{limit}/{page}，支持 Prisma ORM 的 where 条件查询（filter 参数）和 orderBy 排序（sort 参数，负号表示降序）。详见 uctoo API 设计规范。

技术实现

使用内置的 http_request 工具发起 HTTP 请求
自动 Token 管理机制，无需手动处理认证
支持完整的 CRUD 操作

查看完整示例：src/examples/uctoo_api_skill

🚀 无需仓颉编程语言 - JavaScript SDK 快速集成

如果您不需要对 runtime 进行二次开发，无需掌握和安装仓颉编程语言，只需使用多语言 SDK 即可快速集成。

集成步骤

1. 安装 JavaScript SDK

npm install @opencangjie/skills

2. 安装运行时二进制发布版

# 自动下载并安装 AgentSkills 运行时
npx skills install-runtime

# 或指定版本
npx skills install-runtime --runtime-version 0.0.16

3. 配置 AI 模型 编辑运行时目录中的 .env 文件：

Windows: %USERPROFILE%\.agentskills-runtime\release\.env
macOS/Linux: ~/.agentskills-runtime/release/.env

# 配置 AI 模型（以 DeepSeek 为例）
MODEL_PROVIDER=deepseek
MODEL_NAME=deepseek-chat
DEEPSEEK_API_KEY=your_deepseek_api_key_here

4. 启动运行时

npx skills start

5. 安装并执行技能

# 查找技能
npx skills find database

# 安装技能
npx skills add ./my-database-skill

# 执行技能
npx skills run my-database-skill -p '{"query": "查询用户信息"}'

编程 API 使用

import { createClient } from '@opencangjie/skills';

const client = createClient({
  baseUrl: 'http://127.0.0.1:8080'
});

// 列出技能
const skills = await client.listSkills();

// 执行技能
const result = await client.executeSkill('database-skill', {
  query: '查询最近一周注册的用户'
});

console.log(result.output);

优势

渐进式 AI 能力：在原有项目中渐进式实现 “+AI” 能力
零学习成本：无需学习仓颉编程语言
快速集成：几行代码即可集成 AI 技能
跨平台支持：支持 Windows、macOS、Linux

查看完整 SDK 文档：sdk/javascript/README_cn.md

多语言 SDK 使用示例

JavaScript/TypeScript 示例

import { AgentSkillsRuntime } from '@agentskills/runtime';

// 初始化运行时
const runtime = new AgentSkillsRuntime({
  baseUrl: 'http://localhost:8080',
  apiKey: 'your-api-key'
});

// 加载并执行技能
const result = await runtime.executeSkill('example-skill', {
  name: 'Alice',
  age: 30
});

console.log('执行结果:', result);

Python 示例

from agentskills import Runtime

# 初始化运行时
runtime = Runtime(
    base_url="http://localhost:8080",
    api_key="your-api-key"
)

# 加载并执行技能
result = runtime.execute_skill("example-skill", {
    "name": "Alice",
    "age": 30
})

print(f"执行结果: {result}")

Java 示例

import com.agentskills.Runtime;
import com.agentskills.SkillResult;

// 初始化运行时
Runtime runtime = Runtime.builder()
    .baseUrl("http://localhost:8080")
    .apiKey("your-api-key")
    .build();

// 加载并执行技能
Map<String, Object> parameters = new HashMap<>();
parameters.put("name", "Alice");
parameters.put("age", 30);

SkillResult result = runtime.executeSkill("example-skill", parameters);
System.out.println("执行结果: " + result.getOutput());

开发指南

开发环境搭建

# 安装依赖
cjpm install

# 运行测试
cjpm test

# 代码检查
cjpm check

项目结构

apps/agentskills-runtime/
├── cjpm.toml                            # 仓颉包配置
├── build.cj                             # 构建脚本
├── README.md                            # 项目文档
├── README_cn.md                         # 中文项目文档
├── LICENSE                              # 许可证信息
├── docs/                                # 文档
│   ├── architecture.md                  # 架构概述
│   ├── quickstart.md                    # 快速入门指南
│   ├── builtin-tools.md                 # 内置工具文档
│   └── api-reference.md                 # API 参考
├── src/                                 # 源代码
│   ├── app/                            # 应用服务器模块
│   │   ├── main.cj                     # 应用主入口
│   │   ├── core/                       # 核心组件
│   │   │   ├── server/                 # HTTP/HTTPS服务器
│   │   │   ├── router/                 # 路由系统
│   │   │   ├── middleware/             # 中间件
│   │   │   ├── http/                   # HTTP请求/响应
│   │   │   └── database/               # 数据库连接池
│   │   ├── routes/                     # 路由处理
│   │   │   ├── skill/                  # 技能路由
│   │   │   └── tool/                   # 工具路由
│   │   ├── controllers/                # 控制器
│   │   ├── services/                   # 业务服务
│   │   ├── middlewares/                # 中间件实现
│   │   └── registry/                   # 自动路由注册
│   ├── skill/                          # 技能相关功能
│   │   ├── domain/                     # 技能领域模型
│   │   ├── infrastructure/             # 技能基础设施组件
│   │   └── application/                # 技能应用服务
│   ├── tool/                           # 工具模块
│   │   ├── tool_dispatcher.cj          # 工具调度器
│   │   ├── permission_checker.cj       # 权限检查器
│   │   ├── builtin_tools_registry.cj   # 内置工具注册
│   │   └── file_tools.cj               # 文件工具实现
│   ├── security/                       # 安全模块
│   │   ├── wasm_sandbox/               # WASM 沙箱
│   │   └── access_control/             # 访问控制
│   ├── runtime/                        # 运行时核心
│   ├── utils/                          # 工具函数
│   └── examples/                       # 示例实现
├── specs/                               # 规范文档
├── skills/                              # 示例和参考技能
├── sdk/                                 # 多语言 SDK 实现
│   ├── javascript/                     # JavaScript/TypeScript SDK
│   ├── python/                         # Python SDK
│   ├── java/                           # Java SDK
│   ├── go/                             # Go SDK
│   ├── rust/                           # Rust SDK
│   └── csharp/                         # C# SDK
└── tests/                               # 测试实现

依赖关系

此实现利用了仓颉生态系统中的现有库：

yaml4cj：用于解析 SKILL.md 文件中的 YAML 前置元数据
commonmark4cj：用于根据 CommonMark 规范处理 SKILL.md 文件中的 markdown 内容
stdx：用于各种实用函数

多语言 SDK 依赖

各语言 SDK 依赖相应的生态系统：

JavaScript: npm 包管理器，依赖主流 AI 库如 langchain、openai-api
Python: pip 包管理器，依赖 numpy、scikit-learn、transformers 等
Java: Maven/Gradle，依赖 Spring Boot、Apache HttpComponents
Go: Go modules，依赖 gin、gorilla/websocket 等
Rust: Cargo，依赖 tokio、serde、reqwest 等
C#: NuGet，依赖 .NET Core 相关包

基本使用

import magic.agentskills.runtime

// 创建技能运行时实例
let runtime = SkillRuntime()

// 加载技能
let skill = runtime.loadSkill("path/to/skill")

// 执行技能
let result = skill.execute(params)

技能开发示例

import magic.agentskills.runtime
import magic.agentskills.skill.domain.models.skill_manifest

// 定义技能清单
let manifest = SkillManifest {
    name: "example_skill",
    version: "1.0.0",
    description: "示例技能",
    author: "UCToo",
    parameters: [],
    implementation: "./skill_impl.cj"
}

// 创建技能运行时
let runtime = SkillRuntime()

// 加载并执行技能
let skill_result = runtime.execute(manifest, {})

文档资源

规范驱动开发文档

贡献指南

欢迎参与项目贡献！请查看 CONTRIBUTING.md 了解详情。

请参阅文档中的贡献指南。

贡献方式

代码贡献: 提交 Pull Request 改进代码
文档完善: 帮助完善技术文档和使用指南
问题反馈: 报告 Bug 或提出功能建议
技能开发: 开发新的技能示例
SDK 开发: 为新的编程语言开发 SDK
语言适配器: 开发新的语言适配器和绑定
生态系统集成: 集成主流开发工具和平台

开发流程

# Fork 项目
# 创建功能分支
git checkout -b feature/your-feature

# 提交更改
git commit -am 'Add new feature'

# 推送分支
git push origin feature/your-feature

# 创建 Pull Request

项目状态

核心运行时实现
安全沙箱机制
标准兼容性验证
性能优化
生产环境部署
社区生态建设

整体流程与关键技术

核心工作流程

技能发现与加载
- 自动扫描配置目录中的技能文件
- 解析 SKILL.md 文件的 YAML 前置元数据
- 验证技能格式和依赖关系
安全执行环境
- WASM 沙箱提供隔离执行环境
- 基于能力的权限控制系统
- 资源使用监控和限制
技能执行与编排
- 动态参数解析和验证
- 技能间依赖关系管理
- 执行结果收集和处理

关键技术组件

Skill Manifest Parser: 解析和验证 SKILL.md 文件格式
WASM Runtime: 安全的技能执行环境
Capability Manager: 细粒度的权限控制系统
Resource Monitor: 资源使用监控和配额管理
Dependency Resolver: 技能依赖关系解析
Execution Orchestrator: 技能执行编排引擎

许可证

本项目采用 MIT 许可证，详情请见 LICENSE 文件。

联系方式

项目主页: https://atomgit.com/uctoo/agentskills-runtime
问题反馈: https://atomgit.com/uctoo/agentskills-runtime/issues
邮件联系: contact@uctoo.com
微信交流群: 请通过项目主页获取入群二维码

致谢

感谢以下开源项目和社区的支持：

技术标准

编程语言

开源工具

UCToo
CangjieMagic
Fountain
各种优秀的开源库和工具

参考资料

AgentSkills Runtime - 让 AI 开发更简单、更安全、更快捷！