@yottameta/yotta-compliance 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# 更新日志
+
+## v0.1.0 (2026-09-24)
+
+初始发布：
+
+- 定位：元规 —— 本地、确定性、可复算的合规条款审查技能（零依赖，Python 3.8+ 标准库）。
+- 规则包：PIPL 11 条 + 数据出境 4 条（`pack_version` 2026.09.1，`coverage_level=baseline_review`）；GDPR / HIPAA / SOC2 / PCI-DSS / ISO27001 / 等保 仅做 `mapping_only` 主题映射，不输出独立合规结论。
+- 内核：规范化与偏移映射、结构解析（heading / clause / item / paragraph）、确定性匹配原语、断言求值（absent / present / 数值 / 日期 / 时长）、证据链、Markdown + JSON 报告、规则包校验闸门。
+- CLI：`review` / `rules list` / `rules show` / `rules validate`；退出码 0 / 1 / 2 / 3 / 4；支持 `--frameworks`、`--format json`、`--gate`、`--out`、`--stdin`、`--include-safe`。
+- 可信契约：每条结论带原文位置、命中规则、框架覆盖级别与来源条款；没有证据不输出风险结论；同一输入得到同一结果。
+- 边界：只做基于确定性规则的审查建议，不构成法律意见；核心路径不调用 LLM、不联网；v0.1 不解析 PDF / docx；不判断合同效力或诉讼结果。
+- 测试：116 项，Python 3.8.20 / 3.11.9 / 3.13.15 全绿；正式规则包下全护栏样例 0 finding、缺口样例 11 finding（`--gate high` 退出码 1）。
+- 文档：SKILL.md + references（rule-authoring / report-format / coverage）+ 中英 README + 四方式安装 + banner。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+# NOTICE — YottaMeta 品牌声明
+
+「YottaMeta」「元规」「yotta-compliance」以及本家族各技能名称（yotta-* 前缀）是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源，任何人均可自由使用、修改与分发。若你在其基础上制作派生作品：
+
+1. 不得继续使用 YottaMeta 或本家族名称（yotta-*、元规 等）作为派生作品的名称；
+2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
+3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
+
+条款来源说明：规则包内引用《中华人民共和国个人信息保护法》与国家网信办《促进和规范数据跨境流动规定》的官方公开文本，
+仅用于条款检索、匹配与引用标注；本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学）。

package/README.md

