Document agent secret vault installation

docs/human-guide.md

@@ -0,0 +1,170 @@
+# 人類使用指南：agent-secret-vault
+
+這份文件給人類維護者看：如何安裝、操作，以及如何用自然語言指示 agent 管理 secrets。
+
+## 這是什麼
+
+`agent-secret-vault` 是本地 AI agent 共用的機密資料 repo。
+
+- 加密資料：`secrets/vault.yml`
+- 加密格式：Ansible Vault
+- 解密鑰匙：`~/.config/vault-pass.txt`
+- Repo：`ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git`
+
+`secrets/vault.yml` 可以進 git；`~/.config/vault-pass.txt` 不可以進 git。
+
+## 安裝
+
+```bash
+sudo apt update
+sudo apt install -y git ansible unzip
+
+mkdir -p ~/projects
+cd ~/projects
+git clone ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git
+cd agent-secret-vault
+```
+
+接著安裝 vault password file：
+
+```bash
+./scripts/install-vault-pass.sh
+```
+
+這會從 repo 內的密碼保護壓縮檔解出：
+
+```text
+~/.config/vault-pass.txt
+```
+
+過程中需要你手動輸入壓縮檔密碼。
+
+驗證：
+
+```bash
+./scripts/vault.sh view
+```
+
+## 建立安裝用密碼保護壓縮檔
+
+維護者若要讓其他 agent / 機器安裝，先在已可解密的機器上執行：
+
+```bash
+cd ~/projects/agent-secret-vault
+./scripts/create-vault-pass-archive.sh
+git add secrets/vault-pass.txt.zip
+git commit -m "Add vault password archive"
+git push
+```
+
+腳本會要求互動輸入 zip 密碼。這個 zip 密碼不要寫進 repo、chat 或 log；交給安裝者時用另外的安全渠道。
+
+## 常用人工操作
+
+### 查看 vault
+
+```bash
+cd ~/projects/agent-secret-vault
+./scripts/vault.sh view
+```
+
+### 編輯 vault
+
+```bash
+cd ~/projects/agent-secret-vault
+git pull --ff-only
+./scripts/vault.sh edit
+git add secrets/vault.yml
+git commit -m "Update secrets"
+git push
+```
+
+### 讀單一 secret
+
+```bash
+./scripts/get-secret.sh gitea.api_token
+./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
+```
+
+## 用自然語言請 agent 操作 secrets
+
+你可以直接對 agent 下這類命令：
+
+### 查詢但不要顯示 secret
+
+```text
+幫我確認 agent-secret-vault 裡有沒有 gitea.api_token，不要把 token 印出來。
+```
+
+Agent 應該只回報「有 / 沒有」與使用的 key path，不應顯示 token。
+
+### 使用 secret 去登入或呼叫 API
+
+```text
+用 agent-secret-vault 裡的 openclaw_alice.http_nodes.gitea 帳密登入 Gitea，登入成功後回報狀態，不要把帳密貼出來。
+```
+
+Agent 可以讀取 secret 並用於 browser/API，但不能把 secret value 回傳聊天。
+
+### 新增 secret
+
+```text
+幫我把新的 API token 加到 agent-secret-vault，key 放在 openclaw_alice.http_nodes.example_service.api_token；先 git pull，更新後驗證可讀，再 commit/push。不要在回報中顯示 token。
+```
+
+如果 token 需要由你提供，請用安全渠道或互動輸入；不要把高敏感 token 直接貼到公開群組。
+
+### 修改 secret
+
+```text
+把 agent-secret-vault 裡 openclaw_alice.http_nodes.gitea.password 更新成我等一下提供的新密碼；完成後只回報 commit hash 和驗證方式。
+```
+
+### 列出 key 結構
+
+```text
+列出 agent-secret-vault 目前有哪些 top-level sections 和 key 名稱，不要顯示任何 password/token/secret/private_key 的值。
+```
+
+## Agent 應遵守的回報格式
+
+完成更新後，agent 回報應包含：
+
+- 更新的 key path
+- repo path
+- commit hash
+- 驗證方式，例如 `./scripts/get-secret.sh <key>` 成功
+
+不應包含：
+
+- secret value
+- vault password
+- 解密後完整 YAML
+
+## 故障排除
+
+### `Decryption failed`
+
+通常是 `~/.config/vault-pass.txt` 不存在、權限不對、或內容不是正確密碼。
+
+檢查：
+
+```bash
+ls -l ~/.config/vault-pass.txt
+```
+
+權限應為 `600`。
+
+### `secrets/vault-pass.txt.zip` 不存在
+
+代表 repo 裡沒有安裝用的密碼保護壓縮檔。請由維護者建立並提交到私有 repo，或用其他安全方式提供 vault password file。
+
+### Gitea clone/push 失敗
+
+檢查：
+
+```bash
+ssh -T -p 2203 git@gitea.cowbay.org
+```
+
+通常需要把該機器的 SSH public key 加到 Gitea。