@yottameta/yotta-dev-mcp 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## v0.2.0 (2026-09-25)
+
+- 新增 `system_model`：模块、依赖、入口、测试映射、配置与数据归属的确定性系统模型，
+  附带 `.yotta/architecture.json` 契约分层。
+- 新增 `architecture_review`：按契约评审依赖规则、边界可见性与数据归属，
+  每条产出 file / line / severity 证据；critical / high 判 FAIL，medium / low 只告警，
+  无法判定的部分进 UNKNOWN，声明的不变量一律进 `unverified_claims`。
+- 新增 `impact_analysis`：从 changed_files / unified diff / 目标符号生成变更影响锥，
+  含直接消费者、受影响层与边界、数据存储、不变量、映射测试、可解释风险分级与回滚探针。
+- 新增 `verify_change`：L0-L5 验证阶梯与确定性证据账本；L0 / L1 默认运行，
+  L2-L4 必须同时有 `.yotta/verification.json` 白名单声明与 `allow_execute=true`，
+  L5 人工复核始终留在 `unverified_claims`；账本以 output hash 与 ledger digest 复算。
+- 新增 `self_test`：检查必需文件、版本五件、协议工具 schema / engine dispatch 漂移、
+  写入与执行闸门是否 fail-closed，并用 seeded defect 与 mutation control 反证验证器会红。
+- 新增 `run_adapter`：探测或显式运行项目已安装的 import-linter /
+  dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与 hash，
+  缺工具 / 缺配置 / 超时 / 非法输出一律返回 UNKNOWN，且不自动安装、不下载、不访问远端。
+- 新增架构契约（版本 1）：分层、依赖规则、边界、数据归属、不变量、风险权重；
+  校验输出 code / severity / JSON pointer / evidence。
+- 新增可选验证策略（版本 1）：只允许白名单 runner、仓库内相对 cwd 与显式执行；
+  拒绝任意命令、绝对路径与越界 cwd。
+- 结论只给 `PASS` / `FAIL` / `UNKNOWN`；缺证据项写入 `unknowns`，未执行的验证级别
+  写入 `unverified_claims`；模型带稳定 `model_digest`。
+- 引擎按共享层拆分：`dev_common` / `dev_model` / `dev_architecture` /
+  `dev_impact` / `dev_verify` / `dev_selftest` / `dev_adapters`；`dev_engine`
+  保留原公开函数与 dispatch 作为稳定门面。
+- 原 12 个工具行为不变；新增的六个工具离线、零依赖（适配器只在用户已安装时调用），默认只读。
+
+## v0.1.1 (2026-09-25)
+
+- 品牌改名：对外显示名统一为「元开（yotta-dev-mcp）」，不再把功能描述「开发能力 MCP」当产品名。
+- 功能与 12 个工具保持不变；协议、参数、输出与 0.1.0 兼容。
+
+## v0.1.0 (2026-09-25)
+
+- 首个本地候选：MCP 双时代协议内核（2026-07-28 modern + 2025-11-25 legacy）。
+- 十二个确定性工具：`repo_map` / `find_code` / `compress_output` /
+  `review_code` / `review_diff` / `mcp_doctor` / `scan_secrets` /
+  `scan_dependencies` / `check_publish_readiness` / `run_checks` /
+  `scaffold_skill` / `workflow_state`。
+- Python 3.8+ 标准库实现；离线默认运行；输出带证据、排序稳定。
+- `run_checks` 默认关闭执行；`scaffold_skill` / `workflow_state` 默认只预览。

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,7 @@
+# NOTICE - YottaMeta 品牌声明
+
+「YottaMeta」「元阁」「yotta-dev-mcp」以及本家族各技能名称（yotta-* 前缀）
+是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源。派生作品不得继续使用 YottaMeta 或本家族名称作为名称，
+不得暗示派生作品由 YottaMeta 官方维护或认可。

package/README.md

