picture_bed · 设计总览 + 实现状态 · v0.3.0

picbed 工程架构与功能详细设计

写法对齐 my_gallery/docs：先用 F/P/模块/AC 标识体系写 Markdown 设计族谱，本页仅作 HTML 呈现层，便于浏览器浏览与评审。权威定义在 docs/features-index.md。 F1–F22 已实现（CLI + 本地 Web 控制台，含拖拽工作台）。

CLI + 本地 Web UI 拖拽文档工作台 GitHub Contents API（PicX 同源） F1–F22 done v0.3.0 2026-09-23

0. 安装（复制即用）

Release 固定资产名 picbed.tgz，下面命令永远装最新版：

npm install -g https://github.com/Aermberry/picture_bed/releases/latest/download/picbed.tgz

鉴权两种方式（无 OAuth App）：

PAT：$env:PICBED_GITHUB_TOKEN = "ghp_…"（或别名 GITHUB_TOKEN）
或 GitHub CLI：gh ≠ git；安装后 gh auth login，picbed 自动 gh auth token

1. 标识体系（先抽象）

沿用 my_gallery 的契约锚点：用稳定代号避免「同物异名」，并在总表 ↔ 模块间双向链接。

F · 功能点

可独立描述与验收的产品能力。权威定义在 features-index.md；不是任务号/类名。

P · 优先级

P0 MVP 闭环 · P1 第二批 · P2 后续 · P3 backlog。数字越小越早交付。

模块 · 归属

主责限界上下文：ingest / transfer / rewrite / cliops / webui。

AC · 验收

做完的可观察契约；步骤可改，AC 变更须显式修订总表。

一句话：某能力（F）在一定优先级（P）下主要落在某模块，并以某组 AC 判定完成。阅读顺序：总表 → P/模块/AC → module-* 域规则 → cross-cutting 全局契约。

2. 背景与目标

日常用 picx-app 做图床，但难以批量处理一篇/一夹文档中的本地图片，且Agent 难以稳定驱动。 picbed 目标：扫描 Markdown/HTML 内嵌图片 → PicX 同源 GitHub 通道上传 → 自动回写链接。

G0 抽取文档中的图片引用（代码块不误伤）
G1 解析本地文件并 sha256 去重，产出可预览 plan
G2 GitHub Contents API 上传 + 稳定 public URL
G3 回写链接：dry-run / backup / revert
G4 Agent 契约：--json、退出码、无 TTY、幂等
G5 安全：token 不入库；默认拒路径越界
G6 本地 Web 控制台：拖拽文档/目录或路径指定，完成 scan/plan/sync/revert 等

非目标：公网/多用户 UI、Tauri/桌面壳、OAuth 登录（已移除）、图片工具箱。watch / 多图床 / MCP 已实现（原 P3）。

3. 功能点总表（定义权威）

完整 AC 以 docs/features-index.md 为准；下表为索引视图。

ID	名称	P	模块	AC 摘要
F1	项目初始化与配置	P0	cliops	init 模板合法；config 读写；token 掩码
F2	环境与鉴权自检	P0	cliops	doctor 可定位问题；失败退出码 3
F3	目录扫描与文档发现	P0	ingest	扩展名/忽略规则；稳定排序
F4	图片引用抽取	P0	ingest	MD/HTML 覆盖；代码块不误伤；精确偏移
F5	本地资产解析与去重	P0	ingest	相对文档目录；缺文件/越界可诊断；sha 合并
F6	上传计划 plan	P0	transfer	upload/skip/blocked 分类；dry-run 不写不传
F7	GitHub 图床上传	P0	transfer	Contents API；URL 风格；同 sha 幂等
F8	文档链接回写	P0	rewrite	仅换 URL 子串；原子写；默认 backup
F9	Manifest 与 revert	P1	rewrite	映射无 token；revert 还原 raw 路径
F10	Agent 机器接口	P0	cliops	JSON schema；退出码；无 TTY 不阻塞
F11	单文件上传	P1	transfer	upload 输出 URL；与 sync 共用适配器
F12	watch 监听	P3→done	cliops	防抖增量 sync；可退出；无特权
F13	多图床适配器	P3→done	transfer	HostAdapter：github \| local
F14	VS Code / MCP 包装	P3→done	cliops	picbed-mcp 只转调 CLI --json
F15	GitHub Token 鉴权	P0→done	cliops	PAT / GITHUB_TOKEN / gh auth；无 OAuth
F16	本地 Web 控制台服务	P0	webui	本机起停；health；token 不出响应
F17	目录/拖拽与计划工作台	P0	webui	拖拽文档/文件夹；scan/plan；dry-run 无副作用
F18	一键同步	P0	webui	显式确认后 sync；进度与 partial 可观察
F19	回滚面板	P1	webui	manifest 可视；revert 可 dry-run
F20	配置与自检面板	P1	webui	config 掩码；doctor 报告
F21	审计与报告	P2	webui	run 记录；失败明细；JSON 对齐
F22	监听控制台	P2	webui	watch 启停与事件；无常驻特权