@@ -0,0 +1,265 @@
+<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-compliance banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-compliance · 元规 (YuanGui)</h1>
+
+<p align="center">YottaMeta's <b>deterministic compliance clause reviewer</b>: review UTF-8 text or Markdown
+against versioned JSON rule packs, then output a report where every finding returns to
+<b>source text evidence, the matched rule, the framework coverage level, and the cited provision</b>.</p>
+<p align="center">Current <b>baseline_review</b> packs: PIPL (11 rules) and data export (4 rules).
+GDPR / HIPAA / SOC2 / PCI-DSS / ISO27001 / China MLPS are <b>mapping_only</b> topic labels,
+not independent compliance conclusions.</p>
+<p align="center">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS;
+local-only, no model calls and no network access in the review path.</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-compliance"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-compliance" /></a>
+  <a href="https://github.com/YottaMeta/yotta-compliance"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-compliance" /></a>
+  <a href="https://github.com/YottaMeta/yotta-compliance/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-compliance" /></a>
+</p>
+
+## What it is
+
+yotta-compliance reviews text or Markdown clauses with deterministic rules. It parses the document
+structure, matches rule candidates, evaluates assertions, extracts source-text evidence, applies
+framework coverage labels, and renders both a human-readable Markdown report and a stable JSON
+contract.
+
+It is a review aid, not a legal opinion. Every risk statement must point to source text, a rule id,
+and a cited provision. If a rule cannot locate evidence, it does not invent a risk conclusion.
+
+## Core value
+
+- **Evidence first** — every `matched_span` quote is sliced from the original text, with original
+  `start` / `end` offsets plus line and column.
+- **Deterministic** — the same input, rule packs, and options produce the same report; only
+  `generated_at` changes between runs.
+- **Versioned rule packs** — each pack carries `pack_id`, `pack_version`, coverage level, and a
+  SHA-256 in the report.
+- **Explicit coverage levels** — `baseline_review` can produce findings; `mapping_only` is only a
+  topic label and cannot be read as a completed framework review.
+- **Stable JSON contract** — a fixed top-level schema for automation, audit records, and CI gates.
+- **Local and zero-dependency** — Python 3.8+ standard library; no network, no model, no database.
+
+## Coverage
+
+| Pack | Framework | Level | Rules |
+|---|---|---|---|
+| `pipl` | PIPL | `baseline_review` | 11 |
+| `data-export` | Data export | `baseline_review` | 4 |
+
+GDPR / HIPAA / SOC2 / PCI-DSS / ISO27001 / China MLPS are `mapping_only`. They receive topic
+labels only; the report does not output independent conclusions for them.
+
+See [references/coverage.md](references/coverage.md) for the full rule list, cited provisions, topic
+mappings, and the explicit out-of-scope list.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `review --input <file>` | Review a UTF-8 `.txt` / `.md` / `.markdown` file |
+| `review --stdin` | Read text from standard input |
+| `review --frameworks <list>` | Select packs by comma-separated id; default loads all packs |
+| `review --format md\|json` | Markdown (default) or JSON |
+| `review --out <file>` | Write the report to a file; default writes stdout |
+| `review --gate <level>` | CI gate: `off` / `low` / `medium` / `high` / `critical` |
+| `review --min-severity <level>` | Filter emitted findings by minimum severity |
+| `review --include-safe` | List checked-but-unmatched rules |
+| `rules list` | List packs and rules |
+| `rules show <rule_id>` | Show one rule's rationale, remediation, source, and test ids |
+| `rules validate --pack <file>` | Validate a rule pack and fail on any schema error |
+
+Exit codes: **0** completed without hitting the gate; **1** gate hit; **2** input / encoding / path
+error; **3** rule-pack error; **4** CLI usage error.
+
+## Quick start
+
+Windows uses `python`; Linux and macOS use `python3`.
+
+```bash
+# Review with the default packs
+python3 scripts/yotta_compliance.py review --input contract.md
+
+# Review only the PIPL pack
+python3 scripts/yotta_compliance.py review --input contract.md --frameworks pipl
+
+# JSON report + CI gate at high
+python3 scripts/yotta_compliance.py review --input contract.md --format json --gate high --out report.json
+
+# Read from stdin
+python3 scripts/yotta_compliance.py review --stdin --frameworks pipl,data-export
+
+# Inspect and validate the shipped rule packs
+python3 scripts/yotta_compliance.py rules list --framework pipl
+python3 scripts/yotta_compliance.py rules show PIPL-NOTICE-001
+python3 scripts/yotta_compliance.py rules validate --pack rules/pipl.json
+```
+
+The report is written to stdout unless `--out` is provided. Output must not overwrite the input file
+or be written inside the rule-pack directory.
+
+## Example
+
+Input fragment:
+
+```text
+我们收集你的个人信息，用于提供服务。
+保存期限：3年。
+数据出境至境外服务器。
+```
+
+The default run on a deliberately incomplete document reports the following summary:
+
+```text
+- 本次输出 11 条发现（全部 11 条）
+- high：3 条
+- medium：4 条
+- low：4 条
+- 已检查规则：15 条 ｜ 命中规则：13 条
+```
+
+The exact result depends on the input and selected packs. A gate at `high` returns exit code 1 when
+the `high` findings are present.
+
+## Report contract
+
+The Markdown report always contains seven sections: input summary, framework coverage summary, risk
+summary, findings, out-of-scope ranges, manual review list, and disclaimer.
+
+The JSON report always provides:
+
+```json
+{
+  "schema_version": "1.0",
+  "tool": "yotta-compliance",
+  "tool_version": "0.1.0",
+  "generated_at": "2026-09-24T12:00:00Z",
+  "input": {},
+  "rule_packs": [],
+  "framework_coverage": [],
+  "summary": {},
+  "findings": [],
+  "review_items": [],
+  "disclaimer": "本工具提供基于确定性规则的条款审查建议与证据链，不构成法律意见。"
+}
+```
+
+Field-level semantics, evidence shapes, and filtering behavior are documented in
+[references/report-format.md](references/report-format.md).
+
+## Known limitations
+
+- **Word-form matching, not semantic understanding** — absence rules check whether the listed
+  search terms appear; synonyms with different wording may be missed.
+- **Document-level absence scope** — a term found anywhere in the document counts as present,
+  regardless of whether it applies to the processing activity.
+- **Negation is not modeled** — phrases such as “we will not share data” can still match a
+  candidate rule.
+- **Arabic numerals only** — `保存期限：N年` is parsed; Chinese numerals such as “三年” are not
+  converted or compared.
+- **No cross-border headcount thresholds in v1** — thresholds requiring unit-aware numbers are
+  deferred to rule-pack v2 instead of producing a potentially wrong comparison.
+- **Absence findings are deliberately lower confidence** — medium / low confidence findings are
+  placed in the manual review list.
+- **No direct PDF / docx parsing** — convert documents to UTF-8 text or Markdown first.
+- **`mapping_only` is not a review** — it is a topic label only.
+
+## Data and security boundaries
+
+- Runs locally; it does not upload source text, evidence, or reports and does not fetch laws online.
+- Rule packs are read-only data; rule content is never executed.
+- Input limit: 2 MiB, UTF-8 text only.
+- Writes to stdout unless `--out` is explicitly provided.
+- Output path guards prevent overwriting the input or writing into the rule-pack directory.
+- Source text is not cached or written to logs.
+
+## Usage with an AI agent
+
+1. Install the skill into the agent's skills directory (see **Install** below).
+2. When the user asks for a PIPL or data-export clause review, run `review` against the supplied
+   text or Markdown file.
+3. Report the coverage summary first: state which frameworks are `baseline_review` and which are
+   `mapping_only`.
+4. Walk through findings by severity, quoting the source evidence and citing the rule's provision.
+5. Treat all low-confidence findings as manual-review items; never present them as final legal
+   conclusions.
+6. Keep the original document unchanged unless the user explicitly asks for a separate report file.
+
+## Install
+
+Pick any of the four methods below; the order is the recommended priority. Skill files come from
+**npm** (GitHub can be slow without a proxy; npm supports mirrors).
+
+### Method 1: npm one-liner (recommended)
+
+```text
+# Optional China mirror: npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-compliance --agent <agent-name>      # install to the agent's default user-level skills dir
+npx -y @yottameta/yotta-compliance --dir <your-skills-dir>   # point to the skills dir itself
+```
+
+- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each
+  agent's default directory.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir`
+  at their skills directory.
+- If the mirror has not synced the new package (404): add
+  `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror
+  cache.
+
+### Method 2: git clone (developers / git available)
+
+```text
+git clone https://github.com/YottaMeta/yotta-compliance.git <your-skills-dir>/yotta-compliance
+```
+
+### Method 3: GitHub Download ZIP (manual / no git)
+
+On the GitHub repository `YottaMeta/yotta-compliance`, click **Code → Download ZIP**, unzip it, and
+put the `yotta-compliance` folder into the agent's skills directory.
+
+### Method 4: install.sh (multi-agent one-liner script)
+
+```text
+bash install.sh --agent <name>   # install to the agent's default user-level directory
+bash install.sh --dir <path>     # install to the given directory
+bash install.sh --list           # list agents -> default directories
+```
+
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use
+> GitHub and may fail without a proxy in China.
+
+## Development and validation
+
+```bash
+# Contract tests (run inside the skill directory)
+python3 scripts/test_yotta_compliance.py
+
+# Rule-pack validation
+python3 scripts/yotta_compliance.py rules validate --pack rules/pipl.json
+python3 scripts/yotta_compliance.py rules validate --pack rules/data-export.json
+
+# Syntax check
+python3 -m py_compile scripts/yotta_compliance.py
+```
+
+Rule authoring guidance: [references/rule-authoring.md](references/rule-authoring.md).
+
+## Boundaries and disclaimer
+
+yotta-compliance provides deterministic rule-based review suggestions and an evidence chain. It does
+not constitute legal advice, does not replace a lawyer or compliance adviser, and does not determine
+contract validity, regulatory approval, or litigation outcomes. A rule hit describes observable
+text, not the user's actual business conduct. A rule miss does not prove the absence of risk.
+`mapping_only` frameworks must not be described as reviewed or certified. Use the tool only on
+content you are authorized to process, and have qualified professionals make the final judgment.
+
+## License
+
+[MIT](./LICENSE) © YottaMeta. The YottaMeta family names and the `yotta-*` prefix are YottaMeta brand
+identifiers; derived works must not reuse them, see [NOTICE](./NOTICE).

package/README.zh-CN.md

@@ -0,0 +1,242 @@
+<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-compliance banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-compliance · 元规 (YuanGui)</h1>
+
+<p align="center">YottaMeta 的 <b>确定性合规条款审查技能</b>：用版本化 JSON 规则包审查 UTF-8 文本或
+Markdown，每条 finding 都回到 <b>原文证据、命中规则、框架覆盖级别与来源条款</b>。</p>
+<p align="center">当前 <b>baseline_review</b> 规则包：PIPL（11 条）与数据出境（4 条）。
+GDPR / HIPAA / SOC2 / PCI-DSS / ISO27001 / 等保 为 <b>mapping_only</b> 主题标签，
+不输出这些框架的独立合规结论。</p>
+<p align="center">纯 Python 3.8+ 标准库，零外部依赖；Windows + Linux + macOS；
+审查路径纯本地运行，不联网、不调用模型。</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-compliance"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-compliance" /></a>
+  <a href="https://github.com/YottaMeta/yotta-compliance"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-compliance" /></a>
+  <a href="https://github.com/YottaMeta/yotta-compliance/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-compliance" /></a>
+</p>
+
+## 这是什么
+
+元规用确定性规则审查文本或 Markdown 条款：解析文档结构、匹配规则候选、求值断言、抽取原文证据、
+计算框架覆盖标签，最后输出人类可读的 Markdown 报告与稳定的 JSON 契约。
+
+它是审查辅助工具，不是法律意见。每条风险结论必须对应原文证据、规则 id 与来源条款；
+规则找不到证据时，不会凭空生成风险结论。
+
+## 核心价值
+
+- **证据优先**——每条 `matched_span` 的 quote 都来自原文切片，带原始 `start` / `end` 偏移与行列号。
+- **确定性**——同一输入、同一规则包、同一参数得到同一结果，重复运行只有 `generated_at` 变化。
+- **规则包版本化**——报告记录 `pack_id`、`pack_version`、覆盖级别与 SHA-256。
+- **覆盖级别显式**——`baseline_review` 可输出独立 finding；`mapping_only` 只是主题标签，
+  不得解读为已完成该框架审查。
+- **稳定 JSON 契约**——固定顶层字段，便于自动化、审计留痕与 CI 闸门。
+- **本地零依赖**——Python 3.8+ 标准库；无网络、无模型、无数据库。
+
+## 覆盖范围
+
+| 规则包 | 框架 | 覆盖级别 | 规则数 |
+|---|---|---|---|
+| `pipl` | PIPL | `baseline_review` | 11 |
+| `data-export` | 数据出境 | `baseline_review` | 4 |
+
+GDPR / HIPAA / SOC2 / PCI-DSS / ISO27001 / 等保 为 `mapping_only`：只接收主题标签，
+报告不输出这些框架的独立结论。
+
+完整规则清单、来源条款、主题映射与明确未覆盖范围见
+[references/coverage.md](references/coverage.md)。
+
+## 命令一览
+
+| 命令 | 说明 |
+|---|---|
+| `review --input <file>` | 审查 UTF-8 `.txt` / `.md` / `.markdown` 文件 |
+| `review --stdin` | 从标准输入读取文本 |
+| `review --frameworks <list>` | 按逗号分隔的规则包 id 选择；缺省装载全部规则包 |
+| `review --format md\|json` | 输出 Markdown（默认）或 JSON |
+| `review --out <file>` | 写报告文件；缺省写 stdout |
+| `review --gate <level>` | CI 闸门：`off` / `low` / `medium` / `high` / `critical` |
+| `review --min-severity <level>` | 只输出达到该严重度的 finding |
+| `review --include-safe` | 列出已检查但未命中的规则 |
+| `rules list` | 列出规则包与规则 |
+| `rules show <rule_id>` | 查看单条规则的说明、建议、来源与测试用例 |
+| `rules validate --pack <file>` | 校验规则包；结构错误立即失败 |
+
+退出码：**0** 审查完成且未触发 gate；**1** 触发 gate；**2** 输入 / 编码 / 路径错误；
+**3** 规则包错误；**4** CLI 用法错误。
+
+## 快速使用
+
+Windows 使用 `python`，Linux / macOS 使用 `python3`。
+
+```bash
+# 使用默认规则包审查
+python3 scripts/yotta_compliance.py review --input contract.md
+
+# 只使用 PIPL 规则包
+python3 scripts/yotta_compliance.py review --input contract.md --frameworks pipl
+
+# JSON 报告 + high 级 CI 闸门
+python3 scripts/yotta_compliance.py review --input contract.md --format json --gate high --out report.json
+
+# 从标准输入读取
+python3 scripts/yotta_compliance.py review --stdin --frameworks pipl,data-export
+
+# 查看与校验规则包
+python3 scripts/yotta_compliance.py rules list --framework pipl
+python3 scripts/yotta_compliance.py rules show PIPL-NOTICE-001
+python3 scripts/yotta_compliance.py rules validate --pack rules/pipl.json
+```
+
+报告默认写 stdout；只有显式提供 `--out` 才写文件。输出路径不得覆盖输入文件，也不得写入规则包目录。
+
+## 示例
+
+输入片段：
+
+```text
+我们收集你的个人信息，用于提供服务。
+保存期限：3年。
+数据出境至境外服务器。
+```
+
+对一份缺少多项护栏的说明运行默认规则包，汇总示例：
+
+```text
+- 本次输出 11 条发现（全部 11 条）
+- high：3 条
+- medium：4 条
+- low：4 条
+- 已检查规则：15 条 ｜ 命中规则：13 条
+```
+
+实际结果取决于输入内容与所选规则包；示例数字不是固定输出。`--gate high` 在上述结果下返回退出码 1。
+
+## 报告契约
+
+Markdown 报告固定包含七节：输入摘要、框架覆盖摘要、风险汇总、逐条发现、未覆盖范围、
+人工复核清单、免责声明。
+
+JSON 报告固定提供：
+
+```json
+{
+  "schema_version": "1.0",
+  "tool": "yotta-compliance",
+  "tool_version": "0.1.0",
+  "generated_at": "2026-09-24T12:00:00Z",
+  "input": {},
+  "rule_packs": [],
+  "framework_coverage": [],
+  "summary": {},
+  "findings": [],
+  "review_items": [],
+  "disclaimer": "本工具提供基于确定性规则的条款审查建议与证据链，不构成法律意见。"
+}
+```
+
+字段语义、证据结构与过滤行为见 [references/report-format.md](references/report-format.md)。
+
+## 已知局限
+
+- **词形匹配，不是语义理解**——absence 规则只判断检索词是否出现；同义但词形不同的表述可能漏检。
+- **文档级 absence 范围**——检索词出现在文档任何位置都视为已出现，不判断其是否适用于当前处理活动。
+- **否定句不建模**——“不会对外提供”等否定表述仍可能触发候选匹配。
+- **只解析阿拉伯数字**——`保存期限：N年` 可解析；“三年”等中文数字不做解析或换算。
+- **数据出境人数阈值未进入 v1**——需要单位感知的数值原语；为避免输出可能错误的数值结论，
+  相关阈值规则推迟到规则包 v2。
+- **absence 结论降低置信度**——medium / low 置信 finding 进入人工复核清单，必须人工核验后才能采信。
+- **不直接解析 PDF / docx**——需先转成 UTF-8 文本或 Markdown。
+- **`mapping_only` 不是审查**——它只是主题标签。
+
+## 数据与安全边界
+
+- 纯本地运行；不上传原文、证据或报告，不联网检索法条；
+- 规则包是只读数据，规则正文不会被执行；
+- 输入上限 2 MiB，仅接受 UTF-8 文本；
+- 除非显式设置 `--out`，报告只写 stdout；
+- 输出路径防护禁止覆盖输入文件与写入规则包目录；
+- 不缓存原文，不把合同内容写入日志。
+
+## 在智能体中使用
+
+1. 按下方「安装」把技能装入智能体的技能目录；
+2. 用户要求审查 PIPL 或数据出境条款时，对提供的文本 / Markdown 运行 `review`；
+3. 先说明覆盖摘要：哪些框架是 `baseline_review`，哪些只是 `mapping_only`；
+4. 按严重度逐条说明 finding，引用原文证据与规则来源条款；
+5. 低置信 finding 一律作为人工复核项处理，不当作最终法律结论；
+6. 除非用户明确要求另存报告，不修改原文档。
+
+## 安装
+
+以下四种方式任选，顺序即推荐优先级；技能文件一律从 **npm** 获取（GitHub 无代理较慢，
+npm 支持镜像）。
+
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-compliance --agent <智能体名称>      # 装到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-compliance --dir <智能体的技能目录>  # 指到技能目录本身
+```
+
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），
+  或稍等镜像缓存。
+
+### 方式二：git clone（开发者 / 有 git 环境）
+
+```text
+git clone https://github.com/YottaMeta/yotta-compliance.git <智能体的技能目录>/yotta-compliance
+```
+
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+
+在 GitHub 仓库 `YottaMeta/yotta-compliance` 点 **Code → Download ZIP**，解压后把
+`yotta-compliance` 文件夹放进智能体技能目录。
+
+### 方式四：install.sh（多智能体一键脚本）
+
+```text
+bash install.sh --agent <name>   # 装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
+```
+
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
+
+## 开发与校验
+
+```bash
+# 契约测试（技能目录内运行）
+python3 scripts/test_yotta_compliance.py
+
+# 规则包校验
+python3 scripts/yotta_compliance.py rules validate --pack rules/pipl.json
+python3 scripts/yotta_compliance.py rules validate --pack rules/data-export.json
+
+# 语法检查
+python3 -m py_compile scripts/yotta_compliance.py
+```
+
+规则编写规范见 [references/rule-authoring.md](references/rule-authoring.md)。
+
+## 边界与免责声明
+
+元规提供基于确定性规则的条款审查建议与证据链，不构成法律意见，不替代律师或合规顾问，
+也不判断合同效力、监管审批或诉讼结果。规则命中只描述文本中出现的可观察现象，不代表真实业务
+一定未履行义务；规则未命中也不代表不存在风险。`mapping_only` 框架不得被描述为已审查或已认证。
+请只审查有权处理的内容，最终判断由具备资质的专业人士作出。
+
+## 许可证
+
+[MIT](./LICENSE) © YottaMeta。YottaMeta 家族名称与 `yotta-*` 前缀是 YottaMeta 品牌标识；
+衍生作品不得复用，详见 [NOTICE](./NOTICE)。