Folio
在编写 HTML 之前,请先阅读请求和任何现有的工件。所有外部依赖和发布 URL 都必须记录在清单总账中。工件是静态文档 —— 它们不调用 API。
何时使用 folio —— 以及何时不使用
Folio 用于需要持久化、可打开、可分享的 Web 交付物 —— 用户会保存、重新打开或交给其他人的东西。
使用 folio 的场景:
- 用户要求创建一个他们会保存或发送的文档、仪表盘、表格、幻灯片或页面
- 输出是一个交付物,而不是快速查看(“帮我做一份报告”、“为团队建一个仪表盘”、“把这个放到网上”、“我想要一个……的页面”)
- 用户显式调用动词(
folio publish、folio audit、folio remix、folio describe)
不要使用 folio 的场景:
- 用户想要快速查看,而不是交付物(“展示给我看”、“这看起来像什么”、“只是检查一下”、“你能显示出来吗”)
- 此对话结束后输出不会被再次打开 —— 直接回答或写一个草稿文件,不要盖章、记账或把关
- 请求是关于代码片段、配置文件、单个函数 —— 这些不是浏览器工件
入口关卡。 进入工件流程之前,请问:用户会在本次会话结束后再次打开这个文件吗? 如果不会,folio 是错误的选择 —— 直接回答即可。如果是,继续。
独立模式是默认方式。 最轻量的 folio 路径是一个包含单个 index.html 的文件夹 —— 没有站点根目录,没有 site.json,没有首页。仅当出现第二个工件或用户要求发布集合时,才创建站点根目录。不要为单个文件创建站点仪式。
术语表
在 Folio 输出中只使用这些术语。
| 术语 | 含义 |
|---|---|
| artifact | 一个自包含的静态 Web 交付物:包含 CSS/JS 的 HTML,可在浏览器中运行 |
| bundle | single-file(内联 CSS/JS)或 multi-file(在一个目录中链接资源)之一 |
| artifact kind | 文档、表格、仪表盘、解释器、幻灯片、工具、着陆页之一 |
| host profile | 站点持久化所在的位置:local、surge、gh-pages、cf-pages、cf-worker |
| share (tunnel) | 一个临时的公共 URL,指向正在运行的本地服务器,通过 localhost.run(默认)或 ngrok。临时性的,机器仍然是主机 —— 不是发布 |
| site root | 一个包含 index.html 和 artifacts/ 目录结构的目录,作为一个域名发布。工件是其下的路径,而不是独立的子域名 |
| site manifest | .folio/site.json —— 权威的事实来源。包含域名 + 每个工件的注册信息(slug、kind、bundle、ledger、provenance、publish state)。戳记、索引和审计都基于它 |
| standalone artifact | 没有站点根目录的工件。HTML 戳记是其唯一清单。当第二个工件出现时升级为站点条目 |
| provenance | 混合作品上 source 字段:{ slug, site, url }。原创作品为 null。由 describe、audit 和 remix 读取 |
| manifest | 入口 HTML、文件列表、外部依赖和可选的发布元数据 |
| ledger | 清单总账 —— 构建前的依赖、数据文件、URL 和证据级别 |
| gate | 在交接之前必须通过的二元检查 |
| evidence level | observed、derived、stated、absent 之一 |
如何使用本技能
- 默认:创建或更新一个工件。遵循工件流程。单个工件默认是独立的 —— 不需要站点根目录。
folio audit <path|url>:只读审计。不要编辑。阅读references/verbs/audit.md。folio describe <path|url|slug>:读取工件的清单条目(kind、ledger、provenance、publish state)。阅读references/verbs/describe.md。folio share <site-root>:通过隧道(默认 localhost.run — 无需安装,无需账户;备选--ngrok)为本地运行的站点打开一个临时公共链接。机器保持为主机;URL 随进程结束而失效。用于“让别人现在就看”,而不是发布。阅读references/verbs/share.md。folio publish <site-root>:将站点根目录(所有工件)部署到所选主机配置文件,用于持久的其他地方托管。首先重新生成索引(scripts/gen-index.js),然后部署。阅读references/verbs/publish.md。folio remix <path|url>:派生(fork)一个工件并更改它,同时保持清单诚实并记录来源谱系。阅读references/verbs/remix.md。
单次运行 = 一个工件,除非用户指定了多个。优先选择最能满足请求的最小打包方式。单个工件是独立的;多个工件位于一个站点根目录下,并作为一个域名发布。阅读 references/site-index.md 了解站点根目录模型和独立到站点的升级。
不容商榷的原则
- 先可运行,再美观。 工件能在浏览器中打开,核心交互在打磨或发布之前就能工作。
- 仅限静态文档。 没有对外部 API 的
fetch()、没有 WebSocket 连接、没有对实时端点的XMLHttpRequest。数据是内联嵌入的、通过fetch('./data/…')从本地文件加载的,或在构建时生成的。工件发出的唯一网络请求是记录在总账中的 CDN 脚本、样式和字体。 - 清单诚实。 CDN 脚本、字体、图像和数据文件都是总账行,而不是意外。
- 本地优先,然后分享,再发布。 默认主机配置文件是
local。以动态方式运行它 ——node <folio-skill>/scripts/serve.js <site-root>确保存在artifacts/文件夹,从总账重新生成索引/搜索页面,选择一个开放端口,并通过 HTTP 提供服务(对于完全内联的单文件,普通的file://也可以,但会破坏fetch和模块导入)。请参阅references/local-server.md。要立即给别人看,打开一个临时隧道 ——node <folio-skill>/scripts/share.js <site-root>(默认 localhost.run,无需安装/账户);链接是短暂存在的,机器保持为主机。持久化在其他地方托管是publish—— 仅当用户要求或调用folio publish时才进行。切勿主动宣传分享或发布功能。 - 静态文件中没有秘密。 API 密钥、令牌和私有 URL 不应放置在提交或发布的 HTML/JS 中。
- 不能丑陋。 工件遵循视觉基线。在构建之前阅读
references/visual-baseline.md。
金牌决策追踪
请求:为队友从这份 CSV 构建一个交互式延迟直方图。
盘点:
· 目标:新工件 `latency-hist`
· 现有:无
· 数据:用户附带了 `runs.csv`(已观察,840 行)
· 约束:本地文件夹,不发布
选取:kind=explainer · bundle=multi-file · host=local · audience=teammate handoff
总账:
dep | kind | evidence | in artifact as
d3@7 (cdn.jsdelivr) | script | stated, user did not pin | index.html script tag + note in README
runs.csv | data | observed | ./data/runs.csv, loaded via fetch('./data/runs.csv')
文件计划:
Create: artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
No deletes.
验证:npx serve artifacts/latency-hist; chart renders; console clean
关卡:opens-locally=yes, console-clean=yes, ledger-complete=yes, no-secrets=yes, mock-labeled=n/a, visual-baseline=yes
交接:路径、如何打开、总账摘要、待办:无
范围分支
在考虑宽泛的设计问题之前,先解决范围。
| 请求形态 | 打包方式 | 主机 | 跳过 |
|---|---|---|---|
| 快速一次性演示 | single-file | local | README, publish, multi-page |
| 书面文档或报告 | single-file 或 multi-file | local | 图表、繁重 JS |
| 数据表或表格 | single-file 或 multi-file | local | 叙述性文字、装饰 |
| 指标仪表盘 | multi-file | local | 完整 CRUD、实时数据流 |
| 概念解释器 | multi-file | local | 密集原始数据转储 |
| 幻灯片 | multi-file | local | 滚动布局、小部件 |
| 共享给队友的工件 | multi-file | local | 框架构建步骤 |
| 立即给别人看 | single-file 或 multi-file | share (tunnel) | 部署仪式、持久主机 |
| 持久化公共链接 | multi-file | surge 或 cf-pages | 认证、服务器逻辑 |
| 代理交接预览 | single-file 首选 | local | 除非要求,否则不分享/发布 |
模棱两可的请求:简洁地问一次。例如:“单个自包含文件还是包含独立 CSS/JS 的小文件夹?”如果没有回答,选择能够工作的最小打包方式。
工件流程
0. 盘点
阅读请求和任何现有的工件树。阅读 references/evidence.md 和 references/artifact-types.md。
收集:
- 主题: 工件应该展示什么或允许用户做什么
- 输入: 文件、JSON、CSV、副本、设计约束(附带证据级别)
- 现有工件: 路径、入口 HTML、清单、上次发布 URL(如果有)
- 主机配置文件: 默认
local;当涉及发布时,阅读references/host-profiles.md - 约定来源: 如果存在,则为
folio.md
在进行下一步之前,生成一个带有引用的紧凑盘点。
1. 选取
在构建之前输出:Picks: kind=<x> · bundle=<y> · host=<z> · audience=<a>。
当 kind 不明确时,阅读 references/artifact-types.md。当主机不是 local 时,阅读 references/host-profiles.md。
2. 清单总账
在编写 HTML 之前构建总账。阅读 references/manifest-ledger.md。
列:
dep | kind | evidence | in artifact as
类型:script、style、font、image、data、mock、publish-target。
数据文件和模拟数据必须明确。外部 API 调用不在范围内 —— 请参考原则 #2。
3. 文件计划和构建
在编辑之前说明文件计划:
Create: artifacts/<slug>/index.html, app.js, data/sample.json
Modify: none
No deletes.
从模板开始。 加载 references/templates/<kind>.html 并调整它 —— 将 {{placeholder}} 内容和 <!-- Replace: ... --> 标记替换为真实内容。模板本身也是通过关卡的 folio 工件;它们携带令牌块、亮/暗切换、favicon 以及特定类型的结构。阅读 references/templates/ 索引以了解每个模板提供的内容。
在编写 CSS 之前阅读 references/visual-baseline.md。
除非用户指定了特定技术栈,否则使用纯 HTML/CSS/JS 构建。首选:
- 语义化 HTML,一个明显的入口文件(
index.html) - 所有视觉令牌(颜色、字型、间距、圆角、阴影)使用 CSS 自定义属性
- 颜色使用 OKLCH;在
:root令牌块之外没有行内 hex/rgb - 纯 JS 或一个单一的指定 CDN 库 —— 计入总账
multi-file:保持所有资源路径为相对路径;没有绝对机器路径- 没有斜体标题;可读的行宽(
max-width: 60–70ch);在html和body上使用overflow-x: clip
当工件接受用户输入、嵌入第三方内容或公开发布时,阅读 references/security.md。
戳记(HTML 注释,入口文件顶部):
<!-- Folio · slug: latency-hist · kind: explainer · bundle: multi-file · host: local -->
<!-- deps: d3@7 · data: runs.csv · publish: none -->
对于 single-file,保持戳记最小(一行)。
4. 验证
阅读 references/verification.md。运行适合主机配置文件的检查。
最小矩阵:
check | command/evidence | result | notes
示例:静态服务器 + 加载入口 URL,DevTools 控制台清洁,点击主要交互,断链扫描,file:// 与服务器的 fetch 说明,视觉基线抽检。
5. 关卡
在交接前应用。任何 no 都会触发修复循环。
| 关卡 | 检查 |
|---|---|
opens-locally | 入口 HTML 通过静态服务器加载(或记录了诚实的 file:// 限制);服务器设置参见 references/local-server.md(scripts/serve.js 是一键路径) |
console-clean | 主要路径上没有未捕获的错误 |
ledger-complete | 每个外部依赖和数据源都出现在总账中 |
no-secrets | 源码中没有密钥、令牌或私有 URL |
mock-labeled | 当缺少真实数据时,标注模拟/示例数据 |
static-only | 没有对外部 API 的 fetch()、没有 WebSocket、没有对实时端点的 XHR |
visual-baseline | 令牌块存在,:root 外无内联颜色,无斜体标题,对比度足够 |
publish-ready | 发布时:主机配置步骤已记录并验证,或明确延迟 |
manifest-derivation | 建议性。 HTML 戳记(slug、kind、bundle)与此工件的 site.json 条目匹配。标记漂移;参见 references/verification.md#manifest-derivation-check。 |
构建后阅读 references/slop-test.md。在交接前修复 P0/P1。
6. 发布(可选)
仅在用户请求发布或调用 folio publish 时执行。阅读 references/verbs/publish.md 和主机配置文件的深层文件。
在清单和交接中记录发布 URL。未经发布命令输出的证据,绝不声明 URL。
7. 交接
包括:
- 工件路径和入口文件
- 如何在本地打开(确切命令)
- 发布 URL(如果已发布),附带证据
- 清单总账摘要
- 验证命令和结果
- 延迟项(例如,
fetch需要服务器,使用模拟数据)
不要将清单或发布事实埋藏在实现细节之下。
错误/正确对比
错误: 编写 fetch('/api/users'),因为仪表盘通常从 API 加载用户。
正确: 嵌入 data/users.json,并带有可见的“示例数据”标签。无 API 调用。
错误: 未列出就粘贴 Google Analytics、字体和三个 CDN 库。 正确: 每个依赖都是总账中的一行,带有 URL 和用途。
错误: “已部署在 https://demo.example.com”,但未运行发布命令。 正确: 发布 URL 从命令输出复制,或标记为延迟。
错误: oklch() 值散落在 CSS 各处,三个不同的 font-family 声明。
正确: 所有视觉值都在 :root 令牌块中,通过 var() 引用。
约定工件
folio.md(输出目录、默认主机、CDN 允许列表、命名):可选加入。阅读 references/folio-md.md。一旦存在,项目级默认值优先。
可选的每个项目布局:
.proj-root/
├── folio.md # 项目级约定
├── artifacts/ # 所有工件(站点根目录下)
│ ├── <slug>/ # 每个工件一个文件夹
│ │ ├── index.html
│ │ ├── style.css
│ │ ├── app.js
│ │ └── data/
│ ├── index.html # 站点索引/搜索(自动生成)
│ └── search.json # 搜索索引(自动生成)
└── .folio/
├── site.json # 站点清单(权威来源)
├── templates/ # 工件模板(符号链接或复制)
└── references/ # 流程知识(符号链接或复制)