finchtoys/finch-releases/community-manager

Community Manager — finch-releases 推荐索引管理

核心定位

管理 community/ 目录下的 4 个 JSON 注册文件，这些文件是 Finch App 市场和社区网站的数据源：

这些文件通过 Cloudflare Worker 发布到 community.finchwork.app。Worker 源码位于相邻项目的 ../finch/scripts/community.finchwork.app/worker.js；发布后必须执行本 skill 的「发布与缓存刷新」流程，不能只等待 TTL。

文件格式规范

mini-tools.json 条目 schema

{
  "id": "mcp",                              // 唯一 ID
  "version": "1.0.0",                      // 最新版本号（必填）
  "name": "MCP Bridge",                     // 展示名
  "author": "Finch Team",                   // 作者
  "description": "一句话描述",               // 英文描述
  "repo": "finchtoys/finch-releases",       // GitHub owner/repo
  "npm": "@finchtoys/mcp-bridge",           // (可选) npm 包名，支持一键安装
  "extensionType": "official",              // (可选) "official" | "community"，默认 "community"
  "installScope": "global",                 // (可选) "global" | "local"
  "categories": ["developer"],               // 分类标签
  "featured": true,                          // (可选) true 则成为客户端精选推荐
  "deprecated": true                         // (可选) 标记已弃用
}

skills.json 条目 schema

{
  "id": "docx",                             // 唯一 ID
  "name": "Document",                       // 展示名
  "author": "Finch Team",                   // 作者
  "description": "一句话描述",               // 英文描述
  "repo": "finchtoys/finch-releases",       // GitHub owner/repo
  "installScope": "global",                 // (可选) "global" | "local"
  "categories": ["productivity", "creative"], // 分类标签
  "featured": true,                            // (可选) true 则成为客户端精选推荐
  "deprecated": true                           // (可选) 标记已弃用
}

zh-CN 覆盖条目 schema（只含用户可见字段）

{
  "id": "mcp",                              // 必须匹配英文条目的 id
  "name": "MCP 桥接",                       // 中文展示名
  "description": "连接 MCP 服务..."          // 中文描述
}

分类标签固定列表

productivity（效率） | developer（开发） | creative（创意） | research（研究） | finance（金融） | commerce（电商） | education（教育）

格式规则

• 2 空格缩进，条目按 id 字母序排列
• 英文文件保留完整字段，中文覆盖只含 id/name/description
• 末尾换行，不允许尾随逗号

工作目录

cd ../../..  # finch-releases 仓库根目录

发布与缓存刷新

完成 JSON 修改并通过 validate.py 后，按以下流程发布；不要只推送 GitHub 后等待缓存过期。

