unleak

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unleak

Use

unleak

for database questions only when the current project has an

unleak/

folder. Unleak reduces leakage risk; it is not a sandbox.

仅当当前项目包含

unleak/

文件夹时，才针对数据库问题使用

unleak

。Unleak可降低泄漏风险，但它并非沙箱环境。

Rules

规则

Never read or edit
```
unleak/local/db-conf.json
```
.

Never edit

unleak/scripts/**

unleak/local/schema/**

, or

unleak/local/active-policies/**

Never run
```
activate-policy.mjs
```
; only suggest the manual command with
```
!node
```
.
Never use raw database CLIs when
```
unleak
```
is configured.
Do not query until schema and an active policy exist.
When schema and an active policy already exist, answer normal data-inspection requests by querying approved data only. Do not propose, validate, activate, or re-create policy unless the user explicitly asks to set up or update policy.
Prefer inline SQL with
```
query.mjs --sql
```
for normal queries. Do not create project-visible query files like
```
./query.sql
```
for routine analysis.
Create a SQL file only when the query is very complex. Put those files under
```
unleak/local/queries/
```
in the skill local state, not in the user's project surface.
Treat Claude permissions as guardrails, not a complete sandbox.
Keep the user's current project directory as the working directory. Relative paths must continue to work for the user.

切勿读取或编辑
```
unleak/local/db-conf.json
```
。

切勿编辑

unleak/scripts/**

、

unleak/local/schema/**

或

unleak/local/active-policies/**

。

切勿运行
```
activate-policy.mjs
```
；仅建议用户使用
```
!node
```
执行手动命令。
当已配置
```
unleak
```
时，切勿使用原始数据库CLI。
在模式和有效策略存在之前，请勿执行查询。
当模式和有效策略已存在时，仅通过查询已批准的数据来响应常规数据检查请求。除非用户明确要求设置或更新策略，否则请勿提议、验证、激活或重新创建策略。
对于常规查询，优先使用带
```
query.mjs --sql
```
的内联SQL。请勿为常规分析创建如
```
./query.sql
```
这类项目可见的查询文件。
仅当查询非常复杂时才创建SQL文件。将这些文件放在技能本地状态的
```
unleak/local/queries/
```
下，而非用户的项目表层目录中。
将Claude权限视为防护规则，而非完整的沙箱环境。
保持用户当前的项目目录为工作目录。相对路径必须对用户持续有效。

Workflow

工作流

Run scripts from the user's current project directory, replacing

.claude/skills/unleak

with the actual

unleak/

folder path.

Important cwd rule:

Do not leave the shell inside the Unleak skill root after installing dependencies.
Prefer
```
npm install --prefix .claude/skills/unleak
```
so the working directory stays at the project root.
If you must change directories to install dependencies, immediately return to the original project directory before retrying scripts or giving the user any relative-path commands.

Check readiness:
```
node .claude/skills/unleak/scripts/check-readiness.mjs
```
If the output reports
```
DEPENDENCIES_NOT_INSTALLED
```
or suggests
```
npm install
```
, run:
```
npm install --prefix .claude/skills/unleak
```
Then retry the same readiness command from the original project directory and continue.
List safe connections:
```
node .claude/skills/unleak/scripts/list-connections.mjs
```
If the user asked to inspect, analyze, query, or find patterns in data and the requested connection already has schema and an active policy, skip setup and policy work. Write focused SELECT queries and run:
```
node .claude/skills/unleak/scripts/query.mjs --connection <name> --sql "SELECT ..."
```
Continue iterating with more SELECT queries until the user's data question is answered. If a query is too complex for inline SQL, create it under
```
.claude/skills/unleak/local/queries/<short-name>.sql
```
and run:
```
node .claude/skills/unleak/scripts/query.mjs --connection <name> --file .claude/skills/unleak/local/queries/<short-name>.sql
```
Only continue to setup steps 3-12 when config, schema, or active policy is missing, or when the user explicitly asks to set up, propose, validate, activate, or update policy.

If config is missing, do not read or create

unleak/local/db-conf.json

. Ask the user to run:

node .claude/skills/unleak/scripts/init-config.mjs

Ask the user to edit
```
unleak/local/db-conf.json
```
manually:
- Set a random
```
hmacSecret
```
  .
- Keep and configure only the connections they need.
- For SQLite, set the database file path.
- For Postgres, set host, port, dbname, username, and password.

When the user says the config is saved, rerun:

node .claude/skills/unleak/scripts/list-connections.mjs

Install deny rules if needed:

node .claude/skills/unleak/scripts/install-claude-settings.mjs

Dump schema:

node .claude/skills/unleak/scripts/dump-schema.mjs

Propose policy:

node .claude/skills/unleak/scripts/propose-policy.mjs

Read schema and proposed policy files. Briefly explain policy recommendations.

Edit only files under

./unleak-policy-review/*.policy.proposed.json

Validate:

node .claude/skills/unleak/scripts/validate-policy.mjs

Ask the user to activate manually:

!node .claude/skills/unleak/scripts/activate-policy.mjs ./unleak-policy-review/<connection>.policy.proposed.json

Query approved data:

node .claude/skills/unleak/scripts/query.mjs --connection <name> --sql "SELECT ..."

从用户当前的项目目录运行脚本，将

.claude/skills/unleak

替换为实际的

unleak/

文件夹路径。

重要的工作目录规则：

安装依赖后，请勿让Shell停留在Unleak技能根目录中。
优先使用
```
npm install --prefix .claude/skills/unleak
```
，这样工作目录会保持在项目根目录。
如果必须切换目录来安装依赖，请在重试脚本或向用户提供任何相对路径命令之前，立即返回原始项目目录。

检查就绪状态：
```
node .claude/skills/unleak/scripts/check-readiness.mjs
```
如果输出报告
```
DEPENDENCIES_NOT_INSTALLED
```
或建议运行
```
npm install
```
，则执行：
```
npm install --prefix .claude/skills/unleak
```
然后从原始项目目录重试相同的就绪状态检查命令并继续。
列出安全连接：
```
node .claude/skills/unleak/scripts/list-connections.mjs
```
如果用户要求检查、分析、查询或查找数据中的模式，且请求的连接已存在模式和有效策略，则跳过设置和策略相关工作。编写目标明确的SELECT查询并执行：
```
node .claude/skills/unleak/scripts/query.mjs --connection <name> --sql "SELECT ..."
```
继续执行更多SELECT查询，直到用户的数据问题得到解答。如果查询过于复杂而无法使用内联SQL，则在
```
.claude/skills/unleak/local/queries/<short-name>.sql
```
下创建查询文件并执行：
```
node .claude/skills/unleak/scripts/query.mjs --connection <name> --file .claude/skills/unleak/local/queries/<short-name>.sql
```
仅当配置、模式或有效策略缺失，或用户明确要求设置、提议、验证、激活或更新策略时，才继续执行步骤3-12的设置流程。

如果配置缺失，请勿读取或创建

unleak/local/db-conf.json

。请用户执行：

node .claude/skills/unleak/scripts/init-config.mjs

请用户手动编辑
```
unleak/local/db-conf.json
```
：
- 设置随机的
```
hmacSecret
```
  。
- 仅保留并配置所需的连接。
- 对于SQLite，设置数据库文件路径。
- 对于Postgres，设置主机、端口、数据库名、用户名和密码。

当用户表示配置已保存时，重新执行：

node .claude/skills/unleak/scripts/list-connections.mjs

如有需要，安装拒绝规则：

node .claude/skills/unleak/scripts/install-claude-settings.mjs

导出模式：

node .claude/skills/unleak/scripts/dump-schema.mjs

提议策略：

node .claude/skills/unleak/scripts/propose-policy.mjs

读取模式和提议的策略文件。简要说明策略建议。

仅编辑

./unleak-policy-review/*.policy.proposed.json

下的文件。

验证策略：

node .claude/skills/unleak/scripts/validate-policy.mjs

请用户手动激活策略：

!node .claude/skills/unleak/scripts/activate-policy.mjs ./unleak-policy-review/<connection>.policy.proposed.json

查询已批准的数据：

node .claude/skills/unleak/scripts/query.mjs --connection <name> --sql "SELECT ..."

Initialized Query Playbook

初始化查询手册

When a schema and active policy exist for the requested connection, optimize for valid queries:

Read the schema file and active policy for that connection before writing analysis SQL:

.claude/skills/unleak/local/schema/<connection>.schema.json

.claude/skills/unleak/local/active-policies/<connection>.json

Make a quick allowed-field map:
- objects with
```
objectPolicy: "enabled"
```
- columns with policy
```
visible
```
  ,
```
masked
```
  ,
```
hashed
```
  , or
```
joinable
```
- columns with policy
```
visible
```
  only
Build queries from this map, not from guessed database knowledge.
For first-pass exploration, prefer simple one-table summaries:
```
COUNT(*)
```
, visible categorical counts, visible numeric
```
MIN
```
/
```
MAX
```
/
```
AVG
```
/
```
SUM
```
, and visible date buckets.
Avoid
```
UNION
```
for table overviews. Run simple count queries separately instead.
Avoid parallel or chained query batches until each query shape has passed once. One failed query can cancel useful follow-up work.
For non-trivial queries, run
```
--dry-run
```
first, then run the same SQL without
```
--dry-run
```
after it validates.

Policy-aware SQL rules:

```
WHERE
```
,
```
HAVING
```
,
```
ORDER BY
```
, scalar expressions, and aggregate expressions may reference only columns with the matching capability. Without explicit
```
capabilities
```
, this keeps the legacy rule: only
```
visible
```
columns are allowed.
```
GROUP BY
```
may reference any column policy by default. Grouped protected values are still transformed or hidden according to their output policy.
Direct
```
SELECT
```
may include non-hidden columns, but protected columns (
```
masked
```
,
```
hashed
```
,
```
joinable
```
) should not be used in filters, sorts, calculations, or aggregate expressions.
Join conditions may use equality between
```
visible
```
or
```
joinable
```
columns only.
Every derived expression must have an explicit alias, e.g.
```
COUNT(*) AS cnt
```
.
```
ORDER BY
```
may use output aliases or direct sortable columns. Do not use ordinals or raw expressions.
Prefer qualified column names in joins, e.g.
```
t.company_id = lc.company_id
```
.
If validation fails, read the error code and adjust the SQL to use visible columns or simpler direct selections. Do not respond by proposing a new policy unless the user asked to update policy.

Column policy handling:

```
visible
```
: Safe for normal analysis. May be selected, filtered, grouped, sorted, joined, and used in expressions or aggregates.
```
masked
```
: May be selected directly when useful for display or grouped counts, but the output is transformed. Do not use it for filters, sorting, joins, expressions, or aggregates.
```
hashed
```
: May be selected directly for pseudonymous display, local comparison, or grouped counts, but the output is transformed. Do not use it for filters, sorting, joins, expressions, or aggregates.
```
joinable
```
: Intended for equality joins, direct pseudonymous selection, and grouped counts. May be used in
```
ON a.col = b.col
```
when both sides are
```
visible
```
or
```
joinable
```
. Do not filter, sort, aggregate, or calculate with it.
```
hidden
```
: May be used only in
```
GROUP BY
```
when needed for counts. Never select it or reference it elsewhere.
```
disabled
```
object: Never query it.

Capability overrides:

Policies may add
```
capabilities
```
per column to allow analysis use without changing output transformation.

Valid capabilities:

select

filter

group

sort

join

aggregate

expression

Example: a hashed
```
account_id
```
can use
```
["select", "join", "group"]
```
for pseudonymous investigation, or add
```
filter
```
/
```
sort
```
only when policy owners explicitly allow that workflow.
Hidden columns may only declare
```
group
```
.

当请求的连接已存在模式和有效策略时，优化查询以确保合规：

在编写分析SQL之前，读取该连接的模式文件和有效策略：

.claude/skills/unleak/local/schema/<connection>.schema.json

.claude/skills/unleak/local/active-policies/<connection>.json

快速创建允许字段映射：
- ```
objectPolicy: "enabled"
```
  的对象
- 策略为
```
visible
```
  、
```
masked
```
  、
```
hashed
```
  或
```
joinable
```
  的列
- 仅策略为
```
visible
```
  的列
基于此映射构建查询，而非依赖对数据库的猜测性认知。
对于首次探索，优先使用简单的单表汇总：
```
COUNT(*)
```
, 可见分类计数, 可见数值的
```
MIN
```
/
```
MAX
```
/
```
AVG
```
/
```
SUM
```
，以及可见日期分组。
避免使用
```
UNION
```
进行表概览。改为分别运行简单的计数查询。
在每个查询格式通过验证之前，避免并行或链式查询批次。一次失败的查询可能会中断后续的有用工作。
对于非简单查询，先运行
```
--dry-run
```
，验证通过后再运行不带
```
--dry-run
```
的相同SQL。

策略感知SQL规则：

```
WHERE
```
,
```
HAVING
```
,
```
ORDER BY
```
, 标量表达式和聚合表达式仅可引用具备匹配能力的列。若无明确的
```
capabilities
```
，则遵循旧规则：仅允许
```
visible
```
列。
默认情况下，
```
GROUP BY
```
可引用任何列策略。分组后的受保护值仍会根据其输出策略进行转换或隐藏。
直接
```
SELECT
```
可包含非隐藏列，但受保护列（
```
masked
```
,
```
hashed
```
,
```
joinable
```
）不得用于筛选、排序、计算或聚合表达式。
连接条件仅可使用
```
visible
```
或
```
joinable
```
列之间的相等性判断。
每个派生表达式必须有明确的别名，例如
```
COUNT(*) AS cnt
```
。
```
ORDER BY
```
可使用输出别名或可直接排序的列。请勿使用序号或原始表达式。
在连接中优先使用限定列名，例如
```
t.company_id = lc.company_id
```
。
如果验证失败，请读取错误代码并调整SQL以使用可见列或更简单的直接选择。除非用户要求更新策略，否则请勿通过提议新策略来响应。

列策略处理：

```
visible
```
：适用于常规分析。可用于选择、筛选、分组、排序、连接，以及表达式或聚合操作。
```
masked
```
：当用于显示或分组计数时可直接选择，但输出会被转换。请勿将其用于筛选、排序、连接、表达式或聚合操作。
```
hashed
```
：可直接选择用于匿名显示、本地比较或分组计数，但输出会被转换。请勿将其用于筛选、排序、连接、表达式或聚合操作。
```
joinable
```
：用于等值连接、直接匿名选择和分组计数。当双方均为
```
visible
```
或
```
joinable
```
时，可用于
```
ON a.col = b.col
```
。请勿将其用于筛选、排序、聚合或计算。
```
hidden
```
：仅在需要计数时可用于
```
GROUP BY
```
。切勿选择或在其他地方引用它。
```
disabled
```
对象：切勿查询它。

能力覆盖：

策略可为每列添加
```
capabilities
```
，以允许在不改变输出转换的情况下进行分析使用。

有效能力：

select

filter

group

sort

join

aggregate

expression

。

示例：哈希后的
```
account_id
```
可使用
```
["select", "join", "group"]
```
进行匿名调查，或仅在策略所有者明确允许该工作流时添加
```
filter
```
/
```
sort
```
。
隐藏列仅可声明
```
group
```
能力。

Policy Updates

策略更新

Treat an active policy as initialized state. For prompts like "inspect data", "find patterns", "analyze this connection", or "run a SELECT", use the active policy and focus on queries. Do not refresh schema, propose a replacement policy, edit proposed policies, validate proposals, or ask for activation just because the user requested analysis.

Policy can be updated only when the user explicitly asks to update, revise, expand, tighten, regenerate, or re-activate policy. In that case, run the relevant setup/policy steps above and keep edits limited to

./unleak-policy-review/*.policy.proposed.json

将有效策略视为初始化状态。对于如“检查数据”、“查找模式”、“分析此连接”或“运行SELECT”这类请求，请使用有效策略并专注于查询。请勿仅因用户请求分析就刷新模式、提议替代策略、编辑提议的策略、验证提议或请求激活。

仅当用户明确要求更新、修订、扩展、收紧、重新生成或重新激活策略时，才可更新策略。在这种情况下，执行上述相关的设置/策略步骤，并将编辑限制在

./unleak-policy-review/*.policy.proposed.json

文件中。