docs: 规则与技能迁入 .agents/,并接入决策笔记

- roles/ 与 skills/ 迁移到 .agents/ 下,AGENTS.md 引用同步
- 收录 8 篇决策笔记到 .agents/notes/
- .rgignore 排除 archived 历史快照
This commit is contained in:
2026-11-18 15:01:05 +08:00
parent eb3da2e74a
commit 27ddf8be5a
17 changed files with 369 additions and 7 deletions
@@ -0,0 +1,43 @@
# Agent Note: 行级数据隔离由租户拦截器统一注入,业务代码不写 created_by
Status: implemented
## Problem
多租户表全靠手写 `WHERE created_by = #{当前用户}`。漏一处就是一个越权读:查询单条记录时不带条件,
别人的任务、报告、残片就会被正主之外的请求读到,而且这类缺口在单模块测试里看不出来——测试用的都是同一个
登录用户。逐个 mapper 补条件也不可行:新增查询随时会漏,评审也盯不住。
## Decision
持久层统一挂 `TenantLineInnerInterceptor`(`MybatisPlusConfig`),在 SELECT / UPDATE / DELETE 上自动追加
`WHERE created_by = #{当前用户}`,业务代码与 mapper XML 一律不写这个条件。
- 租户列固定为 `created_by`,取值优先 `TenantContext` 里显式声明的身份(后台线程:AI 任务、定时收敛),
没有就走 `StpUtil.getLoginIdAsString()`。
- 免过滤表白名单 `EXCLUDE_TABLES`:`user`、`flyway_schema_history`、`databasechangelog`、
`databasechangeloglock`、`ai_usage_records`。加表进白名单等于放弃该表的隔离,必须附带「为什么这张表不是租户表」。
- 拦截器注册顺序固定为「多租户 → 分页」。分页的 `count` 语句从当前已处理的 SQL 派生,顺序颠倒会让 `total`
把其他用户的行也算进去——`records` 仍然正确,只有总数错,靠肉眼几乎发现不了。`MybatisPlusConfigTest`
守住这个顺序。
## Alternatives considered
- **每个 mapper 手写 `created_by` 条件** — 最直白,也不引入 SQL 改写。放弃的原因是覆盖面靠人记忆:所有查询
(含以后新增的)都要记得加,漏一处就是一个静默的越权读,而这类错误不会让任何测试变红。
- **Service 层统一用 AOP 在方法入口校验归属** — 能在业务语义上给出更清楚的报错。但它只管「已取出的记录」,
集合查询(列表、分页、汇总)依然会在 SQL 层返回别人的行,等于把越权数据读进内存再挑出去。
## Consequences
- **收益**:新增查询默认就是安全的,越权读从「写测试才能发现」变成「默认不存在」。归属校验也顺带免费:
查不到别人的记录,自然返回空。
- **代价与已知上限**:所有绕过 SQL 的路径都不受保护——手写 JDBC、直接执行的原生 SQL、跨表 join 里别名的列
需要人工确认;免过滤表白名单是一处集中的风险点,改它等于改安全边界。出现「某接口查不到数据但库里明明有」
时,先查是不是白名单或 `TenantContext` 没设置,而不是去业务代码里找条件。
## Verification
- 配置与顺序:`lpt-be/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java`,
`MybatisPlusConfigTest` 断言「租户拦截器先于分页拦截器」。
- 白名单:同一个类里的 `EXCLUDE_TABLES`,静默新增表项即改动安全边界。
@@ -0,0 +1,47 @@
# Agent Note: AI 用量口径——null 不等于 0,计价在 lpt-ai 侧冻结
Status: implemented
## Problem
lpt-ai 的调用会把 token 用量报回 lpt-be,供白名单管理员看总量与费用。这里有三个容易写错、写错还不会报错的地方:
1. 上游有时候根本不返回 `usage`。如果把「没上报」记成 0,用量面板会把一批**未知消耗**显示成「这几次调用没花钱」,
账单与面板永远对不上,而且没人能发现差了。
2. 价格会变。若聚合时按当期价目回算历史,改一次价历史账全部重写,月度对账失去意义。
3. `ai_usage_records` 里还有 `/fetch-title` 这类不消耗 LLM 的记录,混进统计会把「调用次数」和「模型成本」搅在一起。
## Decision
- **`null` 与 `0` 严格区分**:`prompt_tokens` / `completion_tokens` 等列为 `NULL` 表示上游未上报,`0` 表示上游
明确上报为 0。不得用 0 顶替 null。`unreported_usage_calls` 正是靠这个区分统计出来的。
- **计价在 lpt-ai 侧冻结**:`cost_usd` 在任务结算时按当期价目算好随记录落库,lpt-be 只做聚合与汇率换算
(`lpt.ai-usage.usd-to-cny`),改价不重写历史账。
- **统计口径只看 `is_llm_call = 1`**:不消耗 LLM 的调用照常落库(用于调用量排查),但不进用量面板。
- **`user_id` 只是分组维度,不是租户列**:本表在 `EXCLUDE_TABLES` 中,`user_id` 用于按用户分组与筛选;
若改成租户过滤,管理员只能看到自己触发的调用,面板等于永远是空的。
- **上报幂等交给出库方**:`POST /internal/ai-usage/records` 以 `record_id` 唯一索引去重,因此「推送成功但响应
丢失」的重复推送是安全的;失败重试由 lpt-ai 侧 outbox 负责,4xx 属确定性拒绝,丢弃该批并计数,不无限重试。
## Alternatives considered
- **在 lpt-be 侧按当期价目聚合时现算成本** — 少存一列,改价立刻全局生效。放弃是因为它把历史账变成了易变量:
一次调价会让过去几个月的报表同时变化,月初对账没有稳定基线,而账本该是只读的。
- **把「未上报」压成 0,只留一个总数** — 面板实现最简单,表结构也少一列。放弃是因为它抹掉了「我们不知道花了多少」
这个事实:额度异常时无法区分「真的没用量」和「上游没给 usage」。
- **让 lpt-be 反查 lpt-ai 面板取历史用量** — 不用落库,也不必设计上报协议。但面板只是最近若干条的环形缓冲,
进程重启即丢,「长期账本」这个诉求直接落空。
## Consequences
- **收益**:用量面板的数字可以对账——已知消耗、未知消耗、非 LLM 调用分得开;改价不动历史。
- **代价与已知上限**:lpt-be 必须相信 lpt-ai 报来的 `cost_usd`,价目正确性完全取决于 lpt-ai 的 `admin/pricing.ts`
与节假日表(每年需更新)。出现「面板金额与上游账单对不上」时,先核 lpt-ai 的价目与峰谷窗口,再怀疑聚合逻辑。
## Verification
- 表结构与索引:`lpt-be/src/main/resources/db/migration/V20261010_4__add_ai_usage_records.sql`、
`V20261010_5__add_user_id_to_ai_usage_records.sql`。
- 口径与 null 处理:`src/main/resources/mapper/AiUsageRecordMapper.xml`(`is_llm_call = 1` 过滤、
`unreported_usage_calls` 用 `CASE WHEN prompt_tokens IS NULL`),`AiUsageServiceImpl` 的聚合。
- 白名单与令牌:`AiUsageProperties`、`WebMvcConfig` 对 `POST /internal/ai-usage/records` 的排除。
@@ -0,0 +1,50 @@
# Agent Note: 用量归属 mark 跟着请求走,路由信息不进 params
Status: implemented
## Problem
用量要能按用户切分,但 lpt-ai 不知道调用方是谁:它只收到一个 `POST /ai/tasks` 的请求体(`type` + `params`)。
在 lpt-be 侧「提交后再写回归属」也不成立——lpt-ai 可能比 lpt-be 的写回更早结算,形成归属与账目赛跑。
## Decision
归属标记由调用方带过来:`POST /ai/tasks` 接受**顶层**可选字段 `callerRef`(限 64 字符),lpt-be 的
`AiServiceClient` 填当前用户 id,lpt-ai 原样透传,结算时写进用量记录,lpt-be 落到 `user_id`。
三条硬约束,改动时必须同时守住:
1. **不放进 `params`** —— `params` 会喂给 prompt 模板,混进去等于把内部 id 塞进模型输入;
2. **不参与幂等键** —— 幂等键是 `type + params`,`callerRef` 进去会让同一份输入因调用方不同而重复调 LLM;
3. **不进 prompt** —— 它只是记账标记,不是上下文。
配套两条:
- **取不到身份就不带**:`currentCallerRef()` 拿不到登录态时返回 null,请求体里整个键都不写,这笔用量记为「未归属」。
绝不能因为取不到用户让 AI 调用失败。
- **复用已有任务沿用原 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上;复用方没有产生新 token,
也就不会有新的用量记录。
## Alternatives considered
- **lpt-be 提交任务后写回归属,等结算时再查** — 不用改 AI 侧协议。但它依赖「写回早于结算」的时序假设,
而任务是异步的,lpt-ai 完全可能先结算;一旦发生就是归属丢失或错挂,且没有信号提示。
- **把 `callerRef` 塞进 `params` 顺带透传** — 不必新增顶层字段,实现最省事。放弃是因为 `params` 同时是 prompt
模板输入和幂等键的组成部分,一个记账字段混进去会同时污染模型输入和去重语义。
- **让 lpt-ai 反查 lpt-be 拿归属** — 归属只在一处定义。但那是服务间反向依赖,AI 服务要为此持有一个 lpt-be 的
查询凭据与失败降级路径,为一个记账字段引入的耦合远大于收益。
## Consequences
- **收益**:归属在 LLM 调用之前就已确定,没有「上报先到、归属还没写回」的竞态;AI 服务不需要知道 lpt-be 的任何
用户概念,只透传一个不透明字符串。
- **代价与已知上限**:归属完全依赖调用方老实带上,`callerRef` 是自由字符串——lpt-ai 不做校验也不该做校验,
伪造与错填由 lpt-be 侧负责(它填的是 `StpUtil` 里取到的登录 id)。未归属记录必须作为单独一行存在,
不能为了报表好看塞给某个用户。
## Verification
- 调用方:`src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java` 的 `currentCallerRef()`
与请求体组装(顶层 `callerRef`),`AiServiceClientAttributionTest`。
- 承接方:lpt-ai `src/routes/ai.ts` 与 `src/task-queue.ts` 的 `callerRef` 透传,报表侧
`breakdown?groupBy=user`(未归属 `key` 为 null、`label` 为「未归属」)。
@@ -0,0 +1,56 @@
# Agent Note: 自由回忆只保存当前导图与本次资料
Status: implemented
## Problem
自由回忆需要持续保存当前输入、提供本次资料,并允许下次接着最后的导图回忆。为每次自动保存维护内容历史,会把编辑、恢复、原文查看和 AI 请求都绑定到版本模型。业务只要求每次回忆的最终内容;不兼容的回忆数据允许一次性删除。
## Decision
每次回忆的 `RecallDocument` 只保存当前 `detail.expression` 和单一 `reference` 来源集合。自动保存覆盖当前导图,不保存中间导图、表达历史、资料历史或对应的版本字段。不同回忆仍是独立记录,各自保留最后保存的导图;“只保留当前内容”不表示整个账号只能有一条回忆记录。
本次资料在创建回忆时取一次,来源不可访问时原地清除正文及依赖它的 AI 结果。下一次创建回忆重新取材。DTO 名称 `ReferenceSnapshot` 只表示本次唯一来源集合,不包含版本号、历史列表或切换入口;普通查询和保存不会生成另一份资料。
`writeToken` 是覆盖写入保护:成功写入替换当前随机令牌,不维护递增内容编号或旧令牌列表。草稿只保留最近一次写入的请求编号与摘要,响应丢失时允许同一请求重试。其他业务收据只保存标识和摘要,不保存历史正文。
创建回忆时,服务端按当前用户、规范化标签集合及并集/交集方式选择最近已结束记录。标签顺序、空格或大小写不构成不同范围,组合方式不同则范围不同。新回忆复制最后导图的文字、节点标识及结构,清空此前帮助标记;资料、提示请求和累计耗时从本次重新建立。没有可用记录时初始化空白根节点。未完成草稿通过恢复接口编辑。
资料目录由 `GET /review/recalls/{num}/references` 分页返回标题与摘要,正文由同一路径下的 `/sources/{sourceId}` 获取。详情只返回资料汇总,避免每次草稿上传都携带全量正文。资料接口不接受版本参数。
AI 执行期间可以暂存一份提交输入,以便重启接手和结果引用校验;终态成功写回后清除 `params_json`,不能据此建立可回看的编辑过程。成功结果保留提示/查漏内容及必要请求信息,不替换当前导图。已显示帮助或原文的事实单独保留,供 AI 区分资料与已知帮助;这些事实不带表达版本或中间导图。具体输出与重试规则归属[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)。
## 删除范围与同步升级
`V20261116_1__replace_recall_storage.sql` 删除 `review_recall_records`,重建自由回忆的当前记录、请求、收据与所有者锁表,清除 `RECALL_COMPARE`、`TAG_RECALL_COMPARE`、`RECALL_HINT` 和 `RECALL_CHECK` 的既存任务。迁移不回填不兼容的表达历史与资料历史,已执行的历史 Flyway 脚本保持不变。
任务标准导图 `review_standard_mind_maps` 与标签导图 `review_tag_mind_maps` 保留,`StartTask` 的生成和编辑能力保留。被移除的是依赖旧对比记录表的查询、写入、统计和浏览链路,不能重新从旧任务类型写入该表。
表达式与提示结果增加字段后,旧版 `document_json` 不做读取兼容:`V20261118_1__clear_incompatible_recall_data.sql` 清空既有回忆、回忆请求/收据与回忆 AI 任务;运行中遇到无法解析的残留行直接逻辑删除并返回 `STORED_DATA_INVALID`,不保留、不隐藏。旧格式 AI 结果读取失败时按“旧版本格式,请重新请求”展示,不再冒充核验失败。
前端、后端与 AI 服务需要在同一环境同步升级;内容协议没有旧形状兼容适配。技术协议标识、模型名和计价信息保留,它们不表示用户内容版本。
## 关联记录与归属
本篇维护当前内容存储、范围匹配、写入保护、临时 AI 输入和删除迁移。[前端工作区决策](../../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-16-current-recall-workspace.md)维护入口与交互,[AI 协议决策](../../../../../lpt-ai/.agents/notes/implemented/architecture/2026-11-16-recall-strict-protocol.md)维护严格输出和调用预算。三篇部分相关,分别保留;[租户隔离](2026-05-27-tenant-line-row-isolation.md)和[计费规则](2026-10-10-ai-usage-accounting-rules.md)继续维护各自决定。
## Alternatives considered
- 只隐藏编号和历史入口:可以复用已有异步绑定,改动面较小;但后端仍保存编辑过程,与只保留当前内容的业务要求冲突,因此删除整个内容版本模型。
- 把不兼容回忆回填为当前结构:能保留个人历史;但需要维护旧格式转换与历史引用,业务已允许删除这些数据,因此使用一次性清理迁移。
- 无写入保护地覆盖当前图:实现更短,也没有内容版本;但两个页面可能静默覆盖彼此输入,因此使用单个随机写入令牌与请求幂等控制。
## Consequences
覆盖保存把正文存储限制在每次回忆的一份当前内容,写入保护继续防止多页面静默覆盖。代价是无法恢复某一步编辑,也不能在本次回忆里刷新或切换资料历史;写入令牌与幂等摘要只能解决请求冲突,不能提供内容回滚。
删除迁移会清除既存对比记录和不兼容的自由回忆记录。保留任务标准导图和标签导图不意味着保留依赖这些图的旧回忆对比记录。代码回退不能还原已删除内容,发布时需要明确接受这个数据结果。
若业务以后确实需要编辑回滚、回忆内更新资料或长期保留请求输入,必须重新评估存储与清理规则;不得以恢复编号字段或长期保留 `params_json` 的方式隐式引入历史。
## Verification
- `ReviewRecallServiceIntegrationTest` 校验多次覆盖后先前正文不再落盘、同范围自动带入、范围差异、租户隔离、资料分页,以及 AI 终态清除临时输入。
- `ReviewRecallControllerIntegrationTest` 校验无版本 DTO、原文读取与旧请求拒绝;`RecallAiResultValidatorTest` 校验引用是否确实来自本次输入。异步结果不能覆盖后续编辑由服务集成测试验证。
- `RecallStorageMigrationTest` 验证重建存储并删除旧记录、保留任务标准导图和标签导图。迁移在 H2 的 MySQL 模式执行;`MigrationIndexKeyLengthTest` 额外复算 InnoDB 索引键长度,不能替代真实 MySQL 的 DDL 验证。
- 使用 JDK 17 运行 `./mvnw clean test`。
@@ -0,0 +1,39 @@
# Agent Note: 自由回忆记录实际用时与有效时间
Status: implemented
## Problem
自由回忆页需要同时显示“实际用时”和“有效时间”,并按在场段与有交互活动分别累计。记录原先只有 `activeDurationMs`(有效时间)一个累计值,页面既拿不到“服务端已确认 + 本段未上传”的实时总量,也没有实际用时可展示。
直接用 `createdAt → endedAt` 推实际用时实现最省,但草稿允许跨天恢复,会把离开的时间全部算进去。实际用时只用于单条回忆展示,不参与任务统计,没有必要像 `active_duration_ms` 那样为聚合新增数据库列。
## Decision
回忆计时同时累计两个值,契约与页面口径详见[前端工作区决策](../../../../../lpt-fe/.agents/notes/implemented/feature/2026-11-16-recall-time-metrics-and-break.md):
- `Timing` 增加 `segmentActualMs`,与 `segmentActiveMs` 一样是当前编辑段的累计值,单调递增。缺省时取 `segmentActiveMs` 与已确认实际用时的较大值,滚动发布中的旧前端仍可保存并保持单调。
- `RecallDocument` 增加 `acceptedSegmentActualMs`,与 `acceptedSegmentMs` 一同在草稿/结束时累加;`resume` 把两者都归零,开启新编辑段。
- `RecallDetail` / `RecallSummary` 增加可空 `actualDurationMs`。旧记录读不到该字段时为 `null`,不回填;旧草稿第一次携带实际用时后从 0 开始累计。
- 服务端只校验 `0 <= segmentActiveMs <= segmentActualMs`,且两者都不超过本次编辑段墙钟(保留 5 秒容差)。闲置截断和休息冻结由客户端计时器决定,服务端不推断。
- 实际用时只存在回忆文档 JSON 中,不新增 `actual_duration_ms` 列:它不参与 `sumTaskDuration` 聚合,列表与回看都从文档读取。以后确实需要聚合再加列。
- 每次保存成功后,前端把本次上传的段值记为已确认基线,展示值 = 服务端累计 + 未确认增量;恢复草稿重置基线。
## Alternatives considered
- **用 `createdAt → endedAt` 作为实际用时**:不需要改契约;但跨天草稿会把离开时间全算进去,显示几十小时,因此否掉。
- **新增 `actual_duration_ms` 列**:查询与聚合更直接;但当前没有按实际用时聚合的需求,SQL 迁移和冗余同步的代价换不来收益,因此只存文档 JSON。
- **客户端只上报增量**:服务端无需保存 accepted 值;但请求丢失重试、幂等重放和并发写入会让增量边界不可验证,因此沿用累计值 + 服务端 accepted 基线。
- **完全由服务端按墙钟推算实际用时**:不需要客户端计时;但服务端不知道标签页隐藏、休息和闲置,会把整夜算进去,因此保留客户端段计时,服务端只做上限校验。
## Consequences
实际用时的精度依赖前端时钟与闲置窗口,服务端只能拒绝超过编辑段墙钟的值,不能识别一段“5 分钟宽限”是否合理。换设备或清缓存不会丢失已上传的累计值,但未上传的当前段本来就不属于服务端记录。
旧记录没有 `actualDurationMs` 时,前端只显示有效时间,不显示错误的 0。服务端与前端需要同批发布;旧前端缺少 `segmentActualMs` 时按有效时间处理,旧记录不会被补算。
## Verification
- `ReviewRecallServiceIntegrationTest#actualDurationAccumulatesAcrossSegmentsAndNeverDropsBelowActive` 校验跨段累加、恢复归零、旧载荷兼容、实际小于有效与实际超过墙钟被拒绝。
- `ReviewRecallControllerIntegrationTest` 校验接口序列化与既有行为不回退。
- 使用 JDK 17 运行 `./mvnw clean test`。
@@ -0,0 +1,38 @@
# Agent Note: 自由回忆提示锚点、表达式配色与核验原因
Status: implemented
## Problem
提示结果缺少挂载位置:`HintNode.parentId` 只描述提示内部,前端只能挂到根节点。表达式也没有配色字段,用户改色无法持久化。同时 BE 对空提示、判定引文和精确偏移的规则比 AI 服务更严,正常结果可能被判为 `INVALID_AI_RESULT`;失败原因被压缩成一句泛化文案,用户不知道哪条规则没过。`claimPendingTasks()` 每次扫描都执行 RUNNING 回收,条件 UPDATE 在无匹配行时也产生大量日志。
## Decision
- `HintItem` 增加 `anchorNodeId`。LEAF/TREE 必须引用本次提交表达式中的真实节点(根节点 id 也可);KEYWORD/QUESTION 必须为 null。LEAF 恰好 1 个节点;TREE 继续校验单根、无环、≤5 节点。
- 表达式节点增加可选 `style {background, color}`,只接受两个 `#RRGGBB`。配色是展示信息:`RecallAiService.bounded` 在构造 AI 输入时剥掉 style,模型契约保持不变;`carryContent` 复制到新回忆时保留用户显式配色,但清空提示 provenance。
- 核验范围此后收窄:结构、提示锚点、LEAF/TREE 形状先由 lpt-ai 校验,BE 侧只复核引文是否真的来自本次输入,见[校验归属决策](2026-11-18-recall-validation-ownership.md)。
- 校验失败返回可核验的原因(结构与字段/分析判定/提示结构/查漏依据/表达依据/分析覆盖等)。`RecallAiFailure.fromException` 保留校验器/客户端的固定安全文案;`RecallAiService.fail` 使用它;`RecallAiClient.remoteFailure` 只从 AI 服务的固定阶段标记中提取原因,不读取供应商原文。
- `claimPendingTasks()` 的回收最多每 60 秒执行一次;扫描仍为 3 秒,抢占与结果回写不变,只有真正回收任务时打日志。
## Alternatives considered
- **继续挂根节点**:无需契约变更;但树/叶的结构关系无法落到用户导图,因此增加锚点。
- **不持久化配色,只做来源默认色**:实现最小;但用户无法按自己的习惯整理视觉,因此增加 style 字段并剥离 AI 输入。
- **把判定引文限制成只能本单位**:语义更整齐;但 AI 服务允许跨单位上下文,模型正常输出会被 BE 误杀,因此对齐为 EXCLUDED 必须有本单位引文。
- **保留泛化错误**:实现简单;但用户无法定位规则,因此返回固定阶段原因。
- **每次扫描都回收任务**:恢复最快;但正常运行时只会制造 SQL 噪声,因此 60 秒节流。
## Consequences
锚点让叶/树能挂到用户已有结构下,但 AI 等待期间用户删除锚点时会回退根节点;前端需要显示这个回退。
配色进入表达式文档,但没有新增数据库列;新格式记录未选色时按来源默认色或普通节点显示。上一版本保存的文档缺少新增 record 组件,按破坏性变更处理:迁移清空既有回忆,运行中遇到无法解析的残留行直接逻辑删除并返回 `STORED_DATA_INVALID`,不增加读取兼容分支。AI 输入剥离 style 后,模型无法感知用户配色,这是刻意的展示/语义分离。
空提示和跨单位判定引文不再被误判为失败;真正不合规的结果仍失败,并返回具体类别。
回收节流最多延迟约一分钟发现崩溃任务;这是可接受的恢复时间。
## Verification
- `RecallAiResultValidatorTest` 现只覆盖引用一致性与结构错乱 fail-closed,结构类断言由 lpt-ai 的 `recall.test.ts` 承担(见[校验归属决策](2026-11-18-recall-validation-ownership.md))。
- `ReviewRecallServiceIntegrationTest` 覆盖 style 合法/非法、实际用时与有效时间的既有累加不回退。
- `AiTaskServiceImplTest#claimPendingTasks_reclaimsStuckRowsAtMostOncePerMinute` 覆盖回收节流。
- `RecallAiClientTest` 保持错误分类与远程清理行为;`ReviewRecallControllerIntegrationTest` 覆盖接口序列化。
- 使用 JDK 17 运行 `./mvnw clean test`。
@@ -0,0 +1,40 @@
# Agent Note: 记忆回忆链路的校验归属与严格解析收窄
Status: implemented
## Problem
回忆链路的 JSON 出入口原先用一份自建严格 ObjectMapper 覆盖了三个方向:前端请求、落盘的 `document_json`、lpt-ai 返回的 AI 结果。这份严格同时打开 `FAIL_ON_UNKNOWN_PROPERTIES` 与 `FAIL_ON_MISSING_CREATOR_PROPERTIES`,后者在 record 上对**每个构造器组件**生效(`PropertyValueBuffer._findMissing` 在 `isRequired()` 之后立即检查该 feature),因此可空组件也变成必填。
后果是一个正常主流程被整单拒绝:`ExpressionNode.style` 在契约里是可选的(前端类型 `style?: NodeStyle | null`,`fromRecallElixirNode` 只在用户显式选色时才写),而「用 AI 提示把节点挂到导图」产生的节点不带 `style`。只要导图里有一个未配色的非根节点,`PUT /review/recalls/{num}/draft` 与 `POST .../end` 都返回 `400 INVALID_INPUT`「这些内容没能读取」。这个问题只有前端真实请求会触发——Java 测试用 record 序列化生成 body,`style` 永远以 `null` 出现而不是缺席,因此全部单测是绿的。
进一步的审计发现:`RecallAiResultValidator` 把 lpt-ai 的 `normalizeRecallResult` 又重新实现了一遍(结构、条数上限、字段枚举、提示树形状、锚点存在性、分析状态归一、长度上限),而且两套规则已经分叉(限制说明 lpt-ai 上限 5 条、后端 12 条;exclusion 引文的后端判定比 AI 服务更严)。2026-11-16 那次「正常结果被判 `INVALID_AI_RESULT`」的事故正是分叉的直接代价。
## Decision
校验按「谁产出、谁保证」划分,同一个规则不写两遍。
- **外部请求(HTTP body)**:`RecallJson.readInput` 只拒绝未知字段、标量强转与浮点转整,不再要求可选字段必须出现。必填语义由 `ReviewRecallService.validateExpression` / `timing` / `ReviewRecallStore.guard` 承担,它们能给出比 Jackson 更具体的理由。
- **落盘读取(`document_json` / AI 结果回读)**:`RecallJson.readStored` 不做结构限制,形状由写入方保证;读不出来即视为数据损坏。`ReviewRecallStore.load` 与 `RecallPrivacyService.readable` 的 catch 从 `IllegalStateException` 扩到 `IllegalStateException | NullPointerException | ClassCastException`,继续维持「损坏即删行」而不静默隐藏——但仍不捕获任意的 `RuntimeException`,数据库与事务异常必须照常上抛,不能因为一次读失败就删掉用户数据。
- **AI 结果**:结构、条数、枚举、提示树形状、锚点、分析覆盖全部归 lpt-ai 的 `normalizeRecallResult`。后端 `RecallAiResultValidator` 只保留一条不变量:模型声称的引文与表达依据,必须能在本次输入原文里按偏移逐字取回(含不切开代理对)。本服务是落库与展示的边界,这条线必须自己持有,不能靠上游自证。
- **序列化配置不动**:`RecallJson.write` 同时产出幂等摘要(`receipt_key` / `payload_hash`),任何序列化 feature、Module 或字段顺序的变动都会让既有收据失配、把重试判成 `REQUEST_ID_CONFLICT`。因此本轮只调整反序列化侧,并在类注释里写明这条约束。
## Alternatives considered
- **继续让后端做全套 AI 结果校验**:后端确实是落库边界,多一层防线看起来更保险;但两套规则已经分叉并误杀过正常结果,维护成本随每次协议调整翻倍,因此只保留引文一致性这条不可替代的复核,其余交给产出方。
- **整体删掉 `RecallAiResultValidator`,完全信任 lpt-ai**:代码与测试最少,最符合「各服务自证」;但 lpt-ai 的回归或部署漂移会让伪造引文直接进库并展示给用户,而「引文确实来自本次资料」正是这套功能对用户的核心承诺,因此保留最小复核。
- **在前端补 `style: null` 了事**:一行改动即可让当前页面不再 400;但契约里 `style` 本来就是可选的,旧版本地草稿(`recallCache` 里的 `pendingSave`)与任何第三方客户端仍会被打回,服务端「少一个 key 就拒」的陷阱也还在,因此改在接收侧。
- **保留 `FAIL_ON_MISSING_CREATOR_PROPERTIES`,改用 `@JsonProperty(required = true)` 标注必填字段**:能精确表达必填;但实测 Jackson 2.15 下该 feature 仍会否决未被 `required` 标注的缺席组件(`required=false` 也不生效),要真正生效必须去掉这个 feature,因此等价于本方案,只是多一层注解。
## Consequences
前端按 TS 类型省略可选字段不再被拒,`PUT /draft` 与 `/end` 对真实页面恢复可用;后端不再因为协议细微差异误杀 AI 结果,`INVALID_AI_RESULT` 现在只表示「引文不可回溯」这一种情况。
代价是:AI 结果的条数与枚举约束在后端不再有第二道检查,若 lpt-ai 的解析器回归,后端只能靠引文一致性挡掉一部分问题;`RecallAiResultValidatorTest` 的覆盖面相应收窄,原来的结构类断言改为引用 lpt-ai 的 `recall.test.ts`。存储侧的损坏判定从「序列化异常」扩到「形状类异常」,能覆盖字段缺失导致的 `NullPointerException` 与类型不符导致的 `ClassCastException`;数据库与事务异常仍会上抛,排查时从日志里的 `recallNum` 与「旧版本或不兼容文档已删除」入手区分两种情况。
## Verification
- `ReviewRecallControllerIntegrationTest#draftAcceptsOmittedOptionalStyleAndRejectsMissingRequiredFields` 用**手写 JSON 字符串**(不经 Java 序列化)验证:子节点省略 `style` 返回 200;缺 `schemaVersion`、缺节点 `id`、缺 `provenance`、出现未知字段 `carryFrom` 仍返回 400 `INVALID_INPUT`。
- `RecallAiResultValidatorTest` 保留伪造引文、未知 `unitId`、切开代理对、表达依据越界、提示引文伪造与结构错乱 fail-closed 的用例。
- `ReviewRecallServiceIntegrationTest#legacyDocumentsAreDeletedInsteadOfSkippedAndNewRecallStartsEmpty` 改为写入非法 JSON 来构造损坏文档,继续验证「损坏即删除并返回 `STORED_DATA_INVALID`」。
- 使用 JDK 17 运行 `./mvnw test`,全量 602 个用例通过。
@@ -0,0 +1,44 @@
# Agent Note: 出包环境由分支绑定,不靠参数切换
Status: implemented
## Problem
同一份代码要出 dev 与 prod 两个包。如果只靠流水线参数(或本地配置)区分环境,那么「用 dev 的代码发到
prod 的 namespace」只是一次手滑——而这类手滑的代价最大:库表迁移已经跑上去、前端已经指到生产后端,
回滚时数据形状已经不匹配。
## Decision
一个分支对一个环境,绑定关系写进流水线第一步并**直接拒绝**不匹配的组合,而不是打印警告。
| 仓库 | dev 分支 | prod 分支 | 说明 |
|---|---|---|---|
| lpt-be / lpt-fe / lpt-ai | `dev` | `master` | `main`(lpt-ai)仅作历史冻结点,不再发版 |
| lpt-android | `dev` | `master` | 两个分支只差默认 API 地址,不参与 k8s 部署 |
| lpt-infra | `master` | `master` | 单分支,靠 `dev/` 与 `prod/` 目录区分清单 |
- 触发方式固定为 `workflow_dispatch` + 选择 `environment`,流水线首步校验「分支 ↔ 环境」,不匹配即 `exit 1`。
- 网关地址、registry 等推动参数全部来自流水线的环境分支开关;**禁止用 tag 触发部署**(tag 打出来就跟分支脱钩了)。
- 跨仓库同环境同批发:`dev` 配 `dev`、`master` 配 `master`。lpt-ai 的结果字段与 lpt-be 的读取形状是硬耦合,
跨环境出包会让旧版读取方**静默降级**,界面不报错。
## Alternatives considered
- **单分支 + 部署参数区分环境** — 不必维护两条长期分支,也少了合并这一步。放弃是因为环境成了「一次运行里的一个
字符串」:谁都能选错,代码里哪一行是生产配置也无从判断,出事后连「线上跑的是哪份代码」都要翻流水线记录才能答。
- **出包后打 tag,用 tag 决定环境** — 发布形态更接近常规 CI。但本项目的分支本身就是环境契约,再叠一层 tag 会让
两个事实源打架;且 tag 一旦从错误分支打出,校验分支就再也拦不住。
## Consequences
- **收益**:环境错配从一个「可能发生的事故」变成一个「跑不起来的流水线」;线上代码与分支一一对应,可以直接回答。
- **代价与已知上限**:每次上生产都要「`dev` 合并进 `master`」这一次显式动作,合并冲突要自己解;`dev` 上验证过的
东西与 `master` 上的形态之间隔了一次合并,必须同批升级关联仓库才不会错配。历史例外:lpt-ai 的 `main` 停在
冻结点 `7c751bf`,看见它在仓库列表里不代表还能发版。
## Verification
- 规则位置:`lpt-be/.gitea/workflows/deploy.yml`、`lpt-fe/.gitea/workflows/deploy.yml`、
`lpt-ai/.gitea/workflows/deploy.yml` 的 `Validate branch ↔ environment` 首步。
- 清单分区:`lpt-infra/dev/` 与 `lpt-infra/prod/`。
+24
View File
@@ -0,0 +1,24 @@
# AI 集成
- **功能**:约束学习引导与 AI 异步生成链路的实现方式。
- **何时用**:接入或改动 AI 相关功能、新增后台任务、处理生成类能力时。
## 学习引导(复习-06)
一次引导是一次**复习行为**,有自己的记录实体 `review_guidance_conversations`:
- 产出的知识碎片以它作为**记录上下文**(`context_type=REVIEW`),默认内容归属为被引导概念所属任务,并带 `FROM_GUIDANCE` 系统标记。
- 复习耗时记在会话行上(与回忆对比同一口径)。
- 多轮对话复用 AI 异步任务:每轮提交一个 `GUIDANCE` 任务,前端轮询取回复;AI 回复会写回会话轮次,供下一轮作为上下文。
- **没有降级形态**:AI 不可用时该链路直接失败,前端把入口置为不可用。
## AI 异步链路(AI-02)
生成类能力(回忆对比、标准导图、报告草稿)不在请求线程里等 AI:
- 前端 `POST /ai/tasks` 提交,秒级拿到 `taskNum`;随后轮询 `GET /ai/tasks/{taskNum}` 直到 `SUCCEEDED`/`FAILED`。
- 结果写在 `ai_tasks.result_payload`,按 `taskNum` 可重复获取,刷新或离开页面都不丢。
- 同一用户 + 同一类型 + 同一目标已有进行中任务时复用该任务(AI-04),不重复生成。
- 执行器在 `ai-task-*` 线程池里跑;提交后立即投递,`@Scheduled` 兜底扫描接手投递失败或进程重启的任务。
- **后台线程必须显式声明身份**:执行线程没有 Web 上下文,租户拦截器与 `MetaObjectHandler` 字段自动填充都取不到当前用户。执行器用 `TenantContext.callAs(task.createdBy, ...)` 绑定任务所属用户;请求线程不受影响(没有绑定时仍走 `StpUtil`)。新增后台任务时必须照此处理,否则会抛 `NotWebContextException`。
- 禁止在 `@Transactional` 方法内调用 AI:等待 AI 期间不得占用数据库连接。
+19
View File
@@ -0,0 +1,19 @@
# 响应规范与 DTO 转换
- **功能**:统一 API 的响应形态、错误文案风格与 DTO 转换方式。
- **何时用**:新增或修改接口返回值、处理异常、增删 DTO 字段或自定义映射时。
## 响应规范
- 成功:`CommonResult.success(data)`,code=200。
- 业务错误:`CommonResult.error(msg)`,code=400,HTTP 200。
- 未登录:`GlobalExceptionHandler.handleNotLogin()`,HTTP 401 + code=401。
- 参数校验失败:`MethodArgumentNotValidException`,code=400。
- 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。
## DTO 转换
- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。
- 默认 `unmappedTargetPolicy = IGNORE`。
- 自定义映射使用 `@Mapping(source, target)`。
- 增删 DTO 字段后必须重新编译,否则生成代码不含新字段。
+19
View File
@@ -0,0 +1,19 @@
# 数据访问层编码规范
- **功能**:规定数据访问层的实现方式,避免手写 SQL 与字符串 key 取值带来的跨库隐患。
- **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、评审数据访问代码时。
## 编码规范
### 数据访问层
- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL
- 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段
- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值**
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错
- 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法
- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml`
- 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `<resultMap>`
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
+35
View File
@@ -0,0 +1,35 @@
# 数据库迁移
- **功能**:约束 Flyway 迁移脚本的写法,让数据库结构变更可追溯、可部署。
- **何时用**:新增或修改表结构、编写迁移脚本、调整索引、部署前核对历史数据时。
## 数据库迁移(Flyway Migration)
### 测试用 H2、部署用 MySQL:这几件事 H2 测不出来
迁移脚本在测试里跑的是 H2(`MODE=MySQL`),它与真实 MySQL 的差异会造成「测试全绿、部署起不来」:
- **索引键长度上限**:InnoDB 对索引键有 3072 字节硬上限(DYNAMIC 行格式),超了直接报 error 1071;
utf8mb4 下 `VARCHAR(n)` 要按 `4n` 字节算,多列唯一键很容易越界。**H2 不校验**。
→ 改动任何索引后跑 `MigrationIndexKeyLengthTest`(它直接读迁移文件复算键长)。
- **整型显示宽度**:`TINYINT(1)` 在 MySQL 8.0.17 起被标记弃用(MySQL 9.7 文档确认**尚未移除**,只是弃用)。
这里刻意保留 `TINYINT(1)`:它正是 JDBC 把列映射成 `Boolean` 的惯用声明,换成裸 `TINYINT` 会让布尔字段的映射行为依赖连接参数。
- **遇脏数据要响亮失败**:`V20261009_3`(业务编号唯一约束)与 `V20261009_5`(计时列类型修正)
在历史数据不干净时会直接让启动失败。这是有意的——宁可失败也不静默跳过约束。部署前先按迁移注释里的核对 SQL 检查。
### 命名规则
- 脚本格式:`V{YYYYMMDD}_{序号}__{描述}.sql`
- 日期必须使用**实际编写日期**,不得使用过去的日期
- 序号从 1 开始,同一天多个脚本递增
- 描述使用下划线分隔的英文短语
### 核心原则
- **不可变性**:已执行的迁移脚本永远不得修改
- **只增不减**:数据库变更只能通过新增迁移脚本实现
- **向后兼容**:新脚本应兼容已有数据
### 操作规范
- 删除表:创建新迁移脚本,使用 `DROP TABLE IF EXISTS`
- 修改表结构:使用 `ALTER TABLE` 语句
- 新增表:创建新迁移脚本,使用 `CREATE TABLE`
+31
View File
@@ -0,0 +1,31 @@
# 内容归属与标记
- **功能**:区分知识碎片的「记录上下文」与「内容归属」两个维度,并统一管理标记元信息。
- **何时用**:改动碎片归属、生成或查看报告、取材导图、新增或检索标记时。
## 内容归属与结构化报告(归属-01 / 报告-01)
知识碎片有两个**互相独立**的维度,改动任何一处都要先分清是哪一维:
- **记录上下文**(`context_type` + `context_num`):产生于哪次学习会话或复习行为。由系统确定、**不可变、不可为空**;用于时间统计与「这份报告里有哪些碎片」。
- **内容归属**(`owner_task_num`):内容在知识结构上属于哪个任务。由用户确定、**可变、可为空**(为空即待归类);用于导图取材、按任务检索与统计。
由此得出的几条硬约束:
- **导图、按任务检索、碎片计数一律按内容归属**(`owner_task_num`),不再用「该任务的会话所产生的报告/碎片」。
- **报告按会话生成**,报告的任务来自它所属会话——这与上一条是两个视角,是有意为之,不是重复。
- 新建碎片时内容归属默认取该会话所属任务;用户可以改到别的任务或清空为待归类。
- 归属变化(或碎片删除)会把**原任务与新任务**的标准导图标记为 `needs_update=1`;重建由用户手动触发,不自动跑 AI。
- 报告只落库三段文本(`session_summary` / `expectation_verdict` / `free_summary`);「按归属分组的碎片」**不落库**,查看时按当前归属实时聚合,以免与导图取材出现两套口径。文档里的展示顺序是:会话摘要 → 预期达成判断 → 按归属分组的碎片 → 自由总结。
- 删除报告**不**连带删除碎片;删除任务时碎片保留并把归属置空(进入待归类),其余(会话、报告、导图、回忆记录、应用场景)随任务软删除。
## 标记(标记-01)
标记是附加在对象上的轻量元信息,**统一存放**,新增一种标记不改各功能表结构。
- **可挂对象只有知识碎片与学习任务**:报告是会话的派生结果且已有「按归属分组」这一维度;会话是时间轴对象,其流程性信息留在主体上。
- **两类彻底分开**:系统标记走 `SystemMarkerEnum` 固定词表、由系统写入、用户只读;用户标签自由增删改。分开的理由是「找出所有来自 X 的内容」这类检索必须可靠。
- **系统标记成对(名 = 值)**,用户标签只有名(标签名本身就是全部信息)。
- 检索只提供**单一标记筛选**;标记对用户全部可见,标签可改名可删除(改名安全:标记不参与聚合口径)。
- **标记不是状态**:会话状态、报告可否修订、导图是否待更新这类流程判断留在主体上。碎片上的复习反馈(已掌握/稍后再看)也因此落在碎片自身字段,不进标记表。
- 对象被删除时清理其标记(`MarkerService.removeAllMarkers`)。
+178
View File
@@ -0,0 +1,178 @@
---
name: comment-cleanup
description: 提交代码前优化 Java 注释,移除冗余描述性注释,保留功能性注释和业务上下文注释。
metadata:
short-description: 清理 Java 代码中的冗余注释
---
# Comment Cleanup
在代码提交前,扫描变更的 Java 文件,清理冗余注释,保留有价值的注释。
## 触发条件
用户要求清理注释、优化注释、提交前检查注释时使用。
## 工作流程
1. 定位待清理的 Java 文件(通常是 `git diff` 中变更的文件)
2. 逐文件扫描注释,按规则分类处理
3. 执行清理(删除或改造)
4. 输出清理报告
## 注释分类规则
### 移除:类型 A — 代码语义重复注释
代码本身已经清晰表达意图时,删除多余的行内注释。
```java
// ❌ 移除:代码已经说清楚了
// 转换报告
List<ReviewFeedItem> reportItems = reports.stream().map(r -> toFeedItem(r)).collect(Collectors.toList());
// ❌ 移除:合并逻辑一眼就能看出
// 合并并按创建时间倒序
return Stream.concat(reportItems.stream(), fragmentItems.stream())
.sorted(Comparator.comparing(ReviewFeedItem::getCreatedTime).reversed())
.collect(Collectors.toList());
// ❌ 移除:查询目的从变量名已可知
// 先查该任务下的所有 sessionNum
List<String> sessionNums = studySessionsMapper.selectList(...)
```
**判断标准:** 如果删掉注释后,一个熟悉 Java/Spring 的开发者看代码没有任何困惑,就该移除。
**例外:** 方法级的 Javadoc(`/** ... */`)即使与代码重复,也保留,因为它服务于 IDE 提示和文档生成。
### 移除:类型 B — 框架机制注释
框架隐式行为(拦截器、MetaObjectHandler、AOP 等)的说明不在代码中重复标注,而是在 `AGENTS.md` 的"框架机制"章节集中描述。代码中的此类注释一律移除。
```java
// ❌ 移除:框架机制已在 AGENTS.md 中说明
// created_by 条件由 TenantLineInnerInterceptor 自动注入
List<StudyReportsEntity> reports = studyReportsMapper.selectList(...)
// ❌ 移除
// 拦截器自动校验归属
return Optional.ofNullable(studyReportsMapper.selectById(id)) ...
// ❌ 移除
// created_by 由 MetaObjectHandler 自动填充
studySessionsServiceImpl.save(...)
```
### 移除:类型 D — 空注释 / 无信息量注释
```java
// ❌ 空 Javadoc
/**
*
*/
@TableField(value = "created_time")
private LocalDateTime createdTime;
// ❌ 纯标注作者(无版本/日期等有价值信息时)
/**
* @author guo
*/
public class GlobalExceptionHandler { ... }
// ❌ 重复 HTTP 状态码(CommonResult.error 已隐含 400)
//code:400
return CommonResult.error(ex.getMessage());
```
### 保留:类型 C — 字段/类 Javadoc
字段 Javadoc 描述数据含义,类 Javadoc 描述模块职能。
**字段 Javadoc:** 保留,说明字段的业务含义。
```java
// ✅ 保留:字段含义对理解数据模型有帮助
/**
* 账号-登录用
*/
@TableField(value = "user_name")
private String userName;
```
**类 Javadoc:** 保留,但只描述类的职能,不包含实现技术细节。
```java
// ❌ 移除:实现技术属于实现细节,不属于类描述
/** 复习模块 Service 实现(纯 MyBatis-Plus Java API) */
// ✅ 保留:只描述职能
/** 复习模块 Service 实现 */
```
### 改造:类型 E — 枚举注释
枚举中的中文含义注释应迁移到枚举类的专用字段中,而非用注释标注。
```java
// ❌ 改造前:用注释标注含义
public enum Strategy {
// 创建组
CREATE("C"),
// 更新组
UPDATE("U");
}
// ✅ 改造后:用字段存储含义
public enum Strategy {
CREATE("C", "创建组"),
UPDATE("U", "更新组");
private final String code;
private final String label;
Strategy(String code, String label) {
this.code = code;
this.label = label;
}
public String getCode() { return code; }
public String getLabel() { return label; }
}
```
如果枚举已有 `label`/`desc` 等字段,则直接删除注释。
**常量注释保留不变:**
```java
// ✅ 常量注释保留
// 最大重试次数
private static final int MAX_RETRY = 3;
```
### 保留:类型 F — TODO / FIXME 注释
```java
// ✅ 保留
//todo 参数传递未加密
```
## 执行命令
```bash
# 获取变更的 Java 文件
git diff --cached --name-only --diff-filter=ACMR -- '*.java'
# 对每个文件逐行扫描,按上述规则处理
```
## 输出格式
清理完成后,输出简要报告:
```
✅ 清理完成,共处理 N 个文件:
- 移除冗余注释 X 处
- 改造枚举注释 Y 处(需人工确认新增字段)
- 保留注释 Z 处(字段Javadoc/TODO)
```
@@ -0,0 +1,6 @@
schema_version: v1
interface:
display_name: Java 注释清理
short_description: 清理 Java 代码中的冗余注释,保留功能性注释
default_prompt: |
使用 $comment-cleanup 扫描变更的 Java 文件,移除冗余的描述性注释,保留框架机制注释、字段 Javadoc 和 TODO 注释。