polygres-data-pipeline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Polygres Data Pipeline

Polygres 数据管道

Turn setup intent into the smallest complete working result. Adapt to what the user actually needs. Do not force every setup through schema creation, embeddings, graph, backfill, continuous capture, retrieval code, or agent instructions.
将设置意图转化为最小的完整可用结果。适配用户的实际需求。无需强制所有设置都经过schema创建、embeddings、graph、回填、持续捕获、retrieval代码或Agent指令这些流程。

Use guidance at the right strength

适度使用指南

Treat this skill as a decision guide, not a mandatory architecture or ordered checklist. Adapt, reorder, replace, or omit recommended components and numeric defaults when inspected evidence or the user's outcome supports a better design. Numeric defaults are starting points, including sample sizes, result counts, token budgets, recall timing, capture timing, and model rankings.
Keep only safety and correctness boundaries firm: preserve authorization and provenance, keep secrets out of plans and payloads, disclose and approve material effects, use compatible embedding contracts, avoid unsupported public interfaces and invented graph relationships, and test the important selected path before calling it operational.
将本技能视为决策指南,而非强制性架构或有序检查清单。当检查到的证据或用户的预期结果支持更优设计时,可调整、重排、替换或省略推荐组件及数值默认值。数值默认值仅作为起点,包括样本量、结果数量、token预算、召回时机、捕获时机及模型排名。
仅严格遵守安全与正确性边界:保留授权与来源信息,不将机密信息纳入计划和负载,披露并批准实质性影响,使用兼容的embedding协议,避免使用未受支持的公共接口和虚构的graph关系,在宣布可运行前测试选定的关键路径。

Recognize setup intent

识别设置意图

Activate for broad prompts such as "Help me set up Polygres," contextual prompts such as "look at my conversations and set up Polygres," and detailed technical specifications. Treat examples as illustrations, not required wording.
For a question such as "What can I do with Polygres?", use a personalized recommendation branch. Inspect the accessible current workspace and any uniquely resolved Polygres project with bounded, read-only checks. Look only at the data shape, existing retrieval configuration, and application or agent entry points needed to identify useful opportunities. Then give a short answer that says what was found, leads with the most useful Polygres outcome for this project, and mentions only relevant alternatives. Do not return a generic feature list, create a plan, scaffold files, or mutate anything. End with a direct next step such as:
text
To proceed, reply: Set up the recommended Polygres pipeline.
Treat that reply or an equivalent acceptance as setup intent. Carry the inspected source, project, outcome, and recommendation into the setup flow without repeating discovery unless the evidence is stale. This acceptance starts setup; it is not mutation approval. Prepare the implementation and show the normal consolidated review before making covered changes.
If the prompt identifies neither a source or inspectable context nor a desired outcome, do not inspect, design, scaffold, or configure yet. Ask one short direction question first:
text
What would you like Polygres to do, and where is the relevant data? For
example: conversations or agent memory, an existing database, files or an API,
search and retrieval, or connected-data exploration.
Treat a response that identifies a source, an outcome, or both as enough to begin. Infer the remaining reversible details from inspection instead of turning the opening question into a form. Contextual prompts such as "look at my conversations and set up Polygres" and detailed specifications skip this question and proceed immediately.
If the user asks for a generic explanation or design comparison that does not request personalized inspection, use
$polygres-retrieval-design
. If they want a usable project, pipeline, memory, search, ingestion, synchronization, or agent integration, continue here.
针对宽泛提示(如“帮我设置Polygres”)、上下文提示(如“查看我的对话并设置Polygres”)及详细技术规范激活本技能。示例仅作说明,并非必填表述。
对于诸如“我能用Polygres做什么?”这类问题,使用个性化推荐分支。通过有限的只读检查,扫描当前可访问的工作区及任何已明确解析的Polygres项目。仅查看数据形态、现有retrieval配置以及识别有用机会所需的应用或Agent入口点。然后给出简短回答,说明已发现的内容,优先推荐对该项目最有用的Polygres成果,并仅提及相关替代方案。请勿返回通用功能列表、创建计划、搭建文件或修改任何内容。结尾给出明确的下一步操作,例如:
text
如需继续,请回复:设置推荐的Polygres管道。
将该回复或等效的接受视为设置意图。将检查到的数据源、项目、预期结果及推荐内容带入设置流程,除非证据已过时,否则无需重复发现步骤。此接受仅启动设置流程,并非修改批准。在进行涵盖的修改前,需准备好实施方案并展示常规的统一审核内容。
如果提示既未指明数据源或可检查的上下文,也未指明预期结果,则暂不进行检查、设计、搭建或配置。先提出一个简短的方向性问题:
text
你希望Polygres实现什么功能?相关数据存储在哪里?例如:对话或Agent memory、现有数据库、文件或API、搜索与retrieval、或关联数据探索。
将指明数据源、预期结果或两者兼具的回复视为可开始操作的依据。通过检查推断剩余可逆转的细节,而非将初始问题变成表单。诸如“查看我的对话并设置Polygres”这类上下文提示及详细规范可跳过此问题,直接进行下一步。
如果用户询问的是通用解释或设计对比,未要求个性化检查,则使用
$polygres-retrieval-design
。如果用户需要可用的项目、管道、memory、搜索、ingestion、同步或Agent集成,则继续使用本技能。

