Skip to content

Commit f1bad28

Browse files
committed
refactor(program-authoring): promote edit-program to proper Skill structure
edit-program.md was a 106-line workflow file squatting inside skill-authoring/workflows/ — not a real Skill. Restructured into the standard four-layer format under program-authoring: New files: program-authoring/workflows/edit.md — edit workflow (steps only) program-authoring/references/edit-examples.md — common edit patterns Updated files: program-authoring/rules/constraints.md — add §10 YAML safety rules, §11 minimum-change principle program-authoring/SKILL.md — add edit-program route skill-studio.routes.js — point edit-program mode to program-authoring/workflows/edit.md Deleted: skill-authoring/workflows/edit-program.md — replaced by proper structure
1 parent e27edac commit f1bad28

6 files changed

Lines changed: 175 additions & 112 deletions

File tree

data/skills/program-authoring/SKILL.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ inputs:
2222
label: 目标 Program ID(改进时填)
2323
type: string
2424
required: false
25-
placeholder: 例如:my-vps-monitor
25+
placeholder: 例如:vps-metrics-collector
2626
---
2727

2828
# Program 创作规范
@@ -35,7 +35,7 @@ inputs:
3535
| 用户意图 | 读取 |
3636
|---------|------|
3737
| 创建新 program.yaml | rules/constraints.md → workflows/generate.md |
38-
| 修改已有程序 | rules/constraints.md → execute_command 读现有文件 → 最小修改 |
38+
| 修改已有程序(edit-program 模式) | rules/constraints.md → workflows/edit.md → references/edit-examples.md |
3939
| 排查生成错误 | references/antipatterns.md |
4040

4141
## Known Gotchas
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# 程序编辑常见修改示例
2+
3+
## 添加主机
4+
5+
```yaml
6+
# 原来
7+
hosts:
8+
- host_abc123
9+
10+
# 改后(追加,不替换)
11+
hosts:
12+
- host_abc123
13+
- host_def456
14+
```
15+
16+
---
17+
18+
## 改为所有主机
19+
20+
```yaml
21+
hosts: all
22+
```
23+
24+
---
25+
26+
## 增加监控 step(加在 render step 之前)
27+
28+
```yaml
29+
# 新增 step
30+
- id: check_openresty
31+
label: 检查 OpenResty 存活
32+
run: docker inspect 1Panel-openresty-YygR --format '{{.State.Status}}'
33+
verify:
34+
exit_code: 0
35+
stdout_contains: "running"
36+
on_error_hint: OpenResty 容器异常,检查是主动停止还是意外崩溃
37+
38+
# 原有 render step 保持不动
39+
- id: render_status
40+
type: render
41+
```
42+
43+
---
44+
45+
## 修改 cron 触发频率
46+
47+
```yaml
48+
# 原来:每分钟
49+
schedule: "* * * * *"
50+
51+
# 改为每5分钟
52+
schedule: "*/5 * * * *"
53+
```
54+
55+
---
56+
57+
## 添加 Guardian Rescue Skill
58+
59+
```yaml
60+
guardian:
61+
skills:
62+
- existing-rescue-skill
63+
- new-rescue-skill # 追加,保留原有
64+
max_actions_per_hour: 10
65+
```
66+
67+
---
68+
69+
## 常见坑(edit 模式特有)
70+
71+
1. **不要重写整个文件** — 保留原有注释、格式、字段顺序
72+
2. **不要改 `enabled`** — 启用/停用让用户在 UI 里操作
73+
3. **新增 step 必须加 `on_error_hint`** — Guardian 介入时会读
74+
4. **容器名确认** — 添加 Docker 相关 step 前先 `execute_command` 验证容器名

