cgraphx 1.1.0

package/dist/.claude-template/skills/code-impact-markdown/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: code-impact-markdown
+description: 维护可供 cgraphx docs 扫描的 Markdown 知识文件。用于创建、编辑、规范化或提取元数据,将对话、代码探索结果、教程、指南、运维手册、安装说明、决策、经验教训或面向 AI 的项目知识保存为可被本地图谱扫描的 .md 文件。
+---
+
+# Code Impact Markdown
+
+当项目知识需要以可被图谱检索的方式持久化时,使用此 skill。
+
+典型输入:
+- 有价值的对话摘要
+- 代码探索或分析结果
+- 架构或实现发现
+- Bug 调查笔记
+- 项目决策和约定
+- 教程、安装指南和操作文档
+- 运维手册和操作流程
+- 经验教训、警告和未来 AI 指引
+
+## 保存目录
+
+所有可被图谱扫描的 Markdown 知识文件必须保存到:
+
+```text
+docs/knowledge/
+```
+
+如目录不存在则创建。按主题组织文件 —— 一个文档聚焦一个主题。不要将知识文件保存到此目录之外。
+
+## 必要流程
+
+1. 确定目标 Markdown 路径(在 `docs/knowledge/` 下)。
+2. **在命名新概念之前,先查询已有的 concepts、domains、tags**(见下节)。
+3. 当含义相同时,复用规范名称。
+4. 为替代名称添加 `aliases`,而非创建重复的 concept。
+5. 如果是更新已有的 Markdown 文件,先读取并保留当前 frontmatter。
+6. 编写简洁的 frontmatter,使文档可被图谱解析。
+7. 正文必须包含 `## Summary`(唯一进索引的章节),其他章节按 `document_type` 选模板自由组织。
+8. 检查是否已有文档覆盖了相同主题。当三个合并条件全部满足时(见文档合并检查),提示用户是否合并。
+9. 编辑后询问是否触发扫描。**未经确认不要运行扫描**。
+
+## 查询已有词汇
+
+扫描已运行过时,先用 CLI 列出已有 concept/domain/tag,避免造重复名:
+
+```bash
+cgraphx docs concepts              # 列所有 concept + 关联文档数 + 所属 domain
+cgraphx docs domains               # 列所有 domain
+cgraphx docs tags                  # 列所有 tag
+```
+
+查找特定术语或概念:
+
+```bash
+cgraphx docs find --q=Redis         # 关键词子串匹配(LIKE on title + summary)
+cgraphx docs find --concept=Redis   # 按 concept 精确过滤
+```
+
+如果索引尚未建立(刚 clone 仓库 / 还没跑过 `cgraphx docs index`),直接 grep 本地 Markdown 的 frontmatter:
+
+```bash
+grep -rl "concepts:" docs/knowledge/ --include="*.md"
+```
+
+## 校验 frontmatter(本地自查)
+
+cgraphx 无服务端校验端点。**编辑后自查 7 必填字段是否齐全且合法**:
+
+| 字段 | 校验 |
+|---|---|
+| `title` | 非空字符串 |
+| `document_type` | 16 枚举之一(见下) |
+| `domains` | 至少 1 项 |
+| `concepts` | 至少 1 项 |
+| `status` | 4 枚举之一(`draft`/`active`/`superseded`/`deprecated`) |
+| `source_type` | 7 枚举之一(见下) |
+| `updated` | `YYYY-MM-DD` 格式 |
+
+任一字段缺失或非法 → cgraphx 扫描时**整个文件被跳过**,记入 skip 日志(可用 `cgraphx docs index` 输出查看跳过原因)。
+
+## 命名规则
+
+- 每个概念或领域使用一个规范名称。
+- 优先用 cgraphx 已索引的名称(用 `cgraphx docs concepts` 查)。
+- 不要为同一概念创建翻译后的重复项,如 `Redis`、`redis server`、`Redis Installation`。
+- 将替代名称放入 `aliases`。
+- **concept 用项目实际话语里的规范名**:代码标识符/协议/产品名保留真实形式(多为英文,如 `Redis`、`SqliteStore`),领域/业务/流程概念用项目语言(本项目多为中文,如 `本地开发环境`、`知识图谱`)—— 不要把中文概念硬翻成英文。完整规则见「语言」节。
+- 保持 domain 名称稳定且有界,如 `order-service`、`infra`、`cache`、`billing`。
+- 使用 `tags` 进行松散分组;不要用 tags 替代 concepts 或 domains。
+
+## Frontmatter 规范
+
+每个可被图谱扫描的 Markdown 文件顶部必须使用 YAML frontmatter:
+
+```yaml
+---
+title: Redis 本地安装指南
+document_type: guide
+domains:
+  - infra
+concepts:
+  - Redis
+  - 本地开发环境
+aliases:
+  - Local Development Environment
+  - Redis Setup
+tags:
+  - tutorial
+  - cache
+status: active
+source_type: human_note
+owners:
+  - platform
+related_code:
+  - src/main/java/demo/OrderService.java
+related_documents:
+  - docs/guides/order-flow.md
+created: 2026-04-28
+updated: 2026-04-28
+---
+```
+
+**`related_code` 语义**:cgraphx **仅作元数据保存**(JSON 数组存表),**不建立到代码符号的反向链接**(A 范围下的设计决策,文档与代码图完全隔离)。值可以是文件路径、全限定类名或方法引用,作为人类/未来工具的链接提示。
+
+**必填字段(7 个)**:
+
+```text
+title
+document_type
+domains
+concepts
+status
+source_type
+updated
+```
+
+**时间格式**:`YYYY-MM-DD`(ISO 8601 日期,不含时分)。示例:`2026-04-28`。`created` 字段可选但推荐填写。
+
+**`document_type` 枚举(16 个)**:
+
+```text
+conversation     # 对话总结
+exploration      # 探索发现
+finding          # 调查结论
+analysis         # 深度分析
+lesson           # 经验教训
+warning          # 警告/陷阱
+decision         # 决策记录
+rule             # 团队规则
+architecture     # 架构说明
+guide            # 指南
+tutorial         # 教程
+runbook          # 运维手册
+installation     # 安装说明
+api              # API 文档
+faq              # 常见问题
+note             # 笔记
+```
+
+**`source_type` 枚举(7 个)**:
+
+```text
+ai_session          # AI 对话总结
+human_note          # 人写的笔记
+code_review         # 代码审查发现
+debugging           # 问题排查过程
+architecture_review # 架构评审
+manual              # 人工撰写(默认)
+external_summary    # 外部资料摘录
+```
+
+**`status` 枚举(4 个)**:
+
+```text
+draft      # 草稿
+active     # 当前有效
+superseded # 已被替代
+deprecated # 已废弃
+```
+
+## 稳定标题(只有 Summary 进索引)
+
+**唯一进 cgraphx 索引的章节是 `## Summary`(或中文别名 `## 摘要`)**。其他章节保留在文件里,AI 想看就 Read 文件。
+
+```text
+## Summary        ← 唯一进索引(标题大小写敏感,必须正好两个 # + 一个空格)
+## 摘要           ← 中文别名,也接受
+
+## Context        ← 不进索引,留文件里供 Read
+## Decisions      ← 同上
+## Steps          ← 同上
+...               ← 任意其他章节,自由组织
+```
+
+**写作建议**(虽不进索引,但让文档更系统):按 `document_type` 选模板(`template-memory.md` / `template-guide.md` / `template-runbook.md`),模板里的章节结构是写作指南,不是索引契约。
+
+## 语言
+
+文档正文必须用**中文**编写。技术术语、代码标识符、文件路径、函数名和类名保留原始英文形式。`## Summary` 标题保留英文(大小写敏感)。
+
+**Concept 与 aliases 的语言**:concept 用项目实际话语里的规范名 —— 代码标识符/协议/产品名保留真实形式(多为英文,如 `Redis`、`SqliteStore`、`FTS5`),领域/业务/流程概念用项目语言(本项目多为中文,如 `本地开发环境`、`知识图谱`、`任务办理流程`)。**不要把中文概念硬翻成英文。** aliases 放这个 concept 的其他语言译名 + 同义词 + 缩写(例:concept `知识图谱` → aliases `[Knowledge Graph, KG]`;concept `SqliteStore` → aliases `[SQLite 存储层]`)。
+
+理由:cgraphx 关键词搜索是 LIKE 子串匹配(concept 名 + title + Summary 都参与),用项目实际用词,中文查询才能直接命中。dedup 不受影响(同名 concept 跨文档自动合并)。
+
+## 文档模板
+
+按 `document_type` 选模板:
+
+| document_type | 模板文件 |
+|---|---|
+| conversation, exploration, finding, analysis, decision, lesson, warning, rule, architecture | [template-memory.md](template-memory.md) |
+| guide, tutorial, installation, api, faq, note | [template-guide.md](template-guide.md) |
+| runbook | [template-runbook.md](template-runbook.md) |
+
+**注意**:模板里的章节结构是**写作指南**(让文档更系统),cgraphx **只提取 `## Summary`** 进索引,其他章节留文件里。
+
+## 已有 Markdown 处理
+
+当文件已存在时:
+- 首先提取当前 frontmatter。
+- 保留未知的元数据字段,除非它们明显有误。
+- 将 `domains`、`concepts`、`aliases`、`tags`、`owners`、`related_code`、`related_documents` 规范化为 YAML 列表。
+- 添加缺失的必填字段。
+- 未检查已有用法前,不要重命名 concepts 或 domains。
+- 保留有用的已有标题;仅在能改善可读性时才规范化标题。
+- 优先在已有结构下追加带日期的新发现,而非重写历史结论(除非已过时)。
+
+## 文档合并检查
+
+编写新 Markdown 文档后,检查是否已有文档覆盖了相同主题。仅当以下三个条件**同时满足**时才提示用户。
+
+### 三个合并条件
+
+1. **document_type 匹配或兼容** —— 已有文档具有相同的 `document_type`,或类型用途相同(例如 `guide` 和 `installation`、`conversation` 和 `exploration`)。
+2. **核心概念高度重叠** —— 新文档的至少一个核心 concept 出现在已有文档的 `concepts` frontmatter 中。仅边缘概念重叠不足以触发。
+3. **范围相似** —— 标题或正文范围重叠,不仅仅是提到了相同概念,而是覆盖了相同的知识领域。
+
+当任一条件不满足时,跳过合并提示,继续第 9 步。
+
+### 如何检查
+
+用 cgraphx docs find 查找候选文档(已扫描过):
+
+```bash
+cgraphx docs find --concept=<new-doc-core-concept>
+cgraphx docs find --q=<keyword-from-title>
+```
+
+或当索引未建立时直接 grep 本地:
+
+```bash
+grep -rl "concepts:" docs/knowledge/ --include="*.md" | head -20
+```
+
+对每个候选文档,把 `document_type`、`concepts` 以及 `title` 和正文与新文档对比。
+
+### 提示
+
+当三个条件全部满足时,展示合并选项:
+
+```text
+发现已有文档 [existing-doc.md] 与新文档覆盖相同主题:
+
+- 文档类型: [type](相同/兼容)
+- 共享概念: [overlapping concepts]
+- 范围重叠: [brief description]
+
+是否将新内容合并到已有文档?合并后会保留已有文档的结构,追加新内容。选择 "否" 将保留两个独立文档。
+```
+
+### 合并行为
+
+当用户选择合并时:
+- 完整读取已有文档。
+- 在带日期的标题下或相应章节中追加新内容。
+- 更新 `updated` 日期,合并 `concepts`、`aliases`、`tags`、`related_code`、`related_documents`。
+- 如果新文件已写入磁盘,则删除新创建的文件。
+- 保留已有文档的 `title`,除非用户提供了更好的名称。
+
+## 质量规则
+
+知识文档的目的是记录代码、配置文件和 LLM 通用知识**无法提供**的内容。创建文档前,应用以下过滤标准。
+
+### 应当记录的内容
+
+记录至少满足以下**任一**条件的内容:
+- **非显而易见的业务逻辑** —— 代码中隐含但仅阅读代码无法直接看出的规则、约束或工作流。
+- **决策原因** —— 为什么做出了某个技术或架构选择,尤其是存在替代方案时。
+- **执行流程和运维操作** —— 跨多个系统的步骤流程或需要特定顺序的操作。
+- **陷阱、坑点和非显而易见的约束** —— 阅读代码的人会感到意外的事情。
+- **跨系统依赖** —— 组件如何跨越从单个文件无法看到的边界进行交互。
+- **历史背景** —— 过去的事故、变通方案或遗留约束,解释代码为什么是现在这样。
+
+### 不应记录的内容
+
+跳过属于以下类别的内容:
+- **已在代码或配置中记录的内容** —— 默认值、连接字符串、环境变量。代码是事实来源。
+- **通用编程知识** —— 任何合格开发者或 LLM 已知的内容。
+- **已应用的一次性修复** —— 如果修复已在代码/配置中,commit 历史会说明一切。
+- **逐字记录** —— 未经提炼的原始对话日志。提取持久性结论,而非得出结论的过程。
+- **工具使用说明** —— 如何使用 curl、git、npm 等。这些是通用知识。
+- **可从文件结构推导的信息** —— 模块角色、文件位置、API 端点列表。
+
+### 通用规则
+
+- 优先记录持久性知识而非对话式日志。
+- 保留足够的证据,使另一个 AI 无需重复整个探索即可信任该文档。
+- 用 `Open Questions` 章节或 `status: draft` 显式标记不确定性。
+- 对已知的陷阱、回归或意外约束使用 `warning` 类型文档。
+- 当文档被替代时使用 `superseded` 状态;在 `related_documents` 中链接替代文档。
+- 教程和指南尽可能包含 `Validation` 和 `Troubleshooting` 章节。
+
+## 文档拆分
+
+当内容在单个文档中覆盖多个不相关的概念时(例如一次对话讨论了几个不同的问题,用户要求记录整个会话),**拆分为独立文档**而非创建一个庞大的文件。
+
+拆分规则:
+- 每个文档应聚焦于**一个核心概念或一个连贯主题**。
+- 如果两个章节不共享 concepts、domains 或 `document_type`,它们应分别放入不同文件。
+- 当章节相关但目的不同(例如一个发现和由其触发的决策),如果 `concepts` 和 `domains` 显著重叠,可以保留在同一文档中。
+- 以主要主题命名每个文件。
+- 在 frontmatter 中使用 `related_documents` 交叉链接拆分后的文档。
+
+示例:一次涵盖"Redis 安装问题"和"order-service API 设计"的对话应生成两个文档:
+
+```text
+docs/knowledge/redis-installation-issues.md   (document_type: lesson, concepts: [Redis])
+docs/knowledge/order-service-api-design.md    (document_type: decision, concepts: [OrderService, API])
+```
+
+## 扫描提示
+
+创建或编辑 Markdown 元数据后,询问:
+
+```text
+是否需要触发一次扫描,把新的 Markdown 知识写入索引?
+```
+
+仅在用户同意后运行:
+
+```bash
+cgraphx docs index
+```
+
+扫描为**全量覆盖式重建**。运行后会清空旧索引,从 `docs/knowledge/` 下所有合规 `.md` 重建。事务性:任一步骤失败则回滚,旧索引不破坏。