Move immediately once direction is known

明确方向后立即行动

  1. Parse the prompt and current workspace for source, target project, desired outcome, ownership boundary, freshness, embedding choice, and existing code.
  2. Inspect one bounded source sample and the narrow project capabilities needed for the likely setup. Do not inventory every Polygres surface.
  3. Resolve
    target.project_mode
    before selecting any write, import, migration, database, or retrieval surface. For an existing PostgreSQL source, evaluate managed sync with
    references/synced-projects.md
    before designing custom capture.
  4. Infer reversible defaults. Ask one concise batch of questions only for critical facts that inspection cannot resolve safely. Do not ask about optional components that are unnecessary.
  5. Keep a small internal setup plan when work has multiple actions, then create the local source-specific adapter, privacy filter, writer, retrieval entry point, tests, and operator files that the selected design requires.
  6. Test locally with a small safe sample appropriate to the source. Present one consolidated review before the first upload, remote mutation, modification of active agent instructions, or installation of a runtime integration.
  7. After approval, apply all actions covered by that exact review without repeated prompts, verify a bounded end-to-end slice, then continue any approved backfill or integration.
Do not spend setup time explaining Polygres unless the user asks. Do not read an entire source before a privacy filter exists. Do not stop at a plan or generic scaffold when runnable source-specific code can be produced.
  1. 解析提示和当前工作区,获取数据源、目标项目、预期结果、所有权边界、新鲜度、embedding选择及现有代码。
  2. 检查一个有限的数据源样本及可能的设置所需的窄范围项目功能。无需清点Polygres的所有功能面。
  3. 在选择任何写入、导入、迁移、数据库或retrieval功能面之前,先确定
    target.project_mode
    。对于现有PostgreSQL数据源,在设计自定义捕获前,先参考
    references/synced-projects.md
    评估托管同步方案。
  4. 推断可逆转的默认值。仅针对检查无法安全解决的关键事实,提出一组简洁的问题。无需询问不必要的可选组件相关问题。
  5. 当工作包含多个操作时,保留一个小型内部设置计划,然后创建所选设计所需的本地特定数据源适配器、隐私过滤器、写入器、retrieval入口点、测试及操作文件。
  6. 使用适合数据源的小型安全样本在本地测试。在首次上传、远程修改、修改活跃Agent指令或安装运行时集成之前,展示一份统一的审核内容。
  7. 获得批准后,执行该审核涵盖的所有操作,无需重复提示,验证一个有限的端到端切片,然后继续任何已批准的回填或集成工作。
除非用户要求,否则设置过程中无需解释Polygres。在隐私过滤器创建完成前,无需读取整个数据源。当可生成可运行的特定数据源代码时,无需停留在计划或通用搭建阶段。

Ask only for critical unknowns

仅询问关键未知项

Critical means the answer changes safety or makes the implementation invalid:
  • no unique target project can be resolved;
  • source access or source scope is ambiguous;
  • ownership/authorization cannot be inferred;
  • semantic retrieval is required but inspection finds no compatible local, hosted, or existing-vector path that can be fully disclosed in the review;
  • a destructive, externally visible, paid, or difficult-to-reverse choice has no safe default.
