Agent Skills

hscredit 提供可被 AI Agent 发现和调用的 Skills。Agent 负责理解分析目标、组装数据与参数， Skill 负责校验请求、调用真实 hscredit API，并交付 Excel、图片、JSON 或可复用制品。

当前已实现两个 Skill：

Skill	适用任务	主要产物
`$hsbin`	变量分箱、分箱统计、效率评估、分箱器拟合与分箱图	Excel、PNG/SVG、规则 JSON、分箱器 artifact
`$hsreport`	特征分析、模型评估和策略迭代完整报告	多 Sheet Excel 报告及报告图片

hscredit、hsmodel、hsrule、hsselect、hsviz 和 hsexcel 当前只是规划目录，没有 SKILL.md，不能被 Agent 调用。

安装 Skills

从仓库安装

在 hscredit 仓库根目录安装当前已实现的整套 Skill：

python skills/install.py --suite hscredit

只安装一个 Skill：

python skills/install.py --skills hsbin
python skills/install.py --skills hsreport

指定 Agent 的 Skills 目录：

python skills/install.py --skills hsbin hsreport --target-dir /path/to/agent/skills

未指定 --target-dir 时，安装器优先使用 $CODEX_HOME/skills，否则使用 ~/.codex/skills。安装器不会覆盖已经存在的 Skill 目录；更新前应先检查并保留自己的修改。

安装完成后，在 Agent 的下一轮对话中调用 Skill。

让 Agent 从 GitHub 安装

支持从 GitHub 路径安装 Skill 的 Agent，可以直接接收以下任务：

请从 GitHub 仓库 hengshu-credit/hscredit 的 main 分支安装：
skills/hsbin
skills/hsreport

也可以只安装需要的目录：

请安装 hengshu-credit/hscredit 中的 skills/hsbin。

公开仓库可直接下载；私有仓库需要 Agent 已具备相应 Git 凭证或访问令牌。Skill 目录是独立安装单位，无需同时复制规划中的空目录。

OpenAI 项目 Skills API

OpenAI Skills API 支持以文件目录集合或 ZIP 创建 Skill，并提供独立的 Skill ID 和版本管理。发布时分别上传 skills/hsbin 与 skills/hsreport，不要把两个目录合并成一个不可区分的 Skill。

参考 OpenAI Skills API。

在 Agent 中调用

分箱分析

直接描述数据位置、字段角色、分析目标和输出要求：

$hsbin 读取 data/credit.xlsx 的“建模样本”工作表，
对 score 和 age 按 target 做等频分箱，最多 5 箱，
生成分箱统计 Excel 和分箱图，保存到 outputs/。

$hsbin 使用训练好的 outputs/binner.joblib，
把 data/oot.parquet 转换为 WOE，制品是可信的，
结果保存为 outputs/oot_woe.xlsx。

Agent 会根据任务选择 feature_bin_stats、optimal_binning_fit、bin_plot 等具体操作。如果用户只需要单张统计表或图片，应使用 $hsbin，不必生成完整报告。

完整报告

$hsreport 读取 data/credit.xlsx，使用 target 作为坏样本标签，
分析 score、age 和 debt_ratio，按 apply_date 查看月度趋势，
生成完整特征分析报告并保存为 outputs/特征分析报告.xlsx。

$hsreport 使用可信模型 artifacts/model.joblib，
对 train.parquet 和 oot.parquet 生成模型报告，
目标字段是 target，不显示控制台报告，结果保存到 outputs/。

$hsreport 分析规则“score < 560”和“age < 25”，
同时输出订单与 amount 金额口径、按 apply_date 的月度稳定性，
生成策略迭代报告。

$hsreport 只提供以下完整报告入口：

auto_feature_analysis
auto_model_report
swap_out_report

数据输入

文件输入

文件模式适合普通 Chat、CLI 和独立 Agent 进程：

