cgraphx 1.4.1 → 2.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Colby Mchenry
+Copyright (c) 2026 liulongfei
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.en.md

@@ -0,0 +1,126 @@
+[中文](README.md)
+
+# cgraphx
+
+> A local development-assistance system for Claude Code — 20+ skills define the workflow, backed by four project-local capabilities.
+
+One `cgraphx install` drops a full "clarify → spec → implement → test → knowledge capture" workflow into your project. Entirely **project-local, offline, and your data never leaves the repo**.
+
+---
+
+## Problems it solves
+
+Most AI-assisted development tools (including open-source ones) stop at code generation. cgraphx solves what happens **before** and **after**:
+
+| # | Pain point | How cgraphx addresses it |
+|---|---|---|
+| 1 | **Document drift → rework** — PRD/Spec/Plan: change one rule, regression-test all three; eventually none can be trusted | Spec is the sole contract; change one place. PRD, design doc, API doc are generated **post-release on demand**, not on the critical path |
+| 2 | **Business knowledge dies with the session** — understanding built during a conversation vanishes when the window closes | `knowledge-write` captures → `knowledge-recall` retrieves; a closed loop that grows richer with use |
+| 3 | **Data model re-learned from scratch every time** — field meanings, implicit relationships, pitfalls stepped on last time | `export-table-ddl` builds a local DDL baseline; `db-query` writes discoveries back to DISCOVERED blocks; re-dumps preserve accumulated knowledge |
+| 4 | **Requirement misinterpretation** — start coding from a one-liner, finish, discover you built the wrong thing | `/clarify-requirements` locks business boundaries and technical constraints before any code is written |
+| 5 | **Standards rely on memory** — coding/interface/data/commit standards written but never read | Standards are auto-delivered at execution time: plan marks "mandatory references" + a commit gate intercepts `git commit` |
+| 6 | **The workflow stops at "code written"** — testing is manual: record endpoints by hand, run by hand, verify by hand | `/write-api` auto-generates test cases from spec → `/run-api-test` executes + forces DB verification for write APIs (HTTP 200 ≠ pass) |
+| 7 | **Work is untraceable** — "what did you do this month?" answered by scavenging git log | timeline auto-records dev events (~5ms each); `/developer-timeline` generates daily/weekly/monthly reports on demand |
+| 8 | **Upgrades leave residue** — renamed skills leave stale directories; agents can still trigger outdated logic | `deprecated-assets.json` manifest + automatic cleanup on `install` |
+
+## How it works
+
+cgraphx = **skill workflow (the core) + CLI capabilities (the support)**.
+
+- **Skills are the core** — 20+ markdown process guides defining "how requirements should be done." The agent reads skills and follows the process.
+- **The CLI is the support** — four project-local capabilities a skill alone can't provide:
+
+| Subsystem | Command | Capability |
+|---|---|---|
+| **docs** knowledge base | `cgraphx docs` | Index and search `docs/knowledge/*.md` (LIKE queries, CJK-friendly) |
+| **db** database | `cgraphx db` | Read-only introspection for MySQL / PostgreSQL; safety layer structurally rejects writes |
+| **timeline** | `cgraphx timeline` | Auto-records development events via hooks; powers reports |
+| **features** requirements index | `cgraphx features` | Locate requirements by owner / keyword (filesystem-derived, no DB) |
+
+Each project gets its own `.cgraphx/cgraphx.db`: self-contained, no server, no telemetry.
+
+## Workflow overview
+
+```
+knowledge-recall (auto)
+        │
+        ▼
+/clarify-requirements ──→ /write-spec ──→ /write-plan (optional)
+     clarify               sole contract      execution plan
+        │                                        │
+        │            ┌───────────────────────────┘
+        ▼            ▼
+  /implementation (simple) or /subagent-implement (complex)
+        │
+   ┌────┴─────────────────────────────┐
+   ▼              ▼                   ▼
+/write-api    /write-unit-test-spec  delivery:
+→ /run-api-test → /write-unit-test-code  /knowledge-write capture
+  API testing     unit testing         commit gate
+
+── post-release · on demand (off the critical path) ──────
+/write-prd (stakeholder review)  /write-design-doc  /write-api-doc
+```
+
+Everyday default: **clarify + implement**. Add spec / plan / tests as complexity grows.
+
+## Install
+
+```bash
+npm install -g cgraphx    # Node.js >=22.5 <27 (built-in node:sqlite, no native deps)
+```
+
+```bash
+cd your-project
+cgraphx install           # deploys skills → .claude/ + wires hooks + initializes .cgraphx/
+```
+
+Restart Claude Code and you're set.
+
+| Command | What it does |
+|---|---|
+| `cgraphx install` | One command per project: full setup |
+| `cgraphx upgrade` | Self-update via npm; re-run `install` in each project to refresh skills |
+| `cgraphx uninstall` | Removes skills/config by manifest + deletes `.cgraphx/` (`--keep-data` to preserve) |
+
+## Best getting-started practice
+
+Installing is only step one. Recommended order — **set standards, talk business, then do requirements**:
+
+**1. Set standards · `/init-project-guides`**
+
+Generates five quick-reference standards in `docs/guides/` (coding / interface / data / testing / git). A standard = a project's **deliberate deviation** from the default — "no `ORDER BY` in SQL", "money is always `decimal(12,2)`" — the things most easily deviated from with no tooling to enforce them. These guides become mandatory reads for later tasks.
+
+**2. Talk business · chat with Claude Code about your project**
+
+Before any requirement, talk about the business. The agent auto-recalls settled concepts from the knowledge base and aligns on jargon. Capture business entities with `/knowledge-write` as you go — the knowledge base grows richer with use.
+
+**3. Do requirements · start with `/clarify-requirements`**
+
+Enter the main workflow: clarify → spec (`/write-spec`) → implement → test. With the first two steps done, clarification happens in a shared context, not from scratch.
+
+> Standards first (the agent knows the "rules"), then business alignment (the agent knows the "jargon") — only then does clarifying a concrete requirement pay off.
+
+## Knowledge flywheels
+
+cgraphx has two knowledge accumulation loops that compound over time:
+
+**Business knowledge**: `/knowledge-write` captures to `docs/knowledge/` → `knowledge-recall` auto-retrieves before the next task → new concepts get captured → the thicker the base, the better the agent understands your project.
+
+**Data model**: `/export-table-ddl` builds a DDL baseline → `db-query` reads local files first (cheap) → discoveries written back to DISCOVERED blocks → re-dumps preserve accumulation → the agent never re-steps on the same mine.
+
+## Requirements
+
+- **Claude Code** (skill deployment, hooks, and timeline depend on its mechanisms)
+- **Node.js** `>=22.5 <27` (built-in `node:sqlite`; no native deps, no wasm)
+- Project-local, offline
+
+> The `docs` and `db` CLI capabilities are agent-agnostic and can be invoked standalone; but as a development system (skills + hooks + timeline), cgraphx targets Claude Code.
+
+## About the name
+
+cgraphx is named after the 1.x code graph. 2.0 is a breaking rebuild: the graph layer is gone entirely, refocused on the skill workflow + four local capabilities. 1.x → 2.0 is not compatible; see `CHANGELOG.md`.
+
+## License
+
+[MIT](LICENSE) © liulongfei

