git-ai-control 0.4.11 → 0.4.13

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 本项目的所有重要变更都会记录在此文件中。
 
+## [0.4.13] - 2026-09-09
+
+### 新增
+
+- Skill 过滤新增“新目录观察期”：目录创建未满 7 天时，首次 Skill 上报默认拦截 24 小时，超时未处理自动放行；观察期状态在本机持久化，服务重启不会重新计时。
+- 管理后台新增观察期白名单和 Skill 黑名单：白名单可立即放行指定 Skill，黑名单持续阻断指定 Skill 上报。
+
+## [0.4.12] - 2026-08-12
+
+### 变更
+
+- 英文 README 改用完整英文界面截图，并移除末尾误附的中文重复内容；中文说明继续由 `README.zh-CN.md` 提供。
+
 ## [0.4.11] - 2026-08-12
 
 ### 修复

package/README.md

@@ -1,6 +1,6 @@
 # Git AI Control Panel
 
-[中文文档](README.zh-CN.md)
+[Chinese documentation](README.zh-CN.md)
 
 Git AI Control Panel is a local settings and upload-policy manager for Git AI on macOS, Linux, and Windows. It lets you control report event types and fields by repository host without manually editing JSON or writing a script for every privacy rule. The React/Vite control page listens only on `127.0.0.1:38742`; it is never exposed to your LAN or the public internet.
 
@@ -25,11 +25,11 @@ Git AI Control Panel is a local settings and upload-policy manager for Git AI on
 
 ### Native Git AI settings
 
-![Native Git AI settings](docs/images/git-ai-settings.jpg)
+![Native Git AI settings](docs/images/git-ai-settings-en.png)
 
 ### Plugin management
 
-![Repository and Skill filter plugin management](docs/images/plugin-management.jpg)
+![Repository and Skill filter plugin management](docs/images/plugin-management-en.png)
 
 ## Quick start
 
@@ -166,217 +166,3 @@ The project publishes one cross-platform npm package. Pushing a Git tag matching
 - The page rejects modification requests from non-page origins.
 - If plugin configuration is missing or invalid, the default GitHub policy remains fully blocking.
 - Without the granular filtering extension point, the page reports native-settings compatibility instead of claiming filtering is active.
