@runweave/server-linux-x64 0.1.8 → 0.1.9

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from "lru-cache";
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000, // 5 minutes
+});
+
+export async function getUser(id: string) {
+  const cached = cache.get(id);
+  if (cached) return cached;
+
+  const user = await db.user.findUnique({ where: { id } });
+  cache.set(id, user);
+  return user;
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from "react";
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth();
+  if (!session?.user?.id) return null;
+  return await db.user.findUnique({
+    where: { id: session.user.id },
+  });
+});
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } });
+});
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 });
+getUser({ uid: 1 }); // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } });
+});
+
+// Primitive args use value equality
+getUser(1);
+getUser(1); // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 };
+getUser(params); // Query runs
+getUser(params); // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />;
+
+// Client: transform there
+("use client");
+const sorted = useMemo(() => [...usernames].sort(), [usernames]);
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/hoist-static-io.md

@@ -0,0 +1,139 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Alternative: synchronous file reads with Node.js fs**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**General Node.js example: loading config or templates**
+
+```typescript
+// Incorrect: reads config on every call
+export async function processRequest(data: Data) {
+  const config = JSON.parse(await fs.readFile("./config.json", "utf-8"));
+  const template = await fs.readFile("./template.html", "utf-8");
+
+  return render(template, data, config);
+}
+
+// Correct: loads once at module level
+const configPromise = fs.readFile("./config.json", "utf-8").then(JSON.parse);
+const templatePromise = fs.readFile("./template.html", "utf-8");
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ]);
+
+  return render(template, data, config);
+}
+```
+
+**When to use this pattern:**
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+**When NOT to use this pattern:**
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** Module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+**In traditional serverless:** Each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader();
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  );
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems();
+  return <nav>{items.map(renderItem)}</nav>;
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader();
+  return <div>{data}</div>;
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems();
+  return <nav>{items.map(renderItem)}</nav>;
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  );
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader();
+  return <div>{data}</div>;
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems();
+  return <nav>{items.map(renderItem)}</nav>;
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  );
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  );
+}
+```

package/payload/plugins/toolkit/skills/react-best-practices/rules/server/serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser(); // 50 fields
+  return <Profile user={user} />;
+}
+
+("use client");
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>; // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser();
+  return <Profile name={user.name} />;
+}
+
+("use client");
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>;
+}
+```

package/payload/plugins/toolkit/skills/recorded-browser-mcp-verification/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: recorded-browser-mcp-verification
+description: 兼容 recorded-browser-mcp-verification 旧名称，将浏览器录屏取证请求转到 toolkit:acceptance。仅用于旧名称兼容；新请求使用统一入口。
+---
+
+# 旧名称兼容
+
+读取[统一验收材料 Skill](../acceptance/SKILL.md)，按用户本次范围执行。旧名称表示本次偏好原始录屏，不扩大授权，不额外制作用户未要求的产物。原有脚本路径转发到统一实现。

package/payload/plugins/toolkit/skills/recorded-browser-mcp-verification/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "recorded-browser-mcp-verification（兼容）"
+  short_description: "旧名称兼容入口，当前规则与实现统一维护在验收材料 Skill 中"
+  default_prompt: "使用 $acceptance，按我请求的原始录屏形式交付本次验收材料。"
+policy:
+  allow_implicit_invocation: false

