@jahanxu/code-flow 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,88 @@
+# code-flow
+
+一个用于快速初始化与管理项目规范的命令行工具。通过全局安装后执行 `code-flow init`，自动生成项目约定文件与目录结构，帮助团队统一流程并提升协作效率。
+
+## 安装
+
+npm：
+
+```bash
+npm i -g @jahanxu/code-flow
+```
+
+pnpm：
+
+```bash
+pnpm add -g @jahanxu/code-flow
+```
+
+## 升级
+
+npm：
+
+```bash
+npm i -g @jahanxu/code-flow@latest
+```
+
+pnpm：
+
+```bash
+pnpm add -g @jahanxu/code-flow@latest
+```
+
+## 卸载
+
+npm：
+
+```bash
+npm rm -g @jahanxu/code-flow
+```
+
+pnpm：
+
+```bash
+pnpm remove -g @jahanxu/code-flow
+```
+
+## 基本用法
+
+初始化：
+
+```bash
+code-flow init
+```
+
+查看帮助：
+
+```bash
+code-flow --help
+```
+
+## 生成的目录与文件
+
+运行 `code-flow init` 后，将在项目根目录生成（或更新）以下结构：
+
+```
+.code-flow/
+.claude/
+CLAUDE.md
+```
+
+## 依赖说明
+
+- 需要 `python3` 版本 3.9 及以上
+- 需要安装 `pyyaml`（`cf_init` 会尝试自动安装，失败会提示手动处理）
+
+## 常见问题
+
+- EOTP（`--otp`）
+  - 原因：启用了 npm/pnpm 的一次性密码或 2FA。
+  - 处理：按提示输入 OTP，或使用 `--otp` 重新执行安装命令。
+
+- E402（`--access=public`）
+  - 原因：发布/安装时访问级别不匹配或权限不足。
+  - 处理：必要时使用 `--access=public` 重新发布或检查权限配置。
+
+- name 冲突
+  - 原因：本地或全局已有同名命令/包。
+  - 处理：先卸载冲突包或更换名称后再安装。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahanxu/code-flow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

package/src/adapters/claude/CLAUDE.md

@@ -0,0 +1,33 @@
+# Project Guidelines
+
+## Team Identity
+- Team: [team name]
+- Project: [project name]
+- Language: [primary language]
+
+## Core Principles
+- All changes must include tests
+- Single responsibility per function (<= 50 lines)
+- No loose typing or silent exception handling
+- Handle errors explicitly
+
+## Forbidden Patterns
+- Hard-coded secrets or credentials
+- Unparameterized SQL
+- Network calls inside tight loops
+
+## Spec Loading
+This project uses the code-flow layered spec system.
+
+**Auto-inject rule**: Before answering any coding question, you MUST:
+1. Determine domain(s) from the user's question:
+   - **frontend**: mentions components, pages, hooks, styles, UI, CSS, React/Vue/Angular, or references .tsx/.jsx/.css/.scss files
+   - **backend**: mentions services, API, database, models, logging, or references .py/.go files, SQL, ORM
+2. Read `.code-flow/config.yml` → find matching domain's `specs` list
+3. Read each spec file from `.code-flow/specs/` and apply as constraints
+4. If question spans multiple domains, load all matching specs
+5. If no domain matches, skip spec loading
+
+Do NOT ask the user which specs to load — decide automatically based on context.
+
+## Learnings

package/src/adapters/claude/commands/cf-init.md

