@namewta/speculo 0.2.2 → 0.2.3
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/package.json
CHANGED
|
@@ -10,6 +10,8 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
|
|
|
10
10
|
|
|
11
11
|
⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
|
|
12
12
|
|
|
13
|
+
🔒 **目标仓库已写死：`NAMEWTA/Speculo`。** 本命令专为 Speculo 框架自身反馈而设计。不论 retro 在哪个项目仓库中被激活，issue 一律提交到 `NAMEWTA/Speculo`。不允许用户或 AI 覆盖此目标仓库。
|
|
14
|
+
|
|
13
15
|
## 归档路径模式
|
|
14
16
|
|
|
15
17
|
报告文件：`speculo/.speculo/commands/retro/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`
|
|
@@ -28,10 +30,10 @@ keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
|
|
|
28
30
|
1. 读取 `../skills/runtime-context/SKILL.md` 与 `../skills/speculo-retro/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），采集对话、command 报告、change 状态以及各 `PERSISTENCE.md` 声明的 lessons/knowledge store。
|
|
29
31
|
2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
|
|
30
32
|
3. 创建 command 专属目录 `speculo/.speculo/commands/retro/`，把复盘结论写入带 scope 的 Markdown 报告。
|
|
31
|
-
4.
|
|
32
|
-
5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo
|
|
33
|
-
6. **外部写操作边界**：向用户展示将要创建的 issue
|
|
34
|
-
7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo
|
|
33
|
+
4. **目标仓库（写死，不可覆盖）**：本命令的 issue 目标仓库固定为 `NAMEWTA/Speculo`。无论 retro 在哪个项目仓库中被激活，`gh issue create` 的 `--repo` 参数一律使用 `NAMEWTA/Speculo`。用户和 AI 均不得指定其他仓库。
|
|
34
|
+
5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo NAMEWTA/Speculo --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
|
|
35
|
+
6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标仓库 `NAMEWTA/Speculo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
|
|
36
|
+
7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo NAMEWTA/Speculo --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
|
|
35
37
|
8. 把每条提案的最终 issue 编号/URL 回写进本次报告的「提交结果」小节；返回报告路径、3-5 条复盘摘要和已创建 issue 链接清单。
|
|
36
38
|
|
|
37
39
|
## 产物模板
|
|
@@ -64,10 +66,10 @@ generated_at: [TODO: ISO-8601]
|
|
|
64
66
|
[TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
|
|
65
67
|
|
|
66
68
|
## 目标仓库
|
|
67
|
-
|
|
69
|
+
`NAMEWTA/Speculo`（写死，不可覆盖）
|
|
68
70
|
|
|
69
71
|
## 用户确认记录
|
|
70
|
-
[TODO: 记录用户对 issue
|
|
72
|
+
[TODO: 记录用户对 issue 清单的确认原文摘要。]
|
|
71
73
|
|
|
72
74
|
## 提交结果
|
|
73
75
|
[TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]
|
|
@@ -16,7 +16,7 @@ description: 基于可复现 Git 区间、用户确认范围和 workflow 规则
|
|
|
16
16
|
1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
|
|
17
17
|
2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
|
|
18
18
|
3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
|
|
19
|
-
4. 更新 README 时读取 `references/readme-contract.md
|
|
19
|
+
4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`。需要创建或重建多层代理手册树时改用 `../agents-md-builder/SKILL.md`。
|
|
20
20
|
5. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
|
|
21
21
|
|
|
22
22
|
完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# README 写作指南
|
|
2
|
+
|
|
3
|
+
README 面向首次接触项目的读者，需要在约 5 秒内回答三个问题：**这是什么、怎么用、值不值得用**。本指南定义 Speculo 项目的通用 README 结构与写作规范，供 `docs-sync` 及其他命令在生成或审计 README 时引用。
|
|
4
|
+
|
|
5
|
+
> **同步规则参见 [readme-contract.md](./readme-contract.md)。** 本指南定义"写什么内容"（内容规范）；readme-contract.md 定义"何时同步、如何验证"（同步契约）。两者互补。
|
|
6
|
+
|
|
7
|
+
## 九段式结构
|
|
8
|
+
|
|
9
|
+
项目简单时合并相邻章节，README 很长时把 API、架构解释和贡献流程移到对应文档。以下九段覆盖从"吸引注意"到"引导参与"的完整认知漏斗。
|
|
10
|
+
|
|
11
|
+
| # | 段落 | 用途 | 缺失后果 |
|
|
12
|
+
|---|------|------|----------|
|
|
13
|
+
| 1 | **Header** | 项目名 + 一句话定位 + 徽章栏 + 语言切换 | 读者不知道项目是否活跃、能否跨语言阅读 |
|
|
14
|
+
| 2 | **About** | 价值主张 + 内容概览 + 独特卖点 | 读者无法快速判断项目是否解决他的问题 |
|
|
15
|
+
| 3 | **Quick Start** | 前置条件 → 安装命令 → 预期输出 | 读者放弃尝试 |
|
|
16
|
+
| 4 | **Project Structure** | ASCII 目录树 + 命名规范 | 读者不知道从哪里入手改代码 |
|
|
17
|
+
| 5 | **How to Study / Use** | 分步学习或使用方法 | 读者不知道怎么消化内容 |
|
|
18
|
+
| 6 | **Tech Stack** | 组件-包名-用途三列表 | 读者不知道需要什么依赖 |
|
|
19
|
+
| 7 | **Contributing** | Fork → Branch → Convention → Test → PR | 潜在贡献者不知道流程而放弃 |
|
|
20
|
+
| 8 | **License** | 类型 + LICENSE 文件链接 | 读者不确定能否合法使用 |
|
|
21
|
+
| 9 | **Footer** | 社区链接 + 跨语言导航 | 读者不知道怎么联系或获取更多信息 |
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
### 1. Header
|
|
26
|
+
|
|
27
|
+
**应包含：**
|
|
28
|
+
- 项目名居中（`<h1 align="center">Project Name</h1>`）
|
|
29
|
+
- 一句话 tagline —— 说明输入、输出或解决什么问题，删除空泛营销语
|
|
30
|
+
- 徽章栏：License、语言版本、包管理器、Stars、PRs、CI 状态等
|
|
31
|
+
- 语言切换链接：`[中文](./README-ZH.md)` ← → `[English](./README.md)`
|
|
32
|
+
|
|
33
|
+
**不应包含：**
|
|
34
|
+
- 超过一行的冗长描述（放到 About 段）
|
|
35
|
+
- 失效或状态无价值的徽章
|
|
36
|
+
|
|
37
|
+
**示例：**
|
|
38
|
+
|
|
39
|
+
```markdown
|
|
40
|
+
<h1 align="center">My Project</h1>
|
|
41
|
+
<p align="center"><em>A one-line description of what it does.</em></p>
|
|
42
|
+
<p align="center">
|
|
43
|
+
<a href="./README-ZH.md">中文</a>
|
|
44
|
+
</p>
|
|
45
|
+
<p align="center">
|
|
46
|
+
<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">
|
|
47
|
+
<img src="https://img.shields.io/badge/Python-3.10+-green.svg" alt="Python 3.10+">
|
|
48
|
+
<img src="https://img.shields.io/github/stars/owner/repo?style=flat" alt="Stars">
|
|
49
|
+
</p>
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
### 2. About
|
|
55
|
+
|
|
56
|
+
**应包含：**
|
|
57
|
+
- 一段清晰的价值主张：这个项目解决什么痛点、为谁解决
|
|
58
|
+
- 内容/功能概览表（若为学习型仓库：模块列表；若为工具型：核心功能）
|
|
59
|
+
- 1-3 个独特卖点（why this project over alternatives）
|
|
60
|
+
|
|
61
|
+
**不应包含：**
|
|
62
|
+
- 实现细节（放到项目结构或文档链接）
|
|
63
|
+
- 安装步骤（放到 Quick Start）
|
|
64
|
+
- 与其他项目逐行对比（冗长且容易过时）
|
|
65
|
+
|
|
66
|
+
**示例（学习型仓库）：**
|
|
67
|
+
|
|
68
|
+
```markdown
|
|
69
|
+
## About
|
|
70
|
+
|
|
71
|
+
My Project 是一套从零到生产就绪的 XYZ 学习路线，每个模块以"带注释的可运行脚本"而非教程形式呈现 — 代码即教材。
|
|
72
|
+
|
|
73
|
+
| # | 模块 | 覆盖内容 |
|
|
74
|
+
|---|------|----------|
|
|
75
|
+
| 01 | Getting Started | 环境搭建、Hello World |
|
|
76
|
+
| 02 | Core Concepts | 核心抽象与生命周期 |
|
|
77
|
+
| ... | ... | ... |
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
### 3. Quick Start
|
|
83
|
+
|
|
84
|
+
**应包含：**
|
|
85
|
+
- **前置条件**：运行时版本、系统依赖、必需的 API key 等
|
|
86
|
+
- **一步安装命令**：`npx`、`git clone`、`pip install` 等，可复制粘贴
|
|
87
|
+
- **预期输出**：读者执行后应该看到什么才算成功
|
|
88
|
+
- 预计耗时在 60 秒以内
|
|
89
|
+
|
|
90
|
+
**不应包含：**
|
|
91
|
+
- 长篇背景解释
|
|
92
|
+
- 多分支安装路径（初学者只需一条"最快路径"）
|
|
93
|
+
|
|
94
|
+
**示例：**
|
|
95
|
+
|
|
96
|
+
```markdown
|
|
97
|
+
## Quick Start
|
|
98
|
+
|
|
99
|
+
**前置条件：** Node.js >= 22、npm >= 10
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npx my-package init
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
预期输出：
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
✔ Project initialized at ./my-project
|
|
109
|
+
✔ 3 files created
|
|
110
|
+
```
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
### 4. Project Structure
|
|
116
|
+
|
|
117
|
+
**应包含：**
|
|
118
|
+
- ASCII 目录树（第一层级，不超过 2 层深度）
|
|
119
|
+
- 关键命名规范说明（文件前缀、目录约定等）
|
|
120
|
+
- 每个顶级目录的一句话用途
|
|
121
|
+
|
|
122
|
+
**不应包含：**
|
|
123
|
+
- 完整展开的文件树（冗长且随 commit 快速过时）
|
|
124
|
+
- 每个文件的详细说明（放到各自模块的文档中）
|
|
125
|
+
|
|
126
|
+
**示例：**
|
|
127
|
+
|
|
128
|
+
```markdown
|
|
129
|
+
## Project Structure
|
|
130
|
+
|
|
131
|
+
```
|
|
132
|
+
.
|
|
133
|
+
├── src/ # 源代码
|
|
134
|
+
├── tests/ # 测试（文件名 = test_<module>.py）
|
|
135
|
+
├── docs/ # 详细文档
|
|
136
|
+
├── scripts/ # 运维/CI 辅助脚本
|
|
137
|
+
├── pyproject.toml # 项目元数据与依赖
|
|
138
|
+
└── README.md
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
命名规范：源文件使用 `snake_case.py`，测试文件使用 `test_` 前缀。
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
### 5. How to Study / Use
|
|
147
|
+
|
|
148
|
+
此节因项目类型而异：
|
|
149
|
+
|
|
150
|
+
**学习型仓库：** 四步学习法
|
|
151
|
+
```markdown
|
|
152
|
+
## How to Study
|
|
153
|
+
|
|
154
|
+
1. **选择模块** — 按编号顺序，每模块构建在前一模块之上
|
|
155
|
+
2. **阅读注释** — 每个脚本包含详尽的中文注释，解释每行代码的"为什么"
|
|
156
|
+
3. **运行脚本** — `python main-<NN>-<topic>.py`，观察输出
|
|
157
|
+
4. **动手实验** — 修改参数、打破代码、修复它
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**工具/库型仓库：**
|
|
161
|
+
```markdown
|
|
162
|
+
## Usage
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from mylib import Thing
|
|
166
|
+
t = Thing(config)
|
|
167
|
+
result = t.do("input")
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
详见 [docs/](./docs/)。
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
### 6. Tech Stack
|
|
176
|
+
|
|
177
|
+
**格式：** 组件-包名-用途三列表，按层或类别分组。
|
|
178
|
+
|
|
179
|
+
**应包含：**
|
|
180
|
+
- 核心运行时与框架
|
|
181
|
+
- 关键依赖（用户需要知道的，不是全部 `node_modules`）
|
|
182
|
+
|
|
183
|
+
**示例：**
|
|
184
|
+
|
|
185
|
+
```markdown
|
|
186
|
+
## Tech Stack
|
|
187
|
+
|
|
188
|
+
| 组件 | 包名 | 用途 |
|
|
189
|
+
|------|------|------|
|
|
190
|
+
| Runtime | Python 3.10+ | 主运行环境 |
|
|
191
|
+
| Package Manager | uv | 依赖管理与虚拟环境 |
|
|
192
|
+
| LLM Framework | langchain | 大语言模型编排 |
|
|
193
|
+
| Vector Store | chromadb | 嵌入式向量存储与检索 |
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
### 7. Contributing
|
|
199
|
+
|
|
200
|
+
**应包含：**
|
|
201
|
+
- Fork → Branch → Convention → Test → PR 简洁流程
|
|
202
|
+
- Commit 规范（如 Conventional Commits）
|
|
203
|
+
- 在哪提 issue、讨论设计
|
|
204
|
+
|
|
205
|
+
**不应包含：**
|
|
206
|
+
- 完整的 CLA 法律文本（链接到 CONTRIBUTING.md）
|
|
207
|
+
|
|
208
|
+
**示例：**
|
|
209
|
+
|
|
210
|
+
```markdown
|
|
211
|
+
## Contributing
|
|
212
|
+
|
|
213
|
+
1. Fork 本仓库
|
|
214
|
+
2. 从 `main` 分支创建功能分支：`git checkout -b feat/my-feature`
|
|
215
|
+
3. 提交遵循 [Conventional Commits](https://www.conventionalcommits.org/)
|
|
216
|
+
4. 确保现有测试通过并添加新测试
|
|
217
|
+
5. 提交 PR 并描述改动原因
|
|
218
|
+
|
|
219
|
+
欢迎提 issue 讨论新功能或报告 bug。
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
### 8. License
|
|
225
|
+
|
|
226
|
+
**格式：** 一句话 + LICENSE 文件链接。
|
|
227
|
+
|
|
228
|
+
```markdown
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
MIT © [Author] — 详见 [LICENSE](./LICENSE) 文件。
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
### 9. Footer
|
|
237
|
+
|
|
238
|
+
**应包含：**
|
|
239
|
+
- 社区/联系链接（GitHub Discussions、Discord、Twitter 等）
|
|
240
|
+
- 跨语言 README 跳转链接（与 Header 的徽章栏中的语言切换呼应）
|
|
241
|
+
|
|
242
|
+
```markdown
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
<p align="center">
|
|
246
|
+
<a href="./README-ZH.md">中文文档</a>
|
|
247
|
+
·
|
|
248
|
+
<a href="https://github.com/owner/repo/discussions">Discussions</a>
|
|
249
|
+
·
|
|
250
|
+
<a href="https://github.com/owner/repo/issues">Report Bug</a>
|
|
251
|
+
</p>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
## 双语言原则
|
|
257
|
+
|
|
258
|
+
遵循 [readme-contract.md](./readme-contract.md) 中的铁律：
|
|
259
|
+
|
|
260
|
+
- **`README.md` 始终为英文（EN）。** 与之配对的是 `README-ZH.md`，为一对一的中文翻译镜像。
|
|
261
|
+
- 两文件顶部互相提供可点击跳转链接。
|
|
262
|
+
- 结构完全对称，内容一一对应。标题顺序、命令、代码块、URL、表格字段保持对等；代码实体不翻译。
|
|
263
|
+
- `README.md` 内容变更时，`README-ZH.md` 必须在同一次同步中完成对应更新。
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## 与其他资产的关系
|
|
268
|
+
|
|
269
|
+
| 资产 | 路径 | 关系 |
|
|
270
|
+
|------|------|------|
|
|
271
|
+
| readme-contract.md | `./readme-contract.md` | 同步规则与验证契约 —— 定义**何时更新**、触发条件、多语言铁律 |
|
|
272
|
+
| document-lifecycle-contract.md | `./document-lifecycle-contract.md` | 文档生命周期 —— 定义**如何决定** add/update/delete/merge |
|
|
273
|
+
| docs-sync SKILL.md | `../SKILL.md` | 编排 skill —— 调用本指南与 readme-contract.md 协同完成 README 审计 |
|
|
274
|
+
| 项目文档创建与维护规范 | `temp/项目文档创建与维护规范.md` | 背景参考 —— 综合 50+ 来源的文档规范研究（非运行时依赖） |
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## 验证清单
|
|
279
|
+
|
|
280
|
+
生成或审计 README 时逐项检查：
|
|
281
|
+
|
|
282
|
+
- [ ] Header 有项目名、tagline、徽章栏（至少 License + 语言版本）、语言切换链接
|
|
283
|
+
- [ ] About 在 3 秒内回答"这个项目是做什么的"
|
|
284
|
+
- [ ] Quick Start 可在 60 秒内完成并看到预期输出
|
|
285
|
+
- [ ] 安装命令可复制粘贴执行
|
|
286
|
+
- [ ] Project Structure 树与实际目录布局一致
|
|
287
|
+
- [ ] Tech Stack 表与 `package.json` / `pyproject.toml` 等 manifest 文件中的核心依赖一致
|
|
288
|
+
- [ ] Contributing 有可执行步骤
|
|
289
|
+
- [ ] License 类型与实际 LICENSE 文件一致
|
|
290
|
+
- [ ] Footer 有语言切换和社区链接
|
|
291
|
+
- [ ] 无过期命令、路径、参数、徽章、链接
|
|
292
|
+
- [ ] `README-ZH.md` 与 `README.md` 同步更新
|
|
293
|
+
|
|
294
|
+
逐段删除测试：删掉后不影响采用决策或正确使用的内容应压缩、下沉或删除。
|