project-knowledge 0.1.0

package/docs/project-goal.md

@@ -0,0 +1,72 @@
+# Project Goal
+
+Status: accepted
+Owner: SanQian.Xu
+Last updated: 2026-06-12
+
+## One-Sentence Goal
+
+将 `project-knowledge-base` 建设成一个以项目目标为最高事实源、由 Git 提交触发、通过 AI 自动分析代码并生成可审核知识库草稿的本地项目监督系统，为后续 PR 自动审查与项目优化工具提供准确、可信、可追溯的知识基础。
+
+## Original Starting Goal
+
+项目一开始的目标是做一个本地 Git 项目知识库管理工具：
+
+- 管理多个本地项目的知识库目录。
+- 从 `projects.json` 读取项目列表。
+- 通过本地 UI 导入或查看项目。
+- 基于 Git 提交记录生成 Markdown 文档。
+- 通过脚本和定时任务持续更新项目提交文档。
+
+这个早期目标偏向“本地知识库目录 + 管理 UI + Git commit 文档生成”。
+
+## Current Product Goal
+
+当前目标已经升级为一个 AI 项目知识库监督系统。它必须能够：
+
+- 导入用户选中的本地项目。
+- 校验项目路径和 Git 仓库状态。
+- 初始化项目知识库目录结构。
+- 记录项目状态，包括仓库状态、HEAD、待分析提交、上次已分析提交、知识库初始化状态和异常点。
+- 配置 AI 模型、API 参数和每个项目的知识库输出语言。
+- 自动扫描 Git 提交，发现尚未进入知识库的变更。
+- 自动构建 context pack，收集 Git diff、相关源码、已有知识库、项目目标、配置文件和测试文件。
+- 使用 AI 对项目做整体分析，生成 `project-goal.md` 和 `project-analysis.md` 草稿。
+- 使用 AI 对增量提交做深度分析，判断变更是新功能、旧功能更新、bug fix、重构、基础设施、测试还是文档变更。
+- 生成功能、模块、变更等知识库草稿。
+- 将 AI 结果先写入 `_ai/drafts/`，由用户审核后再 apply 到正式知识库。
+- 保证正式知识库内容是可审核、可回溯、可测试的，而不是 AI 静默写入的结果。
+- 为未来的 PR 项目提供稳定读取契约，让 PR 项目可以基于项目目标和已接受知识库自动检查代码、优化代码、辅助测试。
+
+## Core Truth Hierarchy
+
+1. `project-goal.md`
+   项目的真实目标，是最高优先级的人类确认事实。AI 可以提出修改建议，但不能自动覆盖它。
+
+2. `project-analysis.md`
+   当前代码实现的分析，是“项目目标如何被实现”的现状说明。它是证据，不是目标本身，可以随着代码变化更新。
+
+3. `features/`, `modules/`, `changes/`
+   记录功能、模块和提交变更。它们必须说明和项目目标的关系，并尽量引用证据。
+
+4. `_ai/drafts/`, `_ai/runs/`, `_ai/context-packs/`
+   AI 工作区。这里的内容默认不是可信知识，只有通过审核和 apply 后才能进入正式知识库。
+
+## Non-Goals
+
+- 不把 AI 输出直接当作可信知识。
+- 不让 AI 静默修改 `project-goal.md`。
+- 不要求用户手动挑选相关文件再交给 AI；上下文收集必须尽量自动化。
+- 不把每个 commit 都简单变成一个孤立文档，而忽略它对功能、模块和项目目标的影响。
+- 不让未来 PR 项目读取 `_ai/drafts/` 作为权威事实。
+
+## Development Guardrails
+
+- 项目目标优先于项目分析。
+- 项目分析是实现现状，不是目标本身。
+- AI 生成内容必须先进入草稿区。
+- apply 必须是显式动作。
+- `lastAnalyzedCommit` 只能在知识库正式应用成功后推进。
+- 任何面向未来 PR 项目的契约都必须稳定、可测试。
+- 没有测试通过的功能不能视为完成。
+