@@ -0,0 +1,269 @@
+# cf-init
+
+项目规范体系一键初始化。检测技术栈，生成完整的 .code-flow/ 目录、spec 模板、配置文件和 Hook 配置。
+
+## 输入
+
+- `/project:cf-init` — 自动检测技术栈
+- `/project:cf-init frontend` — 强制前端项目
+- `/project:cf-init backend` — 强制后端项目
+- `/project:cf-init fullstack` — 强制全栈项目
+
+## 执行步骤
+
+### 1. 检测技术栈
+
+用 Glob 扫描项目根目录：
+
+- `package.json` 存在 → 前端项目。用 Read 读取，检查 dependencies 中的 react/vue/@angular/core 确定框架。
+- `pyproject.toml` 或 `requirements.txt` 存在 → Python 后端
+- `go.mod` 存在 → Go 后端
+- 同时存在前后端标识 → 全栈项目
+- 均不存在 → Generic（前后端均生成）
+
+如果用户指定了 `frontend|backend|fullstack` 参数，跳过检测直接使用。
+
+### 2. 生成 .code-flow/config.yml
+
+如果文件不存在，用 Write 生成。如果已存在，用 Read 读取后仅补充缺失的顶层 key。
+
+模板内容：
+
+```yaml
+version: 1
+
+budget:
+  total: 2500
+  l0_max: 800
+  l1_max: 1700
+
+inject:
+  auto: true
+  code_extensions:
+    - ".py"
+    - ".go"
+    - ".ts"
+    - ".tsx"
+    - ".js"
+    - ".jsx"
+    - ".java"
+    - ".rs"
+    - ".rb"
+    - ".vue"
+    - ".svelte"
+  skip_extensions:
+    - ".md"
+    - ".txt"
+    - ".json"
+    - ".yml"
+    - ".yaml"
+    - ".toml"
+    - ".lock"
+    - ".csv"
+    - ".xml"
+    - ".svg"
+    - ".png"
+    - ".jpg"
+  skip_paths:
+    - "docs/**"
+    - "*.config.*"
+    - ".code-flow/**"
+    - ".claude/**"
+    - "node_modules/**"
+    - "dist/**"
+    - "build/**"
+    - ".git/**"
+
+path_mapping:
+  frontend:
+    patterns:
+      - "src/components/**"
+      - "src/pages/**"
+      - "src/hooks/**"
+      - "src/styles/**"
+      - "**/*.tsx"
+      - "**/*.jsx"
+      - "**/*.css"
+      - "**/*.scss"
+    specs:
+      - "frontend/directory-structure.md"
+      - "frontend/quality-standards.md"
+      - "frontend/component-specs.md"
+    spec_priority:
+      "frontend/directory-structure.md": 1
+      "frontend/quality-standards.md": 2
+      "frontend/component-specs.md": 3
+  backend:
+    patterns:
+      - "services/**"
+      - "api/**"
+      - "models/**"
+      - "**/*.py"
+      - "**/*.go"
+    specs:
+      - "backend/directory-structure.md"
+      - "backend/logging.md"
+      - "backend/database.md"
+      - "backend/platform-rules.md"
+      - "backend/code-quality-performance.md"
+    spec_priority:
+      "backend/directory-structure.md": 1
+      "backend/database.md": 2
+      "backend/logging.md": 3
+      "backend/code-quality-performance.md": 4
+      "backend/platform-rules.md": 5
+```
+
+根据检测结果，只保留相关的 path_mapping 条目（仅前端项目删除 backend，仅后端项目删除 frontend）。
+
+### 3. 生成 .code-flow/validation.yml
+
+如果文件不存在，用 Write 生成：
+
+```yaml
+validators:
+  - name: "TypeScript 类型检查"
+    trigger: "**/*.{ts,tsx}"
+    command: "npx tsc --noEmit"
+    timeout: 30000
+    on_fail: "检查类型定义，参见 specs/frontend/quality-standards.md"
+
+  - name: "ESLint"
+    trigger: "**/*.{ts,tsx,js,jsx}"
+    command: "npx eslint {files}"
+    timeout: 15000
+    on_fail: "运行 npx eslint --fix 自动修复"
+
+  - name: "Python 类型检查"
+    trigger: "**/*.py"
+    command: "python3 -m mypy {files}"
+    timeout: 30000
+    on_fail: "检查类型注解，参见 specs/backend/code-quality-performance.md"
+
+  - name: "Pytest"
+    trigger: "**/*.py"
+    command: "python3 -m pytest --tb=short -q"
+    timeout: 60000
+    on_fail: "测试失败，检查断言和 mock 是否需要更新"
+```
+
+根据技术栈只保留相关 validators。
+
+### 4. 生成 spec 文件
+
+在 `.code-flow/specs/` 下，按检测到的技术栈生成 spec 模板。每个 spec 遵循统一格式：
+
+```markdown
+# [规范名称]
+
+## Rules
+- 规则1
+
+## Patterns
+- 推荐模式
+
+## Anti-Patterns
+- 禁止模式
+
+## Learnings
+```
+
+前端项目生成：
+- `.code-flow/specs/frontend/directory-structure.md`
+- `.code-flow/specs/frontend/quality-standards.md`
+- `.code-flow/specs/frontend/component-specs.md`
+
+后端项目生成：
+- `.code-flow/specs/backend/directory-structure.md`
+- `.code-flow/specs/backend/logging.md`
+- `.code-flow/specs/backend/database.md`
+- `.code-flow/specs/backend/platform-rules.md`
+- `.code-flow/specs/backend/code-quality-performance.md`
+
+**已存在的 spec 文件不覆盖**。
+
+### 5. 生成 CLAUDE.md
+
+如果 CLAUDE.md 不存在，用 Write 生成 L0 模板：
+
+```markdown
+# Project Guidelines
+
+## Team Identity
+- Team: [team name]
+- Project: [project name]
+- Language: [primary language]
+
+## Core Principles
+- All changes must include tests
+- Single responsibility per function (<= 50 lines)
+- No loose typing or silent exception handling
+- Handle errors explicitly
+
+## Forbidden Patterns
+- Hard-coded secrets or credentials
+- Unparameterized SQL
+- Network calls inside tight loops
+
+## Spec Loading
+This project uses the code-flow layered spec system.
+Specs live in .code-flow/specs/ and are injected on demand.
+
+## Learnings
+```
+
+如果 CLAUDE.md 已存在，用 Read 读取后仅补充缺失的 `##` 段落（不覆盖已有内容）。展示 diff 供用户确认。
+
+### 6. 生成 .claude/settings.local.json Hook 配置
+
+用 Read 检查是否存在。如果不存在，用 Write 生成：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .code-flow/scripts/cf_inject_hook.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .code-flow/scripts/cf_session_hook.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+如果已存在，用 Read 读取 JSON，仅合并 `hooks` 字段中缺失的事件条目，保留其他配置（如 permissions）不变。用 Write 回写。
+
+### 7. 安装 pyyaml
+
+用 Bash 执行：
+
+```bash
+python3 -m pip install pyyaml
+```
+
+成功 → 继续。失败 → 输出 warning（"请手动安装: pip install pyyaml"），不阻塞。
+
+### 8. 输出摘要
+
+输出以下信息：
+- 检测到的技术栈
+- 已生成/跳过的文件列表
+- 各 spec 文件的 token 估算（字符数 / 4）
+- Hook 配置状态确认
+- 提醒用户填充 spec 文件的具体规范内容