格式	配置
CSV	可指定 `encoding` 和 `separator`
XLSX	可指定 `sheet_name`
Parquet	默认由基础依赖 `pyarrow` 支持
hscredit/joblib artifact	必须显式声明 `trusted=true`

Pickle 和 joblib 反序列化可能执行代码。只对自己生成或已经验证来源的制品使用可信模式。

同进程对象

Python、Notebook 或常驻 Agent 可以把 DataFrame、模型或分箱器放入对象注册表：

from hscredit.skills_runtime import execute_skill

request = {
    "version": "1",
    "operation": "feature_bin_stats",
    "inputs": {"data": {"kind": "object_ref", "ref": "data:train"}},
    "parameters": {
        "feature": "score",
        "target": "target",
        "method": "quantile",
        "max_n_bins": 5,
        "n_jobs": 1,
    },
    "output": {
        "directory": "outputs",
        "name": "score_stats",
        "overwrite": False,
    },
    "environment": {"mode": "current", "install_missing": False},
}

result = execute_skill("hsbin", request, objects={"data:train": train_df})

object_ref 只存在于当前 Python 进程，不能自动传入新的隔离解释器。缺少依赖时，先把对象保存为可信 artifact，或者在用户明确同意后使用当前环境安装。

运行环境

默认 environment.mode 是 isolated：

Skill 在用户缓存目录创建专用 venv。
根据操作和文件格式安装受控 hscredit extras。
后续请求按 Python 版本、hscredit 来源和 extras 复用同一环境。

首次运行需要创建环境和安装依赖，耗时通常明显高于后续复用。Skill 不接受请求提供的任意包名、包索引或 Git URL。

只有用户明确要求修改当前代码环境时，才使用：

{
  "environment": {
    "mode": "current",
    "install_missing": true
  }
}

高级：手工 JSON 调用

普通 Agent 使用时不需要手写 JSON。调试、自动化或其他 Agent 适配器可以直接运行 Skill launcher。

hsbin 请求示例：

{
  "version": "1",
  "operation": "feature_bin_stats",
  "inputs": {
    "data": {"kind": "file", "path": "data/credit.csv"}
  },
  "parameters": {
    "feature": ["score", "age"],
    "target": "target",
    "method": "quantile",
    "max_n_bins": 5,
    "n_jobs": 1
  },
  "output": {
    "directory": "outputs",
    "name": "变量分箱统计",
    "overwrite": false
  },
  "environment": {"mode": "isolated", "reuse": true}
}

python skills/hsbin/scripts/run.py request.json

launcher 输出一个 JSON 信封：

status：执行状态。
summary：行列信息、数据集名称或报告结束位置等紧凑摘要。
artifacts：Excel、图片、JSON 或制品的绝对路径。
warnings：非阻断警告。
environment：实际 Python、hscredit 版本和 extras。

常见错误

错误码	含义	处理方式
`SCHEMA_INVALID`	请求字段或参数不符合契约	检查对应 Skill 的 `schemas/request.schema.json`
`OPERATION_NOT_ALLOWED`	Skill 不支持该操作	改用已登记操作或正确的 Skill
`INPUT_NOT_FOUND`	文件、工作表或对象引用不存在	检查路径、Sheet 名和对象注册表
`COLUMN_MISSING`	分析所需字段缺失	明确特征、目标、日期和金额字段
`ARTIFACT_UNTRUSTED`	未授权加载 pickle/joblib	验证来源后显式设置 `trusted=true`
`ARTIFACT_EXISTS`	输出文件已存在	更换名称，或明确设置 `overwrite=true`
`OBJECT_REF_REQUIRES_CURRENT_ENV`	实时对象不能跨隔离解释器	使用当前环境或先保存 artifact
`DEPENDENCY_INSTALL_FAILED`	隔离依赖安装失败	检查网络、Python 版本和精简后的 pip 日志

查看完整操作契约

skills/hsbin/references/operations.md
skills/hsreport/references/operations.md
skills/hsbin/schemas/request.schema.json
skills/hsreport/schemas/request.schema.json