Lina 反馈：结构化的修复、验证与测试覆盖循环

当用户在实现后发现 Bug、改进点或提出建议时，此技能先判断反馈是否值得沉淀为 OpenSpec 记录，再选择追加活跃变更、新建变更、直接修复或仅答复说明。进入 OpenSpec 路径的问题需要组织到tasks.md中的可追踪任务列表；未达到 OpenSpec 记录门槛的问题也必须完成清晰的根因分析、实现取舍、验证和结果说明。

核心原则：

1. 先分诊再处理 — 不因存在活跃变更就自动写入 OpenSpec，先判断反馈价值、影响范围和可追踪性需求
2. 规范是唯一事实来源 — 达到 OpenSpec 门槛且属于规范级别的变更需先更新规范再记录任务
3. 验证方式匹配问题性质 — 功能行为修复需要单元测试或 E2E 测试覆盖；项目治理类反馈使用openspec validate、静态扫描、文件检查、格式检查或审查结论等治理验证方式

交互语言：与用户交互的内容语言以用户上下文使用的语言为准，用户使用英文则使用英文，用户使用中文则使用中文。

工作流

1. 反馈分诊与 OpenSpec 门槛

关键规则：

1. 先判断反馈是否需要 OpenSpec 记录，再决定目标变更；活跃变更只是候选上下文，不是自动追加条件。
2. OpenSpec 记录门槛由 AI 自主判断。除非归属存在真实歧义或方案风险需要用户取舍，不要把门槛判断交还给用户。
3. 活跃变更是指仍直接存在于openspec/changes/下、且未被移入openspec/changes/archive/的变更目录。不要将status: complete、所有任务已勾选或其他完成信号视为"非活跃"，除非实际已归档。

openspec list --json
# 或：ls openspec/changes/ | grep -v archive

当两个信号不一致时，优先遵循文件系统规则：

• 如果变更目录仍存在于openspec/changes/下且不在archive/中，则为活跃变更。
• openspec list --json可能仍将此类变更报告为status: complete；这仅表示实现任务已完成，不表示变更已归档。
• 只有位于openspec/changes/archive/下的已归档变更才是非活跃的。

处理路径：

路径	判定标准	操作
openspec-existing	反馈直接修正或补全某个活跃变更的目标、验收、实现缺口、回归问题或治理门禁	追加到该活跃变更的tasks.md，必要时更新specs/
openspec-new	反馈形成新的可持续产品能力、模块/API/数据/权限契约、跨模块设计、架构决策或需要长期追踪的治理规则	新建变更，再写入最小必要 OpenSpec 文档
direct-fix	反馈是局部实现问题、文案/技能说明微调、轻量治理修正、低风险测试补充，或不具备长期规范沉淀价值	不创建或追加 OpenSpec；直接做根因分析、修复和验证，并在结果中说明跳过 OpenSpec 的理由
no-change	反馈只是讨论、已被现有实现覆盖、暂不采纳的建议，或需要先澄清而不能安全落地	不修改文件；输出判断依据、已检查证据和下一步条件

应进入 OpenSpec 的常见信号：

• 改变用户可观察的功能语义、接口契约、数据模型、权限边界、模块边界或插件宿主能力。
• 修复暴露出原规范缺失、验收标准不完整、任务拆分遗漏或活跃变更实现范围不完整。
• 影响多个模块、插件、端到端工作流、发布治理或后续归档审查。
• 需要在未来审查、归档、回归验证或团队协作中保留明确追踪记录。

通常不进入 OpenSpec 的信号：

• 不改变产品或框架契约的技能文档措辞、注释、格式、局部脚本提示或轻量治理说明。
• 单文件、低风险、无长期设计价值的实现修正，且通过测试或静态检查即可闭环。
• 探索性建议、偏好表达或暂不采纳的方向，尚未形成可执行需求。

分诊后必须先告知：

### 反馈分诊
- 处理路径：direct-fix / openspec-existing / openspec-new / no-change
- 判断依据：<反馈是否达到 OpenSpec 记录门槛的原因>
- 活跃变更：<无 / 已考虑的变更及相关性>
- 后续动作：<直接修复 / 写入目标变更 / 新建变更 / 仅说明>

存在多个活跃变更时： 只有在处理路径为openspec-existing且多个活跃变更都高度相关、无法可靠自主选择时，才向用户确认目标变更。