package/src/adapters/claude/commands/cf-inject.md

@@ -0,0 +1,41 @@
+# cf-inject
+
+强制重新注入指定领域的编码规范（通常不需要手动调用）。
+
+## 自动注入机制
+
+本项目的规范注入是**全自动**的，通过两层机制保障：
+
+1. **CLAUDE.md 指令**（主要）：Claude 根据用户提问内容自动判断领域，读取 `.code-flow/config.yml` 和对应 spec 文件，作为约束应用
+2. **PreToolUse Hook**（安全网）：编辑代码文件时 Hook 自动触发，注入匹配领域的 specs
+
+正常情况下**无需手动调用**此命令。
+
+## 何时使用
+
+- 需要强制刷新已注入的规范（如 spec 文件刚被修改）
+- 想要预览某个领域的完整规范内容
+- 自动注入未生效时的排查手段
+
+## 输入
+
+- `/project:cf-inject frontend` — 强制加载前端全部 specs
+- `/project:cf-inject backend` — 强制加载后端全部 specs
+
+## 执行步骤
+
+1. 用 Read 读取 `.code-flow/config.yml`，获取指定领域的 `specs` 列表
+2. 用 Read 逐个读取 `.code-flow/specs/` 下的匹配文件
+3. 将规范内容直接输出到对话中，格式：
+
+```
+## Active Specs (manual inject)
+
+### [spec-path]
+[spec 内容]
+
+---
+以上规范是本次开发的约束条件，生成代码必须遵循。
+```
+
+4. 用 Write 更新 `.code-flow/.inject-state`，防止 Hook 重复注入

package/src/adapters/claude/commands/cf-learn.md

