feat(插件): 发布意图提单 V2

2026-08-27 12:03:08 +08:00
parent 72e5396e6d
commit 758aa59470
10 changed files with 1107 additions and 215 deletions
@@ -1,28 +1,27 @@
-# 飞书 Base 字段契约
+# 飞书 Base V2 提单契约

- Base Token: `Ed21b9VwNaZfiesxWgDc67wXnoc`
- 数据表: `tblelMMlOif1YHPD`（需求与缺陷）
- 受控表单: `产品需求与 Bug 提交`
- 表单提交范围: 仅企业内获得链接的用户
+目标 Base 与表单由组织配置固定；脚本每次提交前读取真实表单详情，校验字段类型、必填配置和选项，不在 Skill 文档中复制一套可漂移的字段定义。

-允许提交的字段：
+允许提交的 JSON：

-| JSON 属性 | Base 字段 | 值 |
-|---|---|---|
-| `type` | 类型 | `需求` / `Bug` |
-| `title` | 标题 | 非空文本 |
-| `background` | 需求背景与目标 | 非空文本 |
-| `acceptance_criteria` | 验收标准 | 非空字符串数组 |
-| `priority` | 优先级 | `P0` / `P1` / `P2` / `P3` |
-| `environment` | 发生环境 | Bug 必填 |
-| `reproduction_steps` | 复现步骤 | Bug 必填字符串数组 |
-| `actual_result` | 实际结果 | Bug 必填 |
-| `expected_result` | 期望结果 | Bug 必填 |
-| `impact_scope` | 影响范围 | `前端` / `后端` / `全栈` / `部署` 数组，可选 |
+| JSON 属性 | Base 字段 | 要求 |
+| --- | --- | --- |
+| `type` | 类型 | 必填；`需求` / `Bug` |
+| `title` | 标题 | 必填非空文本 |
+| `background` / `problem_or_goal` | 需求背景与目标 | 必填非空文本 |
+| `expected_result` / `expected_outcome` | 期望结果 | 必填非空文本 |
+| `acceptance_criteria` | 验收标准 | 可选字符串数组，仅作为验收提示 |
+| `priority` | 优先级 | 可选；`P0` / `P1` / `P2` / `P3`，默认 `P2` |
+| `environment` | 发生环境 | Bug 可选 |
+| `reproduction_steps` | 复现步骤 | Bug 可选字符串数组 |
+| `actual_result` | 实际结果 | Bug 可选 |
+| `impact_scope` | 影响范围 | 可选提示数组；`前端` / `后端` / `全栈` / `部署` |
+| `constraints` | 约束与非目标 | 可选字符串数组，以“约束：”前缀保存 |
+| `non_goals` | 约束与非目标 | 可选字符串数组，以“非目标：”前缀保存 |
 | `desired_at` | 期望完成时间 | `YYYY-MM-DD HH:mm:ss`，可选 |
 | `references` | 参考资料 | 可选文本 |
 | `attachments` | 附件 | 当前目录内相对路径数组 |

-脚本通过受控表单自动写入但不接受模型指定：`产品负责人`、`提交幂等键`、`提交来源`。
+脚本自动注入且不接受模型指定：`产品负责人`、`提交幂等键`、`提交来源`。附件路径、大小与 SHA256 一起进入确认摘要；表单成功后同一内容摘要会按返回的记录编号固化到 `原始意图指纹`。该补写失败时回执进入 `unknown`，下次先按幂等键找到已有记录并完成指纹固化，不会重复提交表单。

-任务编号由中央调度器生成；其他系统字段不在受控表单中，全部禁止写入。
+受飞书现有表单主字段约束，`任务编号（系统自动生成，请勿填写）` 仍可能作为可选问题存在。V2 插件不得展示或提交它，任务编号由中央调度器生成；任务状态、执行阶段、状态版本、Thread、PR、部署、验收、锁、重试和审计字段都不属于提单插件。
@@ -1,23 +1,40 @@
 # 需求与 Bug 收集规则

-## 共同必填
+## 最小登记契约

- 类型、标题、背景与目标、可执行的验收标准、优先级。
- 验收标准要描述可观察结果，避免“优化一下”“体验更好”等无法判定的表达。
+- 必填：类型、标题、背景与目标、期望结果。
+- 优先级默认 `P2`，只有负责人明确表达紧急程度时才调整。
+- 验收提示、范围提示、约束、非目标、期望时间、参考资料和附件都是可选信息。
+- 范围提示可以是 `前端`、`后端`、`全栈`、`部署`；只填 `部署` 也允许登记。`全栈` 不与 `前端` 或 `后端` 同时选择。
 - 产品负责人由当前飞书授权身份自动填入，不询问 open_id。

-## Bug 额外必填
+## 优先级

- 发生环境、复现步骤、实际结果、期望结果。
- 有截图、视频或日志时作为附件；无法提供时明确记录“暂无证据”，不伪造证据。
+- `P0`：正在发生的严重故障、安全事件或数据损失；不等同于自动紧急发布，服务仍会要求授权人员确认原因。
+- `P1`：阻塞关键业务或近期交付，需优先处理。
+- `P2`：正常排期的需求或缺陷，默认选择。
+- `P3`：低影响改进、体验优化或技术债。

-## 追问优先级
+## Bug 可选补充

-1. 先问会影响是否可执行和可验收的信息。
-2. 再问用户范围、兼容性或时间限制。
-3. 不要让产品选择仓库、技术框架、实现类或数据库结构。
+- 发生环境、复现步骤、实际结果。
+- 有截图、视频或日志时作为附件；无法提供时不伪造证据。
+- 缺少这些信息仍可登记。后续 Codex 先在代码、测试和环境中定位；只有产品现象或期望行为无法确定时才询问负责人。

-## 首个真实 Canary 条件
+## 追问协议
+
+1. 只问会改变产品行为、目标或期望结果且确实阻塞登记的信息。
+2. 每轮最多一个问题，提供 2～3 个选项、推荐项和选择影响。
+3. 不问仓库、前后端归属、技术框架、实现类、数据库结构或测试方式；这些由 Codex 调研。
+
+## 服务分流提示
+
+- 最小契约成立：服务登记后由 Codex 调研代码并形成派生验收计划。
+- 产品行为存在歧义：服务通过带问题版本、状态版本和意图版本校验的飞书卡片继续澄清。
+- 只有技术信息不确定：Codex 自行搜索代码、测试和环境，不询问负责人。
+- 涉及鉴权/权限、支付、数据库迁移、生产基础设施、密钥或破坏性变更：如实记录负责人目标，不替负责人缩小或批准范围；后续服务按风险策略处理。
+
+## 首个真实 Canary 条件（仅当用户明确说是 Canary 时应用）

 - 范围清晰、一天内可完成、验收结果确定、可回滚。
 - 不涉及支付、权限、数据迁移、数据库结构或破坏性操作。