@kernel-sig/console 0.1.0

package/.env.example

@@ -0,0 +1,50 @@
+# ============================================================
+# Kernel SIG Console 配置
+# 复制为 .env 后按需修改：cp .env.example .env
+# ============================================================
+
+# ---- 必填 ----
+# 凭据加密（AES-256-GCM）与 JWT 签名密钥，至少 32 字符。
+# 生成：openssl rand -hex 32
+# 注意：此密钥一旦更换，已加密存储的 AtomGit token / LLM API Key 将无法解密。
+KSC_SECRET_KEY=please-change-me-to-a-random-32-plus-char-string
+
+# ---- 镜像源 ----
+# 部分网络环境直连 Docker Hub 与 pypi.org 极慢或不可达，默认走国内镜像源。
+# 如在其他网络环境，改回 docker.io / https://pypi.org/simple 即可。
+DOCKER_REGISTRY=docker.m.daocloud.io
+PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+NPM_REGISTRY=https://registry.npmjs.org
+
+# ---- 端口 ----
+# 默认避开本机常见的 80/443/3000/8000/6379，避免与既有服务冲突
+KSC_WEB_PORT=18080
+KSC_API_PORT=18000
+KSC_POSTGRES_PORT=15432
+KSC_VALKEY_PORT=16379
+
+# ---- 数据库 ----
+KSC_DB_NAME=kernel_sig
+KSC_DB_USER=kernel_sig
+KSC_DB_PASSWORD=kernel_sig
+
+# ---- 运行环境 ----
+KSC_ENVIRONMENT=production
+KSC_LOG_LEVEL=INFO
+# 通过 HTTPS 访问时设为 true（要求 Secure Cookie）
+KSC_COOKIE_SECURE=false
+
+# ---- 首次启动引导管理员（可选）----
+# 设置后，首次启动会自动创建管理员，无需打开浏览器初始化。
+# 创建完成后建议清空此变量并重启。
+KSC_BOOTSTRAP_ADMIN_USERNAME=admin
+KSC_BOOTSTRAP_ADMIN_PASSWORD=
+KSC_BOOTSTRAP_ADMIN_EMAIL=admin@localhost
+
+# ---- 首次启动纳管默认仓库（可选）----
+# 首次启动时自动纳管 `owner/name`，省得进界面手动添加。留空则跳过。
+# 没配下面那个 token 也照样纳管，只是同步不跑（界面上会标明未配置凭据）。
+KSC_BOOTSTRAP_REPOSITORY=openeuler/kernel
+# AtomGit token，首次启动时导入并加密存库。不填也可以，之后在
+# 「设置 → 凭据」里加。填了就会开始拉数据。
+KSC_ATOMGIT_TOKEN=

package/LICENSE

