# local-content-workbench

**Repository Path**: gitgreat/local-content-workbench

## Basic Information

- **Project Name**: local-content-workbench
- **Description**: Localhost 单项目内容与媒体工作台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Local Content Workbench

供多个 Astro/Markdown 站点复用的本地内容与媒体工作台。它只在 localhost 运行，每个进程一次加载一个明确的站点仓库；它不是在线 CMS，也不成为第二份内容事实源。

当前版本实现项目配置校验、`doctor`、内容阅读/搜索、向量相关文章推荐、站点推荐策略、媒体查看与对账、迁移审核编辑，以及文本保真的内容格式审计。默认仍只读；新建草稿、编辑、审核台账和 AI 网络分别使用独立开关。

Storage Inventory v1 已提供 provider-neutral 的本地分页快照检查与冻结 fixture；Cloudflare R2/OSS 的 SDK-independent 只读 List/Head 适配与有界分页已经实现，但尚无真实 SDK client、凭据读取或网络入口。

Content Draft v1 只有以 `--allow-content-write` 显式启动时才创建新 Markdown。Content Edit v1 使用另一个 `--allow-content-edit` 开关，只编辑已配置 collection 中的原始 Markdown，并通过 SHA 冲突检查、临时文件读回校验和原子替换保护写入。两者都不上传、不发布，也不调用 Git 或云服务。

内容页提供安全 Markdown 阅读预览、本地正文搜索和只读相关文章候选；媒体页提供公开 URL 缩略图、本地 manifest 筛选和 URL 复制。启用 Markdown 编辑后，可以把有效 manifest 媒体片段插入当前文章，再沿用差异预览与冲突保护写入；这不会调用对象存储管理 API。

后台管理页使用固定分组导航。根路径 `/` 提供工作概览，`/settings` 只编辑低风险项目规则；collection、路径和路由保持只读，本机 OSS 凭据仍与项目配置分离。接口与边界见 [ADR-009](./docs/decisions/ADR-009-unified-admin-shell-and-layered-settings.md)，完整流程与验收规范见 [统一内容工作台阶段收口](./docs/unified-content-workflow-closeout-2026-09.md)。

继续开发前先阅读 [当前状态与下一会话交接](./docs/current-status-and-next-session.md)、[项目历史、开发经验与工程思路](./docs/project-history-and-engineering-principles.md)、[2026-08-15 阶段收尾](./docs/stage-closeout-2026-08-15.md)、[工程实施与验收工作流](./docs/engineering-workflow-v1.md) 与 [开发与演进规范](./docs/development-principles.md)。旧阶段文档继续保留为历史决策记录。

## 快速开始

```bash
pnpm install --frozen-lockfile
pnpm test
pnpm project:doctor --project /Users/muze/gitee/site-xgif --json
pnpm media:report --project /Users/muze/gitee/site-xgif --json
pnpm media:reconcile --project /Users/muze/gitee/site-xgif --json
pnpm content:index --project /Users/muze/gitee/site-xgif --json
pnpm content:recommendations --project /Users/muze/gitee/site-xgif --json
pnpm content:format-audit --project /absolute/path/to/site --scope-file /absolute/path/to/scope.json --json
pnpm workbench --project /Users/muze/gitee/site-xgif
# 仅在明确需要创建新草稿时启用；默认不要添加此开关
pnpm workbench --project /Users/muze/gitee/site-xgif --allow-content-write
# 仅在明确需要编辑既有 Markdown 时启用；与新建草稿权限相互独立
pnpm workbench --project /Users/muze/gitee/site-xgif --allow-content-edit
# 仅记录本地审核决定；不发布、不提交 Git
pnpm workbench --project /Users/muze/gitee/blog --allow-review-write
# 编辑既有内容时必须把“站点效果”连接到当前工作树的 localhost Astro dev server
pnpm workbench --project /Users/muze/gitee/blog --port 4323 --allow-content-edit --site-preview-origin http://127.0.0.1:4322
```

