范围裁定(所有者 2026-09-03)

• 规则 8:不是例外,是「先改设计稿、再进轮次」(与 R-TOOLS 同一顺序)。设计稿已于 2026-09-03 从 12 块扩到 15 块 (新增 2f 首页 / 2g 详情页 SKILL.md 态 / 2h 详情页 Python 文件态,原型加 Skills 两屏),并入 design/ (合并口径见 design/README.md:三方合并,本地三处动画 / 进度线优化保留)。然后才有这一轮。
• 四个产品问题的答复(设计前问的,答复直接决定了画板形态):

  问题	裁定
  页面深度	列表 + 详情页(不是就地展开、不是只有列表)
  访客怎么拿走	复制安装命令 + GitHub 仓库外链 + 站内下载 zip(三样都要;「复制 SKILL.md 全文」未单独选,但画板 2g/2h 的文件预览头部有 copy——按画板做,它复制的是当前文件原文)
  组织方式	按用途分类(与 Notes 首页同构:分类表 + 色点 + 卡片网格)
  收录范围	自研 + 精选第三方(卡片带出处行 + 「自研 / 精选」徽标;第三方带原仓库链接)

• 设计中途补的硬要求:每个 skill 要能看到它的目录,并能预览文件——markdown 与 Python 代码。落在 2g/2h:左栏目录树、右栏预览卡,默认 SKILL.md。
• 只读:没有搜索 / 筛选、没有点赞评论、不显示安装量、没有 RSS;卡片上不放按钮。画板上没有的一律不做。
• agent 不读 skills:本轮不给 agent 加 skills_* 只读工具、不给 agent_ro 授权新表(记 rounds/BACKLOG.md 待裁定)。

前置

R6(MCP 管理面)、R-TABS(tab 登记表 + 呈现开关:新 tab 走同一套三处登记)、R11(生产已上线)。 无新凭据。可能有一个新依赖(zip 打包,见「待所有者裁定」第 1 条)。

与画板的对照关系(实现时逐项核对)

画板上的文案是格式不是内容:卡片元信息行 = <出处> · <N> 个文件 · 更新于 <relTime>(自研出处显示 @<owner>,精选显示 owner/repo); 详情元信息 = [v<version> · ]<N> 个文件 · <总大小> · 更新于 <isoDate> · <出处>(第三方时出处是外链 出处 owner/repo ↗); 安装命令 = npx skills add <repo> --skill <name>(由 repo + name 派生,不单独存);zip 按钮文案 下载 zip · <size>。

数据模型(迁移 012_skills.up.sql)

三张表,与 notes 三张同一分工(读面只读、写面在 mcp);不给 agent_ro / agent_title / agent_image 任何权限(迁移 006 刻意不设默认授权,不写 GRANT 就是全部答案)。

• skills_categories(slug PK, name, dot, sort_order, updated_at) —— 与 notes_categories 同形;种子四行 framework / workflow / review / writing(色点沿用 Notes 四色)。
• skills(name PK CHECK '^[a-z0-9][a-z0-9-]{0,63}$', category_slug FK, summary, source_type CHECK IN ('own','curated'), repo, repo_url, version NULL, sort_order, zip BYTEA, zip_size, created_at, updated_at) —— name 就是目录名与 URL 段;repo 是 owner/repo(安装命令用,必填);repo_url 是 GitHub 目录外链(可空,所有者裁定 2026-09-03;空时 GitHub ↗ 与「出处 ↗」不渲染,与 About originUrl 为空时不渲染同一口径);zip 在写入时打好存库(见下)。
• skill_files(skill_name FK ON DELETE CASCADE, path, kind, content TEXT, size_bytes, line_count, sort_order, PK(skill_name, path)) —— 只收文本(UTF-8、无 NUL),kind 由扩展名派生、闭集:markdown / python / shell / typescript / javascript / json / yaml / toml / text; SKILL.md 必须存在且 sort_order = 0(排目录树首位)。
• 同轮迁移里给 site_tab_config 种一行 ('skills', TRUE)(R-TABS「新增 tab 要改三处」的第 2 处)。