@@ -0,0 +1,132 @@
+<p align="center"><img src="assets/banner.png" alt="YuanKai banner" width="100%"></p>
+<h1 align="center">YuanKai (yotta-dev-mcp)</h1>
+<p align="center"><b>Language</b>: English · <a href="README.zh-CN.md">中文</a></p>
+
+Deterministic local development tools exposed over a stdio MCP server.
+
+## What it does
+
+| Tool | Purpose |
+|---|---|
+| `repo_map` | Map modules, imports and entrypoints in a repository. |
+| `system_model` | Build a system model with layer data from the architecture contract. |
+| `architecture_review` | Review dependency rules, boundaries and data ownership with evidence. |
+| `impact_analysis` | Build the change impact cone with tests, blast radius and rollback probes. |
+| `verify_change` | Run the L0-L5 verification ladder and return an evidence ledger. |
+| `self_test` | Check files, versions, tool contracts, write gates and seeded-defect counterexamples. |
+| `run_adapter` | Probe or explicitly run optional import-linter / dependency-cruiser / Repomix adapters. |
+| `find_code` | Locate symbols and text with bounded results. |
+| `compress_output` | Compress long logs while keeping errors and head/tail context. |
+| `review_code` | Apply deterministic review rules with file, line and evidence. |
+| `review_diff` | Review only added lines in a unified diff. |
+| `mcp_doctor` | Inspect installed skills and MCP JSON configuration files. |
+| `scan_secrets` | Scan for credentials and high-entropy tokens with redacted evidence. |
+| `scan_dependencies` | Check manifests, lockfiles, insecure sources and typosquat suspicion. |
+| `check_publish_readiness` | Check version alignment, release files and package metadata. |
+| `run_checks` | Run whitelisted tests, lint or compile checks; execution is explicit. |
+| `scaffold_skill` | Plan or create a minimal skill scaffold; dry-run by default. |
+| `workflow_state` | Read `.workflow` and optionally append an explicit log entry. |
+
+Tools are read-only by default; `run_checks`, the L2-L4 policy checks in
+`verify_change`, the test subset in `self_test`, and `run_adapter` with
+`action=run` require `allow_execute=true`. `scaffold_skill` / `workflow_state`
+require `apply=true` before writing. Python 3.8+ standard library is sufficient;
+no network access is required.
+
+### Architecture contract
+
+`system_model` reads an optional `.yotta/architecture.json` (version 1) that declares
+layers, dependency rules, boundaries, data ownership, invariants and risk weights. The
+result reports `PASS`, `FAIL` or `UNKNOWN`, lists every unknown that still needs
+evidence, and keeps verification levels that were not executed in `unverified_claims`.
+`architecture_review` then checks that contract: dependency rules, boundary visibility
+and data ownership each produce findings with file, line and severity. `critical` and
+`high` findings fail the review, `medium` and `low` stay advisory, and anything that
+cannot be decided from the model becomes `UNKNOWN` instead of a silent pass.
+
+`impact_analysis` starts from `changed_files`, a unified diff or target symbols and
+walks reverse dependencies into a bounded cone: direct consumers, affected layers,
+boundaries, data stores, invariants, mapped tests, an explainable blast radius and
+rollback probes. It executes nothing.
+
+`verify_change` runs the post-change ladder: L0 syntax and contract schema, L1
+architecture checks inside the impact cone, L2-L4 whitelisted checks declared in
+`.yotta/verification.json` with explicit `allow_execute=true`, and L5 independent
+review kept as unverified work. Ledger entries carry a claim, status, evidence,
+check name and output hash so the result can be recomputed; skipped levels are never
+written as passing.
+
+`self_test` checks the integrity of yotta-dev-mcp itself: required files, version
+alignment across package / SKILL / CHANGELOG / server / engine, protocol tool schema
+drift, fail-closed write gates, and seeded-defect plus mutation controls that prove
+the verifier turns red or unknown. The test suite is not executed by default.
+
+`run_adapter` is an optional enhancement layer. `action=list` only probes the
+project-local `node_modules/.bin`, project virtualenvs and `PATH`; `action=run`
+requires `allow_execute=true` and runs one fixed adapter command. Missing tools,
+missing config, invalid output and timeouts return `UNKNOWN` with a next step.
+No package is installed or downloaded, and adapter results do not silently change
+the status of the core architecture tools. Details: `references/adapters.md`.
+
+Schema, glob rules, finding codes and cone fields: `references/architecture-contract.md`.
+
+## Install
+
+### Start the MCP server
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+### Install the skill payload
+
+```bash
+npx -y @yottameta/yotta-dev-mcp --agent codex
+npx -y @yottameta/yotta-dev-mcp --dir <skill-directory>
+npx -y @yottameta/yotta-dev-mcp --list
+```
+
+The installer uses explicit targets. `--global` additionally requires `--yes`, and
+`--dry-run` prints the target without writing.
+
+Other installation methods:
+
+```bash
+git clone https://github.com/YottaMeta/yotta-dev-mcp.git <skill-directory>/yotta-dev-mcp
+bash <skill-directory>/yotta-dev-mcp/install.sh --agent codex
+```
+
+You can also use GitHub's **Download ZIP** action and unpack the archive into the
+skill directory.
+
+## Direct CLI
+
+The engine can also be used without MCP:
+
+```bash
+python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py system-model .
+python scripts/dev_engine.py architecture-review .
+python scripts/dev_engine.py impact-analysis . --changed src/core/store.py
+python scripts/dev_engine.py verify-change . --changed src/core/store.py
+python scripts/dev_engine.py verify-change . --changed src/core/store.py --level L2 --allow-execute
+python scripts/dev_engine.py self-test .
+python scripts/dev_engine.py adapter . --action list
+python scripts/dev_engine.py adapter . --action run --adapter dependency-cruiser --allow-execute
+python scripts/dev_engine.py find-code . "helper"
+python scripts/dev_engine.py review-code .
+python scripts/dev_engine.py mcp-doctor
+```
+
+## Boundaries
+
+- No code execution, no automatic edits, no commits.
+- No network access, no package-existence lookup.
+- Static deterministic findings only; human review remains the final decision.
+
+## Current version
+
+`0.2.0` (2026-09-25) adds `system_model`, `architecture_review`,
+`impact_analysis`, `verify_change`, `self_test`, `run_adapter`, and the
+`.yotta/architecture.json` plus optional `.yotta/verification.json` contracts on
+top of the twelve deterministic tools.

