project-knowledge 0.1.0

package/scripts/gen-commit-doc.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# gen-commit-doc.sh — Bash 版
+# 用法:
+#   ./gen-commit-doc.sh claude-devsprite
+#   ./gen-commit-doc.sh ALL
+#
+# 与 PowerShell 版行为完全一致：在 kb/projects/<slug>/commits/ 下为每个
+# feat/fix/refactor/perf 类型的 commit 生成一个 feature 文件，
+# 同 feature-slug 的多次提交追加到同一文件。
+
+set -euo pipefail
+
+SLUG="${1:-}"
+if [[ -z "$SLUG" ]]; then
+    echo "usage: $0 <project-slug|ALL>" >&2
+    exit 1
+fi
+
+KB_ROOT="${KB_ROOT:-D:/SanQian.Xu/project-knowledge-base}"
+PROJECTS_JSON="$KB_ROOT/projects.json"
+MAX_COMMITS="${MAX_COMMITS:-0}"
+
+if [[ ! -f "$PROJECTS_JSON" ]]; then
+    echo "找不到 $PROJECTS_JSON" >&2
+    exit 1
+fi
+
+# 用 jq 解析
+slug_to_git() {
+    local slug="$1"
+    jq -r ".${slug}.gitPath" "$PROJECTS_JSON"
+}
+
+# 把 commit subject 转 feature-slug
+to_slug() {
+    local s="$1"
+    # 去 type 前缀
+    s=$(echo "$s" | sed -E 's/^(feat|fix|refactor|perf|docs|chore|test|style|build|ci)(\([^)]+\))?:[[:space:]]*//')
+    # 转 ASCII + kebab
+    s=$(echo "$s" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g' | sed -E 's/-+/-/g' | sed -E 's/^-+|-+$//g')
+    if [[ -z "$s" ]]; then s="untitled"; fi
+    if [[ ${#s} -gt 50 ]]; then s="${s:0:50}"; s="${s%-}"; fi
+    echo "$s"
+}
+
+# 取 commit type
+commit_type() {
+    local s="$1"
+    if [[ "$s" =~ ^(feat|fix|refactor|perf|docs|chore|test|style|build|ci)(\([^)]+\))?:\  ]]; then
+        echo "${BASH_REMATCH[1]}"
+    else
+        echo "other"
+    fi
+}
+
+is_writable() {
+    local t="$1"
+    case "$t" in
+        feat|fix|refactor|perf) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+process_project() {
+    local slug="$1"
+    local git_path
+    git_path=$(slug_to_git "$slug")
+    local commits_dir="$KB_ROOT/projects/$slug/commits"
+    mkdir -p "$commits_dir"
+
+    echo ""
+    echo "=== $slug ==="
+    echo "  git: $git_path"
+
+    local log_args=("log" "--no-merges" "--pretty=format:%h|%ad|%an|%s" "--date=short")
+    if [[ "$MAX_COMMITS" -gt 0 ]]; then
+        log_args+=("-n" "$MAX_COMMITS")
+    fi
+
+    local log_out
+    log_out=$(git -C "$git_path" "${log_args[@]}" 2>&1) || {
+        echo "git log 失败: $log_out" >&2
+        return
+    }
+
+    if [[ -z "$log_out" ]]; then
+        echo "  (无 commit)"
+        return
+    fi
+
+    local new=0 updated=0 skipped=0
+
+    # 已有文件 → slug map
+    declare -A existing
+    while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        local base="${f##*/}"
+        base="${base%.md}"
+        if [[ "$base" =~ _(.+)$ ]]; then
+            existing["${BASH_REMATCH[1]}"]="$f"
+        else
+            existing["$base"]="$f"
+        fi
+    done < <(find "$commits_dir" -maxdepth 1 -name "*.md" ! -name "00-index.md")
+
+    while IFS= read -r line; do
+        [[ -z "$line" ]] && continue
+        [[ "$line" != *"|"* ]] && continue
+
+        IFS='|' read -r hash date author subject <<< "$line"
+        local type
+        type=$(commit_type "$subject")
+        if ! is_writable "$type"; then
+            skipped=$((skipped+1))
+            continue
+        fi
+
+        local slug_key
+        slug_key=$(to_slug "$subject")
+        local short_hash="${hash:0:7}"
+        local filename="${date}_${short_hash}_${slug_key}.md"
+        local filepath="$commits_dir/$filename"
+
+        if [[ -f "$filepath" ]]; then
+            existing["$slug_key"]="$filepath"
+            continue
+        fi
+
+        if [[ -n "${existing[$slug_key]:-}" ]]; then
+            # 追加
+            cat >> "${existing[$slug_key]}" <<EOF
+
+### ${date} \`${short_hash}\`: ${subject}
+
+- **类型**: $type
+- **作者**: $author
+- **变更说明**: 由 gen-commit-doc.sh 自动生成 — $type 类型的提交，触及同一 feature。
+EOF
+            updated=$((updated+1))
+        else
+            # 新建
+            cat > "$filepath" <<EOF
+---
+feature: ${slug_key}
+project: ${slug}
+firstCommit: ${short_hash} (${date}, ${author})
+lastUpdate: ${short_hash} (${date}, ${author})
+status: active
+commitType: ${type}
+relatedModule: null
+generatedAt: $(date -Iseconds)
+---
+
+# ${subject}
+
+> 由 gen-commit-doc.sh 自动生成于 $(date +%Y-%m-%d)。
+
+## 概述
+
+待人工补充：${type} 类型的提交 — ${subject}。
+
+## 初始实现
+
+- **Commit**: \`${short_hash}\` (${date}, ${author}): ${subject}
+- **类型**: ${type}
+- **变更说明**: 由 gen-commit-doc.sh 自动生成。
+- **业务影响**: 待人工补充。
+
+## 后续更新记录（倒序）
+
+## 关联模块
+
+- [框架说明](../framework.md)
+
+## 关联 commit
+
+- \`${short_hash}\` ${subject}
+EOF
+            new=$((new+1))
+            existing["$slug_key"]="$filepath"
+        fi
+    done <<< "$log_out"
+
+    echo "  新建: $new, 追加: $updated, 跳过: $skipped"
+}
+
+# 入口
+if [[ "$SLUG" == "ALL" ]]; then
+    for slug in $(jq -r 'keys[]' "$PROJECTS_JSON"); do
+        process_project "$slug"
+    done
+else
+    process_project "$SLUG"
+fi
+
+echo ""
+echo "完成。"

package/scripts/list-features.ps1

@@ -0,0 +1,41 @@
+# list-features.ps1 — 列出某项目所有 feature 文档
+# 用法: .\list-features.ps1 -ProjectSlug claude-devsprite [-SortBy time|count]
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $ProjectSlug,
+    [ValidateSet("time", "count")]
+    [string] $SortBy = "time",
+    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base"
+)
+
+$commitsDir = Join-Path $KbRoot "projects\$ProjectSlug\commits"
+if (-not (Test-Path $commitsDir)) {
+    Write-Error "找不到 $commitsDir"
+    exit 1
+}
+
+$files = Get-ChildItem -Path $commitsDir -Filter "*.md" |
+    Where-Object { $_.Name -ne "00-index.md" }
+
+if ($SortBy -eq "count") {
+    $files = $files | Sort-Object { $_.Length } -Descending
+} else {
+    $files = $files | Sort-Object Name -Descending
+}
+
+Write-Host "=== $ProjectSlug · 所有 feature 文档（按 $SortBy 排序）===" -ForegroundColor Cyan
+Write-Host ""
+foreach ($f in $files) {
+    $name = $f.BaseName
+    $updateCount = 0
+    if (Select-String -Path $f.FullName -Pattern "^### " -Quiet) {
+        $updateCount = ([regex]::Matches((Get-Content $f.FullName -Raw), "(?m)^### ")).Count
+    }
+    $relPath = "./$($f.Name)"
+    Write-Host ("- [{0}]({1})" -f $name, $relPath) -NoNewline
+    Write-Host "  ($updateCount 次更新)" -ForegroundColor Gray
+}
+Write-Host ""
+Write-Host "共 $($files.Count) 个 feature"

package/scripts/register-scheduled-task.bat

@@ -0,0 +1,5 @@
+@echo off
+schtasks /create /tn KB-GitCommits-Daily /tr "powershell -ExecutionPolicy Bypass -File D:\SanQian.Xu\project-knowledge-base\scripts\gen-commit-doc.ps1 -ProjectSlug ALL" /sc daily /st 08:00 /f
+echo Done.
+schtasks /query /tn KB-GitCommits-Daily
+pause

package/templates/change.md

@@ -0,0 +1,59 @@
+---
+schema: change/v1
+project: __PROJECT__
+commit: __COMMIT__
+shortCommit: __SHORTCOMMIT__
+date: __DATE__
+author: __AUTHOR__
+subject: __SUBJECT__
+type: __TYPE__
+classification: __CLASSIFICATION__  # new-feature | existing-feature-update | bug-fix | refactor | infrastructure | test-only | docs-only
+status: draft
+generatedAt: __DATE__
+---
+
+# Change — __SHORTCOMMIT__
+
+## What Changed
+
+TODO
+
+## Files Changed
+
+- TODO — `path/to/file.ts`
+
+## Affected Features / Modules
+
+- TODO — `feature-slug` (new / updated)
+- TODO — `module-slug`
+
+## Classification
+
+- **Type**: __TYPE__
+- **Bucket**: __CLASSIFICATION__
+- **Confidence**: TODO
+
+## Project-Goal Impact
+
+TODO — which project-goal scenario does this advance, harm, or leave untouched?
+
+## Evidence
+
+- TODO — git diff path or commit hash
+- TODO — quoted source line
+
+## Apply Operations
+
+```yaml
+operations:
+  # - op: create-file
+  #   path: features/__SLUG__.md
+  # - op: update-file
+  #   path: features/__SLUG__.md
+  #   appendSection: Update History
+```
+
+## Reviewer Notes
+
+- TODO — question 1
+- TODO — risk 1

package/templates/commit-feature.md

@@ -0,0 +1,56 @@
+---
+feature: <feature-slug>
+project: <slug>
+firstCommit: <hash> (<date>, <author>)
+lastUpdate: <hash> (<date>, <author>)
+status: active | deprecated | superseded
+commitType: feat | fix | refactor | perf
+relatedModule: [<模块名>](../modules/<module>.md)
+---
+
+# <功能名>
+
+> <一段话：这个功能做什么、解决什么问题>
+
+## 概述
+
+<详细描述：动机、设计决策、用户能感知到的变化>
+
+## 初始实现
+
+- **Commit**：`<hash>` (<date>, <author>): <subject>
+- **涉及文件**：
+  - `path/to/file1`
+  - `path/to/file2`
+- **关键代码**：
+
+```<lang>
+// 10-50 行
+```
+
+- **业务影响**：<一段话，用户能感知到的变化>
+
+## 后续更新记录（倒序）
+
+### <YYYY-MM-DD> `<hash>`: <subject>
+
+- **类型**：fix | refactor | perf
+- **作者**：<author>
+- **涉及文件**：`path/to/file`
+- **变更说明**：<一段话>
+- **业务影响**：<一段话>
+
+### <YYYY-MM-DD> `<hash>`: <subject>
+
+- **类型**：fix
+- **变更说明**：<一段话>
+
+## 关联模块
+
+- [<模块名>](../modules/<module>.md)
+- [框架说明](../framework.md)
+
+## 关联 commit
+
+- `<hash>` <subject>
+- `<hash>` <subject>

package/templates/feature.md

@@ -0,0 +1,44 @@
+---
+schema: feature/v1
+project: __PROJECT__
+featureSlug: __SLUG__
+status: active
+firstCommit: null
+lastUpdate: null
+lastUpdatedAt: __DATE__
+---
+
+# Feature — __SLUG__
+
+> Long-lived knowledge about a single user-visible feature. Created on the first commit that introduces it; updated by later commits.
+
+## What the Feature Does
+
+TODO
+
+## Why It Exists
+
+TODO — which project-goal scenario this feature supports.
+
+## User / System Behavior
+
+TODO
+
+## Source Files and Modules Involved
+
+- TODO — `path/to/file.ts` — role
+- TODO — `path/to/module` — role
+
+## Important Commits
+
+- TODO — `abc1234` — first commit
+- TODO — `def5678` — significant follow-up
+
+## Known Limitations
+
+- TODO
+
+## Tests / Verification Points
+
+- TODO — `tests/foo.test.ts` — verifies X
+- TODO — manual: run Y, expect Z

package/templates/framework.md

@@ -0,0 +1,80 @@
+---
+project: <slug>
+updatedAt: <YYYY-MM-DD>
+---
+
+# <项目名> · 框架说明
+
+## 1. 技术栈
+
+| 维度 | 选型 | 版本 | 选择理由 |
+|------|------|------|---------|
+| 语言 | <...> | <...> | <...> |
+| 框架 | <...> | <...> | <...> |
+| 存储 | <...> | <...> | <...> |
+| 构建 | <...> | <...> | <...> |
+| 测试 | <...> | <...> | <...> |
+| 部署 | <...> | <...> | <...> |
+
+## 2. 顶层目录结构
+
+```
+<project>/
+├── src/                  # 主代码
+├── tests/                # 测试
+├── docs/                 # 项目内文档
+├── config/               # 配置文件
+├── scripts/              # 工具脚本
+├── package.json          # 依赖清单
+├── README.md             # 项目说明
+└── ...
+```
+
+## 3. 启动方式
+
+### 开发模式
+```bash
+<...>
+```
+
+### 构建
+```bash
+<...>
+```
+
+### 测试
+```bash
+<...>
+```
+
+## 4. 环境变量
+
+| 变量名 | 必填 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `<ENV_VAR>` | 是/否 | `<default>` | <...> |
+
+## 5. 关键配置文件
+
+| 文件 | 用途 |
+|------|------|
+| `<path>` | <...> |
+
+## 6. 架构图
+
+```mermaid
+graph TD
+    A[用户] --> B[前端]
+    B --> C[后端]
+    C --> D[存储]
+```
+
+## 7. 核心依赖
+
+- `<package>@<version>` — 用途
+- `<package>@<version>` — 用途
+
+## 8. 变更历史
+
+| 日期 | 变更 | 链接 |
+|------|------|------|
+| <YYYY-MM-DD> | <...> | [commits/...](./commits/...) |

package/templates/index-header.md

@@ -0,0 +1,3 @@
+# __SLUG__ · Feature Changes Index
+
+> This directory tracks all feature deliveries and updates for __SLUG__. Commits that touch the same feature are merged into one file.

package/templates/kb-manifest.json

@@ -0,0 +1,38 @@
+{
+  "schema": "kb-manifest/v1",
+  "project": "__PROJECT__",
+  "kbRoot": "projects/__SLUG__",
+  "generatedAt": "__DATE__",
+  "goal": {
+    "path": "project-goal.md",
+    "status": "not-created",
+    "updatedAt": null
+  },
+  "analysis": {
+    "path": "project-analysis.md",
+    "lastAnalyzedCommit": null,
+    "updatedAt": null
+  },
+  "indexes": {
+    "features": "features/00-index.md",
+    "modules": "modules/00-index.md",
+    "changes": "changes/00-index.md",
+    "sourceMap": "references/source-map.md"
+  },
+  "trustedKnowledge": [
+    "README.md",
+    "framework.md",
+    "architecture/",
+    "modules/",
+    "features/",
+    "references/"
+  ],
+  "draftAreas": [
+    "_ai/drafts/",
+    "_ai/runs/",
+    "_ai/context-packs/"
+  ],
+  "backCompat": {
+    "commits": "commits/ is preserved for compatibility with the legacy commit-doc generator."
+  }
+}

package/templates/module.md

@@ -0,0 +1,58 @@
+---
+title: <模块名>
+category: module
+project: <slug>
+sourcePath: <源码路径，如 src/auth/oauth.ts>
+createdAt: <YYYY-MM-DD>
+updatedAt: <YYYY-MM-DD>
+status: active | deprecated | planned
+relations: [<其他模块的 slug>]
+---
+
+# <模块名>
+
+> <一段话：这个模块做什么、解决什么问题>
+
+## 源码位置
+
+- 主文件：`<sourcePath>`
+- 测试：`<testPath>`
+- 配置文件：`<configPath>`
+
+## 职责
+
+1. <职责 1>
+2. <职责 2>
+3. <职责 3>
+
+## 入口 / 出口
+
+### 入口
+
+- `<exported function/class name>`：<签名与用途>
+- HTTP `<METHOD> <path>`：<用途>
+
+### 出口
+
+- 写入文件：`<path>`
+- HTTP 请求：`<target>`
+- 事件：`<eventName>`
+
+## 依赖
+
+- [<其他模块>](../modules/<other>.md) — 用途
+- 外部包：`<package>`
+
+## 关键代码片段
+
+```<lang>
+// 10-50 行的关键代码
+```
+
+## 最近一次重要变更
+
+- <日期>：<简述> — 详见 [commits/...](../commits/00-index.md)
+
+## 关联 commit / 功能文档
+
+- [功能: <feature-slug>](../commits/<file>.md)

package/templates/project-analysis.md

@@ -0,0 +1,48 @@
+---
+schema: project-analysis/v1
+project: __PROJECT__
+lastAnalyzedCommit: null
+updatedAt: __DATE__
+generatedBy: human-template
+---
+
+# Project Analysis — __PROJECT__
+
+> AI-generated description of the current implementation. This is evidence, not intent. For intent see `project-goal.md`.
+
+## AI-Inferred Project Purpose
+
+TODO — generated by initial analysis.
+
+## Current Implemented Capabilities
+
+- TODO — capability 1
+- TODO — capability 2
+
+## Current Architecture
+
+TODO — entry points, main modules, layering.
+
+## Important Modules
+
+- TODO — module 1: role
+- TODO — module 2: role
+
+## Data / Control Flow
+
+TODO — high-level flow description.
+
+## How Current Implementation Supports the Project Goal
+
+TODO — link each implemented capability to a project-goal scenario.
+
+## Gaps Between Implementation and Project Goal
+
+- TODO — gap 1
+- TODO — gap 2
+
+## Evidence List
+
+| File / Commit | Why it is cited |
+|---------------|-----------------|
+| (none yet)    | (run initial analysis to populate) |

package/templates/project-goal.md

@@ -0,0 +1,55 @@
+---
+schema: project-goal/v1
+project: __PROJECT__
+status: draft
+source: human-reviewed
+updatedAt: __DATE__
+lastReviewedBy: __AUTHOR__
+---
+
+# Project Goal — __PROJECT__
+
+> Highest-priority human-controlled truth. AI may propose edits, but must not overwrite this file automatically.
+
+## One-Sentence Goal
+
+TODO — describe the project in a single sentence.
+
+## Target Users
+
+TODO — who benefits from this project and in what way.
+
+## Core Scenarios
+
+- TODO — scenario 1
+- TODO — scenario 2
+
+## Success Criteria
+
+- TODO — measurable outcome 1
+- TODO — measurable outcome 2
+
+## Non-Goals
+
+- TODO — out of scope 1
+- TODO — out of scope 2
+
+## Priority Principles
+
+When requirements conflict, prefer:
+
+1. TODO — first principle
+2. TODO — second principle
+
+## PR Review Principles
+
+The future PR-review project will use this goal to evaluate incoming changes. List the rules it should enforce:
+
+- TODO — rule 1
+- TODO — rule 2
+
+## Human Revision History
+
+| Date       | Reviewer  | Change                             |
+|------------|-----------|------------------------------------|
+| __DATE__   | __AUTHOR__ | Initial draft (pending acceptance) |