@netpilot/skills 0.3.2 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/AGENTS.md +25 -9
- package/CHANGELOG.md +21 -0
- package/README.md +78 -112
- package/THIRD_PARTY_NOTICES.md +1 -1
- package/agents/codex/architecture-designer.toml +2 -1
- package/agents/codex/backend-reviewer.toml +3 -1
- package/agents/codex/frontend-reviewer.toml +3 -1
- package/agents/codex/test-verifier.toml +4 -1
- package/bin/netpilot-skills.mjs +130 -6
- package/docs/agent-authoring.md +15 -5
- package/package.json +1 -1
- package/scripts/sync.mjs +965 -99
- package/scripts/validate.mjs +68 -14
- package/skills/ask/SKILL.md +51 -47
- package/skills/ask/agents/openai.yaml +3 -3
- package/skills/code-review/SKILL.md +68 -52
- package/skills/code-review/agents/openai.yaml +2 -2
- package/skills/codebase-design/SKILL.md +87 -50
- package/skills/codebase-design/agents/openai.yaml +2 -2
- package/skills/codebase-design/references/deepening.md +60 -0
- package/skills/codebase-design/references/design-it-twice.md +54 -0
- package/skills/diagnosing-bugs/SKILL.md +124 -54
- package/skills/diagnosing-bugs/agents/openai.yaml +2 -2
- package/skills/diagnosing-bugs/scripts/hitl-loop.template.mjs +52 -0
- package/skills/domain-modeling/SKILL.md +65 -55
- package/skills/domain-modeling/agents/openai.yaml +2 -2
- package/skills/domain-modeling/references/adr-format.md +47 -0
- package/skills/domain-modeling/references/context-format.md +60 -0
- package/skills/domain-modeling/references/domain-docs.md +53 -0
- package/skills/grill-me/SKILL.md +13 -0
- package/skills/grill-me/agents/openai.yaml +6 -0
- package/skills/grill-with-docs/SKILL.md +16 -63
- package/skills/grill-with-docs/agents/openai.yaml +3 -3
- package/skills/grilling/SKILL.md +10 -54
- package/skills/grilling/agents/openai.yaml +2 -2
- package/skills/handoff/SKILL.md +24 -42
- package/skills/handoff/agents/openai.yaml +3 -3
- package/skills/implement/SKILL.md +18 -55
- package/skills/implement/agents/openai.yaml +3 -3
- package/skills/improve-codebase-architecture/SKILL.md +88 -0
- package/skills/improve-codebase-architecture/agents/openai.yaml +6 -0
- package/skills/improve-codebase-architecture/references/html-report.md +158 -0
- package/skills/prototype/SKILL.md +21 -53
- package/skills/prototype/agents/openai.yaml +2 -2
- package/skills/prototype/references/logic.md +87 -0
- package/skills/prototype/references/ui.md +108 -0
- package/skills/research/SKILL.md +9 -66
- package/skills/research/agents/openai.yaml +2 -2
- package/skills/resolving-merge-conflicts/SKILL.md +94 -0
- package/skills/resolving-merge-conflicts/agents/openai.yaml +6 -0
- package/skills/tdd/SKILL.md +30 -46
- package/skills/tdd/agents/openai.yaml +2 -2
- package/skills/tdd/references/mocking.md +70 -0
- package/skills/tdd/references/tests.md +95 -0
- package/skills/teach/SKILL.md +115 -47
- package/skills/teach/agents/openai.yaml +3 -3
- package/skills/teach/references/glossary-format.md +35 -10
- package/skills/teach/references/learning-record-format.md +41 -11
- package/skills/teach/references/mission-format.md +20 -17
- package/skills/teach/references/resources-format.md +34 -16
- package/skills/to-spec/SKILL.md +56 -51
- package/skills/to-spec/agents/openai.yaml +3 -3
- package/skills/to-tickets/SKILL.md +84 -45
- package/skills/to-tickets/agents/openai.yaml +3 -3
- package/skills/triage/SKILL.md +171 -0
- package/skills/triage/agents/openai.yaml +6 -0
- package/skills/triage/references/agent-brief.md +168 -0
- package/skills/triage/references/issue-tracker-github.md +42 -0
- package/skills/triage/references/issue-tracker-gitlab.md +42 -0
- package/skills/triage/references/issue-tracker-local.md +28 -0
- package/skills/triage/references/out-of-scope.md +113 -0
- package/skills/triage/references/project-config.md +57 -0
- package/skills/triage/references/triage-labels.md +13 -0
- package/skills/wayfinder/SKILL.md +158 -51
- package/skills/wayfinder/agents/openai.yaml +3 -3
- package/skills/writing-great-skills/SKILL.md +96 -54
- package/skills/writing-great-skills/agents/openai.yaml +3 -3
- package/skills/writing-great-skills/references/glossary.md +279 -0
- package/agents/codex/code-reader.toml +0 -11
- package/skills/grill/SKILL.md +0 -54
- package/skills/grill/agents/openai.yaml +0 -6
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# HTML Report Format
|
|
2
|
+
|
|
3
|
+
报告是写入操作系统临时目录的单个、离线可读 HTML 文件。CSS、图形与必要字体回退全部内联，不加载 CDN、远程脚本、分析脚本或数据采集代码。
|
|
4
|
+
|
|
5
|
+
关系图、mass、cross-section 和 collapse visual 优先使用手工 HTML/CSS 或 inline SVG。若环境能把 Mermaid 确定性渲染为 SVG，可以嵌入渲染结果，但不得让浏览器运行时依赖 Mermaid。
|
|
6
|
+
|
|
7
|
+
来自仓库的文件名、标题和文字必须 HTML escape；不要把源码、secret、环境变量值或敏感数据嵌入报告。
|
|
8
|
+
|
|
9
|
+
## 页面骨架
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<!doctype html>
|
|
13
|
+
<html lang="zh-CN">
|
|
14
|
+
<head>
|
|
15
|
+
<meta charset="utf-8" />
|
|
16
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
17
|
+
<title>Architecture review — {{repository}}</title>
|
|
18
|
+
<style>
|
|
19
|
+
:root {
|
|
20
|
+
color-scheme: light;
|
|
21
|
+
--ink: #0f172a;
|
|
22
|
+
--paper: #fafaf9;
|
|
23
|
+
--card: #ffffff;
|
|
24
|
+
--line: #cbd5e1;
|
|
25
|
+
--accent: #2563eb;
|
|
26
|
+
--leak: #dc2626;
|
|
27
|
+
--warn: #d97706;
|
|
28
|
+
}
|
|
29
|
+
* { box-sizing: border-box; }
|
|
30
|
+
body { margin: 0; background: var(--paper); color: var(--ink); font-family: system-ui, sans-serif; }
|
|
31
|
+
main { width: min(72rem, 100%); margin: 0 auto; padding: 3rem 1.5rem; }
|
|
32
|
+
article { background: var(--card); border: 1px solid var(--line); border-radius: 1rem; padding: 1.5rem; }
|
|
33
|
+
.seam { stroke-dasharray: 4 4; }
|
|
34
|
+
.leak { stroke: var(--leak); }
|
|
35
|
+
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); color: white; }
|
|
36
|
+
@media print { body { background: white; } article { break-inside: avoid; } }
|
|
37
|
+
</style>
|
|
38
|
+
</head>
|
|
39
|
+
<body>
|
|
40
|
+
<main>
|
|
41
|
+
<header><!-- repository, date, legend --></header>
|
|
42
|
+
<section id="candidates"><!-- cards --></section>
|
|
43
|
+
<section id="top-recommendation"><!-- one recommendation --></section>
|
|
44
|
+
</main>
|
|
45
|
+
</body>
|
|
46
|
+
</html>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## 页头
|
|
50
|
+
|
|
51
|
+
只放：
|
|
52
|
+
|
|
53
|
+
- repository name；
|
|
54
|
+
- date；
|
|
55
|
+
- compact legend：
|
|
56
|
+
- solid box = Module；
|
|
57
|
+
- dashed line = Seam；
|
|
58
|
+
- red arrow = leakage；
|
|
59
|
+
- thick dark box = deep Module。
|
|
60
|
+
|
|
61
|
+
不要写介绍性长段落，直接进入 candidates。
|
|
62
|
+
|
|
63
|
+
## 候选项卡片
|
|
64
|
+
|
|
65
|
+
每个 candidate 使用一个 `<article>`：
|
|
66
|
+
|
|
67
|
+
- **Title**：命名 deepening 动作，例如“Collapse the Order intake pipeline”。
|
|
68
|
+
- **Badge row**：
|
|
69
|
+
- Strong：emerald；
|
|
70
|
+
- Worth exploring：amber；
|
|
71
|
+
- Speculative：slate；
|
|
72
|
+
- dependency tag：in-process、local-substitutable、ports & adapters 或 mock。
|
|
73
|
+
- **Files**：等宽、小字号列表。
|
|
74
|
+
- **Before / After**：并排的视觉核心。
|
|
75
|
+
- **Problem**：一句话说明 friction。
|
|
76
|
+
- **Solution**：一句话说明 shape 如何改变。
|
|
77
|
+
- **Wins**：每条不超过六个词，使用 Locality、Leverage、Interface 或 test surface。
|
|
78
|
+
- **ADR warning**：仅在存在真实冲突时显示。
|
|
79
|
+
|
|
80
|
+
若一张图需要一段话解释，重新画图，不要追加长文。
|
|
81
|
+
|
|
82
|
+
## 可视化模式
|
|
83
|
+
|
|
84
|
+
按 candidate 要表达的关系选择 pattern，并混合使用。不能让每张图都采用同一种 pattern；变化不是装饰，而是为了让 dependency、layered shallowness、Interface mass 和 call-graph collapse 各自使用最清楚的视觉语法。
|
|
85
|
+
|
|
86
|
+
### Inline SVG 依赖 / 调用流
|
|
87
|
+
|
|
88
|
+
适用于依赖、调用流和 sequence。使用带文本标签的 `<rect>`、`<line>`、`<path>` 与 `<marker>`；为图形提供 `<title>`、`<desc>` 和可读文字 fallback。
|
|
89
|
+
|
|
90
|
+
### 手绘框与箭头
|
|
91
|
+
|
|
92
|
+
Module 使用有边框 `<div>`；箭头使用定位在 relative container 上的 inline SVG。适合表现“一个厚边框 deep Module 包含灰色 internals”。
|
|
93
|
+
|
|
94
|
+
### 截面图
|
|
95
|
+
|
|
96
|
+
水平堆叠 bands：
|
|
97
|
+
|
|
98
|
+
- Before：多个很薄、几乎不吸收复杂性的 Module；
|
|
99
|
+
- After：一个厚 Module 承担完整责任。
|
|
100
|
+
|
|
101
|
+
### 体量图
|
|
102
|
+
|
|
103
|
+
每个 Module 使用两个矩形：
|
|
104
|
+
|
|
105
|
+
- Interface surface；
|
|
106
|
+
- Implementation mass。
|
|
107
|
+
|
|
108
|
+
shallow Module 的 Interface 与 Implementation 接近；deep Module 的 Interface 很小，Implementation 很大。
|
|
109
|
+
|
|
110
|
+
### 调用图折叠
|
|
111
|
+
|
|
112
|
+
Before 显示函数树；After 把树折叠为一个 Module，内部调用以淡色保留。
|
|
113
|
+
|
|
114
|
+
## 样式
|
|
115
|
+
|
|
116
|
+
- editorial，而不是 dashboard；
|
|
117
|
+
- generous whitespace；
|
|
118
|
+
- 一种主 accent，加 red leakage 和 amber warning；
|
|
119
|
+
- diagram 高度约 320px；
|
|
120
|
+
- Module label 使用小号大写跟踪字距；
|
|
121
|
+
- 不添加交互、表单或数据采集；
|
|
122
|
+
- 在窄屏和打印模式下仍可阅读。
|
|
123
|
+
|
|
124
|
+
## 首选建议
|
|
125
|
+
|
|
126
|
+
一个较大的 card，只包含：
|
|
127
|
+
|
|
128
|
+
- candidate title；
|
|
129
|
+
- 一句为什么优先；
|
|
130
|
+
- 到 candidate card 的 anchor。
|
|
131
|
+
|
|
132
|
+
## 词汇
|
|
133
|
+
|
|
134
|
+
报告正文使用中文，但以下架构词汇保持含义稳定：
|
|
135
|
+
|
|
136
|
+
- Module
|
|
137
|
+
- Interface
|
|
138
|
+
- Implementation
|
|
139
|
+
- Depth / deep / shallow
|
|
140
|
+
- Seam
|
|
141
|
+
- Adapter
|
|
142
|
+
- Leverage
|
|
143
|
+
- Locality
|
|
144
|
+
|
|
145
|
+
不要用 component、service、unit、layer 或 wrapper 代替 Module，不要用 API 或 signature 代替 Interface，不要用 boundary 代替 Seam。`layer` 和 `wrapper` 只有在确实描述层或包装器、而不是偷换 Module 概念时才可使用。
|
|
146
|
+
|
|
147
|
+
推荐表达：
|
|
148
|
+
|
|
149
|
+
- “Order intake Module 很 shallow：Interface 几乎等于 Implementation。”
|
|
150
|
+
- “Pricing 穿透了 Seam。”
|
|
151
|
+
- “Deepen：一个 Interface，一个 test surface。”
|
|
152
|
+
- “两个 Adapters 证明 Seam 真实存在。”
|
|
153
|
+
- “Locality：bug 集中在一个 Module。”
|
|
154
|
+
- “Leverage：一个 Interface 服务多个调用方。”
|
|
155
|
+
|
|
156
|
+
不要写“代码更干净”“更现代”“更容易维护”这类无法由 shape 解释的收益。
|
|
157
|
+
|
|
158
|
+
语气遵守 **no hedging / no throat-clearing**：不写“可能值得注意”“也许可以考虑”之类铺垫。能写成 bullet 的句子就写成 bullet；可以删除的 bullet 就删除。推荐强度已经由 badge 表达，不再用含糊句子稀释。
|
|
@@ -1,71 +1,39 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: prototype
|
|
3
|
-
description:
|
|
3
|
+
description: 当关键设计问题不能只靠讨论确定，需要用可丢弃原型验证 state model、business logic、data shape 或 UI 方向时使用。原型用于回答一个问题并保留一手证据，不等同于生产实现；问题已清楚或需要生产级交付时不使用。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Prototype
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Prototype 是**用可丢弃代码回答一个问题**。问题决定它的形状。
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## 选择分支
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
从用户提示、相邻代码或一次澄清中确认问题：
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
- 假设：我们认为会发生什么？
|
|
17
|
-
- 反证：什么结果会证明假设不成立？
|
|
18
|
-
- 指标：观察什么，阈值是多少？
|
|
19
|
-
- 边界：本实验刻意不覆盖什么？
|
|
20
|
-
- 时限：何时停止？
|
|
21
|
-
- 环境：版本、数据、硬件和依赖条件。
|
|
22
|
-
```
|
|
14
|
+
- **“这套 logic / state model 是否合理？”** → 读取 [logic.md](references/logic.md)，构建一个小型交互式 terminal app，让用户推动纸面上难以判断的状态。
|
|
15
|
+
- **“它应该长什么样？”** → 读取 [ui.md](references/ui.md)，在一个 route 上生成数个结构上明显不同的 UI variants，通过 URL search param 和浮动底栏切换。
|
|
23
16
|
|
|
24
|
-
|
|
17
|
+
两个分支产物完全不同，选错会浪费整个实验。问题确实有歧义且用户暂时不可达时，根据相邻代码选择：backend Module 默认 logic，page/component 默认 UI，并在 prototype 顶部明确写出假设。
|
|
25
18
|
|
|
26
|
-
##
|
|
19
|
+
## 两种分支都遵守的规则
|
|
27
20
|
|
|
28
|
-
1.
|
|
29
|
-
2.
|
|
30
|
-
3.
|
|
31
|
-
4.
|
|
32
|
-
5.
|
|
33
|
-
6.
|
|
21
|
+
1. **从第一天起就是 throwaway，并明确标记。** 代码放在最接近未来使用位置的地方，使上下文清楚；命名必须让读者一眼看出它不是 production。UI route 遵循项目既有 routing convention，不发明新的顶层结构。
|
|
22
|
+
2. **一条命令运行。** 使用项目已有 task runner，例如 `pnpm <name>`、`python <path>` 或 `bun <path>`；用户不应记忆内部文件路径。
|
|
23
|
+
3. **默认不持久化。** 状态放在内存。若问题本身涉及数据库，使用 scratch database 或名称明确标注 `PROTOTYPE — wipe me` 的本地文件。
|
|
24
|
+
4. **跳过 polish。** 不写测试，不补与可运行无关的错误处理，不提前抽象。目标是快速学习。
|
|
25
|
+
5. **完整展示状态。** 每次 logic action 或 UI variant 切换后，输出或渲染完整相关状态，使变化可见。
|
|
26
|
+
6. **完成后同时捕获答案和一手证据。** 记录可供正式实现吸收的 decision；只有另行授权 `$implement` 后才写入正式代码。prototype 本身作为 primary source 留在 main 之外的 throwaway branch，并在目标 tracker item（prototype ticket 或 implementation issue）留下该 branch 的 context pointer。该 tracker item 或 commit 还要记录问题和 verdict；main branch 只保留经正式实现采用的 decision。
|
|
34
27
|
|
|
35
|
-
|
|
28
|
+
## 动作授权
|
|
36
29
|
|
|
37
|
-
|
|
30
|
+
以下任一路径成立时，本 skill 才获得原型动作权限：
|
|
38
31
|
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
- 结果受环境或样本限制时，不外推到未测试范围。
|
|
42
|
-
- 若原型未回答问题，说明实验设计为何失效，并决定缩小、改写或停止，不用追加功能掩盖失败。
|
|
32
|
+
- 用户显式调用本 skill，并给出唯一的仓库、目标 tracker item（prototype ticket 或 implementation issue）与 prototype 问题；
|
|
33
|
+
- 显式 user-invoked 父 skill 已明确授权 prototype 工作，并传入唯一的仓库、目标 tracker item（prototype ticket 或 implementation issue）与 prototype 问题。
|
|
43
34
|
|
|
44
|
-
|
|
35
|
+
目标 tracker item 可以直接使用 wayfinder 当前已 claim 的 prototype ticket，不要求先创建 implementation issue。
|
|
45
36
|
|
|
46
|
-
|
|
47
|
-
## 原型结论
|
|
48
|
-
- 假设：
|
|
49
|
-
- 结果：支持 / 反驳 / 不确定
|
|
50
|
-
- 证据：
|
|
51
|
-
- 适用边界：
|
|
52
|
-
- 原型代码位置：
|
|
53
|
-
- 复现方式：
|
|
54
|
-
- 是否建议产品化：
|
|
55
|
-
- 产品化前必须补齐：
|
|
56
|
-
```
|
|
37
|
+
获得权限后，可以预告并自动创建本地 throwaway branch、实现原型、commit artifact，并把问题、verdict 和 context pointer 写回该目标 tracker item。目标不唯一、父 skill 没有明确授权，或用户只要求比较方案时先预览。
|
|
57
38
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
- 原型回答了一个明确、重要且可证伪的问题。
|
|
61
|
-
- 结果可复现，环境和限制已记录。
|
|
62
|
-
- 明确区分实验代码与生产实现。
|
|
63
|
-
- 结论能触发继续、换路或停止中的一个决策。
|
|
64
|
-
|
|
65
|
-
## 反模式
|
|
66
|
-
|
|
67
|
-
- 不要把“能跑起来”自动解释为方案可用。
|
|
68
|
-
- 不要在原型阶段提前建设通用平台。
|
|
69
|
-
- 不要隐藏失败结果或只展示最佳一次运行。
|
|
70
|
-
- 不要未经批准把原型直接合入生产路径。
|
|
71
|
-
- 不要使用真实敏感数据来换取方便。
|
|
39
|
+
永不自动 push、创建 PR、merge、deploy 或发布；prototype 不因完成而自动成为生产实现。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
interface:
|
|
2
2
|
display_name: "Prototype"
|
|
3
|
-
short_description: "
|
|
4
|
-
default_prompt: "请使用 $prototype
|
|
3
|
+
short_description: "用可丢弃的 Logic 或 UI 原型回答一个明确且可证伪的问题"
|
|
4
|
+
default_prompt: "请使用 $prototype 选择 Logic 或 UI 分支，为当前关键假设制作最小可运行实验。"
|
|
5
5
|
policy:
|
|
6
6
|
allow_implicit_invocation: true
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# Logic Prototype
|
|
2
|
+
|
|
3
|
+
构建一个小型交互式 terminal app，让用户手动推动 business logic、state transition 或 data shape。
|
|
4
|
+
|
|
5
|
+
## 适用情形
|
|
6
|
+
|
|
7
|
+
- “我不确定 X 后再发生 Y 时，这个 state machine 是否正确。”
|
|
8
|
+
- “这套 data model 能否表达某个边界情况？”
|
|
9
|
+
- “实现前我想先感受一下 API 应该是什么形状。”
|
|
10
|
+
- 用户需要“按键并观察状态改变”。
|
|
11
|
+
|
|
12
|
+
若问题是“它应该长什么样”，改用 `ui.md`。
|
|
13
|
+
|
|
14
|
+
## 流程
|
|
15
|
+
|
|
16
|
+
### 1. 写明问题
|
|
17
|
+
|
|
18
|
+
在 README 或主文件顶部用一段话写明待验证的 state model 与问题。用户无论在线还是之后回来，都必须能判断 prototype 是否回答了正确问题。
|
|
19
|
+
|
|
20
|
+
### 2. 选择语言
|
|
21
|
+
|
|
22
|
+
使用宿主项目已有语言、runtime 与 task runner。项目没有明显 runtime 时再询问，不要只为 prototype 引入新工具链。
|
|
23
|
+
|
|
24
|
+
### 3. 把 logic 隔离为可移植 Module
|
|
25
|
+
|
|
26
|
+
把真正回答问题的逻辑放到小而 pure 的 Interface 后。TUI 是 throwaway；logic module 应能独立提取。
|
|
27
|
+
|
|
28
|
+
按问题选择：
|
|
29
|
+
|
|
30
|
+
- **Pure reducer**：`(state, action) => state`。适用于 actions 是离散 events，且 state 可表示为单一值的情况。
|
|
31
|
+
- **Explicit state machine**：适用于“当前究竟允许哪些 actions”本身就是待验证问题的情况。
|
|
32
|
+
- **作用于 plain data type 的一组 pure functions**：适用于不存在隐式 current state、只有数据转换的情况。
|
|
33
|
+
- **Method surface 清楚的 class/module**：仅在 logic 确实拥有持续内部状态时使用。
|
|
34
|
+
|
|
35
|
+
根据问题选择，不根据 TUI 接线便利选择。Logic 内不得包含 I/O、terminal code 或用于控制流的 `console.log`。TUI 可以 import logic，logic 不得反向依赖 TUI。
|
|
36
|
+
|
|
37
|
+
### 4. 构建最小 TUI
|
|
38
|
+
|
|
39
|
+
每个 tick 清屏并重绘整个 frame，而不是不断追加 scrollback。
|
|
40
|
+
|
|
41
|
+
Frame 按顺序包含：
|
|
42
|
+
|
|
43
|
+
1. **Current state**：每字段一行或 formatted JSON。字段名/标题可用 bold，timestamp、ID、derived value 可用 dim。已有 styling library 才复用；否则 ANSI escape 足够。
|
|
44
|
+
2. **Keyboard shortcuts**：例如 `[a] add user [d] delete user [t] tick clock [q] quit`。
|
|
45
|
+
|
|
46
|
+
行为：
|
|
47
|
+
|
|
48
|
+
1. 初始化单一 in-memory state；
|
|
49
|
+
2. 启动时渲染；
|
|
50
|
+
3. 每次读取一个 key 或一行；
|
|
51
|
+
4. dispatch 到 handler；
|
|
52
|
+
5. 每次 action 后重绘完整 frame；
|
|
53
|
+
6. 持续循环直到 quit。
|
|
54
|
+
|
|
55
|
+
整个 frame 应能放入一个 terminal screen。
|
|
56
|
+
|
|
57
|
+
### 5. 一条命令运行
|
|
58
|
+
|
|
59
|
+
把运行入口加入现有 `package.json`、`Makefile`、`justfile` 或 `pyproject.toml`。用户应只需执行 `pnpm run <prototype-name>` 或等价命令。
|
|
60
|
+
|
|
61
|
+
项目没有 task runner 时，把完整命令写在 prototype 顶部。
|
|
62
|
+
|
|
63
|
+
### 6. 交给用户操作
|
|
64
|
+
|
|
65
|
+
给出运行命令，由用户亲手驱动。最有价值的反馈通常是：
|
|
66
|
+
|
|
67
|
+
- “这个动作此时不应该合法。”
|
|
68
|
+
- “我以为这个字段会变成另一种状态。”
|
|
69
|
+
- “这里缺少一个状态。”
|
|
70
|
+
|
|
71
|
+
用户需要新 action 时可以追加，但每次追加都必须继续服务原问题。
|
|
72
|
+
|
|
73
|
+
### 7. 捕获答案与证据
|
|
74
|
+
|
|
75
|
+
问题回答后：
|
|
76
|
+
|
|
77
|
+
- validated reducer、machine 或 pure functions 可以作为正式实现输入；只有另行授权 `$implement` 后才写入正式代码；
|
|
78
|
+
- TUI shell 与完整实验记录保留在已授权的 throwaway branch；
|
|
79
|
+
- 主分支不保留 TUI shell。
|
|
80
|
+
|
|
81
|
+
## 反模式
|
|
82
|
+
|
|
83
|
+
- 不给 prototype 本身补测试。
|
|
84
|
+
- 除非问题就是 persistence，否则不连接真实数据库。
|
|
85
|
+
- 不泛化未来可能需求。
|
|
86
|
+
- 不把 logic 与 TUI 混在一起。
|
|
87
|
+
- 不把 TUI shell 直接送入生产。
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# UI Prototype
|
|
2
|
+
|
|
3
|
+
在一个 route 上生成数个结构上显著不同的 UI variants，通过浮动底部 switcher 切换。用户可以选择一个方案，或组合不同方案的优点，其余最终丢弃。
|
|
4
|
+
|
|
5
|
+
若问题是 logic/state，改用 `logic.md`。
|
|
6
|
+
|
|
7
|
+
## 适用情形
|
|
8
|
+
|
|
9
|
+
- “这个 page 应该长什么样？”
|
|
10
|
+
- “实现 dashboard 前先看几个方案。”
|
|
11
|
+
- “尝试 settings screen 的不同 layout。”
|
|
12
|
+
|
|
13
|
+
## 两种形态
|
|
14
|
+
|
|
15
|
+
强烈优先 A。Variant 与真实 header、sidebar、data 和 density 相邻时，才容易判断。
|
|
16
|
+
|
|
17
|
+
### A：调整已有页面
|
|
18
|
+
|
|
19
|
+
Route 已存在。通过 `?variant=` 在同一 route 切换 render subtree；保留原 data fetching、params 和 auth。
|
|
20
|
+
|
|
21
|
+
即使新内容尚无独立 page，只要它自然属于已有 dashboard、settings 或 flow，也仍使用 A，把 variants mount 到 host page。
|
|
22
|
+
|
|
23
|
+
### B：全新页面
|
|
24
|
+
|
|
25
|
+
只有完全没有合理 host page 的全新顶层 surface 或 flow 才使用。
|
|
26
|
+
|
|
27
|
+
按项目 routing convention 创建明确标记 prototype 的 throwaway route，例如 `/prototype/<name>`，同样使用 `?variant=`。不要自创新的顶层目录结构。
|
|
28
|
+
|
|
29
|
+
进入 B 前再次确认：它真的无法嵌入任何现有 page 吗？
|
|
30
|
+
|
|
31
|
+
## 流程
|
|
32
|
+
|
|
33
|
+
### 1. 写明问题并确定数量
|
|
34
|
+
|
|
35
|
+
默认 **3 variants**，最多 5 个。超过 5 个往往不再是 radically different，而只是噪声。
|
|
36
|
+
|
|
37
|
+
在 prototype 位置写一行：
|
|
38
|
+
|
|
39
|
+
> 在现有 `/settings` route 上提供 3 个 settings page variants，通过 `?variant=` 切换。
|
|
40
|
+
|
|
41
|
+
### 2. 生成结构上显著不同的 variants
|
|
42
|
+
|
|
43
|
+
每个 variant 必须符合：
|
|
44
|
+
|
|
45
|
+
- page purpose 与可用 data；
|
|
46
|
+
- 项目已有 component library / styling system；
|
|
47
|
+
- 清楚的 exported component name，例如 `VariantA`、`VariantB`、`VariantC`。
|
|
48
|
+
|
|
49
|
+
Variants 必须在 layout、information hierarchy 或 primary affordance 上不同，而不只是颜色、copy 或 card 间距不同。若两个方案太像，明确要求其中一个不用 card grid 并重新设计。
|
|
50
|
+
|
|
51
|
+
### 3. 连接切换逻辑
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
// pseudo-code：按项目 framework 调整
|
|
55
|
+
const variant = searchParams.get("variant") ?? "A";
|
|
56
|
+
|
|
57
|
+
return (
|
|
58
|
+
<>
|
|
59
|
+
{variant === "A" && <VariantA {...data} />}
|
|
60
|
+
{variant === "B" && <VariantB {...data} />}
|
|
61
|
+
{variant === "C" && <VariantC {...data} />}
|
|
62
|
+
<PrototypeSwitcher
|
|
63
|
+
variants={["A", "B", "C"]}
|
|
64
|
+
current={variant}
|
|
65
|
+
/>
|
|
66
|
+
</>
|
|
67
|
+
);
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Sub-shape A：所有现有 data fetching 保留在 switcher 上方，只替换 render subtree。
|
|
71
|
+
Sub-shape B：throwaway route mount 同一个 switcher。
|
|
72
|
+
|
|
73
|
+
### 4. 浮动 switcher
|
|
74
|
+
|
|
75
|
+
底部中央固定一个小 bar：
|
|
76
|
+
|
|
77
|
+
- 左箭头：切换前一 variant，首尾循环；
|
|
78
|
+
- label：显示当前 key 与名称，例如 `B — Sidebar layout`；
|
|
79
|
+
- 右箭头：切换后一 variant，首尾循环。
|
|
80
|
+
|
|
81
|
+
行为：
|
|
82
|
+
|
|
83
|
+
- 使用项目 router 更新 URL search param，使 variant 可分享、reload 后稳定；
|
|
84
|
+
- `←` 与 `→` 键切换；
|
|
85
|
+
- focus 位于 `input`、`textarea` 或 `[contenteditable]` 时不截获方向键；
|
|
86
|
+
- 视觉上明显独立于被评估页面；
|
|
87
|
+
- 通过 `NODE_ENV !== "production"` 或等价条件确保 production build 隐藏；
|
|
88
|
+
- switcher 只实现一次，放在项目合理的 shared UI 位置。
|
|
89
|
+
|
|
90
|
+
### 5. 交给用户比较
|
|
91
|
+
|
|
92
|
+
给出完整 URL 与 variant keys。用户可能会提出“B 的 header 加 C 的 sidebar”，这种组合反馈正是 prototype 要发现的答案。
|
|
93
|
+
|
|
94
|
+
### 6. 捕获结论并清理
|
|
95
|
+
|
|
96
|
+
选定方案后记录 winner 与原因：
|
|
97
|
+
|
|
98
|
+
- Sub-shape A：把 winner 作为现有 page 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 losing variants 与 switcher。
|
|
99
|
+
- Sub-shape B：把 winner 作为真实 route 的实现输入；只有另行授权 `$implement` 后才写入正式代码，并从主分支移除 throwaway route 与 switcher。
|
|
100
|
+
- 完整 variants 作为 primary source 留在已授权的 throwaway branch，而不是主分支。
|
|
101
|
+
|
|
102
|
+
## 反模式
|
|
103
|
+
|
|
104
|
+
- Variants 只改变颜色或 copy。
|
|
105
|
+
- 共享过多 layout 代码，使各方案无法真正不同。
|
|
106
|
+
- 把 prototype 连接到真实 mutation；需要 mutation 时使用 stub。
|
|
107
|
+
- 把 prototype variant 直接提升为生产实现；正式吸收时必须补生产级错误处理与测试。
|
|
108
|
+
- 把 losing variants 或 switcher 留在主分支腐化。
|
package/skills/research/SKILL.md
CHANGED
|
@@ -1,77 +1,20 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: research
|
|
3
|
-
description:
|
|
3
|
+
description: 当任务需要依据高可信一手资料调查问题、核验文档或 API 事实，或把阅读工作交给后台 agent 时使用。它形成一份带来源的 Markdown artifact；单纯代码定位、已有可靠答案或无需保存研究结果时不使用。
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Research
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
启动一个 **background agent** 执行阅读工作，使调用者可以同时推进其他不依赖研究结论的任务。
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
后台 agent 的职责只有三项：
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
1. 依据 **primary sources** 调查问题：官方文档、源代码、规范、论文或 first-party API，而不是二手总结。每项事实都追溯到拥有该事实的一手来源。
|
|
13
|
+
2. 把结论写入一份 Markdown 文件；每项可验证 claim 或事实都在出现位置直接引用拥有该事实的一手来源，而不是只给整篇文档附一组链接。
|
|
14
|
+
3. 遵循仓库现有研究文档位置与命名约定；没有约定时选择合理位置，并明确返回绝对或仓库相对路径。
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
- 必须回答的 1 至 5 个问题；
|
|
16
|
-
- 时间、版本、平台、预算等适用边界；
|
|
17
|
-
- 什么证据足以改变当前方案；
|
|
18
|
-
- 何时停止研究并进入验证或实施。
|
|
16
|
+
后台 agent 的写入范围只限已约定的研究 artifact。若宿主只提供只读子代理，则子代理返回完整、带引用的报告，由调用者原样落盘；不要因此把研究退化成无引用摘要。
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
在 `wayfinder` 的 research ticket 中，显式工作流且 repo、ticket 与隔离 branch 唯一时，可以写入并 commit artifact、把 artifact 的 context pointer 与独立可读的结论写回 tracker，然后关闭该 research ticket。目标不唯一时先预览；永不自动 push、创建 PR、merge、deploy 或发布。
|
|
21
19
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
按以下顺序寻找证据：
|
|
25
|
-
|
|
26
|
-
1. 当前仓库代码、配置、测试和可复现运行结果；
|
|
27
|
-
2. 官方文档、规范、源代码、发布说明和维护者声明；
|
|
28
|
-
3. 原始论文、数据集或厂商技术资料；
|
|
29
|
-
4. 高质量二手分析，仅用于补充解释或发现线索；
|
|
30
|
-
5. 社区帖子与搜索摘要，只能作为待核验线索。
|
|
31
|
-
|
|
32
|
-
技术问题优先依赖官方文档和原始资料。涉及当前版本、价格、规则、安全或其他可能变化的信息时，必须联网核验日期和版本。不要把搜索结果摘要当作证据。
|
|
33
|
-
|
|
34
|
-
## 执行方式
|
|
35
|
-
|
|
36
|
-
1. 把问题拆成互不重叠的研究项，可并行时分配给只读子代理。
|
|
37
|
-
2. 为每个关键主张记录来源、发布日期或版本、适用范围和可信度。
|
|
38
|
-
3. 交叉核对重要结论。来源冲突时展示冲突，不用多数票代替判断。
|
|
39
|
-
4. 对候选方案使用一致维度比较，例如能力、约束、成熟度、运维成本、迁移成本和退出路径。
|
|
40
|
-
5. 遇到只能通过运行确认的行为，转交 `prototype`，不要从文档继续推测。
|
|
41
|
-
|
|
42
|
-
并行研究时，主 agent 负责统一问题、去重、核验引用并形成最终判断；子代理结论不能直接当成事实。
|
|
43
|
-
|
|
44
|
-
## 输出格式
|
|
45
|
-
|
|
46
|
-
```markdown
|
|
47
|
-
## 研究结论
|
|
48
|
-
- 要支持的决策：
|
|
49
|
-
- 建议：
|
|
50
|
-
- 置信度与适用边界：
|
|
51
|
-
|
|
52
|
-
## 关键证据
|
|
53
|
-
| 主张 | 类型（事实/推断） | 证据 | 日期或版本 | 限制 |
|
|
54
|
-
|
|
55
|
-
## 候选方案
|
|
56
|
-
| 方案 | 优势 | 代价 | 主要风险 | 适用条件 |
|
|
57
|
-
|
|
58
|
-
## 未知项与验证方式
|
|
59
|
-
## 建议下一步
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
引用应尽量靠近它所支持的主张。清楚标记自己的推断，不制造来源未明确表达的确定性。
|
|
63
|
-
|
|
64
|
-
## 完成标准
|
|
65
|
-
|
|
66
|
-
- 每个核心问题都有答案、证据或明确的未知标记。
|
|
67
|
-
- 推荐结论与决策维度直接对应，并包含适用边界。
|
|
68
|
-
- 时间敏感信息已核验日期和版本。
|
|
69
|
-
- 需要运行验证的部分已形成最小原型建议。
|
|
70
|
-
|
|
71
|
-
## 反模式
|
|
72
|
-
|
|
73
|
-
- 不要用链接数量代表研究质量。
|
|
74
|
-
- 不要引用搜索摘要、AI 摘要或无来源转述作为最终证据。
|
|
75
|
-
- 不要忽略与偏好方案相冲突的证据。
|
|
76
|
-
- 不要无限研究；达到停止条件后进入决策或原型。
|
|
77
|
-
- 不要未经验证执行网上获得的高风险命令或脚本。
|
|
20
|
+
研究为访谈、设计和规格提供材料，不代替这些阶段的判断。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
interface:
|
|
2
2
|
display_name: "Research"
|
|
3
|
-
short_description: "
|
|
4
|
-
default_prompt: "请使用 $research
|
|
3
|
+
short_description: "把阅读工作交给后台 agent，并以一手资料形成单一带引用 Markdown"
|
|
4
|
+
default_prompt: "请使用 $research 基于一手资料调查这个问题，并保存一份逐项带引用的 Markdown 结论。"
|
|
5
5
|
policy:
|
|
6
6
|
allow_implicit_invocation: true
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: resolving-merge-conflicts
|
|
3
|
+
description: 当 Git 已处于 merge 或 rebase 中且存在冲突，需要依据双方原始意图逐个 hunk 解决并验证时使用。它不主动发起合并，也不用于普通 diff、cherry-pick 规划或用户想直接 abort 的场景。
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Resolving Merge Conflicts
|
|
7
|
+
|
|
8
|
+
逐 hunk 解决正在进行的 merge 或 rebase。目标是保存双方原始意图，并使项目重新通过检查；不是选择“ours 全赢”或“theirs 全赢”。
|
|
9
|
+
|
|
10
|
+
## 动作门禁
|
|
11
|
+
|
|
12
|
+
用户显式调用本 skill 或明确要求解决当前冲突，且当前仓库确实处于唯一的 merge/rebase 状态时，用一句话预告后自动修改冲突文件、删除 conflict markers、运行检查、stage 已解决文件，并继续当前操作直至完成；merge 可产生当前操作所需的 merge commit，rebase 遇到后续冲突时重复本流程。
|
|
13
|
+
|
|
14
|
+
模型只是隐式发现冲突、用户只要求分析、操作目标不唯一，或继续会包含未归属改动时，停在只读诊断或 verified + staged 状态并请求方向。
|
|
15
|
+
|
|
16
|
+
永不自动发起新的 merge/rebase，也不自动 push、创建 PR、merge 其他分支、deploy 或发布。
|
|
17
|
+
|
|
18
|
+
操作类型不明、多个 worktree 状态混淆或冲突文件含用户未归属改动时，先只读展示状态并询问。
|
|
19
|
+
|
|
20
|
+
本 skill 不执行 abort；若用户目标是放弃操作，应停止并把它作为独立破坏性请求处理。
|
|
21
|
+
|
|
22
|
+
## 读取当前状态
|
|
23
|
+
|
|
24
|
+
确认：
|
|
25
|
+
|
|
26
|
+
```shell
|
|
27
|
+
git status
|
|
28
|
+
git diff --name-only --diff-filter=U
|
|
29
|
+
git ls-files -u
|
|
30
|
+
git log --oneline --decorate --graph -n 30
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
识别：
|
|
34
|
+
|
|
35
|
+
- merge 还是 rebase；
|
|
36
|
+
- 当前 commit 与另一侧；
|
|
37
|
+
- 未合并文件；
|
|
38
|
+
- staged、unstaged 和无关用户改动；
|
|
39
|
+
- 是否存在 rename/delete、binary、submodule 或生成文件冲突。
|
|
40
|
+
|
|
41
|
+
没有进行中的操作或没有冲突时停止，说明本 skill 不适用。
|
|
42
|
+
|
|
43
|
+
## 找到双方的一手来源
|
|
44
|
+
|
|
45
|
+
对每个冲突理解：
|
|
46
|
+
|
|
47
|
+
- base、ours、theirs 的内容；
|
|
48
|
+
- 两侧相关 commit message；
|
|
49
|
+
- branch/PR 的目标；
|
|
50
|
+
- 原始 issue、ticket、spec 或 ADR；
|
|
51
|
+
- 相邻测试揭示的 contract。
|
|
52
|
+
|
|
53
|
+
优先读取拥有意图的一手来源。无法获取 PR 或 issue 时明确缺口，不猜测。
|
|
54
|
+
|
|
55
|
+
## 逐个 hunk 解决
|
|
56
|
+
|
|
57
|
+
每个 hunk：
|
|
58
|
+
|
|
59
|
+
1. 用一句话描述 ours 的意图；
|
|
60
|
+
2. 用一句话描述 theirs 的意图；
|
|
61
|
+
3. 判断两者是否兼容；
|
|
62
|
+
4. 兼容时组合并保留双方行为；
|
|
63
|
+
5. 不兼容时选择更符合当前 merge/rebase 明确目标的一侧，并记录 trade-off；
|
|
64
|
+
6. 删除 markers；
|
|
65
|
+
7. 运行最小定向验证。
|
|
66
|
+
|
|
67
|
+
不得发明两侧都没有的新行为。不得机械使用整文件 ours/theirs，除非 primary sources 证明整文件替换就是正确意图。
|
|
68
|
+
|
|
69
|
+
生成文件优先通过项目生成流程重建；lockfile 使用项目认可工具重建，不手工拼接。
|
|
70
|
+
|
|
71
|
+
## 验证
|
|
72
|
+
|
|
73
|
+
先确认没有未解决 markers 和 unmerged entries，再运行仓库 canonical checks，并服从仓库规定的顺序。仓库没有规定时采用上游默认：**typecheck → tests → format**：
|
|
74
|
+
|
|
75
|
+
1. typecheck / compile；
|
|
76
|
+
2. 定向 tests，风险允许时再运行完整测试；
|
|
77
|
+
3. format 或生成检查。
|
|
78
|
+
|
|
79
|
+
修复只限于 merge 造成的问题。历史失败单独报告。
|
|
80
|
+
|
|
81
|
+
检查最终 diff 是否意外丢失某一侧的行为。
|
|
82
|
+
|
|
83
|
+
## 暂存并继续
|
|
84
|
+
|
|
85
|
+
只 stage 已解决且属于当前操作的文件。
|
|
86
|
+
|
|
87
|
+
在动作门禁允许继续时：
|
|
88
|
+
|
|
89
|
+
- merge：执行项目要求的 continue/commit；
|
|
90
|
+
- rebase：继续到下一 commit；若出现新冲突，重复本流程，直到 rebase 完成。
|
|
91
|
+
|
|
92
|
+
动作门禁不允许继续时，报告剩余操作并给出准确 continue 命令，不自行执行。
|
|
93
|
+
|
|
94
|
+
完成后再次检查 status、log 和 tests。不得 push。
|