@@ -0,0 +1,127 @@
+                     木兰宽松许可证, 第2版
+
+   木兰宽松许可证， 第2版 
+   2020年1月 http://license.coscl.org.cn/MulanPSL2
+
+
+   您对“软件”的复制、使用、修改及分发受木兰宽松许可证，第2版（“本许可证”）的如下条款的约束：
+
+   0. 定义
+
+      “软件”是指由“贡献”构成的许可在“本许可证”下的程序和相关文档的集合。
+
+      “贡献”是指由任一“贡献者”许可在“本许可证”下的受版权法保护的作品。
+
+      “贡献者”是指将受版权法保护的作品许可在“本许可证”下的自然人或“法人实体”。
+
+      “法人实体”是指提交贡献的机构及其“关联实体”。
+
+      “关联实体”是指，对“本许可证”下的行为方而言，控制、受控制或与其共同受控制的机构，此处的控制是指有受控方或共同受控方至少50%直接或间接的投票权、资金或其他有价证券。
+
+   1. 授予版权许可
+
+      每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的版权许可，您可以复制、使用、修改、分发其“贡献”，不论修改与否。
+
+   2. 授予专利许可
+
+      每个“贡献者”根据“本许可证”授予您永久性的、全球性的、免费的、非独占的、不可撤销的（根据本条规定撤销除外）专利许可，供您制造、委托制造、使用、许诺销售、销售、进口其“贡献”或以其他方式转移其“贡献”。前述专利许可仅限于“贡献者”现在或将来拥有或控制的其“贡献”本身或其“贡献”与许可“贡献”时的“软件”结合而将必然会侵犯的专利权利要求，不包括对“贡献”的修改或包含“贡献”的其他结合。如果您或您的“关联实体”直接或间接地，就“软件”或其中的“贡献”对任何人发起专利侵权诉讼（包括反诉或交叉诉讼）或其他专利维权行动，指控其侵犯专利权，则“本许可证”授予您对“软件”的专利许可自您提起诉讼或发起维权行动之日终止。
+
+   3. 无商标许可
+
+      “本许可证”不提供对“贡献者”的商品名称、商标、服务标志或产品名称的商标许可，但您为满足第4条规定的声明义务而必须使用除外。
+
+   4. 分发限制
+
+      您可以在任何媒介中将“软件”以源程序形式或可执行形式重新分发，不论修改与否，但您必须向接收者提供“本许可证”的副本，并保留“软件”中的版权、商标、专利及免责声明。
+
+   5. 免责声明与责任限制
+
+      “软件”及其中的“贡献”在提供时不带任何明示或默示的担保。在任何情况下，“贡献者”或版权所有者不对任何人因使用“软件”或其中的“贡献”而引发的任何直接或间接损失承担责任，不论因何种原因导致或者基于何种法律理论，即使其曾被建议有此种损失的可能性。 
+
+   6. 语言
+      “本许可证”以中英文双语表述，中英文版本具有同等法律效力。如果中英文版本存在任何冲突不一致，以中文版为准。
+
+   条款结束 
+
+   如何将木兰宽松许可证，第2版，应用到您的软件
+   
+   如果您希望将木兰宽松许可证，第2版，应用到您的新软件，为了方便接收者查阅，建议您完成如下三步：
+
+      1， 请您补充如下声明中的空白，包括软件名、软件的首次发表年份以及您作为版权人的名字；
+
+      2， 请您在软件包的一级目录下创建以“LICENSE”为名的文件，将整个许可证文本放入该文件中；
+
+      3， 请将如下声明文本放入每个源文件的头部注释中。
+
+   Copyright (c) [Year] [name of copyright holder]
+   [Software Name] is licensed under Mulan PSL v2.
+   You can use this software according to the terms and conditions of the Mulan PSL v2. 
+   You may obtain a copy of Mulan PSL v2 at:
+            http://license.coscl.org.cn/MulanPSL2 
+   THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.  
+   See the Mulan PSL v2 for more details.  
+
+
+                     Mulan Permissive Software License，Version 2
+
+   Mulan Permissive Software License，Version 2 (Mulan PSL v2)
+   January 2020 http://license.coscl.org.cn/MulanPSL2
+
+   Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions: 
+   
+   0. Definition
+   
+      Software means the program and related documents which are licensed under this License and comprise all Contribution(s). 
+   
+      Contribution means the copyrightable work licensed by a particular Contributor under this License.
+   
+      Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License.
+   
+      Legal Entity means the entity making a Contribution and all its Affiliates.
+   
+      Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity.
+
+   1. Grant of Copyright License
+
+      Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not.
+
+   2. Grant of Patent License 
+
+      Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken.
+
+   3. No Trademark License
+
+      No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in Section 4.
+
+   4. Distribution Restriction
+
+      You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software.
+
+   5. Disclaimer of Warranty and Limitation of Liability
+
+      THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+   6. Language
+
+      THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL.
+
+   END OF THE TERMS AND CONDITIONS
+
+   How to Apply the Mulan Permissive Software License，Version 2 (Mulan PSL v2) to Your Software
+
+      To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps:
+
+      i Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner; 
+
+      ii Create a file named “LICENSE” which contains the whole context of this License in the first directory of your software package;
+
+      iii Attach the statement to the appropriate annotated syntax at the beginning of each source file.
+
+
+   Copyright (c) [Year] [name of copyright holder]
+   [Software Name] is licensed under Mulan PSL v2.
+   You can use this software according to the terms and conditions of the Mulan PSL v2. 
+   You may obtain a copy of Mulan PSL v2 at:
+               http://license.coscl.org.cn/MulanPSL2 
+   THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.  
+   See the Mulan PSL v2 for more details.  