package/payload/plugins/toolkit/skills/reproduce-before-fix/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: reproduce-before-fix
+description: 仅供显式调用：对给定或执行中发现的问题，先通过真实业务入口和生产代码路径复现，再决定是否修复或优化；无法复现、只能由 mock 或伪造状态触发、或确认处于不支持边界时停止修改。
+---
+
+# 真实复现后修复
+
+坚持一个顺序：**先复现，再解决，再优化**。问题描述、测试结论和 P0/P1/P2 标签都是待验证输入，不是问题已经成立的证据。
+
+## 调用边界
+
+本技能只允许通过 `$toolkit:reproduce-before-fix` 显式调用，不根据普通的“修复问题”“测试失败”或“优化性能”等请求自动触发。
+
+显式调用代表执行复现门槛，不代表承诺修复。处理用户提供的问题，也处理本次任务中发现的新问题；每个问题都独立经过同一门槛。
+
+需要通过新增、录制和分析 AI 诊断日志逐步定位时，显式组合使用 `$toolkit:diagnostic-log-debugging`。该技能负责日志采集与定位方法；本技能仍负责判断真实复现是否成立、是否允许进入修复和优化。
+
+复现需要实际规划、启动、查询、打开或停止 Dev Session 时，同时使用 `$toolkit:runweave-dev-session`；本技能负责复现门槛和 Before 证据，该技能负责准确的 Session 生命周期。
+
+## 什么是真实复现
+
+使用真实产品入口、当前生产代码路径和实际运行中的进程、接口、存储、事件流或传输层，观察真实可见结果。尽量还原报告中的用户角色、操作顺序、数据规模、环境和时序。
+
+可以用脚本或浏览器自动化驱动真实系统，但自动化只能代替人工操作，不能代替被验证的系统。以下内容可以帮助形成假设，但不能单独算作复现：
+
+- mock、stub、fake transport 或伪造响应；
+- 只构造 fixture、内存对象或虚假业务数据；
+- 绕过产品入口直接调用内部类、私有函数或测试专用接口；
+- 只阅读代码后推断“应该会发生”；
+- 只让单元测试或模拟环境失败。
+
+## 执行流程
+
+### 1. 把结论还原成可观察问题
+
+先写清触发条件、操作入口、预期结果和实际症状。区分报告原话、当前事实和待验证推测。优先级只影响处理顺序和响应速度，不得跳过复现。
+
+如果描述缺少细节，先从代码、测试记录、日志和实际产品入口补齐；只有缺失信息会实质改变复现路径时才向用户确认。
+
+### 2. 在修改前执行真实复现
+
+记录代码基线、运行环境、真实入口、完整步骤和观察证据。证据按问题选择，可以是页面行为、DOM、网络消息、真实接口响应、日志、存储结果、事件序列、截图、录屏或性能数字。
+
+在安全且成本合理时重复执行，排除偶发环境噪声。性能问题必须先记录基线、规模和可判断的数字；没有测到问题，就不进入性能优化。
+
+在 Runweave 中预期后续组合 `$toolkit:runweave-change-validation` 时，复现阶段同时建立交接记录：
+
+- 默认让第一次 `dev:session start` 自动生成 ID，并立即从 JSON 结果捕获为 `validationSessionId`；如果必须在启动前建立证据目录或映射，使用 `rcv-YYYYMMDD-<hash6>`，其中 `hash6` 固定取 `SHA-256("<baselineRevision>\n<scenarioId>")` 前 6 位小写十六进制，禁止 `Math.random`、UUID、裸时间戳、随意截 commit 或任意标题；
+- 选定稳定的 `scenarioId`；`validationSessionId` 一旦捕获或生成，本次任务内不得更换；
+- 将代码 revision、完整步骤、输入数据、target surface、关键身份和证据写入同一证据根目录的 `before/`；
+- 若修复前使用 Dev Session，使用该 `validationSessionId`，并在 `dev:stop` 前归档 `dev:status`、`dev:open` 和 manifest 关键字段；后续修复验证必须复用同一 ID；
+- 若问题来自不可替换的既有用户 session，不改名或迁移该 session；记录 `sourceSessionId → validationSessionId` 映射及不能复用的原因，这是唯一允许不同 ID 的情形。
+
+### 3. 通过门槛决定动作
+
+只允许以下结论：
+
+| 结论         | 判断依据                                                 | 动作                                   |
+| ------------ | -------------------------------------------------------- | -------------------------------------- |
+| 已复现       | 真实入口稳定出现报告症状，并有可回查证据                 | 定位已证实机制，进入最小修复           |
+| 未复现       | 已覆盖可信路径，但真实系统没有出现症状                   | 停止，不修改代码，记录尝试与证据       |
+| 边界情形     | 超出支持契约，或只能靠伪造内部状态、不可达时序等方式触发 | 停止，不为该情形扩展实现               |
+| 环境阻塞     | 缺少设备、权限、服务、数据或必要版本，无法完成真实路径   | 停止修改，报告阻塞；不要写成“未复现”   |
+| 实际问题不同 | 真实复现暴露了不同症状、范围或根因                       | 以证据重述问题；范围实质变化时先行对齐 |
+
+低频不自动等于边界情形。只要受支持的真实用户可以从正常入口触发，即使概率低，也属于有效问题。反过来，一旦契约和真实入口已经证明某情形不可达，就不要继续扩大输入空间来制造复现。
+
+### 4. 只修复已证实的机制
+
+改动必须直接对应复现证据和已定位机制，不顺手处理相邻推测、未复现风险或其它优先级问题。若同时拿到 P0、P1、P2，分别建立结论；若只拿到 P2，也按同一流程处理，不补造更高优先级任务。
+
+### 5. 用同一真实场景验证修复
+
+先原样重跑修复前的复现场景，确认实际症状消失且预期结果成立，再执行受影响路径的回归。静态检查、代码阅读或 mock 测试不能替代这一轮验证。
+
+在 Runweave 仓库修改代码后，必须组合使用 `$toolkit:runweave-change-validation`。向它交接 `validationSessionId`、`scenarioId`、修复前 revision、原样复现步骤和 `before/` 证据。由该技能基于真实 diff 和 Dev Session 决定修复后场景的 target profile、服务 ownership 和 CDP surface，并把修复证据写入同一证据根目录的 `after/`。不要手工启动 Backend/App Server、修改全局运行时或使用 ambient CDP 代替 Dev Session。
+
+只有正确性问题已经解决且真实测量仍显示可优化空间时，才进入优化。优化后继续使用同一基线和规模比较，不用主观描述代替数字。
+
+## 交付结果
+
+按问题给出简洁、可审计的结果：
+
+- 问题与原始优先级；
+- 真实环境和复现步骤；
+- 预期、实际与证据；
+- 门槛结论；
+- 是否修改代码及修改范围；
+- 修复后同场景结果；
+- `validationSessionId`、必要的 source session 映射，以及 Before/After 并列证据；
+- 未处理原因或环境阻塞。
+
+不要把“尝试修复”“理论上修复”或“测试应该通过”写成完成。没有真实复现，就没有修复。