写面校验(全部在 skills_upsert 里做,库级 CHECK 兜底):文件 ≤ 64 个;单文件 ≤ 256 KB;整包 ≤ 512 KB;path 相对、无 ..、不以 / 开头、段字符集 [A-Za-z0-9._-]、深度 ≤ 4; SKILL.md 的 frontmatter name 必须等于 skill name;repo_url 可空、有值时只收 http(s)(与 About originUrl 的 isHttpUrl 同一口径);LICENSE 文件不强制(所有者裁定);未知分类拒;删除仍有 skill 的分类拒。 内容与库内完全一致时整行不动(不刷新 updated_at,与 notes_chapter_upsert 同一约定)。

交付物

后端

• apps/api/agent/migrations/012_skills.up.sql —— 三张表 + 分类种子四行 + site_tab_config 种 skills
• apps/api/shared/site-tabs.ts —— 登记表加 { key: "skills", label: "Skills 技能库", path: "/skills" }(插在 notes 与 about 之间;site_tab_set 的 enum 自动多出 skills)
• apps/api/skills/{encore.service.ts,db.ts,store.ts,skills.ts,zip.ts} + README.md —— 只读面: GET /skills(首页)· GET /skills/:name(详情,含全部文件内容,整包 ≤ 512 KB 所以一次取完、文件切换不打后端)· GET /assets/skills/:name.zip(api.raw,流式吐库内 zip,Content-Disposition: attachment、nosniff、一天缓存 + 强 ETag,不用 immutable,理由同 notes 供图)
• apps/api/mcp/store.ts / tools.ts —— 八个工具:skills_categories_list / skills_category_upsert / skills_category_delete / skills_list / skills_get / skills_upsert(整包:name, categorySlug, summary, sourceType, repo, repoUrl?, version?, files[{path, content}],整包替换文件集合)/ skills_delete; skills_upsert 在写入时用 zip 库打包并存 skills.zip(管理面工具总数 34 → 42)
• apps/api/mcp/server.ts —— INSTRUCTIONS 的「顶部三个 tab」改「四个」,补一句 skills 发布约定
• apps/api/mcp/README.md —— 工具表补八条;apps/api/site/README.md —— 四个 tab
• dev.ps1 —— $hostedServices 白名单补 skills(R-TABS 漏补 site 曾让整站 500 级,本条列在验收里)
• deploy/Caddyfile —— @skillsZip path_regexp ^/skills/[a-z0-9-]+\.zip$ → rewrite * /assets{path} → api(与 @notesAsset 同一手法)
• apps/web/next.config.ts —— dev 代理补同一条(按 .zip 扩展名,动态路由 /skills/[name] 不会命中)
• docs/deploy-environments.md —— 构建命令的 --services 列表补 skills;冒烟清单第 1 条改「八个服务各取一个端点」(GET /skills)

前端(规则 7:既有页面与 GlobalNav 零改动)

• apps/web/lib/tabs.ts —— TabKey 加 "skills",TABS 加 { key: "skills", label: "Skills", href: "/skills", match: p => p.startsWith("/skills") }(第 3 处登记)
• apps/web/app/(site)/skills/page.tsx —— 画板 2f(Server Component,force-dynamic,requireVisibleTab("skills"))
• apps/web/app/(site)/skills/[name]/page.tsx —— 画板 2g/2h 的服务端壳(取数、?file= 选初始文件、404 门禁)
• apps/web/components/skills/SkillDetail.tsx(客户端:目录树选中态、?file= 同步、两处 copy 的 1.5s 回落)· FileViewer.tsx(markdown → frontmatter 键值块 + 既有 components/Markdown;代码 → 行号网格)· lib/highlight.ts(三 token 高亮的最小 tokenizer:注释 / 字符串 / 关键字,只做 python / typescript / javascript / shell,其余 kind 纯等宽)· lib/frontmatter.ts(只切 --- 围起来的 key: value 行,不引 yaml 库)
• apps/web/lib/api-client.ts —— dev.ps1 gen 产物(新增 skills 命名空间,mcp 仍排除)

测试

