redbeacon 0.1.0__tar.gz

redbeacon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 djw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

redbeacon-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: redbeacon
+Version: 0.1.0
+Summary: RedBeacon — 小红书自动化 CLI（生成 / 审核 / 发布 / 多账号）
+Author: djw
+License: MIT
+Project-URL: Homepage, https://github.com/jidouqie/redbeacon
+Project-URL: Issues, https://github.com/jidouqie/redbeacon/issues
+Keywords: xiaohongshu,redbook,automation,cli,claude-code,skill
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: playwright>=1.44.0
+Requires-Dist: cloakbrowser>=0.3.30
+Requires-Dist: markdown>=3.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# redbeacon — 小红书自动化 CLI
+
+把"选好题"以外的事全部交给 CLI：AI 生成文案 + 渲图 / 出图 → 审核 → 多账号发布 → 排期 → 选题库管理。所有命令都是 JSON in / JSON out，方便接入任何 agent、脚本、CI。
+
+主要被 [`redbeacon-skill`](https://github.com/jidouqie/redbeacon-skill)（Claude Code skill 封装）调用，但完全可以独立用。
+
+---
+
+## 安装
+
+```bash
+# 推荐：pipx 隔离环境
+pipx install redbeacon
+
+# 或者直接 pip
+pip install redbeacon
+
+# Playwright 渲图引擎（图文卡片用）
+playwright install chromium
+
+# 校验
+redbeacon --version
+```
+
+> CloakBrowser 的 stealth Chromium 在首次跑 `redbeacon login start` 时自动下载到 `~/.cloakbrowser/`（约 200MB），不用手动装。
+
+依赖：Python ≥ 3.11。
+
+---
+
+## 30 秒看懂
+
+```bash
+redbeacon readiness                   # 入口：看现在缺什么配
+redbeacon config set ai_api_key sk-…  # 配 AI Key
+redbeacon accounts create             # 建第 1 个小红书账号（id=1）
+redbeacon login start --account-id 1  # 阻塞 + 弹浏览器扫码
+redbeacon generate --account-id 1 --image-mode cards   # 生成一篇
+redbeacon content list --account-id 1 --status pending_review
+redbeacon content approve --account-id 1 --id 1        # 本地审核
+redbeacon publish --account-id 1                       # 发布
+```
+
+每个命令成功 → exit 0 + stdout 一行 JSON；失败 → exit ≠0 + stderr `{"error", "next"}`。
+
+---
+
+## 命令总览
+
+| 子命令 | 说明 |
+|---|---|
+| `redbeacon readiness` | 配置完整度 + 引导下一步 |
+| `redbeacon status` | 账号 / 内容计数 / 路径总览 |
+| `redbeacon accounts <list\|get\|create\|delete\|patch>` | 账号 CRUD |
+| `redbeacon login <start\|verify\|status\|delete>` | 小红书登录（CloakBrowser） |
+| `redbeacon config <list\|get\|set\|models\|test-ai\|test-feishu\|feishu-users>` | 配置管理 |
+| `redbeacon strategy <get\|patch>` | 账号定位 / 调性 / 提示词 |
+| `redbeacon topics <list\|add\|batch\|inspire\|stats\|reset\|types\|types-init>` | 选题库 |
+| `redbeacon content <list\|get\|approve\|reject\|edit\|feishu-push>` | 内容审核 |
+| `redbeacon generate --account-id N [--topic …] [--image-mode cards\|ai\|both]` | AI 生成（阻塞） |
+| `redbeacon publish --account-id N` | 发布（飞书源 / 本地源自动判断，阻塞） |
+| `redbeacon feishu <sync\|setup\|test>` | 飞书多维表格 |
+| `redbeacon logs [--tail 150]` | 看日志 |
+
+`redbeacon --help` / `redbeacon <子命令> --help` 看完整参数。
+
+---
+
+## 数据位置
+
+| 路径 | 内容 |
+|---|---|
+| `~/.redbeacon/data/redbeacon.db` | SQLite 主库 |
+| `~/.redbeacon/data/cb_profiles/{id}/` | 每账号 CloakBrowser profile（含 cookie） |
+| `~/.redbeacon/data/images/` | 生成的图片 |
+| `~/.redbeacon/logs/redbeacon.log` | 运行日志 |
+| `~/.cloakbrowser/chromium-*/` | stealth Chromium |
+
+环境变量覆盖：`REDBEACON_DATA_DIR` / `REDBEACON_LOG_DIR`。
+
+跑 `redbeacon status` 看当前实际路径。
+
+---
+
+## 输出契约
+
+- 默认：`{"key": "value", ...}` 一行 JSON
+- TTY 下自动 indent=2 可读；强制覆盖：`REDBEACON_OUT=pretty` / `REDBEACON_OUT=compact`
+- 错误：stderr `{"error": "...", "next": "redbeacon <修复命令>"}`
+
+完整 schema 定义在 `src/redbeacon/schemas.py`（TypedDict）。
+
+---
+
+## 开发
+
+```bash
+git clone https://github.com/jidouqie/redbeacon-cli.git
+cd redbeacon-cli
+
+pip install -e .[dev]
+
+# 测试
+pytest tests/
+
+# 本地跑
+redbeacon --version
+REDBEACON_DATA_DIR=/tmp/rb_dev redbeacon readiness
+```
+
+代码结构：
+
+```
+src/redbeacon/
+├── cli.py            # argparse 入口 + dispatch
+├── config.py         # settings 表读写（加密支持）
+├── config_keys.py    # 所有 settings key 集中定义
+├── database.py       # SQLite 初始化 + migrate
+├── schemas.py        # 输出 TypedDict
+├── render_xhs_v2.py  # 图文卡片渲染（Playwright）
+├── routers/          # 子命令处理（accounts / login / config / publish ...）
+├── services/
+│   ├── xhs/          # CloakBrowser 集成（session/login/publish）
+│   ├── feishu_api.py
+│   ├── image_gen.py
+│   └── proxy_service.py
+├── tasks/            # 复杂业务编排（generate / publish / feishu_sync）
+└── utils/            # logger / crypto / paths
+```
+
+加新命令：在 `routers/` 下加文件 + 在 `cli.py:_build_parser` 和 `_DISPATCH` 注册即可。
+
+---
+
+## License
+
+MIT。详见 [LICENSE](LICENSE)。

redbeacon-0.1.0/README.md

@@ -0,0 +1,137 @@
+# redbeacon — 小红书自动化 CLI
+
+把"选好题"以外的事全部交给 CLI：AI 生成文案 + 渲图 / 出图 → 审核 → 多账号发布 → 排期 → 选题库管理。所有命令都是 JSON in / JSON out，方便接入任何 agent、脚本、CI。
+
+主要被 [`redbeacon-skill`](https://github.com/jidouqie/redbeacon-skill)（Claude Code skill 封装）调用，但完全可以独立用。
+
+---
+
+## 安装
+
+```bash
+# 推荐：pipx 隔离环境
+pipx install redbeacon
+
+# 或者直接 pip
+pip install redbeacon
+
+# Playwright 渲图引擎（图文卡片用）
+playwright install chromium
+
+# 校验
+redbeacon --version
+```
+
+> CloakBrowser 的 stealth Chromium 在首次跑 `redbeacon login start` 时自动下载到 `~/.cloakbrowser/`（约 200MB），不用手动装。
+
+依赖：Python ≥ 3.11。
+
+---
+
+## 30 秒看懂
+
+```bash
+redbeacon readiness                   # 入口：看现在缺什么配
+redbeacon config set ai_api_key sk-…  # 配 AI Key
+redbeacon accounts create             # 建第 1 个小红书账号（id=1）
+redbeacon login start --account-id 1  # 阻塞 + 弹浏览器扫码
+redbeacon generate --account-id 1 --image-mode cards   # 生成一篇
+redbeacon content list --account-id 1 --status pending_review
+redbeacon content approve --account-id 1 --id 1        # 本地审核
+redbeacon publish --account-id 1                       # 发布
+```
+
+每个命令成功 → exit 0 + stdout 一行 JSON；失败 → exit ≠0 + stderr `{"error", "next"}`。
+
+---
+
+## 命令总览
+
+| 子命令 | 说明 |
+|---|---|
+| `redbeacon readiness` | 配置完整度 + 引导下一步 |
+| `redbeacon status` | 账号 / 内容计数 / 路径总览 |
+| `redbeacon accounts <list\|get\|create\|delete\|patch>` | 账号 CRUD |
+| `redbeacon login <start\|verify\|status\|delete>` | 小红书登录（CloakBrowser） |
+| `redbeacon config <list\|get\|set\|models\|test-ai\|test-feishu\|feishu-users>` | 配置管理 |
+| `redbeacon strategy <get\|patch>` | 账号定位 / 调性 / 提示词 |
+| `redbeacon topics <list\|add\|batch\|inspire\|stats\|reset\|types\|types-init>` | 选题库 |
+| `redbeacon content <list\|get\|approve\|reject\|edit\|feishu-push>` | 内容审核 |
+| `redbeacon generate --account-id N [--topic …] [--image-mode cards\|ai\|both]` | AI 生成（阻塞） |
+| `redbeacon publish --account-id N` | 发布（飞书源 / 本地源自动判断，阻塞） |
+| `redbeacon feishu <sync\|setup\|test>` | 飞书多维表格 |
+| `redbeacon logs [--tail 150]` | 看日志 |
+
+`redbeacon --help` / `redbeacon <子命令> --help` 看完整参数。
+
+---
+
+## 数据位置
+
+| 路径 | 内容 |
+|---|---|
+| `~/.redbeacon/data/redbeacon.db` | SQLite 主库 |
+| `~/.redbeacon/data/cb_profiles/{id}/` | 每账号 CloakBrowser profile（含 cookie） |
+| `~/.redbeacon/data/images/` | 生成的图片 |
+| `~/.redbeacon/logs/redbeacon.log` | 运行日志 |
+| `~/.cloakbrowser/chromium-*/` | stealth Chromium |
+
+环境变量覆盖：`REDBEACON_DATA_DIR` / `REDBEACON_LOG_DIR`。
+
+跑 `redbeacon status` 看当前实际路径。
+
+---
+
+## 输出契约
+
+- 默认：`{"key": "value", ...}` 一行 JSON
+- TTY 下自动 indent=2 可读；强制覆盖：`REDBEACON_OUT=pretty` / `REDBEACON_OUT=compact`
+- 错误：stderr `{"error": "...", "next": "redbeacon <修复命令>"}`
+
+完整 schema 定义在 `src/redbeacon/schemas.py`（TypedDict）。
+
+---
+
+## 开发
+
+```bash
+git clone https://github.com/jidouqie/redbeacon-cli.git
+cd redbeacon-cli
+
+pip install -e .[dev]
+
+# 测试
+pytest tests/
+
+# 本地跑
+redbeacon --version
+REDBEACON_DATA_DIR=/tmp/rb_dev redbeacon readiness
+```
+
+代码结构：
+
+```
+src/redbeacon/
+├── cli.py            # argparse 入口 + dispatch
+├── config.py         # settings 表读写（加密支持）
+├── config_keys.py    # 所有 settings key 集中定义
+├── database.py       # SQLite 初始化 + migrate
+├── schemas.py        # 输出 TypedDict
+├── render_xhs_v2.py  # 图文卡片渲染（Playwright）
+├── routers/          # 子命令处理（accounts / login / config / publish ...）
+├── services/
+│   ├── xhs/          # CloakBrowser 集成（session/login/publish）
+│   ├── feishu_api.py
+│   ├── image_gen.py
+│   └── proxy_service.py
+├── tasks/            # 复杂业务编排（generate / publish / feishu_sync）
+└── utils/            # logger / crypto / paths
+```
+
+加新命令：在 `routers/` 下加文件 + 在 `cli.py:_build_parser` 和 `_DISPATCH` 注册即可。
+
+---
+
+## License
+
+MIT。详见 [LICENSE](LICENSE)。

redbeacon-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "redbeacon"
+version = "0.1.0"
+description = "RedBeacon — 小红书自动化 CLI（生成 / 审核 / 发布 / 多账号）"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "djw" }]
+keywords = ["xiaohongshu", "redbook", "automation", "cli", "claude-code", "skill"]
+
+dependencies = [
+    "pydantic>=2.0.0",
+    "cryptography>=42.0.0",
+    "requests>=2.31.0",
+    "httpx>=0.27.0",
+    "openai>=1.30.0",
+    "playwright>=1.44.0",
+    "cloakbrowser>=0.3.30",
+    "markdown>=3.6",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+redbeacon = "redbeacon.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jidouqie/redbeacon"
+Issues   = "https://github.com/jidouqie/redbeacon/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["redbeacon*"]
+
+[tool.setuptools.package-data]
+redbeacon = ["py.typed"]

redbeacon-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

redbeacon-0.1.0/src/redbeacon/__init__.py

@@ -0,0 +1,5 @@
+"""RedBeacon — 小红书自动化 CLI。
+
+入口：`redbeacon` 命令（pyproject.toml 声明），实现在 redbeacon.cli:main。
+"""
+__version__ = "0.1.0"

redbeacon-0.1.0/src/redbeacon/cli.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""RedBeacon CLI — skill 入口。
+
+约定：
+  - 成功：exit 0 + stdout JSON
+  - 失败：exit ≠0 + stderr {"error": str}
+  - 输出 shape 见 redbeacon.schemas
+  - 子命令实现在 redbeacon.routers.<feature>
+
+新增子命令：在 routers/ 下加文件 + 在 _build_parser/_DISPATCH 注册即可。
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from redbeacon import __version__
+from redbeacon.utils.paths import default_data_dir, default_log_dir
+
+DATA_DIR = str(os.environ.get("REDBEACON_DATA_DIR", default_data_dir()))
+LOG_DIR  = str(os.environ.get("REDBEACON_LOG_DIR",  default_log_dir()))
+
+from redbeacon.utils.logger import init_logger
+from redbeacon import database
+
+init_logger(LOG_DIR)
+database.init_db(DATA_DIR)
+
+from redbeacon.routers import (
+    accounts as r_accounts,
+    login as r_login,
+    strategy as r_strategy,
+    topics as r_topics,
+    content as r_content,
+    generate as r_generate,
+    publish as r_publish,
+    feishu as r_feishu,
+    config as r_config,
+    status as r_status,
+    logs as r_logs,
+    readiness as r_readiness,
+)
+
+
+# ── CLI Parser ────────────────────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="redbeacon", description="RedBeacon CLI — 小红书自动化")
+    p.add_argument("--version", action="version", version=f"redbeacon {__version__}")
+    sp = p.add_subparsers(dest="cmd", required=True)
+
+    # accounts
+    acc = sp.add_parser("accounts")
+    acc_sp = acc.add_subparsers(dest="sub", required=True)
+    acc_sp.add_parser("list")
+    _add_account_arg(acc_sp.add_parser("get"))
+    acc_sp.add_parser("create")
+    _add_account_arg(acc_sp.add_parser("delete"))
+    acc_pat = acc_sp.add_parser("patch")
+    _add_account_arg(acc_pat)
+    acc_pat.add_argument("--data", required=True, help='JSON: {"field": "value"}')
+
+    # login
+    login = sp.add_parser("login")
+    login_sp = login.add_subparsers(dest="sub", required=True)
+    for sub in ("start", "verify", "status", "delete"):
+        _add_account_arg(login_sp.add_parser(sub))
+
+    # strategy
+    strat = sp.add_parser("strategy")
+    strat_sp = strat.add_subparsers(dest="sub", required=True)
+    _add_account_arg(strat_sp.add_parser("get"))
+    sp2 = strat_sp.add_parser("patch")
+    _add_account_arg(sp2)
+    sp2.add_argument("--data", required=True, help='JSON: {"field": "value"}')
+
+    # topics
+    top = sp.add_parser("topics")
+    top_sp = top.add_subparsers(dest="sub", required=True)
+    tl = top_sp.add_parser("list")
+    _add_account_arg(tl)
+    tl.add_argument("--type", default=None)
+    tl.add_argument("--used", type=int, default=None)
+    tl.add_argument("--limit", type=int, default=100)
+    tl.add_argument("--offset", type=int, default=0)
+    ta = top_sp.add_parser("add"); _add_account_arg(ta)
+    ta.add_argument("--content", required=True)
+    ta.add_argument("--type", required=True)
+    tb = top_sp.add_parser("batch"); _add_account_arg(tb)
+    tb.add_argument("--type", required=True)
+    tb.add_argument("--text", default=None, help="换行分隔的选题，不传则从 stdin 读取")
+    ti = top_sp.add_parser("inspire"); _add_account_arg(ti)
+    ti.add_argument("--text", required=True)
+    _add_account_arg(top_sp.add_parser("stats"))
+    tr = top_sp.add_parser("reset"); _add_account_arg(tr)
+    tr.add_argument("--type", default=None)
+    _add_account_arg(top_sp.add_parser("types"))
+    _add_account_arg(top_sp.add_parser("types-init"))
+
+    # content
+    cont = sp.add_parser("content")
+    cont_sp = cont.add_subparsers(dest="sub", required=True)
+    cl = cont_sp.add_parser("list"); _add_account_arg(cl)
+    cl.add_argument("--status", default=None)
+    cl.add_argument("--limit", type=int, default=20)
+    cl.add_argument("--offset", type=int, default=0)
+    for sub in ("get", "approve", "reject", "edit"):
+        s = cont_sp.add_parser(sub); _add_account_arg(s)
+        s.add_argument("--id", type=int, required=True)
+        if sub == "reject":
+            s.add_argument("--comment", default="")
+        elif sub == "edit":
+            s.add_argument("--title", default=None)
+            s.add_argument("--body", default=None)
+            s.add_argument("--tags", default=None, help='JSON array: ["#tag1","#tag2"]')
+    cont_sp.add_parser("feishu-push")
+
+    # generate
+    gen = sp.add_parser("generate"); _add_account_arg(gen)
+    gen.add_argument("--topic", default=None)
+    gen.add_argument("--image-mode", default=None, dest="image_mode",
+                     choices=["cards", "ai", "both"])
+    gen.add_argument("--content-type", default=None, dest="content_type")
+    gen.add_argument("--pillar", default=None)
+
+    # publish
+    _add_account_arg(sp.add_parser("publish"))
+
+    # feishu
+    fei = sp.add_parser("feishu")
+    fei_sp = fei.add_subparsers(dest="sub", required=True)
+    fs = fei_sp.add_parser("sync")
+    fs.add_argument("--account-id", type=int, default=None, dest="account_id")
+    fsu = fei_sp.add_parser("setup"); _add_account_arg(fsu)
+    fsu.add_argument("--app-token", default=None, dest="app_token")
+    fsu.add_argument("--table-id", default=None, dest="table_id")
+    _add_account_arg(fei_sp.add_parser("test"))
+
+    # config
+    conf = sp.add_parser("config")
+    conf_sp = conf.add_subparsers(dest="sub", required=True)
+    cg = conf_sp.add_parser("get"); cg.add_argument("key")
+    cs = conf_sp.add_parser("set"); cs.add_argument("key"); cs.add_argument("value")
+    for sub in ("list", "models", "test-ai", "test-feishu", "feishu-users"):
+        conf_sp.add_parser(sub)
+
+    # readiness / status / logs
+    sp.add_parser("readiness")
+    sp.add_parser("status")
+    log_p = sp.add_parser("logs")
+    log_p.add_argument("--tail", type=int, default=150)
+
+    return p
+
+
+def _add_account_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--account-id", type=int, required=True, dest="account_id")
+
+
+# ── Dispatch ──────────────────────────────────────────────────────────────────
+
+_DISPATCH = {
+    "accounts": r_accounts.dispatch,
+    "login":    r_login.dispatch,
+    "strategy": r_strategy.dispatch,
+    "topics":   r_topics.dispatch,
+    "content":  r_content.dispatch,
+    "generate": r_generate.dispatch,
+    "publish":  r_publish.dispatch,
+    "feishu":   r_feishu.dispatch,
+    "config":   r_config.dispatch,
+    "status":   r_status.dispatch,
+    "logs":     r_logs.dispatch,
+    "readiness": r_readiness.dispatch,
+}
+
+
+def main():
+    args = _build_parser().parse_args()
+    fn = _DISPATCH.get(args.cmd)
+    if fn is None:
+        import json
+        print(json.dumps({"error": f"未知命令：{args.cmd}"}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)
+    fn(args)
+
+
+if __name__ == "__main__":
+    main()

redbeacon-0.1.0/src/redbeacon/config.py

@@ -0,0 +1,102 @@
+"""全局配置读写（settings 表）。
+
+支持两种 key 形态：
+  - 字符串："ai_api_key"
+  - Key 常量：config_keys.CK_AI_API_KEY（推荐，附带默认值、加密标志）
+
+敏感字段（is encrypted=True）写入时自动加密，读取时自动解密。
+"""
+from __future__ import annotations
+
+import logging
+from typing import Union
+
+from redbeacon.database import conn
+from redbeacon.utils.crypto import encrypt, decrypt
+from redbeacon.config_keys import Key, ENCRYPTED_KEY_NAMES, ALL_KEYS
+
+_log = logging.getLogger("config")
+
+KeyArg = Union[str, Key]
+
+
+def _name_and_default(key: KeyArg, default: str) -> tuple[str, str]:
+    if isinstance(key, Key):
+        return key.name, (default if default else key.default)
+    return key, default
+
+
+def get(key: KeyArg, default: str = "") -> str:
+    name, default = _name_and_default(key, default)
+    c = conn()
+    row = c.execute(
+        "SELECT value, is_encrypted FROM settings WHERE key=?", (name,)
+    ).fetchone()
+    c.close()
+    if row is None:
+        return default
+    value = row["value"]
+    if row["is_encrypted"] and value:
+        try:
+            value = decrypt(value)
+        except Exception:
+            _log.warning(
+                "配置项 '%s' 解密失败（可能是机器迁移导致密钥不匹配），"
+                "请重新保存该字段", name,
+            )
+            c2 = conn()
+            c2.execute(
+                "UPDATE settings SET value='', updated_at=datetime('now') WHERE key=?",
+                (name,),
+            )
+            c2.commit()
+            c2.close()
+            return default
+    return value
+
+
+def set(key: KeyArg, value: str) -> None:
+    name = key.name if isinstance(key, Key) else key
+    is_enc = 1 if name in ENCRYPTED_KEY_NAMES else 0
+    stored = encrypt(value) if is_enc and value else value
+    c = conn()
+    c.execute(
+        """INSERT INTO settings (key, value, is_encrypted, updated_at)
+           VALUES (?, ?, ?, datetime('now'))
+           ON CONFLICT(key) DO UPDATE SET
+               value=excluded.value,
+               is_encrypted=excluded.is_encrypted,
+               updated_at=excluded.updated_at""",
+        (name, stored, is_enc),
+    )
+    c.commit()
+    c.close()
+
+
+_SENTINEL = "__SET__"   # 表示"已设置但不回传明文"
+
+
+def get_all_public() -> dict:
+    """返回所有配置；加密字段已设置则返回哨兵值 __SET__，未设置或解密失败返回 ""。"""
+    c = conn()
+    rows = c.execute("SELECT key, value, is_encrypted FROM settings").fetchall()
+    c.close()
+    result: dict[str, str] = {}
+    for r in rows:
+        if r["is_encrypted"]:
+            if not r["value"]:
+                result[r["key"]] = ""
+            else:
+                try:
+                    decrypt(r["value"])
+                    result[r["key"]] = _SENTINEL
+                except Exception:
+                    result[r["key"]] = ""
+        else:
+            result[r["key"]] = r["value"]
+    return result
+
+
+def registered_keys() -> tuple[Key, ...]:
+    """供 CLI / 文档使用：枚举所有注册的 key。"""
+    return ALL_KEYS