pi-tsgw 0.0.16 → 0.0.18
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 +44 -12
- package/extensions/index.ts +2 -0
- package/extensions/mcp.ts +18 -6
- package/extensions/memory.ts +32 -0
- package/extensions/upload/local-file.ts +1 -1
- package/extensions/upload/protocol.ts +4 -4
- package/package.json +2 -2
- package/skills/{delegate-model-selection → tsgw-delegate-model-selection}/SKILL.md +1 -1
- package/skills/tsgw-git-commit/SKILL.md +65 -0
- package/skills/tsgw-git-commit/scripts/discover-repos.mjs +58 -0
- package/skills/tsgw-github/SKILL.md +85 -0
- package/skills/tsgw-mk-docs/SKILL.md +72 -0
- package/skills/tsgw-mk-docs/SOURCE.md +47 -0
- package/skills/tsgw-mk-docs/assets/000-todo.template.md +21 -0
- package/skills/tsgw-mk-docs/references/000-terminology.md +58 -0
- package/skills/tsgw-mk-docs/references/000-todo.md +106 -0
- package/skills/tsgw-mk-docs/references/a-series/checklist.md +20 -0
- package/skills/tsgw-mk-docs/references/a-series/modules.md +33 -0
- package/skills/tsgw-mk-docs/references/a-series/overview.md +24 -0
- package/skills/tsgw-mk-docs/references/b-series/checklist.md +20 -0
- package/skills/tsgw-mk-docs/references/b-series/modules.md +36 -0
- package/skills/tsgw-mk-docs/references/b-series/overview.md +24 -0
- package/skills/tsgw-mk-docs/references/c-series/checklist.md +20 -0
- package/skills/tsgw-mk-docs/references/c-series/modules.md +33 -0
- package/skills/tsgw-mk-docs/references/c-series/overview.md +23 -0
- package/skills/tsgw-mk-docs/references/design-doc-boundaries.md +146 -0
- package/skills/tsgw-programmer-go/SKILL.md +64 -0
- package/skills/tsgw-programmer-go/references/UPDATE_GUIDE.md +26 -0
- package/skills/tsgw-programmer-go/references/code_review_comments.md +50 -0
- package/skills/tsgw-programmer-go/references/effective_go.md +49 -0
- package/skills/tsgw-smemo/SKILL.md +179 -0
- package/skills/tsgw-smemo/references/blinko-guide.md +111 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# 000.名词解释.md 编写与使用说明
|
|
2
|
+
|
|
3
|
+
## 职责
|
|
4
|
+
|
|
5
|
+
- 维护术语、别名、历史名称、禁止词和命名冻结规则。
|
|
6
|
+
- 为 `000.TODO.md`、`A00.需求分析.md`、`B00.规划设计.md`、`C00.执行计划/详细设计.md` 提供统一命名基线。
|
|
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
|
+
- 架构方案、模块拆分、协议设计、数据流。
|
|
35
|
+
- 实现计划、迁移步骤、测试命令、发布安排。
|
|
36
|
+
- 当前任务状态、阻塞、风险、完成度。
|
|
37
|
+
|
|
38
|
+
## 与其他文档的关系
|
|
39
|
+
|
|
40
|
+
- 本文件是术语基线,其他主文档引用其命名结论,不重复承载完整术语治理正文。
|
|
41
|
+
- `A00.需求分析.md` 使用这里定义的术语描述问题、目标和需求。
|
|
42
|
+
- `B00.规划设计.md`、`C00.执行计划/详细设计.md` 使用这里冻结的命名描述模块、接口和实现落点。
|
|
43
|
+
- `000.TODO.md` 只记录状态和证据指针,不负责定义术语;遇到术语冲突时应回退到本文件补齐。
|
|
44
|
+
|
|
45
|
+
## 更新触发条件
|
|
46
|
+
|
|
47
|
+
- 新增关键概念或现有概念边界变化。
|
|
48
|
+
- 旧名称需要废弃、替换或加入禁止词。
|
|
49
|
+
- 评审或实施过程中发现跨文档叫法不一致。
|
|
50
|
+
- 需求、架构或详细设计引入新的命名冻结要求。
|
|
51
|
+
|
|
52
|
+
## 复核要点
|
|
53
|
+
|
|
54
|
+
- 同一概念是否只有一个主叫法。
|
|
55
|
+
- 别名、历史名称和禁止词是否齐全且不互相矛盾。
|
|
56
|
+
- A/B/C/TODO 是否存在未同步的旧叫法。
|
|
57
|
+
- 行文是否采用规范书面语,是否存在口语、黑话、含混缩略或无必要中英混杂。
|
|
58
|
+
- 文档是否夹带需求正文、架构方案、实现计划或任务状态。
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# 000.TODO.md 编写与使用说明
|
|
2
|
+
|
|
3
|
+
## 职责
|
|
4
|
+
|
|
5
|
+
- 记录当前状态、任务树、阻塞、验收状态和证据指针。
|
|
6
|
+
- 作为项目或专题级文档治理入口,维护设计依据、实现、验证、发布和回填的闭环状态。
|
|
7
|
+
- 反映真实进展与未闭合项,而不是替代设计正文。
|
|
8
|
+
- 不是实时任务看板,也不替代 issue、项目管理系统、会话待办、执行日志或测试报告。
|
|
9
|
+
|
|
10
|
+
## 适用场景
|
|
11
|
+
|
|
12
|
+
- 创建或重建设计文档骨架时,需要建立统一状态账本。
|
|
13
|
+
- 迁移旧文档或旧流程后,需要汇总未迁完项、残留入口和证据缺口。
|
|
14
|
+
- 一轮实施、验证或发布完成后,需要批量回写状态与证据。
|
|
15
|
+
- 复核是否仍有遗漏、伪完成、阻塞或外部依赖未闭合。
|
|
16
|
+
|
|
17
|
+
## 推荐结构
|
|
18
|
+
|
|
19
|
+
- 优先使用 [000.TODO.md 模板](../assets/000-todo.template.md) 作为起始模板。
|
|
20
|
+
- 默认结构只有 `## 树形 TODO`。
|
|
21
|
+
- `## 树形 TODO`:父节点聚合;普通执行叶子默认只写 `前置依赖 / 验收证据`,只有当前阻塞影响推进或验收时才补 `阻塞`;若项目确实需要筛选或统计,可额外加可选标签,如 `类型`。
|
|
22
|
+
- 完整性复核、遗漏回填、更新触发等维护说明保留在 reference,不进入默认模板主体章节。
|
|
23
|
+
|
|
24
|
+
## 可选视图
|
|
25
|
+
|
|
26
|
+
- `## 说明`:仅当项目需要在文档内声明本项目编号口径、维护规则或边界说明时添加,保持极简。
|
|
27
|
+
- `## 简短总览`:仅当 TODO 树过长、读者需要快速定位当前阶段时添加,不能替代任务树。
|
|
28
|
+
- `## 关键路径`:仅当跨工作包依赖链很长时添加;优先使用节点 `前置依赖` 字段,关键路径视图不得成为第二套任务图。
|
|
29
|
+
|
|
30
|
+
## 必填内容
|
|
31
|
+
|
|
32
|
+
- 当前状态、任务树、阻塞、验收状态、证据指针。
|
|
33
|
+
- 每个工作包的设计依据指针和验收证据入口。
|
|
34
|
+
- 真实进度口径,至少覆盖未开始、进行中、阻塞、待验证、已完成。
|
|
35
|
+
- TODO 条目的增删改一定涉及文档变更,必须能追溯到文档依据或证据变化。
|
|
36
|
+
- `checkbox` 通常在一轮实施完成后结合证据批量标记,不应边执行子任务边同步打勾。
|
|
37
|
+
- 若一次性执行未完成,应先回写结果、失败原因或偏离点,再调整对应设计文档和 TODO 条目。
|
|
38
|
+
- 若执行中发现 TODO 本身不可执行,应先记录偏离、阻塞证据或失败原因,再调整对应 A/B/C 文档,最后调整 TODO 条目。
|
|
39
|
+
- 生成的项目 `000.TODO.md` 默认不受一般文档的 300-500 行建议限制,但项目明确行数规则优先;本技能包内所有文件仍须不超过 500 行。
|
|
40
|
+
- TODO 只记录状态与证据指针;风险分析正文应放回对应主文档,而不是作为普通执行叶子的固定字段。
|
|
41
|
+
|
|
42
|
+
## 编号规范
|
|
43
|
+
|
|
44
|
+
- 编号表达任务树归属,不表达文档编号;总目标不编号,只在标题或说明区描述。
|
|
45
|
+
- 编号由固定七级形态组成,层级不靠推断,直接按格式判定:
|
|
46
|
+
1. 第 1 级:`A-1`
|
|
47
|
+
2. 第 2 级:`A-01`
|
|
48
|
+
3. 第 3 级:`AB-01`
|
|
49
|
+
4. 第 4 级:`ABC-01`
|
|
50
|
+
5. 第 5 级:`ABC-001`
|
|
51
|
+
6. 第 6 级:`ABC-0001`
|
|
52
|
+
7. 第 7 级:`ABC-00001`
|
|
53
|
+
- `ABC-00001` 是第 7 级,也是最后一层实际任务;实际任务必须使用第 7 级格式,不使用其他格式作为实际任务,也不允许再向下挂子项。
|
|
54
|
+
- 第 1-6 级都是组织层,可按项目复杂度裁剪;新项目推荐从第 3 级 `AB-01` 开始建立,避免后续项目扩张时没有高层编号可用。
|
|
55
|
+
- 若后续需要更高层聚合,可以向上补第 1 级 `A-1` 或第 2 级 `A-01`,但不改动既有下层编号归属。
|
|
56
|
+
- 子项必须沿固定层级向下走,且子项编码号必须继承父项编码号。
|
|
57
|
+
- 合法:`AB-01 -> ABC-01 -> ABC-00001`。
|
|
58
|
+
- 合法:`ABC-01 -> ABC-001 -> ABC-0001 -> ABC-00001`。
|
|
59
|
+
- 合法:裁剪中间组织层后直接使用 `AB-01 -> ABC-00001`。
|
|
60
|
+
- 非法:`ABC-001 -> ABC-01`,因为子项不能回到更高层格式。
|
|
61
|
+
- 非法:`AB-01 -> XYC-00001`,因为子项前缀没有继承父项编码号。
|
|
62
|
+
- 可以裁剪中间组织层,但不能反向回到更高层格式,也不能混用不继承父项编码号的前缀。
|
|
63
|
+
- 实际任务的三字母前缀应尽量取所属模块、能力域或工作包的首字母,并在项目内保持唯一。
|
|
64
|
+
- 每个工作包或任务组的首个实际任务 `ABC-00001` 固定为 A/B/C 文档依据验收任务,必须指向 `A00`、`B00`、`C00` 系列中的某个文档或其子文档,用于确认后续任务的文档依据已经存在且足以支撑推进;未通过前,不推进该工作包或任务组的后续实现、测试、部署或联调子项。
|
|
65
|
+
- `ABC-00001` 的 `证据:` 必须填写 A/B/C 文档路径、章节、评审记录或设计依据指针;如果环境、发布、接口或数据等依据重要,应先沉淀到对应 A/B/C 文档,再由 `ABC-00001` 指向该文档依据。
|
|
66
|
+
- 编号一旦发布,不因排序、插入、删除或展示方式变化而重排。
|
|
67
|
+
- 删除、废弃或迁移的编号不复用;必须保留废弃说明、迁移说明或证据指针,保证后续可追溯。
|
|
68
|
+
- TODO 条目的增删改一定涉及文档变更;编号变化本身也算文档变更,必须同步回写依据或说明。
|
|
69
|
+
- `checkbox` 不是实时进度;执行完成后一轮批量回写状态和证据,避免边执行边改编号或边做边打勾。
|
|
70
|
+
|
|
71
|
+
## 不应写入
|
|
72
|
+
|
|
73
|
+
- 需求、架构或详细设计的长篇正文。
|
|
74
|
+
- 用 TODO 条目替代正式设计决策或详细实现说明。
|
|
75
|
+
- 执行子任务时的实时流水账式过程记录。
|
|
76
|
+
- 执行过程中的临时进度、试错记录、命令输出或局部 todo;这些内容应留在执行会话、issue/MR、测试报告或其他执行记录中。
|
|
77
|
+
- 因为“做了一步”就即时回写 TODO,或边执行边勾 `checkbox`。
|
|
78
|
+
- 与文档依据无关的孤立 checklist 或平行状态账本。
|
|
79
|
+
|
|
80
|
+
## 与其他文档的关系
|
|
81
|
+
|
|
82
|
+
- 本文件引用 `000.名词解释.md`、`A00.需求分析.md`、`B00.规划设计.md`、`C00.执行计划/详细设计.md` 的结论,不复制其正文。
|
|
83
|
+
- 需要判断内容是否应回退到其他主文档时,先读 [设计文档职责边界](design-doc-boundaries.md)。
|
|
84
|
+
- 轻量追踪关系建议保持为 `A00` 需求 ID -> `B00` 模块/接口 -> `C00` 文件/函数/测试 -> `000.TODO.md` 状态与证据指针。
|
|
85
|
+
- 设计决策变更应先更新对应主文档,再在本文件回写状态、缺口和证据指针。
|
|
86
|
+
- 创建或重建时应参考 [000.TODO.md 模板](../assets/000-todo.template.md),保持字段和复核入口一致。
|
|
87
|
+
|
|
88
|
+
## 更新触发条件
|
|
89
|
+
|
|
90
|
+
- TODO 条目发生增删改,即文档依据、任务树结构或治理结构发生变化。
|
|
91
|
+
- 一轮实施、验证、部署或联调结束,需要批量勾选 `checkbox` 并补证据指针。
|
|
92
|
+
- 一次性执行未完成,需要记录失败原因、偏离点、阻塞证据,或据此调整后续文档和 TODO。
|
|
93
|
+
- A/B/C 文档发生变化,需要同步状态、缺口和证据指针。
|
|
94
|
+
- 验收结果、证据入口或阻塞状态发生变化,需要更新证据指针。
|
|
95
|
+
|
|
96
|
+
## 复核要点
|
|
97
|
+
|
|
98
|
+
- 是否清楚记录当前状态、阻塞、验收状态和证据指针。
|
|
99
|
+
- 是否错误承载了设计决策正文。
|
|
100
|
+
- 风险分析正文是否被错误写进 TODO,而没有回到对应主文档。
|
|
101
|
+
- 是否把临时进度、试错记录、命令输出或局部 todo 误写进 TODO。
|
|
102
|
+
- 是否把 TODO 当作实时看板,替代其他执行记录或协作系统。
|
|
103
|
+
- 是否出现边执行子任务边同步修改 TODO 的痕迹。
|
|
104
|
+
- `checkbox` 是否基于可复核证据批量更新,而非主观估计。
|
|
105
|
+
- 工作包首项是否先完成 A/B/C 文档依据验收,再推进实现、测试、部署和联调。
|
|
106
|
+
- 编号前缀表、编号稳定性、废弃编号说明和编号映射是否完整。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# A00.需求分析.md 复核清单
|
|
2
|
+
|
|
3
|
+
## 必查项
|
|
4
|
+
|
|
5
|
+
- 是否为每条需求分配了稳定需求 ID。
|
|
6
|
+
- 是否为每条需求写了验收标准或至少一个可验证场景。
|
|
7
|
+
- 是否把功能需求和非功能需求分开表达。
|
|
8
|
+
- 是否明确列出约束、假设、依赖和非目标。
|
|
9
|
+
- 是否给出了后续追踪指针,能映射到 `B00` 模块 / 接口与 `C00` 验证入口。
|
|
10
|
+
|
|
11
|
+
## 串层检查
|
|
12
|
+
|
|
13
|
+
- 是否混入 `B00` 的模块拆分、接口协议细节、数据模型口径。
|
|
14
|
+
- 是否混入 `C00` 的代码落点、命令、迁移步骤或发布细节。
|
|
15
|
+
- 是否把实施状态、勾选项或阻塞说明写成了需求正文。
|
|
16
|
+
|
|
17
|
+
## 结果检查
|
|
18
|
+
|
|
19
|
+
- 文档是否能单独回答为什么做、要做什么、做到什么算完成。
|
|
20
|
+
- 需求是否可被后续设计与测试验证,而不是停留在抽象口号。
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# A00.需求分析.md 模块裁剪
|
|
2
|
+
|
|
3
|
+
## 必选最小模块
|
|
4
|
+
|
|
5
|
+
- `Why`:背景、问题、触发原因。
|
|
6
|
+
- `What Changes`:本次要改变什么能力、行为或边界。
|
|
7
|
+
- `Scope / In / Out`:本次覆盖范围与明确不覆盖范围。
|
|
8
|
+
- `Requirement` + `Scenario` / 验收场景:每条需求带稳定 ID,至少绑定一个可验证场景。
|
|
9
|
+
|
|
10
|
+
## 常用可选模块
|
|
11
|
+
|
|
12
|
+
- `Capabilities`:按能力簇整理需求,而不是平铺罗列。
|
|
13
|
+
- `Impact`:对现有流程、角色、上下游或兼容面的影响。
|
|
14
|
+
- `Non-Goals`:主动声明不做什么,防止范围漂移。
|
|
15
|
+
- 用户 / 场景:按角色、输入面、业务情境组织需求。
|
|
16
|
+
- 非功能需求:性能、安全、可靠性、可观测性、兼容性、合规。
|
|
17
|
+
- 外部接口需求:对外输入输出、第三方约束、协议前提。
|
|
18
|
+
|
|
19
|
+
## 中大型项目模块
|
|
20
|
+
|
|
21
|
+
- SRS 式引言:目的、范围、术语、参考资料、文档约定。
|
|
22
|
+
- 总体描述:产品环境、用户类别、运行约束、假设依赖。
|
|
23
|
+
- 功能需求:分组需求、优先级、业务规则、异常情形。
|
|
24
|
+
- 非功能需求:质量属性、容量、性能、安全、审计、可运维性。
|
|
25
|
+
- 外部接口需求:用户接口、软件接口、硬件接口、通信接口。
|
|
26
|
+
- 验收标准:按需求 ID 给出验证条件与通过标准。
|
|
27
|
+
- 需求追踪矩阵:把需求映射到 `B00` 模块 / 接口和 `C00` 验证入口。
|
|
28
|
+
|
|
29
|
+
## 组织原则
|
|
30
|
+
|
|
31
|
+
- 先写最小闭环,再按风险补可选模块。
|
|
32
|
+
- 每条需求保持稳定 ID,不因排序调整而改号。
|
|
33
|
+
- 每条需求至少要有一个可验证场景;只有描述没有验证入口的条目不算完成。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# A00.需求分析.md 总览
|
|
2
|
+
|
|
3
|
+
## 职责
|
|
4
|
+
|
|
5
|
+
- 回答为什么做、要做什么、做到什么算完成。
|
|
6
|
+
- 定义问题空间、范围边界、验收口径和稳定需求输入。
|
|
7
|
+
- 作为 `B00.规划设计.md` 与 `C00.执行计划/详细设计.md` 的上游依据。
|
|
8
|
+
|
|
9
|
+
## 边界
|
|
10
|
+
|
|
11
|
+
- 不写架构、模块拆分、接口协议细节、数据流和系统分层。
|
|
12
|
+
- 不写代码落点、目录映射、脚本命令、迁移步骤和实施状态。
|
|
13
|
+
- 不用任务状态或 TODO 勾选替代需求正文。
|
|
14
|
+
|
|
15
|
+
## 写法口径
|
|
16
|
+
|
|
17
|
+
- 轻量写法可参考 OpenSpec 的 proposal / spec 思路:只保留当前变更真正需要的需求模块。
|
|
18
|
+
- 中大型或合规项目可参考 IEEE 830 / ISO 29148 的 SRS 组织方式,但只采纳需要的章节,不复制整套模板。
|
|
19
|
+
- 模块裁剪见 [模块裁剪](modules.md),交付前复核见 [复核清单](checklist.md)。
|
|
20
|
+
|
|
21
|
+
## 最小结论
|
|
22
|
+
|
|
23
|
+
- 至少回答背景、目标范围、稳定需求 ID、验收标准。
|
|
24
|
+
- 每条需求都应能被 `B00` 设计映射和 `C00` 验证入口追踪。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# B00.规划设计.md 复核清单
|
|
2
|
+
|
|
3
|
+
## 必查项
|
|
4
|
+
|
|
5
|
+
- 是否写清楚模块职责,以及每个关键模块不负责什么。
|
|
6
|
+
- 是否定义了接口契约、关键输入输出和边界条件。
|
|
7
|
+
- 是否记录了关键决策、取舍理由和被放弃方案。
|
|
8
|
+
- 是否把非功能需求映射到具体架构策略,而不是停留在口号。
|
|
9
|
+
- 是否能从 `A00` 需求追踪到 `B00` 模块 / 接口,再追踪到 `C00` 落地入口。
|
|
10
|
+
|
|
11
|
+
## 串层检查
|
|
12
|
+
|
|
13
|
+
- 是否混入 `C00` 的逐文件改动清单、命令、迁移任务或验证流水账。
|
|
14
|
+
- 是否把 TODO 状态、阻塞、完成度写成了设计正文。
|
|
15
|
+
- 是否把需求新增或验收标准修改偷偷放进了 B 文档。
|
|
16
|
+
|
|
17
|
+
## 结果检查
|
|
18
|
+
|
|
19
|
+
- 文档是否足以支撑后续实现者在不猜测总体结构的前提下进入 `C00`。
|
|
20
|
+
- 架构说明是否既有边界,也有理由,而不是只给结论不说明依据。
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# B00.规划设计.md 模块裁剪
|
|
2
|
+
|
|
3
|
+
## 必选最小模块
|
|
4
|
+
|
|
5
|
+
- 小变更且现有架构边界稳定时,`B00` 可以省略为独立文件。
|
|
6
|
+
- 若需要写 `B00`,最小只保留 `Context` 和 `Decisions`:
|
|
7
|
+
- `Context`:当前系统边界、相关参与方、外部依赖、已有约束。
|
|
8
|
+
- `Decisions`:当前必须冻结的模块划分、接口边界、数据口径或策略取舍。
|
|
9
|
+
|
|
10
|
+
## 常用可选模块
|
|
11
|
+
|
|
12
|
+
- `Goals / Non-Goals`:本轮设计要解决什么,不解决什么。
|
|
13
|
+
- `Risks / Trade-offs`:风险、代价、质量属性冲突和取舍。
|
|
14
|
+
- `Alternatives`:备选方案、拒绝原因、适用前提。
|
|
15
|
+
- 模块职责:谁负责什么,也写清楚不负责什么。
|
|
16
|
+
- 接口边界:输入输出、所有权、版本口径、失败语义。
|
|
17
|
+
- 数据模型口径:关键实体、字段含义、一致性和生命周期。
|
|
18
|
+
|
|
19
|
+
## 中大型项目模块
|
|
20
|
+
|
|
21
|
+
- arc42 / 概要设计式上下文与范围。
|
|
22
|
+
- 约束与驱动因素。
|
|
23
|
+
- 构建块视图:模块分层、职责、依赖。
|
|
24
|
+
- 运行时视图:关键场景、时序、交互链路。
|
|
25
|
+
- 部署视图:环境、节点、边界、外部系统。
|
|
26
|
+
- 横切概念:安全、可观测性、配置、错误处理、兼容策略。
|
|
27
|
+
- 质量需求映射:把性能、安全、可靠性等映射到设计决策。
|
|
28
|
+
- 设计决策、风险与技术债。
|
|
29
|
+
|
|
30
|
+
## 何时必须写 B
|
|
31
|
+
|
|
32
|
+
- 变更跨多个切面或多个模块边界。
|
|
33
|
+
- 引入新架构、新外部依赖或新的部署/交互边界。
|
|
34
|
+
- 数据模型、协议口径或接口契约发生变化。
|
|
35
|
+
- 安全、性能、迁移复杂度显著提高。
|
|
36
|
+
- 现有实现存在歧义,`C00` 无法在不猜测架构的前提下落地。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# B00.规划设计.md 总览
|
|
2
|
+
|
|
3
|
+
## 职责
|
|
4
|
+
|
|
5
|
+
- 回答系统怎么分、模块怎么协作、协议 / 边界 / 数据流怎么定。
|
|
6
|
+
- 把 `A00.需求分析.md` 的需求和约束映射成可实施的系统边界。
|
|
7
|
+
- 记录关键设计决策、取舍理由和质量属性落实方式。
|
|
8
|
+
|
|
9
|
+
## 边界
|
|
10
|
+
|
|
11
|
+
- 不写代码改动清单、逐文件实施计划、迁移任务清单。
|
|
12
|
+
- 不写 CI job 细节、发布步骤、联调流水账或实施状态。
|
|
13
|
+
- 不用 TODO 状态替代设计正文,也不把临时实现技巧上升为架构原则。
|
|
14
|
+
|
|
15
|
+
## 写法口径
|
|
16
|
+
|
|
17
|
+
- 小变更下,B 文档是条件性设计文档;当现有边界足够稳定时,可只补最小决策记录。
|
|
18
|
+
- 轻量写法可参考 OpenSpec design 的条件性设计思想:只写当前变更真正需要澄清的结构与决策。
|
|
19
|
+
- 中大型项目可参考 arc42、IEEE 1016 和常见 GB 概要设计口径,但按项目风险裁剪章节。
|
|
20
|
+
- 模块裁剪见 [模块裁剪](modules.md),交付前复核见 [复核清单](checklist.md)。
|
|
21
|
+
|
|
22
|
+
## 最小结论
|
|
23
|
+
|
|
24
|
+
- 至少说明上下文、关键边界、核心决策以及它们如何承接 `A00` 需求。
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# C00.执行计划/详细设计.md 复核清单
|
|
2
|
+
|
|
3
|
+
## 必查项
|
|
4
|
+
|
|
5
|
+
- 是否能从 `B00` 模块 / 接口映射到 `C00` 的代码落点和任务分组。
|
|
6
|
+
- 是否写清楚主要代码落点、配置入口和验证入口。
|
|
7
|
+
- 是否给出迁移、发布和回滚路径,或明确说明不需要。
|
|
8
|
+
- 是否让测试入口和 `A00` 验收标准一一对应。
|
|
9
|
+
- 是否保留了状态回写和证据收口位置,供 `000.TODO.md` 引用。
|
|
10
|
+
|
|
11
|
+
## 串层检查
|
|
12
|
+
|
|
13
|
+
- 是否偷偷新增需求、扩展范围或修改验收标准。
|
|
14
|
+
- 是否绕开 `B00` 直接改写了架构边界或模块职责。
|
|
15
|
+
- 是否把实时状态、勾选项、阻塞记录当成详细设计正文。
|
|
16
|
+
|
|
17
|
+
## 结果检查
|
|
18
|
+
|
|
19
|
+
- 实施者是否可以据此找到入口、按顺序执行并完成验证。
|
|
20
|
+
- 文档是否足以支撑失败时回滚,成功时回写证据,而不是只给理想路径。
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# C00.执行计划/详细设计.md 模块裁剪
|
|
2
|
+
|
|
3
|
+
## 必选最小模块
|
|
4
|
+
|
|
5
|
+
- 分组任务:按实现闭环拆成可执行的小组,而不是只列主题。
|
|
6
|
+
- 可验证步骤:每组任务都要有完成判定和验证入口。
|
|
7
|
+
- 依赖顺序:说明先做什么、后做什么、哪些前提必须满足。
|
|
8
|
+
- 执行入口:给出从哪里开始改、从哪里开始测。
|
|
9
|
+
|
|
10
|
+
## 常用可选模块
|
|
11
|
+
|
|
12
|
+
- 代码落点:目录、文件、函数、模块、配置键。
|
|
13
|
+
- 配置 / 脚本 / 命令:需要修改什么,如何执行。
|
|
14
|
+
- 测试入口:单测、集成、联调、验收入口与前置环境。
|
|
15
|
+
- 回滚 / 迁移:数据、配置、兼容开关、发布回退路径。
|
|
16
|
+
- 验收映射:把 `A00` 验收标准和 `B00` 边界映射到具体验证动作。
|
|
17
|
+
|
|
18
|
+
## 中大型项目模块
|
|
19
|
+
|
|
20
|
+
- 详细设计式模块说明:职责、边界、依赖。
|
|
21
|
+
- 输入 / 输出:参数、事件、报文、状态变更。
|
|
22
|
+
- 算法 / 流程:关键流程、状态机、异常处理。
|
|
23
|
+
- 接口:内部接口、外部 API、调用约束。
|
|
24
|
+
- 存储:表、索引、缓存、文件、生命周期。
|
|
25
|
+
- 错误日志:错误码、告警、日志、可观测性入口。
|
|
26
|
+
- API 详细设计:字段、语义、兼容、版本演进。
|
|
27
|
+
- 数据库物理设计:表结构、迁移顺序、回滚策略。
|
|
28
|
+
- 测试计划:覆盖面、数据准备、环境、验收方式。
|
|
29
|
+
|
|
30
|
+
## 执行原则
|
|
31
|
+
|
|
32
|
+
- 任务条目应尽量控制在一次会话或一轮内可完成。
|
|
33
|
+
- 未完成时先回写结果、失败原因和偏离点,再调整设计文档或 `000.TODO.md`,不要让计划与现实脱节。
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# C00.执行计划/详细设计.md 总览
|
|
2
|
+
|
|
3
|
+
## 职责
|
|
4
|
+
|
|
5
|
+
- 回答代码怎么落、怎么迁移、怎么测、怎么发。
|
|
6
|
+
- 把 `B00.规划设计.md` 的边界转换成可执行的代码、配置、验证和发布方案。
|
|
7
|
+
- 让实施、联调、回滚和验收都能沿文档找到入口。
|
|
8
|
+
|
|
9
|
+
## 边界
|
|
10
|
+
|
|
11
|
+
- 不新增需求,不改写完成标准。
|
|
12
|
+
- 不推翻 `B00` 已定架构;若边界不成立,应先回到 `B00` 补决策。
|
|
13
|
+
- 不用任务状态、勾选项或流水账替代详细设计正文。
|
|
14
|
+
|
|
15
|
+
## 写法口径
|
|
16
|
+
|
|
17
|
+
- 轻量写法可参考 OpenSpec tasks:按可验证步骤组织执行计划,而不是写成散乱备注。
|
|
18
|
+
- 中大型项目可参考常见 GB 详细设计口径,但只保留当前实现真正需要的模块说明。
|
|
19
|
+
- 模块裁剪见 [模块裁剪](modules.md),交付前复核见 [复核清单](checklist.md)。
|
|
20
|
+
|
|
21
|
+
## 最小结论
|
|
22
|
+
|
|
23
|
+
- 至少给出执行入口、依赖顺序、主要代码落点和验证入口。
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# 设计文档职责边界
|
|
2
|
+
|
|
3
|
+
## 目的
|
|
4
|
+
|
|
5
|
+
- 用于判断内容应写入 `000.名词解释.md`、`000.TODO.md`、`A00.需求分析.md`、`B00.规划设计.md` 还是 `C00.执行计划/详细设计.md`。
|
|
6
|
+
- 用于文档迁移、骨架补齐、完整性复核时统一口径,避免需求、架构、实现、状态和术语相互串层。
|
|
7
|
+
|
|
8
|
+
## 判断口诀
|
|
9
|
+
|
|
10
|
+
- 要不要做 / 为什么做 / 完成标准 -> `A00.需求分析.md`
|
|
11
|
+
- 系统怎么分 / 模块怎么协作 / 协议边界怎么定 -> `B00.规划设计.md`
|
|
12
|
+
- 代码怎么落 / 怎么迁移 / 怎么测 / 怎么发 -> `C00.执行计划/详细设计.md`
|
|
13
|
+
- 现在做到哪 / 卡在哪 / 证据在哪 -> `000.TODO.md`
|
|
14
|
+
- 术语怎么叫 / 哪些名字禁止 -> `000.名词解释.md`
|
|
15
|
+
|
|
16
|
+
## 决策表
|
|
17
|
+
|
|
18
|
+
| 关注点 | 应写入 | 应包含 | 不应包含 |
|
|
19
|
+
| --- | --- | --- | --- |
|
|
20
|
+
| 术语与命名治理 | `000.名词解释.md` | 术语定义、别名、禁止词、命名冻结、跨文档术语一致性 | 需求正文、架构设计、实现计划 |
|
|
21
|
+
| 当前推进与验收状态 | `000.TODO.md` | 当前状态、任务树、阻塞、验收状态、证据指针 | 设计决策正文、长篇方案说明 |
|
|
22
|
+
| 需求与成功标准 | `A00.需求分析.md` | 背景、目标、非目标、场景、需求、约束、成功标准、验收口径 | 架构拆分、模块协作、代码落点 |
|
|
23
|
+
| 系统设计与边界 | `B00.规划设计.md` | 总体架构、模块职责、接口/协议/数据模型口径、系统级策略、方案取舍 | 代码改动清单、实施状态 |
|
|
24
|
+
| 落地实现与发布验证 | `C00.执行计划/详细设计.md` | 代码落点、目录/包/模块映射、实现细节、配置/脚本/命令、迁移/发布/回滚、验证入口 | 新增需求、推翻 B 层架构 |
|
|
25
|
+
|
|
26
|
+
## `000.名词解释.md`
|
|
27
|
+
|
|
28
|
+
### 负责内容
|
|
29
|
+
|
|
30
|
+
- 统一术语定义,明确一个概念在全文档体系中的唯一主叫法。
|
|
31
|
+
- 记录别名、历史名称、易混淆说法、禁止词。
|
|
32
|
+
- 说明命名冻结规则,避免后续文档在同一概念上反复改名。
|
|
33
|
+
- 维护跨文档术语一致性,作为 A/B/C/TODO 的命名基线。
|
|
34
|
+
|
|
35
|
+
### 不负责内容
|
|
36
|
+
|
|
37
|
+
- 不承载需求背景、目标、约束或验收口径。
|
|
38
|
+
- 不承载架构分层、模块协作、协议设计。
|
|
39
|
+
- 不承载实现计划、迁移步骤、测试命令。
|
|
40
|
+
|
|
41
|
+
## `000.TODO.md`
|
|
42
|
+
|
|
43
|
+
### 负责内容
|
|
44
|
+
|
|
45
|
+
- 记录当前状态、任务树、阻塞、验收状态。
|
|
46
|
+
- 维护证据指针,例如指向设计章节、实现变更、测试结果、联调记录、发布验证入口。
|
|
47
|
+
- 作为持续更新的状态账本,反映真实推进情况与未闭合项。
|
|
48
|
+
|
|
49
|
+
### 不负责内容
|
|
50
|
+
|
|
51
|
+
- 不承载设计决策正文。
|
|
52
|
+
- 不复制 A/B/C 中的大段论证、架构说明或实现细节。
|
|
53
|
+
- 不承载风险分析正文;风险判断应落在 A/B/C 对应层级,TODO 只记录阻塞、状态和证据。
|
|
54
|
+
- 不用 TODO 代替正式需求文档、架构文档或详细设计文档。
|
|
55
|
+
|
|
56
|
+
## 扩展文档归位表
|
|
57
|
+
|
|
58
|
+
| 内容 | 默认归位 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| ADR | 默认归 `B` 系列 `Decisions`;决策很多时可拆成 `B` 系列子文档。 |
|
|
61
|
+
| API | 高层契约、边界、兼容策略归 `B`;字段、schema、命令、兼容测试细节归 `C`。 |
|
|
62
|
+
| 测试计划 | 归 `C`;`A` 只写验收口径,`B` 只写质量策略。 |
|
|
63
|
+
| 发布 / 回滚 | 归 `C`;`B` 可写部署视图或发布策略,TODO 只写状态和证据指针。 |
|
|
64
|
+
| 安全 | 安全需求归 `A`;威胁模型、控制策略归 `B`;验证、加固步骤和测试入口归 `C`。 |
|
|
65
|
+
| 运维 / Runbook | 常规操作步骤归 `C` 或外部运维文档指针;TODO 只记录状态和证据。 |
|
|
66
|
+
| 用户文档 / README / 贡献指南 | 不属于 A/B/C 强制骨架;可作为外部文档或项目文档入口,不纳入默认顶层。 |
|
|
67
|
+
|
|
68
|
+
## Micro Mode / 小项目最小模式
|
|
69
|
+
|
|
70
|
+
- 小项目或低风险改动可只维护最小 `A00` + `C00` + `000.TODO.md`。
|
|
71
|
+
- `000.名词解释.md` 是否单独创建,按术语复杂度决定。
|
|
72
|
+
- `B` 系列仅在系统边界、架构、协议、数据模型、安全或性能策略发生变化,或现有口径存在歧义时单独产出。
|
|
73
|
+
- 即使采用 micro mode,仍要保留 `A` 的完成标准、`C` 的验证入口、TODO 的证据指针。
|
|
74
|
+
|
|
75
|
+
## `A00.需求分析.md`
|
|
76
|
+
|
|
77
|
+
### 负责内容
|
|
78
|
+
|
|
79
|
+
- 回答为什么做、要做什么、做到什么算完成。
|
|
80
|
+
- 记录背景、目标、非目标、用户或业务场景、需求清单、约束、成功标准、验收口径。
|
|
81
|
+
- 定义问题空间和结果边界,为 B/C 提供稳定输入。
|
|
82
|
+
|
|
83
|
+
### 不负责内容
|
|
84
|
+
|
|
85
|
+
- 不写系统架构拆分、模块职责划分。
|
|
86
|
+
- 不写接口协议、数据流细节、代码目录或包路径。
|
|
87
|
+
- 不写实现进度、任务状态或回滚步骤。
|
|
88
|
+
|
|
89
|
+
## `B00.规划设计.md`
|
|
90
|
+
|
|
91
|
+
### 负责内容
|
|
92
|
+
|
|
93
|
+
- 回答系统怎么分、模块怎么协作、协议/边界/数据流怎么定。
|
|
94
|
+
- 记录总体架构、模块职责、接口与协议约定、数据模型口径、系统级策略、方案取舍。
|
|
95
|
+
- 说明关键设计决策及其理由,为 C 层实现提供边界条件。
|
|
96
|
+
|
|
97
|
+
### 不负责内容
|
|
98
|
+
|
|
99
|
+
- 不写代码改动清单、文件逐项修改计划。
|
|
100
|
+
- 不写当前实施状态、任务完成度、验证进展。
|
|
101
|
+
- 不把临时实现细节上升为架构原则。
|
|
102
|
+
|
|
103
|
+
## `C00.执行计划/详细设计.md`
|
|
104
|
+
|
|
105
|
+
### 负责内容
|
|
106
|
+
|
|
107
|
+
- 回答代码怎么落、怎么迁移、怎么测、怎么发。
|
|
108
|
+
- 记录代码落点、目录/包/模块映射、实现细节、配置/脚本/命令、迁移/发布/回滚、验证入口。
|
|
109
|
+
- 把 B 层设计转换成可执行的实现与验证路径。
|
|
110
|
+
|
|
111
|
+
### 不负责内容
|
|
112
|
+
|
|
113
|
+
- 不新增需求,不修改完成标准。
|
|
114
|
+
- 不推翻 B 层已确定的总体架构和模块边界;若确需调整,应先回到 B 层补决策。
|
|
115
|
+
- 不用实现便利性倒逼需求改写。
|
|
116
|
+
|
|
117
|
+
## 回退规则
|
|
118
|
+
|
|
119
|
+
- 如果 `000.TODO.md` 的设计依据验收失败,先判断缺口属于哪一层:
|
|
120
|
+
- 术语不清、命名冲突 -> 补 `000.名词解释.md`
|
|
121
|
+
- 为什么做、做什么、完成标准不清 -> 补 `A00.需求分析.md`
|
|
122
|
+
- 模块边界、协议、数据流或方案取舍不清 -> 补 `B00.规划设计.md`
|
|
123
|
+
- 代码落点、迁移路径、验证入口或发布回滚不清 -> 补 `C00.执行计划/详细设计.md`
|
|
124
|
+
- 对应文档补齐后,再回写 `000.TODO.md` 的状态、阻塞变化和证据指针。
|
|
125
|
+
- 不在 TODO 中临时塞入设计正文来“补齐”依据。
|
|
126
|
+
|
|
127
|
+
## 常见误放
|
|
128
|
+
|
|
129
|
+
- 把“为什么需要这个能力、什么情况下算完成”写进 `B00`:应回到 `A00`。
|
|
130
|
+
- 把“服务拆成几个模块、边界如何约束”写进 `C00`:应回到 `B00`。
|
|
131
|
+
- 把“修改哪些目录、执行哪些命令、如何回滚”写进 `A00`:应移到 `C00`。
|
|
132
|
+
- 把“当前卡在外部依赖、测试结果在哪里”写进 `B00` 正文:应记录到 `000.TODO.md` 并附证据指针。
|
|
133
|
+
- 把“同一个概念出现多个叫法,哪些用词禁止”散落在 A/B/C 中:应统一收敛到 `000.名词解释.md`。
|
|
134
|
+
|
|
135
|
+
## 迁移与复核提示
|
|
136
|
+
|
|
137
|
+
- 迁移混合文档时,先按术语、需求、设计、执行、状态五类拆分,再决定落点。
|
|
138
|
+
- 确定拆分方案后、执行任何文件写入前,逐一列出将从哪个文件的哪个段落或章节搬移到哪个目标文件,完整展示全部迁移计划。
|
|
139
|
+
- 等待用户明确授权后,才执行实际搬迁;涉及删除或改写原文件内容的操作,与新增同等对待,一并纳入确认范围。
|
|
140
|
+
- 复核文档完整性时,先看 `A00` 是否定义完成标准,再看 `B00` 是否给出系统边界,再看 `C00` 是否提供落地与验证路径,最后看 `000.TODO.md` 是否反映真实状态和证据。
|
|
141
|
+
- 当多个文档都涉及同一事实时,以层级职责判断主归属,其余文档只保留引用或摘要,不重复承载整段正文。
|
|
142
|
+
|
|
143
|
+
## 轻量追踪关系
|
|
144
|
+
|
|
145
|
+
- 推荐用最小链路串起四层:`A00` 需求 ID -> `B00` 模块 / 接口 -> `C00` 文件 / 函数 / 测试 -> `000.TODO.md` 状态与证据指针。
|
|
146
|
+
- `000.TODO.md` 只保留状态和证据指针,不复制追踪矩阵正文。
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tsgw-programmer-go
|
|
3
|
+
description: "用于所有 Go 开发任务:编写、审查、重构、调试 Go 程序及回答 Go 问题。结合 Go 官方文档阅读要点与本技能强制约定,落实 PascalCase JSON、零值省略优先 omitzero,以及真实功能或修复变更中的旧 JSON 标签同步迁移;遇到明确协议或兼容性冲突先暴露并确认。"
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Go 编程技能(Pi 版)
|
|
8
|
+
|
|
9
|
+
编写简洁、地道、可维护的 Go 代码。适用于新增代码、审查、重构、调试和 Go 相关问答。Pi 可按任务加载,也可用 `/skill:tsgw-programmer-go` 显式调用。
|
|
10
|
+
|
|
11
|
+
## 规则来源与执行边界
|
|
12
|
+
|
|
13
|
+
- 下述 JSON 命名、省略策略与迁移规则是用户认定的最佳实践,属于**本技能约定**,必须执行;不是可选建议,也不冒称来自 Effective Go。
|
|
14
|
+
- Go 惯用法的阅读入口是 [Effective Go](https://go.dev/doc/effective_go) 和 [Code Review Comments](https://go.dev/wiki/CodeReviewComments)。本地 references 是自主组织的中文要点,不是官方全文,不代表本轮核验的最新版;Effective Go 也不能覆盖所有现代 Go 主题。
|
|
15
|
+
- 先检查项目明确的协议、兼容性要求和 Go 工具链约束。若与本技能约定冲突,必须指出具体字段、消费者及可能破坏的行为,向用户确认迁移范围和兼容方案;确认前不得擅自破坏公共协议。不得以“兼容”为由悄悄删除或降级本技能约定。
|
|
16
|
+
- 本技能不引入依赖,不依赖 OpenCode 专属工具。离线任务仅阅读本地资料;不能验证的版本能力应报告不确定性,不新增未经核验的新版本知识。
|
|
17
|
+
|
|
18
|
+
## Go 基础约定
|
|
19
|
+
|
|
20
|
+
- **格式化**:始终使用 `gofmt`,没有例外。
|
|
21
|
+
- **命名**:多词名称不用下划线;导出名称用 MixedCaps,未导出名称用 mixedCaps。包名简短、小写;缩写保持一致,例如 `ServeHTTP`、`appID`。
|
|
22
|
+
- **错误处理**:始终检查错误,处理或返回错误;不用 `panic` 处理普通错误,不用 `_` 悄悄丢弃错误。正常路径少缩进,错误分支尽早返回。
|
|
23
|
+
- **并发**:通过通信共享内存,使用 channel 表达协作;明确每个 goroutine 的退出条件,避免阻塞与泄漏。优先同步接口,让调用者决定是否并发。
|
|
24
|
+
- **接口**:保持精简,理想情况下 1–3 个方法;接收接口,返回具体类型。根据实际使用需求定义接口,不为假想需求预建接口。
|
|
25
|
+
- **文档**:为所有导出符号编写文档,以符号名称开头;复杂的未导出声明也应说明用途。
|
|
26
|
+
|
|
27
|
+
## JSON 强制约定(本技能)
|
|
28
|
+
|
|
29
|
+
### 零值省略
|
|
30
|
+
|
|
31
|
+
在 `encoding/json` 中,若要根据**零值**省略字段,包括自定义 `IsZero() bool` 逻辑,优先使用 `omitzero`,而不是 `omitempty`。**仅当明确需要“空值”语义而非“零值”语义时,才使用 `omitempty`**。不能不区分语义就机械替换;若项目工具链不能满足所需能力,暴露约束并确认处理方案,不擅自升级工具链或静默改用不同语义。
|
|
32
|
+
|
|
33
|
+
### 命名与标签
|
|
34
|
+
|
|
35
|
+
- 全局保持一致,默认使用 **PascalCase**。
|
|
36
|
+
- 唯一命名例外是**解析(消费或解码)来自不可控外部来源的 JSON**,例如第三方 API 响应、ADB 协议或上游工具输出;此时使用 `snake_case` 或该来源的原始格式。该例外不自动扩展到我们自己生成的输出。
|
|
37
|
+
- 对于 JSON 表示由**我们自己生成**的任何 struct,包括 API 响应、CLI 输出、文件格式或配置清单,始终使用 PascalCase。若既有明确协议与此冲突,按前述边界暴露并确认,不能直接破坏协议。
|
|
38
|
+
- Go 字段名已能生成所需 PascalCase JSON 键时,优先不指定重命名。
|
|
39
|
+
- 仅需省略零值时用 `json:",omitzero"`。
|
|
40
|
+
- 仍需显式指定 PascalCase 名称时用 `json:"FieldName,omitzero"`(此例同时需要零值省略;标签选项仍须服从实际省略语义)。
|
|
41
|
+
- 字段既不需要重命名也不需要省略时,不添加标签。
|
|
42
|
+
- 同一个 struct 内不得混用多种命名风格。若同一类型同时消费外部格式并生成我们自己的格式,先暴露用途冲突并确认边界,不将外部解析例外当作输出豁免。
|
|
43
|
+
|
|
44
|
+
### 旧 JSON 标签随真实变更迁移
|
|
45
|
+
|
|
46
|
+
- 现有代码可能包含早于本约定的 `snake_case` 或 `camelCase` 标签;**新增代码必须始终遵循 PascalCase 规则**,外部解析例外仍按上述限定执行。
|
|
47
|
+
- 修改包含旧标签的文件时,在同一次变更中顺带修正相关标签;迁移单位是该次因**真实功能或修复**而被修改的所属 struct,不借机全文件、全仓扫描改写无关 struct。
|
|
48
|
+
- 某个旧标签所属的 struct 下次因真实功能或修复被修改时,必须同步修正相关旧标签;不得在同一 struct 中同时保留旧式标签和新增 PascalCase 标签。
|
|
49
|
+
- **不要创建仅为统一 JSON 标签的独立迁移 PR**。应自然、渐进迁移,避免不成比例的代码扰动、合并冲突和下游破坏。
|
|
50
|
+
- 迁移若触及明确的公共协议或兼容性边界,必须先说明冲突并取得确认;等待确认不是取消迁移规则,不能偷偷改名,也不能默默跳过迁移而声称已合规。
|
|
51
|
+
|
|
52
|
+
## 执行与检查
|
|
53
|
+
|
|
54
|
+
1. 阅读目标代码、项目约束和相关测试,判断 JSON 是外部输入还是我们生成的输出,识别本次真实变更触及的 struct。
|
|
55
|
+
2. 按需读取 [Go 惯用法要点](references/effective_go.md) 与 [代码审查要点](references/code_review_comments.md)。不要把阅读入口当作完整规范或已验证的最新文档。
|
|
56
|
+
3. 完成功能或修复,并按上述规则同步迁移相关标签;有冲突先确认,禁止无关标签大扫除。
|
|
57
|
+
4. 对变更的 Go 文件运行 `gofmt`,在项目允许范围内运行相关测试;JSON 改动检查实际键名、零值/空值及自定义 `IsZero` 的省略行为和兼容边界。报告未执行的验证及原因。
|
|
58
|
+
5. 汇报功能改动、同步迁移的标签、协议冲突及确认结果,不把尚待确认的事项写成已完成。
|
|
59
|
+
|
|
60
|
+
## 参考与维护
|
|
61
|
+
|
|
62
|
+
- [本地来源评估与维护边界](references/UPDATE_GUIDE.md)
|
|
63
|
+
- 官方阅读入口:<https://go.dev/doc/effective_go>、<https://go.dev/wiki/CodeReviewComments>、<https://pkg.go.dev/std>
|
|
64
|
+
- 标准库 JSON 文档入口:<https://pkg.go.dev/encoding/json>(仅提供链接,本轮未联网核验)。
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# 来源与维护
|
|
2
|
+
|
|
3
|
+
## 来源与许可
|
|
4
|
+
|
|
5
|
+
本技能由本地维护的 Pi/OpenCode Go 工作流整理,保留原有 JSON 约定。正文及两份参考是自主组织的中文指导,按 MIT 提供;官方链接是阅读入口,不是官方全文副本,也不表示已经核验其最新版本。
|
|
6
|
+
|
|
7
|
+
- [Go 惯用法要点](effective_go.md)
|
|
8
|
+
- [代码审查要点](code_review_comments.md)
|
|
9
|
+
- [技能正文](../SKILL.md)
|
|
10
|
+
|
|
11
|
+
## 维护原则
|
|
12
|
+
|
|
13
|
+
1. 完整阅读技能、项目约束和目标代码,区分官方阅读要点与本技能强制约定。
|
|
14
|
+
2. 需要确认版本能力时,核对项目实际 Go 工具链、官方文档与最小测试;不猜测新 API 或最低版本。无网络或工具受限时明确报告未验证内容。
|
|
15
|
+
3. 使用宿主实际提供的工具,不依赖特定 OpenCode 抓取入口;不因维护技能而擅自安装工具或升级项目依赖。
|
|
16
|
+
4. 参考保持中文、简明,每份不超过 500 行。不要用许可不明的官方长文副本替换阅读要点。
|
|
17
|
+
5. 修改后检查技能声明、相对链接与规则完整性,不将静态检查说成实际代码或宿主验证。
|
|
18
|
+
|
|
19
|
+
## 强制约定保留清单
|
|
20
|
+
|
|
21
|
+
- 自产 JSON 默认 PascalCase;外部解析例外仅限不可控来源的输入。
|
|
22
|
+
- 根据零值省略时优先 `omitzero`,包括自定义 `IsZero() bool`;明确需要空值语义时才用 `omitempty`。
|
|
23
|
+
- 无需重命名则不重命名;只省略零值用 `json:",omitzero"`,显式命名并省略零值用 `json:"FieldName,omitzero"`;两者均不需要则不加标签。
|
|
24
|
+
- 同一 struct 不混用新旧命名风格;真实功能或修复触及所属 struct 时,同次迁移相关旧标签。
|
|
25
|
+
- 不创建仅统一标签的迁移 PR,不扩大成无关全文件或全仓改写。
|
|
26
|
+
- 不以跟随官方为由删除或降级这些最佳实践;遇到明确公共协议、兼容性或工具链冲突,先暴露影响并确认,不擅自破坏协议或虚报合规。
|