package/README.zh-CN.md

@@ -0,0 +1,120 @@
+<p align="center"><img src="assets/banner.png" alt="元开 banner" width="100%"></p>
+<h1 align="center">元开（yotta-dev-mcp）</h1>
+<p align="center"><b>Language</b>: <a href="README.md">English</a> · 中文</p>
+
+把本地、确定性的开发工具做成 stdio MCP server，任何支持 MCP 的客户端接上即可使用。
+
+## 能做什么
+
+| 工具 | 用途 |
+|---|---|
+| `repo_map` | 代码库模块、导入关系与入口点地图。 |
+| `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属，附带契约分层。 |
+| `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属，逐条给出证据。 |
+| `impact_analysis` | 变更影响锥：消费者、受影响层与存储、映射测试、风险分级与回滚探针。 |
+| `verify_change` | L0-L5 验证阶梯与证据账本；未执行级别保留在 `unverified_claims`。 |
+| `self_test` | 文件、版本、工具契约、写闸门与 seeded defect / mutation 反证自测。 |
+| `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器。 |
+| `find_code` | 符号与文本定位，结果有数量上限。 |
+| `compress_output` | 压缩长日志，保留错误、错误栈和首尾上下文。 |
+| `review_code` | 规则化代码评审，输出文件、行号、证据与建议。 |
+| `review_diff` | 只评审 unified diff 的新增行。 |
+| `mcp_doctor` | 只读检查技能目录与 MCP JSON 配置。 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描，证据强制脱敏。 |
+| `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查。 |
+| `check_publish_readiness` | 版本对齐、发布文件与包元数据检查。 |
+| `run_checks` | 运行白名单测试 / lint / compile，执行必须显式开启。 |
+| `scaffold_skill` | 规划或生成最小技能脚手架，默认 dry-run。 |
+| `workflow_state` | 读取 `.workflow`，可选显式追加快照日志。 |
+
+默认只读；`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集，
+以及 `run_adapter` 的 `action=run` 必须显式 `allow_execute=true`，
+`scaffold_skill` / `workflow_state` 必须显式 `apply=true` 才写入。
+核心只用 Python 3.8+ 标准库，默认不联网。
+
+### 架构契约
+
+`system_model` 读取可选的 `.yotta/architecture.json`（版本 1），其中声明分层、依赖规则、
+边界、数据归属、不变量与风险权重。结果只给 `PASS` / `FAIL` / `UNKNOWN`，把还缺证据的
+未知项列进 `unknowns`，未执行的验证级别保留在 `unverified_claims`。schema、glob 规则与
+错误码见 `references/architecture-contract.md`。
+
+`architecture_review` 在这份契约上做评审：依赖规则、边界可见性与数据归属逐条产出
+文件、行号与严重级；`critical` / `high` 判 FAIL，`medium` / `low` 只告警，
+模型无法判定的部分进 `UNKNOWN`，不会被静默放行。
+
+`impact_analysis` 从 `changed_files`、unified diff 或目标符号出发，沿反向依赖走出一棵
+有上限的影响锥：直接消费者、受影响层与边界、数据存储、不变量、映射测试、
+可解释的风险分级与回滚探针；全程不执行任何命令。
+
+`verify_change` 在改动后跑同一份模型：L0 检查语法与契约 schema，L1 检查影响锥内架构规则，
+L2-L4 只执行 `.yotta/verification.json` 中声明的白名单检查且必须显式 `allow_execute=true`，
+L5 独立复核始终保留在未验证项。账本中的每个结论都带 claim、status、evidence、check 与
+output hash，便于复算；未跑级别不会被写成“已通过”。
+
+`self_test` 对元开自身做完整性检查：必需文件、版本五件、协议工具 schema 与引擎
+dispatch 是否漂移、写 / 执行闸门是否仍 fail-closed，并用临时仓库里的 seeded defect
+与 mutation control 证明验证器会变红或变 UNKNOWN。测试子集默认不跑。
+
+`run_adapter` 是可选增强层：`action=list` 只探测项目 `node_modules/.bin`、
+项目虚拟环境和 `PATH`；`action=run` 必须显式 `allow_execute=true`，且只运行固定
+适配器命令。缺工具、缺配置、非法输出或超时都返回 `UNKNOWN` 并给出下一步；
+不安装、不下载，适配器结果也不会悄悄改写核心架构工具的状态。详见
+`references/adapters.md`。
+
+## 安装
+
+### 启动 MCP server
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+### 安装技能载荷
+
+```bash
+npx -y @yottameta/yotta-dev-mcp --agent codex
+npx -y @yottameta/yotta-dev-mcp --dir <技能目录>
+npx -y @yottameta/yotta-dev-mcp --list
+```
+
+安装器只写入显式目标。`--global` 必须同时给 `--yes`；`--dry-run` 只预览不写入。
+
+其他安装方式：
+
+```bash
+git clone https://github.com/YottaMeta/yotta-dev-mcp.git <技能目录>/yotta-dev-mcp
+bash <技能目录>/yotta-dev-mcp/install.sh --agent codex
+```
+
+也可以使用 GitHub 的 **Download ZIP**，解压到技能目录。
+
+## 直接使用 CLI
+
+```bash
+python scripts/dev_engine.py repo-map .
+python scripts/dev_engine.py system-model .
+python scripts/dev_engine.py architecture-review .
+python scripts/dev_engine.py impact-analysis . --changed src/core/store.py
+python scripts/dev_engine.py verify-change . --changed src/core/store.py
+python scripts/dev_engine.py verify-change . --changed src/core/store.py --level L2 --allow-execute
+python scripts/dev_engine.py self-test .
+python scripts/dev_engine.py adapter . --action list
+python scripts/dev_engine.py adapter . --action run --adapter dependency-cruiser --allow-execute
+python scripts/dev_engine.py find-code . "helper"
+python scripts/dev_engine.py review-code .
+python scripts/dev_engine.py mcp-doctor
+```
+
+## 边界
+
+- 不执行代码、不自动改文件、不自动提交。
+- 不联网，不查询公共仓库中包是否存在。
+- 仅做确定性静态判断，最终评审由人负责。
+
+## 当前版本
+
+`0.2.0`（2026-09-25）在原有十二个确定性工具之上新增 `system_model`、
+`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、
+`run_adapter`，以及 `.yotta/architecture.json` 与可选
+`.yotta/verification.json` 契约（版本 1）。