检测到多个活跃变更。此反馈应追加到哪个变更？

1. config-management — 系统配置 CRUD 管理
2. user-auth — 用户认证增强

请选择 1 或 2：

如果只有一个活跃变更与反馈强相关，则自动选择并告知；如果存在活跃变更但均不相关，不要强行追加。

需要新建变更时：

1. 从反馈内容派生 kebab-case 名称（如 "fix-menu-circular-ref"）
2. 如果名称已存在，添加后缀 ("-2")
3. 执行：openspec new change "<name>"
4. 生成最小化的proposal.md（一段话概述上下文）
5. 纯 Bug 修复可跳过design.md，除非涉及架构变更

OpenSpec 路径告知："将反馈修复应用到变更：<名称>"

2. 读取当前上下文

如果处理路径为openspec-existing或openspec-new，读取目标变更上下文：

文件	用途
tasks.md	任务结构、命名规范、编号
design.md	架构上下文
proposal.md	功能范围和意图
specs/	增量规范定义

# 查找目标模块目录内的 TC ID，用于按模块本地递增规划测试编号
find hack/tests/e2e/<module> -maxdepth 1 -type f -name 'TC*.ts' | sort
# 或源码插件：
find apps/lina-plugins/<plugin-id>/hack/tests/e2e/<module> -maxdepth 1 -type f -name 'TC*.ts' | sort

如果处理路径为direct-fix或no-change，只读取判断和验证所需的源码、文档、测试、规则文件或运行证据；不要为了形式化流程创建 OpenSpec 文档。

外部规则文件：

