🔄 卡若AI 同步 2026-02-15 23:26 | 变更 21 个文件 | 排除 >20MB: 4 个

2026-02-15 23:26:41 +08:00
parent 34ff8c290b
commit 1299d96b37
21 changed files with 612 additions and 0 deletions
--- a/.gitea/ISSUE_TEMPLATE/Bug反馈.md
+++ b/.gitea/ISSUE_TEMPLATE/Bug反馈.md
@@ -0,0 +1,28 @@
+---
+name: Bug 反馈
+about: 反馈某 Skill 或流程出现的错误、异常
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## 问题简述
+<!-- 一句话描述问题 -->
+
+## 复现步骤
+1.
+2.
+3.
+
+## 期望行为
+<!-- 正常应该怎样 -->
+
+## 实际行为
+<!-- 实际发生了什么（可贴报错、截图） -->
+
+## 环境（如相关）
+- 位置/Skill：
+- 系统/工具：
+
+## 补充
+<!-- 日志、截图等 -->
--- a/.gitea/ISSUE_TEMPLATE/config.yml
+++ b/.gitea/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,3 @@
+# 工单模板配置：新建工单时可从同目录下 .md 模板中选择
+blank_issues_enabled: true
+contact_links: []
--- a/.gitea/ISSUE_TEMPLATE/任务报备.md
+++ b/.gitea/ISSUE_TEMPLATE/任务报备.md
@@ -0,0 +1,26 @@
+---
+name: 任务报备
+about: 记录计划做或正在做的任务，便于追踪与同步
+title: "[任务] "
+labels: task
+assignees: ""
+---
+
+## 任务目标
+<!-- 要完成什么 -->
+
+## 计划步骤（可选）
+1.
+2.
+3.
+
+## 负责人/角色
+<!-- 卡资/卡人/卡木/卡火/卡土 或 具体成员 -->
+
+## 截止/状态
+- [ ] 待开始
+- [ ] 进行中
+- [ ] 已完成
+
+## 备注
+<!-- 关联的 Skill、文档、分支等 -->
--- a/.gitea/ISSUE_TEMPLATE/功能建议.md
+++ b/.gitea/ISSUE_TEMPLATE/功能建议.md
@@ -0,0 +1,27 @@
+---
+name: 功能建议
+about: 为卡若AI或某 Skill 提出新功能、优化想法
+title: "[功能] "
+labels: enhancement
+assignees: ""
+---
+
+## 功能简述
+<!-- 一句话说明希望增加或改进什么 -->
+
+## 使用场景
+<!-- 在什么情况下会用到 -->
+
+## 期望效果
+<!-- 希望做到什么程度 -->
+
+## 所属板块（可选）
+- [ ] 卡资（金）
+- [ ] 卡人（水）
+- [ ] 卡木（木）
+- [ ] 卡火（火）
+- [ ] 卡土（土）
+- [ ] 共享/规则
+
+## 补充
+<!-- 其他说明 -->
--- a/.gitea/ISSUE_TEMPLATE/默认工单.md
+++ b/.gitea/ISSUE_TEMPLATE/默认工单.md
@@ -0,0 +1,13 @@
+---
+name: 默认工单
+about: 通用工单，不限于功能/Bug/任务
+title: ""
+labels: []
+assignees: ""
+---
+
+## 说明
+<!-- 描述问题或需求 -->
+
+## 补充
+<!-- 其他信息 -->
--- a/.gitea/pull_request_template.md
+++ b/.gitea/pull_request_template.md
@@ -0,0 +1,18 @@
+## 合并说明
+<!-- 简述本 MR 要合并的内容与原因 -->
+
+## 变更类型
+- [ ] Skill/规则 更新
+- [ ] 脚本或文档
+- [ ] 结构/目录调整
+- [ ] 其他
+
+## 关联工单（可选）
+<!-- 如：Closes #1 -->
+
+## 自检
+- [ ] 无 >20MB 大文件
+- [ ] 已本地验证
+
+## 补充
+<!-- 其他说明 -->
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,7 @@ __pycache__/
 .env
 .env.*
 *.log
