Lina Feedback

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 的常见信号：

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

通常不进入 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，读取目标变更上下文：

# 查找目标模块目录内的 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 — 仅缺少测试覆盖

按规范影响分类：

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

同时记录 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 或现有测试中添加子断言