project-knowledge 0.1.0 → 1.0.1

package/docs/development-progress.md

@@ -0,0 +1,141 @@
+# 开发进度总结
+
+> 截至 2026-06-12，commit `db32274`，tag `v0.1.0`。
+
+## 一句话定位
+
+`project-knowledge-base` 是 `D:\SanQian.Xu` 下多个项目的自动化知识库管理工具：
+扫描 git 仓库 → 调用 LLM 生成结构化知识草稿 → 人工审核后落地为受信任知识。
+双语（zh-CN / en-US）输出，可作为 PR 评审的外部 consumer。
+
+## 远程与发布
+
+- 仓库：`https://github.com/SanQianX/project-knowledge-base.git`
+- 主分支：`main`，最新 commit：`db32274`
+- 首发 tag：`v0.1.0`（已推上 origin）
+- npm 包：`project-knowledge@0.1.0`（由 tag push 触发 GitHub Actions 自动发布）
+  - Workflow：`.github/workflows/publish.yml`，监听 `v*` tag
+  - Secret：`secrets.NPM_TOKEN`（用户已在 Repository secrets 配置）
+  - Tarball：109.2 kB / 81 个文件（unpacked 425 kB）
+
+## 11 个任务分组的状态
+
+| 任务 | 主题 | 状态 |
+|------|------|------|
+| TASK-001～003 | 项目骨架 / 项目注册表 / 模板系统 | ✅ |
+| TASK-004 | Git scanner（commit 枚举、repo 状态校验） | ✅ |
+| TASK-005 | AI profile adapter（mock + 真实 LLM 双实现） | ✅ |
+| TASK-006 | Context pack builder（按 commit 汇总上下文） | ✅ |
+| TASK-007 | 初始项目分析（建仓后第一轮 goal + analysis） | ✅ |
+| TASK-008 | 增量 commit 分析（lastAnalyzedCommit..HEAD） | ✅ |
+| TASK-009 | 草稿审核 / apply（人类确认后才写入 trusted KB） | ✅ |
+| TASK-010 | 调度器 / 回归门禁 | ✅ |
+| TASK-011 | PR consumer contract（KB 校验 + pr-context API） | ✅ |
+
+合计 125 个子任务，全部完成。
+
+## 代码地图
+
+### 后端（`_site/`）
+
+| 文件 | 职责 |
+|------|------|
+| `server.js` | HTTP API + 静态文件服务，端口 7777 |
+| `lib/scanner.js` | 读取 git 状态、枚举 commit、校验仓库 |
+| `lib/context-pack-builder.js` | 构造 LLM 用的上下文包（top N entries） |
+| `lib/ai-adapter.js` | 适配器接口 + `mock-agent` + `claude-code-agent` |
+| `lib/llm-client.js` | Anthropic Messages API 客户端（零依赖、支持任意 baseUrl） |
+| `lib/analysis-orchestrator.js` | 调度初始分析 / commit 分析 / 草稿生成 |
+| `lib/draft-apply.js` | 草稿 → 正式 KB 文件的写入 |
+| `lib/job-orchestrator.js` | 后台 job 队列、并发控制、超时 |
+| `lib/hook-manager.js` | git hook 安装/卸载/读取（含 KB 标记） |
+| `lib/kb-validator.js` | KB 完整性校验（健康/缺 goal/草稿泄漏 三种 fixture） |
+| `lib/git-runner.js` | git 命令封装 |
+| `scripts/hook-trigger.js` | post-commit 钩子脚本（2s 超时，静默失败） |
+| `scripts/safe-runner.js` | KB 写入的安全网（不直接由 orchestrator 写） |
+
+### 前端
+
+- `index.html`：Vue 3 单文件，**Control Center / 控制中心** UI
+- Tab：Dashboard / Import / AI Profiles / Runs · Drafts / Schedule / Logs
+- 中英双语
+- 浅色主题（sidebar 非纯白）
+
+## AI 集成
+
+- **mock-agent**：确定性输出，用于回归测试和离线开发
+- **claude-code-agent**：真实 LLM，Anthropic Messages API 兼容（实测 MiniMax-M3 走 `api.minimaxi.com/anthropic` 跑通）
+- 配置靠 env vars：`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`
+- 选哪个 profile 在 `ai-profiles.json`（默认 `mock-agent`），项目侧在 `projects.json` 的 `aiProfileId` 覆盖
+- 严格 JSON 输出，要求 LLM 复制**完整 40 字符 commit hash**（曾因 LLM 返回 short hash 导致 drafts 落空，已修复）
+- 双语输出：每个项目在 `projects.json` 设 `knowledgeLanguage: "zh-CN" | "en-US"`，prompt 强制同语言
+
+## Post-commit hook
+
+- 每个项目独立安装（在项目的 `Install hook` 按钮触发）
+- 安装位置：`<gitDir>/hooks/post-commit`
+- 行为：commit 完成后异步 POST `/api/jobs/run`（safe-mode 扫描）
+- 2 秒超时；不阻塞 commit
+- 失败：写 `<kbRoot>/.hook-trigger-errors.log`，不弹错
+- 不会泄露到远端：hook 装在本地 `.git/hooks/`，不在仓库里
+
+## 测试覆盖
+
+15 个 `*test.js`，由 `node _site/_test/run-all-tests.js` 一键跑：
+
+```
+ai-profile-test.js          baseline-schema-test.js
+commit-analysis-test.js     context-pack-test.js
+draft-apply-test.js         git-validation-test.js
+hook-trigger-test.js        initial-analysis-test.js
+job-orchestrator-test.js    kb-v2-templates-test.js
+pr-consumer-contract-test.js scanner-test.js
+```
+
+加 `ui-smoke-test.js`（headless Chrome via CDP，端到端验证 Control Center 渲染 + 5 个 tab 切换 + 无 console 错误 + 提交 hash 渲染）。需 `node ui-smoke-test.js` 显式触发或 `--include-ui` 包含进回归套件。
+
+测试 fixture 包含三个 KB 状态：健康 / 缺 goal / 草稿泄漏，专门验证 `kb-validator` 不放行半成品进 PR context。
+
+## PR Consumer Contract（TASK-011 引入）
+
+外部 PR 评审系统通过两个端点消费 KB：
+
+- `POST /api/projects/:slug/validate-kb` — 校验 KB 是否可信（无草稿泄漏、goal 完整）
+- `GET  /api/projects/:slug/pr-context` — 拉取结构化 PR 上下文（已合入 trusted KB 的内容）
+
+契约文档：`docs/pr-consumer-contract.md`。
+关键不变量：**草稿（drafts）绝不能出现在 pr-context 里**——这是 12 个测试用例专门守的门。
+
+## 当前未提交的开发态
+
+- `projects.json` 有未提交的修改（只是 LLM 扫描多发现一个 commit 后的 `headCommit` / `lastSeenCommit` / `lastScanAt` 字段更新）
+- `projects/token-consumption-leaderboard/_ai/` 下有未跟踪的分析产物（context-packs、runs）
+
+是否清理取决于团队约定；如果要长期忽略，建议把 `_ai/` 模式加进 `.gitignore`。
+
+## 已知待办
+
+1. publish workflow 当前不带测试门禁。`ui-smoke-test.js` 用了 Windows 硬编码 Chrome 路径（`C:\Users\SanQian\AppData\Local\ms-playwright\...`），在 ubuntu runner 上会挂；如果要 `tag → test → publish`，得加 Linux 兼容的 headless 浏览器或加 `--include-ui` 排除
+2. `package.json` 没有 `bin` 入口；如果希望 `npx project-knowledge start` 直接启动服务，需要给 `server.js` 加 shebang 并在 `bin` 注册一个 CLI 名
+3. KB 模板（TASK-006 / TASK-007 引入的 `kb-manifest/v1`）和 v1 旧模板的迁移路径没有自动工具，老项目要手动重跑 `initial` 扫描
+4. 没有针对 LLM 调用做重试 / 限流；网络抖动会让一次 commit-batch 整个失败
+
+## 怎么继续
+
+```bash
+# 本地开发
+cd _site
+node server.js                    # 端口 7777
+
+# 跑回归
+node _site/_test/run-all-tests.js
+
+# 装到本地项目（UI 上点 Install hook 也行）
+node _site/scripts/safe-runner.js install-hook --project=<slug>
+
+# 发新版
+# 1. 改 package.json 的 version
+# 2. git add && git commit
+# 3. git tag v0.1.x && git push origin v0.1.x
+# → GitHub Actions 自动 publish
+```

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "project-knowledge",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "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"
   },