Group critical unknowns into one short request. Prefer a reversible default and state it in the review. Use
references/guided-interview.md
for the initial vague-prompt question or when genuinely blocked; it is not the normal flow for contextual or detailed requests.
关键未知项指答案会影响安全性或导致实现无效的内容:
  • 无法确定唯一的目标项目;
  • 数据源访问权限或范围不明确;
  • 所有权/授权无法推断;
  • 需要语义retrieval,但检查发现没有可在审核中完全披露的兼容本地、托管或现有向量路径;
  • 存在破坏性、外部可见、付费或难以逆转的选择,且无安全默认值。
将关键未知项整合为一个简短的请求。优先选择可逆转的默认值,并在审核中说明。初始模糊提示或真正受阻时,使用
references/guided-interview.md
;但上下文提示或详细请求的常规流程无需使用该文档。

Select only useful components

仅选择有用组件

  • Reuse a suitable table. Create or alter schema only when needed for stable IDs, ownership, provenance, content, timestamps, deletion state, metadata, or selected retrieval inputs.
  • Start with relational or text retrieval when it satisfies the outcome. Add pgContext for meaning, similarity, natural-language recall, or agent memory.
  • Follow an established embedding deployment preference. If it is unknown, silently rank one compatible local recommendation and one hosted alternative and put both in the existing consolidated review. Device feasibility does not imply a local preference. Do not create a separate model questionnaire or a second approval after the user selects a fully reviewed option. Polygres does not generate embeddings.
  • Recommend pgGraph when validated relationships improve the requested retrieval. A single memory table does not by itself justify graph, but self-references or reliably derived relationships may. Omit graph when it adds no value.
  • Add backfill, checkpointing, deletion propagation, and ongoing capture only when the source or freshness requirement needs them.
  • Add retrieval code when the user needs application or agent recall. Choose timing, result bounds, token budget, and fallback for that application while preserving provenance and authorization.
  • Update agent instructions only when an agent should capture or recall. Scope the managed block to the relevant repository or agent, and do not claim guaranteed capture without a tested runtime hook.
Read
references/schema-and-graph.md
for schema and graph decisions and
references/context-and-retrieval.md
for text, embedding, Context, and recall. For semantic retrieval, follow
references/embedding-model-selection.md
and use
scripts/recommend_embedding_models.py
after bounded inspection.
  • 重用合适的表。仅当需要稳定ID、所有权、来源信息、内容、时间戳、删除状态、元数据或选定的retrieval输入时,才创建或修改schema。
  • 当关系型或文本retrieval可满足预期结果时,优先使用。若需要语义、相似度、自然语言召回或Agent memory,则添加pgContext。
  • 遵循既定的embedding部署偏好。若未知,则静默排序一个兼容的本地推荐方案和一个托管替代方案,并将两者纳入现有的统一审核内容。设备可行性并不意味着优先选择本地方案。无需创建单独的模型调查问卷,也无需在用户选择完全审核过的选项后进行二次批准。Polygres不生成embeddings。
  • 当经验证的关系可改善请求的retrieval效果时,推荐使用pgGraph。单一memory表本身不足以证明需要graph,但自引用或可靠推导的关系可能需要。若无价值,则省略graph。
  • 仅当数据源或新鲜度要求需要时,才添加回填、检查点、删除传播及持续捕获功能。
  • 当用户需要应用或Agent召回时,添加retrieval代码。在保留来源信息和授权的前提下,为该应用选择时机、结果范围、token预算及回退方案。
  • 仅当Agent需要捕获或召回时,才更新Agent指令。将管理块的范围限定在相关仓库或Agent,且在未测试运行时钩子的情况下,不得声称可保证捕获。
schema和graph决策请参考
references/schema-and-graph.md
;文本、embedding、Context及召回相关内容请参考
references/context-and-retrieval.md
。语义retrieval请遵循
references/embedding-model-selection.md
,并在有限检查后使用
scripts/recommend_embedding_models.py

Generate a working implementation