package/Makefile

@@ -0,0 +1,66 @@
+SHELL := /bin/bash
+COMPOSE := docker compose
+
+.DEFAULT_GOAL := help
+.PHONY: help up down logs ps build restart migrate revision test test-backend test-frontend test-e2e verify-analysis verify-ai lint fmt typecheck shell clean
+
+help: ## 显示所有可用目标
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+up: ## 启动全部服务
+	$(COMPOSE) up -d --build
+
+down: ## 停止全部服务
+	$(COMPOSE) down
+
+logs: ## 跟踪服务日志
+	$(COMPOSE) logs -f --tail=100
+
+ps: ## 查看服务状态
+	$(COMPOSE) ps
+
+build: ## 重新构建镜像
+	$(COMPOSE) build
+
+restart: down up ## 重启全部服务
+
+migrate: ## 执行数据库迁移
+	$(COMPOSE) exec backend alembic upgrade head
+
+revision: ## 生成迁移（用法: make revision m="描述"）
+	$(COMPOSE) exec backend alembic revision --autogenerate -m "$(m)"
+
+test: test-backend ## 运行全部测试
+
+test-backend: ## 运行后端测试
+	$(COMPOSE) exec backend pytest -q
+
+test-e2e: ## 浏览器端端到端验证（需 pip install playwright && playwright install chromium）
+	python3 scripts/e2e-verify.py
+
+# 以下两个脚本跑在真实数据库上，因此用本机 venv 而非容器 ——
+# 它们断言的是数据的性质（覆盖率、幂等、不打回 AI 判定），
+# 而这些性质只有当数据真实存在时才可验证。
+verify-analysis: ## 校验分类与关注项流水线（需本机 backend/.venv）
+	cd backend && KSC_SECRET_KEY="$$(grep -m1 '^KSC_SECRET_KEY=' ../.env | cut -d= -f2-)" \
+		.venv/bin/python ../scripts/verify-analysis-pipeline.py
+
+verify-ai: ## 校验 AI 链路（本地桩端点，需本机 backend/.venv）
+	cd backend && KSC_SECRET_KEY="$$(grep -m1 '^KSC_SECRET_KEY=' ../.env | cut -d= -f2-)" \
+		.venv/bin/python ../scripts/verify-ai-pipeline.py
+
+lint: ## 后端静态检查
+	$(COMPOSE) exec backend ruff check .
+
+fmt: ## 后端格式化
+	$(COMPOSE) exec backend ruff format .
+
+typecheck: ## 前端类型检查
+	cd frontend && npx tsc --noEmit
+
+shell: ## 进入后端容器
+	$(COMPOSE) exec backend bash
+
+clean: ## 停止并删除数据卷（危险：会清空数据库）
+	$(COMPOSE) down -v

package/README.md

