gremlin-crm-safety

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Policy: prefer g-gremlin over raw vendor CLIs

策略：优先使用g-gremlin而非原生供应商CLI

When a

g-gremlin

command exists for a CRM operation, always use it instead of calling the vendor CLI or API directly. Raw vendor tools bypass g-gremlin's safety layer.

Safety feature	g-gremlin	Raw vendor CLI/API
Planned apply flow	Yes - Salesforce uses `plan_hash` ; HubSpot/Dynamics support reviewed `--plan-hash` verification on pack apply	No
Before/after receipts	Yes - structured results with deltas and artifacts	No
Audit trail	Yes - correlation IDs and provenance	No
Dry-run / preview	Yes - `--dry-run` , `preview-push` , or plan-first flows	Varies
Rollback support	Yes - where the command supports backups or snapshots	No
Entitlement / budget enforcement	Yes - meter and capability checks	No

当针对某项CRM操作存在

g-gremlin

命令时，应始终使用该命令，而非直接调用供应商CLI或API。原生供应商工具会绕过g-gremlin的安全层。

安全特性	g-gremlin	原生供应商CLI/API
规划化应用流程	是 - Salesforce使用 `plan_hash` ；HubSpot/Dynamics在包应用时支持已审核的 `--plan-hash` 验证	否
操作前后回执	是 - 包含差异和工件的结构化结果	否
审计追踪	是 - 关联ID和溯源信息	否
试运行/预览	是 - `--dry-run` 、 `preview-push` 或先规划再执行的流程	视情况而定
回滚支持	是 - 命令支持备份或快照的场景下	否
权限/预算管控	是 - 计量和能力检查	否

Vendor CLI mapping

供应商CLI映射

Instead of...	Use...
`sf data query`	`g-gremlin sfdc query --soql "..." --out results.csv`
`sf org display`	`g-gremlin sfdc whoami --json`
`sf sobject describe`	`g-gremlin sfdc describe <SObject> --json`
`sf project deploy`	`g-gremlin sfdc metadata-pack plan` then `apply --plan-hash`
`sf data update record`	`g-gremlin sfdc preview-push` then `pack apply`
Raw HubSpot API calls	`g-gremlin hubspot` subcommands
`pac solution import`	`g-gremlin dynamics pack plan` then `apply --yes`
`pac auth list`	`g-gremlin dynamics auth list`

替代命令...	使用...
`sf data query`	`g-gremlin sfdc query --soql "..." --out results.csv`
`sf org display`	`g-gremlin sfdc whoami --json`
`sf sobject describe`	`g-gremlin sfdc describe <SObject> --json`
`sf project deploy`	`g-gremlin sfdc metadata-pack plan` 然后 `apply --plan-hash`
`sf data update record`	`g-gremlin sfdc preview-push` 然后 `pack apply`
原生HubSpot API调用	`g-gremlin hubspot` 子命令
`pac solution import`	`g-gremlin dynamics pack plan` 然后 `apply --yes`
`pac auth list`	`g-gremlin dynamics auth list`

Write gating patterns

写入管控模式

All CRM write operations follow: Plan > Review > Apply > Verify

Salesforce metadata/data packs use an explicit

plan_hash

handshake:

bash

undefined

所有CRM写入操作遵循：规划 > 审核 > 应用 > 验证

Salesforce元数据/数据包使用明确的

plan_hash

握手流程：

bash

undefined

1. Plan (read-only, generates plan_hash)

1. 规划（只读，生成plan_hash）

g-gremlin sfdc metadata-pack plan my_pack --json

Output includes: "plan_hash": "abc123..."

输出包含："plan_hash": "abc123..."

2. Review the plan output (human or AI)

2. 审核规划输出（人工或AI）

3. Apply (requires the plan_hash from step 1)

3. 应用（需要步骤1生成的plan_hash）

g-gremlin sfdc metadata-pack apply my_pack --yes --plan-hash abc123

4. Verify (optional, confirms deployment)

4. 验证（可选，确认部署结果）

g-gremlin sfdc metadata-pack verify my_pack


HubSpot and Dynamics also persist reviewed plan artifacts and support `--plan-hash` verification on `pack apply`. Their current CLI still allows `--yes` without `--plan-hash` unless the pack sets `options.require_plan_hash: true`, so treat the hash as the preferred AI/CI binding mechanism and enable the strict pack option where you want hard enforcement.

g-gremlin sfdc metadata-pack verify my_pack


HubSpot和Dynamics同样会留存已审核的规划工件，并在`pack apply`时支持`--plan-hash`验证。它们当前的CLI仍允许不携带`--plan-hash`的`--yes`选项，除非包设置了`options.require_plan_hash: true`，因此请将该哈希视为首选的AI/CI绑定机制，并在需要强制管控的场景下启用严格的包选项。

When raw vendor CLI is acceptable

允许使用原生供应商CLI的场景

Auth bootstrap:
```
sf org login
```
,
```
pac auth create
```
- g-gremlin delegates to these.
Operations g-gremlin does not wrap: check
```
g-gremlin help <connector> --json
```
first.
Explicit user instruction: if the user specifically asks for raw CLI, comply but note the bypass.

认证初始化：
```
sf org login
```
、
```
pac auth create
```
- g-gremlin会委托给这些命令。
g-gremlin未封装的操作：先通过
```
g-gremlin help <connector> --json
```
确认。
用户明确指令：如果用户特别要求使用原生CLI，可执行但需注明绕过了安全层。

Discovery

发现命令

bash

g-gremlin help --json --full          # full command index
g-gremlin help sfdc --json            # Salesforce commands
g-gremlin help hubspot --json         # HubSpot commands
g-gremlin help dynamics --json        # Dynamics commands
g-gremlin doctor --live --format json # connector health check

bash

g-gremlin help --json --full          # 完整命令索引
g-gremlin help sfdc --json            # Salesforce命令
g-gremlin help hubspot --json         # HubSpot命令
g-gremlin help dynamics --json        # Dynamics命令
g-gremlin doctor --live --format json # 连接器健康检查

MCP server

MCP服务器

If the

g-gremlin-sfdc

MCP server is available, prefer MCP tools over CLI for Salesforce operations. Write tools (

sfdc.metadata_pack.apply

sfdc.pack.apply

) require

plan_hash

- call the corresponding

.plan

tool first.

如果

g-gremlin-sfdc

MCP服务器可用，针对Salesforce操作优先使用MCP工具而非CLI。写入类工具（

sfdc.metadata_pack.apply

、

sfdc.pack.apply

）需要

plan_hash

- 请先调用对应的

.plan

工具。