feat: export core Hermes skills

2026-07-15 02:45:56 +00:00
parent a028b63eda
commit 54711fee2a
308 changed files with 41310 additions and 1 deletions
@@ -0,0 +1,76 @@
+# Nextcloud File Upload Diagnostics
+
+When files appear visible in the Nextcloud web UI but `find` on the container filesystem returns nothing, use this diagnostic sequence.
+
+## Step 1: Check physical filesystem
+```bash
+docker exec <container> find '<nc_data_path>/<dir>' -type f -exec ls -la {} \;
+```
+Look for `.part` and `.ocTransferId*` files — these are incomplete upload fragments.
+
+## Step 2: Rescan
+```bash
+docker exec -u www-data <container> php occ files:scan admin --path='<path>'
+```
+
+## Step 3: Check Nextcloud logs
+```bash
+docker exec <container> tail -20 /var/www/html/data/nextcloud.log | python3 -c "
+import sys, json
+for line in sys.stdin:
+    try:
+        d = json.loads(line.strip())
+        if d.get('level', 0) >= 2:
+            print(f'[{d.get(\"time\",\"?\")}] {d.get(\"message\",\"\")[:300]}')
+    except: pass
+"
+```
+Upload failures show: "预期文件大小为 X字节，实际...写入...Y字节"
+
+## Step 4: Query MariaDB directly
+Find the DB password first:
+```bash
+docker exec <container> grep dbpassword /var/www/html/config/config.php
+```
+
+Then query (use `mariadb` client, not `mysql`):
+```bash
+docker exec nextcloud-db-1 mariadb -u nextcloud -p<DB_PASSWORD_FROM_CONFIG> nextcloud -e "
+SELECT f.fileid, f.path, f.name, f.size, FROM_UNIXTIME(f.mtime) as modified
+FROM oc_filecache f 
+WHERE f.path LIKE '%<search_term>%'
+ORDER BY f.path;
+"
+```
+
+To find children of a directory (by parent fileid):
+```bash
+... -e "SELECT f.fileid, f.parent, f.path, f.name, f.size
+FROM oc_filecache f WHERE f.parent IN (<parent_id1>, <parent_id2>);"
+```
+
+## Step 5: Clean up fragments
+```bash
+docker exec <container> find '<path>' -name '*.part' -delete
+docker exec <container> find '<path>' -name '*.ocTransferId*' -delete
+```
+
+## Common root cause
+Cloudflare Tunnel (free tier) truncates large file uploads. The Nextcloud chunked upload protocol partially writes, then the connection drops. Repeated retries produce the same result.
+
+**Solution**: Receive files via alternate channel (WeChat private message → `~/.hermes/cache/documents/`) and `docker cp` into Nextcloud.
+
+## Quirk: docker cp'd file present + md5 correct, but `files:scan` returns 0 and DB row missing (2026-06-17)
+
+After `docker cp` + `chown www-data` a new xlsx, `php occ files:scan admin --path='小Maggie协作区/.../世茂'` returned all-zeros (`Folders 0 Files 0`) and `oc_filecache` had **no row** for the file — so it was invisible in the web UI despite physically existing with a correct md5.
+
+**Root cause**: `files:scan` keys off directory mtime; a fresh `docker cp` into an existing dir doesn't always bump the parent mtime, so the scanner skips it.
+
+**Fix** (verified):
+```bash
+# 1. touch the parent dir to force an mtime change
+docker exec <container> bash -c "touch '/var/www/html/data/admin/files/<REL_PATH>'"
+# 2. rescan using the admin/files/ prefixed --path form (not the bare share path)
+docker exec -u www-data <container> php occ files:scan --path="admin/files/<REL_PATH>"
+```
+This returns `Updated N` and registers the file. **Always verify after upload** by querying `oc_filecache` for the filename (Step 4) — md5 match alone does NOT prove the file is indexed/visible. Don't tell the user "uploaded" until the DB row exists.