• 读取AGENTS.md作为顶层规范入口。
• 必须按AGENTS.md的强制规则加载矩阵识别反馈命中的规则域，并在分诊、记录任务、修改规范、修复代码或输出审查结论前读取所有对应的.agents/rules/*.md。
• 禁止仅凭记忆、历史上下文、摘要或此前读取记录替代本次读取。
• 若触发场景命中但对应规则文件不存在、无法读取或存在无法调和的规则冲突，不得继续反馈修复；必须先修复规则入口或向用户说明阻断原因。
• 每个反馈都必须评估并记录i18n、缓存一致性、数据权限、开发工具跨平台和测试影响。若存在影响，必须读取对应规则文件并按其中的设计、实现、验证和审查要求执行；若确认无影响，也必须在该反馈的影响分析或审查结论中明确记录。
• 常见规则域包括但不限于：后端 Go 读取.agents/rules/backend-go.md；API 契约读取.agents/rules/api-contract.md；SQL 和 DAO 读取.agents/rules/database.md；缓存读取.agents/rules/cache-consistency.md；数据权限读取.agents/rules/data-permission.md；源码插件、动态插件、插件同构开发目录和插件生命周期资源读取.agents/rules/plugin.md；前端 UI 读取.agents/rules/frontend-ui.md；测试读取.agents/rules/testing.md；开发工具读取.agents/rules/dev-tooling.md；文档治理读取.agents/rules/documentation.md；OpenSpec 流程读取.agents/rules/openspec.md；i18n读取.agents/rules/i18n.md。

3. 分析和组织问题

对每个报告的问题：

按类型分类：

• bug — 行为不正确，代码与规范不匹配
• missing — 功能不完整，实现存在缺口
• ux — 用户体验改进，无需修改规范
• test-gap — 仅缺少测试覆盖

按规范影响分类：

级别	定义	操作
implementation	规范正确，代码有误	仅修复代码
spec-level	需求缺失/不完整/已变更	先更新规范，再修复
internal	无用户可观察变更但涉及可执行行为	修复代码，优先单元测试
governance	文档命名、规范文本、OpenSpec 记录、审查规则说明等项目治理问题	修复文档/规范，使用治理验证

关联问题分组 — 同一根因 → 合并为单个任务，包含多个验证点。

同时记录 OpenSpec 门槛判断：

• openspec-existing：说明关联的活跃变更、关联原因和需要更新的tasks.md/specs/范围。
• openspec-new：说明为什么不能放入现有活跃变更，以及新变更的最小范围。
• direct-fix：说明为什么不值得沉淀为 OpenSpec，以及采用的验证方式。
• no-change：说明不修改的原因和未来触发条件。

4. 更新增量规范（仅限 OpenSpec 路径的规范级别问题）

对于规范级别的问题，在记录任务前先更新规范：

1. 确定受影响的能力：specs/<capability>/spec.md
2. 执行增量操作：

<!-- ADDED: 新增需求 -->
### Requirement: 父级选择器循环引用防护
系统应在父级选择器中禁用当前菜单及其所有子菜单，
以防止循环引用。

#### Scenario: 编辑包含子菜单的菜单
WHEN 用户编辑一个包含子菜单的菜单
THEN 父级选择器应禁用当前菜单及所有子菜单

<!-- MODIFIED: 变更需求（包含完整原始块） -->
### Requirement: 导入错误处理
系统应在导入失败时显示错误信息。
**MODIFIED:** 错误信息应包含行号、字段名和校验失败原因。

<!-- REMOVED: 废弃需求 -->
### Requirement: 旧版导入格式
系统应支持旧版 CSV 格式。
**REMOVED:** 此格式不再支持。
**迁移方案：** 使用带表头行的新版 CSV 格式。

5. 将任务列表写入 tasks.md（仅限 OpenSpec 路径）

在tasks.md中追加反馈章节：

## Feedback

- [ ] **FB-1**: 父级选择器在菜单编辑中允许循环引用
- [ ] **FB-2**: 导入错误信息缺少行号和字段详情
- [ ] **FB-3**: 重置密码功能缺少测试覆盖

编号： 顺序使用FB-1、FB-2等。如果章节已存在，从最后编号继续。

每个任务一行 — 不使用子字段。分析在修复阶段进行。

写入前说明分诊结论和拟写入任务；只有在多个目标变更归属不清、任务范围存在高风险取舍或用户明确要求确认时，才暂停等待用户选择。

如果处理路径为direct-fix或no-change，跳过本步骤，并在最终结果中记录未更新tasks.md的原因。

验证覆盖规划（内部）：

• 用户可观察的行为变更 → 需要 E2E 测试
• 源码插件专属的用户可观察行为变更 → E2E 放在apps/lina-plugins/<plugin-id>/hack/tests/e2e/，专属 POM/helper 放在插件同级hack/tests/pages/、hack/tests/support/
• 后端逻辑、服务层、工具函数、缓存、权限、数据权限、插件桥接等内部可执行行为变更 → 需要单元测试或更低成本的自动化测试
• 纯项目治理类反馈 → 不为兜底新增单元测试或 E2E 测试，改用openspec validate、静态扫描、文件存在性检查、格式检查或审查结论
• 场景合适时优先在现有 TC 或现有测试中添加子断言

6. 执行修复（循环）

对每个 OpenSpec 反馈任务或直接修复项：

a. 告知： ## 修复 FB-X: <问题标题>或## 直接修复: <问题标题>

b. 调查 — 读取源文件，确认根因

c. 实现 — 最小化、聚焦的修复，遵循现有模式

d. 编写/更新测试或治理验证 — 行为修复按AGENTS.md选择单元测试或lina-e2e测试；项目治理类反馈使用规范校验、静态扫描或文件检查

e. 评估影响范围（必须）

实现后，识别回归风险：

变更类型	关联验证
后端 API 端点	所有调用该端点的前端页面
共享组件/工具函数	所有使用该组件的页面
数据库 Schema/DAO	所有读写受影响表的功能
认证/权限	所有认证测试 + 权限相关测试
页面特定	该模块目录下的所有测试
项目治理文档/规范	openspec validate、静态扫描、文件存在性检查或格式检查

# 示例：查找用户 API 变更的相关测试，包含宿主和源码插件自有 E2E
git grep -l "api/user" -- 'hack/tests/e2e/**/TC*.ts' 'apps/lina-plugins/**/TC*.ts'

告知：

### FB-X 影响分析
- 修改文件：apps/lina-core/internal/controller/menu.go
- 受影响模块：菜单管理
- 回归测试：hack/tests/e2e/iam/menu/TC001-menu-crud.ts, hack/tests/e2e/iam/menu/TC002-auth-menu.ts

同时必须记录：