@@ -0,0 +1,120 @@
+# cf-learn
+
+自动扫描项目配置文件和代码模式，提取隐含的编码约束和团队规范，呈现给用户确认后写入 CLAUDE.md 或 spec 文件。
+
+## 输入
+
+- `/project:cf-learn` — 全量扫描
+- `/project:cf-learn frontend` — 仅扫描前端相关
+- `/project:cf-learn backend` — 仅扫描后端相关
+
+## 执行步骤
+
+### 1. 扫描项目配置文件
+
+用 Glob 查找以下配置文件（存在则 Read 读取内容）：
+
+**前端配置**：
+- `.eslintrc*` / `eslint.config.*` — 提取 lint 规则（no-any、import 排序、命名规范等）
+- `tsconfig.json` — 提取 strict 模式、path alias、target 等关键配置
+- `.prettierrc*` / `prettier.config.*` — 提取格式化规则（缩进、引号、分号）
+- `tailwind.config.*` — 提取自定义 theme、spacing 规则
+- `next.config.*` / `nuxt.config.*` / `vite.config.*` — 提取框架特定约束
+- `jest.config.*` / `vitest.config.*` — 提取测试配置（覆盖率阈值等）
+
+**后端配置**：
+- `pyproject.toml` — 提取 ruff/mypy/pytest 配置、Python 版本要求
+- `setup.cfg` / `tox.ini` — 提取测试和 lint 配置
+- `.golangci.yml` — 提取 Go lint 规则
+- `Makefile` — 提取构建和测试命令
+- `Dockerfile` / `docker-compose.yml` — 提取运行时约束
+
+**通用配置**：
+- `.github/workflows/*.yml` / `.gitlab-ci.yml` — 提取 CI 检查步骤（哪些 lint/test 是必须通过的）
+- `.editorconfig` — 提取编辑器统一配置
+- `.gitignore` — 推断项目结构（哪些目录被排除）
+- `package.json` 的 scripts 字段 — 提取常用命令
+
+### 2. 扫描代码模式
+
+用 Grep 在项目代码中搜索以下模式，提取隐含规范：
+
+- 错误处理模式：`try/except`、`catch`、自定义 Error 类的使用方式
+- 日志模式：使用的日志库和格式（structlog、winston、pino 等）
+- 测试模式：测试框架、断言风格、mock 方式
+- 导入规范：absolute vs relative imports、barrel exports
+- 命名模式：文件命名（kebab-case / PascalCase）、变量命名风格
+
+### 3. 综合分析并生成候选学习点
+
+将扫描结果综合分析，提取 **具体的、可执行的** 编码约束。每个学习点格式：
+
+```
+[来源] 约束描述
+```
+
+例如：
+```
+[tsconfig.json] strict 模式已启用，禁止 implicit any
+[.eslintrc] import 必须按 builtin → external → internal 排序
+[pyproject.toml] Python 最低版本 3.11，可使用 match/case 语法
+[CI: lint.yml] PR 必须通过 ruff check + mypy --strict
+[代码模式] 错误处理统一使用自定义 AppError 类，不使用裸 Exception
+[Makefile] 测试命令为 make test，覆盖率阈值 80%
+```
+
+**过滤规则**：
+- 跳过已在 CLAUDE.md 或 spec 文件中记录的规范（避免重复）
+- 只提取对 AI 生成代码有实际影响的约束
+- 忽略纯格式化规则（如果有 Prettier/formatter 自动处理）
+
+### 4. 呈现给用户确认
+
+将候选学习点分组展示：
+
+```
+扫描发现以下未记录的编码约束：
+
+全局约束（建议写入 CLAUDE.md）：
+  1. [x] [tsconfig.json] strict 模式已启用，禁止 implicit any
+  2. [x] [CI] PR 必须通过 lint + type check
+  3. [ ] [.editorconfig] 缩进使用 2 空格
+
+前端约束（建议写入 specs/frontend/）：
+  4. [x] [.eslintrc] React hooks 必须遵循 exhaustive-deps 规则
+  5. [x] [代码模式] 组件文件使用 PascalCase 命名
+
+后端约束（建议写入 specs/backend/）：
+  6. [x] [pyproject.toml] 使用 ruff 替代 flake8/isort
+  7. [x] [代码模式] 所有 API handler 使用 async def
+
+确认要写入的条目（输入编号，或 all 全部写入，或 none 跳过）：
+```
+
+等待用户确认。
+
+### 5. 写入确认的条目
+
+根据用户选择：
+
+- **全局约束** → 用 Edit 追加到 `CLAUDE.md` 的 `## Learnings` 段落，格式：`- [YYYY-MM-DD] 内容`
+- **前端约束** → 询问用户写入哪个 spec 文件，用 Edit 追加到对应 spec 的 `## Learnings` 段落
+- **后端约束** → 同上
+
+每条写入后输出确认。
+
+### 6. 输出摘要
+
+```
+已写入 N 条学习点：
+- CLAUDE.md: +3 条
+- specs/frontend/quality-standards.md: +2 条
+- specs/backend/code-quality-performance.md: +2 条
+Token 变化: CLAUDE.md 138 → 195 tokens
+```
+
+## 异常处理
+
+- 无配置文件可扫描 → 提示项目可能未初始化，建议手动添加
+- 未发现新约束 → 输出"未发现未记录的约束，当前规范已覆盖项目配置"
+- `.code-flow/` 不存在 → 提示运行 `/project:cf-init`