4. 总体架构

CLI / WebUI（呈现）→ 应用编排 → 领域核心（无 I/O）→ Host / LocalStore 适配器。

5. 模块与功能点映射

模块	职责	F 映射	设计文档
`ingest`	扫描、抽取、解析、去重	F3–F5	`docs/design/module-ingest.md`
`transfer`	plan、上传、URL、Host 工厂	F6–F7, F11, F13	`docs/design/module-transfer.md`
`rewrite`	回写、manifest、revert	F8–F9	`docs/design/module-rewrite.md`
`cliops`	配置、doctor、Agent 契约、watch、MCP、token 鉴权	F1–F2, F10, F12, F14, F15	`docs/design/module-cliops.md`
`webui`	本地 Web 控制台：拖拽工作台、确认门、审计	F16–F22	`docs/design/module-webui.md`

双向链接：各 module 文首「归属功能点」+ 文末「功能点映射」链回总表，与 my_gallery 一致。

6. CLI / Agent 契约

Code	含义	典型
0	成功	含 0 变更
2	用法	参数非法
3	配置/鉴权	doctor 失败、缺 token
4	本地文件	缺失、越界
5	远端 API	限流、5xx
6	部分成功	部分文档失败
7	需确认	无 `--yes` / Web 缺 `confirm`

{
  "schemaVersion": 1,
  "ok": true,
  "command": "sync",
  "data": { "uploaded": 3, "rewrittenDocs": ["docs/a.md"] },
  "warnings": [],
  "error": null
}

全局旗标：--json --quiet --verbose --config --cwd --yes --dry-run；Web API 同信封（command: api.*）。详见 docs/design/cross-cutting.md。

7. 图床通道（PicX / GitHub）

PicX = GitHub 仓库托管 + URL 风格。配置：host.type（github|local）、token / owner / repo / branch / dir / url.style。

# raw
https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}

# jsdelivr
https://cdn.jsdelivr.net/gh/{owner}/{repo}@{branch}/{path}

# custom template

远端路径：{dir}/{yyyy}/{mm}/{sha12}-{safeName}；同 sha256 幂等跳过。

8. 测试与验证

单测（extract/resolve/rewrite）对齐 F4/F5/F8；Host mock 对齐 F7；CLI JSON 对齐 F10；e2e fixture 对齐 F6–F9。
Web：health/confirm/掩码（F16/F18/F20）；拖拽解析与 plan 分组（F17）；revert/runs/watch（F19/F21/F22）。
黄金用例：代码块内 ![]() 不改写；中文路径；同图多引用；已 URL 跳过；拖拽项不在 root 下 → blocked。
交付规则：每次改动相关测试/验证全部通过；设计阶段用 scripts/validate-design.ps1 校验 docs 结构与本页锚点。

9. 文档地图（Markdown 权威源）

层	路径
阅读指南	`docs/design-reading-guide.md`
架构总纲	`docs/architecture.md`
功能点总表（F 权威）	`docs/features-index.md`
模块详设	`docs/design/module-{ingest,transfer,rewrite,cliops,webui}.md`
横切约定	`docs/design/cross-cutting.md`
HTML 呈现（本页）	`docs/html/index.html` + `styles.css` + `app.js`

10. 状态与开放问题

已冻结：命令/包名 picbed；栈 Node/TS；F1–F15 已实现；OAuth 登录已移除
已发布：GitHub Release（picbed.tgz 跟随 latest；本版 v0.3.0）
已实现：F1–F22 全量（CLI + picbed ui Web 控制台）

URL 默认风格是否在文档示例中再收紧？
是否增加更多 HostAdapter 后端（对象存储等）？
npm 官方源发布？（当前仅 GitHub Release tarball）
开放问题均已冻结：ui · 轻量 Vite+原生 · 拖拽强制绑根 · watch 默认 preview