内容编辑会话不得使用保存前生成的 `dist` 或旧 `astro preview` 作为“站点效果”：它们不会随 Markdown 保存实时更新。应先启动目标站点的 Astro dev server，再用 `--site-preview-origin` 显式连接。保存后检查 dev server 返回的实时服务端 HTML；批次、SEO 和发布候选收口仍须重新构建，并检查本次生成的静态产物。

目标站点需要在仓库根目录提供 `publisher.config.json`。配置格式见 [项目配置契约](./docs/project-config-v1.md)，示例见：

- [XGIF 示例](./examples/xgif.publisher.config.json)
- [npc.ink 示例](./examples/npcink.publisher.config.json)

XGIF 示例显式选择内置 `xgif` 插件。Site Plugin Contract v1 只允许核心注册表中的单一只读 `project.inspect` 插件；不从站点仓库、npm、URL 或任意路径加载代码。该机制当前暂停扩展，仅保留已实现代码。契约见 [Site Plugin Contract v1](./docs/site-plugin-contract-v1.md) 与 [ADR-007](./docs/decisions/ADR-007-core-and-site-plugin-boundary.md)。

## 当前命令

| 命令 | 行为 |
| --- | --- |
| `pnpm test` | 运行配置、doctor 与媒体字节契约测试 |
| `pnpm check` | 检查 Node.js 模块语法 |
| `pnpm project:doctor --project <绝对路径> --json` | 只读检查一个站点配置、内容目录、manifest 和 Git 工作树 |
| `pnpm media:report --project <绝对路径> --json` | 只读检查配置声明的媒体 JSONL manifest |
| `pnpm media:reconcile --project <绝对路径> --json` | 只读核对 Markdown/MDX 媒体引用与 manifest |
| `pnpm content:index --project <绝对路径> --json` | 显式重建本地 SQLite 向量索引；默认 provider 不联网 |
| `pnpm content:recommendations --project <绝对路径> --json` | 只读应用站点推荐策略并输出 decisions 报告 |
| `pnpm content:format-audit --project <绝对路径> --scope-file <绝对路径> --json` | 只读审计明确范围内的 HTML→Markdown 格式候选和结构证据 |
| `pnpm workbench --project <绝对路径> [--port 8788]` | 启动仅绑定 `127.0.0.1` 的单项目只读内容工作台 |
| `pnpm workbench --project <绝对路径> --allow-content-write` | 明确启用“仅创建新草稿”的本地写入能力 |
| `pnpm workbench --project <绝对路径> --allow-content-edit` | 明确启用既有 Markdown 的差异预览、SHA 冲突保护与原子写入 |
| `pnpm workbench --project <绝对路径> --allow-review-write` | 明确启用 `/reviews` 的本地审核决定台账写入；不修改正文或发布 |
| `pnpm workbench --project <绝对路径> --site-preview-origin <localhost-origin>` | 将最终站点预览重定向到显式 localhost HTTP origin；不授权网络写入 |

