@gavinmo1/skills 0.1.1 → 0.2.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/README.md +5 -1
- package/bin/cli.mjs +15 -2
- package/package.json +1 -1
- package/skills/ai-explore-inline/SKILL.md +227 -0
- package/skills/ai-explore-inline/references/output-template.md +94 -0
- package/skills/ai-explore-inline/references/questioner-guide.md +156 -0
- package/skills/deep-generate/SKILL.md +124 -0
- package/skills/deep-generate/references/delivery-checklist.md +20 -0
- package/skills/deep-generate/references/error-handling.md +21 -0
- package/skills/deep-generate/references/output-templates.md +68 -0
- package/skills/deep-generate/references/research-protocol.md +34 -0
- package/skills/deep-generate/references/scoring-rubric.md +41 -0
- package/skills/deep-generate/references/self-check-list.md +37 -0
- package/skills/deep-generate/references/state-protocol.md +78 -0
- package/skills/deep-generate/scripts/check-state.py +253 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# skills
|
|
2
2
|
|
|
3
|
-
Agent skill 集合。每个 skill 是 `skills/` 下的一个目录,目录里必须有 `SKILL.md`(frontmatter 含 `name` 与 `description`),可选 `references/`、`agents/` 等附属文件。
|
|
3
|
+
Agent skill 集合。每个 skill 是 `skills/` 下的一个目录,目录里必须有 `SKILL.md`(frontmatter 含 `name` 与 `description`),可选 `references/`、`scripts/`、`agents/` 等附属文件。
|
|
4
4
|
|
|
5
5
|
## 安装
|
|
6
6
|
|
|
@@ -66,8 +66,12 @@ npx github:GavinMo1/skills-repo add plan-review-loop --dir ~/.claude/skills
|
|
|
66
66
|
|
|
67
67
|
| skill | 用途 |
|
|
68
68
|
|---|---|
|
|
69
|
+
| ai-explore-inline | 深度探索(内联模式):主 agent 自己扮演回答者和追问者,在同一上下文内多轮深挖。快、连贯,但追问者易被回答者逻辑带着走 |
|
|
70
|
+
| deep-generate | 从零生成主题深度系列文章:先定读者要解决的问题,再知识梳理、章节设计、分工撰写、独立评审、整合交付 |
|
|
69
71
|
| plan-review-loop | 制定或修订要交给用户执行的方案时,用独立评审、修订、复评闭环,产出可直接开工的方案 |
|
|
70
72
|
|
|
73
|
+
部分 skill 的正文会路由到兄弟 skill(`ai-explore-inline` → `ai-explore-agents` / `ai-debate` / `deep-analyze`,`deep-generate` → `reader-review`)。这些只是「该走哪个技能」的分诊提示,不属于文件依赖,装不上不影响使用;需要时另行安装即可。`deep-generate` 的 frontmatter 保留着原作者的 `disable-model-invocation: true` 字段,原样收录、未作改动。
|
|
74
|
+
|
|
71
75
|
## 添加新 skill
|
|
72
76
|
|
|
73
77
|
1. 新建 `skills/<name>/`,放入 `SKILL.md`;附属文件一并放进去(安装器整目录复制)。
|
package/bin/cli.mjs
CHANGED
|
@@ -59,9 +59,22 @@ async function metaOf(dir) {
|
|
|
59
59
|
const text = await readFile(file, 'utf8');
|
|
60
60
|
const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
|
61
61
|
if (!fm) return { name: path.basename(dir), description: '(缺 frontmatter)' };
|
|
62
|
+
const lines = fm[1].split(/\r?\n/);
|
|
62
63
|
const pick = (key) => {
|
|
63
|
-
const
|
|
64
|
-
|
|
64
|
+
const i = lines.findIndex((l) => new RegExp(`^${key}:`).test(l));
|
|
65
|
+
if (i < 0) return '';
|
|
66
|
+
let rest = lines[i].slice(lines[i].indexOf(':') + 1).trim();
|
|
67
|
+
// YAML 块标量(>- / > / | / |- / |+):取缩进续行,folding 用空格连接
|
|
68
|
+
if (/^[>|][+-]?$/.test(rest)) {
|
|
69
|
+
const folded = rest[0] === '>';
|
|
70
|
+
const body = [];
|
|
71
|
+
for (let j = i + 1; j < lines.length; j++) {
|
|
72
|
+
if (lines[j].trim() === '' || /^\s/.test(lines[j])) body.push(lines[j].trim());
|
|
73
|
+
else break;
|
|
74
|
+
}
|
|
75
|
+
return body.filter(Boolean).join(folded ? ' ' : '\n');
|
|
76
|
+
}
|
|
77
|
+
return rest.replace(/^["']|["']$/g, '');
|
|
65
78
|
};
|
|
66
79
|
return { name: pick('name') || path.basename(dir), description: pick('description') };
|
|
67
80
|
}
|
package/package.json
CHANGED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ai-explore-inline
|
|
3
|
+
description: >-
|
|
4
|
+
深度探索(内联模式):主 agent 自己扮演回答者和追问者两个角色,在同一上下文内
|
|
5
|
+
完成多轮深度对话。速度快、上下文连贯,但追问者可能被回答者逻辑带着走。
|
|
6
|
+
当用户提到「帮我深入了解一下」「这个问题值得深挖」「explore」「探索一下」
|
|
7
|
+
「把这个概念搞清楚」,或输入一个简单问题但希望深入理解时使用。
|
|
8
|
+
不适用于:多角色辩论(走 ai-debate)、已有文档分析(走 deep-analyze)、
|
|
9
|
+
从零生成长文(走 deep-generate)、纯信息查询(一个回答就够)。
|
|
10
|
+
metadata:
|
|
11
|
+
version: "1.0.0"
|
|
12
|
+
category: thinking
|
|
13
|
+
variant: inline
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# AI Explore(内联模式)— 深度探索对话
|
|
17
|
+
|
|
18
|
+
> **模式说明**:回答者和追问者都由主 agent 在同一上下文内扮演。不调用子 agent。
|
|
19
|
+
> 优势:速度快、上下文完整不丢失细节、逻辑链连贯。
|
|
20
|
+
> 劣势:追问者知道回答者的推理过程,提问可能不够"陌生"和犀利。
|
|
21
|
+
> 如果需要真正独立的追问视角 → 用 `ai-explore-agents`。
|
|
22
|
+
|
|
23
|
+
## 核心机制
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
用户输入 → [回答者回答] → [追问者提问] → [回答者回答] → ... → 收敛 → 输出完整对话
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
两个角色,始终只有两个:
|
|
30
|
+
- **回答者**:提供知识、解释、分析、例子、类比
|
|
31
|
+
- **追问者**:专职提问——替你问 + 帮你发现
|
|
32
|
+
|
|
33
|
+
## 执行模式:内联自演(不调用子 agent)
|
|
34
|
+
|
|
35
|
+
**主 agent 在同一个上下文里交替扮演两个角色。** 具体操作:
|
|
36
|
+
|
|
37
|
+
1. 主 agent 以"回答者"身份生成回答 → 写入文件
|
|
38
|
+
2. 主 agent **切换视角**,以"追问者"身份审视刚生成的回答,找到最有价值的追问 → 写入文件
|
|
39
|
+
3. 主 agent 再切换回"回答者"身份回答 → 写入文件
|
|
40
|
+
4. 重复直到收敛
|
|
41
|
+
|
|
42
|
+
**切换视角时的关键操作**:
|
|
43
|
+
- 回答者写完后,**主动反思自己的盲区**——"我刚才的推理跳过了什么?假设了什么?"
|
|
44
|
+
- 追问者提问时,**假装自己是第一次读到这个回答的读者**——"哪里没看懂?哪里觉得可疑?哪里觉得值得深入?"
|
|
45
|
+
- 追问者**只看回答的文字输出**,不要利用自己推理过程中"知道但没说出来"的信息来提问
|
|
46
|
+
|
|
47
|
+
## 流式写入 REQUIRED
|
|
48
|
+
|
|
49
|
+
每轮完成后 **立即 append 到输出文件**,不要等到最后才写。这样即使中途中断,已完成的轮次也不会丢失。
|
|
50
|
+
|
|
51
|
+
**输出文件路径**:当前工作目录下 `ai-explore-{主题关键词}.md`(英文短横线连接,2-4 个词概括主题)。
|
|
52
|
+
|
|
53
|
+
**文件初始化**(Phase 0 完成后):
|
|
54
|
+
- 用 `write` 创建文件,写入标题、问题目录表头、`## 完整对话` 标题
|
|
55
|
+
- 后续每轮用 `edit` 或 bash `echo >>` append,不要覆盖已有内容
|
|
56
|
+
|
|
57
|
+
**原文保留规则**(Phase 0 同步执行):用户的原始输入有独立阅读价值,必须保留在输出文件中,不要丢弃。
|
|
58
|
+
- **短原文**(≤500字左右):在文件标题和问题目录之间插入 `## 用户原文`,用 `<details><summary>点击展开用户原文</summary>` 包裹原文全文,`</details>` 结束。
|
|
59
|
+
- **长原文**(>500字):原文单独存为 `ai-explore-{主题关键词}-source.md`,主文件在标题下方放一行引用链接。
|
|
60
|
+
|
|
61
|
+
**写入节奏**:
|
|
62
|
+
| 时机 | 写入内容 |
|
|
63
|
+
|------|---------|
|
|
64
|
+
| Phase 0 完成 | 文件头(标题 + **原文折叠/链接** + 目录表头 + 对话标题) |
|
|
65
|
+
| 每轮回答者回答后 | 该轮完整内容(追问 + 回答) |
|
|
66
|
+
| Phase 2 收敛 | 探索摘要 |
|
|
67
|
+
| 最后 | 回填问题目录表 |
|
|
68
|
+
|
|
69
|
+
## 异常与失败处理 REQUIRED
|
|
70
|
+
|
|
71
|
+
- context 过长 → 每轮对前序对话做摘要压缩,保留关键论点原文
|
|
72
|
+
- 收敛判断不确定 → 倾向多问一轮(保守策略)
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
### Phase 0: 理解输入
|
|
77
|
+
|
|
78
|
+
1. 读取用户的输入(想法、概念、问题、或一段话)
|
|
79
|
+
2. 识别主题领域和复杂度
|
|
80
|
+
3. 确定输出文件名:`ai-explore-{主题关键词}.md`,创建文件并写入标题和骨架
|
|
81
|
+
4. 如果输入过于模糊 → 问一个澄清问题,然后继续
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
### Phase 1: 第一轮回答
|
|
86
|
+
|
|
87
|
+
直接以回答者身份给出第一轮回答。回答完成后 **立即 append 到输出文件**。
|
|
88
|
+
|
|
89
|
+
**回答者的 prompt**:
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
用户提出了以下问题/概念/想法:
|
|
93
|
+
|
|
94
|
+
「{用户输入}」
|
|
95
|
+
|
|
96
|
+
请给出第一轮回答。要求:
|
|
97
|
+
1. 核心解释——用清晰、准确的语言解释这个概念/回答这个问题
|
|
98
|
+
2. 关键前提——你的回答建立在哪些假设之上?
|
|
99
|
+
3. 具体例子——至少一个具体案例或类比帮助理解
|
|
100
|
+
4. 边界条件——你的回答在什么情况下不成立?
|
|
101
|
+
5. 值得知道的意外——有什么反直觉的点?
|
|
102
|
+
|
|
103
|
+
回答风格:清晰 > 花哨。一句话只说一件事。有歧义时拆成两句。
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
### Phase 2: 探索循环
|
|
109
|
+
|
|
110
|
+
每轮包含:**追问者提问 → 回答者回答**
|
|
111
|
+
|
|
112
|
+
#### 2.1 追问者提问(内联:主 agent 切换视角)
|
|
113
|
+
|
|
114
|
+
先读取 [`references/questioner-guide.md`](references/questioner-guide.md) 完整内容。然后**切换到追问者视角**,基于上一轮回答生成问题。
|
|
115
|
+
|
|
116
|
+
**追问者的 prompt**:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
你是一个专业追问者。你的职责不是回答问题,而是提出下一个最有价值的问题。
|
|
120
|
+
|
|
121
|
+
你有两重职责:
|
|
122
|
+
1. **替用户问**:填补理解缺口,追究说不清的地方,匹配用户可能的知识基础
|
|
123
|
+
2. **帮用户发现**:提出用户未必会想到、但看了会觉得值得的问题
|
|
124
|
+
|
|
125
|
+
当前对话历史:
|
|
126
|
+
{conversation_history}
|
|
127
|
+
|
|
128
|
+
上一轮回答:
|
|
129
|
+
{last_answer}
|
|
130
|
+
|
|
131
|
+
追问质量要求(详见 questioner-guide.md):
|
|
132
|
+
- 检查:读者可能没真正理解的地方?
|
|
133
|
+
- 检查:回答暗含了什么前提?
|
|
134
|
+
- 检查:有没有反例或具体例子能帮助理解?
|
|
135
|
+
- 检查:如果这是真的,会推导出什么有意思的结论?
|
|
136
|
+
- 检查:它和其他已知概念有什么联系?
|
|
137
|
+
- 检查:哪个意外的方向值得顺着探索?
|
|
138
|
+
|
|
139
|
+
反模式(必须避免):
|
|
140
|
+
- 不要重复问已经覆盖的问题(换个说法也不行)
|
|
141
|
+
- 不要突然跳到完全不相关的领域
|
|
142
|
+
- 不要为了凑轮数不停深挖同一个点
|
|
143
|
+
|
|
144
|
+
输出格式:
|
|
145
|
+
{
|
|
146
|
+
"question": "你的下一个问题",
|
|
147
|
+
"rationale": "为什么这个问题值得问(一句话)",
|
|
148
|
+
"category": "理解缺口/前提追究/反例探索/推导延伸/跨界联系/意外方向",
|
|
149
|
+
"confidence_this_question_is_valuable": 1-10
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**收敛自评**:
|
|
154
|
+
|
|
155
|
+
如果 `confidence_this_question_is_valuable < 6`,追问者应输出:
|
|
156
|
+
```json
|
|
157
|
+
{
|
|
158
|
+
"question": null,
|
|
159
|
+
"stop_reason": "没有足够有价值的新问题了",
|
|
160
|
+
"coverage_summary": "已覆盖的主要方向总结"
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
#### 2.2 回答者回答
|
|
165
|
+
|
|
166
|
+
基于追问者的问题给出回答。**回答完成后,立即 append 该轮内容到输出文件。**
|
|
167
|
+
|
|
168
|
+
**回答者的 prompt**:
|
|
169
|
+
|
|
170
|
+
```
|
|
171
|
+
你正在和一位追问者进行深度探索对话。用户会阅读完整对话记录。
|
|
172
|
+
|
|
173
|
+
当前对话历史:
|
|
174
|
+
{conversation_history}
|
|
175
|
+
|
|
176
|
+
追问者的最新问题:
|
|
177
|
+
{question}
|
|
178
|
+
|
|
179
|
+
请回答这个问题。要求:
|
|
180
|
+
1. 直接回答——先给结论/答案,再展开
|
|
181
|
+
2. 具体——用案例、数据、代码、类比,不要纯抽象
|
|
182
|
+
3. 诚实——不确定的说不确定,有争议的列出不同观点
|
|
183
|
+
4. 衔接——如果和前面的回答有关联,明确指出来
|
|
184
|
+
5. 意外——尽量包含一个读者不知道但有价值的信息
|
|
185
|
+
|
|
186
|
+
回答风格:清晰 > 花哨。一句话只说一件事。有歧义时拆成两句。
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
#### 2.3 用户介入点
|
|
190
|
+
|
|
191
|
+
每轮结束后:
|
|
192
|
+
- 追问者输出问题后,如果用户输入了指令 → 执行(调整方向、深入某点、跳过、结束)
|
|
193
|
+
- 用户说「继续」或无回应 → 回答者回答,进入下一轮
|
|
194
|
+
- 用户说「结束」→ 进入 Phase 3
|
|
195
|
+
|
|
196
|
+
#### 2.4 收敛判断
|
|
197
|
+
|
|
198
|
+
由追问者的 `confidence_this_question_is_valuable` 驱动:
|
|
199
|
+
|
|
200
|
+
- confidence >= 6 → CONTINUE
|
|
201
|
+
- confidence < 6 → CONVERGE
|
|
202
|
+
- 达到 10 轮 → 强制 CONVERGE
|
|
203
|
+
- 用户要求结束 → CONVERGE
|
|
204
|
+
|
|
205
|
+
**保守策略**:拿不准时倾向多问一轮。
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
### Phase 3: 收尾输出
|
|
210
|
+
|
|
211
|
+
1. **回填问题目录表**
|
|
212
|
+
2. **Append 探索摘要**(覆盖方向、关键发现、未探索方向、核心结论)
|
|
213
|
+
3. **告知用户文件路径**
|
|
214
|
+
|
|
215
|
+
格式见 [`references/output-template.md`](references/output-template.md)。
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## 关于追问质量
|
|
220
|
+
|
|
221
|
+
追问者是整个系统的灵魂。详见 [`references/questioner-guide.md`](references/questioner-guide.md)。
|
|
222
|
+
|
|
223
|
+
核心原则:
|
|
224
|
+
- **不重复**:已覆盖的问题不问第二遍(换个说法也不行)
|
|
225
|
+
- **不跳跃**:问题之间有逻辑链条,不要突然跳到完全不相关的领域
|
|
226
|
+
- **不凑数**:没有好问题就停,不要为了轮数硬问
|
|
227
|
+
- **有价值**:每个问题都应该让读者觉得「这个问得好」
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# 探索输出模板
|
|
2
|
+
|
|
3
|
+
## 输出路径
|
|
4
|
+
|
|
5
|
+
文件写在 **当前工作目录**,命名规则:`ai-explore-{主题关键词}.md`
|
|
6
|
+
- 主题关键词用英文短横线连接,2-4 个词,概括核心主题
|
|
7
|
+
- 示例:`ai-explore-ai-agent-strategy.md`、`ai-explore-rust-error-handling.md`
|
|
8
|
+
|
|
9
|
+
## 完整对话记录格式
|
|
10
|
+
|
|
11
|
+
```markdown
|
|
12
|
+
# 深度探索:{主题}
|
|
13
|
+
|
|
14
|
+
## 问题目录
|
|
15
|
+
|
|
16
|
+
| # | 问题 | 类型 | 轮次 |
|
|
17
|
+
|---|------|------|------|
|
|
18
|
+
| 1 | {初始问题/概念} | 入口 | 1 |
|
|
19
|
+
| 2 | {追问1} | {理解缺口/前提追究/...} | 2 |
|
|
20
|
+
| 3 | {追问2} | {类型} | 3 |
|
|
21
|
+
| ... | ... | ... | ... |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 完整对话
|
|
26
|
+
|
|
27
|
+
### 第 1 轮
|
|
28
|
+
|
|
29
|
+
**用户**:{原始输入}
|
|
30
|
+
|
|
31
|
+
**回答者**:
|
|
32
|
+
{回答}
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
### 第 2 轮
|
|
37
|
+
|
|
38
|
+
**追问者**:{问题}
|
|
39
|
+
> *为什么问这个:{rationale}*
|
|
40
|
+
|
|
41
|
+
**回答者**:
|
|
42
|
+
{回答}
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
### 第 3 轮
|
|
47
|
+
|
|
48
|
+
**追问者**:{问题}
|
|
49
|
+
> *为什么问这个:{rationale}*
|
|
50
|
+
|
|
51
|
+
**回答者**:
|
|
52
|
+
{回答}
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
...(依此类推)
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 探索摘要
|
|
61
|
+
|
|
62
|
+
### 覆盖的主要方向
|
|
63
|
+
- **{方向1}**:{一句话说明覆盖了什么}
|
|
64
|
+
- **{方向2}**:{一句话说明}
|
|
65
|
+
- ...
|
|
66
|
+
|
|
67
|
+
### 关键发现
|
|
68
|
+
- {最有价值的发现1}
|
|
69
|
+
- {最有价值的发现2}
|
|
70
|
+
- ...
|
|
71
|
+
|
|
72
|
+
### 未探索的方向
|
|
73
|
+
- **{方向1}**:{为什么值得但没深入}
|
|
74
|
+
- **{方向2}**:{为什么值得但没深入}
|
|
75
|
+
|
|
76
|
+
### 核心结论
|
|
77
|
+
{一段话总结这次探索的核心收获}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 质量标准
|
|
83
|
+
|
|
84
|
+
### 对话记录
|
|
85
|
+
1. **忠实于原始回答**:不歪曲、不简化关键论点
|
|
86
|
+
2. **保留关键原文**:重要的解释用原文,不用摘要替代
|
|
87
|
+
3. **问题目录完整**:每个追问都列出,方便跳读
|
|
88
|
+
4. **rationale 保留**:每个追问的「为什么问这个」保留,帮助读者理解探索逻辑
|
|
89
|
+
5. **输出位置**:文件写在当前工作目录,不是 `local://` 内部路径
|
|
90
|
+
|
|
91
|
+
### 探索摘要
|
|
92
|
+
1. **不替代对话**:摘要是辅助导航,不是替代品——读者应该能通过目录跳到感兴趣的部分
|
|
93
|
+
2. **诚实**:未探索的方向如实列出,不假装已覆盖
|
|
94
|
+
3. **结论有依据**:核心结论必须能从对话中推导出来,不能凭空产生
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# 追问者质量指南
|
|
2
|
+
|
|
3
|
+
## 核心身份
|
|
4
|
+
|
|
5
|
+
你是一个专业追问者。你的职责不是回答问题,而是提出下一个最有价值的问题。
|
|
6
|
+
|
|
7
|
+
你有两重职责:
|
|
8
|
+
1. **替用户问**:填补理解缺口,追究说不清的地方,匹配用户可能的知识基础
|
|
9
|
+
2. **帮用户发现**:提出用户未必会想到、但看了会觉得值得的问题
|
|
10
|
+
|
|
11
|
+
你不可能准确预测用户每一步会想什么。更合理的目标是:**生成一条用户愿意读下去的探索路径**。
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 追问的六个维度
|
|
16
|
+
|
|
17
|
+
每轮追问前,从以下六个维度检查上一轮回答,找到最有价值的追问方向:
|
|
18
|
+
|
|
19
|
+
### 1. 理解缺口
|
|
20
|
+
**问自己**:读者可能没真正理解的地方是什么?
|
|
21
|
+
|
|
22
|
+
- 回答中有没有用了读者可能不熟悉的概念但没解释?
|
|
23
|
+
- 有没有逻辑跳跃——从 A 到 C,但 B 被省略了?
|
|
24
|
+
- 有没有「这显然是」但实际上并不显然的环节?
|
|
25
|
+
|
|
26
|
+
**追问示例**:
|
|
27
|
+
- 「你提到了 X,但我不太理解它和 Y 的区别是什么?」
|
|
28
|
+
- 「从 A 到 B 的推导中间,是不是跳过了一个关键步骤?」
|
|
29
|
+
|
|
30
|
+
### 2. 前提追究
|
|
31
|
+
**问自己**:回答暗含了什么前提?
|
|
32
|
+
|
|
33
|
+
- 这个回答建立在哪些假设之上?
|
|
34
|
+
- 如果这些假设不成立,结论会怎样变化?
|
|
35
|
+
- 有没有被当作「理所当然」但实际上有争议的前提?
|
|
36
|
+
|
|
37
|
+
**追问示例**:
|
|
38
|
+
- 「你这个结论的前提是 X 对吧?如果 X 不成立呢?」
|
|
39
|
+
- 「你假设了用户会按预期方式使用,但现实中呢?」
|
|
40
|
+
|
|
41
|
+
### 3. 反例与具象
|
|
42
|
+
**问自己**:有没有反例或具体例子能帮助理解?
|
|
43
|
+
|
|
44
|
+
- 有没有真实世界的案例可以印证或反驳这个观点?
|
|
45
|
+
- 有没有一个极端情况能暴露这个理论的边界?
|
|
46
|
+
- 能不能用一个日常类比让这个概念更直观?
|
|
47
|
+
|
|
48
|
+
**追问示例**:
|
|
49
|
+
- 「有没有一个真实案例能说明这个?」
|
|
50
|
+
- 「如果把这个放到极端情况下(比如规模扩大 100 倍),还成立吗?」
|
|
51
|
+
|
|
52
|
+
### 4. 推导延伸
|
|
53
|
+
**问自己**:如果这是真的,会推导出什么有意思的结论?
|
|
54
|
+
|
|
55
|
+
- 这个观点的逻辑终点是什么?
|
|
56
|
+
- 如果顺着这个思路走下去,会发现什么?
|
|
57
|
+
- 这个结论对相关领域有什么影响?
|
|
58
|
+
|
|
59
|
+
**追问示例**:
|
|
60
|
+
- 「如果按你说的,那是不是意味着 X 也应该是这样的?」
|
|
61
|
+
- 「这个逻辑推到极端,会得出什么结论?」
|
|
62
|
+
|
|
63
|
+
### 5. 跨界联系
|
|
64
|
+
**问自己**:它和其他已知概念有什么联系?
|
|
65
|
+
|
|
66
|
+
- 这个概念在其他领域有没有类似的东西?
|
|
67
|
+
- 有没有可以借鉴的类比或对照?
|
|
68
|
+
- 这个问题和其他热门话题有什么关联?
|
|
69
|
+
|
|
70
|
+
**追问示例**:
|
|
71
|
+
- 「这让我想到了 X 领域的 Y,它们之间有共通之处吗?」
|
|
72
|
+
- 「这个模式在 Z 领域也出现过,背后的原理是一样的吗?」
|
|
73
|
+
|
|
74
|
+
### 6. 意外方向
|
|
75
|
+
**问自己**:哪个意外的方向值得顺着探索?
|
|
76
|
+
|
|
77
|
+
- 有没有一个读者不会主动想到、但了解后会觉得「原来如此」的角度?
|
|
78
|
+
- 有没有被大多数人忽略的细节?
|
|
79
|
+
- 有没有一个反直觉的推论?
|
|
80
|
+
|
|
81
|
+
**追问示例**:
|
|
82
|
+
- 「大多数人关注的是 X,但 Y 是不是才是更关键的问题?」
|
|
83
|
+
- 「有一个很少被讨论的角度:...」
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## 反模式(必须避免)
|
|
88
|
+
|
|
89
|
+
### ❌ 重复
|
|
90
|
+
已覆盖的问题不问第二遍。换个说法也不行。如果真的需要从不同角度重访同一个点,必须明确说明为什么需要重访。
|
|
91
|
+
|
|
92
|
+
**检测方法**:对比对话历史中所有已问问题的核心主题。如果新问题的核心和之前某个问题高度重叠,放弃。
|
|
93
|
+
|
|
94
|
+
### ❌ 跳跃
|
|
95
|
+
问题之间需要有逻辑链条。不要从「数据结构的选择」突然跳到「公司的商业模式」,除非你能清晰地建立连接。
|
|
96
|
+
|
|
97
|
+
**检测方法**:新问题能不能用一句话和上一轮回答建立联系?如果不能,要么找到联系并说明,要么换一个问题。
|
|
98
|
+
|
|
99
|
+
### ❌ 凑数
|
|
100
|
+
没有好问题就停。不要为了凑轮数问一些低价值的问题(比如「你还有什么补充吗?」这种万能问题)。
|
|
101
|
+
|
|
102
|
+
**检测方法**:你的 confidence_this_question_is_valuable 如果 < 6,就应该停了。
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## 追问节奏
|
|
107
|
+
|
|
108
|
+
好的探索对话有节奏感:
|
|
109
|
+
|
|
110
|
+
1. **前 1-2 轮**:补理解缺口,确保基础概念清晰
|
|
111
|
+
2. **中间轮次**:推导延伸、跨界联系,拓宽视野
|
|
112
|
+
3. **后期轮次**:意外方向、边界条件,收束到有价值的结论
|
|
113
|
+
|
|
114
|
+
不要在第 1 轮就问「这对人类文明有什么深远影响」——先把基础搞清楚。
|
|
115
|
+
不要在第 8 轮还在问「X 和 Y 的区别是什么」——基础问题应该早期解决。
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 收敛信号
|
|
120
|
+
|
|
121
|
+
**继续**(至少一个成立):
|
|
122
|
+
- 上一轮回答中暴露了新的理解缺口
|
|
123
|
+
- 有一个推导延伸的链条还没走完
|
|
124
|
+
- 出现了一个值得探索的意外方向
|
|
125
|
+
|
|
126
|
+
**收敛**(全部成立):
|
|
127
|
+
- 核心概念已经清晰
|
|
128
|
+
- 主要方向已经覆盖
|
|
129
|
+
- 下一个问题的 confidence < 6
|
|
130
|
+
|
|
131
|
+
**强制收敛**:
|
|
132
|
+
- 达到 10 轮上限
|
|
133
|
+
- 连续 2 轮问题都是对同一个点的重复变体
|
|
134
|
+
- 用户要求结束
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 输出格式
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"question": "你的下一个问题",
|
|
143
|
+
"rationale": "为什么这个问题值得问(一句话)",
|
|
144
|
+
"category": "理解缺口/前提追究/反例探索/推导延伸/跨界联系/意外方向",
|
|
145
|
+
"confidence_this_question_is_valuable": 1-10
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
如果应该停止:
|
|
150
|
+
```json
|
|
151
|
+
{
|
|
152
|
+
"question": null,
|
|
153
|
+
"stop_reason": "没有足够有价值的新问题了",
|
|
154
|
+
"coverage_summary": "已覆盖的主要方向总结"
|
|
155
|
+
}
|
|
156
|
+
```
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deep-generate
|
|
3
|
+
description: Generate comprehensive multi-article deep-dive series from scratch on a given topic, with gap analysis and parallel blind review.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Deep Generate — 全新主题深度系列生成器
|
|
8
|
+
|
|
9
|
+
## 任务与边界
|
|
10
|
+
|
|
11
|
+
用户给出主题,需要从零生成一套深度解析系列文章时,使用本技能。先确定读者需要解决的问题,再梳理知识、设计章节、分工撰写与独立评审,最后整合交付。不用于仅分析现成文档或回答一个普通问题。
|
|
12
|
+
|
|
13
|
+
默认中文、Markdown;用户另有语言要求时遵从用户。章节数量和篇幅由必要问题、解释难度和阅读用途决定,不设置内容配额。保留足够的依据、推导、例子和限制,使读者能够理解结论、作出判断或执行适用的操作。
|
|
14
|
+
|
|
15
|
+
## 执行约定
|
|
16
|
+
|
|
17
|
+
- **主协调者**负责结构、任务分配、文件核对、跨章整合和交付状态。**撰写者**负责章节与自检。**评审者**独立检查章节,不能由该章作者或修改者担任。
|
|
18
|
+
- 使用环境提供的子 Agent 和并行能力。独立任务在可用并发容量内并行;有依赖的任务先等必要输入。不要依赖某个平台专有的参数或工具名称。
|
|
19
|
+
- 给子 Agent 提供任务范围、必要上下文、可访问的参考文件路径、输入版本、输出路径和完成条件。同一文件同时只由一个执行者修改。
|
|
20
|
+
- **当前状态只维护一份。** 由主协调者维护 `_work/本次任务标识/任务状态.json`,记录文件、当前版本、作者与修改者、评审依据和下一步。执行者提交正文与报告,不修改总清单。首次登记、派发评审或恢复任务前,读取[状态协议](references/state-protocol.md)。快照、原始报告和正文是判断依据;不另建需要人工同步的近义清单。
|
|
21
|
+
- 如果独立 Agent 不可用,先完成不依赖该能力的准备工作。向用户说明无法独立评审;只有用户接受后,才改为顺序撰写与自检,并标明未完成独立评审。不得把自检称为盲审。
|
|
22
|
+
- 主协调者首次执行前读取 [异常处理](references/error-handling.md);出现异常时查阅对应规则,无须每一步重复读取。
|
|
23
|
+
|
|
24
|
+
## 1. 明确目标与建立知识图谱
|
|
25
|
+
|
|
26
|
+
根据请求确定目标读者、已有知识、阅读用途、主题范围和时效要求。可合理推定的信息写入任务说明;只有缺失信息会实质改变内容或结构时才询问。用户未要求确认的阶段可连续推进,不增加固定确认节点。
|
|
27
|
+
|
|
28
|
+
输出到用户指定目录,未指定时使用当前工作目录下的主题目录。先确认路径可用。将本次知识图谱、结构设计、资料记录、版本快照和评审放入主题目录的 `_work/本次任务标识/`;任务标识应与已有运行区分。不要覆盖其他任务的文件。
|
|
29
|
+
|
|
30
|
+
开始搜集资料和建立知识图谱前,读取 [资料与证据规则](references/research-protocol.md)。需要记录知识图谱和章节结构时,读取 [输出模板](references/output-templates.md) 的对应部分。
|
|
31
|
+
|
|
32
|
+
主题包含多个子领域时,安排独立分析者分别梳理核心问题、易忽略内容、前置知识和子领域关联。主协调者合并同义问题,核对缺口和依据,形成知识图谱。不要把初次列出的目录当作完整领域地图。
|
|
33
|
+
|
|
34
|
+
按当前读者目标标记问题优先级:
|
|
35
|
+
|
|
36
|
+
- **P0:必要问题。** 缺失会导致核心结论不成立、无法理解主线或无法完成目标操作。
|
|
37
|
+
- **P1:重要问题。** 影响读者作出适用性判断、理解权衡或识别主要限制。
|
|
38
|
+
- **P2:扩展问题。** 不阻断当前目标,可留作选读或后续探索。
|
|
39
|
+
|
|
40
|
+
停止梳理的条件:P0、P1 问题已有依据或明确缺口,均有章节归属或排除理由;关键争议已处理或披露;继续检索主要增加不影响当前目标的扩展内容。前置依赖追溯到读者已知基础或够用解释为止,不扩展成整门学科。分析者熟悉某个领域,不构成将其升级为必要内容的理由。
|
|
41
|
+
|
|
42
|
+
完成条件:范围明确;必要问题及其依赖已记录;关键依据与证据缺口可追踪。证据不足但影响关键结论的问题,应继续查证、缩小范围或明确列为未解决项。
|
|
43
|
+
|
|
44
|
+
## 2. 设计系列结构
|
|
45
|
+
|
|
46
|
+
将 P0、P1 问题映射到章节。每章记录核心问题、前置知识、应覆盖内容、读后能力、主要依据及与其他章节的关系。未纳入的问题说明原因,不能静默遗漏。
|
|
47
|
+
|
|
48
|
+
按理解依赖和阅读用途排序,不强套“基础到前沿”的固定层次。每章围绕独立问题组织内容;独立价值不等于无需前置知识。指定共享概念的主讲章节,其他章节只保留理解当前问题所需的回顾,并链接完整解释。
|
|
49
|
+
|
|
50
|
+
并行前稳定共享的解释基础:核心解释框架、共享场景与示例、版本和基本假设、已有依据的结论及未决争议。说明关键概念由哪章建立,以及后续章节可以假定读者知道什么。强依赖章节先等基础章节初稿或足够明确的解释约定,不只靠术语相同判断含义一致。
|
|
51
|
+
|
|
52
|
+
将跨章术语、来源、章节职责和链接约定提供给所有撰写者。文件名使用可排序的 `XX-标题.md`;正文标题不必重复文件序号。默认使用标准 Markdown 相对链接;用户的阅读工具需要 wikilink 时再使用,并核对目标。
|
|
53
|
+
|
|
54
|
+
完成条件:必要问题都有明确归属;章节边界与依赖清楚;结构设计写入工作目录。章节数量不足以形成有意义的系列时,说明适合合并的原因,而不是为了凑数拆章。
|
|
55
|
+
|
|
56
|
+
同时确定主阅读路线和用途:连续学习、建立理解或掌握操作的系列,整合后安排主路线试读;只作跳读参考或用户明确跳过时,记录不安排的原因。
|
|
57
|
+
|
|
58
|
+
## 3. 分工撰写与自检
|
|
59
|
+
|
|
60
|
+
主协调者按章节安排分工明确的撰写者,提供任务说明、系列结构、共享约定、该章资料和输出路径。有必要依赖其他章节的实际内容时,等待对应初稿;其余章节可并行。
|
|
61
|
+
|
|
62
|
+
撰写者开始前读取 [写作与自检](references/self-check-list.md)。资料规则同样适用于撰写阶段;新增事实必须记录依据。按章节目标写作,不用代码、图表数量或文字长度代替深度。
|
|
63
|
+
|
|
64
|
+
初稿完成后按适用项自检并修改。必要检查完成且没有新的实质发现时结束;缺少依据、能力或资源而无法解决的问题随稿提交,不反复改写措辞来冒充进展。主协调者批量核对本批输出:文件存在、非空、属于本次任务,正文覆盖章节职责,且未混入其他章节或评审内容。文件存在不等于内容合格。
|
|
65
|
+
|
|
66
|
+
## 4. 独立评审与修订
|
|
67
|
+
|
|
68
|
+
### 评审输入与独立性
|
|
69
|
+
|
|
70
|
+
每章安排独立评审者,使用不包含该章写作或修改过程的新上下文。评审前读取 [评审标准](references/scoring-rubric.md) 与 [输出模板](references/output-templates.md) 中的评审格式。
|
|
71
|
+
|
|
72
|
+
首轮评审不提供作者自评分、作者辩护或其他评审结论。提供判断必需的材料:目标读者、任务范围、系列结构、章节职责、共享术语、当前章节、来源记录,以及涉及衔接或重复问题的相邻或相关章节。盲审隔离既有判断,不隔离必要证据。
|
|
73
|
+
|
|
74
|
+
要求评审者依据可核对内容报告问题;不要求凑问题或给出赞扬。不能核实的内容标为待核实,不作已证实错误处理。报告记录实际读取的版本和检查范围。
|
|
75
|
+
|
|
76
|
+
### 通过与修订
|
|
77
|
+
|
|
78
|
+
按评审标准区分高、中、低影响问题。没有未解决的高、中影响问题,且必要检查完成,才可标记“通过”。检查或证据不足时标记“待核实”;未完成独立评审时标记“未评审”。总分仅辅助比较,不能抵消实质问题。
|
|
79
|
+
|
|
80
|
+
主协调者将原始报告按轮次保留,在任务状态清单登记实际输入、覆盖范围、结论和问题 ID。批量核对报告是否覆盖预期章节、是否对应当前版本、是否有具体问题依据。逐轮汇总仅在需要时从清单与报告生成,并注明生成时点,不作为第二份可编辑状态。
|
|
81
|
+
|
|
82
|
+
对需要修订的章节,安排非评审者的修改者。修改前保存输入快照,交代问题、涉及文件、当前版本与完成条件;同一文件只能有一个修改者。修改后记录实际输出和问题处理结果,再由独立评审者复核。复评可以提供旧问题与处理记录,不能称为首轮盲审。
|
|
83
|
+
|
|
84
|
+
保留文件实际作者、历史修改者和输出版本;更换负责人不清空历史。按环境可核实的执行实体判断独立性,不以角色名代替。评审记录实际输入及检查范围;输入改变后,先将相关结论标为待核实,由独立评审者确认沿用范围或复查,不自动继承通过。
|
|
85
|
+
|
|
86
|
+
默认每章进行两轮问题修订与复评,可按用户要求调整。只在实际产出针对评审问题的新版本后计一轮;派发、失败重试和同一提交续接不重复计数。初稿写作、正常跨章整合和其必要检查不占问题修订轮次,但不能借“整合”重置已经消耗的修复预算。读者试读发现的问题也按实际修复对象登记。具体计数见[状态协议](references/state-protocol.md)。
|
|
87
|
+
|
|
88
|
+
轮次是执行预算,不是质量标准。达到上限时,根据新证据、收敛程度和剩余资源,说明是否需要继续的理由;超出既定预算需用户调整,不能自动无限重审,也不能因为轮次用完就标为通过。
|
|
89
|
+
|
|
90
|
+
比较版本时检查问题是否解决、是否引入新问题、原有正确内容是否丢失。不能只因分数下降就回退,也不能以最高分作为保留版本的唯一依据。确认实质退化时,从快照恢复受影响内容并复核;保留有依据的有效修复。
|
|
91
|
+
|
|
92
|
+
达到轮次上限仍有问题时,保存依据最充分、实质问题最少的可用版本,记录遗留问题及影响。未完成章节若阻断后续理解或关键结论,暂停依赖它的部分;其余部分可以继续。
|
|
93
|
+
|
|
94
|
+
## 5. 跨章整合与索引
|
|
95
|
+
|
|
96
|
+
主协调者读取当前章节并对照结构设计;资料超出上下文容量时分批读取,保留章节职责与问题索引,避免强行一次装入全部内容。
|
|
97
|
+
|
|
98
|
+
- 核对共享术语、前置知识、引用和结论。按含义与领域惯例统一术语;不同含义不能机械合并。
|
|
99
|
+
- 按解释作用处理重复。完整解释集中在主讲章节,保留当前章节必要的简短回顾。仅在帮助读者定位信息时添加交叉链接,不对每次概念出现都插链接。
|
|
100
|
+
- 核对跨章示例、数据、版本假设和边界条件,避免各章单独成立但组合后冲突。
|
|
101
|
+
- 扫描 `TODO`、`FIXME`、`待补充`、`xxx`、`placeholder`、`TBD` 等候选标记。逐项判断是否为未完成内容、引用原文或有意展示的代码。只修复真实缺口,保留必要示例。
|
|
102
|
+
- 检查本地链接文件与锚点。外部链接的可访问性和内容真实性分别检查;未能访问的链接说明限制。
|
|
103
|
+
|
|
104
|
+
生成 `00-阅读指南.md`,说明系列目标、适用读者、阅读路线、章节链接、前置知识、选读分支及重要限制。来源可随章记录或集中放入 `来源与说明.md`,但必须能定位到支持的论点。
|
|
105
|
+
|
|
106
|
+
### 主阅读路线试读
|
|
107
|
+
|
|
108
|
+
需要试读时,在初步整合与阅读指南完成后,按环境提供的位置读取配套技能 `reader-review`,由其规定读者画像、独立派发、模拟判断、误读处理和复读方法。不要在本技能维护第二套试读规则。技能无法定位或读取时,说明缺失与对交付的影响,继续不依赖试读的工作,不声称已完成试读。
|
|
109
|
+
|
|
110
|
+
提供必要画像、目标、正文入口、主路线和实际范围,首轮不传作者辩护或旧判断。协调者将报告存入本次工作目录的 `读者试读/`;本生成任务的留档约定优先于单独试读时默认不留档的规则。
|
|
111
|
+
|
|
112
|
+
区分阅读障碍与技术疑点:前者按读者目标修订,后者交内容评审核实。采纳修改后按改动影响进行定向复查或重新试读。试读不代替事实评审,记录真实覆盖与未验证范围;阻断目标的障碍未解决时,按部分交付披露。
|
|
113
|
+
|
|
114
|
+
整合后复核所有受影响部分:路径和格式改动核对相应链接与格式;改变事实、结论、示例、章节职责或理解依赖的改动,由独立评审者复查相关内容。正常整合不占问题修订轮次;若本次修改用于解决已登记评审问题,仍按该章实际修订计数,不因换阶段重置。预算耗尽时报告遗留问题,不无限循环。报告注明对应最终版本,不能沿用已失效的通过状态。
|
|
115
|
+
|
|
116
|
+
## 6. 交付
|
|
117
|
+
|
|
118
|
+
交付前读取 [交付检查](references/delivery-checklist.md),逐项记录已完成、未完成或不适用及原因。
|
|
119
|
+
|
|
120
|
+
核对清单与实际文件后,运行 `python <本技能目录>/scripts/check-state.py --root <主题目录> --state <任务状态.json路径> --final`;中途恢复检查可不加 `--final`。脚本需要 Python 3.9 或更新版本,只读检查结构、版本、身份登记与修订记录一致性,不判断内容正确性;按输出修复失败项,必要检查未完成时披露影响。正文、来源、本地链接与锚点等仍按交付检查核对,不能用脚本通过替代。最终摘要从清单与原始报告生成,不另立账本。
|
|
121
|
+
|
|
122
|
+
交付阅读指南、最终章节、来源与必要限制。存在未解决问题时,同时交付 `交付状态.md`,说明受影响章节、阅读或使用影响、未完成检查和后续所需条件。聊天中给出入口链接和关键状态,完整正文与报告保存到文件。
|
|
123
|
+
|
|
124
|
+
默认保留工作目录中的知识图谱、结构、来源、评审和快照。只自动删除本次创建且明确可丢弃的临时文件;不清空已有目录,不删除评审证据。用户要求精简包时,打包阅读材料并说明工作记录的位置。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# 交付检查
|
|
2
|
+
|
|
3
|
+
主协调者交付前读取。记录每项已完成、未完成或不适用及原因。未完成必要检查时,说明对交付状态的影响,不机械勾选通过。
|
|
4
|
+
|
|
5
|
+
- 目标读者、范围、阅读用途和重要推定条件已记录。
|
|
6
|
+
- 知识图谱与结构设计可读取;P0、P1 问题有明确归属或排除理由。
|
|
7
|
+
- 关键事实与来源可追踪;推断、示例和证据缺口有明确标识。
|
|
8
|
+
- 当前章节文件存在、非空、版本正确,内容覆盖实际章节职责。
|
|
9
|
+
- 唯一当前状态清单与磁盘版本、原始报告一致;机械检查已运行并记录失败/未检查项,未用机械通过代替内容判断。没有多份需要人工同步的近义状态表。
|
|
10
|
+
- 撰写者已自检;未解决问题已交给主协调者。
|
|
11
|
+
- 独立评审报告对应当前交付版本,检查范围和状态明确;未独立评审时没有使用“通过独立评审”的说法。
|
|
12
|
+
- 修订有快照、问题处理记录和必要复评;达到预算上限的遗留问题已记录。
|
|
13
|
+
- 实际修订与问题处理记录可在中断后恢复;派发与失败未虚耗轮次。作者、历史修改者与评审者按实际实体区分,身份或历史未知未被当作通过。
|
|
14
|
+
- 跨章术语、假设、示例、数据和结论无未披露冲突;必要的理解回顾已保留。
|
|
15
|
+
- 阅读指南、章节链接和本地锚点已核对;外部链接未完成的检查已说明。
|
|
16
|
+
- 占位符候选已按语义判断;真实缺口已修复或列为遗留项。
|
|
17
|
+
- 整合修改涉及的内容已复核;实质修改未沿用失效的评审状态。
|
|
18
|
+
- 连续学习系列已按reader-review完成主路线试读并披露实际覆盖;跳过有原因。读者报告存于工作目录,首次输入未泄漏旧判断;采纳的修改已定向复查,实际问题修订按原预算计数,正常整合另作必要复查。模拟读者意见未声称真实用户验证。
|
|
19
|
+
- 最终阅读材料与工作记录分开;旧记录未被覆盖,知识图谱和评审证据默认保留。
|
|
20
|
+
- 存在遗留问题时已提供交付状态,聊天中已说明关键限制和入口路径。
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# 异常处理
|
|
2
|
+
|
|
3
|
+
主协调者首次执行前读取;出现异常时查阅对应规则。修复不得绕过授权、伪造检查结果或无限重试。
|
|
4
|
+
|
|
5
|
+
| 条件 | 恢复动作 | 停止或继续条件 |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Agent 长时间无新输出 | 检查工具状态、错误及可见进展;按环境的超时信息判断。确认为失败时,保留可用输出并重试一次,可缩小独立任务或减少并发 | 再次失败时记录未完成任务。继续不依赖它的工作,暂停被它阻断的部分;不以统一秒数判定失败 |
|
|
8
|
+
| 独立 Agent 不可用 | 完成资料与结构等可独立推进的工作,说明独立撰写或评审能力缺失 | 用户接受替代方式后再顺序写作与自检,报告中保留“未独立评审”状态 |
|
|
9
|
+
| 资料不可获取或来源冲突 | 使用可访问材料,查找相关原始来源;记录适用条件与证据差异 | 核心结论缺证时缩小论点或保留待核实状态,不补造依据 |
|
|
10
|
+
| 知识图谱为空或过于宽泛 | 回到读者目标与核心问题,检查题目范围、检索条件及分析输入,再做一次针对性分析 | 仍无可用依据时报告缺口;可记录临时结构,但不能宣称已完成知识梳理 |
|
|
11
|
+
| 文件缺失、为空或内容错位 | 核对路径、任务标识和输入版本;让对应执行者重写或补交一次 | 仍失败时标明缺口,暂停依赖该文件的任务;不把文件存在当作覆盖完整 |
|
|
12
|
+
| 写入失败 | 检查目标目录与权限,在已授权位置创建必要目录后重试一次 | 用户指定路径仍不可用时说明具体失败与原因,不静默更换位置;继续不依赖写入的准备工作 |
|
|
13
|
+
| 术语冲突 | 比较定义、领域惯例和来源,区分同义词与不同概念,再修改受影响内容 | 存在会改变结论的歧义且资料无法解决时,保留争议并询问所需信息,不按频率替换 |
|
|
14
|
+
| 评审意见冲突 | 对照位置、依据、章节目标和适用条件,由主协调者记录采纳或不采纳理由 | 缺少决定性证据时标待核实,不用投票或平均分代替判断 |
|
|
15
|
+
| 修订引入退化 | 比较修改前快照、问题处理记录与新稿,定位丢失或错误内容 | 恢复受影响内容并复核有效修复;不单纯按分数回退 |
|
|
16
|
+
| 问题修订达到既定预算 | 保存可用版本与全部记录,说明仍存问题、影响和依赖 | 预算是执行限制,不是通过标准;继续需调整预算,不重置预算无限重审;交付不受影响的内容,明确部分完成状态 |
|
|
17
|
+
| 主题不足以支持多个有价值章节 | 按核心问题合并或缩小结构,解释原因 | 不为凑章数拆分内容;实际范围与用户明确要求冲突时询问 |
|
|
18
|
+
| 上下文不足以容纳全部章节 | 分批读取正文,维护章节职责、版本与问题索引,需要时重读相关段落 | 不根据截断内容声称完成全系列检查 |
|
|
19
|
+
| 清单损坏或更新中断 | 保留损坏副本,读取上一有效清单,对照实际文件、Agent状态、报告、快照和修订处理记录重建;按状态协议运行机械检查 | 无法核实的版本、身份和预算标未知或待核实,不凭旧完成标记接受输出,不重复派单 |
|
|
20
|
+
| 评审输入变化 | 按覆盖目标把受影响条目标为pending;由原独立评审者确认沿用或复查,保留旧报告为历史依据 | 当前版本未获确认前不沿用通过;单纯哈希变化不等于内容错误 |
|
|
21
|
+
| 历史修订不明 | 对照实际输出、问题处理记录和任务历史恢复已完成修订;派发与失败不计轮次,同提交续接不重复计数 | 无法核实则标未知,不凭空补全历史;暂停需要依赖剩余预算的新修订,报告限制 |
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# 输出模板与记录字段
|
|
2
|
+
|
|
3
|
+
需要创建相应记录时读取对应部分。以下规定必要信息,不强制所有文档采用同一标题或表格;可以合并字段,但不能遗漏判断与追踪所需内容。模板示例不是真实结论。
|
|
4
|
+
|
|
5
|
+
## 目录约定
|
|
6
|
+
|
|
7
|
+
```text
|
|
8
|
+
主题目录/
|
|
9
|
+
├── 00-阅读指南.md
|
|
10
|
+
├── XX-标题.md
|
|
11
|
+
├── 来源与说明.md # 来源也可随章记录,此时不必单独建文件
|
|
12
|
+
├── 交付状态.md # 存在未解决问题或未完成检查时生成
|
|
13
|
+
└── _work/本次任务标识/
|
|
14
|
+
├── 任务说明.md
|
|
15
|
+
├── 知识图谱.md
|
|
16
|
+
├── 结构设计.md
|
|
17
|
+
├── 资料记录.md
|
|
18
|
+
├── 任务状态.json # 唯一可编辑的当前状态索引,仅协调者维护
|
|
19
|
+
├── 版本/ # 每次修改前的快照,含被修改章节与必要的关联文件
|
|
20
|
+
└── 评审/轮次标识/
|
|
21
|
+
├── 00-汇总.md # 可选:从清单与报告生成的只读历史摘要
|
|
22
|
+
└── XX-章节评审.md
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
文件夹仅在实际需要时创建。用户另有目录约定时使用用户约定,并保持追踪关系。轮次目录不可覆盖已有记录;部分章节复评时汇总注明哪些报告仍有效,哪些已被新报告替代。
|
|
26
|
+
|
|
27
|
+
## 任务状态清单
|
|
28
|
+
|
|
29
|
+
首次登记、派发评审或恢复任务时,读取[状态协议](state-protocol.md)。字段、版本、快照与恢复规则集中在该文件,不在模板中重复维护。当前协议为版本2;版本1记录须依据真实文件和历史报告迁移,不能只改版本号。
|
|
30
|
+
|
|
31
|
+
## 任务说明与知识图谱
|
|
32
|
+
|
|
33
|
+
任务说明记录主题边界、读者基础、阅读目标、时效要求、推定条件、输出位置及任务标识。
|
|
34
|
+
|
|
35
|
+
知识图谱可使用以下字段:
|
|
36
|
+
|
|
37
|
+
| 子领域或维度 | 核心问题 | 读者易忽略的信息 | P0/P1/P2 | 前置依赖与关联 | 依据及缺口 |
|
|
38
|
+
|---|---|---|---|---|---|
|
|
39
|
+
|
|
40
|
+
覆盖哪些维度由主题决定,不强制工程实践或前沿方向。
|
|
41
|
+
|
|
42
|
+
## 结构设计
|
|
43
|
+
|
|
44
|
+
| 文件 | 核心问题 | 必要覆盖 | 前置知识 | 读后能力 | 主要依据 | 与其他章节的关系 |
|
|
45
|
+
|---|---|---|---|---|---|---|
|
|
46
|
+
|
|
47
|
+
另外记录问题到章节的映射、排除项与理由、术语约定、概念主讲位置和链接格式。
|
|
48
|
+
|
|
49
|
+
## 章节评审
|
|
50
|
+
|
|
51
|
+
报告必须包含以下信息:
|
|
52
|
+
|
|
53
|
+
- 目标文件、版本标识(快照、内容哈希或等效可核对标识)、评审日期、首评或复评。
|
|
54
|
+
- 实际读取的材料、检查范围、未完成检查。
|
|
55
|
+
- 状态:通过、待修订、待核实或未评审,并说明理由。
|
|
56
|
+
- 问题清单:编号、位置、影响级别、描述、依据、读者影响、建议及复核条件。没有已确认问题时如实写明。
|
|
57
|
+
- 按评审维度说明问题依据;只有用户需要版本比较或长期量化时才附辅助得分。
|
|
58
|
+
- 复评时的问题处理结果及新增问题。
|
|
59
|
+
|
|
60
|
+
## 评审汇总
|
|
61
|
+
|
|
62
|
+
当前版本、评审引用与已用预算只维护在任务状态清单;高、中、低问题数量按原报告未决问题计算,剩余预算由已用轮次计算,不重复维护计数。需要汇总时从清单与报告生成只读摘要,注明时点及适用版本。辅助分数可列出,不使用系列平均分代替章节状态。归并跨章共性问题并说明适用章节,不以出现次数决定问题是否重要。
|
|
63
|
+
|
|
64
|
+
## 阅读指南与交付状态
|
|
65
|
+
|
|
66
|
+
阅读指南提供系列目标、适用读者、前置知识、章节链接、推荐顺序、选读分支、来源入口与重要限制。
|
|
67
|
+
|
|
68
|
+
存在遗留问题时,交付状态记录章节、问题、影响、已完成工作、未完成检查及继续所需条件。说明哪些部分可使用、哪些结论仍受限制;不要把部分完成标为完整通过。
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# 资料与证据规则
|
|
2
|
+
|
|
3
|
+
建立知识图谱前读取;撰写者新增事实或评审者核实争议时查阅相关部分。
|
|
4
|
+
|
|
5
|
+
## 根据问题选择资料
|
|
6
|
+
|
|
7
|
+
优先使用与论点直接相关的原始资料:官方规范、版本文档、原始研究、公开数据和一手记录。综述或解释性文章可帮助定位问题,但不能用其权威名称代替检查原始结论。资料类型按主题选择,不要求所有主题都有代码、实验或学术论文。
|
|
8
|
+
|
|
9
|
+
对版本行为、数字、引语、历史事件、时效结论和有争议的观点,记录支持资料与适用范围。论证关键处给出可追踪引用;常识性连接说明不必逐句添加来源。
|
|
10
|
+
|
|
11
|
+
## 资料记录
|
|
12
|
+
|
|
13
|
+
每项关键资料记录标题、作者或机构、日期或版本、链接或可用定位、支持的论点,以及适用限制。对时效性网页记录访问日期。区分资料实际已读、仅见摘要和未能获取全文,不能把搜索摘要冒充阅读全文。
|
|
14
|
+
|
|
15
|
+
来源有冲突时,比较对象、时间、条件和方法。可以保留不同解释及其证据,不强行归为统一结论。多篇文章转述同一来源不等于多份独立证据。
|
|
16
|
+
|
|
17
|
+
## 内容身份
|
|
18
|
+
|
|
19
|
+
- **已核实事实**:能与已检查的来源或可观察记录对应,说明适用条件。
|
|
20
|
+
- **解释或推断**:写出依据和必要假设,不冒充原始资料的明确结论。
|
|
21
|
+
- **示例**:说明是教学构造、简化模型还是实际案例。虚构数据与假设输入要标明。
|
|
22
|
+
- **待核实内容**:记录缺失证据及其影响;不补造文献、链接、数据或引语。
|
|
23
|
+
|
|
24
|
+
代码区分实际执行过与仅作解释的示例。说明关键环境与前提;未执行时不声称已验证。用户未授权运行或环境不支持时,进行可行的静态检查并说明边界。
|
|
25
|
+
|
|
26
|
+
## 无法检索或证据不足
|
|
27
|
+
|
|
28
|
+
外部检索不可用时,使用用户材料及可访问资料,标记未核实的时效信息。核心结论依赖缺失证据时,继续获取资料、缩小论点或将问题保留为未解决项。不能用增加篇幅掩盖缺证。
|
|
29
|
+
|
|
30
|
+
知识图谱的完整性限于任务范围、读者目标和已检查资料。记录可能遗漏的领域边界,不宣称穷尽整个学科。
|
|
31
|
+
|
|
32
|
+
## 结束本轮检索
|
|
33
|
+
|
|
34
|
+
必要问题已有支持依据或明确缺口,关键争议已解决或限制结论,继续检索只增加不影响阅读目标的扩展内容时,结束本轮。若新的资料会改变核心结论,仍需核对;若资料不可获取,缩小论点并披露限制,不用扩大领域范围代替补证。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# 独立评审标准
|
|
2
|
+
|
|
3
|
+
评审章节或复查实质改动前读取。评审根据章节目标与可核对证据判断,不以写作长度、图表数量或固定文风评分。
|
|
4
|
+
|
|
5
|
+
## 问题与通过状态
|
|
6
|
+
|
|
7
|
+
| 影响 | 判定依据 | 处理 |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| 高 | 核心结论错误;关键依据失实;会造成严重误解或错误操作;必要问题缺失使目标无法完成 | 修复后复核,未解决不能通过 |
|
|
10
|
+
| 中 | 必要解释、主要限制或证据不足;示例与结论不一致;前置依赖或章节冲突影响理解 | 修复或以证据证明不成立,未解决不能通过 |
|
|
11
|
+
| 低 | 不影响主要理解与使用的措辞、局部格式或可选补充 | 可继续交付,记录有价值的改进 |
|
|
12
|
+
|
|
13
|
+
每个问题包含:编号、章节与可定位位置、问题描述、依据、对读者的影响、建议和复核条件。没有依据的偏好不得升级为实质缺陷。未取得所需资料时写“待核实”,说明影响,不能凭怀疑判定错误,也不能当作已核实通过。
|
|
14
|
+
|
|
15
|
+
状态定义:
|
|
16
|
+
|
|
17
|
+
- **通过**:必要检查已完成,无未解决的高、中影响问题。
|
|
18
|
+
- **待修订**:存在已确认的高、中影响问题。
|
|
19
|
+
- **待核实**:缺少完成必要判断的资料或检查,无法确定是否满足要求。
|
|
20
|
+
- **未评审**:未完成独立评审。
|
|
21
|
+
|
|
22
|
+
分数与状态分开记录。高分不能抵消问题;没有发现问题只代表本次版本在已检查范围内未发现问题。
|
|
23
|
+
|
|
24
|
+
## 辅助评分
|
|
25
|
+
|
|
26
|
+
默认只按下列维度检查并报告具体问题,不要求数字、权重或总分。只有用户需要比较候选版本或长期跟踪质量时,才采用下列可调整的评分方式。启用时,各维度使用 1–10 分,并给出实际依据。无法判断的维度标为“未评估”,不虚构分数或完整总分。
|
|
27
|
+
|
|
28
|
+
| 维度 | 权重 | 检查重点 |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| 事实与证据 | 25% | 关键事实、来源、推断、示例身份及适用条件是否可靠 |
|
|
31
|
+
| 内容覆盖 | 20% | 是否回答章节职责内的必要问题,是否遗漏影响目标的限制 |
|
|
32
|
+
| 解释深度 | 20% | 因果、推理或机制是否足够支撑结论,而非堆砌术语 |
|
|
33
|
+
| 目标适配 | 15% | 是否符合读者基础与阅读用途,能否支持预期理解、判断或操作 |
|
|
34
|
+
| 结构与可读性 | 10% | 信息顺序、表达和表现形式是否帮助理解 |
|
|
35
|
+
| 系列连贯性 | 10% | 前置依赖、术语、跨章结论和阅读路径是否一致 |
|
|
36
|
+
|
|
37
|
+
全部维度可评估时,总分为各维度分数乘权重后的总和。辅助锚点:9–10 表示该维度要求充分满足且有证据支持;7–8 表示基本满足但有具体不足;5–6 表示重要部分不足;3–4 表示明显缺失或冲突;1–2 表示基本未满足。评分不等于出版认证。
|
|
38
|
+
|
|
39
|
+
## 复评
|
|
40
|
+
|
|
41
|
+
逐项说明原问题已解决、部分解决、未解决或经证据撤销,并检查修改引入的新问题。核对受影响的其他章节和引用。分数变化仅为线索;回退须指出具体退化,不能依据评分波动自动执行。
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# 写作与自检
|
|
2
|
+
|
|
3
|
+
撰写者开始写作前读取。初稿完成后检查下列适用项并直接修改;必要检查完成且没有新的实质发现时结束;缺证或资源不足的遗留问题随稿提交。自检不代替独立评审。
|
|
4
|
+
|
|
5
|
+
## 内容与解释
|
|
6
|
+
|
|
7
|
+
- 对照章节职责,确认核心问题已回答,读者目标所需的依据、机制、边界和例子已覆盖。
|
|
8
|
+
- 根据内容选择解释方法:机制展示因果过程;操作解释前提、步骤、结果和失败条件;比较说明维度与权衡;理论展示推理;历史主题区分记录与解释。不强套统一段落结构。
|
|
9
|
+
- 对影响判断或操作的事实,按 [资料与证据规则](research-protocol.md) 核对来源。说明推断、简化与未知。
|
|
10
|
+
- 深度取决于解释是否足以支持理解、判断或行动,不取决于篇幅、术语量或代码数量。
|
|
11
|
+
|
|
12
|
+
## 中文表达
|
|
13
|
+
|
|
14
|
+
- 同一概念使用一致术语;首次出现且目标读者不熟悉时解释。缩写需要时展开,保留有意义的领域区分。
|
|
15
|
+
- 明确动作、对象和适用条件。拆开存在歧义或同时承担多项要求的句子,不机械限制自然叙述的句长。
|
|
16
|
+
- 删除不推进理解的套话和重复,保留必要推导、对照、例外与限制。
|
|
17
|
+
- 结论适合先给时先给结论;需要铺垫才能理解时按推理顺序展开。主动语态和第二人称用于帮助理解,不设为统一句式。
|
|
18
|
+
- 文件名序号用于排序,正文标题不重复序号。标题表达实际问题或内容,层级反映逻辑关系。
|
|
19
|
+
|
|
20
|
+
## 示例与表现形式
|
|
21
|
+
|
|
22
|
+
- 代码只在帮助理解或操作时使用。邻近文字或注释解释用途、关键逻辑、适用环境和限制,不要求代码块前后重复解释。
|
|
23
|
+
- 示例输入、输出和结论相互一致;区分真实结果与预期结果,注明未执行的代码。
|
|
24
|
+
- 表格用于比较,图用于解释关系,列表用于并列或步骤。没有解释价值时用自然段,不设可视化密度。
|
|
25
|
+
- 使用 Mermaid 时检查代码围栏、图类型语法、节点标识和标签写法。按目标渲染器处理特殊字符与换行;不把某种图的规则推广到所有图。连线应表达真实关系,不强制所有节点从父节点引出。
|
|
26
|
+
- 无法渲染时检查源码并说明未验证渲染;复杂表达可改为更简单的图或文字。
|
|
27
|
+
|
|
28
|
+
## 章节关系
|
|
29
|
+
|
|
30
|
+
- 说明真正需要的前置知识。仅回顾理解本章所需的信息,链接完整解释,不要求固定句数。
|
|
31
|
+
- 结尾回答本章核心问题,说明必要限制。确有自然延伸时引出后续问题;末章收束系列,不制造悬念。
|
|
32
|
+
- 对照共享约定与已可用的相关章节,检查术语、数据、示例和依赖。无法读取的章节列为整合阶段待核对项。
|
|
33
|
+
- 检查未完成标记与交叉链接。原文或教学代码中的标记不等于未完成内容。
|
|
34
|
+
|
|
35
|
+
## 提交
|
|
36
|
+
|
|
37
|
+
提交章节路径、已覆盖内容、自检修改摘要、来源记录和未解决问题。不要只给自评分或声称“已完善”。
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# 状态协议
|
|
2
|
+
|
|
3
|
+
首次登记、派发评审或恢复任务前读取。协调者维护唯一当前清单,正文、报告和历史快照保存事实依据。当前格式为版本2,不兼容直接套用版本1。
|
|
4
|
+
|
|
5
|
+
## 日常记录
|
|
6
|
+
|
|
7
|
+
最小示例仅说明字段,不是真实执行记录:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"schema_version": 2,
|
|
12
|
+
"run_id": "example-run",
|
|
13
|
+
"next_action": "收取章节初稿",
|
|
14
|
+
"revision_limit": 2,
|
|
15
|
+
"actors": {"writer": {"identity": "实际执行实体身份"}},
|
|
16
|
+
"files": {
|
|
17
|
+
"ch01": {
|
|
18
|
+
"path": "01-标题.md", "kind": "chapter", "sha256": null,
|
|
19
|
+
"owner": "writer", "contributors": [], "revisions": []
|
|
20
|
+
}
|
|
21
|
+
},
|
|
22
|
+
"reviews": [],
|
|
23
|
+
"reading": {"status": "计划中", "reason": "连续学习", "review_ids": []}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
- 路径相对主题根目录,使用 `/`,解析后不得越界。文件 ID 保持稳定;改名只更新路径。
|
|
28
|
+
- `kind` 为 `chapter`、`guide`、`source` 或 `shared`。SHA256 对磁盘实际字节计算;未产出文件为 `null`。哈希只标识版本,不证明内容正确。
|
|
29
|
+
- `owner` 必须存在,未分配可为 `null`。`actors` 保存环境可核实的实体身份;未知为 `null`,不以角色名证明独立性。
|
|
30
|
+
- `contributors` 保留全部实际作者和修改者,每项为 `{"actor":"writer","sha256":"实际输出哈希"}`,必须包含当前产出版本。负责人变更不清空历史。协调者修改正文也要登记。
|
|
31
|
+
- `revisions` 只记录实际完成的问题修订,每项为 `{"id":"fix-01","output_sha256":"实际输出哈希","record":"_work/run/处理/fix-01.md"}`。处理记录说明问题 ID、修改前后版本和处理结果。相同提交续接更新原项,不重复登记;正常整合不计问题修订,但其修改者与输出仍登记在 contributors。
|
|
32
|
+
- `revision_limit` 默认2,可按用户指示调整。剩余轮次从实际修订条目计算,不人工另存计数;历史不明时 `revisions` 为 `null`,不能假定还有预算。
|
|
33
|
+
|
|
34
|
+
未产生修改时不计轮次。问题只经证据撤销、没有正文修改时,在评审报告解释,不新增修订项。预算耗尽不影响报告真实问题,也不允许自动通过。
|
|
35
|
+
|
|
36
|
+
## 评审记录
|
|
37
|
+
|
|
38
|
+
每项包含 `id`、`kind`(`content` 或 `reader`)、`actor`、`report`、`coverage`:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"id": "review-01", "kind": "content", "actor": "reviewer",
|
|
43
|
+
"report": {"path": "_work/run/评审/01.md", "sha256": "实际报告哈希"},
|
|
44
|
+
"coverage": [{
|
|
45
|
+
"target": "ch01", "status": "通过", "scope": "本章及共享约定",
|
|
46
|
+
"inputs": [{"file_id": "ch01", "sha256": "实际输入哈希"}],
|
|
47
|
+
"issues": [], "applicability": "current"
|
|
48
|
+
}]
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
内容状态为通过、待修订、待核实、未评审;读者状态为已完成、部分覆盖、未完成。`issues` 记录未解决的高、中问题以及影响必要判断的核实项 ID,低影响建议留在报告;通过记录的 `issues` 必须为空。
|
|
53
|
+
|
|
54
|
+
`scope` 写实际检查范围。输入必须包含目标与影响判断的共享或相邻材料;不能只因目标哈希未变就忽略依赖变化。`applicability` 为 current、pending 或 historical:输入改变后先标 pending,独立评审者确认沿用或复查后新建当前记录,旧记录留为历史。
|
|
55
|
+
|
|
56
|
+
评审前保存目标及必要输入的可恢复版本,可用不可变副本、Git 提交或等效版本存储;报告记录具体定位。需要文件快照时,可在 inputs 条目加 `snapshot` 相对路径,脚本核对其哈希。并发、异步交付、恢复或审计需要精确冻结输入时必须登记 snapshot;不要求每次判断重复复制已有相同版本。
|
|
57
|
+
|
|
58
|
+
当前评审者不能是目标的实际作者或修改者。首评用新上下文,不提供旧判断;身份登记只能检查实体是否重合,不能证明上下文已隔离或评审真实独立。
|
|
59
|
+
|
|
60
|
+
## 试读与交付
|
|
61
|
+
|
|
62
|
+
`reading.status` 为计划中、已完成、部分覆盖、未完成或跳过;reason 说明路线及覆盖限制或跳过原因,review_ids 引用当前适用的读者报告。全部完成须由对应范围的已完成报告支持,部分覆盖不能声称全读。
|
|
63
|
+
|
|
64
|
+
交付前运行只读脚本,要求 Python 3.9 或更新版本:
|
|
65
|
+
|
|
66
|
+
```text
|
|
67
|
+
python <本技能目录>/scripts/check-state.py --root <主题目录> --state <清单路径> --final
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
退出码0表示已实现的机械检查无失败或未检查项;1表示失败;2表示存在未检查项。非 final 模式用于恢复和中途核对。报告、引用内容、范围完整性、上下文隔离、来源真实性和链接锚点仍需实际检查。
|
|
71
|
+
|
|
72
|
+
## 并发、恢复与迁移
|
|
73
|
+
|
|
74
|
+
协调者派发修改前,记录涉及文件、输入版本、执行实体和占用情况,可放在现有任务说明中;同一文件只允许一个修改者。恢复后先查任务是否仍运行,不重复派发。不要求在总清单与处理文件中提前登记同一修订轮次。
|
|
75
|
+
|
|
76
|
+
清单更新采用同目录临时文件,成功解析后替换,保留上一有效版本。损坏时对照实际正文、运行任务、报告和版本记录恢复;无法确认的身份或历史标未知,不能凭空补全。需要严格审计时补充实际输入快照与版本定位,不为普通任务增加多份人工账本。
|
|
77
|
+
|
|
78
|
+
迁移版本1时保留原清单,按实际输出重建 contributors 与 revisions,取消纯派发或失败所占轮次,保留实际修订。重建评审输入及有效性,核对后再使用版本2;不能只修改 schema_version。历史无法核实则保留未知和交付限制。
|
|
@@ -0,0 +1,253 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Read-only state-v2 checks. Requires Python 3.9+. See state-protocol.md."""
|
|
3
|
+
import argparse
|
|
4
|
+
import hashlib
|
|
5
|
+
import json
|
|
6
|
+
import re
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class Check:
|
|
11
|
+
def __init__(self, root, final=False):
|
|
12
|
+
self.root = root.resolve()
|
|
13
|
+
self.final = final
|
|
14
|
+
self.result = {"passed": [], "failed": [], "unchecked": []}
|
|
15
|
+
|
|
16
|
+
def add(self, level, at, message):
|
|
17
|
+
self.result[level].append({"at": at, "message": message})
|
|
18
|
+
|
|
19
|
+
def require(self, condition, at, message):
|
|
20
|
+
if not condition:
|
|
21
|
+
self.add("failed", at, message)
|
|
22
|
+
return condition
|
|
23
|
+
|
|
24
|
+
def obj(self, value, at):
|
|
25
|
+
return value if self.require(isinstance(value, dict), at, "必须为对象") else {}
|
|
26
|
+
|
|
27
|
+
def seq(self, value, at):
|
|
28
|
+
return value if self.require(isinstance(value, list), at, "必须为数组") else []
|
|
29
|
+
|
|
30
|
+
def text(self, value, at):
|
|
31
|
+
return self.require(isinstance(value, str) and bool(value.strip()), at, "必须为非空字符串")
|
|
32
|
+
|
|
33
|
+
def sha(self, value, at):
|
|
34
|
+
return self.require(isinstance(value, str) and bool(re.fullmatch(r"[0-9a-f]{64}", value)), at, "必须为64位小写SHA256")
|
|
35
|
+
|
|
36
|
+
def path(self, value, at):
|
|
37
|
+
if not self.text(value, at):
|
|
38
|
+
return None
|
|
39
|
+
if not self.require("\\" not in value and not re.match(r"^[A-Za-z]:", value) and not Path(value).is_absolute(), at, "必须使用主题根目录下的相对/路径"):
|
|
40
|
+
return None
|
|
41
|
+
path = (self.root / value).resolve()
|
|
42
|
+
return path if self.require(path.is_relative_to(self.root), at, "路径越出主题目录") else None
|
|
43
|
+
|
|
44
|
+
def blob(self, data, at):
|
|
45
|
+
data = self.obj(data, at)
|
|
46
|
+
path = self.path(data.get("path"), at + ".path")
|
|
47
|
+
valid = self.sha(data.get("sha256"), at + ".sha256")
|
|
48
|
+
if path is None or not self.require(path.is_file(), at, "文件不存在"):
|
|
49
|
+
return
|
|
50
|
+
raw = path.read_bytes()
|
|
51
|
+
self.require(bool(raw.strip()), at, "文件为空")
|
|
52
|
+
if valid:
|
|
53
|
+
self.require(hashlib.sha256(raw).hexdigest() == data["sha256"], at, "实际文件哈希与登记不符")
|
|
54
|
+
|
|
55
|
+
def actor(self, actor, at):
|
|
56
|
+
if not self.require(isinstance(actor, str) and actor in self.actors, at, "执行实体未登记"):
|
|
57
|
+
return None
|
|
58
|
+
self.require("identity" in self.actors[actor], at, "缺少identity字段")
|
|
59
|
+
identity = self.actors[actor].get("identity")
|
|
60
|
+
if identity is None:
|
|
61
|
+
self.add("unchecked", at, "实体身份未知")
|
|
62
|
+
return None
|
|
63
|
+
return identity if self.text(identity, at + ".identity") else None
|
|
64
|
+
|
|
65
|
+
def run(self, state):
|
|
66
|
+
state = self.obj(state, "state")
|
|
67
|
+
self.require(type(state.get("schema_version")) is int and state["schema_version"] == 2, "schema_version", "需要版本2;旧版须依据历史迁移")
|
|
68
|
+
for key in ("run_id", "next_action"):
|
|
69
|
+
self.text(state.get(key), key)
|
|
70
|
+
limit = state.get("revision_limit")
|
|
71
|
+
valid_limit = self.require(type(limit) is int and limit >= 0, "revision_limit", "必须为非负整数")
|
|
72
|
+
self.actors = self.obj(state.get("actors"), "actors")
|
|
73
|
+
self.actors = {k: self.obj(v, "actors." + k) for k, v in self.actors.items()}
|
|
74
|
+
files = self.obj(state.get("files"), "files")
|
|
75
|
+
files = {k: self.obj(v, "files." + k) for k, v in files.items()}
|
|
76
|
+
self.require(bool(files), "files", "没有登记文件")
|
|
77
|
+
people, paths = {}, set()
|
|
78
|
+
for fid, item in files.items():
|
|
79
|
+
at = "files." + fid
|
|
80
|
+
self.require(item.get("kind") in ("chapter", "guide", "source", "shared"), at, "无效文件类型")
|
|
81
|
+
path = self.path(item.get("path"), at + ".path")
|
|
82
|
+
if path is not None:
|
|
83
|
+
self.require(path not in paths, at, "不同ID指向同一文件")
|
|
84
|
+
paths.add(path)
|
|
85
|
+
self.require("sha256" in item, at, "缺少sha256字段")
|
|
86
|
+
current = item.get("sha256")
|
|
87
|
+
if current is None:
|
|
88
|
+
self.add("unchecked", at, "尚未产出或登记版本")
|
|
89
|
+
else:
|
|
90
|
+
self.blob(item, at)
|
|
91
|
+
self.require("owner" in item, at, "缺少owner字段")
|
|
92
|
+
if item.get("owner") is not None:
|
|
93
|
+
self.actor(item["owner"], at + ".owner")
|
|
94
|
+
elif self.final:
|
|
95
|
+
self.add("unchecked", at, "未分配负责人")
|
|
96
|
+
identities, outputs = set(), set()
|
|
97
|
+
for n, entry in enumerate(self.seq(item.get("contributors"), at + ".contributors")):
|
|
98
|
+
loc = f"{at}.contributors[{n}]"
|
|
99
|
+
entry = self.obj(entry, loc)
|
|
100
|
+
identity = self.actor(entry.get("actor"), loc)
|
|
101
|
+
identities.add(identity)
|
|
102
|
+
if self.sha(entry.get("sha256"), loc):
|
|
103
|
+
outputs.add(entry["sha256"])
|
|
104
|
+
if current is not None:
|
|
105
|
+
self.require(current in outputs, at, "当前版本缺少作者或修改者登记")
|
|
106
|
+
people[fid] = identities
|
|
107
|
+
if item.get("kind") != "chapter":
|
|
108
|
+
continue
|
|
109
|
+
if item.get("revisions") is None:
|
|
110
|
+
self.add("unchecked", at, "修订历史缺失或未知")
|
|
111
|
+
continue
|
|
112
|
+
revisions = self.seq(item["revisions"], at + ".revisions")
|
|
113
|
+
seen = set()
|
|
114
|
+
for n, revision in enumerate(revisions):
|
|
115
|
+
loc = f"{at}.revisions[{n}]"
|
|
116
|
+
revision = self.obj(revision, loc)
|
|
117
|
+
rid = revision.get("id")
|
|
118
|
+
if self.text(rid, loc):
|
|
119
|
+
self.require(rid not in seen, loc, "同一提交重复计数")
|
|
120
|
+
seen.add(rid)
|
|
121
|
+
output = revision.get("output_sha256")
|
|
122
|
+
if self.sha(output, loc):
|
|
123
|
+
self.require(output in outputs, loc, "修订输出未登记贡献版本")
|
|
124
|
+
record = self.path(revision.get("record"), loc + ".record")
|
|
125
|
+
if record is not None:
|
|
126
|
+
self.require(record.is_file() and bool(record.read_bytes().strip()), loc, "处理记录缺失或为空")
|
|
127
|
+
if valid_limit:
|
|
128
|
+
self.require(len(revisions) <= limit, at, "实际修订超过当前预算,需核对授权与登记")
|
|
129
|
+
|
|
130
|
+
review_ids, readers, passes = set(), {}, set()
|
|
131
|
+
for n, review in enumerate(self.seq(state.get("reviews"), "reviews")):
|
|
132
|
+
at = f"reviews[{n}]"
|
|
133
|
+
review = self.obj(review, at)
|
|
134
|
+
rid = review.get("id")
|
|
135
|
+
valid_id = self.text(rid, at + ".id")
|
|
136
|
+
if valid_id:
|
|
137
|
+
self.require(rid not in review_ids, at, "重复评审ID")
|
|
138
|
+
review_ids.add(rid)
|
|
139
|
+
kind = review.get("kind")
|
|
140
|
+
self.require(kind in ("content", "reader"), at, "无效评审类型")
|
|
141
|
+
identity = self.actor(review.get("actor"), at)
|
|
142
|
+
self.blob(review.get("report"), at + ".report")
|
|
143
|
+
coverage = self.seq(review.get("coverage"), at + ".coverage")
|
|
144
|
+
self.require(bool(coverage), at, "评审无覆盖目标")
|
|
145
|
+
targets, reader_entries = set(), []
|
|
146
|
+
for j, entry in enumerate(coverage):
|
|
147
|
+
loc = f"{at}.coverage[{j}]"
|
|
148
|
+
entry = self.obj(entry, loc)
|
|
149
|
+
target = entry.get("target")
|
|
150
|
+
if not self.require(isinstance(target, str) and target in files, loc, "目标未登记"):
|
|
151
|
+
continue
|
|
152
|
+
self.require(target not in targets, loc, "重复覆盖目标")
|
|
153
|
+
targets.add(target)
|
|
154
|
+
self.text(entry.get("scope"), loc + ".scope")
|
|
155
|
+
app, status = entry.get("applicability"), entry.get("status")
|
|
156
|
+
self.require(app in ("current", "pending", "historical"), loc, "无效适用状态")
|
|
157
|
+
allowed = ("通过", "待修订", "待核实", "未评审") if kind == "content" else ("已完成", "部分覆盖", "未完成")
|
|
158
|
+
self.require(status in allowed, loc, "无效结论状态")
|
|
159
|
+
issues = self.seq(entry.get("issues"), loc + ".issues")
|
|
160
|
+
for issue in issues:
|
|
161
|
+
self.text(issue, loc + ".issues")
|
|
162
|
+
if status == "通过":
|
|
163
|
+
self.require(not issues, loc, "通过与未决必要问题冲突")
|
|
164
|
+
inputs, matches = set(), True
|
|
165
|
+
for k, value in enumerate(self.seq(entry.get("inputs"), loc + ".inputs")):
|
|
166
|
+
point = f"{loc}.inputs[{k}]"
|
|
167
|
+
value = self.obj(value, point)
|
|
168
|
+
fid = value.get("file_id")
|
|
169
|
+
if not self.require(isinstance(fid, str) and fid in files, point, "输入未登记"):
|
|
170
|
+
matches = False
|
|
171
|
+
continue
|
|
172
|
+
self.require(fid not in inputs, point, "重复输入")
|
|
173
|
+
inputs.add(fid)
|
|
174
|
+
self.sha(value.get("sha256"), point)
|
|
175
|
+
matches = matches and value.get("sha256") == files[fid].get("sha256")
|
|
176
|
+
if "snapshot" in value:
|
|
177
|
+
self.blob({"path": value["snapshot"], "sha256": value.get("sha256")}, point + ".snapshot")
|
|
178
|
+
snapshot_path = self.path(value["snapshot"], point + ".snapshot.path")
|
|
179
|
+
current_path = self.path(files[fid].get("path"), point + ".current.path")
|
|
180
|
+
self.require(snapshot_path is None or snapshot_path != current_path, point, "快照不能是当前正文")
|
|
181
|
+
self.require(target in inputs, loc, "输入未包含目标")
|
|
182
|
+
matches = matches and target in inputs
|
|
183
|
+
if app == "current":
|
|
184
|
+
self.require(matches, loc, "评审输入已变化,需确认适用性")
|
|
185
|
+
if identity is None or not people[target] or None in people[target]:
|
|
186
|
+
self.add("unchecked", loc, "无法核实实体是否重合")
|
|
187
|
+
else:
|
|
188
|
+
self.require(identity not in people[target], loc, "评审者也是目标作者或修改者")
|
|
189
|
+
if kind == "content":
|
|
190
|
+
if status == "通过" and not issues and matches:
|
|
191
|
+
passes.add(target)
|
|
192
|
+
else:
|
|
193
|
+
self.add("unchecked", loc, "当前内容尚无通过结论")
|
|
194
|
+
elif app == "pending":
|
|
195
|
+
self.add("unchecked", loc, "评审适用性待确认")
|
|
196
|
+
reader_entries.append((app, status, matches))
|
|
197
|
+
if kind == "reader" and valid_id:
|
|
198
|
+
readers[rid] = reader_entries
|
|
199
|
+
reading = self.obj(state.get("reading"), "reading")
|
|
200
|
+
status = reading.get("status")
|
|
201
|
+
self.require(status in ("计划中", "已完成", "部分覆盖", "未完成", "跳过"), "reading", "无效试读状态")
|
|
202
|
+
self.text(reading.get("reason"), "reading.reason")
|
|
203
|
+
links = self.seq(reading.get("review_ids"), "reading.review_ids")
|
|
204
|
+
for rid in links:
|
|
205
|
+
valid = isinstance(rid, str) and rid in readers
|
|
206
|
+
self.require(valid, "reading", "读者报告引用无效")
|
|
207
|
+
if valid and status in ("已完成", "部分覆盖"):
|
|
208
|
+
entries = readers[rid]
|
|
209
|
+
self.require(bool(entries) and all(a == "current" and m and st in ("已完成", "部分覆盖") for a, st, m in entries), "reading", "报告未完成或不适用当前版本")
|
|
210
|
+
if status == "已完成":
|
|
211
|
+
self.require(all(st == "已完成" for _, st, _ in entries), "reading", "部分覆盖不能证明完成")
|
|
212
|
+
if status in ("已完成", "部分覆盖"):
|
|
213
|
+
self.require(bool(links), "reading", "缺少支持试读结论的报告")
|
|
214
|
+
if self.final:
|
|
215
|
+
for fid, item in files.items():
|
|
216
|
+
if item.get("kind") != "shared" and fid not in passes:
|
|
217
|
+
self.add("unchecked", "files." + fid, "缺少当前内容通过记录")
|
|
218
|
+
if status not in ("已完成", "跳过"):
|
|
219
|
+
self.add("unchecked", "reading", "试读未完成或仅部分覆盖")
|
|
220
|
+
if not self.result["failed"]:
|
|
221
|
+
self.add("passed", "scope", "已实现的机械约束未发现冲突;未检查项另列")
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
def unique_keys(pairs):
|
|
225
|
+
result = {}
|
|
226
|
+
for key, value in pairs:
|
|
227
|
+
if key in result:
|
|
228
|
+
raise ValueError("重复JSON键: " + key)
|
|
229
|
+
result[key] = value
|
|
230
|
+
return result
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def main():
|
|
234
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
235
|
+
parser.add_argument("--root", type=Path, required=True)
|
|
236
|
+
parser.add_argument("--state", type=Path, required=True)
|
|
237
|
+
parser.add_argument("--final", action="store_true")
|
|
238
|
+
args = parser.parse_args()
|
|
239
|
+
check = Check(args.root, args.final)
|
|
240
|
+
try:
|
|
241
|
+
if not args.root.is_dir() or not args.state.resolve().is_relative_to(args.root.resolve()):
|
|
242
|
+
raise ValueError("主题目录不存在或清单越出目录")
|
|
243
|
+
state = json.loads(args.state.read_text(encoding="utf-8-sig"), object_pairs_hook=unique_keys)
|
|
244
|
+
check.run(state)
|
|
245
|
+
except (OSError, ValueError, TypeError, RecursionError) as exc:
|
|
246
|
+
check.add("failed", "state", str(exc))
|
|
247
|
+
check.result["limits"] = "只检查机械一致性;不证明来源、范围完整性、上下文隔离、实际体验或链接锚点正确。"
|
|
248
|
+
print(json.dumps(check.result, ensure_ascii=False, indent=2))
|
|
249
|
+
return 1 if check.result["failed"] else 2 if check.result["unchecked"] else 0
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
if __name__ == "__main__":
|
|
253
|
+
raise SystemExit(main())
|