@@ -0,0 +1,279 @@
+# Kernel SIG Console
+
+openEuler Kernel SIG 的本地自托管协作平台，用于管理 AtomGit 上的 PR 与 Issue。
+
+## 为什么需要它
+
+openEuler 内核仓库当前有 **1000+ 个开放的 PR**，评审状态由 `lgtm-*` / `approved` /
+`ci_*` 标签承载，没有统一视图。Maintainer 难以快速识别优先级、统计评审 SLA、
+发现被淹没的重要 PR。
+
+本平台把这些信息结构化，并提供 AI 辅助分析。
+
+## 功能
+
+| 模块 | 说明 | 状态 |
+|------|------|------|
+| 认证与权限 | 五级 RBAC（观察者/评审者/提交者/维护者/管理员），审计留痕 | 已实现 |
+| PR 管理 | 门禁阶段筛选、标题/编号检索、分支与排序、详情含提交/文件 diff/评审时间线 | 已实现 |
+| Issue 管理 | 按 AtomGit 原生类型与优先级筛选、状态着色 | 已实现 |
+| 评审跟踪 | 从评论解析评审事件，归属评审人工作量；合并门禁四段推导 | 已实现 |
+| 数据同步 | 分层增量同步（列表/详情/评论），幂等，支持 webhook 触发 | 已实现 |
+| 定时轮询 | ARQ worker 按任务错峰调度：列表 / 详情 / 分类 / 关注项 / AI 补判 | 已实现 |
+| 统计分析 | 积压时长、合并周期、门禁分布、分支分布、评审人排行 | 已实现 |
+| 凭据管理 | AES-256-GCM 加密存储、指纹展示、有效性校验 | 已实现 |
+| 自动分类 | 规则优先、AI 兜底，识别 CVE / Backport / 子系统归属，支持人工指定 | 已实现 |
+| 关注队列 | 13 条规则收敛成可认领的待办，每条附判定依据 | 已实现 |
+| AI 对接 | OpenAI 兼容协议、按任务路由模型、类型补判 / 摘要 / 风险审查 / backport 核对 | 已实现 |
+
+## 实测数据（openeuler/kernel）
+
+平台在真实仓库上验证，以下为某次同步的实际结果：
+
+| 指标 | 数值 |
+|------|------|
+| 未合并 PR | 1,133 |
+| 已合并 PR | 4,000 |
+| 未关闭 Issue | 2,031 |
+| 可立即合入 | 179 |
+| 待评审 | 772 |
+| 超 30 天未评审 | 457 |
+| 合并周期中位数 | 2 天 |
+
+> 「可合入」指 CLA 已签署、CI 通过、有 LGTM 且已关联 Issue ——
+> 在这之前，这些信息散落在上千个 PR 的标签里，无法一眼看出。
+
+### 关于评审状态的两个反直觉事实
+
+实现过程中通过真实数据确认，与直觉相反，且都会导致维护者看到错误信息：
+
+1. **CI 失败标签是 `ci_failed`**，而非 `ci_must_go_failed`（实测前者 36 次、后者 1 次）。
+2. **`approved` 不是合入前的前置门禁**：200 个 open PR 中 0 个带此标签，
+   而 200 个已合并 PR 中 199 个带 —— 它是合入时补记的标记。
+   把它当作前置条件会让「可合入」状态永不可能出现。
+3. **评审人身份在评论里，不在标签里**：PR 上用的是整体 `lgtm` 标签，
+   具体是谁评审的，记录在人类的 `/lgtm` 评论中。
+
+## 自动分类、关注队列与 AI
+
+三者是同一条链路上的三环：**规则能判的判定，判不出的交给模型，需要人看的排成待办**。
+
+### 分类：规则优先，AI 兜底，人工最高
+
+规则是确定性的（标题里有 `CVE-\d{4}-\d{4,}` 就是 CVE），因此先跑规则。
+实测 3164 个 open PR/Issue 上规则覆盖率约 **54%** —— 剩余部分不是规则写少了，
+而是内核补丁标题描述的是「改了什么」而非「属于哪一类」。这部分交给模型补判。
+
+三档优先级严格有序，且每条记录都保留判定来源与依据：
+
+| 来源 | 何时写入 | 会被谁覆盖 |
+|------|----------|-----------|
+| 规则 | 每次同步后重算 | 规则、AI、人工 |
+| AI | 规则判不出时补判 | 人工；**规则判不出来时不覆盖** |
+| 人工 | 维护者显式指定 | 只有维护者自己撤销 |
+
+第二条约束不是可选项。规则每 10 分钟全量重算一次；若允许它把 AI 的结论打回
+`unknown`，那条记录下一轮又会被挑去补判 —— 模型会被反复调用同一个对象，
+既不收敛也持续计费。
+
+### 关注队列：只给结论是没有用的
+
+13 条规则覆盖 PR 与 Issue 两侧（评审超期、CI 失败、CVE 未推进、缺签名、
+Issue 无人认领……）。每条命中都带**证据**：等了几天、哪个文件是二进制、
+缺几个签名、涉及哪些 CVE。维护者据此可以直接决定下一步动作，
+而不是只看到一个「有问题」的标记。
+
+状态是保留而非覆盖的：命中时保留 `first_detected_at`，不再命中的置
+`resolved_at` 而不删除 —— 「这条挂了多久才被处理」本身就是要看的信息。
+
+### AI：唯一按次计费的部分
+
+- **按任务配模型**：分类这类轻任务用便宜模型，代码风险审查才用强模型
+- **内容指纹幂等**：输入没变就不重复调用，`force=true` 才强制重跑
+- **失败不中断**：单条上游失败只落状态，不让整轮定时任务停摆；
+  但**未配置模型**属于部署问题，直接抛错，不留失败记录污染用量统计
+- **Prompt 内嵌领域规则**：KABI 兼容性约束、补丁格式要求、backport 核对方法，
+  而不是让它「通用地评审一段代码」
+
+## 快速开始
+
+前提只有一个：本机装了 Docker。
+
+```bash
+npx @kernel-sig/console            # 起一整套实例，首次要构建镜像、几分钟
+npx @kernel-sig/console --open      # 顺手打开浏览器
+```
+
+首次运行会自动生成 `~/.kernel-sig/.env`（含随机的 `KSC_SECRET_KEY`）、构建镜像、
+起容器，就绪后打印地址。访问 <http://localhost:18080> 会引导创建管理员账号。
+
+装成全局之后命令短得多，日常用这个：
+
+```bash
+npm i -g @kernel-sig/console
+ksc          # 再次启动，秒级
+ksc logs     # 看日志
+ksc status   # 看容器状态
+ksc down     # 停止；数据留在 docker 卷里，下次启动仍在
+```
+
+新实例**默认已纳管 `openeuler/kernel`**。给个 AtomGit token 就开始拉数据：
+
+```bash
+ksc --token <你的 AtomGit token>
+```
+
+不给也能起，只是没有数据 —— 界面上的仓库卡片会标明「未配置凭据」并指向凭据设置，
+之后随时在「设置 → 凭据」里补。
+
+> 注意：这是**在你本机跑一个独立实例**，不是连到别人的服务；和已有的实例各有各的
+> 数据库。另外平台的定时同步需要机器常驻，合上笔记本就停了 —— 适合试用与评估，
+> 正式给团队用仍然建议部署到服务器（见下一节）。
+
+### 从源码部署
+
+服务器上部署走这条，`ksc` 只是它的封装：
+
+```bash
+cp .env.example .env
+# 生成密钥并写入 .env 的 KSC_SECRET_KEY
+openssl rand -hex 32
+
+make up
+```
+
+## 常用命令
+
+```bash
+make help        # 查看全部命令
+make up          # 启动
+make down        # 停止
+make logs        # 查看日志
+make migrate     # 执行数据库迁移
+make test        # 运行测试
+make lint        # 静态检查
+```
+
+## 配置
+
+所有配置通过环境变量提供，见 [`.env.example`](.env.example)。
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `KSC_SECRET_KEY` | 凭据加密与 JWT 签名密钥（≥32 字符），**必填** | 无 |
+| `DOCKER_REGISTRY` | 镜像源前缀 | `docker.m.daocloud.io` |
+| `PIP_INDEX_URL` | 构建时的 PyPI 源 | 清华源 |
+| `KSC_WEB_PORT` | Web 访问端口 | `18080` |
+| `KSC_ENVIRONMENT` | `development` / `production` | `production` |
+| `KSC_BOOTSTRAP_REPOSITORY` | 首次启动自动纳管的仓库（`owner/name`） | `openeuler/kernel` |
+| `KSC_ATOMGIT_TOKEN` | 首次启动导入成凭据；不填则在界面上添加 | 空 |
+
+> **端口说明**：默认使用 18080 / 18000 / 15432 / 16379，
+> 主动避开常见的 80 / 443 / 3000 / 8000 / 6379，以免与本机既有服务冲突。
+
+> **镜像源说明**：部分网络环境直连 Docker Hub 与 pypi.org 极慢或不可达，
+> 因此默认走国内镜像源。其他网络环境改回官方源即可。
+
+## 架构
+
+```
+浏览器 → Nginx (:18080) → FastAPI (:8000) → PostgreSQL
+                                      ↘
+                          ARQ Worker → AtomGit API / LLM
+                                      ↘ Valkey（队列）
+```
+
+后端分层为 API / Service / Model / Core，依赖单向：`api → services → models`，
+`integrations` 不依赖任何内部模块，保证领域逻辑能被 worker 与测试独立复用。
+
+worker 与 API 复用同一镜像、只换启动命令。迁移由 API 进程负责执行，
+worker 等它就绪再接活，避免两个进程同时跑 Alembic。
+
+### 定时任务节奏
+
+分钟点刻意错开：全部压在整点会让上游在瞬间收到成倍请求，
+自己的数据库也会同时承受多个全量重算。
+
+| 任务 | 频率 | 超时 |
+|------|------|------|
+| `sync_pulls` | 每 10 分钟 | 600s |
+| `sync_issues` | 每 30 分钟 | 600s |
+| `sync_pull_details` | 每 5 分钟（一批 50 个） | 900s |
+| `classify_repository` | 每 10 分钟 | 600s |
+| `compute_attention` | 每 15 分钟 | 600s |
+| `run_ai_analysis` | 每 30 分钟（一批 5 个） | 1800s |
+
+详情同步刻意小批量高频：单次请求量大时上游会限流，
+而列表同步必须先跑完 —— 关注项规则读的是它写下的派生列。
+
+## 安全
+
+- AtomGit token 与 LLM API Key 使用 **AES-256-GCM** 加密落库，
+  密钥由 `KSC_SECRET_KEY` 经 HKDF-SHA256 派生（不直接复用配置密钥）
+- 界面**不回显**凭据明文，仅展示指纹
+- 密码使用 **Argon2id** 哈希
+- 会话令牌存 **HttpOnly + SameSite** Cookie
+- 所有写操作记入审计日志，凭据类字段自动脱敏
+
+## 开发
+
+```bash
+# 仅启动依赖服务
+docker compose up -d postgres valkey
+
+# 后端（本机）
+cd backend
+python3 -m venv .venv
+.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"
+.venv/bin/uvicorn app.main:app --reload --port 18000
+
+# 前端（本机）
+cd frontend && npm install && npm run dev   # http://localhost:15173
+```
+
+### 验证脚本
+
+除单元测试外，仓库内有三个跑在真实数据 / 真实浏览器上的校验脚本。
+单元测试证明代码符合预期，这三个脚本证明系统在真实环境下确实工作。
+
+```bash
+# 浏览器端到端（100+ 项断言，覆盖全部页面与交互）
+# 需要 playwright：pip install playwright && playwright install chromium
+python3 scripts/e2e-verify.py
+
+# 分类与关注项：跑在真实数据库上，验证覆盖率与重算幂等
+cd backend && KSC_SECRET_KEY=... .venv/bin/python ../scripts/verify-analysis-pipeline.py
+
+# AI 链路：本地桩服务冒充 OpenAI 兼容端点，验证请求头/payload/
+# JSON 解析/幂等/失败降级/人工覆盖优先
+cd backend && KSC_SECRET_KEY=... .venv/bin/python ../scripts/verify-ai-pipeline.py
+```
+
+> 后两个脚本读的是本机活实例的数据库，断言不假设环境为空；
+> 它们验证的是数据的性质（覆盖率、幂等、不打回 AI 判定），
+> 这些性质只有数据真实存在时才可验证。
+
+## 发布到 npm（维护者）
+
+`package.json` 顶部的 `files` 是**显式白名单**，不是可选项。实测 npm 10.9.8 会把
+白名单里列出的目录**原样整目录**收进包 —— `frontend/node_modules`（290 MB）
+就是这么做进去的，`.npmignore` 拦不住。所以新增构建产物类的文件时，要同步更新这份
+名单，不要指望忽略文件。
+
+发布前先看一遍清单，尤其确认里面**没有 `.env`**（那是明文密钥）：
+
+```bash
+npm pack --dry-run          # 看清单
+npm pack                    # 出 tarball，可先用它本地验一遍
+npm publish --access public --otp=<六位码>
+```
+
+`name@version` 一旦发布就永远不能重用（即使 `npm unpublish` 也不行），
+所以先用 `npm exec --package=./kernel-sig-console-0.1.0.tgz -- ksc up` 跑通再发。
+
+## 许可
+
+[木兰宽松许可证，第 2 版](LICENSE)（Mulan Permissive Software License, Version 2，
+SPDX 标识符 `MulanPSL-2.0`）。
+
+Copyright (c) 2026 Xie XiuQi

