用途：提供一个从零构建 Gety 自定义连接器的标准化工作流，把任意数据源（API、SaaS 应用、数据库或本地文件）转换为可搜索的 Gety 文档。
前置条件：需要 git（克隆样例仓库）、deno（样例通过 deno task 构建、测试和运行，不需要 Node；若缺失需指向 https://deno.com 安装），以及安装了 Gety 桌面应用并启用 CLI 集成（仅用于安装和用 gety search / gety doc 验证，非构建测试必需）。
主要能力与工作流：
- 编辑前检查连接器仓库。新连接器必须从 https://github.com/gety-ai/gety-sample-connector 开始，不得手工创建骨架；若当前仓库不是其克隆或分叉，需先切换或克隆。修改 manifest 结构、SDK 生命周期、doc_link、metadata、state、文件/下载行为或校验命令前，需阅读 references/gety-custom-connector-contract.md。
- 编码前澄清数据源语义：确认认证方式、必需配置字段、文档标识、标题/内容映射、源创建与更新时间、删除处理及链接行为；向用户说明内容提取方案并确认哪些字段成为 Gety 的 title、content、metadata 和链接。若涉及 OAuth 浏览器登录、临时签名 URL、懒加载远程文件预览/下载、二进制提取或混合 URL/文件链接，需停止并讨论，当前技能范围不端到端覆盖这些能力。
- 设计文档契约：选择稳定 id 和连接器自有的 doc_type（如 linear:issue）；仅在内容确为 markdown 时设置 content_format: "markdown"，标题、URL、按行分隔的字段等纯文本保持默认 "plaintext"；稳定浏览器 URL 放入 metadata.url 并使用 manifest doc_link: { "kind": "url", "field": "url" }；用 doc_updated_at 表示源文档更新时间，metadata.created_at 表示源创建时间。
- 实现 src/index.ts：继承 Connector<ManifestConfig, State> 并实现 async *poll()；ManifestConfig 由 manifest 的 config.fields 经 deno task generate 生成到 src/gen/manifest.d.ts，因此需先改 manifest.json 再重新生成；使用 this.config、this.lastState、this.signal，onLoad 可选且可为异步；边拉取边流式产出批次，仅在对应批次 yield 后持久化 state 游标；不要依赖类字段做跨轮询缓存，每次轮询都是新的运行时进程。
- 更新 manifest.json：entry 指向已提交的构建产物（通常 dist/main.js）；capabilities 必填且非空，轮询/索引数据源需声明 ["data-source"]；用 min_gety_app_version（SemVer）声明 Gety 兼容性；schedule 支持 manual、interval（interval_seconds）或 daily（time: HH:mm），省略则用 Gety 默认；面向作者的字段用小写/snake_case 和有效类型；不得添加 permissions、mode、动态每文档钩子或每文档 doc_link 等不支持的字段。
- 本地校验与安装：运行 deno task verify，或分别执行 generate、格式化/检查、lint、测试和构建；如配置需要密钥，告知用户自行放入 .env（如 API_KEY 或 GETY_CONFIG_API_KEY），不要让其粘贴到聊天中；用 deno task runner -- --reset-state 或重复轮询验证文档、删除、state 和增量行为，结束后报告输出目录 dev/runs/<timestamp>/ 并检查关键文件；用 gety connector install <dir> --dry-run 试运行，再执行 gety connector install <dir> [--config <file> | --set key=value] 安装（或通过 Gety 设置界面安装）；用 gety connector show <connector_id> 或 gety connector list --kind custom 查看状态；用 gety connector poll <connector_id> 触发同步；改代码后重建（deno task build）并执行 gety connector restart <connector_id>；用 gety search <query> -c "<connector_name>" 验证搜索。
- 添加图标：索引验证后，在连接器根目录放置 PNG/SVG 图片（如 icon.png），并在 manifest 中设置 "icon": "icon.png"（连接器根目录内的相对路径），有官方 logo 时优先复用。
反模式：不要把所有远程条目拉入内存后一次性 yield；不要把临时签名 URL 或临时本地缓存路径写入 doc_link；不要在 metadata 中存大块数据，可搜索/可渲染文本应放入 content；不要把 metadata.updated_at 当作固定契约，应使用 doc_updated_at；不要在类构造函数中读取 this.config、this.lastState、this.signal（宿主在构造后注入，构造时仍是默认值），应在 onLoad 或 poll 中读取；不要手工编辑生成的 dist/main.js，应改 src/index.ts 后重建。
适用场景：需要将内部 API、SaaS 应用、数据库或本地文件接入 Gety 搜索索引，并希望遵循样例仓库和校验流程的场景。
限制：当前技能范围不涵盖 OAuth 浏览器登录、临时签名 URL、懒加载远程文件预览/下载、二进制提取和混合 URL/文件链接等端到端能力，遇到时需停止并讨论。