From 057291358dad1818893264e49c8ab9b05cca5945 Mon Sep 17 00:00:00 2001 From: cat-shark Date: Wed, 18 Nov 2026 14:58:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=AD=90=E4=BB=A3?= =?UTF-8?q?=E7=90=86=E6=89=A7=E8=A1=8C=E3=80=81=E4=B8=9A=E5=8A=A1=E5=90=8D?= =?UTF-8?q?=E8=AF=8D=E6=94=B6=E6=95=9B=E4=B8=8E=E8=B7=A8=E6=9C=8D=E5=8A=A1?= =?UTF-8?q?=E6=A0=A1=E9=AA=8C=E5=BD=92=E5=B1=9E=E4=B8=89=E6=9D=A1=E8=A7=84?= =?UTF-8?q?=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/roles/business-terminology.md | 46 ++++++++++ .agents/roles/dev-unblock-and-escalation.md | 6 ++ .agents/roles/parallel-and-delegation.md | 5 ++ .../service-boundaries-and-validation.md | 53 ++++++++++++ .agents/roles/subagent-execution.md | 83 +++++++++++++++++++ 5 files changed, 193 insertions(+) create mode 100644 .agents/roles/business-terminology.md create mode 100644 .agents/roles/service-boundaries-and-validation.md create mode 100644 .agents/roles/subagent-execution.md diff --git a/.agents/roles/business-terminology.md b/.agents/roles/business-terminology.md new file mode 100644 index 0000000..e9f16f3 --- /dev/null +++ b/.agents/roles/business-terminology.md @@ -0,0 +1,46 @@ +# 业务名词收敛 + +- **功能**:让 agent 之间(含写给下一个 agent 的文本)始终使用同一套业务名词,避免同一概念在不同会话里被叫成不同名字而对不上号。 +- **何时用**:描述系统概念、拆需求、委派子代理、写评审结论、写决策笔记与提交信息时;新造词或怀疑某个词不在术语表里时。 + +## 权威来源 + +- 唯一权威:`lpt-docs/docs/concepts/README.md`(术语表:概念 / 英文名 / 一句话定义 / 详细文档,另带「代码现状」与「已确认的命名分歧」两表)。 +- 该目录不存在时先按 meta `AGENTS.md`「首次初始化」的 clone 命令拉取(`-b main`),不要凭记忆复述术语。 +- 术语表本身的维护边界与更新顺序见 `lpt-docs/.agents/roles/documentation-scope.md`(概念文档 → 术语表 → `lpt-docs/README.md` 阅读路径)。 +- 本规则不复制术语表正文(依据 `workspace-layout.md`:meta 仓库不复制业务正文)。 + +## 硬约束 + +1. 提到系统概念,必须使用术语表「概念」列的原词。不改字、不缩写、不加书名号式别名、不换同义表述、不造英文缩写替代。 +2. 写代码时用术语表「英文名」列的词,不另行翻译:同一个概念在不同仓库必须同一个英文词。 +3. 表里没有的词:先在 `lpt-docs` 补齐概念文档与术语表,再在交流里使用。不允许「先这么叫,回头统一」。 +4. 一个概念一个名字:术语表存在历史同义词映射时(如「学习报告残片」与「知识碎片」),以术语表主词为准;同义词只在解释映射关系时出现,不用于指代。 +5. 拿不准某词是否在表内:`rg "<关键词>" lpt-docs/docs/concepts/README.md` 核对,不靠印象。 + +## 不在约束内 + +- 代码标识符、数据库列、API 字段、类/文件/命令/路径、第三方产品名(Flyway、Sa-Token、DeepSeek 等)——按代码原样书写,不强行中文化、不转写成中文。 +- 但解释这些标识符含义时必须落回术语表用词:`StudyReportFragmentsEntity` 要说「知识碎片」,不能说「报告片段」「笔记条目」。 + +## 代码命名派生 + +术语表不只管说话,也管代码:每个概念的英文名就是它的英文表达,代码标识必须能从英文名机械派生,不另起别名。 + +| 代码位置 | 派生规则 | +|----------|----------| +| 库表 | 英文名转 snake_case,复数 | +| 实体类 | `<英文名>Entity` | +| DTO / 前端类型 | 与英文名同形的 PascalCase | +| 字段 / 接口参数 | 与英文名同形的 camelCase | + +- 写新类、新表、新字段、新类型前,先在术语表找到对应概念的英文名,按上表派生;找不到概念就先补表(含英文名),再写代码。 +- 与英文名不一致的存量标识登记在术语表「代码现状」,不算违规;但**不能基于存量偏差再派生新名**,同一概念不得出现第三种叫法。 +- 概念改名或新增英文名属于跨仓库契约:先改术语表,再同步库表、实体、接口字段与各端类型,不单端先改。 + +## 边界情形 + +- 用户自己用了表外词:沿用其指代的概念,回复里用术语表原词,不跟着改口(用户明确要求换词除外)。 +- 新概念尚未定稿:标「术语待定」并在同一次改动里补表,不要用「暂时叫 X」了事。 +- 术语表与代码、注释、文档用词冲突:以术语表为准修正其他位置,按 `research-and-reporting.md` 报事实,不自行造词补齐。 +- 交付前自查:把本次回复与改动里的业务名词、以及新增或改动的类名/表名/字段名/前端类型名,逐项对一遍术语表;解释不出来的就是自造词,出现表外词就是未完成。 diff --git a/.agents/roles/dev-unblock-and-escalation.md b/.agents/roles/dev-unblock-and-escalation.md index 8d949ea..5b4f521 100644 --- a/.agents/roles/dev-unblock-and-escalation.md +++ b/.agents/roles/dev-unblock-and-escalation.md @@ -12,6 +12,12 @@ - 解锁完成后必须**还原临时改动**,并在最终汇报里说明「改了什么、是否已还原」;若无法还原,必须明确标出并提示用户。 - 禁止用复杂且会污染运行环境的绕过手段(伪造会话状态、拦截网络请求、长时间改配置等)替代直接、可控的临时解锁。 +### 计时类功能不要真实等待 + +- 验证倒计时、番茄钟、休息、冷却、重试退避等计时功能时,**直接临时改短时长常量**(如把 25 分钟改成 5~10 秒)走完流程,不要真的等 5 分钟或 25 分钟。 +- 同样只在开发环境生效、改一处、验证完立即还原,并在汇报里注明改了哪个常量、是否已还原。 +- 只验证「到点后的状态切换与按钮行为」;耗时精度、长时段累积这类靠单元/集成测试的假时钟覆盖,不靠真实等待。 + ### 尝试预算与求助阈值 - 对同一个目标,若连续尝试达到 **5 次**仍未解决,立即停止继续加码。 diff --git a/.agents/roles/parallel-and-delegation.md b/.agents/roles/parallel-and-delegation.md index d02f2ad..30bc99b 100644 --- a/.agents/roles/parallel-and-delegation.md +++ b/.agents/roles/parallel-and-delegation.md @@ -33,6 +33,11 @@ meta 还把它混在「工作区规则」里。同一套约束在 5 个仓库里 派发子任务时把**已确认口径、涉及文件、验收命令、提交信息**写清楚。 信息不全的子任务会退回,不要用「你看着办」代替。 +### 改动面大时交给子代理执行 + +一次改动铺开多个文件 / 模块 / 仓库时,按 `.agents/roles/subagent-execution.md` 拆分并委派: +主代理只定口径、验收与整合提交,不逐个文件亲手改。 + ### meta 仓库只由主代理写 `OPTIMIZATION_BACKLOG.md` 只由主代理更新,子代理不要改(避免 meta 仓库并发写); diff --git a/.agents/roles/service-boundaries-and-validation.md b/.agents/roles/service-boundaries-and-validation.md new file mode 100644 index 0000000..fbd0b6a --- /dev/null +++ b/.agents/roles/service-boundaries-and-validation.md @@ -0,0 +1,53 @@ +# 服务边界与校验归属 + +- **功能**:规定一条校验该写在哪一层服务里,禁止同一份结构约束在多个服务各写一遍。 +- **何时用**:要给接口加字段校验时;发现某个服务在复核上游返回的结构时;要限制 LLM 产出格式时;评审跨服务 DTO 与解析代码时;看到「防御式」兜底代码时。 + +## 为什么有这条规则 + +2026-11-18 排查自由回忆草稿保存失败,根因是后端把一份自建严格 ObjectMapper 用在了三个不同方向:前端请求、落盘文档、lpt-ai 返回的 AI 结果。`FAIL_ON_MISSING_CREATOR_PROPERTIES` 在 record 上会把**可选**组件也当成必填,于是前端按契约省略 `style` 就被整单 400。 + +同一轮审计还发现后端 `RecallAiResultValidator` 把 lpt-ai 的严格解析器又实现了一遍,而且两套上限已经分叉(限制说明 lpt-ai ≤5 条、后端 ≤12 条)。此前那次「正常 AI 结果被判 `INVALID_AI_RESULT`」的事故,正是分叉的直接代价。 + +两次故障是同一个病:**服务不相信自己的邻居,于是把对方的规则复述了一遍,复述的东西必然漂移。** + +## 规则 + +### R1 结构由产出方保证,接收方只做映射 + +接口结构一旦协商确定,就由**产出方**保证自己发出的数据满足它、由**接收方**保证自己能读懂它,双方都不再复述对方的规则。 + +- AI / LLM 输出:结构、字段、条数、枚举、长度上限的校验在 AI 服务内完成(如 `lpt-ai` 的 `normalizeRecallResult`),在调用模型的那一侧就解决。 +- 业务后端的 AI 结果处理只做 JSON → DTO 映射与失败分类,不重新校验结构。 +- 前端只校验信封(版本、必要字段存在),不重复业务后端的语义判定。 + +### R2 LLM 的格式约束写在调用模型的那一侧 + +要限制模型返回内容合法,就在**调用模型的服务里**校验并做纠正/重试,不把这条规则下放到下游业务服务。下游加一层不会提高模型输出质量,只会在模型正常输出时制造误判。 + +### R3 必需保留的复核只有一种:落库边界的不可信数据 + +如果本服务把数据**落库或直接展示给用户**,而该数据的真实性是产品的核心承诺(例如「引文确实取自本次资料」「金额确实来自支付回调」),这条复核必须由本服务自己持有,不能靠上游自证。除此之外不再加复核。 + +判断式:**这条校验是不是只有在「落库边界」才成立?** 是 → 本服务做。只是「上游应该已经做过」→ 不做。 + +### R4 反向不适用:接收方必须拒绝的只有类型与未知字段 + +接收方对输入仍应拒绝**真正的类型错误**和**未知字段**(协议漂移信号),但不得把可选字段的缺席当成错误。可选性写进 DTO 就必须真的可选。 + +### R5 发现重复校验时先问「谁的职责」,再删 + +看到两处做同一件事,先确认哪一层是产出方,删掉非产出方那份;不要因为「多一层更安全」而保留。真需要第二道防线时,用 R3 的判断式说明理由,并写进决策笔记。 + +## 边界 + +- 本规则约束的是**跨服务的规则归属**,不禁止单个服务内部的充分校验。服务自己对自己的数据完整性负责,那是分内事。 +- 传输层重试、超时、幂等、鉴权不属于「结构校验」,各服务照常按需实现。 +- 数据已是历史脏数据(旧版本落盘格式)时,接收侧的「读不出来就按损坏处理」不算重复校验,见 `lpt-be/.agents/notes/implemented/architecture/2026-11-18-recall-validation-ownership.md`。 +- 规则与常识冲突时(例如安全审计要求二次校验),以安全要求为准,并在笔记里写明例外原因。 + +## 怎么核对 + +- 问「这条规则改了要改几个仓库」:答案大于 1,就说明规则写错了层。 +- 搜索接收侧的解析代码:出现与上游同名的枚举列表、同名的条数上限、同名的长度限制,即为重复校验候选。 +- 跨服务协议调整后,两边的上限与枚举必须能一一对上;对不上就是分叉,按 R5 处理。 diff --git a/.agents/roles/subagent-execution.md b/.agents/roles/subagent-execution.md new file mode 100644 index 0000000..f96e133 --- /dev/null +++ b/.agents/roles/subagent-execution.md @@ -0,0 +1,83 @@ +# 子代理执行与主代理复核 + +- **功能**:改动面较大时把执行交给子代理,主代理只定口径、派活、验收与整合,避免主代理逐处改到没力气判断,也避免子代理改完没人核对。 +- **何时用**:方案要改很多处时;准备一次改动多个文件/模块/仓库时;已派出子代理、需要确认结果是否达标时;子代理产出与预期不符时。 + +## 为什么有这条规则 + +两个真实存在的失败模式: + +1. **主代理逐处改。** 一次改动铺开十几个文件,主线上下文被读取、试错、回滚占满,真正需要判断的部分(口径是否走偏、边界是否被突破)反而没力气看。 +2. **改动者自己宣布完成。** 改代码和判断「改得对不对」是同一份被细节淹没的上下文,越界改动、漏改、测试没真跑都容易漏过去。 + +委派的收益不是「省字」,而是把执行切成边界清楚的单元,并把最终判断留给一份没有被改动细节淹没的上下文。 + +## 规则 + +### R1 先估改动面,再决定谁写 + +开工前先列改动面清单:要改哪些文件/模块/仓库,彼此是否有依赖。满足任一条就按本规则委派执行: + +- 改动落在 **3 个及以上互不依赖的改动单元**(不同模块、不相关文件组、或独立子项目); +- 需要跨 **2 个及以上子项目**(如后端 + 前端 + AI 服务); +- 同一批改动要来回试错多轮,主代理继续做会把上下文吃光。 + +达不到上述规模时主代理直接做,不要为了「用上子代理」硬拆。 + +### R2 按接缝拆,按单元派 + +按**依赖接缝**拆,不按文件数平均分。每个子任务是一个可独立验收的改动单元,并具备: + +- 明确的写边界:只能改哪些文件/目录;越界必须先回来问; +- 明确的完成定义:改完后应该是什么行为,怎么证明; +- 互不重叠的写范围。同一目录单写入者仍然成立(见 `parallel-and-delegation.md`),必须同目录并行时用 worktree 隔离。 + +有真实依赖的单元串行派,无依赖的同时派;不要逐个等。 + +### R3 派活说明写全 + +按 `parallel-and-delegation.md` 的「派发说明要写全」:已确认口径、涉及文件、验收命令、提交信息。另外必须补两条: + +- **写边界**:允许改动的文件清单;边界外一律先问。 +- **输出要求**:返回实际 diff 摘要、跑过的命令与结果、未完成项或存疑项。只回「已完成」视为信息不全,退回。 + +### R4 主代理只做定口径、验收、整合 + +委派之后,主代理**不再逐个文件改同一批改动**。它的工作是: + +1. 定口径与验收标准——口径没定就派不出去,先定再派; +2. 发任务并跟踪返回; +3. 收结果后自己跑验收命令、读 diff,核对是否越界、是否漏改; +4. 整合提交、收口 todo、对外汇报。 + +验收不通过时,把**具体差异**回给同一个子代理(resume / steer)让它继续改,不要主代理接手重写;同一子代理连续两次改不对,主代理才接手,并把原因写进记录或笔记。 + +### R5 复核看证据,不看声明 + +复核至少覆盖以下各项,任一项不通过就不算完成: + +- diff 是否只落在允许的文件范围内,有没有顺手重构、加功能、改口径; +- 子代理声称跑过的验收命令,主代理自己再跑一次并看到通过; +- 有没有留下调试代码、临时文件、被注释掉的旧逻辑; +- 提交信息是否符合 `commit-convention.md`; +- 多单元改动合并后整体行为是否仍成立(跨单元边界最容易出问题)。 + +### R6 这些情况不委派 + +- 单文件、单点小改; +- 方案口径还没定——先定口径,再派执行; +- 改动本身就是探索性的(要来回试才知道改什么)——主代理先探明,再把确定的执行部分派出去; +- meta 仓库根目录的 `AGENTS.md`、`.agents/`、`OPTIMIZATION_BACKLOG.md`:由主代理自己写,子代理只读(避免 meta 仓库并发写)。 + +## 边界 + +- 委派不改变责任归属:口径、最终判断、提交、对外汇报都在主代理。 +- 不得以「已派给子代理」为由跳过复核;也不得把复核再转派出去后自己不看 diff。 +- 用户明确要求主代理自己做,或当前入口没有子代理能力时,按用户要求执行,并在回复里说明未委派的原因。 +- 本规则约束的是「谁写、谁验」,不重复并行与依赖判断,后者仍以 `parallel-and-delegation.md` 为准。 + +## 怎么核对 + +- 每个委派批次都能说清:拆分依据、每个子任务的写边界、验收命令与结果; +- 主线看到的 diff 与子代理返回的 diff 一致,没有主代理未申报的补改; +- 最终提交里没有子代理越界产物,也没有「子代理说完成但没人验」的条目。