package/backend/.dockerignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+*.egg-info/
+build/
+dist/
+.env

package/backend/Dockerfile

@@ -0,0 +1,43 @@
+ARG DOCKER_REGISTRY=docker.io
+FROM ${DOCKER_REGISTRY}/library/python:3.12-slim
+
+# 部分网络环境下 pypi.org 直连极慢，构建参数允许切换到镜像源
+ARG PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+ENV PIP_INDEX_URL=${PIP_INDEX_URL} \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl \
+ && rm -rf /var/lib/apt/lists/*
+
+# 先装依赖再拷源码，让依赖层在源码变更时仍可复用
+COPY pyproject.toml ./
+RUN python -m pip install --upgrade pip \
+ && python -m pip install -e ".[dev]"
+
+COPY . .
+
+# 上面那次 -e 安装时 app/ 还没进来，`packages.find` 一无所获，
+# 生成的映射是空的 —— 于是 import app 只在 cwd 正好是 /app 时成立。
+# 服务本身跑在 /app 下看不出问题，但 `pytest` 控制台脚本不把 cwd
+# 放进 sys.path：`make test-backend` 会报满屏 ModuleNotFoundError，
+# 看着像代码坏了。补跑一次，此时包已就位；--no-deps 保证不重解依赖，
+# 上面的依赖层仍然复用。
+RUN python -m pip install -e . --no-deps
+
+RUN useradd --create-home --uid 10001 appuser \
+ && chmod +x entrypoint.sh \
+ && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -fsS http://localhost:8000/api/v1/healthz || exit 1
+
+CMD ["./entrypoint.sh"]

package/backend/alembic/env.py

@@ -0,0 +1,75 @@
+"""Alembic 环境配置：URL 从应用 Settings 读取，不落配置文件。"""
+
+import asyncio
+import os
+from logging.config import fileConfig
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+
+# 迁移本身不需要签名/加密密钥。若调用方只跑迁移（如 CI 的 schema 校验），
+# 不应被迫提供 KSC_SECRET_KEY。应用启动时仍会强制校验该变量。
+os.environ.setdefault("KSC_SECRET_KEY", "migration-only-placeholder-key-0000000000")
+
+from app.core.config import get_settings
+from app.models import Base
+
+config = context.config
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def _database_url() -> str:
+    return get_settings().database_url
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=_database_url(),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        compare_type=True,
+        compare_server_default=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    configuration = config.get_section(config.config_ini_section, {})
+    configuration["sqlalchemy.url"] = _database_url()
+    connectable = async_engine_from_config(
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/backend/alembic/script.py.mako

@@ -0,0 +1,25 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: str | None = ${repr(down_revision)}
+branch_labels: str | Sequence[str] | None = ${repr(branch_labels)}
+depends_on: str | Sequence[str] | None = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}