From 8027cdd1d93684b5c97df61724a590741f4c68a0 Mon Sep 17 00:00:00 2001 From: iven Date: Mon, 25 May 2026 14:03:50 +0800 Subject: [PATCH] =?UTF-8?q?docs(graphify):=20=E6=B7=BB=E5=8A=A0=E7=9F=A5?= =?UTF-8?q?=E8=AF=86=E5=9B=BE=E8=B0=B1=E4=BD=BF=E7=94=A8=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: graphify 从英文规则扩展为中文开发流程指南 - 定义 5 种使用场景（接手任务/排查bug/理解模块/代码更新/架构审查） - 融入闭环工作法，优先级：graphify query > path > Grep/Read - wiki/index.md: 关键数字添加 Graphify 行 + 模块导航新增开发工具分区 - wiki/infrastructure.md: §3 常用命令添加 Graphify 子节 --- CLAUDE.md | 33 ++++++++++++++++++++++++++------- wiki/index.md | 6 +++++- wiki/infrastructure.md | 12 ++++++++++++ 3 files changed, 43 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 605b05b..0baf9bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -505,12 +505,31 @@ chore(docker): 添加 PostgreSQL 健康检查 | 开发进度、模块状态 | `wiki/index.md` 关键数字 | | 环境配置、连接信息、登录凭据 | `wiki/infrastructure.md` §2 | -## graphify +## graphify — 代码知识图谱 -This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. +> 项目知识图谱位于 `graphify-out/`，当前规模：18,517 节点 / 22,666 边 / 1,841 社区（纯 AST 解析，无 API 成本）。 +> 工具：`python -m graphify`（已安装 graphifyy 0.8.18）。 -Rules: -- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. -- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. -- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. -- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). +### 开发流程中的使用场景 + +| 时机 | 命令 | 目的 | +|------|------|------| +| **接手新任务，理解代码关系** | `graphify query "概念名"` | 搜索相关节点，比 Grep 更精准（按调用/引用/包含关系） | +| **排查 bug，追踪调用链** | `graphify path "A" "B"` | 查找两个模块/函数间的最短路径 | +| **理解某个模块的职责** | `graphify explain "模块名"` | 自然语言解释节点及其邻居 | +| **代码改动后** | `graphify update .` | 增量更新图谱（AST-only，秒级完成） | +| **宏观架构审查** | 读 `graphify-out/GRAPH_REPORT.md` | 全局社区结构、跨文件关系概览 | + +### 使用优先级（融入 §2.5 闭环工作法） + +在 §2.5 步骤 1「现状确认」中，**优先使用 graphify 替代盲目 Grep**： + +1. **先 `graphify query`** — 精确定位相关节点和社区（比 Grep 返回更结构化的结果） +2. **再 `graphify path`** — 确认模块间依赖路径（避免遗漏间接依赖） +3. **最后 Grep/Glob/Read** — 确认 graphify 发现的具体文件内容 + +### 注意事项 + +- `graphify update .` 纯本地 AST 解析，不消耗 LLM token，每次代码改动后都可以运行 +- 查询结果比 GRAPH_REPORT.md 更精准，优先使用 query/path/explain，仅在需要全局视图时读报告 +- 首次生成需几分钟（1712 文件），后续增量更新秒级完成 diff --git a/wiki/index.md b/wiki/index.md index 5a6dd76..82a0123 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -4,7 +4,7 @@ ## 关键数字 -> 最后更新: 2026-05-24 | 数据截止: feat/media-library-banner 分支（小程序 DevTools 卡死排查 + 构建优化） +> 最后更新: 2026-05-25 | 数据截止: feat/media-library-banner 分支（小程序 DevTools 卡死排查 + 构建优化） | 指标 | 值 | |------|-----| @@ -28,6 +28,7 @@ | 依赖版本 | 全部最新主版本线（Rust edition 2024） | | API 文档 | `http://localhost:3000/api/docs/openapi.json` | | Git 提交 | **996 次** | +| Graphify 知识图谱 | **18,517 节点** / 22,666 边 / 1,841 社区（`graphify-out/`，AST 解析，无 API 成本） | | 系统分析评分 | **6.9/10 (B)**（多专家组生产就绪度分析，2026-05-21：业务 8.5 / 医疗合规 6.5 / 前端 8.0 / 安全 7.5 / DevOps 4.0） | | 审计状态 | V1: 83% → V2: 85%，P0 安全修复已完成；E2E 测试 157 端点(Health 63% / AI+Plugin 92.4%)，CRITICAL×2 待修复 | | 角色测试 | R01-R05 全角色验证完成，86.5% 通过率，5 个 BUG 已修复；小程序 MP 多角色 96.2% 通过率 | @@ -180,6 +181,9 @@ - [[frontend]] — React 19 SPA · 健康管理页面（29 活跃路由 + 6 冻结 + 工作台组件） - [[testing]] — 验证清单 · 测试分布 · 性能基准 +### 开发工具 +- **graphify** — 代码知识图谱（18,517 节点 / 22,666 边 / 1,841 社区）。接手新任务时先 `graphify query "概念"` 定位相关代码，再 `graphify path "A" "B"` 追踪调用链，比盲目 Grep 更精准。代码改动后运行 `graphify update .` 增量更新（AST-only，秒级完成）。详见 `CLAUDE.md` §graphify。 + ## 核心架构问答 **为什么 erp-health 用原生模块而非 WASM 插件？** 医疗业务需要 18 强类型实体、自定义 API（趋势分析/统计报表）、文件上传（化验单/体检报告）、未来 AI 集成，超出 WASM 插件能力范围。详见 [[erp-health]]。 diff --git a/wiki/infrastructure.md b/wiki/infrastructure.md index d5e3ede..98d24f6 100644 --- a/wiki/infrastructure.md +++ b/wiki/infrastructure.md @@ -158,6 +158,17 @@ wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_test_s cargo test -p erp-plugin-prototype # 运行插件集成测试 ``` +### Graphify 知识图谱 + +```bash +python -m graphify query "BLEConnection" # 搜索节点（比 Grep 更精准，按调用/引用关系） +python -m graphify path "A" "B" # 两个模块间的最短路径 +python -m graphify explain "ArticleDetail" # 自然语言解释节点及其邻居 +python -m graphify update . # 增量更新图谱（AST-only，秒级完成） +``` + +> **开发流程中的使用：** 接手新任务时先 `graphify query` 定位相关代码 → `graphify path` 追踪调用链 → 再 Grep/Read 确认具体内容。代码改动后运行 `graphify update .` 保持图谱最新。详见 `CLAUDE.md` §graphify。 + ## 4. 代码逻辑 ### 一键启动（推荐） @@ -196,6 +207,7 @@ cd apps/web && pnpm install && pnpm dev | 日期 | 变更 | |------|------| +| 2026-05-25 | 添加 Graphify 知识图谱工具命令（query/path/explain/update） | | 2026-05-25 | 明确 dev:weapp vs build:weapp 构建模式区分，记录 .env.production 导致 DevTools 卡死的陷阱 | | 2026-04-26 | 从 CLAUDE.md 迁移：常用命令（§9） | | 2026-04-25 | 外部化微信凭据和健康加密密钥为环境变量；添加 4 个新的必设环境变量 |