package/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: yotta-dev-mcp
+description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / system_model / architecture_review / impact_analysis / verify_change / self_test / run_adapter / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、构建系统模型或架构契约（.yotta/architecture.json）、按契约评审架构、分析改动影响锥与回归面、按验证阶梯产出证据账本、对元开自身做完整性 / 反证自测、探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 系统模型 / 架构契约 / 架构评审 / 影响分析 / 验证账本 / 反证自测 / 代码评审 MCP / 适配器 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）、verify_change 的 L2-L4 策略检查（显式 allow_execute）与 self_test 的测试子集（显式 allow_execute）、run_adapter 的 action=run（显式 allow_execute）、scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在、不自动安装或下载适配器。
+version: 0.2.0
+license: MIT
+---
+
+# 元开（yotta-dev-mcp）
+
+元开（YuanKai）把一组本地、确定性的开发工具做成一个 stdio MCP server。任何支持 MCP 的客户端接上后，
+都能在真实开发任务里调用这些工具；输出带文件、行号、规则和证据，便于直接进入修复清单。
+
+## 何时使用
+
+- 接手陌生项目：先 `repo_map` 看模块、依赖和入口，再 `find_code` 定位。
+- 架构与影响分析：先写 `.yotta/architecture.json`，再用 `system_model` 拿分层、依赖、测试映射与 `UNKNOWN` 清单。
+- 契约评审：用 `architecture_review` 查依赖规则、边界可见性与数据归属，每条给证据与严重级。
+- 改动前评估：用 `impact_analysis` 从改动文件 / diff / 目标符号走出影响锥、映射测试与回滚探针。
+- 改动后验证：用 `verify_change` 跑 L0 / L1 默认检查，按需结合 `.yotta/verification.json` 与 `allow_execute=true` 执行 L2-L4 白名单检查，产出可复算账本。
+- 自身完整性：用 `self_test` 检查文件、版本、工具契约、写闸门与 seeded defect / mutation 反证。
+- 可选增强：用 `run_adapter` 先 `action=list` 探测 import-linter / dependency-cruiser / Repomix，再按需 `action=run` + `allow_execute=true`；缺工具或配置返回 UNKNOWN，不自动安装、不自动下载。
+- 评审改动：`review_diff` 只看新增行；`review_code` 对文件或仓库做规则检查。
+- 长日志 / 长命令输出：`compress_output` 保错误、错误栈和首尾上下文。
+- 本机排查：`mcp_doctor` 只读检查技能目录和 MCP JSON 配置。
+
+## MCP 接入
+
+启动命令：
+
+```bash
+npx -y @yottameta/yotta-dev-mcp
+```
+
+或直接用本地脚本：
+
+```bash
+python scripts/yotta_dev_mcp.py
+```
+
+自动接入说明：AI 首次协助配置时，必须先展示目标配置文件、完整配置片段和影响，
+并获得用户明确同意后再写入 `mcpServers`。用户拒绝时不要写文件，直接提供上面的启动命令
+让用户手动接入。
+
+## 工具
+
+| 工具 | 用途 | 写入 |
+|---|---|---|
+| `repo_map` | 模块、导入、入口点地图 | 否 |
+| `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属；附带契约分层，输出 PASS / FAIL / UNKNOWN | 否 |
+| `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属；critical / high 判 FAIL，medium / low 只告警 | 否 |
+| `impact_analysis` | 变更影响锥：直接消费者、受影响层 / 边界 / 存储 / 不变量、映射测试、风险分级与回滚探针 | 否 |
+| `verify_change` | L0-L5 验证阶梯与证据账本：L0 / L1 默认，L2-L4 需策略声明 + 显式执行，L5 始终留在未验证项 | 仅显式 allow_execute 的 L2-L4 |
+| `self_test` | 文件 / 版本 / 工具契约 / 写闸门 / seeded defect 与 mutation 反证自测 | 仅显式 allow_execute 的测试子集 |
+| `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与哈希 | 仅 action=run + 显式 allow_execute |
+| `find_code` | 符号 / 文本定位，结果有上限 | 否 |
+| `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
+| `review_code` | 规则化代码评审，带行号与建议 | 否 |
+| `review_diff` | 只评审 diff 的新增行 | 否 |
+| `mcp_doctor` | 技能版本与 MCP JSON 配置体检 | 否 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描（强制脱敏） | 否 |
+| `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查 | 否 |
+| `check_publish_readiness` | 版本四件、发布文件、仓库与 publishConfig 检查 | 否 |
+| `run_checks` | 白名单测试 / lint / compile 并返回结构化摘要 | 仅显式 allow_execute |
+| `scaffold_skill` | 生成最小技能脚手架，默认 dry-run | 仅显式 apply |
+| `workflow_state` | 读取 `.workflow`，可选显式追加日志 | 仅显式 apply |
+
+详细契约见 `references/tools.md`；架构契约、评审语义与影响锥字段见 `references/architecture-contract.md`。
+
+## 边界
+
+- 会执行项目代码的工具默认关闭：`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集都必须显式 `allow_execute=true`，且只运行白名单检查或已声明的策略检查。
+- 外部适配器只在用户已安装时接入：`run_adapter` 不安装、不下载、不访问远端、不接收任意命令参数；工具缺失或配置缺失一律返回 `UNKNOWN` 并给出 next_step。
+- `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；脚手架拒绝覆盖已有非空目录，状态写入使用原子替换并为被覆盖文件保留 `.bak`。
+- 不联网，不查询包是否存在于公共仓库。
+- 不读取或修改 YottaCode 仓库。
+- 结论是确定性静态判断，不替代人工评审与最终决策。
+
+## 当前版本
+
+- v0.2.0（2026-09-25）：新增 `system_model`、`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、`run_adapter`，以及 `.yotta/architecture.json` 与可选 `.yotta/verification.json` 契约（版本 1）；工具总数 18，原 12 个工具行为不变。
+- v0.1.1：品牌显示名统一为「元开」；功能与 12 个工具不变。