生成可运行的实现

Read only the source reference that matches the inspected input:
SourceReference
Agent memory, Codex, Claude Code, or chat export
references/source-chat-agents.md
Existing database, polling, outbox, or change stream
references/source-databases.md
Managed Supabase, Neon, or PostgreSQL sync project
references/synced-projects.md
Files, APIs, webhooks, queues, or mixed input
references/source-files-and-apis.md
Follow
references/pipeline-runtime.md
. The generated implementation must use stable source identities, filter before persistence or embedding, write idempotently, checkpoint only after durable success, expose exact capture and retrieval commands when selected, and include focused tests.
Use the public interface appropriate to each workload:
  • synced project: keep the source database authoritative, hand sync creation and configuration to the dashboard, and use the Runtime API key only for supported retrieval and retrieval configuration;
  • dataset or bounded backfill: reviewed CLI import is normally sufficient;
  • one JSON object or runtime event: use the rows surface when the target and workload pass its read-only validation and deployed limits;
  • runtime record capture: public rows API, SDK, or CLI only when installed client and deployed Runtime compatibility evidence confirm the surface;
  • retrieval: documented SDK or Runtime API;
  • deletion or unsupported/high-throughput writes: use another documented public operation when available, otherwise approved direct Postgres;
  • direct Postgres: only when no public operation satisfies the approved need.
Never apply the standard-project mutation routes to a synced project. Do not probe rows validation, request target database information, or infer that a project API key can call sync control-plane operations.
The single-row contract is available in CLI/SDK
0.3.0
and includes
insert
,
upsert
,
ignore
, and
validate
. If the installed client or project does not contain that endpoint version, mark capture
upgrade-required
, give the exact upgrade requirement, and continue all unaffected setup work. Never infer the endpoint or disguise a bulk import as per-turn capture.
When a bulk import feeds a selected Context collection, reconcile the imported source rows into Context before declaring semantic retrieval operational. The rows API does not delete records; route deletion through an approved source-row deletion path and remove the corresponding Context, text, and graph evidence.
仅读取与检查到的输入匹配的数据源参考文档:
数据源参考文档
Agent memory、Codex、Claude Code或聊天导出
references/source-chat-agents.md
现有数据库、轮询、发件箱或变更流
references/source-databases.md
托管Supabase、Neon或PostgreSQL同步项目
references/synced-projects.md
文件、API、webhook、队列或混合输入
references/source-files-and-apis.md
遵循
references/pipeline-runtime.md
。生成的实现必须使用稳定的数据源标识,在持久化或embedding前进行过滤,实现幂等写入,仅在持久化成功后创建检查点,在选定功能时暴露精确的捕获和retrieval命令,并包含针对性测试。
为每个工作负载使用合适的公共接口:
  • 同步项目:保持源数据库的权威性,将同步创建和配置交给控制台,仅使用Runtime API密钥进行受支持的retrieval和retrieval配置;
  • 数据集或有限回填:经审核的CLI导入通常已足够;
  • 单个JSON对象或运行时事件:当目标和工作负载通过其只读验证和部署限制时,使用rows功能面;
  • 运行时记录捕获:仅当已安装的客户端和部署的Runtime兼容性证据确认该功能面可用时,才使用公共rows API、SDK或CLI;
  • retrieval:使用已文档化的SDK或Runtime API;
  • 删除或未受支持/高吞吐量写入:若有可用的已文档化公共操作,则使用该操作;否则使用已批准的直接Postgres操作;
  • 直接Postgres操作:仅当没有公共操作可满足已批准的需求时才使用。
切勿对同步项目应用标准项目修改路由。切勿探测rows验证、请求目标数据库信息,或推断项目API密钥可调用同步控制平面操作。
单行契约在CLI/SDK
0.3.0
版本中可用,包括
insert
upsert
ignore
validate
。若已安装的客户端或项目不包含该端点版本,则标记捕获为
upgrade-required
,给出确切的升级要求,并继续所有未受影响的设置工作。切勿推断端点,或将批量导入伪装成逐次捕获。
当批量导入为选定的Context集合提供数据时,需在宣布语义retrieval可运行前,将导入的数据源行协调到Context中。rows API不删除记录;需通过已批准的数据源行删除路径进行删除,并移除相应的Context、文本和graph证据。