图片字节契约见 [Image Inspection v1](./docs/image-inspection-v1.md)。
媒体台账契约见 [Media Manifest Report v1](./docs/media-manifest-report-v1.md)。
内容引用对账见 [Media Reference Reconciliation v1](./docs/media-reference-reconciliation-v1.md)。
内容读取、搜索和相关文章候选见 [Read, Search and Related Content v1](./docs/read-search-related-v1.md)。
可重建 SQLite 与 embedding adapter 见 [Content Vector Index v1](./docs/content-vector-index-v1.md)。
站点拥有的过滤和人工覆盖规则见 [Recommendation Policy v1](./docs/recommendation-policy-v1.md) 与 [ADR-004](./docs/decisions/ADR-004-site-owned-recommendation-policy.md)。
存储 inventory 契约见 [Storage Inventory v1](./docs/storage-inventory-v1.md)。
R2/OSS 只读 List/Head 翻译与分页边界见 [Storage Read Adapter v1](./docs/storage-read-adapter-v1.md)。
新建草稿的 opt-in 写入边界见 [Content Draft v1](./docs/content-draft-v1.md)。
既有 Markdown 的独立编辑边界见 [Content Edit v1](./docs/content-edit-v1.md) 与 [ADR-005](./docs/decisions/ADR-005-safe-raw-markdown-editing.md)。
从有效 manifest 选择并插入文章见 [Media Markdown Insertion v1](./docs/media-markdown-insertion-v1.md)。
provider-neutral 上传顺序、adapter 和恢复状态见 [Media Write Transaction v1](./docs/media-write-transaction-v1.md) 与 [ADR-006](./docs/decisions/ADR-006-provider-neutral-media-write-transaction.md)。
manifest 原子追加与原始 Markdown 引用提交见 [Media Local Committers v1](./docs/media-local-committers-v1.md)。
本轮完整历史、经验和后续准入见 [2026-08-05 阶段收尾](./docs/stage-closeout-2026-08-05.md) 与 [工程实施与验收工作流 v1](./docs/engineering-workflow-v1.md)。
长期演进与收尾规范见 [开发与演进规范](./docs/development-principles.md) 和 [ADR-002](./docs/decisions/ADR-002-minimal-workbench-and-progressive-capabilities.md)。
站点内容规范尚未稳定时的观察优先决策见 [ADR-003](./docs/decisions/ADR-003-observe-before-site-schema-integration.md)。
新功能应放在站点仓库还是共享工作台，见 [站点功能与共享工作台的归属规则](./docs/site-feature-routing.md)。
文本保真的格式候选、批次审计和结构诊断见 [Content Format Preview v1](./docs/content-format-preview-v1.md) 与 [ADR-008](./docs/decisions/ADR-008-text-preserving-format-proposals.md)。

## 架构边界

```text
Local Content Workbench
        │ 启动时加载一个 publisher.config.json
        ├── XGIF adapter   → XGIF 内容、R2、GitHub/Cloudflare 专属规则
        └── npc.ink adapter → npc.ink 内容、OSS、Gitee/EdgeOne 专属规则
```

- 通用能力：输入校验、媒体字节检查、哈希、manifest、引用扫描、只读对账、收据和本地 UI。
- 站点能力：内容 schema、路径、URL、SEO、对象存储实现和发布平台事实。
- 插件边界：插件返回站点特色检查结果，核心验证输入输出并保留文件、Git、网络和写入权限。
- WordPress/RDS 提取器留在 npc.ink 迁移项目，不进入本工作台核心。
- 推荐算法、来源授权规则等 XGIF 特有能力留在 XGIF adapter。

详细决策见 [ADR-001](./docs/decisions/ADR-001-standalone-single-project-instance.md)。

## 当前阶段

1. 配置契约、只读 doctor、媒体字节检查、manifest 和引用对账已完成；
2. provider-neutral storage inventory 契约与 fixture 已完成，真实网络 adapter 暂缓；
3. 单项目 localhost UI、opt-in Content Draft v1 与 Content Edit v1 已完成；
4. 本地向量索引和站点拥有的推荐策略已完成；
5. 有效 manifest 媒体选择/插入、provider-neutral 上传事务和本地提交器已完成；真实存储 adapter 和上传 UI 尚未开放。
6. Site Plugin Contract v1、内置注册表、XGIF 只读项目检查和 doctor 集成已完成；内容 hook、动态加载、UI 注入和写入能力尚未开放。
7. R2/OSS Storage Read Adapter v1 已完成 SDK-independent List/Head 翻译、分页与数量上限；真实 SDK wiring、凭据和网络运行尚未开放。
8. Migration Review Editor 与 Content Format Preview v1 已完成；格式整理只生成候选，复杂结构继续人工审核，保存仍受独立编辑权限和 SHA 冲突保护。
9. 日常发布收敛为草稿、发布检查、警告确认和发布记录；内部候选快照不作为用户工作流入口。

媒体写入、站点入口接管、Git 同步和发布适配器不是当前承诺的路线项；它们需要独立需求、契约、验证和明确授权。