uplift-model-sample-preparation

Name: uplift-model-sample-preparation
Author: QFIN-tech

40stars16forks

How to install uplift-model-sample-preparation?

qfin-tech/model-evo/uplift-model-sample-preparation

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-sample-preparation

Installs into the current project.

Summary

在 uplift-model-task-spec 产出 confirmed task_config_path 后使用：检查样本语义、起草并确认切分方案、生成建模样本产物。不要用于任务定义、特征选择、建模、调参、模型比较或最终报告。

Files · 1

View on GitHub

SKILL.md

1	# 样本准备
2
3	## 1. 输入依赖
4
5	本 skill 在 `uplift-model-task-spec` 已产出 confirmed `task_config_path` 后使用，用来准备 uplift 建模样本。
6
7	流程：
8
9	```text
10	raw_sample_check
11	-> confirm data_semantics_plan
12	-> split_planning
13	-> confirm split_plan
14	-> post_split_validation
15	-> modeling_sample_spec.confirmed
16	-> uplift-model-sample-homogeneity-check
17	```
18
19	## 2. 执行入口
20
21	使用统一 runner：
22
23	```bash
24	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
25	```
26
27	Windows 环境可按需将路径分隔符改为反斜杠。
28
29	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。本 skill 输出到：
30
31	```text
32	{run_dir}/uplift-model-sample-preparation/{timestamp}_sample_preparation/
33	inputs/0001_<action>.request.json
34	results/0001_<action>.result.json
35	artifacts/
36	_flow_manifest.json
37	_flow_log.jsonl
38	report.md
39	```
40
41	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`raw_sample_check` 创建 flow；后续 action 必须显式传入上一步 `outputs.flow_dir`，不得从 artifact path 反推 flow。
42
43	request JSON 必须通过 UTF-8 stdin 传入：
44
45	```json
46	{"action": "raw_sample_check", "payload": {"task_config_path": "..."}}
47	```
48
49	stdout 和落盘 result JSON 都使用共同返回 shape：
50
51	```text
52	status, summary, outputs, issues, next_steps
53	```
54
55	只从 `outputs.result_path` 读取当前 action 的 result JSON。存在报告时读取 `outputs.report_path`。复用同一个 flow 时读取 `outputs.flow_dir` 后作为下一次请求的 `flow_dir` 输入。不要读取或传播顶层 `flow_dir`、`result_path`、`warnings`。
56
57	旧输入字段如果以 `_ref` 或 `_refs` 结尾，runner 会返回 `needs_input`，并在 `issues` / `next_steps` 中给出对应 `_path` 或 `_paths` 替代字段。业务数据字段 `data_ref` 仍可出现在 task config 内。
58
59	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
60
61	## 3. Actions 与参数说明
62
63	### raw_sample_check
64
65	必填 payload：
66
67	```json
68	{
69	"task_config_path": "<confirmed task_config artifact>"
70	}
71	```
72
73	可选 payload：
74
75	```json
76	{
77	"data_source": {"kind": "local_csv", "path": "..."}
78	}
79	```
80
81	如果省略 `data_source`，runner 使用 `task_config.external_inputs.data_source` 或 task config 中的 `data_ref`。
82
83	输出：
84
85	```text
86	outputs.data_semantics_plan_path
87	```
88
89	该 action 写入 `artifacts/data_semantics_plan.draft.v1.json`，并返回 `needs_confirmation`。
90
91	### confirm_artifact
92
93	必填 payload：
94
95	```json
96	{
97	"source_draft_path": "<draft artifact path>",
98	"artifact_kind": "data_semantics_plan",
99	"confirmed_by": "user"
100	}
101	```
102
103	`artifact_kind` 可为 `data_semantics_plan` 或 `split_plan`。确认后写入：
104
105	```text
106	artifacts/data_semantics_plan.confirmed.v1.json
107	artifacts/split_plan.confirmed.v1.json
108	```
109
110	输出会暴露 `outputs.data_semantics_plan_path` 或 `outputs.split_plan_path`。
111
112	### split_planning
113
114	必填 payload：
115
116	```json
117	{
118	"task_config_path": "<confirmed task_config artifact>",
119	"data_semantics_plan_path": "<confirmed data_semantics_plan artifact>"
120	}
121	```
122
123	可选 payload：
124
125	```json
126	{
127	"split_method": "random",
128	"ratios": {"train": 0.8, "test": 0.2, "valid": 0.0},
129	"random_seed": 42
130	}
131	```
132
133	时间切分需提供 `split_method=time`、`time_column`、`oot_window.start`、可选 `oot_window.end_exclusive` 和可选 `non_oot_random_ratios`。
134
135	输出：
136
137	```text
138	outputs.split_plan_path
139	```
140
141	该 action 写入 `artifacts/split_plan.draft.v1.json`，并返回 `needs_confirmation`。
142
143	### post_split_validation
144
145	必填 payload：
146
147	```json
148	{
149	"task_config_path": "<confirmed task_config artifact>",
150	"data_semantics_plan_path": "<confirmed data_semantics_plan artifact>",
151	"split_plan_path": "<confirmed split_plan artifact>"
152	}
153	```
154
155	该 action 会 dry-run 切分，校验启用切分中的 treatment/control 和 outcome 支撑；只有验证通过才写入产物。
156
157	输出：
158
159	```text
160	outputs.modeling_sample_spec_path
161	outputs.modeling_sample_path
162	outputs.modeling_sample_paths
163	outputs.report_path
164	```
165
166	产物：
167
168	```text
169	artifacts/modeling_sample_spec.confirmed.v1.json
170	artifacts/modeling_sample.v1.csv
171	artifacts/modeling_sample.train.v1.csv
172	artifacts/modeling_sample.test.v1.csv
173	artifacts/modeling_sample.valid.v1.csv
174	artifacts/modeling_sample.oot.v1.csv
175	report.md
176	```
177
178	只写入启用的 split 数据集。
179
180	## 4. 输出产物
181
182	典型输出目录：
183
184	```text
185	{run_dir}/uplift-model-sample-preparation/{timestamp}_sample_preparation/
186	inputs/0001_<action>.request.json
187	results/0001_<action>.result.json
188	artifacts/
189	data_semantics_plan.draft.v1.json
190	data_semantics_plan.confirmed.v1.json
191	split_plan.draft.v1.json
192	split_plan.confirmed.v1.json
193	modeling_sample_spec.confirmed.v1.json
194	modeling_sample.v1.csv
195	modeling_sample.train.v1.csv
196	modeling_sample.test.v1.csv
197	modeling_sample.valid.v1.csv
198	modeling_sample.oot.v1.csv
199	_flow_manifest.json
200	_flow_log.jsonl
201	report.md
202	```
203
204	关键下游路径：
205
206	- `outputs.data_semantics_plan_path`
207	- `outputs.split_plan_path`
208	- `outputs.modeling_sample_spec_path`
209	- `outputs.modeling_sample_path`
210	- `outputs.modeling_sample_paths`
211	- `outputs.report_path`
212
213	## 5. 与其他 skill 的关联
214
215	\| 方向 \| Skill \| 关系 \|
216	\|---\|---\|---\|
217	\| 上游 \| `uplift-model-task-spec` \| 提供 confirmed `task_config_path` \|
218	\| 下游 \| `uplift-model-sample-homogeneity-check` \| 消费 confirmed `modeling_sample_spec_path` 做 treatment/control 同质性检查 \|
219
220	## 6. 执行约束
221
222	本 skill 只负责样本语义检查、切分方案确认和建模样本产

