feat: add frontend development guidelines and structure documentation

- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
2026-07-25 22:20:25 +08:00
commit 91861565bb
78 changed files with 5001 additions and 0 deletions
@@ -0,0 +1,13 @@
+# Assets
+
+索引由成熟经验产生的可执行资产：
+
+- global-agents
+- repo-agents
+- skills
+- hooks
+- scripts
+- evals
+- templates
+
+资产的实际 source of truth 可以在对应项目或 `~/.agents/skills` 中；这里记录来源 learning、目标路径和验证方式。
@@ -0,0 +1,5 @@
+# Experiments
+
+记录可复现的模型、提示词、上下文、工具和工作流实验。
+
+每个实验至少包含假设、输入、对照、观察指标、结果和结论。不要把单次主观感受直接提升为 Pattern。
@@ -0,0 +1,52 @@
+---
+id: 20260625-central-compounding-brain
+title: 使用中央知识仓库管理跨项目 AI coding 经验
+created: 2026-06-25
+updated: 2026-06-25
+status: candidate
+scope: global
+category: agent-workflows
+confidence: medium
+last_verified: 2026-06-25
+promotion_target: skill
+projects:
+  - personal-codex
+tags:
+  - compound-engineering
+  - knowledge-management
+  - cross-project
+---
+
+# 使用中央知识仓库管理跨项目 AI coding 经验
+
+## Trigger
+
+多个项目分别积累 AI coding 经验，导致相同纠正、失败路径和成功模式难以跨项目检索与复用。
+
+## Context
+
+当前 Obsidian Vault 被选为个人跨项目复利仓库。全局 Skill 负责工作流，Vault 负责持续增长的经验数据，各项目继续保留与代码版本强关联的执行规则。
+
+## Evidence
+
+- 2026-06-25：确定采用中央大脑与项目执行层分离的架构。
+- 全局 Skill 位于 `~/.agents/skills/compound-coding/`。
+- 中央知识入口位于 `AI Coding/index.md`。
+
+## Root cause
+
+经验如果只保留在单次对话或单个项目中，就无法稳定跨项目检索；如果所有规则都集中在全局提示中，又会造成上下文膨胀并污染项目边界。
+
+## Preferred action
+
+将新经验先写入中央 `inbox/`，验证后进入 `learnings/`，跨项目成立后再归纳为 `patterns/`。把确定性要求同步为项目测试、lint、hook、脚本或 `AGENTS.md`。
+
+## Boundaries
+
+- 项目专属架构、命令和业务事实仍以项目仓库为准。
+- 中央经验在使用前需要根据当前代码和文档重新验证。
+- 不把凭证、客户数据或其他敏感信息写入复利仓库。
+
+## Promotion record
+
+- 2026-06-25：创建全局 `compound-coding` Skill 作为工作流执行层；候选经验仍需经过实际项目使用验证。
@@ -0,0 +1,75 @@
+---
+id: 20260627-cloud-runtime-project-root
+title: 云端运行时不要依赖 process.cwd() 推断项目根目录
+created: 2026-06-27
+updated: 2026-06-27
+status: candidate
+scope: global
+category: debugging
+confidence: high
+last_verified: 2026-06-27
+promotion_target: none
+projects:
+  - evaluator-agent
+tags:
+  - cloud-deployment
+  - path-resolution
+  - playwright
+  - diagnostics
+---
+
+# 云端运行时不要依赖 process.cwd() 推断项目根目录
+
+## Trigger
+
+本地测试能读到配置或资源，但部署到云端后同一流程表现为配置缺失、鉴权未执行、文件不存在、资源路径 404，且日志里只看到后续业务失败。
+
+## Context
+
+一次 Playwright 云端测试排查中，测试进程能访问目标页面，但前置鉴权没有执行，页面最终停留在登录页。最初怀疑是 cookie/sessionStorage 写入失败、Chrome 限制或跨域问题。后来通过运行时证据确认：fixture 已经执行，但没有读到项目 auth 配置。
+
+关键差异是云端 Playwright 进程的 `process.cwd()` 是应用包目录，而项目文件和 `.evaluator/projects/<id>.json` 在另一个工作目录。代码用 `process.cwd()` 推断项目根目录，导致读取了错误位置的配置文件。
+
+## Evidence
+
+- 2026-06-26/27，`evaluator-agent` 云端测试排查。
+- 运行时 `auth-setup` 证据显示：`projectIdPresent=true`，但 `authConfigured=false`，`authApplied=false`。
+- 临时深度诊断曾显示运行时尝试读取 `/app/.evaluator/projects/<project-id>.json`，但实际项目产物位于 `/workspace/project/...`。
+- 修复提交：`ee1e9b0 Fix Playwright project root resolution for auth config`。
+- 相关文件：
+  - `packages/core/src/evaluator/run.ts`：启动 Playwright 时传入 `EVALUATOR_PROJECT_ROOT=projectRoot`。
+  - `packages/playwright/src/fixtures/ai-test.ts`：fixture 读取配置时使用 `EVALUATOR_PROJECT_ROOT || process.cwd()`。
+  - `.trellis/spec/frontend/run-analysis-contracts.md`：记录云端 cwd 与项目根目录可能不同的契约。
+- 清理提交：`8547bd1 chore: remove temporary auth debug diagnostics`，保留稳定布尔证据，删除过细路径/配置探测字段。
+
+## Root cause
+
+已验证原因：云端运行进程的 cwd 不等于项目根目录。配置读取逻辑把 `process.cwd()` 当作项目根，导致读取错误路径，表现为配置不存在。
+
+推断：类似问题也可能发生在测试报告、静态资源、项目级配置、凭证文件、生成产物、fixture 初始化、CLI 子进程中，只要代码通过 cwd 隐式推导项目根。
+
+## Preferred action
+
+对需要部署到云端或由子进程执行的代码：
+
+1. 显式传递项目根目录，例如 `PROJECT_ROOT` / `EVALUATOR_PROJECT_ROOT`，而不是在下游模块里直接信任 `process.cwd()`。
+2. 子进程启动处负责设置这个 env；fixture、worker、CLI helper 只读取显式根目录并保留 `process.cwd()` 作为本地直跑 fallback。
+3. 在运行产物里记录低风险、结构化的健康检查字段，例如 `projectIdPresent`、`authConfigured`、`authApplied`，用于远程确认流程是否执行。
+4. 临时深度诊断可以短期记录路径、config existence 等字段定位问题，但修复后应清理，避免长期暴露内部部署结构。
+5. 把这个约束写成项目契约或测试，防止以后又退回 cwd 推断。
+
+## Boundaries
+
+- 本地单进程脚本、一次性维护脚本、明确从仓库根执行的工具可以使用 `process.cwd()`，但要把这个前提写清楚。
+- 不要把密码、token、cookie 值、请求 body/header 值写入诊断产物。
+- 路径诊断是否保留要看用户场景：短期排查可以详细，长期产品化证据应收敛到必要布尔状态和可操作错误摘要。
+
+## Failed approaches
+
+- 先排查 cookie/sessionStorage、CORS、Chrome flags 和页面 JS 错误，虽然有价值，但没有直接回答“fixture 是否读到配置”。
+- 临时把 `configPath`、`configFilePresent`、`projectRoot` 等字段加入运行时证据能快速定位问题，但不适合作为长期默认产物。
+- 不推荐把配置复制到云端 cwd 对应目录；这会形成两份配置，后续 UI、测试和服务端可能读到不同来源。
+
+## Promotion record
+
+- Not promoted.
@@ -0,0 +1,63 @@
+---
+id: 20260715-codegraph-before-impact-analysis
+title: 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
+created: 2026-07-15
+updated: 2026-07-15
+status: candidate
+scope: global
+category: agent-workflows
+confidence: medium
+last_verified: 2026-07-15
+promotion_target: none
+projects:
+  - oppein-react-component
+tags:
+  - codegraph
+  - impact-analysis
+  - dependency-context
+  - agent-workflows
+---
+
+# 跨文件和共享 API 改动前先用 CodeGraph 建立依赖上下文
+
+## Trigger
+
+项目启用了 CodeGraph，且任务涉及跨包、跨目录或跨组件理解，调用链排查，重构、重命名、删除，或修改共享 API、类型、导出、hooks、服务接口和工具；也适用于需要评估回归范围或应补充哪些测试的任务。
+
+## Context
+
+当前项目的执行提示词将 CodeGraph 定位为影响分析的第一层上下文：先用代码关系索引缩小依赖范围，再回到源码、构建配置和精确文本核验，修改共享代码后再检查受影响文件和测试。这个流程既避免在陌生功能区盲目通读，也避免把图谱结果误当成完整事实。
+
+## Evidence
+
+- 2026-07-15：用户要求将当前项目的 CodeGraph 使用提示词沉淀到复利工程。
+- `oppein-react-component/AGENTS.md:23-58`：记录了 CodeGraph 的触发条件、`status`/`sync` 规则、`explore`/`query`/`node`/`impact`/`callers`/`callees`/`affected` 的选择，以及源码核验和常规质量验证边界。
+- 当前项目存在 `.codegraph/` 本地代码关系索引；该提示词明确要求首次使用时先检查索引状态。
+
+## Root cause
+
+已验证：代码关系图适合发现静态依赖、调用方和潜在影响范围，但不能可靠覆盖动态路径、字符串引用、构建配置和实现细节；索引过期时，图谱结论也可能失真。因此图谱只能用于缩小范围，不能单独证明“没有调用方”或“没有影响”。
+
+推断：把 CodeGraph 放在影响分析前段，并固定接上源码核验与变更后测试范围检查，可以减少漏查共享调用方和遗漏回归测试的风险。
+
+## Preferred action
+
+1. 任务首次需要 CodeGraph 时先运行 `codegraph status`；仅在索引不是最新时运行 `codegraph sync`。不要自行执行 `init`、`index` 或 `uninit`，除非用户明确要求，或索引缺失且无法继续完成任务。
+2. 按问题选择最小工具链：陌生模块用 `codegraph explore "<需求或模块>"`；查定义用 `codegraph query "<符号>"`，再用 `codegraph node "<符号>"` 阅读实现和调用链；修改共享 API 前用 `codegraph impact "<符号>"`，必要时补充 `callers` 和 `callees`。
+3. 以图谱结果缩小源码阅读和搜索范围；修改前直接阅读相关实现，并用 `rg` 核对动态路径、字符串引用、构建配置和精确文本。
+4. 共享代码修改完成后运行 `codegraph sync`，再用 `codegraph affected <改动文件>` 找出需要补充或执行的测试，最后仍按项目约定执行 lint、类型检查、构建和针对性测试。
+
+## Boundaries
+
+- 只有在项目启用 CodeGraph 且索引或对应 MCP 工具可用时，才直接套用这些命令；其他项目需先确认其工具和命令语义。
+- 用户已指定文件和行，且只是局部文案、注释、格式或显然不影响外部行为的小改动，以及单文件、无公共接口变化的机械性修复，可以跳过 CodeGraph。
+- CodeGraph 不能替代源码核验、`rg` 搜索、lint、类型检查、构建或测试；不要仅凭图谱结果断言不存在调用方或影响。
+
+## Failed approaches
+
+- 只依据图谱结果判断影响范围，会遗漏动态引用、配置驱动路径和未被索引覆盖的文本关系。
+- 直接执行 `sync`、`init` 或 `index` 而不先检查状态，会增加不必要的索引操作，并可能偏离项目约定。
+
+## Promotion record
+
+- Not promoted. 当前只有 `oppein-react-component` 的一份项目证据；待在另一项目或独立场景复用并验证后，再考虑提升为全局 guidance、skill 或可执行检查。
@@ -0,0 +1,107 @@
+---
+id: 20260724-bounded-list-flex-height-chain
+title: 有界列表页使用连续 Flex 高度链并收敛滚动视口
+created: 2026-07-24
+updated: 2026-07-24
+status: candidate
+scope: global
+category: frontend-layout
+confidence: medium
+last_verified: 2026-07-24
+promotion_target: none
+projects:
+  - usercenter-react
+tags:
+  - flex-layout
+  - min-height-zero
+  - bounded-workspace
+  - scroll-ownership
+  - data-table
+---
+
+# 有界列表页使用连续 Flex 高度链并收敛滚动视口
+
+## Trigger
+
+列表页、主从工作台或树表页面需要填满应用内容区，同时保持标题、筛选、操作栏和分页可见，只让表格数据区、树节点区或详情正文滚动；或者当前页面出现双滚动条、分页被挤出视口、`h-full` 不生效、窗口高度变化后布局失效。
+
+## Context
+
+`usercenter-react` 的商场管理页面曾需要移除固定像素高度推算，使应用外壳、路由页面、Tabs、组织树和数据表形成连续的有界高度链。修复后，普通内容页仍由共享 `<main>` 滚动，有界工作台则填满 `<main>` 并把滚动交给最小内容视口。
+
+这项经验的核心不是“给页面加 `flex-col`”，而是同时解决两个契约：高度从视口向后代连续传递，滚动权从外层收敛到最小内容区域。任一中间层缺少明确高度或 `min-h-0`，后代的 `h-full`、`flex-1` 和 `overflow-auto` 都可能无法按预期工作。
+
+## Evidence
+
+- 2026-07-24：重新检查 `usercenter-react` 当前源码、项目规范和 Git 历史；中央经验库搜索“有界列表页 / 连续 Flex 高度链 / min-h-0 / 滚动视口”无重叠条目。
+- `usercenter-react/src/shared/layout/app-layout.tsx:207-236`：应用根节点使用 `h-dvh overflow-hidden`，内容列使用 `flex h-full min-h-0 flex-col`，共享 `<main>` 使用 `min-h-0 flex-1 overflow-y-auto`。
+- `usercenter-react/src/features/market-management/pages/market-management-page.tsx:181-230`：有界路由根节点、分栏、Tabs 和 TabPane 连续使用 `h-full`、`flex-1`、`min-h-0` 与受控 overflow。
+- `usercenter-react/src/shared/table/data-table.tsx:40-45,168-232`：`fillHeight` 以 opt-in 方式把表格面板变成有界 Flex 列，工具栏和分页留在滚动视口之外，数据区域消费剩余高度。
+- `usercenter-react/.trellis/spec/frontend/layout-guidelines.md:23-32,74-125`：记录了各布局边界的类契约、滚动归属、错误矩阵和禁止使用固定 `calc(100vh - Npx)` 的规则。
+- `usercenter-react/specs/page-layout.spec.md:5-11`：产品级规范要求有界页面使用连续 Flex 高度链，并将 overflow 委托给最小树或数据视口。
+- Git 提交 `ccf068c` 修复商场管理页面高度适配，`1bb14e8` 将实践整理为 bounded layout 指南，`849219a` 继续补充可伸缩侧栏场景下的表格滚动与 sticky 边界。
+- 当前仓库的 `src/shared/list-templates/master-detail-list-template.tsx:34-60` 仍存在 `calc(100vh - 10.5rem)` 实现；这是需要结合响应式父级契约进一步验证的现有反例，不能仅凭规则直接判定或修改。
+
+## Root cause
+
+已验证：
+
+- `flex-col` 和 `flex-1` 只负责空间分配，不会自动建立可解析的高度边界。
+- Flex/Grid 子项默认的 `min-height: auto` 会阻止内容区域收缩；中间层缺少 `min-h-0` 时，内容会撑高页面而不是在指定视口内滚动。
+- `h-full` 依赖祖先提供确定高度；高度链中断时，百分比高度不能可靠地代表剩余视口空间。
+- 页面、共享 `<main>` 和表格数据区同时拥有纵向 overflow 时，会形成嵌套或竞争滚动条。
+- `calc(100vh - Npx)`、JavaScript 测量和重复的标题高度常量容易在工具栏换行、外壳调整、缩放或窄屏布局下失效。
+
+推断：把布局评审固定为“先从外向内检查高度链，再从内向外确认唯一滚动所有者”，比逐个添加高度类或 overflow 类更容易定位缺失环节，也更适合跨组件复用。
+
+## Preferred action
+
+1. 先区分页面模式：普通内容页继续由应用 `<main>` 滚动；只有需要固定控制区和内部滚动的页面才进入有界模式。
+2. 从视口向目标滚动区域建立连续高度链：应用根节点建立动态视口边界，中间内容列使用 `flex h-full min-h-0 flex-col`，有界路由根节点使用 `flex h-full min-h-0 flex-col overflow-hidden`。
+3. 为所有需要消费剩余高度或继续向下传递高度的 Flex/Grid 中间层添加 `min-h-0`；不要只修改最终表格容器。
+4. 标题、筛选、操作栏、Tabs 头部和分页等固定区域使用 `shrink-0`。剩余内容区域使用 `min-h-0 flex-1`。
+5. 将纵向滚动交给最小内容视口：通常是表格数据区、树节点区或详情正文。结构层使用 `overflow-hidden`，实际内容视口使用 `overflow-auto` 或 `overflow-y-auto`。
+6. 共享表格的填高能力保持 opt-in；只有父级已经提供有界 `h-full/min-h-0` 区域时才启用，避免改变普通内容型页面的默认行为。
+7. 优先使用 Flex 剩余空间，不使用固定 `calc(100vh - Npx)`、JavaScript 高度测量或跨组件共享的像素常量。
+8. 在真实浏览器中验证滚动归属：有界页面不增加 body 高度，固定控制区和分页保持可见，只有目标数据区滚动；同时检查窄屏、工具栏换行、loading、empty 和 error 状态。类型检查、lint 和构建不能替代这项验证。
+
+## Examples
+
+```tsx
+<div className="h-dvh overflow-hidden">
+  <div className="flex h-full min-h-0 flex-col">
+    <main className="min-h-0 flex-1 overflow-y-auto">
+      <section className="flex h-full min-h-0 flex-col overflow-hidden">
+        <header className="shrink-0">{header}</header>
+        <div className="shrink-0">{filtersAndActions}</div>
+        <div className="min-h-0 flex-1 overflow-hidden">
+          <DataTable fillHeight {...tableProps} />
+        </div>
+      </section>
+    </main>
+  </div>
+</div>
+```
+
+记忆方式：高度从外向内连续传递，滚动权收敛到最小内容视口。
+
+## Boundaries
+
+- 普通详情页、表单页和自然增长的长页面通常应继续由共享 `<main>` 滚动，不要为了统一外观强制启用有界模式。
+- 移动端主从区域改为纵向堆叠时，可能更适合自然页面滚动；有界模式可以只在桌面断点启用。
+- `overflow-hidden` 只有在后代明确拥有滚动视口时才安全，否则会直接裁切内容。
+- Tabs、Drawer、Spin、Table 和虚拟列表等第三方组件可能插入包装层，需要根据实际 DOM 补齐高度链或沿用组件自己的滚动机制。
+- 可交互变宽的分栏可能触发第三方表格的 ResizeObserver 和 sticky 行为；`nativeStickyHeader`、固定列实现等属于组件或项目特例，不是连续 Flex 高度链的通用要求。
+- 已存在的 `calc(100vh - Npx)` 不应机械替换；需要先确认页面父级是否能提供完整高度链，以及窄屏模式是否依赖自然内容高度。
+- 当前证据主要来自 `usercenter-react` 的一次完整修复及后续演进。在另一个项目或独立场景复用并完成浏览器验证前，不提升为全局强制规则。
+
+## Failed approaches
+
+- 只在页面根节点增加 `flex-col` 或只在表格增加 `flex-1`：高度链仍可能在中间层中断。
+- 只给最终内容区域增加 `overflow-auto`：默认 `min-height: auto` 仍可能让它撑高父级。
+- 同时让 `<main>`、路由根节点和表格数据区滚动：容易出现双滚动条、滚轮焦点切换和分页被挤出视口。
+- 通过 `calc(100vh - Npx)` 或 JavaScript 测量补偿标题高度：在标题、操作栏换行或应用外壳变化后容易产生新的固定偏差。
+
+## Promotion record
+
+- Not promoted. 当前已有一个项目中的修复、规范和后续演进证据，先保留为中央 candidate；待第二个项目或独立场景验证后，再考虑提升为 `patterns/` 下的前端布局模式或可执行浏览器检查。
@@ -0,0 +1,7 @@
+# Inbox
+
+保存刚从任务、用户纠正、失败路径或成功实践中提取的候选经验。
+
+候选经验尚不能直接视为全局规则。验证后移动到 `learnings/`；没有复用价值的内容直接删除。
+
+文件命名：`YYYYMMDD-short-slug.md`。
@@ -0,0 +1,93 @@
+# AI Coding 复利大脑
+
+这里是跨项目 AI coding 经验的统一来源，用于捕获、验证、检索、提升和审计可复用经验。
+
+## 工作流
+
+```text
+项目任务
+  → inbox 候选经验
+  → learnings 已验证经验
+  → patterns 跨项目模式
+  → assets 可执行资产
+  → 项目 AGENTS / 测试 / hooks / skills
+```
+
+## 导航
+
+- [[inbox/index|Inbox]]：尚未验证的候选经验
+- [[learnings/index|Learnings]]：有证据支持的经验
+- [[patterns/index|Patterns]]：跨项目验证的通用模式
+- [[projects/index|Projects]]：项目索引和同步状态
+- [[experiments/index|Experiments]]：模型、提示词和工作流实验
+- [[assets/index|Assets]]：可以下发的规则、Skill、hook 和 eval
+- [[maintenance/index|Maintenance]]：冲突、过期和待提升内容
+
+## 经验 Meta 字段
+
+每份经验的 YAML frontmatter 使用以下 12 个字段。除特别说明外，字段都应填写；当前 `brain.py validate` 会强制校验前 10 个标量字段，`projects` 和 `tags` 由 schema 约定为必填列表，但暂未被校验脚本强制检查。
+
+| 字段 | 含义 | 格式或枚举值 |
+|---|---|---|
+| `id` | 经验的稳定唯一标识，也用于文件名和检索。 | `YYYYMMDD-short-slug`；日期后接小写字母、数字或连字符，例如 `20260724-bounded-list-flex-height-chain`。 |
+| `title` | 清晰、可搜索的经验标题，应概括触发场景和核心做法。 | 自由文本，无固定枚举。 |
+| `created` | 首次创建该经验的日期。 | `YYYY-MM-DD`。 |
+| `updated` | 最近一次实质更新该经验内容或元信息的日期。 | `YYYY-MM-DD`。 |
+| `status` | 经验在验证与提升生命周期中的状态。 | `candidate`、`validated`、`promoted`、`stale`、`superseded`。 |
+| `scope` | 经验适用范围的最小边界。 | `global`、`repository`、`module`。 |
+| `category` | 用于按问题域或实践类型归类和检索。 | 自由的 kebab-case 分类，无固定枚举；当前已有 `agent-workflows`、`debugging`、`frontend-layout`。 |
+| `confidence` | 基于现有证据，对经验可靠程度的判断。 | `low`、`medium`、`high`。 |
+| `last_verified` | 最近一次用当前代码、运行结果、文档或其他证据核验该经验的日期；只有实际复核后才更新。 | `YYYY-MM-DD`。 |
+| `promotion_target` | 该经验已经提升到或计划提升到的最小持久化执行载体；尚无目标时填 `none`。 | `none`、`global-agents`、`repo-agents`、`skill`、`test`、`lint`、`hook`、`script`、`docs`、`pattern`、`eval`。 |
+| `projects` | 产生、验证或适用过该经验的项目，用于追溯证据与判断是否跨项目成立。 | YAML 字符串列表，无固定枚举；使用稳定的项目名。 |
+| `tags` | 更细粒度的检索关键词，描述技术、组件、故障模式或工作流。 | YAML 字符串列表，无固定枚举；建议使用简短的 kebab-case 标签。 |
+
+### `status` 枚举含义
+
+| 值 | 含义 |
+|---|---|
+| `candidate` | 刚捕获的候选经验，已有复用信号，但证据还不足以作为稳定规则。 |
+| `validated` | 已有当前、可检查的证据支持，适用边界也已确认。 |
+| `promoted` | 已写入并验证某个持久化载体；具体载体记录在 `promotion_target` 和 `Promotion record` 中。 |
+| `stale` | 当前真实性不确定，或已被新代码、证据、文档或执行载体否定；不能直接复用。 |
+| `superseded` | 已由更新、更完整的规范经验替代；应指向替代项，避免继续作为主来源。 |
+
+### `scope` 枚举含义
+
+| 值 | 含义 |
+|---|---|
+| `global` | 跨仓库、跨项目通常成立，但复用前仍需核对当前上下文。 |
+| `repository` | 只对某个仓库的命令、架构、约定或运行环境成立。 |
+| `module` | 只对仓库内某个模块、组件或局部边界成立。 |
+
+### `confidence` 枚举含义
+
+| 值 | 含义 |
+|---|---|
+| `low` | 主要是初步观察或推断，证据有限，复用前需要重点验证。 |
+| `medium` | 有明确实例或验证结果支持，但复现次数、覆盖范围或边界仍有限。 |
+| `high` | 有强且可复查的证据，通常经过独立复现、跨项目验证，或有高严重度事件及已验证的预防机制。 |
+
+### `promotion_target` 枚举含义
+
+| 值 | 含义 |
+|---|---|
+| `none` | 尚未决定或不需要提升到其他载体。 |
+| `global-agents` | 跨仓库稳定适用的个人全局 Agent 指引。 |
+| `repo-agents` | 特定仓库的 `AGENTS.md` 规则或约定。 |
+| `skill` | 有清晰触发条件、输入、输出和验证方式的可复用多步工作流。 |
+| `test` | 用自动化测试守护可确定验证的行为或不变量。 |
+| `lint` | 用静态检查规则发现可机械识别的问题。 |
+| `hook` | 在提交、推送或其他生命周期节点自动执行的检查或动作。 |
+| `script` | 用可重复运行的脚本固化操作、检查或修复流程。 |
+| `docs` | 与项目代码或运行方式绑定的解释性文档。 |
+| `pattern` | 至少经过两次独立验证的跨项目工程原则或规范模式。 |
+| `eval` | 针对可复现的 Agent 行为回归建立评测用例和可观察的通过标准。 |
+
+## 原则
+
+- 笔记数量不是指标，行为改善才是。
+- 项目事实留在项目中；这里保存索引、证据和跨项目归纳。
+- 先搜索再读取，避免把整个知识库注入上下文。
+- 能用测试、lint、hook 或脚本执行的规则，不只保留为文字。
+- 所有经验都要说明边界和最后验证日期。
@@ -0,0 +1,14 @@
+# Learnings
+
+保存已有明确证据、适用边界和首选行动的经验。
+
+按实际增长情况建立主题目录，例如：
+
+- debugging
+- planning
+- testing
+- review
+- context-engineering
+- agent-workflows
+
+不要预先创建空分类。
@@ -0,0 +1,3 @@
+# Conflicts
+
+当前没有待处理冲突。
@@ -0,0 +1,7 @@
+# Maintenance
+
+- [[conflicts]]：互相冲突、需要进一步验证的经验
+- [[promotion-queue]]：已满足证据条件、等待提升的经验
+- [[stale]]：当前真实性不足或执行资产已经漂移的经验
+
+年龄本身不是过期证据。应根据代码、工具、文档和实际行为判断。
@@ -0,0 +1,3 @@
+# Promotion Queue
+
+当前没有等待提升的经验。
@@ -0,0 +1,3 @@
+# Stale
+
+当前没有标记为 stale 的经验。
@@ -0,0 +1,11 @@
+# Patterns
+
+保存至少经过两个独立项目或场景验证的跨项目模式。
+
+Pattern 应说明：
+
+- 触发条件
+- 核心机制
+- 适用与不适用边界
+- 支撑它的 learning
+- 已提升到哪些执行资产
@@ -0,0 +1,11 @@
+# Projects
+
+为每个项目维护一份简短索引，记录：
+
+- 仓库位置
+- 项目内知识入口
+- 已贡献到公共仓库的经验
+- 从公共仓库同步回项目的规则或资产
+- 最后审计日期
+
+项目专属事实和强制规则仍以项目仓库为准。