package/bin/install.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * yotta-dev-mcp installer.
+ *
+ * Safe defaults:
+ *   --agent <name>  install to one agent's user-level skill directory
+ *   --dir <path>    install to an explicit skill directory
+ *   --list          print the supported agent directory map
+ *   --global        install to all known user-level directories, requires --yes
+ *   --dry-run       print the target without writing
+ */
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SKILL_NAME = 'yotta-dev-mcp';
+const PKG_ROOT = path.join(__dirname, '..');
+const AGENT_DIRS = {
+  claude: { label: 'Claude Code', dirs: ['.claude/skills'] },
+  cursor: { label: 'Cursor', dirs: ['.cursor/skills', '.agents/skills'] },
+  codex: { label: 'Codex', dirs: ['.codex/skills'] },
+  gemini: { label: 'Gemini CLI', dirs: ['.gemini/skills', '.agents/skills'] },
+  goose: { label: 'Goose', dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp: { label: 'Amp', dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode: { label: 'OpenCode', dirs: ['.config/opencode/skills'] },
+  windsurf: { label: 'Windsurf', dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy', dirs: ['.workbuddy/skills'] },
+  kiro: { label: 'Kiro', dirs: ['.kiro/skills'] },
+  trae: { label: 'Trae Code CLI', dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE', dirs: ['.trae-cn/skills'] },
+  qwen: { label: 'Qwen Code', dirs: ['.qwen/skills'] },
+  comate: { label: 'Comate', dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code', dirs: ['.codebuddy/skills'] },
+  kimi: { label: 'Kimi Code CLI', dirs: ['.kimi/skills'] },
+  agents: { label: 'AGENTS.md', dirs: ['.agents/skills'] },
+};
+
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function shouldSkip(name) {
+  return name === 'package.json' || name === 'bin' || name === 'node_modules' ||
+    name === '.git' || name === '__pycache__' || name.indexOf('test_') === 0 ||
+    name.endsWith('.pyc') || name.endsWith('.pyo');
+}
+
+function copyDir(source, target) {
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (shouldSkip(entry.name)) continue;
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function installTo(directory, dryRun) {
+  const target = path.join(directory, SKILL_NAME);
+  if (dryRun) {
+    console.log('[dry-run] install -> ' + target);
+    return;
+  }
+  copyDir(PKG_ROOT, target);
+  console.log('installed -> ' + target);
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.indexOf('--dry-run') !== -1;
+  const yes = args.indexOf('--yes') !== -1 || args.indexOf('-y') !== -1;
+  const list = args.indexOf('--list') !== -1 || args.indexOf('-l') !== -1;
+  const global = args.indexOf('-g') !== -1 || args.indexOf('--global') !== -1;
+  const dirIndex = args.indexOf('--dir');
+  const agentIndex = args.indexOf('--agent');
+  const explicitDir = dirIndex !== -1 ? args[dirIndex + 1] : null;
+  const agent = agentIndex !== -1 ? String(args[agentIndex + 1]).toLowerCase() : null;
+
+  if (list) {
+    for (const [key, value] of Object.entries(AGENT_DIRS)) {
+      console.log('  ' + key.padEnd(10) + value.label.padEnd(18) +
+        value.dirs.map(displayDir).join(', '));
+    }
+    return;
+  }
+  if (explicitDir) {
+    installTo(explicitDir, dryRun);
+    return;
+  }
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.error('Unknown agent: ' + agent + '. Use --dir <path>.');
+      process.exitCode = 2;
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]), dryRun);
+    return;
+  }
+  if (global) {
+    if (!yes) {
+      console.error('Refusing --global without --yes. Use --dry-run to preview.');
+      process.exitCode = 2;
+      return;
+    }
+    const seen = new Set();
+    for (const value of Object.values(AGENT_DIRS)) {
+      for (const rel of value.dirs) {
+        if (seen.has(rel)) continue;
+        seen.add(rel);
+        installTo(resolveUserDir(rel), dryRun);
+      }
+    }
+    return;
+  }
+  console.error('Choose --agent <name>, --dir <path>, or --list. Use --global --yes explicitly.');
+  process.exitCode = 2;
+}
+
+main();

package/bin/yotta-dev-mcp.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * yotta-dev-mcp launcher.
+ *
+ * Default: start the stdio MCP server.
+ * Install flags: delegate to bin/install.js.
+ */
+'use strict';
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+const SERVER = path.join(PKG_ROOT, 'scripts', 'yotta_dev_mcp.py');
+const INSTALL_FLAGS = ['--agent', '--dir', '--list', '-l', '-g', '--global', '--dry-run', '--yes'];
+
+function isInstallRequest(args) {
+  return args.some(function (item) {
+    if (INSTALL_FLAGS.indexOf(item) !== -1) return true;
+    return item.indexOf('--agent=') === 0 || item.indexOf('--dir=') === 0;
+  });
+}
+
+function findPython() {
+  const candidates = [];
+  if (process.env.YOTTA_MCP_PYTHON) candidates.push(process.env.YOTTA_MCP_PYTHON);
+  candidates.push('python3', 'python', 'py');
+  for (let i = 0; i < candidates.length; i++) {
+    try {
+      const result = spawnSync(candidates[i], ['--version'], { encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) return candidates[i];
+    } catch (error) {
+      // Try the next candidate.
+    }
+  }
+  return 'python';
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.indexOf('--version') !== -1 || args.indexOf('-v') !== -1) {
+    process.stdout.write(require(path.join(PKG_ROOT, 'package.json')).version + '\n');
+    return;
+  }
+  if (isInstallRequest(args)) {
+    require(path.join(__dirname, 'install.js'));
+    return;
+  }
+  const python = findPython();
+  const child = spawn(python, [SERVER].concat(args), { stdio: 'inherit' });
+  child.on('exit', function (code) { process.exit(code || 0); });
+  child.on('error', function (error) {
+    process.stderr.write('yotta-dev-mcp: cannot start Python MCP server: ' + error.message + '\n');
+    process.exit(1);
+  });
+}
+
+main();

package/install.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "$(uname -s)" in
+  MINGW*|MSYS*) SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -W)" ;;
+esac
+
+exec node "$SOURCE_DIR/bin/install.js" "$@"