People who liked this also viewed

6 picks

Type

uplift-model-sample-preparation

40stars16forks

View on GitHub

How to install uplift-model-sample-preparation?

qfin-tech/model-evo/uplift-model-sample-preparation

$npx -y skills add QFIN-tech/model-evo --skill uplift-model-sample-preparation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 样本准备
2
3	## 1. 输入依赖
4
5	本 skill 在 `uplift-model-task-spec` 已产出 confirmed `task_config_path` 后使用，用来准备 uplift 建模样本。
6
7	流程：
8
9	```text
10	raw_sample_check
11	-> confirm data_semantics_plan
12	-> split_planning
13	-> confirm split_plan
14	-> post_split_validation
15	-> modeling_sample_spec.confirmed
16	-> uplift-model-sample-homogeneity-check
17	```
18
19	## 2. 执行入口
20
21	使用统一 runner：
22
23	```bash
24	python <skill-dir>/scripts/run.py --input - --output-dir <output_dir>
25	```
26
27	Windows 环境可按需将路径分隔符改为反斜杠。
28
29	`--output-dir` 必须是已存在的 `run_dir`；runner 不创建 run_dir，不扫描 `latest/current`。本 skill 输出到：
30
31	```text
32	{run_dir}/uplift-model-sample-preparation/{timestamp}_sample_preparation/
33	inputs/0001_<action>.request.json
34	results/0001_<action>.result.json
35	artifacts/
36	_flow_manifest.json
37	_flow_log.jsonl
38	report.md
39	```
40
41	所有 stdout、result、manifest 和 log 中的持久化 path 都是 `run_dir` 相对路径。`raw_sample_check` 创建 flow；后续 action 必须显式传入上一步 `outputs.flow_dir`，不得从 artifact path 反推 flow。
42
43	request JSON 必须通过 UTF-8 stdin 传入：
44
45	```json
46	{"action": "raw_sample_check", "payload": {"task_config_path": "..."}}
47	```
48
49	stdout 和落盘 result JSON 都使用共同返回 shape：
50
51	```text
52	status, summary, outputs, issues, next_steps
53	```
54
55	只从 `outputs.result_path` 读取当前 action 的 result JSON。存在报告时读取 `outputs.report_path`。复用同一个 flow 时读取 `outputs.flow_dir` 后作为下一次请求的 `flow_dir` 输入。不要读取或传播顶层 `flow_dir`、`result_path`、`warnings`。
56
57	旧输入字段如果以 `_ref` 或 `_refs` 结尾，runner 会返回 `needs_input`，并在 `issues` / `next_steps` 中给出对应 `_path` 或 `_paths` 替代字段。业务数据字段 `data_ref` 仍可出现在 task config 内。
58
59	如果缺少 Python 包，runner 返回 `status=failed`、`code=PYTHON_IMPORT_ERROR` issue，并在 issue/next_steps 中提示阅读本 skill 的缺依赖处理说明，不返回 skill 安装目录文件路径。
60
61	## 3. Actions 与参数说明
62
63	### raw_sample_check
64
65	必填 payload：
66
67	```json
68	{
69	"task_config_path": "<confirmed task_config artifact>"
70	}
71	```
72
73	可选 payload：
74
75	```json
76	{
77	"data_source": {"kind": "local_csv", "path": "..."}
78	}
79	```
80
81	如果省略 `data_source`，runner 使用 `task_config.external_inputs.data_source` 或 task config 中的 `data_ref`。
82
83	输出：
84
85	```text
86	outputs.data_semantics_plan_path
87	```
88
89	该 action 写入 `artifacts/data_semantics_plan.draft.v1.json`，并返回 `needs_confirmation`。
90
91	### confirm_artifact
92
93	必填 payload：
94
95	```json
96	{
97	"source_draft_path": "<draft artifact path>",
98	"artifact_kind": "data_semantics_plan",
99	"confirmed_by": "user"
100	}
101	```
102
103	`artifact_kind` 可为 `data_semantics_plan` 或 `split_plan`。确认后写入：
104
105	```text
106	artifacts/data_semantics_plan.confirmed.v1.json
107	artifacts/split_plan.confirmed.v1.json
108	```
109
110	输出会暴露 `outputs.data_semantics_plan_path` 或 `outputs.split_plan_path`。
111
112	### split_planning
113
114	必填 payload：
115
116	```json
117	{
118	"task_config_path": "<confirmed task_config artifact>",
119	"data_semantics_plan_path": "<confirmed data_semantics_plan artifact>"
120	}
121	```
122
123	可选 payload：
124
125	```json
126	{
127	"split_method": "random",
128	"ratios": {"train": 0.8, "test": 0.2, "valid": 0.0},
129	"random_seed": 42
130	}
131	```
132
133	时间切分需提供 `split_method=time`、`time_column`、`oot_window.start`、可选 `oot_window.end_exclusive` 和可选 `non_oot_random_ratios`。
134
135	输出：
136
137	```text
138	outputs.split_plan_path
139	```
140
141	该 action 写入 `artifacts/split_plan.draft.v1.json`，并返回 `needs_confirmation`。
142
143	### post_split_validation
144
145	必填 payload：
146
147	```json
148	{
149	"task_config_path": "<confirmed task_config artifact>",
150	"data_semantics_plan_path": "<confirmed data_semantics_plan artifact>",
151	"split_plan_path": "<confirmed split_plan artifact>"
152	}
153	```
154
155	该 action 会 dry-run 切分，校验启用切分中的 treatment/control 和 outcome 支撑；只有验证通过才写入产物。
156
157	输出：
158
159	```text
160	outputs.modeling_sample_spec_path
161	outputs.modeling_sample_path
162	outputs.modeling_sample_paths
163	outputs.report_path
164	```
165
166	产物：
167
168	```text
169	artifacts/modeling_sample_spec.confirmed.v1.json
170	artifacts/modeling_sample.v1.csv
171	artifacts/modeling_sample.train.v1.csv
172	artifacts/modeling_sample.test.v1.csv
173	artifacts/modeling_sample.valid.v1.csv
174	artifacts/modeling_sample.oot.v1.csv
175	report.md
176	```
177
178	只写入启用的 split 数据集。
179
180	## 4. 输出产物
181
182	典型输出目录：
183
184	```text
185	{run_dir}/uplift-model-sample-preparation/{timestamp}_sample_preparation/
186	inputs/0001_<action>.request.json
187	results/0001_<action>.result.json
188	artifacts/
189	data_semantics_plan.draft.v1.json
190	data_semantics_plan.confirmed.v1.json
191	split_plan.draft.v1.json
192	split_plan.confirmed.v1.json
193	modeling_sample_spec.confirmed.v1.json
194	modeling_sample.v1.csv
195	modeling_sample.train.v1.csv
196	modeling_sample.test.v1.csv
197	modeling_sample.valid.v1.csv
198	modeling_sample.oot.v1.csv
199	_flow_manifest.json
200	_flow_log.jsonl
201	report.md
202	```
203
204	关键下游路径：
205
206	- `outputs.data_semantics_plan_path`
207	- `outputs.split_plan_path`
208	- `outputs.modeling_sample_spec_path`
209	- `outputs.modeling_sample_path`
210	- `outputs.modeling_sample_paths`
211	- `outputs.report_path`
212
213	## 5. 与其他 skill 的关联
214
215	\| 方向 \| Skill \| 关系 \|
216	\|---\|---\|---\|
217	\| 上游 \| `uplift-model-task-spec` \| 提供 confirmed `task_config_path` \|
218	\| 下游 \| `uplift-model-sample-homogeneity-check` \| 消费 confirmed `modeling_sample_spec_path` 做 treatment/control 同质性检查 \|
219
220	## 6. 执行约束
221
222	本 skill 只负责样本语义检查、切分方案确认和建模样本产

People who liked this also viewed

6 picks

Type