package/docs/project-registry-schema.md

@@ -0,0 +1,46 @@
+# Project Registry Schema
+
+Status: baseline schema for TASK-001
+Date: 2026-06-11
+
+`projects.json` is the registry for projects supervised by the knowledge base.
+
+The current schema version is `v1`. The server normalizes project entries on read and write so older entries can coexist with newer fields.
+
+## Required Identity Fields
+
+```json
+{
+  "displayName": "Example Project",
+  "localPath": "D:\\SanQian.Xu\\Example",
+  "gitPath": "D:\\SanQian.Xu\\Example",
+  "kbPath": "D:\\SanQian.Xu\\project-knowledge-base\\projects\\example"
+}
+```
+
+## Baseline Fields Added In TASK-001
+
+| Field | Default | Purpose |
+|------|---------|---------|
+| `enabled` | `true` | Whether the project is included in future scan/analyze workflows. |
+| `repoStatus` | `"unknown"` | Placeholder for Git validation state. TASK-002 will set concrete values. |
+| `headCommit` | `null` | Latest known repository head commit. |
+| `lastSeenCommit` | `null` | Latest commit observed by a scan. |
+| `lastAnalyzedCommit` | `null` | Latest commit whose knowledge updates were applied. |
+| `aiProfileId` | `"default-agent"` | Analyzer profile selected for this project. |
+| `kbSchemaVersion` | `"v1"` | Knowledge-base layout/schema generation used by the project. |
+| `goalStatus` | `"not-created"` | State of `project-goal.md` for future workflows. |
+
+## Normalization Rules
+
+- Missing `gitPath` defaults to `localPath`.
+- Missing `kbPath` defaults to `<KB_ROOT>\\projects\\<slug>`.
+- Legacy `D:\\SanQian.Xu\\kb\\projects\\<slug>` paths are replaced with the current `project-knowledge-base` root.
+- Missing `tags` becomes an empty array.
+- String `tags` are split on commas.
+- Existing unknown fields are preserved.
+
+## Compatibility
+
+`kbInitialized`, `commitCount`, and `moduleCount` are runtime status fields returned by the site. Older project entries may still contain them; TASK-001 does not remove them to avoid unnecessary data churn.
+

package/docs/testing-strategy.md