package/src/adapters/claude/commands/cf-scan.md

@@ -0,0 +1,56 @@
+# cf-scan
+
+审计规范文件的 token 分布，检测冗余和过时内容，输出优化建议。
+
+## 输入
+
+- `/project:cf-scan` — 完整审计
+- `/project:cf-scan --json` — 仅输出原始 JSON
+- `/project:cf-scan --only-issues` — 仅显示有问题的文件
+- `/project:cf-scan --limit=N` — 限制输出行数
+
+## 执行步骤
+
+### 1. 调用 Python 脚本
+
+用 Bash 执行：
+
+```bash
+python3 .code-flow/scripts/cf_scan.py [--json] [--only-issues] [--limit=N]
+```
+
+将用户传入的参数原样透传。
+
+### 2. 解析输出
+
+解析 stdout 的 JSON 输出，格式如下：
+
+```json
+{
+  "files": [
+    {"path": "CLAUDE.md", "tokens": 650, "percent": "26%", "issues": []},
+    {"path": "specs/frontend/component-specs.md", "tokens": 420, "percent": "17%", "issues": ["冗余: '结构化日志' 3处重复"]}
+  ],
+  "total_tokens": 2150,
+  "budget": 2500,
+  "warnings": []
+}
+```
+
+### 3. 格式化输出
+
+将 JSON 格式化为人类可读的表格：
+
+| 文件 | Tokens | 占比 | 问题 |
+|------|--------|------|------|
+| CLAUDE.md | ~650 | 26% | - |
+| specs/frontend/component-specs.md | ~420 | 17% | - |
+| **合计** | **~2150** | **/ 2500** | |
+
+如有 warnings，在表格下方输出优化建议。
+
+## 异常处理
+
+- `.code-flow/` 不存在 → 提示运行 `/project:cf-init`
+- Python 脚本执行失败 → 输出错误信息，建议检查 Python 环境和 pyyaml 安装
+- spec 文件全为空模板 → 输出 warning，提示先填充规范内容

package/src/adapters/claude/commands/cf-stats.md

@@ -0,0 +1,65 @@
+# cf-stats
+
+统计规范体系的 token 使用情况，包括各文件分布和预算利用率。
+
+## 输入
+
+- `/project:cf-stats` — 完整统计
+- `/project:cf-stats --human` — 人类可读格式
+- `/project:cf-stats --domain=frontend` — 仅统计指定领域
+
+## 执行步骤
+
+### 1. 调用 Python 脚本
+
+用 Bash 执行：
+
+```bash
+python3 .code-flow/scripts/cf_stats.py [--human] [--domain=frontend]
+```
+
+将用户传入的参数原样透传。
+
+### 2. 解析输出
+
+解析 stdout 的 JSON 输出，格式如下：
+
+```json
+{
+  "l0": {"file": "CLAUDE.md", "tokens": 650, "budget": 800},
+  "l1": {
+    "frontend": [
+      {"path": "frontend/directory-structure.md", "tokens": 180},
+      {"path": "frontend/quality-standards.md", "tokens": 150}
+    ],
+    "backend": [
+      {"path": "backend/database.md", "tokens": 200}
+    ]
+  },
+  "total_tokens": 1580,
+  "total_budget": 2500,
+  "utilization": "63%"
+}
+```
+
+### 3. 格式化输出
+
+将 JSON 格式化为人类可读的统计信息：
+
+```
+L0 (CLAUDE.md): ~650 / 800 tokens
+
+L1 Frontend:
+  - directory-structure.md: ~180 tokens
+  - quality-standards.md: ~150 tokens
+
+L1 Backend:
+  - database.md: ~200 tokens
+
+Total: ~1580 / 2500 tokens (63%)
+```
+
+## 异常处理
+
+- `.code-flow/` 不存在 → 提示运行 `/project:cf-init`
+- Python 脚本执行失败 → 输出错误信息，建议检查 Python 环境