fdk

技能：fdk — Framework Dev Kit（自包含）

按需使用：不要在会话开始时自动加载（大多数会话都在开发其他项目）。此技能本身包含足够的指导，可在任何项目中使用；文末的“完整版本”仅适用于你身处框架仓库时。

WHAT

目的与背景

• **目的：**按需使用的自包含入口，用于修改框架本身，或在任何项目中提炼／编写技能：涵盖任何更改前的预检、发布／HTML 规则、下游映射，以及问题树维护。
• 触发条件（何时使用）：
  • 正在修改框架本身（技能／规则／验证器／钩子／wiki），或
  • 正在任意项目的会话中提炼／编写技能。
• **非目标：**不要用于常规项目功能开发（这是大多数会话的情况 — ADR-004）；不要在会话开始时自动触发。

默认理念 — Donella Meadows：修复系统，不要修复症状

所有框架工作都要通过系统思维与反馈回路的视角来审视（systems thinking，Thinking in Systems）：

• 遇到错误／问题 → 先问“什么结构导致了它？”，再修补痛点。反复出现的症状，说明反馈回路缺失或有误 — 第二次手动修复同类错误就是流程出了问题；正确做法是改变结构（规则 harness、技能、模板、钩子），从根源上防止错误再次发生。（这正是 failure-flywheel 和 problem-tree 正在做的事。）
• 以最低成本选择最高杠杆点（leverage point），遵循 Meadows 的层级：调整参数 < 增加反馈回路 < 改变信息流 < 改变规则 < 改变目标／范式。编码前先问自己：这个修复处于哪个层级？有没有成本更低的更高层级做法？（例如，与其提醒 Agent 记住 — 低层级 — 不如添加会自动触发的验证器 — 改变规则。）
• 培育反馈回路，而不是只打出一发：每次更改都必须有信号回传路径（确定性验证、台账、日志、评估），让系统自行发现偏差。没有反馈回路的更改 = 盲目更改。
• 尊重延迟（delay）：新规则／技能的效果，只有经过多个会话才会显现 — 不要过早下结论，也不要在前一个修复尚未生效时叠加更多修复；在台账中记录日期以便衡量。

第二条准则 — Hub 与呈现（面向用户的 UX，2026-07-03 反馈）

除了 Meadows 的思维方式外，所有框架工具／技能／Hub 都必须遵循便于使用且安全的原则：

• **一个 Hub，一个名称，描述范围 — 不要让用户记住多个子命令。**一个 Hub 处理所有相关工作；用户只需描述范围（全部 > 一部分／同类部分／程度），而不必记住子命令。命令名称必须简短、好记（用户熟悉 curl；难记的名称 = 永远不会被调用 → 毫无用处）。例如，用 medic（健康检查总入口）替代冗长的名称。
• **TL;DR — 用户阅读的部分要精炼且包含足够信息，不要吝于说明。**用户有“too long didn't read”的习惯：内容要简短，但不能残缺，也不要吝于解释。
• 思维模型要透明 — 用户会阅读 think 部分来了解方向。不要隐藏推理过程。
• 在输出结尾：注入回顾 + 被动教学 — 简明重申此工具的用途 + 提示典型和意外的使用场景（用户没想到也能用的场景）→ 让用户无需询问就能学会使用。
• **透明 = 安全；可用性 > 性能。**让用户能够读懂目录结构和底层实现，而不只是针对查询进行优化。展示出来就意味着透明 → 用户会觉得使用系统更安全。优先考虑可用性，而不是隐性优化。

心智模型

pre-flight（pull → 规则 → grep/影响分析 → 提议 STOP → 精准修改+验证 → 下游布局）→ 修改 → [提炼技能 · 来自其他项目的 kit · 仓库内的完整版本] → ship 前执行 ci-local + fdk-uat → 结束当前轮次前更新 problem-tree。

Input và output contract

	Field	Required?	Ý nghĩa
In	việc framework hoặc skill cần distill	có	mô tả của user
In	repo hiện tại (framework hay dự án khác)	có	quyết định dùng bản đầy đủ hay kit
Out	draft propose chờ duyệt, rồi thay đổi surgical đã verify	có	không code thẳng
Out	llmwiki/html/fdk-problem-tree.html đã rà/cập nhật	có mỗi lần gọi	trước khi kết thúc turn
Out	PR qua kit	khi dev từ dự án khác	fdk-kit.sh submit