1. 提交并推送 community/*.json 变更到 main。
2. 编辑 ../finch/scripts/community.finchwork.app/worker.js，将 CACHE_VERSION 递增（例如 v2 → v3）。版本化 cache key 会让所有 PoP 绕过旧的 caches.default 条目；cache.delete() 只保证当前 PoP 清理，不能作为全局刷新方案。
3. 部署 Worker。当前 Worker 名称为 fancy-feather-a91f：

``bash npx wrangler deploy ../finch/scripts/community.finchwork.app/worker.js \ --name fancy-feather-a91f \ --compatibility-date 2026-08-28 ``

部署前确认已运行 npx wrangler login 或在安全环境设置了 CLOUDFLARE_API_TOKEN。不要把 token 写入仓库。

1. 调用 Worker 的受保护 purge 接口，并请求索引完成预热。

• PURGE_SECRET 必须同时配置在 Cloudflare Worker 的 Secret variables 与本机 `finch-releases/.env`；.env 必须被 Git 忽略，绝不在聊天、日志或提交中暴露。
• .env 可能包含签名等非 Shell 格式字段，不要 `source .env`。
• 仅在进程内读取 PURGE_SECRET；不要输出、记录或提交该密钥。

``bash node -e ' const fs = require("node:fs"); const { execFileSync } = require("node:child_process"); const line = fs.readFileSync(".env", "utf8").split(/\r?\n/) .find((value) => value.startsWith("PURGE_SECRET=")); if (!line) throw new Error("PURGE_SECRET is not configured"); const raw = line.slice("PURGE_SECRET=".length).trim(); const quoted = raw[0] === "\"" || raw.charCodeAt(0) === 39; const secret = quoted && raw.at(-1) === raw[0] ? raw.slice(1, -1) : raw; execFileSync("curl", [ "-sS", "--fail-with-body", "-X", "POST", "https://community.finchwork.app/purge?file=mini-tools.json", "-H", Authorization: Bearer ${secret}, ], { stdio: "inherit" }); ' ``

新 CACHE_VERSION 首次 purge 返回 "deleted": false 属正常；接着访问索引，确认 X-Cache: MISS 且内容已更新，即完成预热。若返回 401，检查本机 .env 与 Cloudflare Secret 是否完全一致并已重新部署；若返回 404，说明线上 Worker 尚未部署包含 /purge 路由的版本。

1. 验证线上内容。首次响应应为 X-Cache: MISS，之后访问会变为 HIT：

``bash curl -sS -D - 'https://community.finchwork.app/mini-tools.json' | \ grep -E 'X-Cache|"id": "markdown-editor"' ``

Worker 的 JSON 缓存只保留 caches.default 一层；不要为 JSON 上游 fetch() 再设置 cf.cacheTtl，否则 purge 后仍可能读取到旧的上游缓存。

操作指令

概览

为什么用脚本而不是直接 Edit JSON？ JSON 数组的 Edit 操作容易破坏格式（尾逗号、缩进不对、字母序错乱）。用 Python 脚本保证写入格式一致，自动排序。查看和展示变更摘要时用 Read 工具即可。

前置：收集用户意图

每次操作前先 Read 相关 JSON 文件了解当前状态，然后和用户确认字段。不要跳过收集环节直接写入。

操作 1：查看（使用 Read 工具）

# 列出所有小工具
Read community/mini-tools.json
 
# 列出所有技能
Read community/skills.json
 
# 查看中文覆盖
Read community/mini-tools.zh-CN.json
Read community/skills.zh-CN.json

展示格式示例：

## 扩展推荐 (2)
 
| id | name | author | categories | deprecated |
|---|---|---|---|---|
| github-copilot-chat | GitHub Copilot Chat | Finch Team | developer | — |
| mcp | MCP Bridge | Finch Team | developer | — |

操作 2：新增（使用脚本）

交互流程：

1. Read 当前文件，确认现有条目
2. 逐项收集用户输入，必须同时询问中英文
3. 必填：id, version, name(英), author, description(英), repo
4. version 优先从 extensions/<id>/package.json#version 读取，社区扩展查 npm registry 获取
5. 中文必填：name_zh, description_zh
6. 选填：npm(仅扩展), extensionType(默认community), installScope, categories, featured
7. 校验 id 格式（小写字母、数字、连字符）和唯一性
8. 执行脚本

cd ../../..
 
python3 .finch/skills/community-manager/scripts/manage_registry.py add mini-tool '{
  "id": "my-ext",
  "version": "0.1.0",
  "name": "My Extension",
  "author": "Me",
  "description": "Does something useful.",
  "repo": "me/my-repo",
  "npm": "@me/finch-ext-my",
  "extensionType": "community",
  "categories": ["productivity"],
  "name_zh": "我的扩展",
  "description_zh": "做了些有用的事。"
}'

python3 .finch/skills/community-manager/scripts/manage_registry.py add skill '{
  "id": "my-skill",
  "name": "My Skill",
  "author": "Me",
  "description": "A useful skill.",
  "repo": "me/my-repo",
  "categories": ["developer"],
  "name_zh": "我的技能",
  "description_zh": "一个有用的技能。"
}'

操作 3：更新（使用脚本）

# 更新小工具的 description 和 categories
python3 .finch/skills/community-manager/scripts/manage_registry.py update mini-tool mcp '{
  "description": "New description.",
  "categories": ["developer"]
}'
 
# 同时更新中文覆盖（name_zh/description_zh 字段触发 zh-CN 写入）
python3 .finch/skills/community-manager/scripts/manage_registry.py update mini-tool mcp '{
  "description": "New description.",
  "description_zh": "新描述。"
}'

支持的更新字段：

• 英文：version, name, author, description, repo, npm, extensionType, installScope, categories, featured
• 中文：name_zh, description_zh（传入这两个字段会自动更新或创建 zh-CN 条目）

操作 4：删除（使用脚本）

Finch 端暂未支持 deprecated 过滤，所以「拿掉」= 直接删除条目（包括 zh-CN 覆盖）。

等 Finch 支持 deprecated 过滤后再改为软删除方案。

# 删除一个小工具或技能条目
python3 .finch/skills/community-manager/scripts/manage_registry.py remove mini-tool old-ext
python3 .finch/skills/community-manager/scripts/manage_registry.py remove skill theme-factory

操作 5：校验（使用脚本）

python3 .finch/skills/community-manager/scripts/validate.py

校验内容：

1. JSON 合法性 — 每个文件是否能被解析
2. 必填字段 — mini-tools: id/version/name/author/description/repo；skills: id/name/author/description/repo
3. id 格式 — 小写字母、数字、连字符
4. id 唯一性 — 无重复 id
5. 分类合规 — categories 只使用固定 7 个分类 ID
6. 字母序 — 条目按 id 排序
7. 中文覆盖完整 — 每个英文条目有对应 zh-CN 条目
8. 中文覆盖无多余 — zh-CN 中无已移除的条目
9. 扩展 id 一致性 — 检查 id 是否与 extensions/<id>/package.json#finch.id 匹配

操作 6：同步中文覆盖（交互式）

当英文文件新增了条目但 zh-CN 还没跟随时执行：

1. 运行 validate.py 找出缺失的 zh-CN 条目
2. 逐条询问用户对应的中文 name 和 description
3. 用 manage_registry.py update 逐条写入

变更摘要规范

每次修改后，在对话中输出以下格式的摘要：

## 变更摘要
 
### 新增
- [extension] `github-copilot-chat` — GitHub Copilot Chat
- [extension] `github-copilot-chat` (zh-CN) — GitHub Copilot Chat 扩展
 
### 修改
- [skill] `find-skills` — description 已更新
- [skill] `find-skills` — categories 改为 productivity
 
### 删除
- [skill] `theme-factory` — 已移除
 
### 文件变更
- community/mini-tools.json — 新增 1 条
- community/mini-tools.zh-CN.json — 新增 1 条
- community/skills.json — 修改 1 条
 
### 下一步
请 review 变更，确认后手动 git commit。

重要原则

• community/*.json 是 Finch App 市场的数据源，格式错误会导致 App 端解析失败。每次修改后用 validate.py 自我校验。
• zh-CN 覆盖是可选降级，新增条目时必须同时写入。更新纯技术字段（repo, npm 等）不需要同步中文。
• deprecated 是软删除，保留条目但 Finch 端过滤不显示。永远不要删除条目。
• 字母序让 diff 清晰可读，脚本自动处理排序，无需手动插入位置。
• 变更摘要是给用户的，不是 commits，用户据此决定是否 git commit。