package/payload/plugins/toolkit/skills/reproduce-before-fix/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Reproduce Before Fix"
+  short_description: "要求先在真实业务场景复现问题，再决定是否进入修复与优化"
+  default_prompt: "使用 $toolkit:reproduce-before-fix 先通过真实业务入口复现问题，再决定是否修复。"
+
+policy:
+  allow_implicit_invocation: false

package/payload/plugins/toolkit/skills/review-only/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: review-only
+description: 当识别到用户想要做评审（计划评审或代码评审）、只评审不改代码时使用。
+---
+
+# 仅评审
+
+只评审，不改代码。先判断评审对象是「计划」还是「代码」，切换到对应角色。
+
+## 触发与约束
+
+- 识别到用户的评审意图时即可使用（无需用户点名技能名）。
+- 只读：不编辑被评审的源码、配置、测试、文档，不做格式化/代码生成，不改 git 状态。
+- 默认只在对话中回复；需要归档时，唯一允许的写操作是按下方规则保存评审报告。
+- 不用「顺手实现」代替评审结论。
+- 下结论前，用阅读/命令验证可疑点，基于证据而非猜测。
+
+## 角色判定
+
+- 评审对象是设计文档、方案、计划、RFC、PRD → 用 **计划评审**。
+- 评审对象是源码、diff、PR、配置/脚本 → 用 **代码评审**。
+- 二者混合时分别评审，结论里分两部分。
+
+## 计划评审（重点：方案是否成立）
+
+判断这个计划该不该这么做，而不是抠措辞。关注：
+
+- 问题定义：解决的是不是真问题？目标和成功标准是否清晰。
+- 方案合理性：路径能否达成目标，关键假设是否站得住。
+- 更简方案：是否有更简单或复用现有平台/能力的做法（自研 vs 复用）。
+- 可行性与风险：工作量、依赖、迁移/回滚、未覆盖的边界。
+- 缺口：被忽略的关键场景、监控、运维、成本。
+
+至少给出一个「更简单或复用现有能力」的替代方向并对比权衡。
+
+## 代码评审（重点：全维度）
+
+按需覆盖以下维度，只报有真实风险的问题：
+
+- 正确性与回归：逻辑错误、边界、并发、错误处理、副作用。
+- 架构与边界：耦合/内聚、分层、契约/协议变更的影响面。
+- 安全：鉴权、注入、敏感信息、输入校验。
+- 性能：明显的复杂度、N+1、资源泄漏。
+- 测试：关键路径覆盖盲区。
+- 可维护性：可读性、命名、归属清晰度；以及「能否删掉而非新增」。
+
+## 输出格式
+
+按严重级别排序输出，简洁直接。每条一行核心 + 必要细节：
+
+- **P0 阻断**：必须改，否则不可上线（数据/安全/线上故障/方案根本性错误）。
+- **P1 严重**：应尽快改（正确性缺陷、重大回归风险、架构错误方向）。
+- **P2 一般**：建议改（可维护性、次要风险、更优方案）。
+- **P3 提示**：可选优化、风格、待确认项。
+
+每条发现包含：
+
+- 一句话标题
+- 为什么是风险（影响）
+- `文件:行号` 定位（计划评审引用章节）
+- 修复方向（不实现）
+
+无重大问题时明确说明，并列出残余风险/待确认项。
+
+## 按需归档
+
+- 普通评审直接在对话中给出结论、证据和建议，不创建报告文件，也不额外询问是否留档。
+- 仅当用户要求留档，或已约定的正式交付、交接需要报告文件时，保存 Markdown 报告。
+- 保存位置优先遵循用户指定路径；未指定时使用 `docs/review/YYYY-MM-DD-<主题>.review.md`，仅在需要保存时创建目录。主题用小写连字符；同名不覆盖，加递增后缀。
+- 保存的报告与回复结论一致，可补充检查范围、命令输出摘要和残余风险；实际保存后，最终回复给出报告路径。
+
+!!! 必须用中文回复