@@ -0,0 +1,169 @@
+# Testing Strategy for AI Knowledge Base Development
+
+Status: draft
+Date: 2026-06-11
+
+## 1. Testing Rule
+
+No development task is complete until its tests pass.
+
+If tests fail, the task returns to implementation. The developer must fix the feature or update an incorrect test with a clear reason, then run the test plan again.
+
+## 2. Test Levels
+
+### 2.1 Static and Syntax Tests
+
+Purpose: catch broken files before runtime.
+
+Required checks:
+
+- JSON files parse successfully.
+- Node server scripts pass syntax checks.
+- PowerShell scripts parse and support `-WhatIf` or dry-run where possible.
+- Markdown files that define machine contracts contain required headings and frontmatter.
+
+Example commands:
+
+```powershell
+node --check _site\server.js
+powershell -NoProfile -Command "$null = Get-Content projects.json -Raw | ConvertFrom-Json"
+```
+
+### 2.2 API Integration Tests
+
+Purpose: prove the local API performs real file and Git operations safely.
+
+Required coverage:
+
+- `GET /api/state`
+- project upsert
+- Git validation success
+- Git validation failure: missing path
+- Git validation failure: path exists but is not a Git repo
+- Git validation edge case: repo exists but has no commits
+- analysis job creation
+- draft listing
+- draft apply
+- failure reporting
+
+### 2.3 Git Fixture Tests
+
+Purpose: make Git-driven behavior deterministic.
+
+The test harness should create temporary repositories with:
+
+- no commits
+- one initial commit
+- multiple commits
+- feature commit touching one module
+- refactor commit touching multiple modules
+- commit that changes tests only
+- commit with binary or large files
+
+The analyzer should never require real user repositories for automated tests.
+
+### 2.4 AI Adapter Tests
+
+Purpose: test orchestration without relying on live AI calls.
+
+Required adapters:
+
+- `mock-agent`: deterministic output for tests
+- `recorded-agent`: replay saved responses
+- `real-agent`: manual or nightly verification only
+
+Automated CI-style tests must use `mock-agent` or `recorded-agent`.
+
+### 2.5 Knowledge Write Snapshot Tests
+
+Purpose: ensure generated knowledge files are stable and safe.
+
+For a known Git fixture and mock AI response, assert:
+
+- `project-goal.md` is created as draft first.
+- `project-analysis.md` includes evidence.
+- `features/<feature>.md` is created or updated correctly.
+- `changes/<commit>.md` exists.
+- `kb-manifest.json` points to valid files.
+- accepted knowledge is not overwritten without an apply step.
+
+### 2.6 UI End-to-End Tests
+
+Purpose: prove the user can complete workflows from the browser.
+
+Required Playwright flows:
+
+- import valid Git project
+- reject invalid Git project
+- show repository status
+- configure AI profile
+- run initial analysis with mock agent
+- view generated drafts
+- edit project goal
+- apply draft
+- run incremental commit analysis
+- inspect failed analysis run
+
+### 2.7 Regression Tests for Existing Site
+
+The current site behavior must remain working:
+
+- projects render
+- add project form works
+- schedule controls work
+- manual run starts a job
+- log output renders
+- tree view renders
+
+## 3. Task Completion Gate
+
+Every task file must list:
+
+- automated tests to add
+- manual checks to run
+- fixtures required
+- failure behavior
+- definition of done
+
+Completion requires:
+
+1. All task-specific tests pass.
+2. Existing regression tests pass.
+3. The developer records the executed tests in the task file or test report.
+4. Known failures are either fixed or explicitly moved into a follow-up task.
+
+## 4. Failure Loop
+
+```mermaid
+flowchart TD
+    A["Implement task"] --> B["Run required tests"]
+    B --> C{"All tests pass?"}
+    C -->|No| D["Fix implementation or justified test issue"]
+    D --> B
+    C -->|Yes| E["Mark task complete"]
+```
+
+## 5. Recommended Test File Layout
+
+```text
+_site/_test/
+├─ ui-test.js
+├─ api-test.js
+├─ fixtures/
+│  ├─ make-git-repos.js
+│  └─ mock-agent-responses/
+├─ snapshots/
+└─ TEST-REPORT.md
+```
+
+Future non-UI scripts can use:
+
+```text
+tests/
+├─ git-inspector.test.js
+├─ context-pack-builder.test.js
+├─ draft-writer.test.js
+├─ manifest.test.js
+└─ fixtures/
+```
+

