用暖纸色、森林绿与克制的陶土橙，组织技术文章、证据型报告、知识卡片和架构图。
English · 中文
既是 Agent Skill，也是可复用的静态设计包。日常使用无需构建或安装运行依赖。
## 目录 - [是什么](#是什么) - [为什么需要](#为什么需要) - [核心概念](#核心概念) - [目录结构](#目录结构) - [快速开始](#快速开始) - [功能与使用场景](#功能与使用场景) - [配置](#配置) - [集成与扩展](#集成与扩展) - [安全与证据边界](#安全与证据边界) - [常见问题](#常见问题) - [已实现路线图](#已实现路线图) - [贡献指南](#贡献指南) - [许可证](#许可证) - [维护者职责](#维护者职责) ## 是什么 Forest Editorial Design 1.0.0 包含 Agent 指令、CSS token 与组件、四类 HTML 模板和离线示例。适合明确要求此编辑部主题的任务，不是通用前端框架，也不意味着所有绿色界面都应采用这套规范。 它侧重中文技术内容的可读性、文章的连续正文、明确的证据和限制。不使用 Agent 也可以直接打开 HTML 或复用 CSS。九个 HTML 页面由五个示例和四个模板组成，使用本地资源与系统字体回退。README 顶部的装饰性徽章需要联网加载，HTML 页面不需要。 三张原始参考图因尚无可核实的再分发授权，**不随公开包分发**。历史数值采样 CSV/JSON 仍保留，但这既不代表原图已公开，也不意味着仅凭公开包就能独立复现图像测量。详见 [NOTICE.md](NOTICE.md) 和[颜色来源](references/color-provenance.md)。 ## 为什么需要 | 常见问题 | 临时拼装的方式 | 本包的处理 | |---|---|---| | 文章、报告和架构图视觉不一致 | 每页单独调样式 | 共享语义 token 与组件 CSS | | 长文被装饰卡片打断 | 每段都放进面板 | 连续正文，只对必要信息强调 | | 漂亮报告看起来像已认证的数据 | 使用未标注的演示指标 | 保留范围、状态、来源与限制 | | 分享页面依赖远程字体或脚本 | 默认读者一直在线 | 本地 CSS、系统字体与已渲染 SVG | | 配色结论缺少来源层级 | 把所有采样像素当作设计 token | 区分实测、历史归纳与实现建议 | **目标是统一表达，而不是让版式夸大底层证据的可信度。** ## 核心概念 - **编辑层级：**章节标签 → 标题 → 上下文 → 主体 → 结论与限制 → 来源。 - **克制的视觉词汇：**森林绿 `#193C35`、页面底色 `#F5F2EA`、卡片 `#FCFAF6`、鼠尾草绿 `#E7EDD9` 与少量陶土橙 `#A35436`。通过细线和留白组织内容，而不是装饰阴影。 - **优先语义 token：**`--fe-bg-page`、`--fe-text` 等变量表达用途。`--fe-raw-*` 保留实测或历史配色，不代表这些值都适合作为正文颜色。 - **文字可读性：**推荐的正文、辅助文字和小字强调色比部分历史色更深。受支持色对的对比度检查不等于整页无障碍认证。 - **证据分层：**历史解码像素统计、推断出的设计选择和实现建议是不同的结论。位图无法证明源字体、原设计文件的颜色属性或业务结果。 ## 目录结构 ```text forest-editorial-design/ ├── README.md ├── README.zh-CN.md ├── INSTALL.md ├── CONTRIBUTING.md ├── SECURITY.md ├── LICENSE ├── NOTICE.md ├── SKILL.md ├── VERIFICATION.md ├── MANIFEST.sha256 ├── agents/ │ └── openai.yaml ├── assets/ │ ├── design-tokens.css │ ├── components.css │ ├── architecture-mermaid.svg │ └── sampling/ │ ├── samples.json │ ├── reference-01-all-colors.csv │ ├── reference-02-all-colors.csv │ └── reference-03-all-colors.csv ├── references/ │ ├── design-spec.md │ ├── typography.md │ ├── components.md │ ├── layouts.md │ ├── diagrams.md │ └── color-provenance.md ├── templates/ │ ├── article.html │ ├── report.html │ ├── cards.html │ ├── architecture.html │ └── architecture.mmd ├── examples/ │ ├── index.html │ ├── article.html │ ├── report.html │ ├── cards.html │ └── architecture.html └── scripts/ ├── validate.py └── sample_colors.py ``` 此目录树聚焦可复用设计包及公开文档；项目还可能包含发布管理文件。 | 路径 | 职责 | |---|---| | `SKILL.md`、`agents/openai.yaml` | Agent 工作流、主题边界与选择器元数据 | | `assets/design-tokens.css`、`assets/components.css` | 配色、字体、间距、组件、响应式与打印样式 | | `assets/architecture-mermaid.svg` | 可离线复用的预渲染图 | | `assets/sampling/` | 历史数值证据：RGB 直方图与区域测量 | | `references/` | 设计、布局、字体、图表及来源的详细规范 | | `templates/`、`examples/` | 四类内容模式、总览页与 Mermaid 源码 | | `scripts/validate.py` | 基于 Python 标准库的公开包校验 | | `scripts/sample_colors.py` | 对另行提供且已获授权的图像进行可选重采样 | | `MANIFEST.sha256`、`VERIFICATION.md` | 文件完整性清单与已记录的验证范围 | | `INSTALL.md`、`CONTRIBUTING.md`、`SECURITY.md` | 安装、变更流程与安全漏洞报告 | | `LICENSE`、`NOTICE.md` | MIT 条款及权利、来源边界 | 公开包有意不包含 `assets/references/` 原图目录。 ## 快速开始 ### 环境要求 | 任务 | 要求 | |---|---| | 查看或复用页面 | 现代浏览器；无需安装依赖或构建 | | 作为 Agent Skill 使用 | 支持此 Skill 格式的 Agent；安装与发现方式取决于宿主 | | 校验设计包 | Python 3.9+；仅使用标准库 | | 可选颜色重采样 | `uv`、与脚本兼容的 Python，以及脚本声明的固定版本 Pillow；首次使用可能需要联网 | ### 1. 打开总览 将源码归档解压到一个新目录，在浏览器中打开 [examples/index.html](examples/index.html)。保留 `examples/`、`templates/` 与 `assets/` 的相对位置。无需启动本地 Web 服务。 源码 ZIP 名为 `forest-editorial-design.zip`，顶层目录为 `forest-editorial-design/`。这是源码与 Skill 归档，不是 Python wheel 或已安装服务。便携解压和可选的用户级 Skill 安装方法见 [INSTALL.md](INSTALL.md)，安装时不覆盖已有副本。 ### 2. 校验解压后的源码 在包根目录执行： ```sh python3 -B scripts/validate.py ``` 校验器用于检查公开包结构、本地引用、CSS token、受支持文字色对、数值证据一致性与 SHA-256 清单，**不依赖已移除的原图**。成功时退出码为 0，并输出 `PASS` 摘要；失败项需要调查。此命令不认证浏览器渲染、Agent 发现、图像权利，也不独立复现历史图像测量。实际执行记录及限制应以 [VERIFICATION.md](VERIFICATION.md) 为准。 ### 3. 调用 Skill 或使用模板 可选安装 Skill 后，向 Agent 提出： ```text 使用 $forest-editorial-design，把以下技术复盘做成可离线阅读的 HTML。 保留全部事实、限制和来源，不补造缺失结果。 演示数据必须保留“示例”标识。 ``` 不使用 Agent 时，从 `templates/article.html`、`report.html`、`cards.html` 或 `architecture.html` 开始，将其中演示内容替换为自己的材料。 ## 功能与使用场景 | 场景 | 入口 | 必须保留的信息 | |---|---|---| | 技术文章 | [文章模板](templates/article.html) | 上下文、连续论述、来源与限制 | | 测试或评测报告 | [报告模板](templates/report.html) | 范围、环境、样本、实际执行状态、断言与证据 | | 知识或观点卡片 | [卡片模板](templates/cards.html) | 一个核心观点、短步骤、来源与限定条件 | | 架构或流程 | [架构模板](templates/architecture.html) | 节点、连线、方向、条件、回流、图例与边界 | | 主题总览 | [离线总览](examples/index.html) | 配色和组件演示，不是生产结果 | 模板是已填内容的排版示例，不是空白表单。需要替换标题、正文、指标和来源说明；真实证据齐备之前，保留明确的示例标识。卡片的 1080px 是图片工作宽度建议，不是网页强制宽度，也不是从原图恢复出的统一尺寸规范。 ## 配置 日常使用不需要环境变量文件、API key、包管理器配置或构建配置。在自己的副本中加载 token 和组件样式后，可覆盖 CSS 变量： ```css /* 在 design-tokens.css 和 components.css 之后加载。 */ :root { --fe-prose-max: 760px; --fe-page-max: 1120px; --fe-size-body: 16px; --fe-leading-body: 1.75; } ``` 以上是现有默认值，用于说明扩展位置。按用途调整语义变量。更改颜色后，需要重新检查受影响的前景/背景色对；更改字号或内容后，需要检查折行、手机宽度与打印分页。字体采用系统回退，不同操作系统的字形尺寸可能不同。包内不附带字体文件。修改主题前先阅读[字体规范](references/typography.md)和[设计规范](references/design-spec.md)。 ## 集成与扩展 - **静态站点：**复制两份 CSS，按 token → component 顺序加载，参考模板使用 `.fe-theme`、`.fe-page` 及内容类名。保留资源相对路径，或明确更新它们。 - **单文件 HTML：**按相同顺序内联两份 CSS，并嵌入必要的 SVG 或其他已获授权的资源。链接到某台机器已安装 Skill 的目录不具备可移植性。 - **图表工作流：**在支持 Mermaid 的工具中编辑 [templates/architecture.mmd](templates/architecture.mmd)。渲染新的 Mermaid 输出需要该工具；查看随包 HTML/SVG 不需要 Mermaid 运行库。详见[图表规范](references/diagrams.md)。 - **PDF 或图片导出：**使用浏览器打印或截图，再检查实际导出文件的中文、裁切与分页。不保证不同浏览器及下游图片压缩后的输出质量一致。 ### 可选颜色重采样 正常使用与公开包校验均不需要这一步。在 `./private-reference-images` 中自行提供**已获授权的原始输入文件**，名称为 `reference-01.jpg`、`reference-02.png`、`reference-03.png`。已记录的采样区域绑定这些原始文件，其他替代图无法复现历史测量。 ```sh uv run --script scripts/sample_colors.py --input-dir ./private-reference-images --output-dir ./sampling-output ``` 脚本通过内联元数据声明固定版本 Pillow，无需安装完整 Python 包；`uv` 可能下载 Python 或依赖。输入和输出目录都必须排除在公开分发之外；上述相对目录只是临时本地工作位置，不是应加入归档的内容。应在独立位置对比新输出，不要静默覆盖历史证据。只有另行取得授权、且字节完全一致的原始输入，才能用于独立对比历史记录；仅凭公开源码包无法完成这一点。 ## 安全与证据边界 - 三张原始参考图不随包提供，MIT 不授予对这些原图的权利。不得将原图、缩略图或其他未获许可的素材重新加入贡献或发布包。 - 历史 CSV/JSON 支持数值一致性检查，不支持恢复图像，也不能验证缺失原始输入的真实字节。输入哈希是来源记录，不能代替输入本身。 - 示例报告和图表用于排版演示，不得当作自己的已执行测试、业务成果或第三方背书。 - 生成 HTML 含不可信内容时，在打开或分享前应检查内容。静态模板不是 HTML 清洗器或安全沙箱。 - 对比度检查只覆盖受支持 token 色对，不覆盖所有自定义配色、辅助技术或 WCAG 要求。 - 公开示例、日志、截图和归档不得含凭据、个人数据、私密对话标识或机器特定的绝对路径。 - 校验和用于对照可信清单发现文件变更；未签名清单不能证明发布者身份，也不能证明内容不存在恶意行为。 漏洞报告遵循 [SECURITY.md](SECURITY.md)；再分发边界见 [NOTICE.md](NOTICE.md)。 ## 常见问题 **查看页面需要 Node.js、服务端或 Python 吗？** 不需要，直接在本地打开 HTML。Python 3.9+ 只用于包校验；可选重采样另有依赖路径。 **为什么没有原始参考图？** 尚无可核实的再分发授权，因此公开源码有意排除原图，同时保留历史数值来源记录。没有另行获授权的原始输入，就无法复现相关图像测量。 **离线徽章意味着所有步骤都不联网吗？** 不是。它描述九个 HTML 页面。获取 Agent 或 `uv`、下载可选采样依赖等环节可能需要网络。 **能只使用 CSS 吗？** 可以，设计包不依赖 Agent Skill 才能使用。再分发受 MIT 覆盖的代码时，应保留适用的版权与许可声明。 **为什么换台机器字体不一样？** CSS 使用本地系统字体回退，既不声称识别了原图字体，也不分发原图所用字体。 **校验通过是否意味着报告正确或 Skill 已被发现？** 不是。校验器检查设计包，不验证业务结论、真实 Agent 调用、视觉质量或全部无障碍要求。宿主发现行为需要在自己的环境确认。 **修改公开文件后怎么办？** 清单哈希会发生变化。先审查修改，再按 [CONTRIBUTING.md](CONTRIBUTING.md) 重新生成清单并运行校验。重新生成清单本身不等于验证通过。 ## 已实现路线图 以下勾选项描述已有实现范围，不是未来发布承诺： - [x] Forest Editorial 主题的可复用 CSS token 与组件。 - [x] 文章、报告、卡片、架构四类模板及五个离线示例页。 - [x] Mermaid 源码与预渲染 SVG，供图表复用。 - [x] 带有外部输入限制说明的历史数值颜色来源记录。 - [x] Agent 指令、安装说明与 Python 标准库校验器。 此列表不承诺发布时间、托管服务或未来兼容性。实际执行范围见 [VERIFICATION.md](VERIFICATION.md)，不要把功能清单当作测试报告。 ## 贡献指南 提出修改前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。保持双语 README 同步，保留证据边界与离线能力，只提供已获授权的素材。若仓库宿主已启用议题或拉取请求，可通过这些界面提出不含敏感信息的建议。本文不假定具体远程地址或社区功能已经启用。 ## 许可证 公开分发的项目材料采用 [MIT License](LICENSE)，版权归 **2026 Forest Editorial Design contributors**，适用范围及来源限制见 [NOTICE.md](NOTICE.md)。被排除的原始参考图不在本项目 MIT 授权之内。使用者应自行确认其新增内容的权利。 ## 维护者职责 **Forest Editorial Design 维护者**以集体角色审查贡献、权利与来源问题、验证记录和发布内容。本文不声明个人联系方式或远程仓库身份。仓库提供相关界面时可使用实际托管平台的功能；安全敏感沟通必须遵循 [SECURITY.md](SECURITY.md)，不要在公开议题中粘贴敏感细节。