data/skills/program-authoring/rules/constraints.md

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,4 +158,28 @@ Program 的 `type: render` step 的输出会显示在程序页的 **「📊 结
158158
"0 */5 * * *" # 每 5 分钟(5 位)
159159
"0 0 3 * *" # 每天 3:00(5 位)
160160
"*/30 * * * * *" # 每 30 秒(6 位,含秒)
161-
```
161+
```
162+
---
163+
164+
## 10. YAML 安全规则(edit 模式必须遵守)
165+
166+
以下写法会导致 program.yaml 解析失败,**绝对禁止**
167+
168+
- `python3 - <<'PYEOF' ... PYEOF` — Python heredoc,`#` 注释破坏 YAML
169+
- `python3 -c "..."` 多行字符串 — `try:` `except:` 等冒号触发 YAML mapping 解析
170+
- 任何 `<<'EOF'` heredoc — YAML block scalar 内不支持
171+
172+
**替代方案**
173+
- 把 Python 逻辑写成单行(用 `;` 分隔语句,不换行)
174+
- 或把脚本预先写到文件,step 只调用文件路径
175+
176+
---
177+
178+
## 11. edit 模式最小修改原则
179+
180+
修改已有 program.yaml 时:
181+
- 只改用户明确描述的字段
182+
- 禁止删除用户未提及的 step
183+
- 禁止修改 `enabled` 字段(除非用户明确要求)
184+
- 禁止重写整个文件(除非用户明确说"重写")
185+
- 保留原有注释、字段顺序、格式风格
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Program 编辑 Workflow
2+
3+
> 用于修改**已存在**的 program.yaml。
4+
> 核心原则:**最小必要修改——只改用户描述的部分,其余原封不动。**
5+
6+
## 前置:必须先读
7+
8+
- `rules/constraints.md` — YAML 安全规则、命令白名单
9+
- 当前 program.yaml 全文(已由 Studio 注入上下文)
10+
11+
---
12+
13+
## Step 1:理解现有程序
14+
15+
从注入的 `## 当前 program.yaml` 块中提取:
16+
- `hosts`:当前绑定的主机列表
17+
- `actions.<action>.steps`:所有 step 的 id / run / verify
18+
- `guardian.skills`:已挂载的 Rescue Skill
19+
- `triggers`:触发周期
20+
21+
**必须完整读完再动手,不得跳过。**
22+
23+
---
24+
25+
## Step 2:解析修改意图
26+
27+
| 用户说 | 对应字段 |
28+
|---|---|
29+
| 加入 VPS2 / 增加主机 | `hosts` 追加 host_id |
30+
| 去掉某台主机 | `hosts` 移除对应 id |
31+
| 改成所有主机 | `hosts: all` |
32+
| 增加监控项 / 新功能 | `steps` 末尾(render 之前)新增 step |
33+
| 修改某个 step 命令 | 只改该 step 的 `run` 字段 |
34+
| 改触发频率 | 只改 `triggers[].schedule` |
35+
| 加 Rescue Skill | `guardian.skills` 追加 id |
36+
| 修改阈值/参数 | 只改对应 step `run` 内的参数值 |
37+
38+
如需探测新主机或新服务,用 `execute_command` 做 1-2 条只读探测。
39+
40+
---
41+
42+
## Step 3:展示计划 + 写入
43+
44+
`render_result format=keyvalue level=info` 列出将改什么、不改什么。
45+
然后**立即**`write_local_file` 写入修改后的完整 yaml。
46+
47+
路径:`data/programs/<programId>/program.yaml`
48+
49+
> 写入约束见 `rules/constraints.md` §10(YAML 安全规则)
50+
51+
---
52+
53+
## Step 4:成功反馈 + 保持对话
54+
55+
```
56+
render_result format=message level=success
57+
已更新 <programId>:
58+
✓ <改了什么>
59+
→ 未改动:<列出未改动主要字段>
60+
```
61+
62+
然后 `ask_user type=input title="还要继续调整吗?"`
63+
64+
---
65+
66+
## 自检(写入前)
67+
68+
- [ ] 只改了用户描述的部分
69+
- [ ] 未删除用户未提及的 step
70+
- [ ] 未修改 `enabled` 字段(除非用户明确要求)
71+
- [ ] run 字段无 heredoc、无多行 Python(见 rules/constraints.md §10)

data/skills/skill-authoring/workflows/edit-program.md

Lines changed: 0 additions & 107 deletions
This file was deleted.

src/routes/skill-studio.routes.js

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -238,8 +238,9 @@ function createSkillStudioRouter({ hostService, libraryService, mcpRegistry }) {
238238
lines.push('**模式**:精准修改已有 Program');
239239
lines.push(`**Program ID**:\`${programId}\``);
240240
lines.push(`**产物路径**:\`data/programs/${programId}/program.yaml\``);
241-
lines.push('**约束**:严格按 `data/skills/skill-authoring/workflows/edit-program.md` 执行。');
242-
lines.push('**核心原则**:最小必要修改——只改用户描述的部分,其余原封不动。');
241+
lines.push('**约束**:严格按 `data/skills/program-authoring/workflows/edit.md` 执行。');
242+
lines.push('**硬规则**:`data/skills/program-authoring/rules/constraints.md` §10-11(YAML 安全 + 最小修改)。');
243+
lines.push('**示例参考**:`data/skills/program-authoring/references/edit-examples.md`');
243244
lines.push('');
244245
lines.push('## 当前 program.yaml');
245246
lines.push('```yaml');

0 commit comments

Comments
 (0)