package/iterations.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "里程碑定义，供 gen-commit-doc.ps1 按里程碑聚合使用。since/until 格式 YYYY-MM-DD，null 表示开放。",
+  "claude-devsprite": [
+    { "id": "v1.0-skill-core",          "since": "2024-01-01", "until": "2025-04-30", "title": "Skill 核心能力" },
+    { "id": "v2.0-knowledge-graph",     "since": "2025-05-01", "until": "2026-04-30", "title": "知识图谱化" },
+    { "id": "v2.1-dashboard",           "since": "2026-05-01", "until": null,        "title": "Web Dashboard 与多 Agent" }
+  ],
+  "web-remote-control": [
+    { "id": "v0.1-webrtc-poc",          "since": "2026-04-01", "until": "2026-05-15", "title": "WebRTC PoC" },
+    { "id": "v0.2-rrweb-and-deploy",    "since": "2026-05-16", "until": null,        "title": "rrweb 集成与部署" }
+  ],
+  "token-consumption-leaderboard": [
+    { "id": "v1.0-local-dashboard",     "since": "2024-01-01", "until": "2024-04-30", "title": "本地 Dashboard" },
+    { "id": "v2.0-leaderboard",         "since": "2024-05-01", "until": null,        "title": "排行榜与认证" }
+  ],
+  "quant-platform": [
+    { "id": "v1.0-base",                "since": null,        "until": "2026-03-12", "title": "基础框架" },
+    { "id": "v3.0-multi-market",        "since": "2026-03-13", "until": "2026-03-14", "title": "多市场 + 真实数据源" }
+  ],
+  "claude-code-ui": [
+    { "id": "v1.32.0",                  "since": "2026-01-01", "until": "2026-05-19", "title": "上游 v1.32.0 引用" }
+  ]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "project-knowledge",
+  "version": "0.1.0",
+  "description": "Knowledge base manager with Git integration, AI-driven analysis, and bilingual (zh-CN/en-US) knowledge output",
+  "main": "_site/server.js",
+  "scripts": {
+    "start": "node _site/server.js",
+    "test": "node _site/_test/run-all-tests.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "_site/server.js",
+    "_site/index.html",
+    "_site/lib/",
+    "_site/scripts/",
+    "_site/_test/*.js",
+    "_site/_test/fixtures/",
+    "_site/start.bat",
+    "_site/stop.bat",
+    "templates/",
+    "scripts/",
+    "ai-profiles.json",
+    "iterations.json",
+    "docs/",
+    "README.md",
+    "INDEX.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SanQianX/project-knowledge-base.git"
+  },
+  "keywords": [
+    "knowledge-base",
+    "git",
+    "ai",
+    "claude",
+    "documentation",
+    "scanner",
+    "context-pack",
+    "post-commit-hook"
+  ],
+  "author": "SanQianX",
+  "license": "UNLICENSED"
+}

package/scripts/gen-commit-doc.ps1