• apps/api/skills/skills.test.ts(读面:分类顺序、SKILL.md 首位、未知 name、zip 回读)
• apps/api/mcp/mcp.test.ts 新增 describe(写面校验逐条、幂等、级联删除、分类删除拒绝、工具总数闸 42)
• apps/api/site/tabs.test.ts 的「种子 ↔ 登记表一致」自动覆盖新 tab;apps/api/agent/sandbox.test.ts 加断言:agent_ro 读 skills 三表 permission denied

文档

• docs/security.md §1 第 2 层 / §4 的 R-SKILLS 补记(本次已随文档轮写入,实现时若有偏离先改文档)
• docs/architecture.md 总览已标「待实现」,收口时去掉标注
• docs/releases.md —— 发生产时记一行

验收

禁止

• 不改前端页面样式(规则 7):既有三 tab 页面、GlobalNav.tsx、Markdown.tsx 零改动;新页面严格照画板 2f/2g/2h。
• 不加设计稿没有的功能(规则 8):无搜索 / 筛选 / 排序、无点赞评论、无安装量、无 RSS、卡片无按钮、无「查看原始文件」新页面。
• 不执行任何 skill 文件、不做服务端 markdown 改写、不收二进制文件;文件内容一律当文本进 React(转义)与既有 Markdown 组件(不开 raw HTML)。
• 不给 agent 加读 skills 的工具、不给 agent_ro 授权新表(BACKLOG 待裁定)。
• 不在 /skills 之外新增站点路由;zip 的 API 侧路径固定 /assets/skills/…(与 notes 供图同一前缀策略,避开 Encore 同层字面量 / 通配撞车)。
• 不动 .secrets.local.cue 与任何环境的 token / 密钥;不升级 encore CLI / MCP SDK(规则 12)。

所有者裁定(2026-09-03,开工前四条已定)

1. zip 打包库 → 裁定:默认,fflate(纯 JS、无原生依赖、zipSync 一次调用;bun 下可用)。新增一个生产依赖,落地时记进「本轮实测」并钉 exact 版本。 备选(未采用):自写 stored-method zip 写入器。
2. 精选第三方 skill 的许可与仓库链接 → 裁定:均非必填。LICENSE 文件不强制、repoUrl 可空,skills_upsert 不因缺它们拒绝; 许可合规由所有者在收录时自行把关(只收允许再分发的包)。repoUrl 有值时仍走 http(s) 两道校验;为空时前端不渲染 GitHub ↗ 与出处链接(About originUrl 先例)。
3. 自研 skill 的真实仓库 → 裁定:默认,即不设全局默认值:repo(owner/repo)是每个 skill 发布时 skills_upsert 的必填字段,安装命令由它派生;画板里的 ClickPM/agent-skills 只是示例数据,不入库、不写死在代码里。
4. 代码高亮 → 裁定:默认,按画板做三 token 高亮(自写最小 tokenizer,只做 python / typescript / javascript / shell,不引高亮库)。

已知边界(不在本轮修,写明)

