@yottameta/yotta-dev-mcp 0.2.3 → 0.2.5

package/.review-allowlist.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "entries": [
+    {
+      "path": "yotta_dev_mcp.py",
+      "rule": "debug-print",
+      "line": 710,
+      "reason": "CLI --version output"
+    },
+    {
+      "path": "yotta_dev_mcp.py",
+      "rule": "debug-print",
+      "line": 713,
+      "reason": "CLI --help usage line"
+    },
+    {
+      "path": "yotta_dev_mcp.py",
+      "rule": "debug-print",
+      "line": 714,
+      "reason": "CLI --help core profile line"
+    },
+    {
+      "path": "yotta_dev_mcp.py",
+      "rule": "debug-print",
+      "line": 715,
+      "reason": "CLI --help full profile line"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+# Changelog
+
+## v0.2.5 (2026-10-31)
+
+安全热修批次（ClawHub 0.2.4 扫描复核）：
+
+- `review_diff`：`base` 先解析为 commit SHA（`git rev-parse --verify --end-of-options`），
+  拒绝以 `-` 开头、含空白、超长或无法解析的 revision；防止 `--output=` 等 Git 选项注入
+  在仓库外写文件。
+- `workflow_state`：原子写入改为同目录随机独占临时文件 + `os.replace`；备份同样先写
+  随机临时文件；拒绝目标 / 祖先路径中的 symlink、junction 等 reparse point；预置
+  `.tmp` / `.bak` 链接不会再重定向写入。
+- 回归：新增 option injection、valid base、temp / backup / hardlink / junction 用例；
+  全量测试 **199（3 skip）**。
+
+## v0.2.4 (2026-10-31)
+
+外部缺陷报告修复批次：
+
+- `architecture_review`：UTF-8 BOM 解码修正；规则零证据（`decided_imports=0`）改判
+  `UNKNOWN` 并输出 `rule-no-evidence` / `rule-no-source-modules`。
+- `review_code` / `review_diff`：`eval-exec` 排除 `.exec(`；单行字符串 / 注释遮罩；
+  新增 `.review-allowlist.json`（或 `.yotta/review-allowlist.json`）精确豁免
+  （path + rule + line + reason，无通配符，非法配置 fail-closed）。
+- legacy `initialize` 返回当前工具档位 instructions；SKILL.md 增加运行期档位自检。
+- `repo_map` / `review_code` 忽略 `temp` / `tmp` / `.yottameta` / `_bak*` /
+  `vendor` / `third_party`。
+- `scan_secrets`：补 6-7 字符弱口令规则并去重高熵重复；`find_code` 支持
+  `def ` / `class ` / `function ` 前缀。
+- `self_test` source 档增加 SKILL.md「当前版本」正文检查；SKILL.md / CHANGELOG
+  版本节对齐。
+- 回归：P0 / P1 / P2 新增用例；全量测试基线 176（1 skip）。
+
 ## v0.2.3 (2026-10-01)
 
 - 安装器卫生批次：`bin/install.js` / `install.sh` 统一（未知参数报错 exit 2、`--help` / `--version`、残留清理白名单、嵌套载荷保留）；由模板单一真源渲染，接入漂移门禁。
@@ -14,8 +47,6 @@
 - `--help` / `--version` 支持；非法分组值以中文用法错误 + 退出码 2 拒绝。
 - 回归：新增 7 项分档用例（默认 full / core 列表与顺序 / core 拒绝 full 专属工具 / schema 预算 / 非法值拒绝 / stdio 两种端到端）；元开全量 189/189（1 skip）。
 
-# Changelog
-
 ## v0.2.1 (2026-09-25)
 
 **缺陷修复批次（LedgerHouse 实测 + 元开自审）**
@@ -38,7 +69,7 @@
   `file://` 百分号编码路径、常见二进制 / 源码 / 文档后缀、带 `sha*` / hash /
   checksum / digest / integrity 上下文的 32/40/64/128 位十六进制；
   `api-key` / token / AWS / 私钥规则不放宽，真随机高熵 token 仍会命中。
-- `review_code` / `repo_map` 共用忽略规则：新增 `.workflow` / `.codex` /
+- `review_code` / `repo_map` 共用目录排除规则：新增 `.workflow` / `.codex` /
   `.cursor` / `.claude` / `.agents` / `scratch` / `_probe` / `probe` /
   `sandbox` / `debug` 等目录与 `probe_*` / `_probe_*` / `scratch_*` /
   `tmp_*` / `temp_*` / `*_tmp` 文件名兜底；`scan_secrets` 仍扫描全部文件，

package/README.md

@@ -18,14 +18,14 @@ Deterministic local development tools exposed over a stdio MCP server.
 | `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. |
+| `review_diff` | Review only added lines in a unified diff; `base` resolves to a commit SHA. |
 | `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. |
+| `workflow_state` | Read `.workflow` and optionally append an explicit log entry; writes are atomic and reject link paths. |
 
 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

package/README.zh-CN.md

@@ -18,14 +18,14 @@
 | `find_code` | 符号与文本定位，结果有数量上限。 |
 | `compress_output` | 压缩长日志，保留错误、错误栈和首尾上下文。 |
 | `review_code` | 规则化代码评审，输出文件、行号、证据与建议。 |
-| `review_diff` | 只评审 unified diff 的新增行。 |
+| `review_diff` | 只评审 unified diff 的新增行；`base` 先解析为 commit SHA。 |
 | `mcp_doctor` | 只读检查技能目录与 MCP JSON 配置。 |
 | `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描，证据强制脱敏。 |
 | `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查。 |
 | `check_publish_readiness` | 版本对齐、发布文件与包元数据检查。 |
 | `run_checks` | 运行白名单测试 / lint / compile，执行必须显式开启。 |
 | `scaffold_skill` | 规划或生成最小技能脚手架，默认 dry-run。 |
-| `workflow_state` | 读取 `.workflow`，可选显式追加快照日志。 |
+| `workflow_state` | 读取 `.workflow`，可选显式追加快照日志；写入原子化并拒绝链接路径。 |
 
 默认只读；`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集，
 以及 `run_adapter` 的 `action=run` 必须显式 `allow_execute=true`，

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.3
+version: 0.2.5
 license: MIT
 ---
 
@@ -49,6 +49,11 @@ python scripts/yotta_dev_mcp.py --tools full   # 18 工具（默认）
 `full` 暴露全部工具，适合按需调用、不常驻的场景。`core` 模式下调用 full 专属工具会返回
 明确提示（提示用 `--tools full` 重启）。
 
+运行期自检：先看客户端 `tools/list` 实际返回。只有 5 个工具即 core 档；需要
+`system_model` / `architecture_review` 等 full 专属工具时，用 `--tools full` 重启。
+服务端不会在 `tools/list` 之外补发隐藏工具，legacy `initialize` 与 modern
+`server/discover` 都会在 instructions 中报告当前档位。
+
 自动接入说明：AI 首次协助配置时，必须先展示目标配置文件、完整配置片段和影响，
 并获得用户明确同意后再写入 `mcpServers`。用户拒绝时不要写文件，直接提供上面的启动命令
 让用户手动接入。
@@ -62,19 +67,19 @@ python scripts/yotta_dev_mcp.py --tools full   # 18 工具（默认）
 | `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 的测试子集 |
+| `self_test` | source 档：文件 / 版本 / 工具契约 / 写闸门 / 反证；installed 档：文件 / 版本 / 反证（3 项） | 仅显式 allow_execute 的测试子集 |
 | `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与哈希 | 仅 action=run + 显式 allow_execute |
 | `find_code` | 符号 / 文本定位，结果有上限 | 否 |
 | `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
 | `review_code` | 规则化代码评审，带行号与建议；忽略 `.workflow` / `scratch` / `_probe` 等临时目录 | 否 |
-| `review_diff` | 只评审 diff 的新增行 | 否 |
+| `review_diff` | 只评审 diff 的新增行；`base` 先解析为 commit SHA，拒绝选项注入 | 否 |
 | `mcp_doctor` | 技能版本与多宿主 MCP 配置体检；返回 coverage，只列 server 名，不含 command / env | 否 |
 | `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 |
+| `workflow_state` | 读取 `.workflow`，可选显式追加日志；写入拒绝链接路径并使用原子替换 | 仅显式 apply |
 
 详细契约见 `references/tools.md`；架构契约、评审语义与影响锥字段见 `references/architecture-contract.md`。
 
@@ -83,12 +88,21 @@ python scripts/yotta_dev_mcp.py --tools full   # 18 工具（默认）
 - 会执行项目代码的工具默认关闭：`run_checks`、`verify_change` 的 L2-L4 策略检查、`self_test` 的测试子集都必须显式 `allow_execute=true`，且只运行白名单检查或已声明的策略检查。
 - 外部适配器只在用户已安装时接入：`run_adapter` 不安装、不下载、不访问远端、不接收任意命令参数；工具缺失或配置缺失一律返回 `UNKNOWN` 并给出 next_step。
 - `scaffold_skill` / `workflow_state` 默认只预览，显式 `apply=true` 才写入；脚手架拒绝覆盖已有非空目录，状态写入使用原子替换并为被覆盖文件保留 `.bak`。
+- `workflow_state` 写入会拒绝目标或祖先路径中的 symlink / junction 等链接重定向；
+  临时文件使用随机独占名，避免可预测 `.tmp` / `.bak` 路径被预置链接利用。
+- `review_code` / `review_diff` 支持 `.review-allowlist.json`（或 `.yotta/review-allowlist.json`）精确豁免（path + rule + line + reason，无通配符）；非法配置 fail-closed，不抑制 findings。
+- `review_diff` 的 `base` 必须是可解析 Git revision；以 `-` 开头、含空白或无法解析的值会被拒绝，
+  防止 `--output=` 等选项注入。
 - 不联网，不查询包是否存在于公共仓库。
 - 不读取或修改 YottaCode 仓库。
 - 结论是确定性静态判断，不替代人工评审与最终决策。
 
 ## 当前版本
 
+- v0.2.5（2026-10-31）：安全热修——`review_diff` 的 `base` 先解析为 commit SHA，拒绝 Git 选项注入；`workflow_state` 改为随机独占临时文件 + 原子替换，备份同样原子化，并拒绝 symlink / junction 等链接路径；新增 option injection、temp / backup / hardlink / junction 回归。
+- v0.2.4（2026-10-31）：外部缺陷报告修复——`architecture_review` 修 BOM 假 PASS 与零证据 PASS；legacy `initialize` 报告当前工具档位；`review_code` / `review_diff` 修 `.exec(` 与字符串内待办标记误报并新增精确 allowlist；补齐临时 / 备份目录忽略；`scan_secrets` 补弱口令并去重；`find_code` 支持 `def ` 前缀；`self_test` 增加当前版本正文检查。
+- v0.2.3（2026-10-01）：安装器卫生批次——`bin/install.js` / `install.sh` 统一，未知参数 exit 2、`--help` / `--version`、残留清理白名单与嵌套载荷保留。
+- v0.2.2（2026-09-26）：新增 `--tools core|full` 工具分组；core 5 工具 / full 18 工具，core 拒绝 full 专属工具。
 - v0.2.1（2026-09-25）：缺陷修复批次——`mcp_doctor` 改为多宿主 / 多根 / JSON+JSONC+TOML 子集发现并返回 coverage；`self_test(mode="installed")` 按精简分发副本 / npm / plugin / r0 形态判断 banner；`repo_map` 修复 `from . import X` 解析；`scan_secrets` 过滤路径 / 哈希 / 文件名噪声；`review_code` / `repo_map` 忽略 `.workflow` / `scratch` / `_probe` 等临时目录。
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-dev-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: 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 and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
   "license": "MIT",
   "keywords": [
@@ -20,6 +20,7 @@
     "CHANGELOG.md",
     "install.sh",
     "server.json",
+    ".review-allowlist.json",
     "references",
     "scripts",
     "assets",

package/references/tools.md

@@ -124,10 +124,11 @@ Input:
 - `timeout` (optional, default 120, 1-600).
 
 Source mode checks required files, version alignment across `package.json` /
-`SKILL.md` / `CHANGELOG.md` / `server.json` / engine `VERSION`, protocol tool names
-and `inputSchema.additionalProperties=false`, fail-closed defaults for every write or
-execute gate, and counterexamples. Installed mode checks `SKILL.md` and the installed
-asset payload, and records source-only checks as out of scope.
+`SKILL.md` / `CHANGELOG.md` / `server.json` / engine `VERSION`, the SKILL.md
+current-version body, protocol tool names and
+`inputSchema.additionalProperties=false`, fail-closed defaults for every write or
+execute gate, and counterexamples. Installed mode runs three checks: files,
+skill-version and verifier-counterexamples; source-only checks are out of scope.
 
 The counterexample suite is in-process and deterministic: a seeded forbidden
 dependency must be `FAIL`, removing the rule must stop the failure, an invalid
@@ -202,7 +203,9 @@ Each finding contains `path`, `line`, `rule`, `severity`, `evidence`, `suggestio
 Input:
 
 - `diff_text` or `path` (one required).
-- `base` (optional git revision when `path` is used).
+- `base` (optional git revision when `path` is used). It is resolved to a commit SHA
+  before `git diff` runs; option-like, whitespace-containing, oversized or
+  unresolvable revisions are rejected.
 - `max_findings` (optional).
 
 Only added lines are reviewed. Output: `files`, `findings`, `truncated`.
@@ -212,6 +215,23 @@ directories, scratch / probe / sandbox / debug directories and probe/temp
 file names do not flood the result. `review_diff` only reviews added lines,
 so it is unaffected by directory traversal.
 
+Optional `.review-allowlist.json` (or `.yotta/review-allowlist.json`) suppresses
+known-intentional findings by exact path + rule + line. No wildcards are
+supported; `reason` is required. The root-level file is copied by the installer,
+so installed copies keep the same exemptions.
+
+```json
+{
+  "version": 1,
+  "entries": [
+    {"path": "scripts/example.py", "rule": "debug-print", "line": 12, "reason": "CLI help output"}
+  ]
+}
+```
+
+Output adds `suppressed`, `suppressed_findings` and `allowlist_errors`.
+An invalid allowlist fails closed: findings are not suppressed.
+
 ## mcp_doctor
 
 Input:
@@ -287,4 +307,6 @@ Input: `root`, `action` (`read` / `append-log` / `append-file`), optional
 `date`, `text`, `file`, explicit `apply=true`.
 
 Output: `ok`, `files`, `missing`, `excerpts` for read; `target`, `applied`,
-`preview` for writes. Writes are atomic and keep a `.bak` of an existing file.
+`preview` for writes. Writes use a random exclusive temporary file plus
+`os.replace`, keep a `.bak` of an existing file, and reject target or ancestor
+paths that are symlinks, junctions or other reparse points.

package/scripts/dev_architecture.py

@@ -28,6 +28,10 @@ def _review_rules(contract, model, unknown_sink, violation_sink):
     checked = []
     for rule in contract["rules"]:
         severity = rule.get("severity") or dev_contract.RULE_DEFAULT_SEVERITY
+        source_modules = [
+            item["id"] for item in model["modules"]
+            if module_layers.get(item["id"]) == rule["from"]
+        ]
         violations = 0
         undecided = 0
         decisive = 0
@@ -82,6 +86,24 @@ def _review_rules(contract, model, unknown_sink, violation_sink):
             status = "WARN"
         elif undecided:
             status = "UNKNOWN"
+        elif decisive == 0:
+            status = "UNKNOWN"
+            if source_modules:
+                unknown_sink.append({
+                    "kind": "rule-no-evidence",
+                    "id": rule["id"],
+                    "rule": rule["id"],
+                    "detail": "the from layer has modules but no decisive import was found",
+                    "next_step": "add an import that exercises this rule or remove the rule",
+                })
+            else:
+                unknown_sink.append({
+                    "kind": "rule-no-source-modules",
+                    "id": rule["id"],
+                    "rule": rule["id"],
+                    "detail": "the from layer has no modules to review",
+                    "next_step": "add modules to the from layer or remove the rule",
+                })
         else:
             status = "PASS"
         checked.append({
@@ -92,6 +114,7 @@ def _review_rules(contract, model, unknown_sink, violation_sink):
             "severity": severity,
             "claim": rule.get("claim"),
             "status": status,
+            "source_modules": len(source_modules),
             "decided_imports": decisive,
             "violations": violations,
             "undecided_imports": undecided,

package/scripts/dev_common.py

@@ -13,7 +13,11 @@ IGNORE_DIRS = {
     ".workflow", ".codex", ".cursor", ".claude", ".agents",
     "scratch", "_scratch", "_probe", "probe", "probes",
     "sandbox", ".sandbox", "debug", "_debug",
+    "temp", "tmp", ".yottameta", "vendor", "third_party",
 }
+IGNORE_DIR_PATTERNS = (
+    re.compile(r"(?i)^_bak(?:[_-].*)?$"),
+)
 IGNORE_TEMP_FILE_RE = re.compile(
     r"(?i)^(?:probe[_-].*|_probe[_-].*|scratch[_-].*|_scratch[_-].*|tmp_.*|temp_.*|.*_tmp)"
     r"\.(?:py|js|jsx|mjs|cjs|ts|tsx|sh|ps1|go|rs|java|kt|kts|rb|php)$"
@@ -83,6 +87,12 @@ def source_exts():
     return set(SOURCE_EXTS)
 
 
+def _is_ignored_dir(name):
+    return name in IGNORE_DIRS or any(
+        pattern.match(name) for pattern in IGNORE_DIR_PATTERNS
+    )
+
+
 def _json_safe(value):
     if isinstance(value, Path):
         return str(value)
@@ -100,7 +110,7 @@ def _read_text(path):
     data = path.read_bytes()
     if b"\x00" in data[:4096]:
         raise ValueError("二进制文件不参与文本扫描: %s" % path)
-    return data.decode("utf-8", errors="replace")
+    return data.decode("utf-8-sig", errors="replace")
 
 
 def _iter_files(root, extensions=None, max_files=5000, all_files=False, ignore_temp=True):
@@ -108,7 +118,7 @@ def _iter_files(root, extensions=None, max_files=5000, all_files=False, ignore_t
     extensions = set(extensions or TEXT_EXTS)
     count = 0
     for current, dirs, files in os.walk(str(root)):
-        dirs[:] = sorted(d for d in dirs if d not in IGNORE_DIRS)
+        dirs[:] = sorted(d for d in dirs if not _is_ignored_dir(d))
         for name in sorted(files):
             if ignore_temp and IGNORE_TEMP_FILE_RE.match(name):
                 continue

package/scripts/dev_engine.py

@@ -13,8 +13,10 @@ import math
 import os
 import re
 import shutil
+import stat
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 import dev_contract
@@ -41,7 +43,7 @@ from dev_model import (
 )
 from dev_rules import REVIEW_RULES
 
-VERSION = "0.2.3"
+VERSION = "0.2.5"
 
 
 
@@ -100,7 +102,13 @@ def repo_map(path, max_files=2000):
 
 
 def _classify_match(line, query):
-    escaped = re.escape(query)
+    normalized = re.sub(
+        r"^\s*(?:async\s+)?(?:def|class|function|export\s+function|const|let|var)\s+",
+        "",
+        str(query),
+    ).strip()
+    target = normalized or str(query)
+    escaped = re.escape(target)
     if re.search(r"^\s*(?:async\s+)?def\s+%s\b" % escaped, line):
         return "definition"
     if re.search(r"^\s*class\s+%s\b" % escaped, line):
@@ -205,10 +213,125 @@ def compress_output(text=None, file=None, max_chars=4000, head_lines=40, tail_li
     }
 
 
+def _split_code_comment(line_text, rel):
+    language = _language(rel)
+    if language in ("python", "shell"):
+        markers = ("#",)
+    elif language in ("javascript", "typescript"):
+        markers = ("//", "/*")
+    else:
+        markers = ("#", "//", "/*")
+    stripped = line_text.lstrip()
+    if stripped.startswith("*") and not stripped.startswith("*/"):
+        return "", line_text
+    quote = None
+    escaped = False
+    index = 0
+    while index < len(line_text):
+        char = line_text[index]
+        if quote:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+        elif char in ("'", '"', "`"):
+            quote = char
+        else:
+            for marker in markers:
+                if line_text.startswith(marker, index):
+                    return line_text[:index], line_text[index:]
+        index += 1
+    return line_text, ""
+
+
+def _mask_strings(code):
+    chars = list(code)
+    quote = None
+    escaped = False
+    for index, char in enumerate(chars):
+        if quote:
+            if escaped:
+                escaped = False
+                chars[index] = " "
+            elif char == "\\":
+                escaped = True
+                chars[index] = " "
+            elif char == quote:
+                quote = None
+            else:
+                chars[index] = " "
+        elif char in ("'", '"', "`"):
+            quote = char
+    return "".join(chars)
+
+
+def _allowlist_candidates(root):
+    current = Path(root).resolve()
+    candidates = []
+    for base in (current, *current.parents):
+        candidates.append(base / ".yotta" / "review-allowlist.json")
+        candidates.append(base / ".review-allowlist.json")
+        if (base / ".git").exists():
+            break
+    return candidates
+
+
+def _load_review_allowlist(root):
+    for candidate in _allowlist_candidates(root):
+        if not candidate.is_file():
+            continue
+        try:
+            data = json.loads(_read_text(candidate))
+        except Exception as exc:  # noqa: BLE001
+            return {}, [{"path": str(candidate), "detail": str(exc)}]
+        entries = data.get("entries") if isinstance(data, dict) else None
+        if not isinstance(entries, list):
+            return {}, [{"path": str(candidate), "detail": "entries must be a list"}]
+        allowlist = {}
+        errors = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                errors.append({"path": str(candidate), "detail": "entry must be an object"})
+                continue
+            rel = entry.get("path")
+            rule = entry.get("rule")
+            line = entry.get("line")
+            reason = entry.get("reason")
+            if not isinstance(rel, str) or not isinstance(rule, str) or not reason:
+                errors.append({"path": str(candidate), "detail": "path, rule and reason are required"})
+                continue
+            if isinstance(line, bool) or not isinstance(line, int) or line < 1:
+                errors.append({"path": str(candidate), "detail": "line must be a positive integer"})
+                continue
+            normalized = rel.replace("\\", "/")
+            while normalized.startswith("./"):
+                normalized = normalized[2:]
+            allowlist[(normalized, rule, line)] = str(reason)
+        return allowlist, errors
+    return {}, []
+
+
+def _apply_review_allowlist(findings, allowlist):
+    kept = []
+    suppressed = []
+    for item in findings:
+        key = (item["path"], item["rule"], item["line"])
+        if key in allowlist:
+            suppressed.append(dict(item, reason=allowlist[key]))
+        else:
+            kept.append(item)
+    return kept, suppressed
+
+
 def _review_line(rel, line_no, line_text):
     findings = []
+    code, comment = _split_code_comment(line_text, rel)
+    code = _mask_strings(code)
     for rule, severity, pattern, suggestion in REVIEW_RULES:
-        if pattern.search(line_text):
+        target = comment if rule == "todo-comment" else code
+        if pattern.search(target):
             findings.append({
                 "path": rel,
                 "line": line_no,
@@ -222,6 +345,8 @@ def _review_line(rel, line_no, line_text):
 
 def review_code(path=None, text=None, max_findings=200):
     findings = []
+    allowlist = {}
+    allowlist_errors = []
     if text is not None:
         for line_no, line in enumerate(str(text).splitlines(), 1):
             findings.extend(_review_line("<text>", line_no, line))
@@ -231,6 +356,8 @@ def review_code(path=None, text=None, max_findings=200):
         root = Path(path)
         if not root.exists():
             raise ValueError("路径不存在: %s" % path)
+        allowlist_root = root.parent if root.is_file() else root
+        allowlist, allowlist_errors = _load_review_allowlist(allowlist_root)
         files = [root] if root.is_file() else list(_iter_files(root, extensions=source_exts()))
         base = root.parent if root.is_file() else root
         for file_path in files:
@@ -241,9 +368,16 @@ def review_code(path=None, text=None, max_findings=200):
             rel = _rel(base, file_path)
             for line_no, line in enumerate(lines, 1):
                 findings.extend(_review_line(rel, line_no, line))
-    findings.sort(key=lambda item: (item["path"], item["line"], item["rule"]))
-    truncated = len(findings) > max_findings
-    return {"findings": findings[:max_findings], "truncated": truncated}
+    kept, suppressed = _apply_review_allowlist(findings, allowlist)
+    kept.sort(key=lambda item: (item["path"], item["line"], item["rule"]))
+    truncated = len(kept) > max_findings
+    return {
+        "findings": kept[:max_findings],
+        "truncated": truncated,
+        "suppressed": len(suppressed),
+        "suppressed_findings": suppressed[:max_findings],
+        "allowlist_errors": allowlist_errors,
+    }
 
 
 def _parse_added_lines(diff_text):
@@ -266,13 +400,38 @@ def _parse_added_lines(diff_text):
             line_no += 1
 
 
+def _resolve_git_commit(path, revision):
+    value = str(revision or "").strip()
+    if (
+        not value
+        or len(value) > 200
+        or value.startswith("-")
+        or any(char.isspace() for char in value)
+    ):
+        raise ValueError("base 不是有效 revision")
+    command = [
+        "git", "-C", str(path), "rev-parse", "--verify", "--quiet",
+        "--end-of-options", value + "^{commit}",
+    ]
+    proc = subprocess.run(command, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise ValueError("base revision 无法解析: %s" % value)
+    commit = proc.stdout.strip()
+    if not re.match(r"^[0-9a-fA-F]{40,64}$", commit):
+        raise ValueError("base revision 解析结果非法")
+    return commit
+
+
 def review_diff(diff_text=None, path=None, base=None, max_findings=200):
+    allowlist = {}
+    allowlist_errors = []
     if diff_text is None:
         if not path:
             raise ValueError("review_diff 需要 diff_text 或 path")
+        allowlist, allowlist_errors = _load_review_allowlist(path)
         command = ["git", "-C", str(path), "diff", "--no-ext-diff", "--unified=0"]
         if base:
-            command.append(str(base))
+            command.append(_resolve_git_commit(path, base))
         proc = subprocess.run(command, capture_output=True, text=True)
         if proc.returncode != 0:
             raise ValueError("git diff 失败: %s" % (proc.stderr.strip() or proc.stdout.strip()))
@@ -283,9 +442,17 @@ def review_diff(diff_text=None, path=None, base=None, max_findings=200):
         if rel not in files:
             files.append(rel)
         findings.extend(_review_line(rel, line_no, line))
-    findings.sort(key=lambda item: (item["path"], item["line"], item["rule"]))
-    truncated = len(findings) > max_findings
-    return {"files": files, "findings": findings[:max_findings], "truncated": truncated}
+    kept, suppressed = _apply_review_allowlist(findings, allowlist)
+    kept.sort(key=lambda item: (item["path"], item["line"], item["rule"]))
+    truncated = len(kept) > max_findings
+    return {
+        "files": files,
+        "findings": kept[:max_findings],
+        "truncated": truncated,
+        "suppressed": len(suppressed),
+        "suppressed_findings": suppressed[:max_findings],
+        "allowlist_errors": allowlist_errors,
+    }
 
 
 def _default_skill_dirs():
@@ -307,6 +474,9 @@ def mcp_doctor(skills_dirs=None, config_paths=None, include_defaults=None):
 SECRET_KEY_RE = re.compile(
     r"""(?i)\b(api[_-]?key|access[_-]?key|secret|token|password|passwd|pwd)\b\s*[:=]\s*["']?([^"'\s#]{8,})"""
 )
+WEAK_PASSWORD_RE = re.compile(
+    r"""(?i)\b(password|passwd|pwd)\b\s*[:=]\s*["']?([^"'\s#]{6,7})"""
+)
 AWS_KEY_RE = re.compile(r"\bAKIA[0-9A-Z]{16}\b")
 PRIVATE_KEY_RE = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")
 HIGH_ENTROPY_RE = re.compile(r"[A-Za-z0-9_+/=\-]{32,}")
@@ -381,6 +551,7 @@ def scan_secrets(path=None, text=None, max_findings=200, include_git_history=Fal
     findings = []
     for rel, content in entries:
         for line_no, line in enumerate(content.splitlines(), 1):
+            specific_spans = []
             if PRIVATE_KEY_RE.search(line):
                 findings.append({
                     "path": rel, "line": line_no, "rule": "private-key",
@@ -393,6 +564,7 @@ def scan_secrets(path=None, text=None, max_findings=200, include_git_history=Fal
                     "severity": "critical", "evidence": _redact(match.group(0)),
                     "suggestion": "Rotate the key and move it to a secret manager.",
                 })
+                specific_spans.append(match.span(0))
             for match in SECRET_KEY_RE.finditer(line):
                 name = match.group(1).lower()
                 rule = "api-key" if "api" in name or "access" in name else (
@@ -403,12 +575,25 @@ def scan_secrets(path=None, text=None, max_findings=200, include_git_history=Fal
                     "severity": "high", "evidence": "%s=%s" % (match.group(1), _redact(match.group(2))),
                     "suggestion": "Remove the literal credential and load it from the environment or a secret store.",
                 })
+                specific_spans.append(match.span(2))
+            for match in WEAK_PASSWORD_RE.finditer(line):
+                findings.append({
+                    "path": rel, "line": line_no, "rule": "weak-password",
+                    "severity": "medium",
+                    "evidence": "%s=%s" % (match.group(1), _redact(match.group(2))),
+                    "suggestion": "Use a longer password and load it from the environment or a secret store.",
+                })
+                specific_spans.append(match.span(2))
             for match in HIGH_ENTROPY_RE.finditer(line):
                 token = match.group(0)
                 if (
                     _entropy(token) >= 4.0
                     and not PRIVATE_KEY_RE.search(line)
                     and not _high_entropy_noise(line, token, match.start(), match.end())
+                    and not any(
+                        start < match.end() and match.start() < end
+                        for start, end in specific_spans
+                    )
                 ):
                     findings.append({
                         "path": rel, "line": line_no, "rule": "high-entropy-token",
@@ -756,15 +941,80 @@ def scaffold_skill(name, output_dir, apply=False, description=None):
     }
 
 
+def _write_temp_text(path, content):
+    descriptor, name = tempfile.mkstemp(
+        prefix="." + path.name + ".", suffix=".tmp", dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(content)
+    except BaseException:
+        try:
+            os.unlink(name)
+        except OSError:
+            pass
+        raise
+    return Path(name)
+
+
+def _write_temp_bytes(path, data):
+    descriptor, name = tempfile.mkstemp(
+        prefix="." + path.name + ".", suffix=".tmp", dir=str(path.parent),
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(data)
+    except BaseException:
+        try:
+            os.unlink(name)
+        except OSError:
+            pass
+        raise
+    return Path(name)
+
+
+def _preserve_mode(source, target):
+    try:
+        os.chmod(str(target), os.stat(str(source)).st_mode & 0o777)
+    except OSError:
+        pass
+
+
+def _is_link_like(path):
+    try:
+        info = os.lstat(str(path))
+    except OSError:
+        return False
+    if stat.S_ISLNK(info.st_mode):
+        return True
+    attributes = getattr(info, "st_file_attributes", 0)
+    reparse_point = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return bool(attributes & reparse_point)
+
+
+def _assert_no_symlink_path(path, root):
+    root = Path(root)
+    current = Path(path)
+    while True:
+        if _is_link_like(current):
+            raise ValueError("拒绝通过符号链接写入: %s" % current)
+        if current == root or current.parent == current:
+            break
+        current = current.parent
+
+
 def _atomic_write(path, content):
     path = Path(path)
     path.parent.mkdir(parents=True, exist_ok=True)
     backup = None
     if path.exists():
         backup = path.with_suffix(path.suffix + ".bak")
-        shutil.copy2(str(path), str(backup))
-    temporary = path.with_suffix(path.suffix + ".tmp")
-    temporary.write_text(content, encoding="utf-8")
+        temporary_backup = _write_temp_bytes(backup, path.read_bytes())
+        _preserve_mode(path, temporary_backup)
+        os.replace(str(temporary_backup), str(backup))
+    temporary = _write_temp_text(path, content)
+    if path.exists():
+        _preserve_mode(path, temporary)
     os.replace(str(temporary), str(path))
     return str(backup) if backup else None
 
@@ -803,6 +1053,7 @@ def workflow_state(root, action="read", date=None, text=None, file=None, apply=F
     body = (text or "").rstrip() + "\n"
     preview = body
     if apply:
+        _assert_no_symlink_path(target, Path(root))
         target.parent.mkdir(parents=True, exist_ok=True)
         if target.exists():
             existing = _read_text(target)

package/scripts/dev_rules.py

@@ -12,7 +12,7 @@ import re
 REVIEW_RULES = [
     ("bare-except", "medium", re.compile(r"^\s*except\s*:"),
      "Catch a specific exception instead of a bare except."),
-    ("eval-exec", "high", re.compile(r"\b(?:eval|exec)\s*\("),
+    ("eval-exec", "high", re.compile(r"(?<![\w.$])(?:eval|exec)\s*\("),
      "Avoid dynamic evaluation; use explicit parsing or dispatch."),
     ("shell-true", "high", re.compile(r"\bshell\s*=\s*True\b"),
      "Do not invoke a shell with untrusted input; pass an argument list."),

package/scripts/dev_selftest.py

@@ -284,6 +284,33 @@ def _self_test_version_check(root, mode):
         }], "align package, SKILL, CHANGELOG, server and engine versions"
     return "PASS", [], None
 
+def _self_test_skill_version_body(root):
+    skill = root / "SKILL.md"
+    if not skill.is_file():
+        return "UNKNOWN", [{
+            "code": "skill-missing", "path": "SKILL.md",
+            "detail": "SKILL.md is missing",
+        }], "restore SKILL.md"
+    text = _read_text(skill)
+    version = _frontmatter_version(text)
+    if not version:
+        return "FAIL", [{
+            "code": "missing-version", "path": "SKILL.md",
+            "detail": "SKILL.md has no version field",
+        }], "restore a valid SKILL.md version"
+    section = re.search(r"(?ms)^##\s+当前版本\s*$(.*?)(?=^##\s+|\Z)", text)
+    if not section:
+        return "UNKNOWN", [{
+            "code": "version-section-missing", "path": "SKILL.md",
+            "detail": "SKILL.md has no 当前版本 section",
+        }], "add a 当前版本 section"
+    if not re.search(r"(?m)^\s*-\s*v?%s\b" % re.escape(version), section.group(1)):
+        return "FAIL", [{
+            "code": "version-section-drift", "path": "SKILL.md",
+            "detail": "current version %s is not listed in 当前版本" % version,
+        }], "add the current version to 当前版本"
+    return "PASS", [], None
+
 def _self_test_tool_contracts(root):
     protocol_path = root / "scripts" / "yotta_dev_mcp.py"
     engine_path = root / "scripts" / "dev_engine.py"
@@ -420,6 +447,15 @@ def self_test(path, mode="auto", allow_execute=False, timeout=120):
     checks = [files_check, version_check]
     unverified = []
     if mode == "source":
+        body_status, body_evidence, body_next = _self_test_skill_version_body(root)
+        checks.append({
+            "id": "skill-version-body",
+            "status": body_status,
+            "severity": "high",
+            "claim": "SKILL.md current-version section lists the frontmatter version",
+            "evidence": body_evidence,
+            "next_step": body_next,
+        })
         tool_status, tool_evidence, tool_next = _self_test_tool_contracts(root)
         checks.append({
             "id": "tool-contracts",

package/scripts/yotta_dev_mcp.py

@@ -660,6 +660,11 @@ def handle_message(msg, tool_profile=None):
                 "protocolVersion": MCP_PROTOCOL_LEGACY,
                 "capabilities": {"tools": {}},
                 "serverInfo": SERVER_INFO,
+                "instructions": (
+                    "yotta-dev-mcp exposes deterministic local development tools. "
+                    "Current tool profile: %s (%d tools). Use --tools full to expose all tools."
+                    % (normalize_tool_profile(tool_profile), len(mcp_tools(tool_profile)))
+                ),
             },
         }
     if method == "ping":

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/YottaMeta/yotta-dev-mcp",
     "source": "github"
   },
-  "version": "0.2.3",
+  "version": "0.2.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@yottameta/yotta-dev-mcp",
-      "version": "0.2.3",
+      "version": "0.2.5",
       "transport": {
         "type": "stdio"
       }