+sync_tokens.env

 # Node / 前端
 node_modules/
--- a/01_卡资（金）/_团队成员/金仓/群晖NAS管理/references/GitHub与Gitea同步_脚本与钩子规则.md
+++ b/01_卡资（金）/_团队成员/金仓/群晖NAS管理/references/GitHub与Gitea同步_脚本与钩子规则.md
@@ -0,0 +1,87 @@
+# GitHub 与 Gitea 同步：脚本与钩子规则
+
+> **目的**：说清定时脚本与 Web 钩子的关系、是否冲突、最佳用法与固定规则。  
+> **维护**：金仓
+
+---
+
+## 一、脚本 vs 钩子
+
+| 方式 | 触发 | 方向 | 说明 |
+|:-----|:-----|:-----|:-----|
+| **定时脚本**（cron） | 每 30 分钟 | GitHub → Gitea | NAS 上执行 `sync_github_to_gitea.sh`，拉取 GitHub 全仓/指定仓并推送到存客宝 Gitea。 |
+| **GitHub Web 钩子** | GitHub 有 push 时 | GitHub → Gitea | GitHub 向 NAS 上的接收端发 POST，接收端执行同步脚本（实时）。 |
+| **Gitea Web 钩子** | Gitea 有 push 时 | Gitea → 外部 | Gitea 向指定 URL 发 POST（通知用）；若要做 Gitea→GitHub 反向同步，需接收端再推送到 GitHub。 |
+
+---
+
+## 二、是否冲突？结论：不冲突，用锁兜底
+
+- **脚本与 GitHub 钩子**：做的是同一件事（GitHub → Gitea），只是触发不同（定时 vs 事件）。可能同时发生（例如刚 push 完又赶上 cron），**不会逻辑冲突**，但并发跑同一仓库可能造成重复拉取/推送。
+- **处理方式**：同步脚本已加**全局锁**（同一时间只允许一个同步进程）。钩子或 cron 触发时，若脚本已在跑，后到的会等待锁或超时跳过，**不会两个进程同时写同一仓库**。
+- **Gitea 钩子**：若只做「GitHub → Gitea」单向，**不需要在 Gitea 配置钩子**。若要做「Gitea → GitHub」反向，Gitea 钩子只负责「通知接收端」，由接收端去 push 到 GitHub，与脚本（GitHub→Gitea）方向相反，**不冲突**。
+
+---
+
+## 三、最佳方案（推荐）
+
+1. **主向：GitHub → Gitea（实时 + 兜底）**
+   - **实时**：在 **GitHub** 仓库或组织里配置 Web 钩子，Payload URL 指向 NAS 上的 webhook 接收端（需 NAS 有可从外网访问的地址，如 frp）；触发时只同步该仓库（或按约定同步全仓）。
+   - **兜底**：保留 **cron 每 30 分钟** 全量同步，防止钩子漏触发或网络问题。
+   - **规则**：脚本带锁，钩子与 cron 都只调同一脚本，不会并发冲突。
+
+2. **Gitea 钩子（按需）**
+   - 若只需「GitHub 为源、Gitea 为镜像」，**不必在 Gitea 配置钩子**。
+   - 若需「在 Gitea 的修改也推到 GitHub」：
+     - 在 Gitea **用户设置 → Web 钩子** 添加「添加 Web 钩子」；
+     - URL 填接收端地址，触发事件选「推送」等；
+     - 接收端收到后，根据 payload 找到对应仓库并执行 `git push` 到 GitHub（需在接收端配置 GitHub 权限）。
+
+3. **约定规则（固定）**
+   - **源真相**：默认以 **GitHub 为准**，Gitea 为镜像；反向（Gitea→GitHub）仅对明确需要的仓库开启。
+   - **只用一个同步脚本**：所有同步（cron 或钩子触发）都调用 `sync_github_to_gitea.sh`（可带 `--repo xxx`），脚本内用同一把锁。
+   - **不在 Gitea 侧做「镜像仓库」与脚本重复**：若用 Gitea 的「从 URL 迁移/镜像」功能，就不要再对同一仓库用本脚本，二选一，避免双写。
+
+---
+
+## 四、Gitea 上钩子设置（界面说明）
+
+- 打开 **open.quwanzhi.com:3000** → 右上角头像 → **设置** → 左侧 **Web 钩子**。
+- 「添加 Web 钩子」：选类型（如 Gitea 或 HTTP），URL 填你的接收端地址（例如 `http://你的NAS或frp地址:端口/webhook`）。
+- 触发事件：至少勾选「推送」；若需合并请求等再勾选对应项。
+- 说明：此处钩子为**由 Gitea 发出**的通知，用于「Gitea → 外部」（如 Gitea→GitHub 反向同步）；**GitHub → Gitea** 的实时同步是在 **GitHub 侧** 配置钩子指向 NAS 接收端，而不是在 Gitea 配置。
+
+---
+
+## 五、脚本锁规则（实现层面）
+
+- 同步脚本使用**全局锁目录** `$WORK_DIR.lock`（如 `/tmp/github_gitea_sync.lock`），通过 `mkdir` 原子性获取锁。
+- 获取不到锁时，每 5 秒重试，超过 `SYNC_LOCK_WAIT` 秒（默认 300）则退出，不执行本次同步。
+- 脚本正常或异常退出时用 `trap EXIT` 释放锁。
+- **结论**：cron 与 webhook 可同时配置，两者都触发同一脚本，由锁保证同一时刻只跑一个同步，无冲突。
+
+---
+
+## 六、Web 钩子接收端（实时触发同步）
+
+- **位置**：`scripts/webhook_receiver.py`（Python 3，仅标准库）。
+- **在 NAS 上运行**：  
+  `cd /volume1/docker/gitea && nohup python3 webhook_receiver.py >> webhook.log 2>&1 &`  
+  默认监听 **9999** 端口，环境变量 `WEBHOOK_PORT` 可改。
+- **行为**：对任意路径的 **POST**（如 `http://NAS或frp地址:9999/sync`）执行同步；若 body 为 JSON 且含 `repository.name`（GitHub/Gitea 格式），则只同步该仓库，否则全量同步。**GET** `/`、`/sync`、`/health` 返回 200 用于探活。
+- **GitHub 配置**：仓库或组织 → Settings → Webhooks → Add webhook → Payload URL 填 `http://你的NAS公网或frp地址:9999/sync`，Content type 选 `application/json`，事件选 “Just the push event” 即可。
+- **Gitea 配置**（仅当需要 Gitea→GitHub 反向时）：用户设置 → Web 钩子 → 添加 Web 钩子 → URL 填上述地址，触发选「推送」。
+
+---
+
+## 七、相关文件
+
+| 文件 | 说明 |
+|:-----|:-----|
+| `scripts/sync_github_to_gitea.sh` | 带锁的同步脚本，GitHub → Gitea |
+| `scripts/webhook_receiver.py` | NAS 上 Web 钩子接收端（被 GitHub/Gitea 调用） |
+| `references/GitHub全仓同步到CKB_NAS_Gitea_方案与双向说明.md` | 全量同步与部署说明 |
+
+---
+
+*版本：v1.0*
--- a/01_卡资（金）/_团队成员/金仓/群晖NAS管理/references/GitHub全仓同步到CKB_NAS_Gitea_方案与双向说明.md
+++ b/01_卡资（金）/_团队成员/金仓/群晖NAS管理/references/GitHub全仓同步到CKB_NAS_Gitea_方案与双向说明.md
@@ -93,6 +93,7 @@ ssh fnvtk@192.168.1.201 "/bin/bash /volume1/docker/gitea/sync_github_to_gitea.sh
 | `references/CKB_NAS_Gitea_类GitHub访问.md` | Gitea 部署与访问 |
 | `scripts/sync_github_to_gitea.sh` | 全仓/单仓同步（固定推送到存客宝 NAS Gitea） |
 | `scripts/deploy_github_to_gitea_on_nas.sh` | 一键部署到 NAS，从账号索引读 Token，接通 GitHub ↔ Gitea |