-
-> [!IMPORTANT]
-> 项目可以识别 `custom_metrics` 定制版和官方 [`git-ai-project/git-ai`](https://github.com/git-ai-project/git-ai)，但两者支持层级不同。仓库级事件开关、字段脱敏和 Skill 过滤目前需要 `custom_metrics` 扩展点；官方版只能管理 Git AI 已公开的原生配置。安装前请阅读[兼容性说明](COMPATIBILITY.md)。
-
-## 功能
-
-- 可视化管理 Git AI 自动更新、版本检查、仓库排除和提示词排除；
-- 通过“匹配仓库主机”统一处理 GitHub、GitLab、Gitee 或其他 Git 服务；
-- 分别控制 Token、Skills、Commit、Checkpoint、Agent、提示耗时和提示报告；
-- 可删除仓库信息、项目路径和分支名称等敏感字段；
-- 可将允许上传的 Skill 项目目录替换为固定目录；
-- 可按关键词或正则拦截指定 Skill；
-- 仓库插件可按不同主机添加多个，并支持全局兜底、仓库、目录、分支与优先级；
-- 敏感内容脱敏插件可识别 API Key、私钥、凭据，并按规则脱敏或拦截；
-- Agent / 模型治理插件支持允许名单、阻止正则及审计/拦截模式；
-- Skill、敏感内容和 Agent / 模型治理均使用独立配置表单；
-- 支持配置验证、运行状态检查和本机过滤服务重启。
-
-## 界面截图
-
-### Git AI 原生设置
-
-![Git AI 原生设置页面](docs/images/git-ai-settings.jpg)
-
-### 插件管理
-
-![仓库插件与 Skill 过滤插件管理页面](docs/images/plugin-management.jpg)
-
-仓库插件可以同时配置匹配主机、允许上传的数据类型和允许保留的字段，也可以按不同主机添加多个。主机规则重叠时按列表顺序使用第一个命中插件；Skill 过滤插件使用独立表单管理名称规则，且只能添加一次。
-
-插件管理页面按添加顺序展示全部插件。无论添加仓库插件还是独立插件，新卡片都会追加到现有列表最后；这只影响页面展示顺序，不改变仓库规则的匹配优先级。
-
-## 快速开始
-
-### 1. 一条命令启动
-
-支持 macOS、Linux 和 Windows，需要 Node.js 18+、Python 3，并要求 Git AI 已安装在默认目录：
-
-```text
-macOS / Linux: ~/.git-ai/bin/git-ai
-Windows:       %USERPROFILE%\.git-ai\bin\git-ai.exe
-```
-
-确认文件存在后运行：
-
-```bash
-npx git-ai-control
-```
-
-首次运行时，该命令会自动下载最新版本、安装本机服务，并打开 Git AI 配置中心；之后检测到已运行的配置中心时，会直接复用现有进程。
-
-首次安装过程会：
-
-1. 识别当前 Git AI 是否支持 `custom_metrics` 扩展；
-2. 将原始上报端点备份到仅当前用户可读的本机配置；
-3. 安装控制页面和上传过滤运行时；
-4. 保留已有的 `config.json` 与 `filter_plugins.json`；
-5. 通过当前系统的用户级服务管理器创建并启动两个本机服务；
-6. 等待控制页面和过滤服务通过健康检查。
-
-如果浏览器没有自动打开，可以手动访问：
-
-```text
-http://127.0.0.1:38742
-```
-
-页面顶部会显示当前 Git AI 发行版、过滤接管状态和服务状态。
-
-各系统使用的服务管理方式：
-
-| 系统 | 服务管理器 | 使用条件 |
-| --- | --- | --- |
-| macOS | LaunchAgent | 当前图形用户会话 |
-| Linux | systemd user | 可用的 systemd 用户会话 |
-| Windows | 任务计划程序 | Windows 10/11，当前用户可创建登录任务 |
-
-### 2. 配置仓库插件
-
-以“GitHub 私人仓库只允许上传 Token”为例：
-
-1. 在“仓库插件”中添加或打开现有仓库插件；
-2. 在“匹配仓库主机”中填写 `github.com`；
-3. 只打开 `Token`，关闭 `Skills`、`Commit`、`Checkpoint`、`Agent`、提示耗时和提示报告；
-4. 关闭“仓库信息”“项目路径”和“分支名称”；
-5. 保存配置。
-
-同一个仓库插件也可以填写多个主机，每行一个；也可以为不同主机分别添加仓库插件。GitLab、Gitee 和自建 Git 服务不需要单独开发插件。
-
-仓库策略会先匹配特定规则，再匹配“全部仓库”全局规则；特定规则之间优先级数字越大越靠前，同优先级按插件列表顺序处理。仓库、目录、分支同时填写时需要全部命中。
-
-### 3. 配置敏感内容与 Agent
-
-在“插件管理”中可分别添加以下独立插件：
-
-1. “敏感内容脱敏”：选择作用事件、内置规则和自定义正则；命中后可脱敏或阻止上报；
-2. “Agent / 模型治理”：配置允许的 Agent、模型与阻止正则；先使用“仅审计”确认命中情况，再按需改为阻止。
-
-### 4. 配置 Skill 过滤插件
-
-需要按名称拦截 Skill 时：
-
-1. 添加“Skill 过滤插件”；
-2. 打开插件；
-3. 每行填写一个关键词或正则；
-4. 保存配置。
-
-Skill 过滤插件只负责名称规则。仓库匹配、上传类型和目录替换仍由仓库插件负责。
-
-### 5. 验证配置
-
-点击页面中的“验证配置”。结果会通过右上角 Toast 显示，不会占用配置表单空间。
-
-也可以在终端检查两个本机服务：
-
-```bash
-curl -fsS http://127.0.0.1:38742/api/status
-curl -fsS http://127.0.0.1:38741/health
-```
-
-## 工作方式
-
-本项目不会修改 `~/.git-ai/bin/git-ai` 二进制。检测到 `custom_metrics` 扩展点后，安装脚本会将 Git AI 的自定义上报端点指向本机过滤服务：
-
-```text
-Git AI
-  -> ~/.git-ai/custom_metrics.json
-  -> http://127.0.0.1:38741
-  -> 读取 ~/.git-ai/filter_plugins.json
-  -> 读取 ~/.git-ai/upstream_metrics.json
-  -> 拦截，或脱敏后转发至原上报服务
-```
-
-两个页签中的“查看配置”会重新读取当前磁盘内容，不会显示未保存的表单修改。Git AI 原生配置只展示本页面安全管理的字段，插件策略展示完整已写入策略。
-
-控制页面保存时只更新：
-
-- `~/.git-ai/config.json`：Git AI 原生设置；
-- `~/.git-ai/filter_plugins.json`：仓库插件和 Skill 过滤插件策略。
-
-过滤逻辑来自仓库中的 `plugins/upload-filter/plugin_filter_runtime.py`。控制页面不会动态生成或改写 Python 脚本，`~/.git-ai` 只保存安装副本和用户配置。
-
-## 文件位置
-
-| 内容 | 位置 |
-| --- | --- |
-| 过滤运行时源码 | `plugins/upload-filter/plugin_filter_runtime.py` |
-| 跨平台安装器 | `scripts/install.mjs`、`scripts/uninstall.mjs` |
-| 服务适配器 | `scripts/platform-services.mjs` |
-| Git AI 原生配置 | `~/.git-ai/config.json` |
-| 插件策略 | `~/.git-ai/filter_plugins.json` |
-| 原上报端点本机备份 | `~/.git-ai/upstream_metrics.json` |
-| 过滤运行时安装副本 | `~/.git-ai/filters/plugin_filter_runtime.py` |
-| Web 服务安装副本 | `~/.git-ai/control-panel` |
-| macOS 服务定义 | `~/Library/LaunchAgents/com.git-ai.*.plist` |
-| Linux 服务定义 | `~/.config/systemd/user/git-ai-*.service` |
-| Windows 服务定义 | `%USERPROFILE%\.git-ai\services\*.ps1` 与任务计划程序 |
-
-## 卸载
-
-```bash
-npx git-ai-control uninstall
-```
-
-卸载命令会停止两个服务、删除本项目安装的程序副本，并将上报端点恢复为 Git AI 原地址。`config.json`、`filter_plugins.json` 和日志会保留。
-
-## 参与贡献
-
-欢迎提交 Issue 和 Pull Request，尤其欢迎：
-
-- 补充不同 Git AI 版本的兼容性验证；
-- 新增与仓库过滤不同类型的独立插件；
-- 改进过滤规则的测试覆盖；
-- 修正文档、交互和无障碍问题。
-
-开发前请先 Fork 仓库并创建主题分支。前端源码位于 `frontend/git-ai-control-panel`，shadcn/ui 组件位于 `src/components/ui`。
-
-```bash
-cd frontend/git-ai-control-panel
-npm ci
-npm run lint
-npm run build
-cd ../..
-npm run check
-```
-
-提交 Pull Request 时请说明：
-
-1. 解决的问题和使用场景；
-2. 对配置结构或过滤行为的影响；
-3. 已执行的验证命令；
-4. 涉及界面变化时附上前后截图。
-
-新增插件类型时，请为它设计独立的数据结构和配置表单；不要复用仓库插件表单来表达无关能力。涉及上报兼容性时，应基于实际 Git AI 版本和请求路径验证，避免把“页面可配置”误写成“运行时已接管”。
-
-## 发布
-
-项目只发布一个跨平台 npm 包，不分别生成 macOS、Linux 或 Windows 安装包。推送与 `package.json` 版本一致的 Git 标签后，GitHub Actions 会：
-
-1. 在 macOS、Ubuntu 和 Windows 上检查同一份安装器与运行时源码；
-2. 在 Ubuntu 上只构建一次前端静态资源；
-3. 确认构建产物与仓库内容一致；
-4. 通过 npm Trusted Publishing（OIDC）发布到 npmjs.com。
-
-发布工作流不使用长期 npm Access Token。npm 包需要将 `.github/workflows/publish.yml` 配置为可信发布者。
-
-## 安全边界
-
-- Web 服务只绑定本机回环地址；
-- 不读取或展示 Git AI API key 等敏感字段；
-- 原始上报端点不会写入项目源码，只保存在权限为 `0600` 的本机配置中；
-- 配置保存采用临时文件替换，避免写入中断产生不完整文件；
-- 页面没有跨域权限，拒绝非本页面来源的修改请求；
-- 插件配置缺失或损坏时，GitHub 默认策略保持全部阻断；
-- 官方版缺少细粒度过滤扩展点时，页面会显示“仅原生配置兼容”，不会把空闲代理误报为已接管。

package/README.zh-CN.md

@@ -17,6 +17,7 @@
 - 可删除仓库信息、项目路径和分支名称等敏感字段；
 - 可将允许上传的 Skill 项目目录替换为固定目录；
 - 可按关键词或正则拦截指定 Skill；
+- 新建目录 7 天内的 Skill 上报默认进入 24 小时观察期，可在后台通过白名单放行或黑名单持续拦截；
 - 仓库插件可按不同主机添加多个，并支持全局兜底、仓库、目录、分支与优先级；
 - 敏感内容脱敏插件可识别 API Key、私钥、凭据，并按规则脱敏或拦截；
 - Agent / 模型治理插件支持允许名单、阻止正则及审计/拦截模式；
@@ -90,7 +91,13 @@ http://127.0.0.1:38742
 3. 每行填写一个关键词或正则；
 4. 保存配置。
 
-### 5. 验证配置
+### 5. 新目录 Skill 观察期
+
+“Skill 过滤插件”默认启用新目录观察期。上报事件中的项目目录创建未满 7 天时，首次 Skill 上报会被拦截 24 小时；期间可将 Skill 加入观察期白名单立即放行，或加入 Skill 黑名单持续阻断。24 小时没有处理则自动恢复上报，且过滤服务重启不会重新计时。
+
+文件系统未提供目录创建时间时，观察期不会基于不可靠的修改时间推断目录年龄。
+
+### 6. 验证配置
 
 点击页面中的“验证配置”，或在终端检查两个本机服务：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-ai-control",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Git AI 本地配置与上传隐私控制面板",
   "type": "module",
   "bin": {

package/plugins/upload-filter/plugin_filter_runtime.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import json
 import os
 import re
@@ -39,9 +40,14 @@ GIT_AI_ROOT = Path(os.environ.get("GIT_AI_ROOT", Path.home() / ".git-ai")).resol
 POLICY_CONFIG_PATH = GIT_AI_ROOT / "filter_plugins.json"
 UPSTREAM_CONFIG_PATH = GIT_AI_ROOT / "upstream_metrics.json"
 FILTER_AUDIT_PATH = GIT_AI_ROOT / "filter_audit.jsonl"
+RECENT_SKILL_HOLD_PATH = GIT_AI_ROOT / "recent_skill_holds.json"
 FILTER_AUDIT_RETENTION = timedelta(hours=24)
 FILTER_AUDIT_MAX_EVENTS = 2_000
 FILTER_AUDIT_LOCK = threading.Lock()
+RECENT_SKILL_HOLD_LOCK = threading.Lock()
+RECENT_DIRECTORY_MAX_AGE = timedelta(days=7)
+RECENT_SKILL_HOLD_DURATION = timedelta(hours=24)
+RECENT_SKILL_HOLD_RETENTION = timedelta(days=7)
 OWNER_REPOSITORY_PATTERN = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+(?:\.git)?$")
 SKILL_KEYS = {"skillName", "skill", "name"}
 PATH_KEYS = {
@@ -137,6 +143,11 @@ DEFAULT_POLICY_CONFIG = {
             "cloudflare",
             "cloud-flare",
         ],
+        "recent_directory_guard": {
+            "enabled": True,
+            "allowlist_patterns": [],
+            "blocklist_patterns": [],
+        },
     },
     "plugins": [
         {
@@ -275,6 +286,15 @@ def iter_skill_text(value):
             yield from iter_skill_text(child)
 
 
+def skill_names(payload) -> list[str]:
+    names = set()
+    for value in iter_skill_text(payload):
+        name = audit_text(value, 160)
+        if name:
+            names.add(name)
+    return sorted(names)
+
+
 def audit_timestamp() -> str:
     return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
 
@@ -660,6 +680,148 @@ def matches_allowlist(value: str, patterns) -> bool:
     return any(selector_matches(pattern, [value]) for pattern in patterns)
 
 
+def compile_skill_patterns(patterns) -> list[re.Pattern]:
+    compiled = []
+    for pattern in patterns:
+        try:
+            compiled.append(re.compile(str(pattern), re.IGNORECASE))
+        except re.error:
+            continue
+    return compiled
+
+
+def directory_created_at(path: Path) -> datetime | None:
+    try:
+        metadata = path.stat()
+    except OSError:
+        return None
+
+    timestamp = getattr(metadata, "st_birthtime", None)
+    if timestamp is None and os.name == "nt":
+        timestamp = metadata.st_ctime
+    if timestamp is None:
+        return None
+    return datetime.fromtimestamp(timestamp, timezone.utc)
+
+
+def recent_payload_directories(payload, now: datetime) -> list[str]:
+    directories = set()
+    for value in iter_path_text(payload):
+        if not isinstance(value, str) or not value.strip():
+            continue
+        try:
+            path = Path(value).expanduser().resolve(strict=True)
+        except OSError:
+            continue
+        if not path.is_dir():
+            path = path.parent
+        created_at = directory_created_at(path)
+        if created_at is not None and now - created_at < RECENT_DIRECTORY_MAX_AGE:
+            directories.add(str(path))
+    return sorted(directories)
+
+
+def read_recent_skill_holds(path: Path = RECENT_SKILL_HOLD_PATH) -> dict[str, str]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    holds = value.get("holds", {}) if isinstance(value, dict) else {}
+    if not isinstance(holds, dict):
+        return {}
+    return {
+        key: timestamp
+        for key, timestamp in holds.items()
+        if isinstance(key, str) and parse_audit_timestamp(timestamp) is not None
+    }
+
+
+def write_recent_skill_holds(
+    holds: dict[str, str], path: Path = RECENT_SKILL_HOLD_PATH
+) -> None:
+    temporary = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+        temporary.write_text(
+            json.dumps({"version": 1, "holds": holds}, ensure_ascii=False, indent=2)
+            + "\n",
+            encoding="utf-8",
+        )
+        if os.name != "nt":
+            os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+    except OSError:
+        if temporary:
+            try:
+                temporary.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def recent_skill_hold_key(directory: str, skill: str) -> str:
+    return hashlib.sha256(f"{directory}\0{skill}".encode("utf-8")).hexdigest()
+
+
+def recent_directory_skill_guard(
+    payload,
+    skill_policy: dict,
+    *,
+    now: datetime | None = None,
+    state_path: Path = RECENT_SKILL_HOLD_PATH,
+) -> str | None:
+    if not skill_policy.get("installed", True) or not skill_policy.get("enabled", True):
+        return None
+    guard = skill_policy.get("recent_directory_guard", {})
+    if not isinstance(guard, dict):
+        return None
+    skills = skill_names(payload) or ["[unknown]"]
+    blocklist = compile_skill_patterns(guard.get("blocklist_patterns", []))
+    if any(pattern.search(skill) for skill in skills for pattern in blocklist):
+        return "recent_directory_skill_blocklist"
+    if not guard.get("enabled", True):
+        return None
+    allowlist = compile_skill_patterns(guard.get("allowlist_patterns", []))
+    if skills and all(any(pattern.search(skill) for pattern in allowlist) for skill in skills):
+        return None
+
+    now = now or datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    now = now.astimezone(timezone.utc)
+    directories = recent_payload_directories(payload, now)
+    if not directories:
+        return None
+
+    with RECENT_SKILL_HOLD_LOCK:
+        holds = read_recent_skill_holds(state_path)
+        holds = {
+            key: timestamp
+            for key, timestamp in holds.items()
+            if now - parse_audit_timestamp(timestamp) < RECENT_SKILL_HOLD_RETENTION
+        }
+        should_hold = False
+        for directory in directories:
+            for skill in skills:
+                key = recent_skill_hold_key(directory, skill)
+                first_seen = parse_audit_timestamp(holds.get(key))
+                if first_seen is None:
+                    first_seen = now
+                    holds[key] = audit_timestamp_from(now)
+                if now - first_seen < RECENT_SKILL_HOLD_DURATION:
+                    should_hold = True
+        write_recent_skill_holds(holds, state_path)
+    return "recent_directory_skill_hold" if should_hold else None
+
+
+def audit_timestamp_from(value: datetime) -> str:
+    return (
+        value.astimezone(timezone.utc)
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+
+
 def governance_findings(payload, policy: dict) -> list[str]:
     if not policy.get("installed", False) or not policy.get("enabled", False):
         return []
@@ -717,6 +879,16 @@ def evaluate_request(
             "plugin": plugin_id,
             "config_error": config_error,
         }
+    if event_type == "skill" and (
+        reason := recent_directory_skill_guard(payload, skill_policy)
+    ):
+        return {
+            "blocked": True,
+            "reason": reason,
+            "payload": payload,
+            "plugin": plugin_id,
+            "config_error": config_error,
+        }
 
     if plugin:
         allowed = bool(plugin.get("allow", {}).get(event_type, False))

package/policy.example.json

@@ -22,7 +22,12 @@
       "git-hub",
       "cloudflare",
       "cloud-flare"
-    ]
+    ],
+    "recent_directory_guard": {
+      "enabled": true,
+      "allowlist_patterns": [],
+      "blocklist_patterns": []
+    }
   },
   "plugins": [
     {

package/server.py

@@ -229,6 +229,31 @@ def validate_policy_config(value) -> dict:
             re.compile(pattern)
         except re.error as error:
             raise ConfigError(f"无效的 Skill 正则：{pattern}（{error}）") from error
+    recent_directory_guard = skill_policy.get("recent_directory_guard", {})
+    if not isinstance(recent_directory_guard, dict):
+        raise ConfigError("新目录观察期配置必须是对象")
+    recent_directory_guard_enabled = recent_directory_guard.get("enabled", True)
+    if not isinstance(recent_directory_guard_enabled, bool):
+        raise ConfigError("新目录观察期开关必须是布尔值")
+    recent_directory_allowlist = validate_string_list(
+        recent_directory_guard.get("allowlist_patterns", []),
+        "新目录观察期白名单",
+        maximum=256,
+    )
+    recent_directory_blocklist = validate_string_list(
+        recent_directory_guard.get("blocklist_patterns", []),
+        "新目录观察期黑名单",
+        maximum=256,
+    )
+    for label, patterns in (
+        ("新目录观察期白名单", recent_directory_allowlist),
+        ("新目录观察期黑名单", recent_directory_blocklist),
+    ):
+        for pattern in patterns:
+            try:
+                re.compile(pattern)
+            except re.error as error:
+                raise ConfigError(f"无效的{label}正则：{pattern}（{error}）") from error
 
     plugins = value.get("plugins")
     if not isinstance(plugins, list) or len(plugins) > 32:
@@ -392,6 +417,11 @@ def validate_policy_config(value) -> dict:
             "installed": skill_installed,
             "enabled": skill_enabled,
             "blocked_patterns": blocked_patterns,
+            "recent_directory_guard": {
+                "enabled": recent_directory_guard_enabled,
+                "allowlist_patterns": recent_directory_allowlist,
+                "blocklist_patterns": recent_directory_blocklist,
+            },
         },
         "plugins": normalized_plugins,
         "plugin_order": plugin_order,