From d8faa7cc21fb722253d9882e7d9993d967d8b1f9 Mon Sep 17 00:00:00 2001 From: Eliauk Date: Fri, 21 Aug 2026 05:00:47 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E8=A1=A5=E9=BD=90=E5=AE=89?= =?UTF-8?q?=E8=A3=85=E6=AD=A5=E9=AA=A4=EF=BC=8C=E5=8C=BA=E5=88=86=20Skill?= =?UTF-8?q?=20=E6=9C=AC=E4=BD=93=E4=B8=8E=20DSH=20=E6=8F=92=E4=BB=B6?= =?UTF-8?q?=E5=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新用户此前卡在第一步——原文只说「把仓库目录交给你的 AI Agent」， 没有一条可复制的命令；PR #4 之后根目录多了一层 TS 构建产物， 只用 Skill 的人也无从判断哪些文件可以忽略。 - 「怎么用」第 1 步给出 git clone 命令，并说明无需编译和预装依赖 - 补充生成的主题往哪放（站点目录 themes/，附 customConfig 需重启才生效的提醒） - 目录结构标注 Skill 本体 vs DSH 插件封装，后者明确标为可忽略 - DSH 一句话扩成一节，讲清谁需要、谁可以跳过 - 开发环境说明 jinja2 只有 render_test 需要，且会自动安装 - SKILL.md 描述去掉会过时的「5 步 + 16 条」（实为 6 步，规则按引擎分组） - 散文标点对齐仓库全角惯例（prompt 示例代码块内保持原样） Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 766c171..d3b4f47 100644 --- a/README.md +++ b/README.md @@ -20,38 +20,49 @@ ## 是什么 Gridea Pro 专属的主题构建 AI Agent Skill。 -将该 Skill 加载到支持 Skill 规范的 AI 客户端(Claude Code / Claude Desktop / Cursor / Cline 等)后,你用自然语言描述风格和需求,AI 就会产出一个完整的 Gridea Pro 主题目录,可直接复制到 `themes/` 下使用。 +将该 Skill 加载到支持 Skill 规范的 AI 客户端（Claude Code / Claude Desktop / Cursor / Cline 等）后，你用自然语言描述风格和需求，AI 就会产出一个完整的 Gridea Pro 主题目录，可直接复制到 `themes/` 下使用。 -内置三种模板引擎支持:**Jinja2(推荐)**、**Go Templates**、**EJS**,以及完整的变量参考、避坑指南和渲染测试脚本。 +内置三种模板引擎支持：**Jinja2（推荐）**、**Go Templates**、**EJS**，以及完整的变量参考、避坑指南和渲染测试脚本。 ## 怎么用 -**1. 加载 Skill**——把本仓库目录交给你的 AI Agent(例如 clone 到 `~/.claude/skills/` 或项目根目录)。 +**1. 装上 Skill** -**2. 自然语言下指令**: +```bash +git clone https://github.com/Gridea-Pro/theme-builder-skill.git \ + ~/.claude/skills/gridea-theme-builder +``` + +其他 Agent 放到它约定的 skill 目录即可，或者直接把仓库目录交给它。入口是根目录的 `SKILL.md`，**不需要编译，也不需要预装依赖**。 + +**2. 自然语言下指令** ``` 帮我用 gridea-theme-builder 生成一个叫 "minimal-ink" 的 Jinja2 主题, 极简风格、墨黑配米白、支持暗色模式。 ``` -**3. 取走主题目录**——AI 跑完会自动执行 `scaffold → validate → render` 全流程,把通过测试的主题目录交给你,复制到 Gridea Pro 的 `themes/` 即可使用。 +**3. 取走主题目录** + +AI 跑完会自动执行 `scaffold → validate → render` 全流程，把通过测试的主题目录交给你。复制到 Gridea Pro 站点目录下的 `themes/`（默认 `~/Documents/Gridea Pro/themes/`），在应用里切换主题即可。 + +> 站点目录可以在 Gridea Pro 里修改，以应用中显示的路径为准。另外，主题装好后若又改动了 `config.json` 里的 customConfig 声明，需要重启应用才会生效。 ## 搭配前端设计 Skill 效果更好 -本 Skill 只负责"生成能跑通的主题",**美感不是它的强项**。推荐的组合工作流: +本 Skill 只负责"生成能跑通的主题"，**美感不是它的强项**。推荐的组合工作流： ``` frontend-design → gridea-theme-builder → web-design-guidelines (先出视觉方向) (落地成主题) (审查无障碍/响应式) ``` -常用搭档:`frontend-design`、`ui-ux-pro-max`、`brand-guidelines`、`web-design-guidelines`、`theme-factory`(以上为 Claude 生态 Skill 名,其他 Agent 请找对等物)。 +常用搭档：`frontend-design`、`ui-ux-pro-max`、`brand-guidelines`、`web-design-guidelines`、`theme-factory`（以上为 Claude 生态 Skill 名，其他 Agent 请找对等物）。 ## Prompt 模板
-两阶段:先设计、后生成 +两阶段：先设计、后生成 ``` 阶段 1:用 frontend-design 为个人技术博客设计视觉方向。 @@ -96,7 +107,7 @@ CustomConfig 用 index 访问,跑通 validate 和 render 测试。 ``` . -├── SKILL.md # Skill 入口,5 步工作流 + 16 条关键规则 +├── SKILL.md # Skill 入口：完整工作流 + 三引擎关键规则 ├── references/ # 变量清单、三引擎指南、架构、SEO、CSS 模式等 ├── scripts/ │ ├── scaffold_theme.py # 生成脚手架 @@ -107,11 +118,17 @@ CustomConfig 用 index 访问,跑通 validate 和 render 测试。 └── mock-data.json # 测试 fixture ``` -> `CLAUDE.md` 是 Claude Code 专属的元指令文件,其他 Agent 与人类用户可忽略。 +以上是 **Skill 本体**。根目录另有一层 DSH 插件封装（`src/`、`lib/`、`package.json`、`tsconfig.json`、`cordis.patch.yml`、`overlay.yml`）—— 只用 Claude / Cursor 这类 Skill 客户端的话，**这些文件可以完全忽略**，不影响任何功能。 + +> `CLAUDE.md` 是 Claude Code 专属的元指令文件，其他 Agent 与人类用户可忽略。 + +## 作为 DSH 插件使用（可选） -## 作为 DSH 插件使用 +如果你用的是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)，而不是 Claude Code 一类的 Skill 客户端，本仓库额外提供了一层插件封装，把同一份 `SKILL.md` 注册成 DSH 的 skill provider。两边共用同一份内容，不存在不同步的问题。 -本 Skill 也可作为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件运行,安装方式和说明详见 [src/README.md](src/README.md)。 +安装步骤、本地调试与常见问题见 [src/README.md](src/README.md)。 + +**用 Claude / Cursor 的话，跳过本节即可。** ## 开发环境 @@ -119,6 +136,8 @@ CustomConfig 用 index 访问,跑通 validate 和 render 测试。 pip install -r requirements.txt # 仅需 jinja2 ``` +通常不必手动执行：`scaffold_theme.py` 和 `validate_syntax.py` 是纯标准库，开箱即用；只有 `render_test.py` 需要 jinja2，且它会在缺失时自动安装。 + ## 许可 [MIT](LICENSE)。