dsh-code-security 0.3.4 → 0.3.7

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# 更新记录
+
+[返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
+
+[历史英文记录](docs/CHANGELOG.en.md)
+
+## 0.3.7 (2026-10-05)
+
+- 扫描、策略、报告和 git diff 使用当前会话工作区；支持取消并跳过目录联接。锁定合并历史与基线写入，损坏记录和无效策略明确报错并保留原文件。
+
+## 0.3.6 (2026-09-28)
+
+- 更新官方 Harness 0.2.0-rc.1 的兼容声明和共同加载验证；运行时代码未变。验证范围见[验证记录](docs/VALIDATION.md)。
+
+## 0.3.5 (2026-09-28)
+
+扫描参数写错时明确报错，避免把 `paths`、`files` 或空目标误当成扫描整个工作区。修复标准模式中结果卡片误显示“0 个文件、未通过”的问题；文件数量、结论与问题列表现在使用实际扫描结果。
+
+## 更早的改动
+
+完整历史可查阅 [GitHub 提交记录](https://github.com/STARDUSTLC666/dsh-code-security/commits/master)。

package/README.en.md

@@ -1,44 +1,46 @@
 # dsh-code-security
 
-## 0.3.4 update (2026-09-27)
+[中文](README.md)
 
-Fixes scan output validation when no baseline exists. SARIF now uses workspace file URIs, relative locations and structured rule descriptions, including paths with spaces and Unicode.
+![dsh-code-security whale girl plugin cover](https://raw.githubusercontent.com/STARDUSTLC666/dsh-code-security/master/assets/cover-whale-girl.png)
 
-Validation host: Harness 0.1.7-rc.2 built from official sources, retaining the local tool-scheduler fix. Build and automated checks pass; interactive coverage and external-service limits are recorded in this release round.
+Run local static security checks on code or Git changes and verify fixes.
 
-![npm](https://img.shields.io/npm/v/dsh-code-security) ![downloads](https://img.shields.io/npm/dm/dsh-code-security) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-code-security) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-code-security?style=social)
+[![npm](https://img.shields.io/npm/v/dsh-code-security)](https://www.npmjs.com/package/dsh-code-security) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-code-security-downloads.svg)](https://www.npmjs.com/package/dsh-code-security)
 
-> Every agent code change passes a local security scan before delivery.
+## What it does
 
-A DeepSeek Harness plugin for AI code security review: deterministic rule engine, git-diff incremental review, fix-verify loop, and policy gate. Methodology borrows from Codex security skills (evidence-first findings, severity ordering, supply-chain layers). Zero runtime dependencies.
+- Scan files, directories or Git diffs with locations and code evidence.
+- Recheck fixes and manage baselines or scan policy.
+- Export Markdown or SARIF reports and inspect dependency manifests.
 
-## Compatibility
+## Install
 
-Verified with official `@deepseek-ai/dsh@0.1.5-rc.1` and Node `24.16.0` on 2026-09-11: all 18 components load alongside Modlens, with passing tool-schema, skill-registration and offline read-only invocation checks. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements match this Harness release: 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
+In DSH Desktop, install `dsh-code-security` from the Plugins panel. If the bundled dsh command is available:
 
-2026-09-13 fix: retain the service receiver when calling `subprocess.spawn`, preventing failures caused by passing the method as an unbound callback. Verified with official `0.1.5-rc.1` and `0.1.5-rc.2` on Node `24.16.0`. `secure_diff` reads a real isolated Git repository through the host subprocess service and reports the changed file and added line.
+```bash
+dsh plugin --profile desktop add dsh-code-security
+```
 
-## Tools
+For the web version, replace `desktop` with `web`. Restart DSH after installation.
 
-| Tool | Purpose | Write |
-| :-- | :-- | :-- |
-| `secure_scan` | Scan files with CWE/severity/line/snippet evidence | state |
-| `secure_diff` | Review only added lines of git diff | state |
-| `secure_fix_verify` | Compare with baseline: closed / remaining / fresh | state |
-| `secure_report` | Aggregate by rule/file with gate verdict | no |
-| `secure_export` | Export SARIF 2.1.0 / Markdown | file write approval |
-| `secure_baseline` | Accept current findings as baseline; gate on new issues only | approval |
-| `secure_deps` | SBOM-lite: parse dependency manifests and version-risk flags | no |
-| `secure_policy_show` | Show .code-security.json | no |
-| `secure_policy_set` | Replace policy JSON | approval |
+## Start using it
 
-40+ deterministic rules: injection, deserialization, weak crypto (including shell TLS bypass flags), secrets, dangerous config, sensitive logging, path traversal, SSRF.
+Ask: “Review the current Git diff for security findings, show evidence and recheck the fixes.”
 
-```bash
-dsh plugin --profile web add dsh-code-security
-```
+## Requirements and configuration
+
+Deterministic rules run locally. See the usage guide for rule coverage, baselines and policy configuration.
+
+Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
+
+## Documentation
+
+- [Usage and troubleshooting](docs/USAGE.en.md)
+- [Changelog](CHANGELOG.md)
+- [Validation scope and history](docs/VALIDATION.md)
+- [Report a problem or suggest a feature](https://github.com/STARDUSTLC666/dsh-code-security/issues)
 
-MIT
 ## License
 
-MIT (see [LICENSE](LICENSE))
+[MIT](LICENSE)

package/README.md

@@ -1,91 +1,46 @@
 # dsh-code-security
 
-## 0.3.4 更新（2026-09-27）
+[English](README.en.md)
 
-修复未设置基线时扫描结果被新版 Harness 拒绝的问题。SARIF 正确使用工作区文件 URI、相对路径和规则描述对象，支持空格与中文文件名。
+![dsh-code-security 鲸鱼娘插件封面](https://raw.githubusercontent.com/STARDUSTLC666/dsh-code-security/master/assets/cover-whale-girl.png)
 
-验证宿主：官方源码构建的 Harness 0.1.7-rc.2（保留本地工具调度器修复）。构建与自动测试通过；实际操作和外部服务限制见本轮验收记录。
+对代码与 Git 改动进行本地静态安全检查，并追踪修复结果。
 
-![npm](https://img.shields.io/npm/v/dsh-code-security) ![downloads](https://img.shields.io/npm/dm/dsh-code-security) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-code-security) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-code-security?style=social)
+[![npm](https://img.shields.io/npm/v/dsh-code-security)](https://www.npmjs.com/package/dsh-code-security) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-code-security-downloads.svg)](https://www.npmjs.com/package/dsh-code-security)
 
-> 让 agent 每次改完代码，先过一道本地安全扫描，修复完了才准交付。
+## 功能
 
-DeepSeek Harness AI 代码安全审查插件：确定性规则引擎 + git diff 增量审查 + 修复闭环 + 策略门禁。借鉴 Codex 安全技能的方法论（漏洞分级、证据优先、供应链分层、Agent 安全），实现为可复现工具。零运行时依赖。
-
-## 工具
-
-| 工具 | 作用 | 写操作 |
-| :-- | :-- | :-- |
-| `secure_scan` | 扫描文件/目录，输出 CWE/严重度/行号/代码片段证据 | 写状态 |
-| `secure_diff` | 只审查 git diff 新增行 | 写状态 |
-| `secure_fix_verify` | 修复后复扫：关闭 / 仍存在 / 新引入 | 写状态 |
-| `secure_report` | 按规则/文件聚合 + 门禁结论 | 否 |
-| `secure_export` | 导出 SARIF 2.1.0 / Markdown 报告 | 写文件审批 |
-| `secure_baseline` | 接受当前已知问题为基线，之后只按新增判定 | 审批门 |
-| `secure_deps` | SBOM-lite：解析依赖清单与版本约束风险 | 否 |
-| `secure_policy_show` | 查看 .code-security.json 策略 | 否 |
-| `secure_policy_set` | 写入策略（排除/忽略/阈值） | 审批门 |
-
-## 规则覆盖（40+）
-
-- 注入：eval / exec / shell=True / SQL 拼接 / innerHTML
-- 反序列化：pickle / yaml.load / ObjectInputStream / Marshal / unserialize
-- 加密：弱哈希、ECB、硬编码 IV/密钥、JWT none、TLS 校验关闭、Shell TLS 绕过（curl -k / wget --no-check-certificate / git sslVerify=false）
-- 凭据：硬编码密码、令牌、私钥、高熵密钥
-- 配置：chmod 777、Docker privileged / latest、npm audit=false、CORS *
-- 泄露：敏感日志、错误堆栈外发、路径穿越、SSRF
-
-发现只包含客观证据与 CWE 编号，不附修复建议——修复方案由 agent 基于证据生成。
-
-## 兼容性
-
-已在官方 `@deepseek-ai/dsh@0.1.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
-
-2026-09-13 修复：保留宿主 `subprocess.spawn` 的服务对象，避免方法独立传递后因 `this` 丢失而报错。已在官方 `0.1.5-rc.1` 和 `0.1.5-rc.2`、Node `24.16.0` 上验证。`secure_diff` 已通过真实宿主进程服务读取隔离 Git 仓库差异，正确识别变更文件和新增行。
+- 扫描文件、目录或 Git diff，报告规则、位置与代码证据。
+- 复扫修复结果，维护问题基线和检查策略。
+- 导出 Markdown / SARIF 报告，检查依赖清单。
 
 ## 安装
 
-```bash
-dsh plugin --profile web add dsh-code-security
-```
-
-## 卸载
+桌面版可在「插件」面板按包名 `dsh-code-security` 安装。已配置 dsh 命令时也可使用：
 
 ```bash
-dsh plugin --profile web remove dsh-code-security
+dsh plugin --profile desktop add dsh-code-security
 ```
 
-卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
 
+## 开始使用
 
-## 使用
+安装后可说：“审查当前 Git 改动的安全问题，给出位置和证据，再复查修复结果。”
 
-```text
-secure_scan { target: src }
-secure_diff { base: HEAD }
-secure_fix_verify { target: src }
-secure_baseline { reason: 历史遗留 }
-secure_deps { target: . }
-```
+## 依赖与配置
 
-策略示例（`.code-security.json`）：
+默认在本机执行确定性规则检查。规则覆盖与基线、策略配置见使用说明。
 
-```json
-{
-  "version": 1,
-  "exclude": ["vendor/**", "generated/**"],
-  "ignore": [{ "ruleId": "SEC-206", "file": "test/**", "reason": "非安全敏感" }],
-  "failOn": "high"
-}
-```
+详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
 
-## 工程
+## 文档
 
-```bash
-pnpm test       # 构建 + 24 个测试
-```
+- [使用与排错](docs/USAGE.md)
+- [更新记录](CHANGELOG.md)
+- [验证范围与历史记录](docs/VALIDATION.md)
+- [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-code-security/issues)
 
-MIT
 ## License
 
-MIT（见 [LICENSE](LICENSE)）
+[MIT](LICENSE)

package/docs/CHANGELOG.en.md

@@ -0,0 +1,15 @@
+# Historical release notes
+
+[Current changelog](../CHANGELOG.md) · [Overview](../README.en.md)
+
+These English notes preserve the earlier translations. The main changelog contains the consolidated version history.
+
+## 0.3.7 (2026-10-05)
+
+- Use the session workspace for scans, policy, reports and git diff. Respect cancellation and skip directory junctions. Lock history/baseline merges and preserve damaged files with explicit errors.
+
+## 0.3.5 (2026-09-28)
+
+Rejects unknown scan arguments and empty targets before scanning or replacing state, preventing misspelled scopes from expanding to the whole workspace. Fixes standard-mode output incorrectly displaying zero files and a failed verdict: counts, verdicts and findings now come from the actual scan result.
+
+Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-28. All 31 plugin tests pass in an isolated environment; all 18 plugins mount together in one host registering 10 tools, with tool schemas and health-check contracts passing. No live ports or external services were exercised in this round.

package/docs/USAGE.en.md

@@ -0,0 +1,31 @@
+# dsh-code-security usage guide
+
+[Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
+
+## Current improvements
+
+Relative stateDir defaults to .code-security in the session workspace. Concurrent scans retain both histories. Damaged records must be inspected after backup rather than silently recreated. Scans skip symlinks and junctions; static rules do not replace a full security audit.
+
+## Tools
+
+| Tool | Purpose | Write |
+| :-- | :-- | :-- |
+| `secure_scan` | Scan files with CWE/severity/line/snippet evidence | state |
+| `secure_diff` | Review only added lines of git diff | state |
+| `secure_fix_verify` | Compare with baseline: closed / remaining / fresh | state |
+| `secure_report` | Aggregate by rule/file with gate verdict | no |
+| `secure_export` | Export SARIF 2.1.0 / Markdown | file write approval |
+| `secure_baseline` | Accept current findings as baseline; gate on new issues only | approval |
+| `secure_deps` | SBOM-lite: parse dependency manifests and version-risk flags | no |
+| `secure_policy_show` | Show .code-security.json | no |
+| `secure_policy_set` | Replace policy JSON | approval |
+
+40+ deterministic rules: injection, deserialization, weak crypto (including shell TLS bypass flags), secrets, dangerous config, sensitive logging, path traversal, SSRF.
+
+```bash
+dsh plugin --profile web add dsh-code-security
+```
+
+## License
+
+MIT (see [LICENSE](../LICENSE))

package/docs/USAGE.md

@@ -0,0 +1,77 @@
+# dsh-code-security 使用说明
+
+[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
+
+## 本次改进
+
+相对 stateDir 默认在会话工作区的 .code-security。并发扫描保留双方历史；记录损坏时先备份排查，不会默默重建。扫描不跟随符号链接或目录联接；静态规则不能代替完整安全审计。
+
+## 工具
+
+| 工具 | 作用 | 写操作 |
+| :-- | :-- | :-- |
+| `secure_scan` | 扫描文件/目录，输出 CWE/严重度/行号/代码片段证据 | 写状态 |
+| `secure_diff` | 只审查 git diff 新增行 | 写状态 |
+| `secure_fix_verify` | 修复后复扫：关闭 / 仍存在 / 新引入 | 写状态 |
+| `secure_report` | 按规则/文件聚合 + 门禁结论 | 否 |
+| `secure_export` | 导出 SARIF 2.1.0 / Markdown 报告 | 写文件审批 |
+| `secure_baseline` | 接受当前已知问题为基线，之后只按新增判定 | 审批门 |
+| `secure_deps` | SBOM-lite：解析依赖清单与版本约束风险 | 否 |
+| `secure_policy_show` | 查看 .code-security.json 策略 | 否 |
+| `secure_policy_set` | 写入策略（排除/忽略/阈值） | 审批门 |
+
+## 规则覆盖（40+）
+
+- 注入：eval / exec / shell=True / SQL 拼接 / innerHTML
+- 反序列化：pickle / yaml.load / ObjectInputStream / Marshal / unserialize
+- 加密：弱哈希、ECB、硬编码 IV/密钥、JWT none、TLS 校验关闭、Shell TLS 绕过（curl -k / wget --no-check-certificate / git sslVerify=false）
+- 凭据：硬编码密码、令牌、私钥、高熵密钥
+- 配置：chmod 777、Docker privileged / latest、npm audit=false、CORS *
+- 泄露：敏感日志、错误堆栈外发、路径穿越、SSRF
+
+发现只包含客观证据与 CWE 编号，不附修复建议——修复方案由 agent 基于证据生成。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-code-security
+```
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-code-security
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+## 使用
+
+```text
+secure_scan { target: src }
+secure_diff { base: HEAD }
+secure_fix_verify { target: src }
+secure_baseline { reason: 历史遗留 }
+secure_deps { target: . }
+```
+
+策略示例（`.code-security.json`）：
+
+```json
+{
+  "version": 1,
+  "exclude": ["vendor/**", "generated/**"],
+  "ignore": [{ "ruleId": "SEC-206", "file": "test/**", "reason": "非安全敏感" }],
+  "failOn": "high"
+}
+```
+
+## 工程
+
+```bash
+pnpm test       # 构建并执行测试
+```
+
+## License
+
+MIT（见 [LICENSE](../LICENSE)）

package/docs/VALIDATION.md

@@ -0,0 +1,15 @@
+# dsh-code-security 验证记录
+
+本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
+
+## 原中文记录
+
+2026-09-13 修复：保留宿主 `subprocess.spawn` 的服务对象，避免方法独立传递后因 `this` 丢失而报错。该路径已在隔离宿主进程服务中实测通过。`secure_diff` 已通过真实宿主进程服务读取隔离 Git 仓库差异，正确识别变更文件和新增行。
+
+## Original English record
+
+2026-09-13 fix: retain the service receiver when calling `subprocess.spawn`, preventing failures caused by passing the method as an unbound callback. Verified against a real isolated host subprocess service. `secure_diff` reads a real isolated Git repository through the host subprocess service and reports the changed file and added line.
+
+## 0.3.6 原验证说明
+
+验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-28）。31 项插件测试在隔离环境全部通过；同一个宿主里 18 个插件共同加载，注册 10 个工具，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务。

package/lib/config.d.ts

@@ -15,6 +15,7 @@ export interface ResolvedSecureConfig {
     maxFileBytes: number;
     failOn: Severity;
     stateDir: string;
+    stateDirRelative?: string;
 }
 export declare const DEFAULT_EXCLUDE_DIRS: string[];
 export declare function resolveConfig(config: SecureConfig | undefined | null, cwd?: string): ResolvedSecureConfig;

package/lib/config.js

@@ -21,7 +21,8 @@ export function resolveConfig(config, cwd = process.cwd()) {
     }
     const failOn = cfg.failOn === 'critical' || cfg.failOn === 'high' || cfg.failOn === 'medium' || cfg.failOn === 'low' ? cfg.failOn : 'medium';
     const stateDir = typeof cfg.stateDir === 'string' && cfg.stateDir.trim() !== '' ? path.resolve(cwd, cfg.stateDir.trim()) : path.join(cwd, '.code-security');
-    return { maxFiles, maxFileBytes, failOn, stateDir };
+    const rawStateDir = typeof cfg.stateDir === 'string' && cfg.stateDir.trim() ? cfg.stateDir.trim() : '.code-security';
+    return { maxFiles, maxFileBytes, failOn, stateDir, ...(path.isAbsolute(rawStateDir) ? {} : { stateDirRelative: rawStateDir }) };
 }
 export function optionalString(args, key) {
     const value = args[key];

package/lib/diff.js

@@ -14,7 +14,7 @@ export async function runGitDiff(runner, cwd, base, target, timeoutMs = 30000, s
     argv.push('--no-ext-diff', '--unified=0', base);
     if (target !== undefined && target.trim() !== '')
         argv.push('--', target.trim());
-    const result = await runner.run(argv, { timeoutMs });
+    const result = await runner.run(argv, { timeoutMs, cwd });
     if (result.exitCode !== 0 && result.exitCode !== 1) {
         throw new Error('git diff 失败（退出码 ' + String(result.exitCode) + '）：' + result.stderr.trim().split(/\r?\n/).slice(-4).join(' | '));
     }

package/lib/extra.d.ts

@@ -5,4 +5,4 @@
  */
 import { type ResolvedSecureConfig } from './config.js';
 import type { SecureToolDefinition } from './tools.js';
-export declare function buildExtraTools(cfg: ResolvedSecureConfig, cwd: string): SecureToolDefinition[];
+export declare function buildExtraTools(cfg: ResolvedSecureConfig, cwd: string, signal?: AbortSignal): SecureToolDefinition[];

package/lib/extra.js

@@ -22,7 +22,7 @@ function compileParameters(spec) {
     }
     return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
 }
-export function buildExtraTools(cfg, cwd) {
+export function buildExtraTools(cfg, cwd, signal) {
     const stateDir = cfg.stateDir;
     const secureBaseline = {
         name: 'secure_baseline',
@@ -51,7 +51,7 @@ export function buildExtraTools(cfg, cwd) {
                 fingerprints: state.last.fingerprints,
                 counts: state.last.counts,
             };
-            const file = await saveBaseline(stateDir, baseline);
+            const file = await saveBaseline(stateDir, baseline, signal);
             return { file, acceptedCount: baseline.findings.length, baseline };
         },
         timeoutMs: 10000,

package/lib/index.d.ts

@@ -3,7 +3,7 @@
  *
  * 插件导出 apply(ctx, config)：注册 secure_scan / secure_diff / secure_fix_verify /
  * secure_report / secure_export / secure_policy_show / secure_policy_set 七个工具。扫描为纯确定性规则，
- * git diff 通过官方 subprocess 服务执行，零运行时依赖。
+ * git diff 通过官方 subprocess 服务执行，仅依赖文件锁库。
  *
  * @module dsh-code-security
  */

package/lib/index.js

@@ -3,7 +3,7 @@
  *
  * 插件导出 apply(ctx, config)：注册 secure_scan / secure_diff / secure_fix_verify /
  * secure_report / secure_export / secure_policy_show / secure_policy_set 七个工具。扫描为纯确定性规则，
- * git diff 通过官方 subprocess 服务执行，零运行时依赖。
+ * git diff 通过官方 subprocess 服务执行，仅依赖文件锁库。
  *
  * @module dsh-code-security
  */

package/lib/policy.d.ts

@@ -19,6 +19,6 @@ export declare const POLICY_FILE = ".code-security.json";
 export declare function policyPath(cwd: string): string;
 export declare function loadPolicy(cwd: string): Promise<SecurePolicy>;
 export declare function normalizePolicy(obj: Record<string, unknown>): SecurePolicy;
-export declare function savePolicy(cwd: string, policy: SecurePolicy): Promise<string>;
+export declare function savePolicy(cwd: string, policy: SecurePolicy, signal?: AbortSignal): Promise<string>;
 export declare function policyExcludesDir(policy: SecurePolicy, rel: string): boolean;
 export declare function policyIgnores(policy: SecurePolicy, ruleId: string, file: string): boolean;

package/lib/policy.js

@@ -5,6 +5,7 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 export const DEFAULT_POLICY = Object.freeze({
     version: 1,
     exclude: [],
@@ -21,7 +22,9 @@ export async function loadPolicy(cwd) {
         const obj = (parsed ?? {});
         return normalizePolicy(obj);
     }
-    catch {
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new Error('安全策略无法读取或格式无效，原文件已保留：' + (error instanceof Error ? error.message : String(error)));
         return { ...DEFAULT_POLICY, exclude: [...DEFAULT_POLICY.exclude], ignore: [] };
     }
 }
@@ -33,6 +36,8 @@ export function normalizePolicy(obj) {
         if (typeof item !== 'object' || item === null)
             continue;
         const rec = item;
+        if (!(typeof rec.ruleId === 'string' && rec.ruleId.trim() !== '') && !(typeof rec.file === 'string' && rec.file.trim() !== ''))
+            throw new Error('每条忽略规则必须指定 ruleId 或 file，空规则不能禁用全部检查。');
         ignore.push({
             ruleId: typeof rec.ruleId === 'string' && rec.ruleId !== '' ? rec.ruleId : undefined,
             file: typeof rec.file === 'string' && rec.file !== '' ? rec.file : undefined,
@@ -42,11 +47,18 @@ export function normalizePolicy(obj) {
     const failOn = obj.failOn === 'critical' || obj.failOn === 'high' || obj.failOn === 'medium' || obj.failOn === 'low' ? obj.failOn : undefined;
     return { version: 1, exclude, ignore, failOn };
 }
-export async function savePolicy(cwd, policy) {
+export async function savePolicy(cwd, policy, signal) {
+    signal?.throwIfAborted();
     const file = policyPath(cwd);
-    const tmp = file + '.tmp-' + process.pid;
-    await fs.writeFile(tmp, JSON.stringify(policy, null, 2) + '\n', 'utf8');
-    await fs.rename(tmp, file);
+    const tmp = file + '.tmp-' + randomUUID();
+    try {
+        await fs.writeFile(tmp, JSON.stringify(policy, null, 2) + '\n', { flag: 'wx', mode: 0o600, signal });
+        signal?.throwIfAborted();
+        await fs.rename(tmp, file);
+    }
+    finally {
+        await fs.unlink(tmp).catch(() => { });
+    }
     return file;
 }
 function globToRegex(glob) {

package/lib/runner.d.ts

@@ -12,6 +12,8 @@ export interface RunResult {
 export interface ProcessRunner {
     run(argv: readonly string[], options?: {
         timeoutMs?: number;
+        cwd?: string;
+        signal?: AbortSignal;
     }): Promise<RunResult>;
 }
 export interface SubprocessHandleLike {

package/lib/runner.js

@@ -9,14 +9,16 @@ export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
         async run(argv, options) {
             const timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
             const controller = new AbortController();
+            const signal = options?.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+            signal.throwIfAborted();
             const timer = setTimeout(() => controller.abort(new Error('git diff timed out')), timeoutMs);
             try {
                 const handle = spawn({
                     argv,
-                    cwd: process.cwd(),
+                    cwd: options?.cwd ?? process.cwd(),
                     stdio: { stdin: 'ignore', stdout: { maxBytes: COLLECT_BYTES }, stderr: { maxBytes: COLLECT_BYTES } },
                     graceMs,
-                    signal: controller.signal,
+                    signal,
                 });
                 const outcome = await handle.done;
                 return {

package/lib/scanner.d.ts

@@ -30,6 +30,7 @@ export interface ScanOptions {
     maxFiles: number;
     maxFileBytes: number;
     policy: SecurePolicy;
+    signal?: AbortSignal;
 }
 export interface LineEntry {
     line: number;

package/lib/scanner.js

@@ -179,14 +179,20 @@ export async function scanPath(options) {
     const findings = [];
     const relRoot = path.relative(cwd, root) || '.';
     const visit = async (absolute, rel) => {
+        options.signal?.throwIfAborted();
         let stat;
         try {
-            stat = await fs.stat(absolute);
+            stat = await fs.lstat(absolute);
         }
         catch {
             filesSkipped += 1;
             return;
         }
+        options.signal?.throwIfAborted();
+        if (stat.isSymbolicLink()) {
+            filesSkipped += 1;
+            return;
+        }
         if (stat.isDirectory()) {
             if (DEFAULT_EXCLUDE_DIRS.includes(path.basename(absolute)) || policyExcludesDir(policy, rel))
                 return;
@@ -226,6 +232,7 @@ export async function scanPath(options) {
             return;
         }
         filesScanned += 1;
+        options.signal?.throwIfAborted();
         const text = new TextDecoder('utf-8', { fatal: false }).decode(buffer);
         findings.push(...scanText(text, absolute, rel, policy));
     };

package/lib/state.d.ts

@@ -40,8 +40,8 @@ export interface StateDocument {
 export declare function findingFingerprint(finding: Finding): string;
 export declare function statePath(stateDir: string): string;
 export declare function loadState(stateDir: string): Promise<StateDocument>;
-export declare function saveState(stateDir: string, entry: ScanStateEntry): Promise<string>;
-export declare function saveBaseline(stateDir: string, baseline: BaselineEntry): Promise<string>;
+export declare function saveState(stateDir: string, entry: ScanStateEntry, signal?: AbortSignal): Promise<string>;
+export declare function saveBaseline(stateDir: string, baseline: BaselineEntry, signal?: AbortSignal): Promise<string>;
 export declare function countFindings(findings: Finding[]): {
     critical: number;
     high: number;

package/lib/state.js

@@ -6,7 +6,8 @@
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import lockfile from 'proper-lockfile';
 const STATE_FILE = 'state.json';
 const HISTORY_LIMIT = 50;
 export function findingFingerprint(finding) {
@@ -18,43 +19,96 @@ export function statePath(stateDir) {
 }
 export async function loadState(stateDir) {
     try {
+        const info = await fs.lstat(statePath(stateDir));
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 16 * 1024 * 1024)
+            throw new Error('记录不是普通文件或超过 16 MiB');
         const text = await fs.readFile(statePath(stateDir), 'utf8');
         const parsed = JSON.parse(text);
         const obj = (parsed ?? {});
+        if (!Array.isArray(obj.history) || obj.history.some(entry => !isEntry(entry)) || obj.last !== null && !isEntry(obj.last) || obj.baseline !== undefined && obj.baseline !== null && !isBaseline(obj.baseline))
+            throw new Error('记录结构无效');
         const last = isEntry(obj.last) ? obj.last : null;
         const history = Array.isArray(obj.history) ? obj.history.filter(isEntry) : [];
         const baseline = isBaseline(obj.baseline) ? obj.baseline : null;
         return { last, history, baseline };
     }
-    catch {
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new Error('安全扫描记录无法读取，原文件已保留：' + (error instanceof Error ? error.message : String(error)));
         return { last: null, history: [], baseline: null };
     }
 }
 function isEntry(value) {
-    return typeof value === 'object' && value !== null && Array.isArray(value.findings);
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const row = value;
+    return typeof row.mode === 'string' && typeof row.target === 'string' && typeof row.time === 'string'
+        && Number.isInteger(row.filesScanned) && row.filesScanned >= 0 && validFindings(row.findings)
+        && validFingerprints(row.fingerprints) && validCounts(row.counts);
 }
 function isBaseline(value) {
-    return typeof value === 'object' && value !== null && Array.isArray(value.findings) && Array.isArray(value.fingerprints);
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const row = value;
+    return typeof row.time === 'string' && typeof row.target === 'string' && typeof row.reason === 'string'
+        && validFindings(row.findings) && validFingerprints(row.fingerprints) && validCounts(row.counts);
 }
-export async function saveState(stateDir, entry) {
+function validFingerprints(value) { return Array.isArray(value) && value.every(item => typeof item === 'string'); }
+function validCounts(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const counts = value;
+    return ['critical', 'high', 'medium', 'low'].every(key => typeof counts[key] === 'number' && Number.isInteger(counts[key]) && counts[key] >= 0);
+}
+function validFindings(value) {
+    return Array.isArray(value) && value.every(item => typeof item === 'object' && item !== null
+        && typeof item.ruleId === 'string' && typeof item.file === 'string' && typeof item.snippet === 'string'
+        && Number.isInteger(item.line) && item.line >= 1 && ['critical', 'high', 'medium', 'low'].includes(item.severity));
+}
+export async function saveState(stateDir, entry, signal) {
+    signal?.throwIfAborted();
     await fs.mkdir(stateDir, { recursive: true });
-    const state = await loadState(stateDir);
-    state.last = entry;
-    state.history.unshift(entry);
-    state.history = state.history.slice(0, HISTORY_LIMIT);
-    return writeState(stateDir, state);
+    const unlock = await lockfile.lock(stateDir, { retries: { retries: 30, minTimeout: 25, maxTimeout: 100 } });
+    try {
+        signal?.throwIfAborted();
+        const state = await loadState(stateDir);
+        state.last = entry;
+        state.history.unshift(entry);
+        state.history = state.history.slice(0, HISTORY_LIMIT);
+        return await writeState(stateDir, state, signal);
+    }
+    finally {
+        await unlock();
+    }
 }
-export async function saveBaseline(stateDir, baseline) {
+export async function saveBaseline(stateDir, baseline, signal) {
+    signal?.throwIfAborted();
     await fs.mkdir(stateDir, { recursive: true });
-    const state = await loadState(stateDir);
-    state.baseline = baseline;
-    return writeState(stateDir, state);
+    const unlock = await lockfile.lock(stateDir, { retries: { retries: 30, minTimeout: 25, maxTimeout: 100 } });
+    try {
+        signal?.throwIfAborted();
+        const state = await loadState(stateDir);
+        state.baseline = baseline;
+        return await writeState(stateDir, state, signal);
+    }
+    finally {
+        await unlock();
+    }
 }
-async function writeState(stateDir, state) {
+async function writeState(stateDir, state, signal) {
+    signal?.throwIfAborted();
     const file = statePath(stateDir);
-    const tmp = file + '.tmp-' + process.pid;
-    await fs.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
-    await fs.rename(tmp, file);
+    const tmp = file + '.tmp-' + randomUUID(), bytes = JSON.stringify(state, null, 2);
+    if (Buffer.byteLength(bytes) > 16 * 1024 * 1024)
+        throw new Error('安全扫描记录超过 16 MiB，本次没有保存。');
+    try {
+        await fs.writeFile(tmp, bytes, { flag: 'wx', mode: 0o600, signal });
+        signal?.throwIfAborted();
+        await fs.rename(tmp, file);
+    }
+    finally {
+        await fs.unlink(tmp).catch(() => { });
+    }
     return file;
 }
 export function countFindings(findings) {

package/lib/tools.d.ts

@@ -18,6 +18,7 @@ export interface SecureToolDefinition {
         type: 'object';
         properties: Record<string, unknown>;
         required?: string[];
+        additionalProperties?: boolean;
     };
     output: {
         schema: Record<string, unknown>;

package/lib/tools.js

@@ -6,6 +6,7 @@
  * @module dsh-code-security/tools
  */
 import { writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { optionalString, requiredString } from './config.js';
@@ -16,6 +17,7 @@ import { ruleCategory } from './rules.js';
 import { scanPath } from './scanner.js';
 import { compareFingerprints, countFindings, findingFingerprint, loadState, saveState, splitByBaseline } from './state.js';
 const SEVERITY_ORDER = { critical: 4, high: 3, medium: 2, low: 1 };
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 function compileParameters(spec) {
     const properties = {};
     const required = [];
@@ -33,6 +35,21 @@ function compileParameters(spec) {
     }
     return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
 }
+/** Reject ambiguous scopes before reading files, running git, or replacing scan state. */
+function scanArguments(raw, allowed = ['target']) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('扫描参数必须是对象。请用 { target: "文件或目录" } 限定范围；扫描整个工作区请传 {}。');
+    }
+    const args = raw;
+    const unknown = Object.keys(args).filter(key => !allowed.includes(key));
+    if (unknown.length > 0) {
+        throw new Error('不支持的扫描参数：' + unknown.join('、') + '。请使用 target 指定一个文件或目录；仅省略 target 或使用 target: "." 才扫描整个工作区。');
+    }
+    if (Object.hasOwn(args, 'target') && (typeof args.target !== 'string' || args.target.trim() === '')) {
+        throw new Error('扫描参数 target 必须是非空的文件或目录字符串。扫描整个工作区请省略 target 或使用 "."。');
+    }
+    return args;
+}
 const findingSchema = {
     type: 'object',
     properties: {
@@ -70,7 +87,7 @@ function baselineSummary(value) {
         accepted: Array.isArray(rec.acceptedFindings) ? rec.acceptedFindings : [],
     };
 }
-function renderFindings(value) {
+function renderFindings(_args, value) {
     const rec = (value ?? {});
     const findings = Array.isArray(rec.findings) ? rec.findings : [];
     const counts = rec.counts;
@@ -85,20 +102,32 @@ function renderFindings(value) {
     return [{ type: 'text', text: lines.join('\n') }];
 }
 export function buildSecureTools(cfg, cwd, runner) {
+    return buildWorkspaceTools(cfg, cwd, runner).map(tool => ({ ...tool, async execute(args, exec) {
+            const context = exec;
+            const signal = context?.signal;
+            signal?.throwIfAborted();
+            const workspace = context?.agent?.session?.header?.cwd || cwd;
+            const resolved = { ...cfg, stateDir: cfg.stateDirRelative ? path.resolve(workspace, cfg.stateDirRelative) : cfg.stateDir };
+            const scopedRunner = { run: (argv, options) => runner.run(argv, { ...options, cwd: workspace, signal }) };
+            const selected = buildWorkspaceTools(resolved, workspace, scopedRunner, signal).find(row => row.name === tool.name);
+            return selected.execute(args, exec);
+        } }));
+}
+function buildWorkspaceTools(cfg, cwd, runner, signal) {
     const stateDir = cfg.stateDir;
     const secureScan = {
         name: 'secure_scan',
-        description: '扫描工作区（或指定文件/目录），用确定性规则检测注入、弱加密、硬编码密钥、危险配置等问题。结果写入 .code-security 状态供 secure_fix_verify 对比。',
-        parameters: compileParameters({
-            target: { type: 'string', description: '要扫描的文件或目录（可选，缺省扫描整个工作区）。' },
-        }),
+        description: '扫描工作区（或指定文件/目录），用确定性规则检测注入、弱加密、硬编码密钥、危险配置等问题。使用 target 字符串限定范围，不接受 paths/files 等参数；{} 表示整个工作区。结果写入 .code-security 状态供 secure_fix_verify 对比。',
+        parameters: { ...compileParameters({
+                target: { type: 'string', description: '要扫描的文件或目录（可选，缺省扫描整个工作区）。' },
+            }), additionalProperties: false },
         output: { schema: scanSchema, render: renderFindings },
         async execute(rawArgs) {
-            const args = (rawArgs ?? {});
+            const args = scanArguments(rawArgs);
             const target = optionalString(args, 'target');
             const policy = await loadPolicy(cwd);
             const failOn = policy.failOn ?? cfg.failOn;
-            const result = await scanPath({ cwd, target, maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, policy });
+            const result = await scanPath({ cwd, target, maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, policy, signal });
             const state = await loadState(stateDir);
             const counts = countFindings(result.findings);
             const split = splitByBaseline(result.findings, state.baseline);
@@ -111,7 +140,7 @@ export function buildSecureTools(cfg, cwd, runner) {
                 fingerprints: result.findings.map(findingFingerprint),
                 counts,
             };
-            const stateFile = await saveState(stateDir, entry);
+            const stateFile = await saveState(stateDir, entry, signal);
             return { ...result, counts, newFindings: split.fresh, newCounts: countFindings(split.fresh), acceptedFindings: split.accepted, baseline: state.baseline, passed: verdictOf(split.fresh, failOn), failOn, stateFile };
         },
         timeoutMs: 120000,
@@ -119,14 +148,14 @@ export function buildSecureTools(cfg, cwd, runner) {
     const secureDiff = {
         name: 'secure_diff',
         description: '只审查 git diff 的新增行（默认 HEAD，即未提交改动）。base 可用任意 git ref；staged=true 审查已暂存改动；target 可限定文件。结果同样写入状态。',
-        parameters: compileParameters({
-            base: { type: 'string', description: 'git 基线（默认 HEAD）。' },
-            target: { type: 'string', description: '限定文件路径（可选）。' },
-            staged: { type: 'boolean', description: '审查已暂存改动（git diff --cached，默认 false）。' },
-        }),
+        parameters: { ...compileParameters({
+                base: { type: 'string', description: 'git 基线（默认 HEAD）。' },
+                target: { type: 'string', description: '限定文件路径（可选）。' },
+                staged: { type: 'boolean', description: '审查已暂存改动（git diff --cached，默认 false）。' },
+            }), additionalProperties: false },
         output: { schema: scanSchema, render: renderFindings },
         async execute(rawArgs) {
-            const args = (rawArgs ?? {});
+            const args = scanArguments(rawArgs, ['base', 'target', 'staged']);
             const base = optionalString(args, 'base') ?? 'HEAD';
             const target = optionalString(args, 'target');
             const policy = await loadPolicy(cwd);
@@ -145,7 +174,7 @@ export function buildSecureTools(cfg, cwd, runner) {
                 fingerprints: result.findings.map(findingFingerprint),
                 counts,
             };
-            await saveState(stateDir, entry);
+            await saveState(stateDir, entry, signal);
             return { root: base, filesScanned: result.filesChanged, filesSkipped: 0, addedLines: result.addedLines, findings: result.findings, counts, newFindings: split.fresh, newCounts: countFindings(split.fresh), acceptedFindings: split.accepted, baseline: state.baseline, passed: verdictOf(split.fresh, failOn), failOn, durationMs: 0 };
         },
         timeoutMs: 60000,
@@ -153,9 +182,9 @@ export function buildSecureTools(cfg, cwd, runner) {
     const secureFixVerify = {
         name: 'secure_fix_verify',
         description: '复扫并与上次扫描基线对比，输出已关闭、仍存在、新引入的问题指纹。用于修复后确认没有按下葫芦浮起瓢。',
-        parameters: compileParameters({
-            target: { type: 'string', description: '复扫文件或目录（可选，缺省扫描整个工作区）。' },
-        }),
+        parameters: { ...compileParameters({
+                target: { type: 'string', description: '复扫文件或目录（可选，缺省扫描整个工作区）。' },
+            }), additionalProperties: false },
         output: {
             schema: {
                 type: 'object',
@@ -173,11 +202,11 @@ export function buildSecureTools(cfg, cwd, runner) {
             },
         },
         async execute(rawArgs) {
-            const args = (rawArgs ?? {});
+            const args = scanArguments(rawArgs);
             const target = optionalString(args, 'target');
             const policy = await loadPolicy(cwd);
             const state = await loadState(stateDir);
-            const result = await scanPath({ cwd, target, maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, policy });
+            const result = await scanPath({ cwd, target, maxFiles: cfg.maxFiles, maxFileBytes: cfg.maxFileBytes, policy, signal });
             if (state.last === null) {
                 return { baselineMissing: true, baselineTime: '', closedCount: 0, remainingCount: 0, freshCount: result.findings.length, closed: [], remaining: [], fresh: result.findings, passed: false };
             }
@@ -291,7 +320,7 @@ export function buildSecureTools(cfg, cwd, runner) {
                 throw new Error('policy 参数不是合法 JSON。');
             }
             const policy = normalizePolicy((parsed ?? {}));
-            const file = await savePolicy(cwd, policy);
+            const file = await savePolicy(cwd, policy, signal);
             return { file, policy };
         },
         timeoutMs: 10000,
@@ -322,6 +351,7 @@ export function buildSecureTools(cfg, cwd, runner) {
             if (state.last === null)
                 throw new Error('尚无扫描结果，请先执行 secure_scan 或 secure_diff。');
             const text = format === 'sarif' ? buildSarif(state.last.findings, cwd) : buildMarkdown(state.last.findings, state.last.target);
+            signal?.throwIfAborted();
             if (target !== undefined)
                 await writeFile(target, text, 'utf8');
             return { format, path: target ?? '', text, findingCount: state.last.findings.length };
@@ -354,7 +384,7 @@ export function buildSecureTools(cfg, cwd, runner) {
             return { ok: true, plugin: 'dsh-code-security', checks };
         },
     };
-    return [secureScan, secureDiff, secureFixVerify, secureReport, secureExport, ...buildExtraTools(cfg, cwd), policyShow, policySet, secureHealth];
+    return [secureScan, secureDiff, secureFixVerify, secureReport, secureExport, ...buildExtraTools(cfg, cwd, signal), policyShow, policySet, secureHealth];
 }
 function buildMarkdown(findings, target) {
     const lines = ['# 安全审查报告', '', '目标：' + target, '', '| 严重度 | 规则 | CWE | 文件:行 | 说明 |', '| :-- | :-- | :-- | :-- | :-- |'];
@@ -379,7 +409,7 @@ function buildSarif(findings, cwd) {
         version: '2.1.0',
         $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
         runs: [{
-                tool: { driver: { name: 'dsh-code-security', version: '0.1.0', informationUri: 'https://github.com/STARDUSTLC666/dsh-code-security', rules: [...rules.values()] } },
+                tool: { driver: { name: 'dsh-code-security', version: PACKAGE_VERSION, informationUri: 'https://github.com/STARDUSTLC666/dsh-code-security', rules: [...rules.values()] } },
                 originalUriBaseIds: { ROOTPATH: { uri: pathToFileURL(path.resolve(cwd) + path.sep).href } },
                 results,
             }],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-code-security",
-  "version": "0.3.4",
-  "description": "DSH 代码安全审查插件：40+ 确定性规则与密钥熵检测，支持 git diff/staged 审查、SARIF 导出、基线接受与 SBOM-lite。",
+  "version": "0.3.7",
+  "description": "对代码与 Git 改动进行本地静态安全检查，并追踪修复结果。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -17,7 +17,9 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "README.en.md"
+    "README.en.md",
+    "docs",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -46,6 +48,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@types/proper-lockfile": "4.1.4",
     "typescript": "^5.6.0"
   },
   "repository": {
@@ -57,5 +60,8 @@
   },
   "homepage": "https://github.com/STARDUSTLC666/dsh-code-security#readme",
   "author": "stardustlc",
-  "packageManager": "pnpm@11.7.0"
+  "packageManager": "pnpm@11.7.0",
+  "dependencies": {
+    "proper-lockfile": "4.1.2"
+  }
 }