Keep one execution record

保留一份执行记录

For multi-step work, use
references/pipeline-plan-contract.md
and quietly lint the internal plan with
scripts/validate_pipeline_plan.py
. Automatically fix blockers from available evidence; resolve or accept warnings without turning them into user questions. Never make the user read or edit the plan. Use
scripts/scaffold_pipeline.py
only as a base for selected local files, then add the source-specific runtime. Render the single review with
scripts/render_pipeline_review.py
.
Follow
references/security-and-approvals.md
. One approval covers the reviewed setup while project, source scope, data egress, destructive effects, and paid processing remain unchanged. Implementation details and harmless local files do not invalidate it. Credentials are always local environment-variable values; inspect presence with
scripts/check_env.py
, never their contents.
对于多步骤工作,使用
references/pipeline-plan-contract.md
,并使用
scripts/validate_pipeline_plan.py
静默检查内部计划。根据可用证据自动修复阻塞问题;解决或接受警告,无需将其转化为用户问题。切勿让用户阅读或编辑计划。仅将
scripts/scaffold_pipeline.py
作为选定本地文件的基础,然后添加特定数据源的运行时内容。使用
scripts/render_pipeline_review.py
生成单一审核内容。
遵循
references/security-and-approvals.md
。一次批准涵盖已审核的设置,只要项目、数据源范围、数据流出、破坏性影响及付费处理保持不变,该批准即有效。实现细节和无害的本地文件不会使批准失效。凭据始终为本地环境变量值;使用
scripts/check_env.py
检查是否存在,但切勿查看其内容。

Connect agent capture and recall when selected

选定后连接Agent捕获与召回功能

Use
scripts/update_agent_instructions.py
to add an idempotent managed block to the relevant
AGENTS.md
or equivalent file. Preserve all user-authored text. Prepare a preview before approval. Modify the active instruction file only after the consolidated review is approved. The block may contain capture, recall, or both according to the selected integration. It must name each selected command, say what is safe to store, describe the selected timing, and state the real guarantee.
Agent instructions are guidance. For guaranteed or retryable capture, also wire and test an application hook, wrapper, outbox, worker, or equivalent runtime. Never store system instructions, retrieved context, credentials, attachments, or tool/environment output unless the user explicitly selected and approved that content.
使用
scripts/update_agent_instructions.py
向相关的
AGENTS.md
或等效文件添加一个幂等的管理块。保留所有用户编写的文本。在获得批准前准备好预览内容。仅在统一审核获得批准后,才修改活跃的指令文件。该管理块可包含捕获、召回或两者兼具,具体取决于选定的集成。必须列出每个选定的命令,说明可安全存储的内容,描述选定的时机,并说明实际保证。
Agent指令仅作为指导。若需要保证或可重试的捕获,还需连接并测试应用钩子、包装器、发件箱、工作器或等效的运行时组件。除非用户明确选择并批准,否则切勿存储系统指令、检索到的上下文、凭据、附件或工具/环境输出。

Verify truthfully

如实验证

First prove the selected vertical slice: safe normalization, rejection before egress, idempotent write when applicable, ownership filtering, provenance, and one useful retrieval result. Verify graph or Context readiness only when enabled. Then test update, deletion, retry, resume, reconciliation, and agent integration only when those capabilities were selected.
Report
operational
,
partial
, or
blocked
from observed evidence. Name omitted components as intentionally not selected, not missing. Do not claim remote setup, continuous capture, or retrieval works when only local files were generated.
首先验证选定的垂直切片:安全规范化、流出前过滤、适用时的幂等写入、所有权过滤、来源信息及一个有用的retrieval结果。仅在启用graph或Context时,才验证其就绪状态。然后仅在选定了更新、删除、重试、恢复、协调及Agent集成这些功能时,才对其进行测试。
根据观察到的证据报告
operational
(可运行)、
partial
(部分可运行)或
blocked
(受阻)。将未选择的组件描述为有意省略,而非缺失。仅生成了本地文件时,切勿声称远程设置、持续捕获或retrieval功能已可用。