package/dist/.claude-template/skills/code-impact-markdown/template-guide.md

@@ -0,0 +1,68 @@
+# 指南或教程类文档模板
+
+适用的 `document_type` 值：
+
+```text
+guide
+tutorial
+installation
+api
+faq
+note
+```
+
+## 完整模板
+
+```markdown
+# Redis Local Installation Guide
+
+## Summary
+
+说明本指南的目标。
+
+## Context
+
+说明本指南的适用场景。
+
+## Prerequisites
+
+列出所需的操作系统、工具、权限和前提假设。
+
+## Steps
+
+提供有序的操作步骤。
+
+## Configuration
+
+记录重要的文件、选项、环境变量或默认值。
+
+## Examples
+
+提供命令或使用示例。
+
+## Validation
+
+说明如何验证结果。
+
+## Troubleshooting
+
+记录常见故障和修复方法。
+
+## References
+
+链接源材料或相关的本地文档。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 指南目标 | 一句话说清读完本文能达成什么 |
+| Context | 适用场景 | 说明前置条件、目标读者、与其他指南的关系 |
+| Prerequisites | 前提条件 | 列出 OS、工具版本、权限、网络要求等 |
+| Steps | 操作步骤 | 有序编号，每步一个明确动作，附预期输出 |
+| Configuration | 配置说明 | 记录需要修改的文件、环境变量、默认值及推荐值 |
+| Examples | 使用示例 | 提供可直接复制运行的命令或代码片段 |
+| Validation | 验证方法 | 说明如何确认操作成功，附验证命令或检查点 |
+| Troubleshooting | 故障排除 | 按症状→原因→修复的格式记录常见问题 |
+| References | 参考资料 | 链接官方文档、相关本地文档或相关代码文件 |

package/dist/.claude-template/skills/code-impact-markdown/template-memory.md

@@ -0,0 +1,82 @@
+# 记忆或分析类文档模板
+
+适用的 `document_type` 值：
+
+```text
+conversation
+exploration
+finding
+analysis
+decision
+lesson
+warning
+rule
+architecture
+```
+
+## 完整模板
+
+```markdown
+# DefaultOrderService Exploration Findings
+
+## Summary
+
+陈述持久性结论。
+
+## Context
+
+解释为何进行此探索以及检查了什么范围。
+
+## Findings
+
+记录具体观察结果，而非推测。
+
+## Evidence
+
+引用文件、符号、命令、API 结果或相关代码片段。
+
+## Impact For Future Changes
+
+说明未来 AI/代码变更在编辑前应考虑什么。
+
+## Reuse Guidance
+
+说明另一个 AI 应在何时使用此文档。
+
+## Follow-ups
+
+列出后续工作。
+
+## Open Questions
+
+将未解决的问题与已确认的发现分开跟踪。
+```
+
+## 简短对话摘要模板
+
+用于简短的 conversation 记录：
+
+```markdown
+# Conversation Memory
+
+## Summary
+
+## Decisions
+
+## Follow-ups
+
+## Reuse Guidance
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 持久性结论 | 写结论而非过程；未来 AI 读到此处即可判断相关性 |
+| Context | 探索原因和范围 | 说明为什么需要探索、检查了哪些文件或模块 |
+| Findings | 具体观察 | 只记录确认的事实，推测放入 Open Questions |
+| Evidence | 证据引用 | 附上文件路径、符号名、命令输出等可验证的信息 |
+| Impact For Future Changes | 未来影响 | 说明修改相关代码前需要考虑什么 |
+| Reuse Guidance | 复用指引 | 说明另一个 AI 在什么场景下应参考此文档 |
+| Follow-ups | 后续工作 | 列出待完成的任务或待验证的假设 |
+| Open Questions | 未解决问题 | 与已确认的 Findings 分开，避免混淆 |