+  "bin": {
+    "project-knowledge": "bin/project-knowledge.js"
+  },
   "engines": {
     "node": ">=18"
   },
@@ -15,10 +18,12 @@
     "_site/index.html",
     "_site/lib/",
     "_site/scripts/",
+    "_site/vendor/",
     "_site/_test/*.js",
     "_site/_test/fixtures/",
     "_site/start.bat",
     "_site/stop.bat",
+    "bin/",
     "templates/",
     "scripts/",
     "ai-profiles.json",
@@ -43,5 +48,9 @@
     "post-commit-hook"
   ],
   "author": "SanQianX",
-  "license": "UNLICENSED"
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "ws": "^8.21.0"
+  }
 }

package/scripts/gen-commit-doc.ps1

@@ -5,7 +5,7 @@
 param(
     [Parameter(Mandatory = $true)]
     [string] $ProjectSlug,
-    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base",
+    [string] $KbRoot = (Split-Path -Parent $PSScriptRoot),
     [int] $MaxCommits = 0
 )
 

package/scripts/list-features.ps1

@@ -7,7 +7,7 @@ param(
     [string] $ProjectSlug,
     [ValidateSet("time", "count")]
     [string] $SortBy = "time",
-    [string] $KbRoot = "D:\SanQian.Xu\project-knowledge-base"
+    [string] $KbRoot = (Split-Path -Parent $PSScriptRoot)
 )
 
 $commitsDir = Join-Path $KbRoot "projects\$ProjectSlug\commits"

package/scripts/register-scheduled-task.bat

@@ -1,5 +1,7 @@
 @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 off
+set "KB_ROOT=%~dp0.."
+schtasks /create /tn KB-GitCommits-Daily /tr "powershell -ExecutionPolicy Bypass -File \"%KB_ROOT%\scripts\gen-commit-doc.ps1\" -ProjectSlug ALL" /sc daily /st 08:00 /f
 echo Done.
 schtasks /query /tn KB-GitCommits-Daily
 pause