From c83a85538076b4c94e5e4ac8aef5dcba764b1916 Mon Sep 17 00:00:00 2001 From: rui Date: Fri, 3 Jul 2026 21:57:44 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E8=BF=81=E7=A7=BB=E6=9C=AC=E4=BB=93?= =?UTF-8?q?=E8=87=B3=20v0.3.1=20=E5=B7=A5=E4=BD=9C=E6=B5=81=E7=98=A6?= =?UTF-8?q?=E8=BA=AB=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - reference/rules/*.md 真源大瘦身：删 CRITICAL / 自动化归档守卫两段 - 真源标题脱敏（去 灵枢/LingShu 自称与 emoji），保留 中枢-肢体 技术隐喻 - 真源 frontmatter 精简至只留 order - 目录重构：reference/management/{plans,tasks,walkthroughs,reports}/ → reference/decisions/（ADR） - 删除 reference/experience/ 与 5 篇示例经验（改为按需自建） - reference/docs/README.md 新增可选扩张建议（prd/tad/api/schema） - 本仓 CI workflow 品牌措辞与模板对齐 - CLAUDE.md / AGENTS.md 由 lingshu@0.3.1 重生成（头部去品牌自称） --- .github/workflows/rules-consistency.yml | 5 +- AGENTS.md | 111 +++++++----------- CLAUDE.md | 111 +++++++----------- README.md | 13 +- reference/README.md | 6 +- reference/decisions/README.md | 38 ++++++ reference/docs/README.md | 28 +++-- reference/experience/README.md | 8 -- .../pitfalls/001-port-drifting-fix.md | 36 ------ .../pitfalls/002-agent-browser-blind-retry.md | 24 ---- reference/experience/pitfalls/backend-sync.md | 8 -- reference/experience/prompts/ui-generation.md | 12 -- .../management/plans/ITERATION_TEMPLATE.md | 21 ---- reference/management/plans/README.md | 11 -- reference/management/reports/README.md | 11 -- reference/management/tasks/README.md | 10 -- reference/management/walkthroughs/README.md | 10 -- reference/rules/ai-behavior.md | 60 +++------- reference/rules/lingshu-core.md | 55 ++++----- 19 files changed, 194 insertions(+), 384 deletions(-) create mode 100644 reference/decisions/README.md delete mode 100644 reference/experience/README.md delete mode 100644 reference/experience/pitfalls/001-port-drifting-fix.md delete mode 100644 reference/experience/pitfalls/002-agent-browser-blind-retry.md delete mode 100644 reference/experience/pitfalls/backend-sync.md delete mode 100644 reference/experience/prompts/ui-generation.md delete mode 100644 reference/management/plans/ITERATION_TEMPLATE.md delete mode 100644 reference/management/plans/README.md delete mode 100644 reference/management/reports/README.md delete mode 100644 reference/management/tasks/README.md delete mode 100644 reference/management/walkthroughs/README.md diff --git a/.github/workflows/rules-consistency.yml b/.github/workflows/rules-consistency.yml index 107cd95..18d90ce 100644 --- a/.github/workflows/rules-consistency.yml +++ b/.github/workflows/rules-consistency.yml @@ -1,8 +1,9 @@ # ========================================== -# 灵枢架构 — CI 一致性守护 (GitHub Actions) +# CI 一致性守护 (GitHub Actions) # ========================================== # 防止 reference/rules/ 真源与基线工具产物（CLAUDE.md / AGENTS.md）发生漂移。 # 仅校验 baseline 工具，因为只有它们入库；个人偏好工具产物在 .gitignore 中。 +# 通过 npx 调用全局 CLI，仓库内不携带同步引擎。 name: rules-consistency @@ -17,7 +18,7 @@ on: jobs: rules-consistency: - name: 校验灵枢规则一致性（baseline 工具） + name: 校验规则一致性（baseline 工具） runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/AGENTS.md b/AGENTS.md index 5412ca3..9b6ad8f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,104 +2,79 @@ -# 灵枢 (LingShu) — AI Agents 项目指令 +# AI Agents 项目指令 -> 本文件由 `lingshu sync` 自动生成。所有规则的真理来源位于 `reference/rules/`。 +> 本文件由 `lingshu sync` 自动生成，真源位于 `reference/rules/`。 --- -# 灵枢架构核心准则 (LingShu Core Principles) +# 架构核心准则 -## 1. 架构拓扑定义 (Architecture Topology) -本仓库遵循 **LingShu** 架构，实行"逻辑中枢"与"执行肢体"的物理分离。 +## 1. 拓扑定义 +本仓库采用"中枢-肢体"分层结构： -- **🧠 中枢仓 (The Brain)**: - - **路径**: 当前根目录 `./` - - **职责**: 定义真理 (Reference)、规则 (Rules)、计划 (Plans) 与审计 (Audit)。 - - **特征**: 仅追踪文档与配置，不应包含业务源代码。 +- **中枢仓 (The Brain)**： + - **路径**：当前根目录 `./` + - **职责**：定义真源（Reference）、规则（Rules）与架构决策（Decisions）。 + - **特征**：仅追踪文档与配置，不包含业务源代码。 -- **💪 肢体仓 (The Limbs)**: - - **路径**: 根目录下的具体工程子目录（通常命名为 `*-server`, `*-ui`, `*-mobile`, `*-web`）。 - - **职责**: 承载具体的业务代码实现。 - - **识别规则**: AI 需自动扫描根目录，识别包含 `.git` (子模块/嵌套仓) 或具体语言配置（如 `pyproject.toml`, `package.json`）的子文件夹作为"肢体"。 +- **肢体仓 (The Limbs)**： + - **路径**：根目录下的具体工程子目录（通常命名为 `*-server`、`*-ui`、`*-mobile`、`*-web`）。 + - **职责**：承载具体的业务代码实现。 + - **识别规则**：AI 需自动扫描根目录，识别包含 `.git`（子模块 / 嵌套仓）或具体语言配置（如 `pyproject.toml`、`package.json`）的子文件夹作为"肢体"。 -## 2. Git 物理隔离规则 (Git Isolation Rules) +## 2. Git 物理隔离规则 由于采用嵌套仓库结构，必须严格遵守以下操作边界： -- **🚫 禁止根目录通配提交**: - - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 +- **禁止根目录通配提交**： + - **严禁**在根目录执行 `git add .` 或 `git commit -a`——这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 + - 根目录 Git **仅允许**追踪：`reference/` 治理资产（真源规则、docs、可选 decisions/），以及 AI 工具基线产物（`CLAUDE.md`、`AGENTS.md`）。 -- **✅ 肢体仓独立提交**: +- **肢体仓独立提交**： - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 - 确认 `git status` 显示的是子仓库的状态后，再执行提交。 -- **🛡️ 提交前自检 (Pre-commit Check)**: +- **提交前自检**： - AI 在生成 Git 指令前，必须判断当前变更的文件路径。 - 若路径属于 `*-server/` 或 `*-ui/`，必须输出 `cd` 指令作为前置操作。 -## 3. 规则真源约束 (SSoT for Rules) +## 3. 规则真源约束（SSoT） -- **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 -- **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 - -## 4. 环境与依赖标准 (Stack Standard) -*（注：此部分定义模版默认技术栈，可随项目调整）* -- **Python 环境**: 推荐使用 `uv` 或 `pip` 管理依赖。 - - Windows 特殊指令: `uv` 相关命令须带 `--link-mode copy --no-install-project`。 -- **Node 环境**: 推荐使用 `npm` 管理依赖与脚本（团队统一标准）。 -- **交互语言**: 始终使用 **简体中文**。 +- **真源唯一**：所有 AI 行为规则的真源位于 `reference/rules/`。 +- **产物只读**：`.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为**由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**：规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 +- **CI 保障**：GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 --- --- -# 🤖 灵枢智能体行为准则 (Agentic Workflow) - -## 1. 思考模式：真理驱动 (Truth Driven) -在 **Ask 模式** 或 **Composer 模式** 中，遵循以下逻辑链： - -1. **🔍 寻源 (Locate Truth)**: - - 遇到需求变更，**首先** 检查 `reference/docs/` 下的 API 契约、数据库 Schema 或 PRD。 - - 若文档未定义，先建议用户更新文档，而不是直接写代码。 - - **口号**: "逻辑不入中枢，代码不动分毫。" - -2. **📝 规划 (Planning)**: - - 进入 Composer (Plan) 模式后，必须生成/更新 `.plan.md`。 - - **强制存档 (CRITICAL)**: 在执行代码修改前，必须将当前的 `.plan.md` 完整复制备份到 `reference/management/plans/` 目录下，并更新 `reference/management/tasks/` 中的执行清单。文件名格式建议：`YYYYMMDD-TaskName.md`。 - -3. **⚡ 执行 (Execution)**: - - **跨端同步**: 始终检查后端变更对前端的影响（如 API 字段变动），并主动提示同步修改。 - - **原子化**: 每次只处理一个具体的逻辑闭环，避免跨多个不相关的功能模块修改。 +# AI 智能体行为准则 -## 2. 自动化归档守卫 (Archival Guard) -每当一个任务进入 **Done** 状态，AI 必须强制执行以下同步操作： +## 1. 工作模式：真理驱动（软建议） -1. **方案固化**: 将最终修订的 `.plan.md` 完整备份至 `reference/management/plans/`。 -2. **存证生成**: 生成一份详尽的 `Walkthrough`，记录本次重构的逻辑决策、核心代码变更及验证结果，存放至 `reference/management/walkthroughs/`。 -3. **任务闭环**: 更新 `reference/management/tasks/` 中的执行记录，标注所有步骤已完成。 -4. **专项审计 (Conditional)**: - - 若本次任务涉及 **数据库变更** (Schema/Migration)，必须在 `reference/management/reports/` 中生成一份 `Migration_Report`。 - - 文件命名标准: `YYYYMMDD_ID_TaskName.[plan|tasks|walkthrough|report].md` +- **寻源优先**：遇到需求变更，先看 `reference/docs/` 下的 API 契约、Schema、PRD； + 文档未定义时，建议先更新文档再动代码。 +- **跨端同步**：后端契约变动时主动提示前端影响。 +- **原子化**：一次专注一个逻辑闭环，避免跨模块混合变更。 -## 3. 交付规约 (Delivery Protocol) +## 2. 归档（可选，仅架构决策） -- **交互语言**: 始终使用 **简体中文** 进行对话回复。 -- **Git 提交信息格式**: - - **语言**: 必须使用 **简体中文** 描述变更。 - - **中枢仓**: `docs: <描述>`, `chore: <描述>`, `plan: <描述>` - - *示例*: `docs: 更新发票 API 契约` - - **肢体仓**: `(): <描述>` - - *示例*: `feat(storage): 实现文件生命周期管理` +- **值得留档的场景**：架构决策、数据库迁移、破坏性 API 变更、跨仓协议变更、 + 事故复盘的决策链条。 +- **载体**：`reference/decisions/`（ADR 格式，命名 `ADR-NNNN-.md`）。 +- **日常任务不归档**——决策链条走 Git commit message + PR 描述即可。 +- **判断权**：由 AI 或用户显式判定是否值得写 ADR，不再强制。 -- **分支管理**: - - 开发工作必须在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 +## 3. 交付规约 -- **自我修正 (Self-Correction)**: - - 如果用户指出代码与文档不符，**必须** 优先以文档（中枢真理）为准进行修正，或者询问用户是否需要反向更新文档。 +- **交互语言**：始终使用简体中文。 +- **Git 提交信息**（中文描述）： + - 中枢仓：`docs: <描述>` / `chore: <描述>` + - 肢体仓：`(): <描述>`（例：`feat(storage): 实现文件生命周期管理`） +- **分支管理**：开发在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 +- **自我修正**：代码与文档不符时优先以文档为准，或询问用户是否反向更新文档。 --- diff --git a/CLAUDE.md b/CLAUDE.md index 4121080..714222b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,104 +2,79 @@ -# 灵枢 (LingShu) — Claude Code 项目指令 +# Claude Code 项目指令 -> 本文件由 `lingshu sync` 自动生成。所有规则的真理来源位于 `reference/rules/`。 +> 本文件由 `lingshu sync` 自动生成，真源位于 `reference/rules/`。 --- -# 灵枢架构核心准则 (LingShu Core Principles) +# 架构核心准则 -## 1. 架构拓扑定义 (Architecture Topology) -本仓库遵循 **LingShu** 架构，实行"逻辑中枢"与"执行肢体"的物理分离。 +## 1. 拓扑定义 +本仓库采用"中枢-肢体"分层结构： -- **🧠 中枢仓 (The Brain)**: - - **路径**: 当前根目录 `./` - - **职责**: 定义真理 (Reference)、规则 (Rules)、计划 (Plans) 与审计 (Audit)。 - - **特征**: 仅追踪文档与配置，不应包含业务源代码。 +- **中枢仓 (The Brain)**： + - **路径**：当前根目录 `./` + - **职责**：定义真源（Reference）、规则（Rules）与架构决策（Decisions）。 + - **特征**：仅追踪文档与配置，不包含业务源代码。 -- **💪 肢体仓 (The Limbs)**: - - **路径**: 根目录下的具体工程子目录（通常命名为 `*-server`, `*-ui`, `*-mobile`, `*-web`）。 - - **职责**: 承载具体的业务代码实现。 - - **识别规则**: AI 需自动扫描根目录，识别包含 `.git` (子模块/嵌套仓) 或具体语言配置（如 `pyproject.toml`, `package.json`）的子文件夹作为"肢体"。 +- **肢体仓 (The Limbs)**： + - **路径**：根目录下的具体工程子目录（通常命名为 `*-server`、`*-ui`、`*-mobile`、`*-web`）。 + - **职责**：承载具体的业务代码实现。 + - **识别规则**：AI 需自动扫描根目录，识别包含 `.git`（子模块 / 嵌套仓）或具体语言配置（如 `pyproject.toml`、`package.json`）的子文件夹作为"肢体"。 -## 2. Git 物理隔离规则 (Git Isolation Rules) +## 2. Git 物理隔离规则 由于采用嵌套仓库结构，必须严格遵守以下操作边界： -- **🚫 禁止根目录通配提交**: - - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 +- **禁止根目录通配提交**： + - **严禁**在根目录执行 `git add .` 或 `git commit -a`——这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 + - 根目录 Git **仅允许**追踪：`reference/` 治理资产（真源规则、docs、可选 decisions/），以及 AI 工具基线产物（`CLAUDE.md`、`AGENTS.md`）。 -- **✅ 肢体仓独立提交**: +- **肢体仓独立提交**： - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 - 确认 `git status` 显示的是子仓库的状态后，再执行提交。 -- **🛡️ 提交前自检 (Pre-commit Check)**: +- **提交前自检**： - AI 在生成 Git 指令前，必须判断当前变更的文件路径。 - 若路径属于 `*-server/` 或 `*-ui/`，必须输出 `cd` 指令作为前置操作。 -## 3. 规则真源约束 (SSoT for Rules) +## 3. 规则真源约束（SSoT） -- **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 -- **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 - -## 4. 环境与依赖标准 (Stack Standard) -*（注：此部分定义模版默认技术栈，可随项目调整）* -- **Python 环境**: 推荐使用 `uv` 或 `pip` 管理依赖。 - - Windows 特殊指令: `uv` 相关命令须带 `--link-mode copy --no-install-project`。 -- **Node 环境**: 推荐使用 `npm` 管理依赖与脚本（团队统一标准）。 -- **交互语言**: 始终使用 **简体中文**。 +- **真源唯一**：所有 AI 行为规则的真源位于 `reference/rules/`。 +- **产物只读**：`.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为**由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**：规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 +- **CI 保障**：GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 --- --- -# 🤖 灵枢智能体行为准则 (Agentic Workflow) - -## 1. 思考模式：真理驱动 (Truth Driven) -在 **Ask 模式** 或 **Composer 模式** 中，遵循以下逻辑链： - -1. **🔍 寻源 (Locate Truth)**: - - 遇到需求变更，**首先** 检查 `reference/docs/` 下的 API 契约、数据库 Schema 或 PRD。 - - 若文档未定义，先建议用户更新文档，而不是直接写代码。 - - **口号**: "逻辑不入中枢，代码不动分毫。" - -2. **📝 规划 (Planning)**: - - 进入 Composer (Plan) 模式后，必须生成/更新 `.plan.md`。 - - **强制存档 (CRITICAL)**: 在执行代码修改前，必须将当前的 `.plan.md` 完整复制备份到 `reference/management/plans/` 目录下，并更新 `reference/management/tasks/` 中的执行清单。文件名格式建议：`YYYYMMDD-TaskName.md`。 - -3. **⚡ 执行 (Execution)**: - - **跨端同步**: 始终检查后端变更对前端的影响（如 API 字段变动），并主动提示同步修改。 - - **原子化**: 每次只处理一个具体的逻辑闭环，避免跨多个不相关的功能模块修改。 +# AI 智能体行为准则 -## 2. 自动化归档守卫 (Archival Guard) -每当一个任务进入 **Done** 状态，AI 必须强制执行以下同步操作： +## 1. 工作模式：真理驱动（软建议） -1. **方案固化**: 将最终修订的 `.plan.md` 完整备份至 `reference/management/plans/`。 -2. **存证生成**: 生成一份详尽的 `Walkthrough`，记录本次重构的逻辑决策、核心代码变更及验证结果，存放至 `reference/management/walkthroughs/`。 -3. **任务闭环**: 更新 `reference/management/tasks/` 中的执行记录，标注所有步骤已完成。 -4. **专项审计 (Conditional)**: - - 若本次任务涉及 **数据库变更** (Schema/Migration)，必须在 `reference/management/reports/` 中生成一份 `Migration_Report`。 - - 文件命名标准: `YYYYMMDD_ID_TaskName.[plan|tasks|walkthrough|report].md` +- **寻源优先**：遇到需求变更，先看 `reference/docs/` 下的 API 契约、Schema、PRD； + 文档未定义时，建议先更新文档再动代码。 +- **跨端同步**：后端契约变动时主动提示前端影响。 +- **原子化**：一次专注一个逻辑闭环，避免跨模块混合变更。 -## 3. 交付规约 (Delivery Protocol) +## 2. 归档（可选，仅架构决策） -- **交互语言**: 始终使用 **简体中文** 进行对话回复。 -- **Git 提交信息格式**: - - **语言**: 必须使用 **简体中文** 描述变更。 - - **中枢仓**: `docs: <描述>`, `chore: <描述>`, `plan: <描述>` - - *示例*: `docs: 更新发票 API 契约` - - **肢体仓**: `(): <描述>` - - *示例*: `feat(storage): 实现文件生命周期管理` +- **值得留档的场景**：架构决策、数据库迁移、破坏性 API 变更、跨仓协议变更、 + 事故复盘的决策链条。 +- **载体**：`reference/decisions/`（ADR 格式，命名 `ADR-NNNN-.md`）。 +- **日常任务不归档**——决策链条走 Git commit message + PR 描述即可。 +- **判断权**：由 AI 或用户显式判定是否值得写 ADR，不再强制。 -- **分支管理**: - - 开发工作必须在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 +## 3. 交付规约 -- **自我修正 (Self-Correction)**: - - 如果用户指出代码与文档不符，**必须** 优先以文档（中枢真理）为准进行修正，或者询问用户是否需要反向更新文档。 +- **交互语言**：始终使用简体中文。 +- **Git 提交信息**（中文描述）： + - 中枢仓：`docs: <描述>` / `chore: <描述>` + - 肢体仓：`(): <描述>`（例：`feat(storage): 实现文件生命周期管理`） +- **分支管理**：开发在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 +- **自我修正**：代码与文档不符时优先以文档为准，或询问用户是否反向更新文档。 --- diff --git a/README.md b/README.md index 812f1fd..5bd17da 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,8 @@ │ ├── rules/ # AI 规则 SSoT │ │ ├── lingshu-core.md # 架构核心准则 │ │ └── ai-behavior.md # 智能体行为准则 -│ ├── docs/ # 静态真理：PRD、契约、架构 -│ ├── experience/ # 经验复利：高分 Prompt、避坑笔记 -│ └── management/ # 动态治理 -│ ├── plans/ # 战略：原始方案 (.plan.md) -│ ├── tasks/ # 战术：执行 Checklists -│ ├── walkthroughs/ # 存证：逻辑决策、代码演练 -│ └── reports/ # 审计：汇总报告、数据库变更 +│ ├── docs/ # 静态真理：PRD、契约、架构（可扩张 prd/、tad/） +│ └── decisions/ # ADR：架构决策记录（可选，仅架构级决策才写） │ ├── CLAUDE.md # Claude Code 入口（基线，由 lingshu sync 生成） ├── AGENTS.md # Codex / 通用 Agents 入口（基线，由 lingshu sync 生成） @@ -188,7 +183,7 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings 1. **定策 (Define)**：在 `reference/docs/` 修改功能逻辑或 API 协议 2. **对齐 (Align)**：若涉及 AI 行为规则，更新 `reference/rules/` 真源 3. **触动 (Trigger)**：唤醒 AI（Claude Code / Codex / Cursor），发出指令"请根据中枢文档同步更新肢体逻辑" -4. **皆通 (Sync)**：检查全栈代码逻辑闭环，并产出 `reference/management/walkthroughs/` 存证 +4. **皆通 (Sync)**：检查全栈代码逻辑闭环；架构级决策才写 `reference/decisions/`（ADR） --- @@ -196,7 +191,7 @@ grep -rl "lingshu-template" --exclude-dir=node_modules . | xargs sed -i 's/lings 1. **文档先行**：禁止在没有更新中枢文档（`reference/docs/`）的情况下直接修改业务代码 2. **脑体解耦**：中枢仓严禁提交任何属于肢体仓（`*-server/`、`*-ui/` 等）的业务代码 -3. **同频交付**：所有交付报告或技术存证必须记录在 `reference/management/walkthroughs/`，作为逻辑对齐的凭证 +3. **同频交付**：日常任务走 Git commit + PR 描述；仅**架构级决策**记录到 `reference/decisions/`（ADR，可选） --- diff --git a/reference/README.md b/reference/README.md index ce90316..b4b2f00 100644 --- a/reference/README.md +++ b/reference/README.md @@ -16,9 +16,9 @@ ## 📂 目录结构 -- **`docs/`**: **真源文档**。存储 PRD、API 契约、状态机定义。 -- **`experience/`**: **经验沉淀**。存储 Pitfalls（避坑指南）和 Best Practices。 -- **`management/`**: **动态治理层**。下设 `plans/`（战略方案）、`tasks/`（战术任务）、`walkthroughs/`（变更存证）与 `reports/`（审计报告）。 +- **`rules/`**: **AI 规则真源**。分发到 `CLAUDE.md`、`AGENTS.md` 等产物。 +- **`docs/`**: **真源文档**。存储 PRD、API 契约、状态机定义；可按需扩张 `prd/`、`tad/` 等子目录（见 [docs/README.md](./docs/README.md)）。 +- **`decisions/`**: **架构决策记录 (ADR)**，可选。仅记录架构决策，不承担计划 / 任务 / 回顾职能；日常任务不写 ADR，走 Git commit 与 PR 描述即可。 --- diff --git a/reference/decisions/README.md b/reference/decisions/README.md new file mode 100644 index 0000000..4ea8e3f --- /dev/null +++ b/reference/decisions/README.md @@ -0,0 +1,38 @@ +# Architectural Decision Records (ADR) + +> 记录本仓库**架构级决策**的目录，**可选**——只在需要时创建条目。 + +## 何时写 ADR + +- 架构级技术选型 +- 数据库 Schema / Migration 决策 +- 破坏性 API 变更 +- 跨仓协议变更 +- 事故复盘的关键决策链条 + +**日常任务不写 ADR**——决策链条走 Git commit message 与 PR 描述即可。 + +## 命名与格式 + +- 文件名：`ADR-NNNN-.md`（例：`ADR-0001-.md`） +- 编号连续递增，不跳号；被 Superseded 的条目保留原文件不删。 +- 建议章节：**Context** / **Decision** / **Consequences** / **Alternatives** +- 参考： + +## 状态字段（frontmatter 建议） + +```yaml +--- +adr: 0001 +title: <决策标题> +status: Accepted # Proposed | Accepted | Superseded | Deprecated +date: YYYY-MM-DD +supersedes: null +superseded_by: null +--- +``` + +## 与 Git / PR 的分工 + +- **一次编辑背后的"为什么"** → PR 描述 +- **一个决策背后的"权衡"** → ADR（跨越多次编辑，可被后来的决策 Supersede） diff --git a/reference/docs/README.md b/reference/docs/README.md index 0c8abd4..77a4d75 100644 --- a/reference/docs/README.md +++ b/reference/docs/README.md @@ -1,15 +1,25 @@ -# 📜 灵枢之源 (Source of Truth) +# 真源文档 (Source of Truth) -> **"所有流向海洋的河，都必须记得源头的方向。"** +本目录是项目的**真源文档层**——PRD、API 契约、状态机、数据库 Schema 等 +"技术契约"应在此定义。代码是文档的投影 (Projection)。 -本目录 `contracts/` 是项目的 **唯一真理 (Single Source of Truth)**。 +## 目录扩张建议（可选） -请在开始阅读具体的契约前，先阅读 [灵枢宣言](../README.md) 以理解我们的核心哲学。 +当仓库需要同时承担"设计文档"与"编码过程"两职时，可参考以下子目录约定 +（**按需自建**，模板不预置骨架）： -## 📖 文档索引 +- **`prd/`** — 产品需求文档（PRD / RFC） +- **`tad/`** — 技术架构文档（TAD / 系统设计） +- **`api/`** — API 契约（OpenAPI / GraphQL Schema） +- **`schema/`** — 数据库 Schema / 迁移 +- **`assets/`** — 附属图片、图表源文件 -- [项目全局架构](./architecture.md) -- [API 契约与数据模型](./api-contract.md) -- [业务状态机逻辑](./state-machines.md) -- [业务逻辑说明 (PRD)](./prd-template.md) +### 约定 +- **命名**：`.md`（例：`prd/user-login.md`）。Git 已记录时间线， + 文件名无需日期前缀。 +- **架构决策 (ADR)**：统一放**顶层** `reference/decisions/`，不要在此 + 嵌套 `docs/prd/decisions/` 之类的子目录。 +- **不使用数字前缀**（`01-`/`02-`）——排序交给分类与命名意图，避免手动维护顺序。 + +> 上述结构仅为建议。不需要设计文档承载能力的仓库可让本目录保持扁平。 diff --git a/reference/experience/README.md b/reference/experience/README.md deleted file mode 100644 index 4e85d1c..0000000 --- a/reference/experience/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# 🧠 经验复利 (Knowledge Base) - -本目录记录在本项目开发中，调优 AI (Cursor/Trae/Qoder) 的实战经验。 - -## 目录指南 - -- `/prompts/`: 经过验证的高分 Prompt。 -- `/pitfalls/`: 记录 AI 容易犯的错误和解决方案（避坑指南）。 diff --git a/reference/experience/pitfalls/001-port-drifting-fix.md b/reference/experience/pitfalls/001-port-drifting-fix.md deleted file mode 100644 index af7fa74..0000000 --- a/reference/experience/pitfalls/001-port-drifting-fix.md +++ /dev/null @@ -1,36 +0,0 @@ -# 避坑指南 001：全栈端口冲突与“禁止漂移”原则 - -- **关联领域**: #DevOps #Networking #Antigravity -- **适用 Agent**: Antigravity, Cursor, Trae, Qoder -- **创建日期**: 2026-01-16 - ---- - -## 1. 陷阱描述 (The Pitfall) -AI 在检测到默认端口（后端 5000, 前端 5173）被占用时，会**自动递增端口**（如尝试 5001 或 5174）以绕过错误，而不是解决冲突。 - -## 2. 负面影响 (Impact) -- **跨域失效**: 前端 Proxy 指向 5000，后端漂移到 5001 导致 API 请求全部失败。 -- **孤儿进程堆积**: 端口占用通常是旧进程（Flask Reloader）未释放，逃避导致系统资源持续耗损。 -- **环境一致性破坏**: 导致前后端链路无法对齐，浪费大量调试时间。 - -## 3. 根因分析 (Root Cause) -Agent 的默认决策树中，“启动成功”的权重高于“清理环境”。它不感知 Windows 11 下 Python/Node 进程树的复杂性，误以为旧进程已死。 - -## 4. 解决方案 (Lingshu Solution) - -### 强制原则：端口归位 (Port Anchoring) -严禁任何形式的端口漂移。必须执行 **“检查 -> 强杀 -> 校验 -> 重启”** 的原子流。 - -### 避坑指令 (Windows 11): -- **后端 (5000)**: `taskkill /F /IM python.exe /T` (强制清理进程树) -- **前端 (5173)**: `taskkill /F /IM node.exe /T` -- **校验**: 必须执行 `netstat -ano | findstr :` 确保输出为空后方可重新启动。 - -## 5. 规则同步 (Rules Sync) -该指南已固化至： -- `.agent/rules/network_guard.md` -- `.agent/workflows/service_reboot.md` - ---- -**[架构师笔记]**: 这是灵枢架构的第一块基石。以后凡是涉及环境重启，必须先调用此守卫逻辑。 diff --git a/reference/experience/pitfalls/002-agent-browser-blind-retry.md b/reference/experience/pitfalls/002-agent-browser-blind-retry.md deleted file mode 100644 index 6fe5536..0000000 --- a/reference/experience/pitfalls/002-agent-browser-blind-retry.md +++ /dev/null @@ -1,24 +0,0 @@ -# 避坑指南 002：Agent 浏览器模式的“死循环”陷阱 - -- **关联领域**: #Agent #Antigravity #Automation -- **适用 Agent**: Antigravity (Agent Mode) -- **创建日期**: 2026-01-16 - ---- - -## 1. 陷阱描述 (The Pitfall) - -当 Antigravity 修改完 UI 代码后，会尝试以 Agent 模式启动浏览器预览。若此时前后端服务未启动或已崩溃，浏览器会陷入死循环刷新，Agent 不会自动检查终端服务状态。 - -## 2. 根因分析 (Root Cause) - -Agent 模式下的浏览器组件与 IDE 终端组件存在“感知断层”。浏览器 Agent 认为访问失败是网络抖动或渲染问题，而不具备“检查服务器进程”的联想逻辑。 - -## 3. 灵枢解决方案 (Lingshu Solution) - -- **硬性约束**: 所有的浏览器交互指令前，必须插入一步“终端服务存活校验”。 -- **判断逻辑**: 使用 `curl` 或 `Invoke-WebRequest` 探测端口响应，而非等待页面超时报错。 - ---- - -**[架构师笔记]**: 不要让 Agent 在前台空转，必须让它先低头看一眼后台的命脉。 diff --git a/reference/experience/pitfalls/backend-sync.md b/reference/experience/pitfalls/backend-sync.md deleted file mode 100644 index b5016e5..0000000 --- a/reference/experience/pitfalls/backend-sync.md +++ /dev/null @@ -1,8 +0,0 @@ -# ⚠️ 避坑指南：FastAPI 异步锁问题 - -**问题描述**: Cursor 在生成异步接口时，偶尔会忽略数据库连接池的释放。 - -**解决方案**: - -- 在 `.cursor/rules/tech-stack-py.mdc` 中强制要求使用 `async with` 语法。 -- 每次生成的代码必须包含单元测试以验证并发稳定性。 diff --git a/reference/experience/prompts/ui-generation.md b/reference/experience/prompts/ui-generation.md deleted file mode 100644 index 8397dc1..0000000 --- a/reference/experience/prompts/ui-generation.md +++ /dev/null @@ -1,12 +0,0 @@ -# 🎭 UI 高分 Prompt：Shadcn 复杂表格生成 - -**场景**: 当需要生成带复杂过滤和分页的表格时。 - -**Prompt 文本**: - -> "请基于 shadcn-vue 的 DataTable 组件，实现一个支持服务端分页和多条件搜索的表格。要求： -> 1. 使用 Vue3 defineProps 定义响应式数据。 -> 2. 必须符合 reference/docs/api-contract.md 中的数据结构。 -> 3. 样式参考现有风格，保持简洁。" - -**效果**: 能够减少 80% 的样式微调时间。 diff --git a/reference/management/plans/ITERATION_TEMPLATE.md b/reference/management/plans/ITERATION_TEMPLATE.md deleted file mode 100644 index ea915e2..0000000 --- a/reference/management/plans/ITERATION_TEMPLATE.md +++ /dev/null @@ -1,21 +0,0 @@ -# 📅 迭代计划：[项目名] - [版本/特性名] - -**执行周期**：2026-XX-XX ~ 2026-XX-XX -**状态**：🏃 进行中 / 📝 评审中 - -## 🎯 核心目标 - -- [ ] 目标 1：中枢定义 [XX 逻辑] -- [ ] 目标 2：驱动 [Server] 实现 [XX 接口] -- [ ] 目标 3：驱动 [UI] 实现 [XX 交互] - -## 🧠 灵枢变更预设 (枢机动作) - -1. **文档更新**：修改 `reference/docs/api-contract.md` 增加 [X] 字段。 -2. **规则调整**：在 `.cursor/rules/` 中增加对 [X] 业务逻辑的特殊约束。 - -## 🤖 AI 协作策略 - -- **主驱动**：Cursor (逻辑) / Trae (界面) -- **重点关注**：确保跨端字段命名完全对齐。 - diff --git a/reference/management/plans/README.md b/reference/management/plans/README.md deleted file mode 100644 index 90d95fe..0000000 --- a/reference/management/plans/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# 战略方案 (Strategic Plans) - -**路径**: `reference/management/plans/` - -## 📂 用途 -存放由 Agent 生成的原始方案文件 (`.plan.md`)。 - -## 📝 归档规约 -- 任务初始化时创建临时方案。 -- 任务进入 Done 状态时，必须将最终版方案固化至此目录。 -- 命名格式: `YYYYMMDD_ID_TaskName.plan.md` diff --git a/reference/management/reports/README.md b/reference/management/reports/README.md deleted file mode 100644 index 8375018..0000000 --- a/reference/management/reports/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# 审计报告 (Audit Reports) - -**路径**: `reference/management/reports/` - -## 📂 用途 -存放审计汇总、部署清单、质量报告以及数据库变更报告 (`.report.md`)。 - -## 📝 归档规约 -- 包含月度/季度汇总。 -- **强制约束**: 若任务涉及数据库变更，需在此生成 `Migration_Report`。 -- 命名格式: `YYYYMMDD_ID_TaskName.report.md` diff --git a/reference/management/tasks/README.md b/reference/management/tasks/README.md deleted file mode 100644 index eeb46f6..0000000 --- a/reference/management/tasks/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# 战术执行 (Tactical Tasks) - -**路径**: `reference/management/tasks/` - -## 📂 用途 -存放由 Agent 拆解的执行 Checklists (`.tasks.md`)，用于追踪原子化步骤。 - -## 📝 归档规约 -- 记录任务的详细执行过程、状态与复盘。 -- 命名格式: `YYYYMMDD_ID_TaskName.tasks.md` diff --git a/reference/management/walkthroughs/README.md b/reference/management/walkthroughs/README.md deleted file mode 100644 index f71db53..0000000 --- a/reference/management/walkthroughs/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# 技术存证 (Walkthroughs) - -**路径**: `reference/management/walkthroughs/` - -## 📂 用途 -存放重构逻辑、代码演练、决策记录以及交付报告 (`.walkthrough.md`)。 - -## 📝 归档规约 -- 任务完成后必须强制生成，记录本次迭代的核心逻辑决策。 -- 命名格式: `YYYYMMDD_ID_TaskName.walkthrough.md` diff --git a/reference/rules/ai-behavior.md b/reference/rules/ai-behavior.md index c9abe6c..db01a27 100644 --- a/reference/rules/ai-behavior.md +++ b/reference/rules/ai-behavior.md @@ -1,52 +1,30 @@ --- order: 2 -name: ai-behavior -description: 灵枢智能体行为准则：Plan 模式存档、真理同步流与原子化交付 -globs: **/* -trigger: always_on --- -# 🤖 灵枢智能体行为准则 (Agentic Workflow) +# AI 智能体行为准则 -## 1. 思考模式：真理驱动 (Truth Driven) -在 **Ask 模式** 或 **Composer 模式** 中，遵循以下逻辑链： +## 1. 工作模式：真理驱动（软建议） -1. **🔍 寻源 (Locate Truth)**: - - 遇到需求变更，**首先** 检查 `reference/docs/` 下的 API 契约、数据库 Schema 或 PRD。 - - 若文档未定义，先建议用户更新文档，而不是直接写代码。 - - **口号**: "逻辑不入中枢，代码不动分毫。" +- **寻源优先**：遇到需求变更，先看 `reference/docs/` 下的 API 契约、Schema、PRD； + 文档未定义时，建议先更新文档再动代码。 +- **跨端同步**：后端契约变动时主动提示前端影响。 +- **原子化**：一次专注一个逻辑闭环，避免跨模块混合变更。 -2. **📝 规划 (Planning)**: - - 进入 Composer (Plan) 模式后，必须生成/更新 `.plan.md`。 - - **强制存档 (CRITICAL)**: 在执行代码修改前，必须将当前的 `.plan.md` 完整复制备份到 `reference/management/plans/` 目录下，并更新 `reference/management/tasks/` 中的执行清单。文件名格式建议：`YYYYMMDD-TaskName.md`。 +## 2. 归档（可选，仅架构决策） -3. **⚡ 执行 (Execution)**: - - **跨端同步**: 始终检查后端变更对前端的影响（如 API 字段变动），并主动提示同步修改。 - - **原子化**: 每次只处理一个具体的逻辑闭环，避免跨多个不相关的功能模块修改。 +- **值得留档的场景**：架构决策、数据库迁移、破坏性 API 变更、跨仓协议变更、 + 事故复盘的决策链条。 +- **载体**：`reference/decisions/`（ADR 格式，命名 `ADR-NNNN-.md`）。 +- **日常任务不归档**——决策链条走 Git commit message + PR 描述即可。 +- **判断权**：由 AI 或用户显式判定是否值得写 ADR，不再强制。 -## 2. 自动化归档守卫 (Archival Guard) -每当一个任务进入 **Done** 状态，AI 必须强制执行以下同步操作： +## 3. 交付规约 -1. **方案固化**: 将最终修订的 `.plan.md` 完整备份至 `reference/management/plans/`。 -2. **存证生成**: 生成一份详尽的 `Walkthrough`，记录本次重构的逻辑决策、核心代码变更及验证结果，存放至 `reference/management/walkthroughs/`。 -3. **任务闭环**: 更新 `reference/management/tasks/` 中的执行记录，标注所有步骤已完成。 -4. **专项审计 (Conditional)**: - - 若本次任务涉及 **数据库变更** (Schema/Migration)，必须在 `reference/management/reports/` 中生成一份 `Migration_Report`。 - - 文件命名标准: `YYYYMMDD_ID_TaskName.[plan|tasks|walkthrough|report].md` - -## 3. 交付规约 (Delivery Protocol) - -- **交互语言**: 始终使用 **简体中文** 进行对话回复。 -- **Git 提交信息格式**: - - **语言**: 必须使用 **简体中文** 描述变更。 - - **中枢仓**: `docs: <描述>`, `chore: <描述>`, `plan: <描述>` - - *示例*: `docs: 更新发票 API 契约` - - **肢体仓**: `(): <描述>` - - *示例*: `feat(storage): 实现文件生命周期管理` - -- **分支管理**: - - 开发工作必须在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 - -- **自我修正 (Self-Correction)**: - - 如果用户指出代码与文档不符，**必须** 优先以文档（中枢真理）为准进行修正，或者询问用户是否需要反向更新文档。 +- **交互语言**：始终使用简体中文。 +- **Git 提交信息**（中文描述）： + - 中枢仓：`docs: <描述>` / `chore: <描述>` + - 肢体仓：`(): <描述>`（例：`feat(storage): 实现文件生命周期管理`） +- **分支管理**：开发在 `feat/*` 或 `refactor/*` 分支进行，严禁直推 `master/main`。 +- **自我修正**：代码与文档不符时优先以文档为准，或询问用户是否反向更新文档。 --- diff --git a/reference/rules/lingshu-core.md b/reference/rules/lingshu-core.md index 5887e12..9587180 100644 --- a/reference/rules/lingshu-core.md +++ b/reference/rules/lingshu-core.md @@ -1,52 +1,41 @@ --- order: 1 -name: lingshu-core -description: 灵枢架构核心准则：脑体解耦、Git 物理隔离与路径映射 -globs: **/* -trigger: always_on --- -# 灵枢架构核心准则 (LingShu Core Principles) +# 架构核心准则 -## 1. 架构拓扑定义 (Architecture Topology) -本仓库遵循 **LingShu** 架构，实行"逻辑中枢"与"执行肢体"的物理分离。 +## 1. 拓扑定义 +本仓库采用"中枢-肢体"分层结构： -- **🧠 中枢仓 (The Brain)**: - - **路径**: 当前根目录 `./` - - **职责**: 定义真理 (Reference)、规则 (Rules)、计划 (Plans) 与审计 (Audit)。 - - **特征**: 仅追踪文档与配置，不应包含业务源代码。 +- **中枢仓 (The Brain)**： + - **路径**：当前根目录 `./` + - **职责**：定义真源（Reference）、规则（Rules）与架构决策（Decisions）。 + - **特征**：仅追踪文档与配置，不包含业务源代码。 -- **💪 肢体仓 (The Limbs)**: - - **路径**: 根目录下的具体工程子目录（通常命名为 `*-server`, `*-ui`, `*-mobile`, `*-web`）。 - - **职责**: 承载具体的业务代码实现。 - - **识别规则**: AI 需自动扫描根目录，识别包含 `.git` (子模块/嵌套仓) 或具体语言配置（如 `pyproject.toml`, `package.json`）的子文件夹作为"肢体"。 +- **肢体仓 (The Limbs)**： + - **路径**：根目录下的具体工程子目录（通常命名为 `*-server`、`*-ui`、`*-mobile`、`*-web`）。 + - **职责**：承载具体的业务代码实现。 + - **识别规则**：AI 需自动扫描根目录，识别包含 `.git`（子模块 / 嵌套仓）或具体语言配置（如 `pyproject.toml`、`package.json`）的子文件夹作为"肢体"。 -## 2. Git 物理隔离规则 (Git Isolation Rules) +## 2. Git 物理隔离规则 由于采用嵌套仓库结构，必须严格遵守以下操作边界： -- **🚫 禁止根目录通配提交**: - - **严禁** 在根目录执行 `git add .` 或 `git commit -a`，这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 - - 根目录 Git **仅允许** 追踪：`reference/`, AI 工具基线产物（`CLAUDE.md`, `AGENTS.md`），以及 `reference/management/` 下的任务文档。 +- **禁止根目录通配提交**： + - **严禁**在根目录执行 `git add .` 或 `git commit -a`——这会导致肢体仓的代码被错误地纳入中枢仓版本控制。 + - 根目录 Git **仅允许**追踪：`reference/` 治理资产（真源规则、docs、可选 decisions/），以及 AI 工具基线产物（`CLAUDE.md`、`AGENTS.md`）。 -- **✅ 肢体仓独立提交**: +- **肢体仓独立提交**： - 修改具体业务代码后，必须显式 `cd [limb-folder_name]/` 进入子目录。 - 确认 `git status` 显示的是子仓库的状态后，再执行提交。 -- **🛡️ 提交前自检 (Pre-commit Check)**: +- **提交前自检**： - AI 在生成 Git 指令前，必须判断当前变更的文件路径。 - 若路径属于 `*-server/` 或 `*-ui/`，必须输出 `cd` 指令作为前置操作。 -## 3. 规则真源约束 (SSoT for Rules) +## 3. 规则真源约束（SSoT） -- **真源唯一**: 所有 AI 行为规则的真源位于 `reference/rules/`。 -- **产物只读**: `.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为 **由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 -- **变更流程**: 规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 -- **CI 保障**: GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 - -## 4. 环境与依赖标准 (Stack Standard) -*（注：此部分定义模版默认技术栈，可随项目调整）* -- **Python 环境**: 推荐使用 `uv` 或 `pip` 管理依赖。 - - Windows 特殊指令: `uv` 相关命令须带 `--link-mode copy --no-install-project`。 -- **Node 环境**: 推荐使用 `npm` 管理依赖与脚本（团队统一标准）。 -- **交互语言**: 始终使用 **简体中文**。 +- **真源唯一**：所有 AI 行为规则的真源位于 `reference/rules/`。 +- **产物只读**：`.cursor/rules/`、`.trae/rules/`、`.qoder/rules/`、`.agent/rules/`、`CLAUDE.md`、`AGENTS.md` 均为**由 `lingshu sync` 自动生成的产物**，禁止手动编辑。 +- **变更流程**：规则修改必须改动 `reference/rules/` 真源，再执行 `lingshu sync` 重新分发。 +- **CI 保障**：GitHub Actions 会校验入库产物与真源的一致性，防止漂移。 ---