Imported from Fuxx-1/git-vws (AGENTS.md). Install upstream with npx skills add Fuxx-1/git-vws. Copyright stays with the author.

AGENTS.md

AI 协作规范，适用于所有在本项目中工作的 Agent。

所有输出（文档、代码、分析）分点和描述适当，不过度扩展。

工作模式

plan 模式

在 docs/ 目录下创建变更描述文档：

• 文件命名：{变更简述（5字）}.{uuid（无连接符五位）}.md，例：统一过滤器架构.a3f9c.md
• 文档结构：现状 → 目标 → 影响范围 → 架构示意（可选 Mermaid）→ Todo 列表
• 写作要求：整体描述变更，不写具体实现细节（无代码片段、无函数名列表）
• 影响范围标注：涉及 lc 时按 docs/archieved/lc能力地图.7d4e2.md 三层（入口面 / 业务核心 / 基础设施）+ 专项子系统坐标系标注，避免跨议题术语漂移。
• Todo 列表：文档末尾必须包含 ## Todo 章节，以有序列表列出实施步骤，每条对应一个可独立执行的变更单元，格式：- [ ] {步骤描述}

文档生命周期

• docs/ 顶层：只承载"在飞的"plan 文档，即当前 Todo 未走完或方案仍在演进的变更。Agent 看 docs/ 顶层 = 看仓库当前活跃议题。
• docs/archieved/：归档目录，存放已完成、已落地、已作废、已被取代（superseded）的历史 plan 文档。只读引用，不在此处新建或继续编辑。
• 归档时机：满足下列任一条件即从 docs/ 顶层 mv 到 docs/archieved/：
  • Todo 列表全部勾选完成且代码已落地；
  • 文档自标"已作废（superseded）"或被新 plan 取代；
  • 仅作历史现状陈述、不再驱动后续变更。
• 归档不改写历史：保留原文不动；如有新方案推翻旧描述，应在原文件顶部加 banner 注明"以下为历史，参见 xxx.{uuid}.md"，再 mv 入档。
• 不要重新激活：归档后的文档不再回流到顶层；如需在旧议题上推进，请在 docs/ 顶层新建 plan 并在其中引用归档文件。

长期文档单源（飞书 Wiki）

• 统一入口：项目整体性、长期维护的文档统一维护在 LingChain 文档根节点 及其子文档；该 Wiki 是整体架构、模块与目录、命令契约、能力现状、成熟度和事实边界的单一事实源。
• 父子结构：根节点只保留整体总览与导航；正文按稳定主题拆成子文档。单篇持续变大时继续拆分，不在根节点或单个子文档堆积全部内容。
• 同步责任：涉及架构边界、模块归属、目录组织、CLI 命令、能力增删或成熟度变化的任务，完成前必须同步更新对应 Wiki 子文档，并从根节点保持可发现。
• 本地边界：docs/ 继续只承载在飞 plan 和历史归档；构建、协议或代码审查必须随仓库版本化的材料可留在本地。不要在仓库新增与 Wiki 重复的长期综述文档。
• 引用而非复制：本地 plan 需要整体背景时引用 Wiki 根节点或对应子文档，不复制长期正文；Wiki 内容过大时优先新增子文档并补导航。

bug 模式（plan 之外的零散问题池）

不值得单开 plan 的小修小补、e2e 偶发现象、兼容性补丁，统一记到 lc/examples/bug.md：

• 职责边界：成体系的架构变更走 plan；单点问题、一行修法、待跟进观察项走 bug.md。
• 位置固定：lc/examples/bug.md，永不归档、永不分裂、永不重命名。
• 格式：扁平 Todo 列表，新问题 append 到末尾，- [ ] {问题简述} — {根因/修法摘要}。
• 已修即删：修复落地后从本文删除条目；历史走 git log 查，本文只存活跃问题，避免越积越长。
• 不要写实现细节：一行讲清问题与落点即可，具体代码落提交。
• 被 plan 接管：条目升级为 plan 后从本文删除，由 plan 单源跟进。

注意事项

命令执行

• 所有命令末尾必须带换行（\n），确保 shell 正常接收并执行。
• 不要在同一行拼接多个命令（使用 && 或分号时务必确认换行符存在）。
• 避免在命令中硬编码路径，优先使用项目根目录相对路径或环境变量。
• 执行 node、npm、pnpm、npx、vite、vue-tsc、tsc 等前端 / Node 相关命令前，必须先通过 nvm 进入正确的 Node 运行时；若项目存在 .nvmrc，优先按 .nvmrc 指定版本执行。
• 涉及文件删除、状态变更的命令视为不安全命令，执行前必须获得用户确认。
• 禁止使用 cat << 'EOF' > 命令写入文件
• git commit 消息必须简短（单行 ≤50 字，必要时附 1–3 行 bullet）；不要用 heredoc 多行长篇提交，容易卡 shell。

代码修改

• 优先最小化 diff，不引入无关变更。
• 不新增注释或文档，除非用户明确要求。
• 修改后必须通过 cargo check（Rust）或等效命令验证编译通过。
• 专项子系统对外暴露（computer / deepidx / graph_index / file_search/editor/todo/index 等）遵循 docs/archieved/lc能力地图.7d4e2.md "易用性原则"：默认低认知负担、零必填上限（必填 ≤ 1）、复杂度按需解锁（高级行为走 flag）、输出契约统一（envelope {ok,code,...} + NDJSON）、AI 友好（大产物落盘只回路径）、失败可读（稳定 code + 自然语言 message）；CLI / HTTP / MCP / DAG 四入口的默认值与可选档必须一致。

文件管理

• 不在工作区随意创建临时文件（tmp/、*.bak 等）。
• 新建文件前确认路径不与现有文件冲突。

前端组件设计准则

LingChain 前端的设计纪律以 frontend/rule.md 为唯一权威，所有改动必须遵守。三大主张（详见 frontend/rule.md）：

• 主张 A · 内容感小组件优先：业务页 = 内容感小组件 + 极少量布局；禁止自写 chrome（btn-* / *-btn / *-badge / *-card / *-dot / *-chip / *-pill / *-tag）。任一 .vue 文件自创 chrome class 数 ≤ 8，违反由 npm run check:chrome 阻断。
• 主张 B · 稀缺资源纪律：强调色 / 玻璃 / 大阴影 / 大圆角 / 大字号档按"全 app 出现位置上限"约束（accent ≤ 30 / glass ≤ 5 / shadow-xl ≤ 5 / radius-pill ≤ 10 / text-xl+ ≤ 30）。默认中性，强调是稀缺事件。
• 主张 C · 一个壳、一种按下感：所有业务页用 <AppShell> + <ViewHeader> 为根；按下感统一 lc-interactive（scale 0.97 + 120ms standard），禁止自写 :active scale(0.9~0.96/0.98) 或 translateY 变体。

完成定义（DoD）：npm run build / check:i18n / check:layout / check:tokens / check:press / check:chrome / check:a11y 全绿 + 各项指标不回弹。二期由 docs/二期迭代规划.2f9a1.md 主题 G 统一收口；历史细节见 docs/archieved/去草稿感.h7e2c.md 等设计纪律集群归档文档。