规则与能力

• RULE-01 (MUST)：推送/PR 前必须先运行 python3 fdk/tools/ci-local.py（在本地运行所有 GitHub workflow 的 run: 步骤，L4）。L2（pre-commit/medic）不等于 L4（全新克隆环境中的 CI）：有些 gate 只在 CI 上运行，或 Stop-hook 会自动修复，因此“提交后立即推送”可能通过 L2，但 CI 却失败（已发生：R3 index-sync 2026-07；search-index + skill-provenance 2026-09-08）。全部通过后才能推送；然后运行 /fdk-uat（canary + main-URL smoke），再报告完成。参见 [[harness-enforcement-floor]]。
• RULE-02 (MUST)：不得署名归功于 AI——commit message / PR / 代码 / wiki 中不得插入 Co-Authored-By: Claude…、Generated with Claude Code、🤖，或任何归功于 AI 的 credit/attribution。作者和提交者只能是用户身份。如果模板/工具预先生成了署名 trailer，提交前必须删掉。
• RULE-03 (MUST)：仅按需运行——不得注册会在会话开始时自动触发的 hook（ADR-004）。
• RULE-04 (MUST)：自包含——上文（pre-flight + distill + inventory）足以在其他项目中运行；“完整版本”部分仅在这些文件存在时适用。绝不假定仓库本地文件存在。
• RULE-05 (MUST)：数量始终实时计算；不得硬编码（防止漂移）。
• RULE-06 (MUST)：面向读者的 HTML 必须解释术语——report/visualization 中显示的内容（标题、节点说明、注释）使用普通越南语；专业术语首次出现时必须立即在括号中附上简短解释（例如：“flush（刷新记录——退出前自动保存）”、“untracked（Git 尚未跟踪的文件）”）。不得向读者使用未经解释的 jargon 缩写——未经解释的 jargon 仅可用于机器可读文件。
• RULE-07 (MUST)：面向查看者的 HTML 必须提供明暗模式切换（2026-07-06 反馈——已提醒两次，不得再犯）——所有为人查看而生成的 HTML 文件（report、树、dashboard、docs、proposal 渲染页……）都必须有 dark/light 切换按钮：prefers-color-scheme 仅作为初始默认值；用户点击切换按钮后，必须通过 html[data-theme] 覆盖，并保存到 localStorage（在 head 中附带防止 FOUC 的 script）。不得强制固定某一种模式。必须使用带标签的开关按钮（switch），放在固定于 sidebar/nav 底部的 footer 行——不得使用散落在角落的图标 chip。标准代码片段：skill docs-site-macos § “明暗模式切换”；generator 可参考 _DARK_RULES 中的 fdk/tools/build-overstack-docs.py（单一来源生成两个代码块，防止漂移）。
• RULE-08 (MUST)：切换模式必须使用 circle-reveal，不能瞬间翻转（160926 反馈，任务 T-260916-01）——点击开关后，显示一个与目标模式背景色相同的圆形 overlay，从按钮的准确坐标开始，缓慢扩散，随后快速、干脆地覆盖整个 viewport；此时才更改 data-theme/localStorage 的值，然后淡出 overlay。遵循 prefers-reduced-motion: reduce（降级为 ≤150ms 的 crossfade，不得完全取消动画）。标准代码片段：skill docs-site-macos § “明暗模式切换”第 4 项；使用 node skills/docs-site-macos/scripts/verify-theme-motion.mjs <file.html> 验收（使用真实 Playwright 验证，不能由模型自行保证）。
• RULE-09 (MUST)：面向查看者的 HTML：适用于 13″ 屏幕的紧凑字号范围（2026-07-06 反馈）——字号应调小而非调大：body 约 13.5px，nav 12px，列表/表格 12.5px，标签 10–10.5px；增大字号会让 13″ 屏幕体验更差（显示内容更少、换行更拥挤）。易读性取决于 line-height/contrast，而不是字体大小。详情：docs-site-macos § Best Practices。
• RULE-10 (MUST)：HTML report/visualization 必须显示完整路径——所有为查看而生成的 HTML 文件（report、树、dashboard、proposal 渲染页……）都必须在页面上直接显示其绝对路径（放在 footer 或 titlebar 中，以可复制的 <code> 格式呈现），让查看者知道文件所在位置，以便重新打开或修改。生成文件后必须填入真实路径，不得使用占位符。
• 能力：读取/写入框架仓库或 sandbox kit；在本地运行 gate/test；通过已认证的 CLI 创建 PR。