package/dist/.claude-template/skills/code-impact-markdown/template-runbook.md

@@ -0,0 +1,58 @@
+# 运维手册类文档模板
+
+适用的 `document_type` 值：
+
+```text
+runbook
+```
+
+## 完整模板
+
+```markdown
+# Redis Restart Runbook
+
+## Summary
+
+描述运维目标。
+
+## Symptoms
+
+列出本手册适用的信号。
+
+## Diagnosis
+
+说明确认情况的检查方法。
+
+## Procedure
+
+提供主要操作步骤。
+
+## Rollback
+
+说明操作失败时如何撤销或恢复。
+
+## Verification
+
+说明如何确认服务已恢复。
+
+## Escalation
+
+列出何时以及如何升级。
+
+## References
+
+链接相关文档或仪表盘。
+```
+
+## 各章节填写要点
+
+| 章节 | 用途 | 注意事项 |
+|------|------|----------|
+| Summary | 运维目标 | 一句话说清本手册解决什么问题 |
+| Symptoms | 触发信号 | 列出告警、日志特征、监控指标异常等具体信号 |
+| Diagnosis | 诊断方法 | 提供确认问题的检查命令和判断标准 |
+| Procedure | 操作步骤 | 有序编号，每步一个明确动作，附预期输出 |
+| Rollback | 回滚方案 | 说明操作失败或结果异常时如何恢复到操作前状态 |
+| Verification | 验证恢复 | 提供确认服务已正常恢复的检查命令和标准 |
+| Escalation | 升级路径 | 说明何时应停止自行处理并联系谁 |
+| References | 参考资料 | 链接监控仪表盘、相关文档、责任人联系方式 |