1. skill markdown 里的相对链接 / 相对图片不解析(站内不提供 skill 的资源文件),渲染成什么就是什么;references/*.md 里指向同目录文件的链接会 404。
2. 详情页一次取回整包内容(≤ 512 KB),大包首屏会重一些;上限就是为此设的,不做分文件懒加载。
3. 与 R-TABS「已知边界 1」同类:About 页没有指向 /skills 的链接,不受隐藏影响;Notes 页亦然。
4. 隐藏 skills 时 zip 端点照常服务(与 R-TABS「边界只到呈现层」一致)。

止损

回退成本:删 apps/api/skills/、apps/web/app/(site)/skills/、components/skills/,登记表两处各删一行,Caddy / next 各删一条路由; 表由一条新迁移 DROP(deploy/migrate.sh 口径,不回滚已施加迁移)。临时下架不用回退:site_tab_set{skills,false} 即可。

代码审查

• 审查方式:codex /codex:review --background --scope branch(改动跨前后端 41 个文件;前两轮按 CLAUDE.md 用全量 branch diff against main)
• 第 1 轮(2026-09-03,审 ebe7083):3 条 P2,无 high 级。逐条:
  1. [P2] shared/skill-pack.ts skillPackHash 用 U+001E / U+001F 拼接字段,而内容只拒 NUL 与孤立代理对 —— 正文里恰好含分隔符 + 另一个路径的单文件包,与两个文件的包哈希相同,upsertSkill 回 unchanged、继续供旧 zip。 采纳整改:改成每个字段「长度前缀 + 字节」框定(含文件数),流无歧义;mcp/skills.test.ts 加一条构造碰撞的用例(旧写法下逐字节相同的两包现在哈希不同;同内容乱序仍相同)。
  2. [P2] skills/skills.ts 详情端点两条查询(元信息、文件)各看各的快照,发布并发时会把旧版 fileCount / zipSize 配上新版文件。 采纳整改:skills/store.ts 加 readSnapshot(SET TRANSACTION ISOLATION LEVEL REPEATABLE READ, READ ONLY 的只读事务),详情与首页(卡片 + 最近更新)都改成单快照读;写面 upsertSkill 本就是一个事务,于是读到的永远是某个完整版本。
  3. [P2] skills/zip.ts 对 /assets/skills/%ZZ.zip 这类坏编码,decodeURIComponent 抛 URIError → raw 端点回 500 而不是 404。 采纳整改:捕获后走同一个 404;skills/skills.test.ts 加 %ZZ.zip / 截断的多字节编码两例。notes/assets.ts 与 notes/rss.ts 是同一写法但属既有代码、不在本轮 diff,按「跨轮次问题不顺手改」记 rounds/BACKLOG.md。
  • 审查推理里提到但未列为 finding 的两处,顺手做了一字改动(非机制):clipboard writeText 的异步 reject 补 .catch;[name]/page.tsx 给 SkillDetail 按 skill 名加 key,客户端在两个详情页之间导航时选中文件 / copied 态不跨 skill 残留。
  • 整改后:check 通过、dev.ps1 test 18 文件 / 414 用例全绿、tsc 通过、本机实探(详情 / 首页 / %ZZ.zip → 404)正常。
• 第 2 轮(全量范围,审 0f9c958):1 条 P2 + 1 条 P3,无 high 级。逐条:
  1. [P2] mcp/store.ts 的 getSkill(管理端 skills_get)仍是两条查询各看各的快照 —— 与首轮 #2 同一类,首轮只改了访客读面。 采纳整改:两条查询进同一个 REPEATABLE READ, READ ONLY 事务(复用 inTransaction)。
  2. [P3] CodeView 对空文件渲染一个编号 1 的空行,而头部按 line_count 写 0 行。采纳整改:空内容渲染 0 行。
• 第 3 轮(只审整改 diff,--base 0f9c958,审 01016a4):无 findings(「快照事务正确、空文件行数已对齐」;它提到的 encore check 超时是 codex 自己沙箱里的 daemon,本机 check 通过)。
• 结论:整改后 PASS(三轮合计 4 P2 + 1 P3,全部采纳整改;high 级为零;无不采纳项)。 顺带的教训:第 1 轮 #2 修了访客读面的快照问题,第 2 轮在管理端读面又来了同一类 —— 一条 finding 指向一类模式时,同一 diff 里的同类位置要一起改。

失败处理

同一验收项针对性整改后连续 2 次验证仍不过 → 写 rounds/round-skills/BLOCKED.md,停下呼人。禁止放宽验收标准自我通过。

本轮实测

实现留证(2026-09-03,本机)

数字:dev.ps1 check 通过;dev.ps1 test 18 文件 / 413 用例全绿(本轮前 16 / 388;新增 skills/skills.test.ts 9 条、mcp/skills.test.ts 16 条, site/tabs.test.ts / mcp.test.ts / sandbox.test.ts 各改一处断言);管理面工具 34 → 42;前端 tsc --noEmit 通过;新增生产依赖 fflate@0.8.3(exact)。

验收逐项(本机 encore run :4000 + next dev;发布走真实 MCP 协议路径,脚本在会话 scratchpad,token 取自用户环境变量、不进命令行):

与任务卡的偏离(实现时的判断,列出来供审查 / 所有者过目):

1. 第五个 skill 工具 = skills_file_get。任务卡写「skill 五个」但只点名了四个;skills_get 若回整包内容,一个 512 KB 的包会灌满管理端上下文, 所以 skills_get 只回元信息 + 文件清单(路径 / 种类 / 大小 / 行数),原文由 skills_file_get{name, path} 单取 —— 与 notes_chapter_get「改之前先读回来」同一用途。总数仍是 42。
2. skills 表多一列 content_hash(任务卡的列清单没列):幂等判据(与 notes_chapters.content_hash 同一约定),同时充当 zip 的强 ETag —— 不必另存一份 zip 哈希。
3. 测试文件:写面用例放在新文件 apps/api/mcp/skills.test.ts(25 条),没有塞进已 1000+ 行的 mcp.test.ts;后者只改了工具总数闸与四格相关的三处断言。
4. kind 派生不回落成 text:扩展名不在表里一律拒(闭集的本意);无扩展名的常见文本文件(LICENSE / README / Makefile / .gitignore 等)按白名单收成 text。 .svg / .html 因此进不来 —— 与 docs/security.md 的措辞「SVG 不是文本 kind」一致。路径「深度 ≤ 4」按段数 ≤ 4(至多三层目录)实现;另加不区分大小写去重(Windows / macOS 解压会互相覆盖)。
5. markdown 文件在服务端预渲染:Markdown.tsx 本轮零改动,而它的标题 id 是按出现次序计数的;放进 Client Component 后开发态 StrictMode 双调用会把 id 变成 何时用-1、与 SSR 输出不符(实测水合告警)。 于是 [name]/page.tsx 把每个 markdown 文件预渲染成 ReactNode(mdViews)与目录(tocs)传给 SkillDetail,客户端只决定显示哪一个;代码文件仍在客户端由纯函数 CodeView 渲染。副作用:react-markdown / KaTeX 不进这页的客户端包。
6. SkillFileKind 写成显式字面量联合:(typeof SKILL_FILE_KINDS)[number] 会让 encore check 报 unsupported indexed access type operation(它进了 API 响应形状)。
7. 代码视图的横向滚动在整块上而不是画板上每行各自 overflow-x:auto(静态画板定不出这层差别;逐行滚动条是视觉 bug)。
8. lib/time.ts 新增 relTimeZh(画板 2f 写的是「更新于 12 天前」,Notes 的 relTime 是 3d ago,各照各的画板);lib/external.ts 抽出 About 页同名的 safeExternal(About 页本身零改动)。
9. ?file= 指向不存在的文件时回落到 SKILL.md 而不是 404(它只是「打开哪个文件」的提示,不该让整个 skill 变成 404)。
10. 「本页目录」与 Notes 文章页同一实现:全部项非激活态(画板 2g 画的是第一项激活;Notes 的 2c 同样没做滚动联动,沿用先例不另起机制)。
11. 目录树顺序:每层先文件后目录、各按名字排,根目录 SKILL.md 钉首位(画板示例里 scripts/ 在 references/ 前只是示例数据的顺序)。

踩的坑:Write 工具会把 \u0000 / \u001f 这类转义解码成字面控制字符写进 .ts(用户级 CLAUDE.md 记过),shared/skill-pack.ts 用 python 脚本按 chr(92) 拼回转义形式; worktree 开工三件事(npm ci ×2、复制 .secrets.local.cue、PowerShell cwd)按项目记忆处理,dev.ps1 gen 把 app slug 翻成 mkaxu、按先例还原。

文档轮留证(2026-09-03)

• 设计稿:云端 Claude Design 项目(1a257a60-…)经 DesignSync 拉回三份文件;support.js md5 与本地一致未动;两份 .dc.html 以 16a82bd 为 base 三方合并(零冲突),本地 omWaveSweep / omSpin / 阅读进度线注释全部保留,云端 2f–2h、四格 tab、原型 Skills 两屏全部并入(核验:合并稿相对本地零删除行,Prototype 仅三行为云端有意改动的基线行;<div> / <sc-for> / <sc-if> 开合计数两份文件均配平)。
• 给 Claude Design 的提示词与原型 HTML 原稿未入库(scratchpad 产物,画板已是终稿)。