失败边界

• 尚未获批的草案 → 在 pre-flight #4 blocked，不写代码。
• ci-local.py 报错 → 不推送（RULE-01）。
• repo-local 文件不存在（当前在其他项目中）→ 跳过“完整版本”，不要假设文件存在（RULE-04）。
• fdk-kit.sh check 未完成 15 个步骤 → 不提交。

HOW

主工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	effect	base remote	修改前先拉取	最新版本	—
W02	deterministic	harness	了解规则（rule-registry / policy.yaml）	规则列表	没有 harness → 通用规则
W03	deterministic	模块名称	Grep 名称；修改共用代码 → impact-check 后再 safe-change	没有重复	有重复 → 修改旧模块
W04	judgment	变更	提出草案，STOP 等待批准	批准	未批准 → blocked
W05	effect	已批准的草案	精简修改 → 验证 → 留痕（按工作类型执行 B01–B03）	变更 + 测试通过	报错 → 修复并重复
W06	deterministic	涉及的 path	修改 hook/engine/installer/CI 的 path 前，先查看下游映射	path 通过 overstack_paths.py	bare_path_lint 报错 → 修复
W07	effect	会话中的问题	结束 turn 前检查并更新 problem-tree	已更新的树	不存在 → 根据模板创建

各步骤详情（W01–W06、Pre-flight 的事实来源）：

1. 修改前先拉取 — 同步 base，不要基于旧版本操作。
2. 了解规则 — 如果 repo 有 harness：查看 rule-registry / policy.yaml。通用规则始终适用：wiki 文件必须包含 ## Origin；不要写入 raw/；wiki 文件必须放在正确的子文件夹（concepts/entities/sources/draft/…）；proposal 必须包含成对的 .md 和 .html 文件。
3. 不要踩到旧模块 — 创建新的 skill/validator/script/hook 前，先 grep 名称，查看是否已存在；修改共用代码时，先映射 caller（impact-check），再 safe-change。
4. 先提出方案 — 所有变更都要先起草计划，STOP 等待批准；不要直接写代码。
5. 精简修改 → 验证 → 留痕 — 只修改必须修改的内容；运行 test/drift-test；更新 registry/log。 提交时使用明确的 stage pathspec，不要用 git add -A/./commit -a：多个会话共用同一工作树，批量暂存会带上其他会话尚未完成的工作（框架 repo 中由规则 P1 no-bulk-stage 拦截）。
6. 客户端布局 ≠ repo 布局 — 修改 hook/engine/installer/CI 中的 path 前：先阅读下方的“下游映射”部分；裸路径 llmwiki/ harness/ 仅适用于此 repo。

分支

ID	类型	条件	行为	跳过 / 失败	回到
B01	conditional_required	工作是提炼/编写 skill	按“提炼 / 编写一个 skill”部分执行	—	W06
B02	conditional_required	正从其他项目开发，且没有 fdk/tools	kit：拉取 → 在 kit 中提炼 → check → 提交 PR	如果在 overstack repo 中 → 跳过拉取步骤	W07
B03	capability_optional	当前在框架 repo 中（完整版本文件存在）	阅读完整版本；修改完 SKILL.md 后 → sync-skill.sh	文件不存在 → 跳过	W06
B04	conditional_required	即将推送/提交 PR	运行 ci-local.py，然后运行 /fdk-uat（RULE-01）	报错 → 不推送	W07

验证与停止

确定性检查：test/drift-test、skill 的 swh-lint.py、ci-local.py、fdk-kit.sh check、HTML 的 verify-theme-motion。需要人工批准：在 W04 提出 draft。只有检查完 problem-tree（W07）后才能结束 turn。

示例