• i18n影响：涉及时列出资源归属、目标语言、验证命令；不涉及时写明无运行时行为、前端 UI、API 文档源文本、插件清单或语言包资源影响。
• 缓存一致性影响：涉及时说明权威数据源、失效机制和分布式策略；不涉及时写明无缓存影响。
• 数据权限影响：涉及时说明读写边界和验证；不涉及时写明无数据操作影响。
• 开发工具跨平台影响：涉及时说明验证；不涉及时写明无开发工具或脚本影响。
• 外部规则加载影响：列出已按AGENTS.md命中的.agents/rules/*.md；若某规则域确认无影响，写明无影响判断。命中规则但未读取对应规则文件时，不得标记该反馈完成。

f. 验证（标记完成前必须执行）

1. 运行此任务新增/更新的测试或治理验证 → 必须通过
2. 运行所有已识别的回归测试或回归验证 → 必须通过
3. OpenSpec 路径仅在以上都通过后，才能在tasks.md中将任务标记为[x]；直接修复路径不修改tasks.md

如果回归测试失败：

• 如果与当前变更相关，直接修复
• 如果是独立问题，重新执行反馈分诊；达到 OpenSpec 门槛才作为新的 FB 任务添加，否则按直接修复或后续风险报告处理

g. 运行审查 — 完成后必须调用lina-review技能

7. 综合验证

所有修复完成后：

1. 汇总所有任务的回归测试
2. 一次性运行全部测试
3. 报告：

### 综合验证结果
- 总测试数：N
- 通过：N
- 失败：N（列出详情）
- 回归测试：全部通过 ✓ / X 个失败

如果存在失败 → 重新执行反馈分诊，必要时添加新的 FB 任务，回到步骤 6。

8. 报告完成

## 反馈完成

**处理路径：** direct-fix / openspec-existing / openspec-new / no-change
**变更：** <名称>
**OpenSpec 记录：** 已写入 <change>/tasks.md / 已新建 <change> / 未记录（原因：<原因>）
**报告问题数：** X
**已修复问题数：** Y/X
**新增测试：** Z 个测试用例 / 子断言
**回归测试：** 跨 N 个模块运行 R 个测试
**验证结果：** 全部通过 / 剩余 N 个问题

### 本次已修复
- [x] FB-1: <标题> ✓（测试：TC001a | 回归：iam/menu TC001, TC002 ✓）
- [x] FB-2: <标题> ✓（测试：已有覆盖 | 回归：auth TC003 ✓）

### 剩余（如有）
- [ ] FB-3: <标题> — 被 <原因> 阻塞

边界情况

场景	处理方式
单个问题	先分诊；达到 OpenSpec 门槛才写入变更
仅缺少测试用例	分类为 test-gap；若只是局部覆盖缺口可直接补测试，不强制写入 OpenSpec
修复后发现更多问题	重新分诊；达到门槛才添加 FB 任务
"Bug"实为功能请求	重新分类为 spec-level；达到 OpenSpec 门槛时先更新规范
存在活跃变更但反馈不相关	不强行追加；按direct-fix、openspec-new或no-change处理
轻量文档、技能或治理措辞改进	通常走direct-fix；若会改变 OpenSpec 工作流或团队治理门禁，必须同步规则文件并重新判断记录门槛
测试不可行（时序、基础设施）	通过完整测试套件验证，在摘要中说明原因
多轮反馈	每轮先分诊；同一目标变更中的任务在单个 Feedback 章节中顺序编号

护栏规则

• 先判断 OpenSpec 门槛 — 不因存在活跃变更就自动追加，也不为低价值反馈新建变更
• 达到门槛才记录 — openspec-existing和openspec-new路径需要先记录再修复，direct-fix路径需要先说明分诊和根因再修复
• 规范级别问题先更新规范 — OpenSpec 路径中先更新增量规范
• 减少不必要确认 — AI 自主决定记录门槛；仅在归属或方案取舍确实不清时询问用户
• 最小化修复 — 不进行问题范围之外的重构
• 用户可见的修复需要测试 — 除非技术上不可行，否则无例外
• 测试未通过不得标记完成 — 仅在测试通过后标记[x]
• 必须进行影响分析 — 每个修复都需要识别回归测试
• 回归失败阻塞完成 — 必须在标记完成前解决
• 实时更新 tasks.md — 仅 OpenSpec 路径在验证后立即标记完成
• 匹配文件语言 — 使用目标文件中已有内容的相同语言