package/README.md

@@ -1,242 +1,124 @@
 # cgraphx
 
-> Local-first code intelligence for AI coding agents.
-> Based on [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph),originally authored by **Colby Chenry**. See [Acknowledgements](#acknowledgements).
+> 给 Claude Code 的本地研发辅助系统——20+ 个 skill 定义研发流程,四个项目本地能力在背后支撑。
 
-## What it is
+一条 `cgraphx install`,把「需求澄清 → 规格 → 实现 → 测试 → 知识沉淀」的完整研发流程装进你的项目。全程**项目本地、离线运行、数据不出仓库**。
 
-cgraphx 是一个**本地优先**的代码智能工具,**基于 codegraph 衍生** —— 在原版代码图谱之上增加了中文 skills 工作流、markdown 知识库、数据库查询、Developer Timeline:
+---
 
-- 用 tree-sitter 解析代码库,把 symbols / edges / files 存到 SQLite(FTS5)
-- 暴露 knowledge graph 给 AI agent(Claude Code / Cursor / Codex / opencode / ...)
-- per-project 数据在 `.cgraphx/`,**不外传**
-- CLI / MCP server / Library 三种使用方式,同一份二进制
+## 解决什么问题
 
-## Key Features
+市面上的 AI 辅助研发工具(包括开源的)基本只覆盖到「代码生成」为止。cgraphx 解决的是代码生成**之后**和**之前**的问题:
 
-- **本地优先** —— 所有数据在 `.cgraphx/cgraphx.db`,SQLite + WAL,sub-millisecond reads
-- **自动同步** —— 文件改动后增量同步(native FSEvents / inotify / RDCW)
-- **多语言** —— TypeScript / JavaScript / Python / Go / Rust / Java / C# / PHP / Ruby / C / C++ / Swift / Kotlin / Scala / Dart / Svelte / Vue / Astro / Lua / Luau / R / Liquid / Pascal/Delphi ...
-- **多 Agent** —— Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro
-- **跨平台** —— macOS / Linux / Windows,x64 + arm64
-- **MCP 单工具入口** —— `codegraph_explore` 一次调用拿源码 + 调用路径 + 影响半径
-- **多子系统** —— code graph + markdown knowledge base + db introspection + developer timeline
+| # | 痛点 | cgraphx 的解法 |
+|---|---|---|
+| 1 | **文档漂移返工**——PRD/Spec/Plan 三份文档,改一条规则要回归全部,最终没一份能信 | Spec 是唯一契约,变更只改一处;PRD、设计文档、接口文档**发布后按需生成**,不在开发主链上 |
+| 2 | **业务知识随会话消失**——和 agent 聊出来的理解,关掉窗口就丢了,下次从零开始 | `knowledge-write` 沉淀 → `knowledge-recall` 召回,闭环积累,越用越厚 |
+| 3 | **数据模型每次从零理解**——字段含义、隐式关系,上次踩的坑下次又踩 | `export-table-ddl` 建本地 DDL 基线,`db-query` 探索发现回写 DISCOVERED 块,重 dump 保留积累 |
+| 4 | **需求理解偏差**——拿到一句话就开写,做完发现理解错了 | `/clarify-requirements` 先锁业务边界和技术约束,不急着写代码 |
+| 5 | **规范靠人记**——编码/接口/数据/提交规范,写了没人看 | 规范在执行期自动送达:plan 打「强制引用」标注 + commit 门禁拦截 |
+| 6 | **流程到写完代码就断了**——测试是人的事,手动录接口、手动跑、手动验 | `/write-api` 从 spec 自动生成测试用例 → `/run-api-test` 执行 + 强制查 DB 验数据,闭环不断链 |
+| 7 | **工作不可追溯**——领导问「这个月做了什么」,翻 git log 拼凑 | timeline 自动记录开发事件(每次 ~5ms),`/developer-timeline` 按需生成日报/周报/月报 |
+| 8 | **工具升级留残渣**——skill 改名后旧版本残留,agent 仍能触发过时逻辑 | `deprecated-assets.json` 清单 + install 自动清理 |
 
-## Get Started
+## 它怎么工作
 
-### 1. Install the CLI
+cgraphx = **skill 流程(主体)+ CLI 能力(支撑)**。
 
-```bash
-# npm
-npm i -g cgraphx
-
-# 或本地构建
-git clone https://github.com/smdnkB/cgraphx.git
-cd cgraphx
-npm install && npm run build
-node dist/bin/codegraph.js --version
-```
+- **skill 是主体**——20+ 个 markdown 流程指引,定义「需求该怎么做」。agent 读 skill、按流程办事。
+- **CLI 是支撑**——提供 skill 无法替代的四个项目本地能力:
 
-### 2. Wire up your agent(s)
-
-```bash
-cgraphx install
-```
+| 子系统 | 命令 | 能力 |
+|---|---|---|
+| **docs** 知识库 | `cgraphx docs` | 索引并检索 `docs/knowledge/*.md`(LIKE 查询,中文友好) |
+| **db** 数据库 | `cgraphx db` | 只读内省 MySQL / PostgreSQL,安全层从构造上拒绝写操作 |
+| **timeline** 时间线 | `cgraphx timeline` | 通过 hooks 自动记录开发事件,支撑日/周/月报 |
+| **features** 需求索引 | `cgraphx features` | 按负责人/关键词定位需求(文件系统派生,无 DB) |
 
-自动检测并配置:Claude Code / Cursor / Codex CLI / opencode / Hermes / Gemini / Antigravity / Kiro。
-仅写入 agent 的 MCP server config,不索引代码。
+每个项目一个独立的 `.cgraphx/cgraphx.db`,自包含,无服务端,无遥测。
 
-### 3. Initialize each project
+## 工作流全景
 
-```bash
-cd your-project
-cgraphx init
+```
+knowledge-recall(自动召回)
+        │
+        ▼
+/clarify-requirements ──→ /write-spec ──→ /write-plan(可选)
+     澄清                  唯一契约          执行计划
+        │                                        │
+        │            ┌───────────────────────────┘
+        ▼            ▼
+  /implementation(简单) 或 /subagent-implement(复杂)
+        │
+   ┌────┴─────────────────────────────┐
+   ▼              ▼                   ▼
+/write-api    /write-unit-test-spec  交付收尾:
+→ /run-api-test → /write-unit-test-code  /knowledge-write 沉淀
+  接口测试       单元测试              commit 门禁
+
+── 发布后 · 按需(不在主链)──────────────
+/write-prd(业务方审阅)  /write-design-doc(设计文档)  /write-api-doc(接口文档)
 ```
 
-`cgraphx init` 创建 `.cgraphx/` 目录并构建完整 graph,一步到位。
-
-### 4. Auto-sync(默认开启)
-
-文件改动后自动增量同步,无需手动操作。`cgraphx status` 看新鲜度。
+日常默认两步:**澄清 + 实现**。复杂需求按需补规格/计划/测试。
 
-### Uninstall
+## 安装
 
 ```bash
-cgraphx uninstall      # 从所有 agent 移除 MCP 配置(保留项目索引)
-cgraphx uninit         # 移除当前项目的 .cgraphx/(--force 跳过确认)
+npm install -g cgraphx    # Node.js >=22.5 <27(内置 node:sqlite,无原生依赖)
 ```
 
-## CLI Reference
-
 ```bash
-# 安装 / 配置
-cgraphx install                # 配置 agent
-cgraphx uninstall              # 移除 agent 配置
-cgraphx upgrade [version]      # 升级(--check 看是否有新版)
-
-# 项目索引
-cgraphx init [path]            # 初始化项目 + 构建 graph
-cgraphx uninit [path]          # 移除项目索引
-cgraphx index [path]           # 全量重建(--force / --quiet)
-cgraphx sync [path]            # 增量同步
-cgraphx status [path]          # 索引状态
-cgraphx unlock [path]          # 清除 stale lock
-
-# 查询(主 graph)
-cgraphx explore <query>        # 自然语言探索,主入口(同 MCP 的 codegraph_explore)
-cgraphx node <symbol|file>     # 单符号详情 / 文件内容(带行号)
-cgraphx query <search>         # 按名字搜符号(--kind / --limit / --json)
-cgraphx callers <symbol>       # 谁调用 X
-cgraphx callees <symbol>       # X 调用谁
-cgraphx affected [files...]    # 改这些文件受影响的测试(--stdin / --filter)
-cgraphx files [path]           # 项目文件结构
-
-# 子系统
-cgraphx db <subcmd>            # 数据库 introspection(MySQL/PG,只读,CLI-only)
-cgraphx docs <subcmd>          # Markdown 知识库(docs/knowledge/)
-cgraphx timeline <subcmd>      # 开发历史(prompt / tool / commit 事件流)
-
-# 其他
-cgraphx daemon                 # 管理后台 daemon
-cgraphx telemetry [on|off]     # 匿名遥测开关
-cgraphx version                # 版本
-cgraphx help [command]         # 帮助
-```
-
-详细参数见 `cgraphx help <command>`。
-
-## MCP Tools
-
-CodeGraph 作为 MCP server 时,默认**只暴露一个工具**:
-
-| Tool | Purpose |
-|---|---|
-| `codegraph_explore` | 主入口。给符号名 / 文件 / 自然语言问题,返回相关符号源码 + 调用路径(含动态派生边)+ 影响半径。一次调用通常够答完整问题 |
-
-其他工具(`codegraph_node` / `codegraph_search` / `codegraph_callers` / `codegraph_callees` / `codegraph_impact` / `codegraph_files` / `codegraph_status`)**功能保留,默认不暴露**在 MCP surface —— 它们的输出已经内联在 `codegraph_explore` 里。需要时:
-
-- 用 `CGRAPHX_MCP_TOOLS=explore,node,search,callers` 环境变量重新启用
-- 或走 CLI 等价命令(`cgraphx node` / `query` / `callers` / ...)
-
-## How It Works
-
-```
-┌──────────────────────┐
-│   AI agent           │  "How does X reach Y?"
-│ (Claude/Cursor/...)  │  → calls codegraph_explore directly
-└──────────┬───────────┘
-           │
-           ▼
-┌──────────────────────────────────────────┐
-│         CodeGraph MCP Server             │
-│  explore: source + flow + blast radius   │
-└──────────┬───────────────────────────────┘
-           │
-           ▼
-┌──────────────────────────────────────────┐
-│       SQLite Knowledge Graph             │
-│  symbols · edges · files · FTS5          │
-│  (.cgraphx/cgraphx.db)               │
-└──────────────────────────────────────────┘
+cd your-project
+cgraphx install           # 部署 skills → .claude/ + 接入 hooks + 初始化 .cgraphx/
 ```
 
-1. **Extraction** — tree-sitter 解析为 AST,语言特定 query 提取 nodes / edges
-2. **Storage** — SQLite + WAL + FTS5,per-project 隔离
-3. **Resolution** — 解析 references(imports → source,calls → definitions,framework patterns)
-4. **Auto-Sync** — 原生 OS 文件事件 + debounce(2s)+ 增量同步
+重启 Claude Code 即可。
 
-## Configuration
-
-| 路径 / 文件 | 用途 |
+| 命令 | 作用 |
 |---|---|
-| `.cgraphx/cgraphx.db` | 项目主索引(SQLite,symbols/edges/files + markdown_* + timeline_* 同库不同表) |
-| `.cgraphx/db-profiles.json` | 数据库 profiles(项目级,优先于用户级) |
-| `~/.cgraphx/db-profiles.json` | 用户级数据库 profiles |
-| `docs/knowledge/*.md` | 项目业务知识库(给 `cgraphx docs` 子系统扫) |
-| `.claude/settings.json` | agent MCP 配置(`cgraphx install` 写入) |
+| `cgraphx install` | 项目内一条命令接入全部能力 |
+| `cgraphx upgrade` | npm 自更新;升级后到各项目重跑 `install` 刷新 skill |
+| `cgraphx uninstall` | 按清单移除 skills/配置 + 删 `.cgraphx/`(`--keep-data` 保留数据) |
 
-### 常用环境变量
+## 最佳起步实践
 
-- `CGRAPHX_NO_TIMELINE=1` —— 禁用 timeline hooks
-- `CGRAPHX_DB_QUERY_DISABLED=1` —— 禁用 db-query 子系统
-- `CGRAPHX_MCP_TOOLS=explore,node,...` —— 自定义 MCP 暴露的工具集
-- `CGRAPHX_NO_DAEMON=1` —— 禁用共享 daemon(每 session 独立进程,适合 WSL2 `/mnt`)
-- `CGRAPHX_DIR=.cgraphx-win` —— 区分 Windows / WSL 共享 checkout 的索引
+接入只是第一步。推荐这个顺序——**先立规范、再聊业务、然后做需求**:
 
-## Subsystems
+**1. 立规范 · `/init-project-guides`**
 
-除了主 code graph,cgraphx 还有三个独立子系统:
+生成 `docs/guides/` 五份规范(编码/接口/数据/测试/Git)。规范 = 项目对默认做法的**有意偏离**——「SQL 禁止 `ORDER BY`」「金额一律 `decimal(12,2)`」这类最容易偏离又没有工具兜底的约定。这些 guide 是后续任务的强制读点。
 
-| 子系统 | 命令 | 用途 |
-|---|---|---|
-| **Markdown Knowledge Base** | `cgraphx docs <subcmd>` | 索引 `docs/knowledge/` 下的业务决策、概念、教训;hybrid search(BM25 + 向量) |
-| **Database Introspection** | `cgraphx db <subcmd>` | 外部 MySQL/PostgreSQL 只读查询(CLI-only,内置安全层) |
-| **Developer Timeline** | `cgraphx timeline <subcmd>` | 开发事件流(user prompt / tool use / git commit),per-project 隔离 |
+**2. 聊业务 · 和 Claude Code 聊项目**
 
-各子系统有独立的表 / schema 版本 / 安全约束,详见 CLAUDE.md。
+做需求前先聊业务。agent 会自动从知识库召回已沉淀的概念、对齐术语;边聊边用 `/knowledge-write` 把业务实体沉淀下来。知识库越用越厚,重复解释和重复踩坑越少。
 
-## Supported Platforms
-
-| Platform | Architectures |
-|---|---|
-| macOS | x64, arm64 |
-| Linux | x64, arm64 |
-| Windows | x64, arm64 |
-
-## Supported Agents
-
-`cgraphx install` 自动检测并配置:
-
-- Claude Code
-- Cursor
-- Codex CLI
-- opencode
-- Hermes Agent
-- Gemini CLI
-- Antigravity IDE
-- Kiro
-
-## Supported Languages
-
-| Language | Status |
-|---|---|
-| TypeScript / JavaScript | Full |
-| Python | Full |
-| Go | Full |
-| Rust | Full |
-| Java | Full |
-| C# | Full |
-| PHP | Full |
-| Ruby | Full |
-| C / C++ | Full |
-| Swift / Kotlin / Scala / Dart | Full |
-| Svelte / Vue / Astro | Full(含 framework routes) |
-| Lua / Luau / R | Full |
-| Liquid / Pascal / Delphi | Full |
-| Objective-C | Partial(类、协议、方法、`@property`、`#import`、message sends;`.mm` ObjC++ 可能不完整) |
+**3. 做需求 · `/clarify-requirements` 起步**
 
-## Troubleshooting
+进入主工作流:澄清 → 规格(`/write-spec`)→ 实现 → 测试。有了前两步,澄清才有共同语境。
 
-**"CodeGraph not initialized"** — 在项目目录跑 `cgraphx init`。
+> 先有规范(agent 懂「规矩」),再对齐业务(agent 懂「黑话」),然后做需求才事半功倍。
 
-**Indexing 慢** — 确认 `node_modules` / `dist` 等大目录被默认排除;加 `--quiet`。
+## 知识闭环
 
-**MCP `database is locked`** — 不应出现(本构建用 `node:sqlite` + WAL,并发读不阻塞写)。若仍出现:`cgraphx status` 看 `Journal` 字段,非 `wal` 说明 WAL 无法启用(网络盘 / WSL2 `/mnt`),把项目移到本地盘。
+cgraphx 有两个知识积累闭环,用得越多越值钱:
 
-**MCP server 连不上** — agent 自己启动 server,不需要手动 launch。确认 `cgraphx status` 正常 + MCP config 路径正确;不行就 `cgraphx install` 重写配置。
+**业务知识**:`/knowledge-write` 沉淀到 `docs/knowledge/` → `knowledge-recall` 下次开发前自动召回 → 新概念继续沉淀 → 知识库越厚,agent 越懂你的项目。
 
-**Missing symbols** — MCP 自动同步有 ~1s 延迟;不行就 `cgraphx sync`。确认文件语言被支持、不在 `.gitignore` 排除目录里。
+**数据模型**:`/export-table-ddl` 建 DDL 基线 → `db-query` 查数据时首选读本地(便宜) → 探索发现回写 DISCOVERED 块 → 重 dump 保留积累 → agent 不再重复踩坑。
 
-**Windows + WSL 共享 checkout** —— 不要让两边用同一个 `.cgraphx/`。给其中一边设 `CGRAPHX_DIR=.cgraphx-win`(或类似),两边各用各的索引。
+## 要求
 
-## Acknowledgements
+- **Claude Code**(skill 部署、hooks、timeline 均依赖其机制)
+- **Node.js** `>=22.5 <27`(内置 `node:sqlite`,无原生依赖、无 wasm)
+- 项目本地、离线运行
 
-cgraphx is based on [**colbymchenry/codegraph**](https://github.com/colbymchenry/codegraph),originally authored by **[Colby Chenry](https://github.com/colbymchenry)**.
+> `docs` 与 `db` 两个 CLI 能力本身与 agent 无关,可独立调用;但作为一套研发系统(skills + hooks + timeline),cgraphx 面向 Claude Code。
 
-All credit for the original architecture — tree-sitter-based extraction, the MCP single-tool design, the dynamic-dispatch synthesis, and the broader project direction — belongs to the original author and contributors.
+## 关于名字
 
-This fork exists for internal customization; upstream is the source of truth for the project's roadmap and the canonical place to contribute back.
+cgraphx 得名于 1.x 的代码图谱(code graph)。2.0 是破坏性重构:图谱层已整体移除,聚焦到 skill 流程 + 四个本地能力。1.x → 2.0 不兼容,详见 `CHANGELOG.md`。
 
-## License
+## 许可证
 
-MIT
+[MIT](LICENSE) © liulongfei

package/dist/.claude-template/.cgraphx/timeline-current-turn.json

@@ -0,0 +1 @@
+{"turn_id":"cb2d9f37-0878-4b81-a629-d30703ed6394","session_id":"57ce4488-65ae-4599-963e-51a565cab791","ts":"2026-07-31T23:45:21.037Z"}

package/dist/.claude-template/CLAUDE.md

@@ -0,0 +1,10 @@
+## 项目介绍
+这是一个【项目类型】项目,主要功能包含【核心功能】。
+
+本项目用 cgraphx 的 skill 流程做需求。**流程全图见 `FLOW-MAP.md`**(各流程的链 / 前置依赖 / 强制读 / 产物落点);主线一句话:knowledge-recall → clarify → spec(唯一契约)→ plan(可选)→ implementation / subagent-implement,平行支线:接口测试 / 单元测试 / 知识库 / 规范(guides)。
+
+## 项目约定
+
+- **schema 变更约定(全量+增量双层维护)**:见 `docs/guides/data-standards.md`「Schema 变更约定」节——动表时按其命名与维护规则执行(规范缺失先 `/init-project-guides` 补齐,动表前必读)。
+
+你负责按阶段推进需求,并在每个任务/阶段收尾时**主动给出下一步建议**(2–4 条,标注对应 skill;不要每轮都附,用户已明确就直接执行)。阶段判断:看需求目录 `docs/features/<日期>-<编号>-<前缀>/` 已有产物(有无 spec / plan / 实现)+ 对话上下文。

package/dist/.claude-template/FLOW-MAP.md

@@ -0,0 +1,107 @@
+# 流程地图
+
+本项目开发流程的总索引:只放定位、顺序、依赖、指针——各 skill 的内部规则读 skill 本身。
+
+**阶段判断**:看需求目录 `docs/features/<日期>-<编号>-<前缀>/` 已有产物(有无 spec / plan / 实现)+ 对话上下文,决定现在哪一步、下一步做什么。
+
+## 依赖总览
+
+```text
+                knowledge-recall(先聊概念,实体条目优先)
+                        │
+                        ▼
+  clarify-requirements(必经;只锁业务决策 + 技术约束,手段归 plan)
+                        │
+                        ▼
+                  write-spec ◄── 唯一契约(声明负责人,进个人需求索引)
+                        │
+                        ▼ 可选
+                    write-plan
+                (手段:无业务可观察→plan 自主;有→回跳 spec)
+                        │
+                        ▼
+    implementation(简单)│ subagent-implement(复杂,需 plan)
+                        │
+        ┌───────────────┼────────────────────────┐
+        ▼               ▼                        ▼
+  write-api        write-unit-test-spec     交付收尾:
+  → run-api-test   → write-unit-test-code   沉淀提示 → knowledge-write
+  (接口测试)     (单元测试,代码完成后)     commit 门禁 → git-standards.md
+
+  ── 推荐发布后 · 按需(不在主链,不参与门禁); 原因: 发布前写 PRD:写的是预期,实现过程中一定会漂移,发布后 PRD 就过期了,给业务方看反而误导 ──────────────────
+  write-prd(业务方/客户审阅,任意时刻可执行,推荐发布后)
+  write-design-doc(设计文档,自测通过后)
+  write-api-doc(接口文档,接口开发完毕后)
+
+guides:write-plan 读取并结晶 + 任务打「强制引用」标注(implementation / subagent-implement 执行标注,仅无 plan 时自识别)· write-api 独立读接口规范 · commit 门禁 → git-standards;缺失 → init-project-guides 先补(中断)
+```
+
+## 设计流程
+
+- **链**:`/clarify-requirements` → `/write-spec` →(`/write-plan` 可选)
+- **前置**:knowledge-recall 先聊相关概念(clarify 第 1 步内置提示)
+- **分工**:clarify 只锁业务边界 + 技术约束(读无界、决策有界);spec 是唯一契约,澄清总结只是输入;手段选型在 plan 结合代码定,按业务可观察性分档——无业务可观察后果的 plan 自主并记录,有的回跳 spec 业务拍板
+- **产物**:`docs/features/<feature-id>/<前缀>-spec.md`、`plan/<前缀>-index.md` 等;spec 头部声明 `> 负责人:`,收尾自动进个人需求索引(`cgraphx features list --mine` 按人找需求)
+- **PRD 不在主链上**:`/write-prd` 是补充文档,任意时刻可执行,推荐功能发布后按需执行——发布后写的是实际交付的行为,不存在文档与系统漂移的问题
+
+## 开发流程
+
+- **链**:`/implementation`(简单:1-3 文件 / 单模块)| `/subagent-implement`(复杂:≥3 任务跨域,主 agent 只协调、派子 agent 实现)
+- **前置**:spec 必有;subagent-implement 需 plan
+- **强制读**:规范由 plan 打「强制引用」标注(write-plan 按任务类型机械标:schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注,无 plan 时 implementation 自行识别;**缺失 → 中断,先 `/init-project-guides` 补齐**
+- **小步提交**:plan 把可独立提交的任务(完成后仓库可工作)标「独立提交」并把 `git-standards.md` 提交规范结晶进 index「提交规范」节;implementation / subagent-implement 每完成一个标注任务并按规范自查后提交(原子历史,好 review / revert / bisect),precommit 门禁退化为兜底。未标注的任务不擅自提交,push 永远归用户。
+- **收尾**:沉淀提示(新增/变更实体、坑、隐式约束 → `/knowledge-write`);commit 门禁由 precommit-check hook 指向 `docs/guides/git-standards.md`,被拦 → 按 plan 已结晶的「提交前检查点」自查 staged diff(plan 无结晶时才 Read 原文件)
+
+## 接口测试流程
+
+- **链**:`/write-api`(生成 .bru + 测试规格)→ `/run-api-test`(跑测试 + 核实写接口 DB 副作用 + 出报告;**写接口必查 DB 验数据,HTTP 200 ≠ 通过**)
+- **前置**:spec + 实现完成;run-api-test 也可独立跑已有 .bru
+- **强制读**:write-api 执行前读 `docs/guides/interface-standards.md`(缺失 → `/init-project-guides` 中断)
+- **产物**:`docs/bruno/<服务>/<需求前缀>/`(bruno app 可直接打开)+ feature 目录下测试规格与报告
+
+## 单元测试流程
+
+- **链**:`/write-unit-test-spec`(零代码依赖,从 spec 派生场景)→ `/write-unit-test-code`(填实测试 + 跑 + 出报告;找不到测试规格直接退出要求先跑前者)
+- **前置**:spec + 实现完成(代码写完后独立流程,与接口测试同节奏)
+- **产物**:feature 目录下测试规格与报告 + 项目测试目录的测试代码
+
+## 知识库
+
+- **写**:`/knowledge-write`(双层结构:实体 `concept` 主条目 + 流程条目,正向引用 + 反查派生参与业务;写入前必过 `cgraphx docs validate`)| `/knowledge-init`(陌生项目批量探索建档)
+- **读**:knowledge-recall(子 agent 语义召回,实体条目优先)| knowledge-api(已知概念名精确查)
+- **目录**:`docs/knowledge/*.md`;沉淀时机由开发流程交付收尾提示触发
+
+## 数据库与 Schema
+
+- **全量(单一事实源)**:`docs/schema-knowledge/<工程>/ddl/<表名>.sql`,一表一文件、始终最终态——维护规则见 `docs/guides/data-standards.md`「Schema 变更约定」节(全量写透 + 需求内增量流水 `sql/[<工程>/]<序号>-<动作名>.sql`)
+- **基线与校准**:`/export-table-ddl`(建基线 / 周期校准,DISCOVERED 块重导保留)
+- **查数据**:`db-query`(首选读本地 DDL,缺失连库兜底;探索发现回写 DISCOVERED 块;只读)
+
+## 规范(guides)
+
+- `/init-project-guides` 生成 `docs/guides/`:`coding-standards.md` / `interface-standards.md` / `data-standards.md`(数据与模型,含 schema 变更约定)/ `testing-standards.md` / `git-standards.md`(提交门禁文件)
+- **决策时读点(write-plan,缺失中断;规范结晶进具体契约)**:
+
+| guide 文件 | write-plan 读点 |
+|---|---|
+| `data-standards.md` | schema 任务(含「Schema 变更约定」) |
+| `interface-standards.md` | 接口任务 |
+| `coding-standards.md` | 所有任务(契约部分) |
+| `testing-standards.md` | plan 不读;由测试流程(`write-unit-test-code` / `run-api-test`)自读 |
+| `git-standards.md` | 有「独立提交」任务时结晶进 index「提交规范」节(plan 级,一次)+ precommit-check 门禁兜底(deny → 按已结晶的检查点自查) |
+- **执行期送达**:任务按映射打「强制引用」标注(schema → data-standards.md;接口 → interface-standards.md;动码 → coding-standards.md);有 plan 时 implementation / subagent-implement 只读标注、不自行识别,无 plan 时 implementation 自行识别;write-api 不依赖 plan,执行前独立读 interface-standards.md(自有门禁)。**git-standards.md 例外**:不是每任务强制引用,而是 plan 级结晶进 index「提交规范」节,实施期提交时直接用、门禁仅兜底——消除多次小步提交的重复读取成本。**testing-standards.md 也不走 plan 标注**:测试不进 plan,由独立测试流程(`write-unit-test-code` / `run-api-test`)自读。
+
+## 事后文档(发布后 · 按需,不在开发主链)
+
+设计原则:前期文档越少,变更时的回归成本越低;spec 是唯一契约,其余文档发布后按实际交付物生成,避免「文档描述预期、系统做了另一件事」的漂移。
+
+| skill | 产物 | 推荐时机 | 说明 |
+|---|---|---|---|
+| `/write-prd` | 业务需求文档 | 发布后按需 | 给领导/客户/业务方审阅;发布后写 = 记录实际交付的行为,不是事前审批件 |
+| `/write-design-doc` | 设计文档 | 自测通过后 | 从 knowledge + spec/plan 合成,面向研发/技术负责人/维护者 |
+| `/write-api-doc` | 接口文档 | 接口开发完毕后 | 仅覆盖本次新增接口,从 spec + 代码反向提取 |
+
+## 其他能力
+
+- `/developer-timeline` 开发事件流与日报/周报/月报 | `/write-workload` 交付工作量汇报
+- 可视化:handdrawn-sketch-engine / handdrawn-deck(手绘信息图与翻页演示)