@@ -0,0 +1,178 @@
+# gen-commit-doc.ps1
+# All Chinese strings are loaded from template files to avoid PowerShell
+# parser issues with multi-byte UTF-8 characters in script source.
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $ProjectSlug,
+    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base",
+    [int] $MaxCommits = 0
+)
+
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+$OutputEncoding = [System.Text.Encoding]::UTF8
+$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'
+$PSDefaultParameterValues['Set-Content:Encoding'] = 'utf8'
+$PSDefaultParameterValues['Add-Content:Encoding'] = 'utf8'
+
+$projectsJsonPath = Join-Path $KbRoot "projects.json"
+if (-not (Test-Path $projectsJsonPath)) {
+    throw "Cannot find projects.json: $projectsJsonPath"
+}
+$projects = Get-Content $projectsJsonPath -Raw -Encoding UTF8 | ConvertFrom-Json
+
+$templatePath = Join-Path $KbRoot "templates\commit-feature.md"
+$updateEntryPath = Join-Path $KbRoot "templates\update-entry.md"
+$indexHeaderPath = Join-Path $KbRoot "templates\index-header.md"
+if (-not (Test-Path $templatePath)) { throw "Cannot find template: $templatePath" }
+if (-not (Test-Path $updateEntryPath)) { throw "Cannot find template: $updateEntryPath" }
+if (-not (Test-Path $indexHeaderPath)) { throw "Cannot find template: $indexHeaderPath" }
+
+$FEATURE_TEMPLATE = Get-Content $templatePath -Raw -Encoding UTF8
+$UPDATE_ENTRY_TEMPLATE = Get-Content $updateEntryPath -Raw -Encoding UTF8
+$INDEX_HEADER_TEMPLATE = Get-Content $indexHeaderPath -Raw -Encoding UTF8
+
+$slugs = @()
+if ($ProjectSlug -eq "ALL") {
+    $slugs = @($projects.PSObject.Properties.Name)
+} else {
+    if (-not $projects.$ProjectSlug) {
+        throw "Slug $ProjectSlug not in projects.json"
+    }
+    $slugs = @($ProjectSlug)
+}
+
+function Get-FeatureSlug([string]$Subject) {
+    $s = $Subject -replace '^(feat|fix|refactor|perf|docs|chore|test|style|build|ci)(\([^)]+\))?:\s*', ''
+    # Try ASCII slug first
+    $slug = $s.ToLower() -replace '[^a-z0-9]+', '-' -replace '-+', '-' -replace '^-|-$', ''
+    if ([string]::IsNullOrWhiteSpace($slug)) {
+        # Non-ASCII subject (e.g. Chinese): use a sanitized slice of the original
+        $slug = $s.Substring(0, [Math]::Min(20, $s.Length)) -replace '[\s\\/:*?"<>|]+', '-' -replace '-+', '-' -replace '^-|-$', ''
+    }
+    if ([string]::IsNullOrWhiteSpace($slug)) { $slug = "untitled" }
+    if ($slug.Length -gt 50) { $slug = $slug.Substring(0, 50).TrimEnd('-') }
+    return $slug
+}
+
+function Get-CommitType([string]$Subject) {
+    if ($Subject -match '^(feat|fix|refactor|perf|docs|chore|test|style|build|ci)(\([^)]+\))?:\s*') {
+        return $Matches[1]
+    }
+    # No conventional prefix: treat as feat (the most common case for older projects)
+    return "feat"
+}
+
+function Test-CommitWriteable([string]$Type) {
+    return (@('feat','fix','refactor','perf') -contains $Type)
+}
+
+function New-FeatureDocFromTemplate([string]$Project, [string]$FeatureSlug, [string]$Hash, [string]$Date, [string]$Author, [string]$Subject, [string]$Type) {
+    $today = Get-Date -Format "yyyy-MM-dd"
+    $subjectLine = "# ${Subject}"
+    $headerLine = "---`nfeature: ${FeatureSlug}`nproject: ${Project}`nfirstCommit: ${Hash} (${Date}, ${Author})`nlastUpdate: ${Hash} (${Date}, ${Author})`nstatus: active`ncommitType: ${Type}`nrelatedModule: null`ngeneratedAt: ${today}`n---"
+    $noteLine = "> Auto-generated by gen-commit-doc.ps1 on $today."
+    $initialLine = "## Initial Implementation`n`n- **Commit**: ${Hash} (${Date}, ${Author}): ${Subject}`n- **Type**: ${Type}`n- **Business Impact**: TODO"
+    $relatedLine = "## Related Commits`n`n- ${Hash}: ${Subject}"
+    $linkedModules = "## Related Modules`n`n- [Framework](../framework.md)"
+    $body = "$headerLine`n`n$subjectLine`n`n$noteLine`n`n## Overview`n`nTODO - human to fill in the description.`n`n$initialLine`n`n## Update History (reverse chronological)`n`n$relatedLine`n`n$linkedModules"
+    return $body
+}
+
+function New-UpdateEntry([string]$Date, [string]$Hash, [string]$Subject, [string]$Type, [string]$Author) {
+    $body = $UPDATE_ENTRY_TEMPLATE
+    $body = $body.Replace('__DATE__', $Date)
+    $body = $body.Replace('__HASH__', $Hash)
+    $body = $body.Replace('__SUBJECT__', $Subject)
+    $body = $body.Replace('__TYPE__', $Type)
+    $body = $body.Replace('__AUTHOR__', $Author)
+    return $body
+}
+
+function Rebuild-Index([string]$Slug, [string]$CommitsDir) {
+    $files = Get-ChildItem -Path $CommitsDir -Filter "*.md" |
+        Where-Object { $_.Name -ne "00-index.md" } |
+        Sort-Object Name -Descending
+    $header = $INDEX_HEADER_TEMPLATE.Replace('__SLUG__', $Slug)
+    $sb = New-Object System.Text.StringBuilder
+    [void]$sb.AppendLine($header)
+    [void]$sb.AppendLine("| File | Size | Modified |")
+    [void]$sb.AppendLine("|------|------|----------|")
+    foreach ($f in $files) {
+        $size = $f.Length
+        $mtime = $f.LastWriteTime.ToString("yyyy-MM-dd HH:mm")
+        [void]$sb.AppendLine("| [$($f.Name)](./$($f.Name)) | $size | $mtime |")
+    }
+    [void]$sb.AppendLine("")
+    [void]$sb.AppendLine("---")
+    [void]$sb.AppendLine("")
+    [void]$sb.AppendLine("## Auto Update")
+    [void]$sb.AppendLine("")
+    [void]$sb.AppendLine("Run daily at 08:00: ``project-knowledge-base\scripts\gen-commit-doc.ps1 -ProjectSlug $Slug``")
+    [void]$sb.AppendLine("")
+    $indexPath = Join-Path $CommitsDir "00-index.md"
+    Set-Content -Path $indexPath -Value $sb.ToString() -Encoding UTF8
+}
+
+function Process-Project([string]$Slug, [object]$Project) {
+    $gitPath = $Project.gitPath
+    $commitsDir = Join-Path $KbRoot "projects\$Slug\commits"
+    if (-not (Test-Path $commitsDir)) {
+        New-Item -ItemType Directory -Force -Path $commitsDir | Out-Null
+    }
+
+    Write-Host ""
+    Write-Host "=== $Slug ==="
+    Write-Host "  git: $gitPath"
+
+    $logArgs = @("log", "--no-merges", "--pretty=format:%h|%ad|%an|%s%n", "--date=short")
+    if ($MaxCommits -gt 0) { $logArgs += @("-n", "$MaxCommits") }
+    $rawOutput = & git -C $gitPath @logArgs 2>&1
+    if ($LASTEXITCODE -ne 0) { Write-Warning "git log failed: $rawOutput"; return }
+    if ($rawOutput -is [array]) { $rawLog = ($rawOutput -join "`n") } else { $rawLog = [string]$rawOutput }
+    if ([string]::IsNullOrWhiteSpace($rawLog)) { Write-Host "  (no commits)"; return }
+
+    $commits = @($rawLog -split "`n" | Where-Object { $_ -match '\|' })
+    $newCount = 0; $updatedCount = 0; $skippedCount = 0
+
+    $existingMap = @{}
+    Get-ChildItem -Path $commitsDir -Filter "*.md" | ForEach-Object {
+        $name = $_.BaseName
+        if ($name -match '_(.+)$') { $slugKey = $Matches[1] } else { $slugKey = $name }
+        $existingMap[$slugKey] = $_.FullName
+    }
+
+    foreach ($line in $commits) {
+        $parts = $line -split '\|', 4
+        if ($parts.Count -lt 4) { continue }
+        $hash, $date, $author, $subject = $parts
+        $type = Get-CommitType $subject
+        if (-not (Test-CommitWriteable $type)) { $skippedCount++; continue }
+        $slug = Get-FeatureSlug $subject
+        $shortHash = $hash.Substring(0, [Math]::Min(7, $hash.Length))
+        $filename = "${date}_${shortHash}_${slug}.md"
+        $filepath = Join-Path $commitsDir $filename
+
+        if (Test-Path $filepath) { $existingMap[$slug] = $filepath; continue }
+        if ($existingMap.ContainsKey($slug)) {
+            $entry = New-UpdateEntry $date $shortHash $subject $type $author
+            Add-Content -Path $existingMap[$slug] -Value $entry -Encoding UTF8
+            $updatedCount++
+        } else {
+            $body = New-FeatureDocFromTemplate $Slug $slug $shortHash $date $author $subject $type
+            Set-Content -Path $filepath -Value $body -Encoding UTF8
+            $newCount++
+            $existingMap[$slug] = $filepath
+        }
+    }
+
+    Write-Host "  new: $newCount, updated: $updatedCount, skipped: $skippedCount"
+    Rebuild-Index $Slug $commitsDir
+}
+
+foreach ($slug in $slugs) {
+    Process-Project $slug $projects.$slug
+}
+Write-Host ""
+Write-Host "Done."