# Skill_Studio

**Repository Path**: lft1011/skill_-studio

## Basic Information

- **Project Name**: Skill_Studio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 技能管理器

一个用于创建、导入、转换、安装和解析 Codex 技能的小型全栈项目。

## 功能

- 手动填写名称、描述和指令来创建技能。
- 上传 `.md`、`.txt` 或 `.zip` 技能源文件。
- 从公开 GitHub 仓库导入技能源文件。
- 将来源内容转换成可使用的 Codex 技能目录。
- 将生成后的技能安装到当前机器的 Codex 技能目录。
- 上传 PRD 或文档（`.pdf`、`.docx`、`.md`、`.txt`、`.prd`），按当前技能进行解析。
- 调用已配置的 OpenAI 兼容服务，基于匹配到的技能生成语义拆解、任务拆分、技能使用策略、风险和下一步动作。

## 可使用技能的目录结构

后端会把每个转换后的技能写入：

`backend/data/skills/<skill-slug>/`

每个技能目录包含：

- `SKILL.md`
- `agents/openai.yaml`
- `skill.json`

`SKILL.md` 使用 UTF-8 编码，包含 `name` 和 `description` 两个 frontmatter 字段，以及中文技能说明正文。

安装接口会把生成后的技能复制到：

`${CODEX_HOME:-~/.codex}/skills/<skill-slug>/`

这样 Codex 就可以在当前机器上使用这个技能。

## 后端

```bash
cd backend
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
```

后端接口：

- `GET /api/health`
- `GET /api/skills`
- `POST /api/skills/manual`
- `POST /api/skills/upload`
- `POST /api/skills/github`
- `POST /api/skills/{slug}/install`
- `GET /api/skills/{slug}/download`
- `POST /api/documents/analyze`

文档解析接口会先抽取上传文档中的文本，再扫描当前技能库，返回匹配到的技能、相关片段和需求语句。随后后端会读取 `${CODEX_HOME:-~/.codex}/config.toml` 和 `${CODEX_HOME:-~/.codex}/auth.json` 中的 OpenAI 配置，调用对应的 OpenAI 兼容服务生成深度语义分析。

API Key 只在后端读取，不会发送到浏览器。如果没有配置密钥，普通文档解析仍然可用，`ai_analysis.status` 会返回 `unavailable`。

## 前端

```bash
cd frontend
npm install
npm run dev
```

打开终端里显示的 Vite 地址，通常是 `http://localhost:5173`。

前端默认通过 `/api` 代理访问 `http://localhost:8000`。如需覆盖后端地址，可设置：

```bash
VITE_API_BASE_URL=http://localhost:8000/api
```

## 说明

- 转换后的技能保存在 `backend/data/skills/`。
- 安装动作会把技能复制到当前 Codex Home。
- 下载动作会返回生成技能目录的 zip 压缩包。
- 项目中的页面、提示和文档说明均使用 UTF-8 中文显示。

## 后端规范化配置

后端支持通过环境变量调整运行参数，默认保持本地开发可直接运行：

- `SKILL_MANAGER_API_TOKEN`：可选接口访问令牌；配置后，技能增删改、工具执行、文档上传等敏感接口需要 `X-API-Token` 或 `Authorization: Bearer <token>`。
- `SKILL_MANAGER_DATA_DIR`：后端数据目录，默认 `backend/data`。
- `SKILL_MANAGER_RESULTS_DB`：工具结果 SQLite 数据库路径，默认 `backend/data/tool_results.sqlite3`。
- `SKILL_MANAGER_CODEX_MODEL`：`codex exec` 默认模型。
- `SKILL_MANAGER_ANALYSIS_TIMEOUT_SECONDS`：AI 分析超时时间，默认 240 秒。
- `SKILL_MANAGER_TOOL_TIMEOUT_SECONDS`：工具执行超时时间，默认 300 秒。
- `SKILL_MANAGER_MAX_UPLOAD_BYTES`：技能上传大小上限，默认 15 MB。
- `SKILL_MANAGER_MAX_DOCUMENT_UPLOAD_BYTES`：文档上传大小上限，默认 25 MB。
- `SKILL_MANAGER_MAX_GITHUB_ARCHIVE_BYTES`：GitHub 仓库压缩包下载上限，默认 30 MB。

工具结果已从 `backend/data/tool_results.json` 升级为 SQLite 存储，首次启动会自动迁移旧 JSON 结果。运行态数据库文件不会提交到 Git。

新增接口：

- `GET /api/runtime`：查看后端公开运行配置。
- `POST /api/documents/analyze`：上传 `.pdf`、`.docx`、`.md`、`.txt` 或 `.prd` 并执行文本抽取、技能匹配和语义分析。

本地后端基础检查：

```bash
cd backend
python -m compileall -q app
python -m unittest discover tests
```

## 后台任务队列

`codex exec` 长耗时操作支持异步任务接口，前端工具生成和 PRD 拆解会默认使用任务流程：

- `POST /api/tasks/tools/codex-exec`：提交工具生成任务。
- `POST /api/tools/dbc/from-matrix`：上传 `.xlsx` 或 `.csv` 通信矩阵，确定性生成并校验 `.dbc` 文件。
- `POST /api/tasks/analysis/codex-exec`：提交 PRD / AI 分析任务。
- `GET /api/tasks/{task_id}`：查询任务状态和最终结果。
- `GET /api/tasks?limit=50`：查看最近任务。

任务状态包括：`queued`、`running`、`succeeded`、`failed`、`cancelled`。任务状态和结果存储在 SQLite 中，服务重启后未完成任务会标记为失败，避免前端一直等待。

相关环境变量：

- `SKILL_MANAGER_MAX_TASKS`：最多保留任务记录数量，默认 500。
- `SKILL_MANAGER_MAX_TASK_WORKERS`：后台任务并发数，默认 2。

## 通信矩阵生成 DBC

“智驾测试工具链 → DBC 创建 / 加载”支持直接上传 `.xlsx` 或 `.csv` 通信矩阵。后端会解析报文和信号字段，生成 DBC，通过 `cantools` 严格校验后保存到工具结果，页面可直接下载 `.dbc` 产物。

矩阵至少需要这些列：

- 报文 ID / CAN ID
- 信号名称 / Signal Name
- 起始位 / Start Bit
- 信号长度 / Signal Length

建议同时提供报文名称、DLC、周期、发送节点、字节序、符号类型、精度、偏移、最小值、最大值、单位、接收节点、描述和枚举值。报文信息可以只填写在该报文的第一条信号行，后续空白行会自动继承。旧版 `.xls` 请先另存为 `.xlsx`。

页面“按规范生成 DBC”固定执行 `Vector/CANoe 严格规范 v1`：报文名和信号名必须是 ASCII DBC 标识符；DLC、发送节点、位定义、字节序/符号、Factor、Offset、物理范围和接收节点缺失时拒绝生成；Motorola 使用 Vector sawtooth 起始位约定；扩展帧使用 DBC MSB 标志；物理范围必须能由位宽、符号、Factor 和 Offset 表示；最终必须通过 `cantools strict=True` 校验。下载的 DBC 使用 `GBK/CP936` 编码，兼容中文 Windows 环境下的 CANoe/CANdb++ 备注显示；页面预览仍使用 Unicode。规范名称、版本和编码会写入工具结果元数据，规范名称和版本会写入 DBC `VERSION`。