• 正例： 在框架 repo 中“/fdk 为 medic 添加新的 probe” → 拉取，grep medic.py（不创建零散的工具），提出草案并等待批准 → 精简修改 + 测试 → 推送前确认 ci-local.py 通过 → 添加 problem-tree 节点 status: solved、scope: ["harness"]，显示橙色的“solved 1/3 trụ”。
• 边界/失败： 在其他项目中，想把刚提炼的 skill 推送到 overstack，但输入 python3 fdk/tools/new-skill.py → 文件不存在（ADR-004）→ 切换到 B02：将 kit 拉取到 .overstack-kit/，在 kit 中提炼，运行 fdk-kit.sh check，然后 submit。

参考 — 下游布局 — 你看到的内容并非客户端机器上运行的内容

框架仓库（当前打开）	客户端执行 curl bootstrap.sh 后	备注
llmwiki/	.llmwiki/	wiki · raw · html · .harness-stamp
harness/	.harness/	仅包含 poc-vendor-neutral/ + foundation.yaml + metrics/；不包含 scripts/ validators/
harness/scripts · harness/validators · fdk/tools · llmwiki/.claude/hooks	~/.claude/harness/（全局）	共用引擎；hook 由 ~/.claude/settings.json 触发
fdk/wiki/	不存在	仅限框架
skills/*/SKILL.md	~/.claude/skills/	通过 npx 安装，不在项目仓库中
无	CAPABILITIES.md · .overstack.yaml · 根目录 .claude/settings.json	仅存在于下游

机器可读来源：harness/downstream-contract.yaml → layout_map。规则：涉及下游的路径必须经过 harness/scripts/overstack_paths.py（引擎）或 hooklib.overstack_dir/harness_dir/stamp_path（hook）；bare_path_lint 会在路径硬编码时报错。真实行为测试：bash harness/tests/dot-layout-runtime-test.sh .（dot 布局 fixture，隔离的 HOME）。请记住：rg/Grep 会忽略点号开头的目录 — 检查下游项目时请使用 --hidden。

提炼 / 编写技能（适用于任意项目）

• 按 solid-what-how/1（SWH） 标准编写原生技能：frontmatter 包含 name + description + metadata.design-standard: "solid-what-how/1"，接着是 ## WHAT（目的/触发条件/非目标 · 心智模型 · 输入/输出契约 · 带 ID 的规则 · 失败边界）和 ## HOW（主工作流 W01… 表格，包含 exit/next · 分支，或明确写出“没有次级分支” · 验证/停止条件 · 正向示例 + 边界示例）。完整框架：使用 solid-what-how 概念（框架仓库）或通过 new-skill.py 生成。
• description 必须提供充分的触发信息 — 明确说明何时调用（关键词、场景）；router 会据此选择技能。
• 如果有 catalog，先查找范例再编写（Reuse Layer SWH v1.1）：python3 fdk/tools/skill-reuse.py search --desc "<任务>" → 若契约匹配，则运行 new-skill.py <名称> --from <asset_id> --params p.json（渲染类型化模板 + 固定 sha256）；若不匹配，则从头编写并附上 --reason。每次创建技能都必须留下 reuse_decision；复用不会免除任何关卡。
• 如果有工具，请检查结构：python3 fdk/tools/swh-lint.py --skills <名称> --ci（仅检查结构；仍须用示例句测试行为）。从上游引入的技能位于 skills/external/，不要按 SWH 重写。
• 保持自包含：不要引用仅存在于某一个仓库中的文件；如有需要，请写明“如果文件 X 存在，则……”。
• 编写后：用 1–2 个示例句测试技能是否能正确触发。

参考 — 清单 — 别相信记忆中的数字，实时计数（路径取决于仓库布局）

ls -d skills/*/ 2>/dev/null | wc -l                                   # số skill
ls harness/validators/*.py 2>/dev/null | wc -l                        # số validator
grep -cE 'id: R' harness/poc-vendor-neutral/policy.yaml 2>/dev/null   # số rule

参考 — 问题树 — 整个框架的通用问题台账（不局限于 /fdk）

llmwiki/html/fdk-problem-tree.html 是所有框架问题的唯一台账——任何涉及框架工作的 skill/会话（propose、harness-update、orca-workflow……）发现或解决问题时，都必须更新它；/fdk 是守门人：每次调用 /fdk 时，都必须在结束本轮之前检查并更新问题树（如果文件不存在，就从模板创建；如果当前不在框架仓库中，但项目有 llmwiki/，则使用同名的项目本地路径）：

• 形式：采用 /docs-site-macos 风格（liquid-glass）的单文件 HTML。内容 = 问题树——每个节点都是会话中遇到的一个问题；节点之间通过由 JS 自绘的 SVG 连接线连接父节点→子节点（测量 getBoundingClientRect，调整大小时重绘）——不要硬编码坐标。
• 数据与标记分离：所有节点都放在一个 <script type="application/json" id="tree-data"> 代码块中；每次更新只增改 JSON，不要动标记。每个节点：{id, parent, title, desc, status: solved|partial|open, scope: "full" | ["harness"|"skills"|"llmwiki"...], date, solvedBy?, session?}。
• Scope 是按 3 个支柱划分的固定变量："full" = 解决全部 3 个支柱（harness + skills + llmwiki）；否则列出已覆盖的支柱（例如 ["skills"] = 仅在 skill 层解决）。如果 status: solved 但 scope 不是 full，问题树必须明确显示“已解决 x/3 个支柱”——不能让人误以为问题已完全解决。
• 历史只追加：不要删除旧节点；问题解决后，修改 status 并填写 solvedBy（通过哪个 skill/rule/commit 解决）。
• 颜色按覆盖程度划分，而非按 status 划分：只有完整解决 3/3 个支柱时才显示绿色；覆盖程度由低到高的颜色顺序：0/3（尚无解决方案——最严重）= 红色 #ef4444 → 1/3 = 橙色 #f97316 → 2/3 = 黄色 #eab308 → 3/3 = 绿色 #22c55e。徽标中注明 x/3。部分解决的问题绝不能显示绿色。

适配到 overstack remote — 在其他项目中开发时

如果正在进行其他项目，想提炼一个 skill 并提交到 overstack？该项目中没有 fdk-gate + fdk/tools（这是有意为之——ADR-004），所以要先将 kit 拉到沙盒中，再通过 PR 提交——不要随意手动修改：

1. 拉取 kit（首次使用——直接从远程运行，无需本地文件）：

   bash <(curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/fdk/tools/fdk-kit.sh) pull
   

   → 将 overstack 克隆到 .overstack-kit/（自动添加到 .gitignore，不会触碰你的项目）。
2. 在 kit 中提炼 skill： cd .overstack-kit && python3 fdk/tools/new-skill.py <tên> → 编写 SKILL.md → 注册（mirror + LOOP_MAP + AGENT/CLAUDE 表格 + CAPABILITIES — pre-flight #3 + checklist）。
3. 检查： bash .overstack-kit/fdk/tools/fdk-kit.sh check — fdk-gate 的 15 个步骤全部通过才有效。
4. 提交（自动创建 PR）： bash .overstack-kit/fdk/tools/fdk-kit.sh submit skill/<tên> "<mô tả>" → gate 通过 → 推送分支 → 通过 gh pr create 将 PR 提交到 orca。

如果正在 overstack 仓库中，则跳过拉取步骤——直接在仓库中运行 fdk-kit check / submit。

如果正在框架仓库（Rheinmir/setup）中——完整版本

以下文件仅存在于框架仓库中，不会分发到其他项目（这是有意为之——ADR-004）。如果这些文件存在，请阅读以获取详细版本：

• fdk/wiki/concepts/fdk.md — 完整的入口文档（pre-flight + 按类型划分的模块映射）。
• fdk/docs/CONTRIBUTING.md — 添加/修改 harness 规则的运行手册（content-check / hook-event / process-gate；下一个编号为 R13）。
• fdk/README.md + fdk/tools/ — kit 目录（例如 build-cheatsheet.py）。
• 修改完 SKILL.md 后 → bash fdk/tools/sync-skill.sh <tên> — 一条命令将 canonical 同步到 llmwiki 镜像和 ~/.claude 安装版本，并自动验证一致性。不要手动逐个复制版本（会导致源文件漂移——eval 020726）。
• llmwiki/html/*-fdk-docs.html — HTML 阅读版。