+| `references/GitHub与Gitea同步_脚本与钩子规则.md` | 脚本与钩子是否冲突、最佳方案、Gitea 钩子设置与规则 |

 ---

--- a/01_卡资（金）/_团队成员/金仓/群晖NAS管理/scripts/sync_github_to_gitea.sh
+++ b/01_卡资（金）/_团队成员/金仓/群晖NAS管理/scripts/sync_github_to_gitea.sh
@@ -44,6 +44,19 @@ if [ -z "$GITEA_TOKEN" ]; then
  exit 1
 fi

+# 全局锁：避免与 cron、Web 钩子同时触发时并发写同一仓库（二选一：flock 或 mkdir 原子锁）
+LOCK_DIR="${WORK_DIR}.lock"
+LOCK_WAIT="${SYNC_LOCK_WAIT:-300}"
+acquire_lock() {
+  local waited=0
+  while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+    [ $waited -ge "$LOCK_WAIT" ] && { echo "获取锁超时，跳过本次"; exit 0; }
+    sleep 5; waited=$((waited+5))
+  done
+  trap 'rmdir "$LOCK_DIR" 2>/dev/null' EXIT
+}
+acquire_lock
+
 # 列出要同步的仓库名（不依赖 jq，兼容群晖）
 get_repos() {
  if [ -n "$SINGLE_REPO" ]; then
--- a/01_卡资（金）/_团队成员/金仓/群晖NAS管理/scripts/webhook_receiver.py
+++ b/01_卡资（金）/_团队成员/金仓/群晖NAS管理/scripts/webhook_receiver.py
@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# Web 钩子接收端：收到 GitHub 或 Gitea 的 POST 后执行同步脚本（与 cron 共用同一脚本，脚本内带锁不冲突）
+# 在 NAS 上运行：python3 webhook_receiver.py  或 nohup python3 webhook_receiver.py &
+# 需本机或 frp 暴露端口（如 9999），GitHub/Gitea 的 Webhook URL 填 http://你的地址:9999/sync
+# 依赖：Python 3，同目录 sync_github_to_gitea.sh、sync_tokens.env
+
+import json
+import os
+import subprocess
+import sys
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+SYNC_SCRIPT = os.path.join(SCRIPT_DIR, "sync_github_to_gitea.sh")
+PORT = int(os.environ.get("WEBHOOK_PORT", "9999"))
+
+
+class SyncHandler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        repo = None
+        try:
+            length = int(self.headers.get("Content-Length", 0))
+            if length:
+                body = self.rfile.read(length).decode("utf-8", errors="ignore")
+                try:
+                    data = json.loads(body)
+                    # GitHub: repository.name 或 repository.full_name
+                    repo = (data.get("repository") or {}).get("name")
+                    if not repo and data.get("repository", {}).get("full_name"):
+                        repo = data["repository"]["full_name"].split("/")[-1]
+                    # Gitea: repository.name
+                    if not repo:
+                        repo = (data.get("repository") or {}).get("name")
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+        cmd = [SYNC_SCRIPT]
+        if repo:
+            cmd.extend(["--repo", repo])
+        env = os.environ.copy()
+        env["SYNC_WORK_DIR"] = os.environ.get("SYNC_WORK_DIR", "/tmp/github_gitea_sync")
+        subprocess.Popen(
+            ["/bin/bash"] + cmd,
+            cwd=SCRIPT_DIR,
+            env=env,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        self.send_response(200)
+        self.send_header("Content-Type", "text/plain; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(b"ok")
+
+    def do_GET(self):
+        if self.path in ("/", "/sync", "/health"):
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(b"webhook receiver ok")
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def log_message(self, fmt, *args):
+        sys.stderr.write("[webhook] %s\n" % (fmt % args))
+
+
+def main():
+    if not os.path.isfile(SYNC_SCRIPT):
+        sys.stderr.write("sync script not found: %s\n" % SYNC_SCRIPT)
+        sys.exit(1)
+    server = HTTPServer(("", PORT), SyncHandler)
+    sys.stderr.write("webhook receiver listening on port %s (POST /sync or / => run sync)\n" % PORT)
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
--- a/README.md
+++ b/README.md
@@ -0,0 +1,26 @@
+# 卡若AI
+
+卡若的个人数字管家与智能工作台。五行角色（卡资/卡人/卡木/卡火/卡土）管理 38 个 Skill，有更新即同步到本仓库。
+
+---
+
+## 入口
+
+| 入口 | 说明 |
+|:---|:---|
+| **总索引** | [_共享模块/工作台/00_卡若AI总索引.md](_共享模块/工作台/00_卡若AI总索引.md) |
+| **技能主索引** | [_共享模块/skill_router/SKILL.md](_共享模块/skill_router/SKILL.md) |
+| **百科** | 仓库「百科」页（由 `_共享模块/wiki_source/` 同步） |
+| **工单 / 合并请求 / 发布** | [使用说明](_共享模块/references/Gitea_工单与合并请求使用说明.md) |
+
+## 结构概要
+
+```
+01_卡资（金）  02_卡人（水）  03_卡木（木）  04_卡火（火）  05_卡土（土）
+_共享模块      _经验库       _大文件外置（>20MB 不上传）
+```
+
+## 同步
+
+- 本地有更新 → 执行 `bash _共享模块/auto_sync_gitea.sh` 推送到本仓库。
+- 单文件 >20MB 自动排除，不上传。
--- a/_共享模块/references/Gitea_工单与合并请求使用说明.md
+++ b/_共享模块/references/Gitea_工单与合并请求使用说明.md
@@ -0,0 +1,104 @@
+# Gitea 工单、合并请求、百科、版本发布、项目 — 使用说明
+
+> 仓库：http://open.quwanzhi.com:3000/fnvtk/karuo-ai  
+> 本文路径：`_共享模块/references/Gitea_工单与合并请求使用说明.md`
+
+---
+
+## 一、工单（Issues）
+
+### 功能
+- 记录需求、Bug、任务，便于追踪和协作。
+- 新建时可选择模板，规范填写。
+
+### 模板（仓库内已配置）
+| 模板 | 用途 |
+|:---|:---|
+| 功能建议 | 为新功能或优化提想法，可勾选所属板块（金/水/木/火/土） |
+| Bug 反馈 | 反馈错误与异常，填复现步骤与期望/实际行为 |
+| 任务报备 | 记录计划中或进行中的任务，便于同步 |
+| 默认工单 | 通用，自由填写 |
+
+### 操作
+1. 打开仓库 → 点「工单」→「新建工单」
+2. 选择上述任一模板，按项填写后提交。
+
+---
+
+## 二、合并请求（Merge Requests）
+
+### 功能
+- 将分支改动合并进 `main` 前做评审与记录。
+- 可与工单关联（如填写「Closes #1」）。
+
+### 模板（仓库内已配置）
+- 合并说明、变更类型（Skill/规则、脚本、结构等）、关联工单、自检（如无 >20MB 大文件）。
+
+### 操作
+1. 在分支上完成修改并推送到 Gitea
+2. 仓库页「合并请求」→「新建合并请求」，选择分支 → main
+3. 按模板补充说明后创建，审核通过后合并。
+
+---
+
+## 三、百科（Wiki）
+
+### 功能
+- 仓库的说明文档，独立于代码目录，便于在 Gitea 页直接阅读。
+
+### 内容来源与同步
+- **源目录**：`_共享模块/wiki_source/`（Home.md、快速开始、五行角色、技能索引、Gitea使用 等）
+- **同步到 Gitea 百科**：执行  
+  `bash _共享模块/scripts/sync_wiki_to_gitea.sh`  
+  会将上述 Markdown 推送到 Gitea 的「百科」页。
+
+### 操作
+- 改完 `wiki_source/` 后运行上述脚本即可更新线上百科。
+
+---
+
+## 四、版本发布（Releases）
+
+### 功能
+- 为重要节点打 Tag，并写发布说明，便于回溯与分发。
+
+### 脚本（可选）
+```bash
+bash _共享模块/scripts/create_gitea_release.sh [版本号] [说明]
+# 例：bash _共享模块/scripts/create_gitea_release.sh v1.0.0 "首次结构化发布"
+```
+- 会在当前仓库打 tag 并推送到 Gitea，并调用 API 创建/更新 Release。
+- 也可在 Gitea 页「版本发布」中手动新建发布。
+
+---
+
+## 五、项目（Projects）
+
+### 功能
+- 看板：将工单拖入「待办 / 进行中 / 已完成」等列，做任务排期与状态跟踪。
+
+### 操作
+1. 仓库页「项目」→「新建项目」
+2. 添加列（如：待办、进行中、已完成）
+3. 在「工单」中把对应工单关联到项目，并拖到对应列。
+
+---
+
+## 六、软件包（Packages）
+
+### 说明
+- 本仓库以文档与 Skill 为主，一般不使用「软件包」；若后续有需要再配置包类型。
+
+---
+
+## 七、动态（Activity）
+
+### 说明
+- 「动态」页自动展示提交、工单、合并请求等动态，无需额外配置。
+
+---
+
+## 八、界面与优化说明
+
+- **工单 / 合并请求 / 百科 / 发布 / 项目** 的「该有的功能」已通过仓库内模板与脚本配置好，在 Gitea 页可直接使用。
+- **Gitea 站点整体界面**（主题、布局、导航）由 Gitea 服务端与站点管理端配置，本仓库无法修改；若需改主题或菜单，需在 open.quwanzhi.com:3000 的**管理后台**中调整。
--- a/_共享模块/scripts/create_gitea_release.sh
+++ b/_共享模块/scripts/create_gitea_release.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# 在 Gitea 创建版本发布：打 tag 并可选创建 Release 说明
+# 使用：bash _共享模块/scripts/create_gitea_release.sh [版本号] [说明]
+# 例：  bash _共享模块/scripts/create_gitea_release.sh v1.0.0 "首次结构化发布"
+
+set -e
+REPO_DIR="/Users/karuo/Documents/个人/卡若AI"
+GITEA_API="http://open.quwanzhi.com:3000/api/v1"
+AUTH="fnvtk:Zhiqun1984"
+REPO_OWNER="fnvtk"
+REPO_NAME="karuo-ai"
+
+VERSION="${1:-v$(date '+%Y.%m.%d')}"
+NOTES="${2:-卡若AI 版本 $VERSION}"
+
+cd "$REPO_DIR"
+# 确保在 main 并拉取最新
+git checkout main 2>/dev/null || true
+git pull gitea main 2>/dev/null || true
+
+# 打 tag 并推送
+git tag -a "$VERSION" -m "$NOTES" 2>/dev/null || true
+git push gitea "$VERSION" 2>/dev/null || true
+
+# 调用 Gitea API 创建 Release（若 tag 已存在则更新说明）
+curl -s -u "$AUTH" -X POST "$GITEA_API/repos/$REPO_OWNER/$REPO_NAME/releases" \
+  -H "Content-Type: application/json" \
+  -d "{\"tag_name\":\"$VERSION\",\"name\":\"$VERSION\",\"body\":\"$NOTES\"}" 2>/dev/null || \
+curl -s -u "$AUTH" -X PATCH "$GITEA_API/repos/$REPO_OWNER/$REPO_NAME/releases/tags/$VERSION" \
+  -H "Content-Type: application/json" \
+  -d "{\"body\":\"$NOTES\"}" 2>/dev/null || true
+
+echo "已创建/更新发布: $VERSION"
+echo "打开: http://open.quwanzhi.com:3000/fnvtk/karuo-ai/releases"
--- a/_共享模块/scripts/sync_wiki_to_gitea.sh
+++ b/_共享模块/scripts/sync_wiki_to_gitea.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+# 将 _共享模块/wiki_source/ 同步到 Gitea 百科（karuo-ai.wiki）
+# 使用：bash _共享模块/scripts/sync_wiki_to_gitea.sh
+
+set -e
+REPO_DIR="/Users/karuo/Documents/个人/卡若AI"
+WIKI_SRC="$REPO_DIR/_共享模块/wiki_source"
+WIKI_CLONE="$REPO_DIR/_共享模块/.wiki_clone"
+WIKI_REMOTE="http://fnvtk:Zhiqun1984@open.quwanzhi.com:3000/fnvtk/karuo-ai.wiki.git"
+
+cd "$REPO_DIR"
+mkdir -p "$(dirname "$WIKI_CLONE")"
+
+if [ ! -d "$WIKI_CLONE/.git" ]; then
+  rm -rf "$WIKI_CLONE" 2>/dev/null || true
+  git clone "$WIKI_REMOTE" "$WIKI_CLONE"
+fi
+
+cd "$WIKI_CLONE"
+git fetch origin
+git reset --hard origin/master 2>/dev/null || git reset --hard origin/main 2>/dev/null || true
+
+cp -f "$WIKI_SRC"/*.md . 2>/dev/null || true
+git add -A
+if git diff --cached --quiet; then
+  echo "百科无变更，跳过推送。"
+  exit 0
+fi
+git commit -m "百科同步: $(date '+%Y-%m-%d %H:%M')"
+git push origin HEAD
+
+echo "百科已同步到 Gitea → 打开仓库「百科」页查看。"
--- a/_共享模块/wiki_source/Gitea使用.md
+++ b/_共享模块/wiki_source/Gitea使用.md
@@ -0,0 +1,33 @@
+# Gitea 使用说明
+
+仓库地址：**http://open.quwanzhi.com:3000/fnvtk/karuo-ai**
+
+---
+
+## 工单（Issues）
+
+- 新建工单时可选择模板：**功能建议**、**Bug 反馈**、**任务报备**、**默认工单**。
+- 用于需求记录、Bug 跟踪、任务报备与协作。
+
+## 合并请求（Merge Requests）
+
+- 分支改动合并到 `main` 时创建合并请求。
+- 会自动带出合并说明模板，可勾选变更类型、关联工单。
+
+## 版本发布（Releases）
+
+- 在「版本发布」页创建 Tag，可附说明与附件。
+- 脚本：`_共享模块/scripts/create_gitea_release.sh`（可选，用于打 tag + 创建 Release）。
+
+## 项目（Projects）
+
+- 用于看板：待办 / 进行中 / 已完成等。
+- 在 Gitea 页「项目」中新建项目，将工单拖入对应列即可。
+
+## 软件包（Packages）
+
+- 本仓库以文档与 Skill 为主，一般不使用软件包功能；若有发布物可再开包类型。
+
+## 动态（Activity）
+
+- 「动态」页自动展示提交、工单、合并请求等动态，无需配置。
--- a/_共享模块/wiki_source/Home.md
+++ b/_共享模块/wiki_source/Home.md
@@ -0,0 +1,28 @@
+# 卡若AI 百科
+
+卡若的个人数字管家与智能工作台，基于五行角色（卡资/卡人/卡木/卡火/卡土）管理技能与团队。
+
+---
+
+## 快速入口
+
+| 入口 | 说明 |
+|:---|:---|
+| [快速开始](快速开始) | 本地克隆、规则加载、首次同步 |
+| [五行角色](五行角色) | 卡资/卡人/卡木/卡火/卡土 职责与成员 |
+| [技能索引](技能索引) | 38 个 Skill 与触发词 |
+| [Gitea 使用](Gitea使用) | 工单、合并请求、版本发布、项目 |
+
+---
+
+## 仓库结构（概要）
+
+```
+卡若AI/
+├── 01_卡资（金）/  02_卡人（水）/  03_卡木（木）/  04_卡火（火）/  05_卡土（土）/
+├── _共享模块/      # 工作台、skill_router、memory、references
+├── _大文件外置/    # >20MB 文件（不上传）
+└── _经验库/        # 待沉淀、已整理、已转化
+```
+
+详细索引见仓库内：`_共享模块/工作台/00_卡若AI总索引.md`
--- a/_共享模块/wiki_source/五行角色.md
+++ b/_共享模块/wiki_source/五行角色.md
@@ -0,0 +1,18 @@
+# 五行角色
+
+卡若AI 下分五个角色，各管一块，再分配团队成员与技能。
+
+| 角色 | 口头禅 | 核心能力（不下放） | 成员 |
+|:---|:---|:---|:---|
+| **卡资（金）** | 稳了。 | 基础设施巡检、风险预警、应急响应 | 金剑、金盾、金仓、金链 |
+| **卡人（水）** | 搞定了，清清爽爽。 | 信息流程设计、跨团队协调、任务追踪 | 水溪、水泉、水桥 |
+| **卡木（木）** | 搞起！ | 产品原型设计、内容质量把控、快速迭代 | 木叶、木根、木果 |
+| **卡火（火）** | 让我想想... | 技术决策、代码评审、技术攻关 | 火炬、火锤、火眼、火种 |
+| **卡土（土）** | 先算账。 | 商业决策、ROI 分析、战略规划 | 土基、土砖、土渠 |
+
+各角色详细人设与技能分配见各目录下 `README.md`：
+- `01_卡资（金）/README.md`
+- `02_卡人（水）/README.md`
+- `03_卡木（木）/README.md`
+- `04_卡火（火）/README.md`
+- `05_卡土（土）/README.md`
--- a/_共享模块/wiki_source/快速开始.md
+++ b/_共享模块/wiki_source/快速开始.md
@@ -0,0 +1,28 @@
+# 快速开始
+
+## 1. 克隆仓库
+
+```bash
+git clone http://fnvtk:Zhiqun1984@open.quwanzhi.com:3000/fnvtk/karuo-ai.git
+cd karuo-ai
+```
+
+## 2. 规则与技能
+
+- **Cursor 规则**：`.cursor/rules/karuo-ai.mdc`（对话时自动加载）
+- **技能主索引**：`_共享模块/skill_router/SKILL.md`
+- **总索引**：`_共享模块/工作台/00_卡若AI总索引.md`
+
+## 3. 同步到 Gitea（有更新就上传）
+
+```bash
+bash _共享模块/auto_sync_gitea.sh
+```
+
+- 单文件 >20MB 会自动排除，不上传。
+- 推送记录：`_共享模块/工作台/gitea_push_log.md`
+
+## 4. 大文件规则
+
+- Skill 目录下禁止放超过 20MB 的文件。
+- 大文件统一放到 `_大文件外置/`，参见其内 `README.md`。
--- a/_共享模块/wiki_source/技能索引.md
+++ b/_共享模块/wiki_source/技能索引.md
@@ -0,0 +1,11 @@
+# 技能索引（概要）
+
+共 **38 个 Skill**，按五行角色归属；触发词匹配后读对应 `SKILL.md` 执行。
+
+- **卡资（金）**：12 个 — 服务器、NAS、磁盘、备份、iPhone、iCloud、微信、数据库、照片、容灾、局域网等
+- **卡人（水）**：9 个 — 飞书、智能纪要、小程序、需求拆解、任务规划、文件整理、文档清洗、对话归档、记忆管理
+- **卡木（木）**：5 个 — 视频切片、网站逆向、项目生成、开发模板、个人档案生成器
+- **卡火（火）**：6 个 — 全栈开发、消息中枢、代码修复、智能追问、读书笔记、本地模型
+- **卡土（土）**：6 个 — 商业工具集、云阿米巴、技能工厂、流量自动化、手机流量自动操作、招商运营
+
+完整路径与触发词见仓库内：`_共享模块/skill_router/SKILL.md`。
--- a/_共享模块/工作台/gitea_push_log.md
+++ b/_共享模块/工作台/gitea_push_log.md
@@ -5,3 +5,4 @@

 | 时间 | 提交说明 |
 |:---|:---|
+| 2026-02-15 23:09:40 | 🔄 卡若AI 同步 2026-02-15 23:09 | 变更 5 个文件 | 排除 >20MB: 4 个 |