LocalShield

Use LocalShield immediately before a production Agent moves local content outside the device. WorkBuddy contract and customer-document delivery is the primary workflow; Qoder and TRAE Work use the same entry contract.

LocalShield is an Agent decision service, not a system firewall. The host must call it and honor its result.

Fixed entry point

Expose only scripts\run.ps1 to the host. Run from the Skill directory.

| Intent | Command | |---|---| | Inspect a contract before sending | .\scripts\run.ps1 -InputPath .\examples\risky_contract.md -Action send -Destination external_partner -Mode gate -Policy workbuddy_contract_policy -Device AUTO | | Inspect inline text | .\scripts\run.ps1 -Text "Send customer phone 13800138000 to an external supplier" -Action send -Destination external_partner -Mode gate | | Audit without enforcement | .\scripts\run.ps1 -InputPath .\examples\clean_public_note.md -Action publish -Destination public_web -Mode audit |

The first call creates .runtime\venv and installs pinned dependencies. Run .\scripts\setup.ps1 explicitly when preparing a demo. If setup was interrupted, run .\scripts\setup.ps1 -Continue or pass -Continue to the fixed entry point. After setup, runtime inference does not require network access.

To render a saved decision JSON, run python .\scripts\render_result.py path\to\decision_result.json; the default output is a sibling .html file. Add -RenderHtml to run.ps1 to generate outputs\<request_id>\decision_result.html automatically and receive its path in artifacts.result_panel_html. This is an auxiliary evidence view generated from masked JSON fields, not a native WorkBuddy interface, and it does not include original content.

The client starts a loopback service on demand. Each service process receives a random authentication token stored in .runtime\server.token; the client sends it as X-LocalShield-Token. Treat .runtime\server.token and .runtime\server.log as private runtime state and never submit or copy them. The service accepts at most four concurrent inspections and rejects oversized JSON requests before parsing.

Request behavior

• Provide exactly one of -InputPath or -Text.
• Use -Action audit|upload|publish|share|send|commit|summarize.
• Use -Destination local|internal|external_cloud|external_partner|public_web|public_repo|unknown.
• Use -Mode gate for production actions, sanitize to request a copy, and audit for observation only.
• Keep -Device AUTO unless the user asks to validate a detected CPU, GPU, or NPU.

Supported inputs are text, Markdown, JSON, CSV, common source files, text PDFs, and DOCX. DOCX scanning includes body paragraphs, tables, headers, and footers. DOCX and text-PDF table values use adjacent field labels and first-row column headers, covering supplier/customer organizations, bank accounts, unified social credit codes, certificate identifiers, quote or contract identifiers, sensitive dates, and currency values including plain numeric amounts under financial headers. Structural table labels are retained; only the associated value is redacted. Findings expose precise DOCX part locations such as body.table1.row2.cell4.paragraph1 and PDF line/page parts. Sensitive ranges are replaced with * characters equal to the original Python character count. Text-like inputs keep their original extension, DOCX sanitization creates a new DOCX while preserving the document structure and run formatting where supported, and PDF sanitization creates a new PDF with the original page count and layout as the base. PDF redaction fails closed when a finding cannot be located reliably; image-only PDFs still require manual review.

The semantic model is a secondary detector. Policy defaults set semantic_min_probability to 0.85 and semantic_auto_redact to false: high-confidence model-only findings are reported for review and do not cause an entire paragraph to be masked. If such a finding remains unresolved, sanitized_recheck.usable is false and the host-facing result becomes REVIEW_REQUIRED. The result also contains coverage, including detector counts, known limitations, and the statement that PASS covers only the implemented rules.

The first release limits files to 20 MB, text to 500,000 characters and 100,000 lines, PDFs to 200 pages, and DOCX files to 20,000 text units. A PDF with no extractable text (for example, an image-only scan) fails closed as REVIEW_REQUIRED; it is not treated as clean. Custom policy files must remain under config, and custom model files under models, within this Skill directory. Output artifacts are written under a request-ID subdirectory so concurrent calls cannot overwrite one another.

Interpret the JSON result

For quotation tables, PDF extraction uses detected cell boundaries to associate financial column headers with values. Explicit RMB/CNY/¥/￥ amounts are also scanned without requiring table context, including multiple amounts per line; tax labels such as VAT (6%) retain their label and rate. Pure numeric values (including values below 100) require a recognized financial field or column. Borderless, merged, unusual, or image-based tables may still need manual review; format parity is tested for supported tables, not guaranteed for arbitrary layouts.

After sanitization, artifacts.sanitized_recheck.residual_currency_check provides a separate explicit-currency text check that does not use the primary scanner or table metadata. A residual match forces REVIEW_REQUIRED and usable=false, even if the primary recheck missed it. This check does not validate arbitrary bare numbers, currencies outside the implemented patterns, or image content. Finding/output consistency still checks known findings separately. Do not describe either check as proof that all possible sensitive content has been removed.

• PASS: continue with the original input.
• WARN: explain the risk and ask the user before continuing.
• BLOCK: stop the original-file action. Use only a sanitized artifact whose sanitized_recheck.decision is PASS.
• REVIEW_REQUIRED: stop automation and request manual review.

When a sanitized artifact is generated, sanitized_recheck.usable must be true before a host may use it. If the second check is anything other than PASS, LocalShield changes effective_decision to REVIEW_REQUIRED and sets next_action to manual_review.

The result includes masked findings, location, model/backend/device metadata, input hash, sanitized artifact metadata, and privacy invariants. analysis_metrics.input_* describes the original input; artifacts.sanitized_recheck.post_sanitization_* describes only the emitted copy; manual_review_finding_count and failed_redaction_finding_count are separate unresolved conditions. artifacts.sanitized_recheck.finding_output_consistency records the per-finding removal check without storing raw values. A successful scan may return exit code 0 even when its semantic decision is BLOCK; parse the JSON decision.

Failure handling

Fail closed when input parsing, policy loading, model loading, or local service startup fails. Never retry against a remote URL. The client rejects non-loopback service addresses. Do not write original content or unmasked evidence to audit JSON or remote logs.

Validation and references

Read references/workbuddy_integration.md before WorkBuddy validation and references/host_validation.md for the PASS/WARN/BLOCK/REVIEW_REQUIRED matrix. Read references/architecture.md when changing transport, model, or privacy invariants. Read references/submission_checklist.md before publishing to ModelScope.